Modify GenAI Task: API

• To modify an existing GenAI task, register a modified task configuration object with the server using the existing TaskID, via the UpdateGenAiOperation store operation.

• Note that this TaskID is not the user-defined task identifier that we define as part of the task configuration, but an internal identifier that RavenDB uses to manage its tasks (e.g. ETL tasks, backup tasks, and others).

  • The user-defined task identifier is a string variable that is mainly used as a property name for a list of hashes that identify processed document parts in the document metadata.
  • The TaskID is a long variable that is used by RavenDB to identify and manage the task.
    See the examples below to learn how to extract the TaskID and use it to register the modified task configuration.

• In this article:

  • Modify task configuration
  • Syntax

---

Modify task configuration

To modify the configuration of an existing GenAI task:

• Retrieve the ongoing task information using GetOngoingTaskInfoOperation, passing it:
  • The existing task's user-defined task identifier (a string variable).
  • The task type (OngoingTaskType.GenAi for GenAI tasks).
• Extract the TaskID (a long variable) from the returned OngoingTaskInfo object.
• You can -
  • Either modify the existing task configuration and change only selected sections of it
    (this approach is often easier as you can change only relevant details),
  • Or create a new configuration object and populate it from scratch with new settings for your task
    (this approach may be preferable if you want to redefine the whole configuration).
• Register the new or modified configuration with the server using UpdateGenAiOperation, passing it:
  • The extracted TaskID.
  • The configuration object.

Examples:

The below examples modify the spam-filter demonstrated in the create GenAI task article, which removes spam comments from documents in the Posts collection.

• The first example, modify-selected-configuration-details, demonstrates how to retrieve the existing configuration, modify selected sections of it, and register it with the server again.
• The second example, create-configuration-from-scratch, demonstrates how to create a new configuration object, populate it with all necessary configuration details, and register it with the server again.
• Both examples leave all details as configured in the original example except for the task name, the user-defined task identifier, and the update script - which doesn't remove spammy comments but instead adds a Warning property to each comment suspected as spam and explains in it why the comment might be spam.

• modify-selected-configuration-details
• create-configuration-from-scratch

// Provide the existing user-defined task identifier to retrieve the ongoing task info
var getTaskInfo = new GetOngoingTaskInfoOperation("spam-filter", OngoingTaskType.GenAi);
var ongoingTask = store.Maintenance.Send(getTaskInfo); // returns existing task info

// Extract the internal TaskID that RavenDB uses to manage the task
long TaskId = ongoingTask.TaskId;

// Use the existing task configuration as a base for modifications
var modifiedConfig = ((GenAi)ongoingTask).Configuration;

// Modify selected details
modifiedConfig.Identifier = "spam-warning-filter";
modifiedConfig.Name = "spam-warning-filter";
modifiedConfig.UpdateScript = @"    
            // Find the comment
            const idx = this.Comments.findIndex(c => c.Id == $input.Id);  
            // Was detected as spam
            if($output.Blocked)
            {
                // Add a warning to the comment instead of removing it
                this.Comments[idx].Warning = 'This comment may be spam: ' + $output.Reason;
            }";

// Update the GenAI task using the existing TaskID and the modified configuration
store.Maintenance.Send(new UpdateGenAiOperation(TaskId, modifiedConfig));

// Provide the existing user-defined task identifier to retrieve the ongoing task info
var getTaskInfo = new GetOngoingTaskInfoOperation("spam-filter", OngoingTaskType.GenAi);
var ongoingTask = store.Maintenance.Send(getTaskInfo);

// Extract the internal TaskID that RavenDB uses to manage the task
long TaskId = ongoingTask.TaskId;

// Create and populate a new task configuration object
GenAiConfiguration newConfig = new GenAiConfiguration
{
    // New user-defined task identifier
    Identifier = "spam-warning-filter",

    // New task name
    Name = "spam-warning-filter",

    // Connection string to AI model
    ConnectionStringName = "open-ai-cs",

    // Task is enabled
    Disabled = false,

    // Collection associated with the task
    Collection = "Posts",

    // Context generation script - format for objects to be sent to the AI model
    GenAiTransformation = new GenAiTransformation
    {
        Script = @"
        for(const comment of this.Comments)
        {
            ai.genContext({Text: comment.Text, Author: comment.Author, Id: comment.Id});}"
    },

    // AI model Prompt - the instructions sent to the AI model
    Prompt = "Check if the following blog post comment is spam or not",

    // Sample object - the layout for the AI model's response
    SampleObject = @"
    {
        ""Blocked"": true, 
        ""Reason"": ""Concise reason for why this comment was marked as spam or ham""
    }",

    // New Update script - specifies what to do with AI model replies.
    UpdateScript = @"    
            // Find the comment
            const idx = this.Comments.findIndex(c => c.Id == $input.Id);  
            // Was detected as spam
            if($output.Blocked)
            {
                // Add a warning to the comment instead of removing it
                this.Comments[idx].Warning = 'This comment may be spam: ' + $output.Reason;
            }",

    // Max concurrent connections to AI model
    MaxConcurrency = 4
};

// Update the GenAI task using the existing TaskID and the new configuration
store.Maintenance.Send(new UpdateGenAiOperation(TaskId, newConfig));

Syntax:

• UpdateGenAiOperation definition:

  public class UpdateGenAiOperation(long taskId, GenAiConfiguration configuration, StartingPointChangeVector startingPoint = null) : IMaintenanceOperation<UpdateEtlOperationResult>

  Parameters	Type	Description
  taskId	long	The internal RavenDB TaskID of the task to update.
  configuration	GenAiConfiguration	The new or modified configuration for the GenAI task.
  startingPoint	StartingPointChangeVector	Optional starting point for the update operation.