RDBC-926 Introduce AI agent management operations, including create, update, delete. Add AI conversation and agent operation tests, enhance error handling

Author: M4xymm

.gitignore

@@ -24,3 +24,6 @@ old
 test_server_settings.json
 .nyc_output
 coverage
+RavenDB/**/*
+.env
+certs/**/*

src/Documents/DocumentStoreBase.ts

@@ -39,6 +39,7 @@ import { IAbstractIndexCreationTask } from "./Indexes/IAbstractIndexCreationTask
 import { StringUtil } from "../Utility/StringUtil.js";
 import { IHiLoIdGenerator } from "./Identity/IHiLoIdGenerator.js";
 import { BulkInsertOptions } from "./BulkInsert/BulkInsertOptions.js";
+import { AiOperations } from "./Operations/AI/AiOperations.js";
 
 export abstract class DocumentStoreBase
     extends EventEmitter
@@ -112,6 +113,16 @@ export abstract class DocumentStoreBase
 
     private _conventions: DocumentConventions;
 
+    private _aiOperations: AiOperations;
+
+    public get ai() {
+        if (!this._aiOperations) {
+            this._aiOperations = new AiOperations(this);
+        }
+
+        return this._aiOperations;
+    }
+
     public get conventions() {
         if (!this._conventions) {
             this._conventions = new DocumentConventions();

src/Documents/IDocumentStore.ts

@@ -27,6 +27,7 @@ import { IAbstractIndexCreationTask } from "./Indexes/IAbstractIndexCreationTask
 import { TimeSeriesOperations } from "./TimeSeries/TimeSeriesOperations.js";
 import { IHiLoIdGenerator } from "./Identity/IHiLoIdGenerator.js";
 import { BulkInsertOptions } from "./BulkInsert/BulkInsertOptions.js";
+import { AiOperations } from "./Operations/AI/AiOperations.js";
 
 export interface SessionEventsProxy {
     addSessionListener(eventName: "failedRequest", eventHandler: (eventArgs: FailedRequestEventArgs) => void): this;
@@ -245,6 +246,7 @@ export interface IDocumentStore extends IDisposable,
 
     timeSeries: TimeSeriesOperations;
 
+    ai: AiOperations;
     /**
      * Gets the conventions
      */

src/Documents/Operations/AI/Agents/AddOrUpdateAiAgentOperation.ts

@@ -0,0 +1,117 @@
+import { IMaintenanceOperation, OperationResultType } from "../../OperationAbstractions.js";
+import { Stream } from "node:stream";
+import type { AiAgentConfiguration } from "./config/AiAgentConfiguration.js";
+import type { AiAgentConfigurationResult } from "./AiAgentConfigurationResult.js";
+import { RavenCommand } from "../../../../Http/RavenCommand.js";
+import { DocumentConventions } from "../../../Conventions/DocumentConventions.js";
+import { IRaftCommand } from "../../../../Http/IRaftCommand.js";
+import { ServerNode } from "../../../../Http/ServerNode.js";
+import { HttpRequestParameters } from "../../../../Primitives/Http.js";
+import { RaftIdGenerator } from "../../../../Utility/RaftIdGenerator.js";
+import { throwError } from "../../../../Exceptions/index.js";
+import { ObjectUtil } from "../../../../Utility/ObjectUtil.js";
+import { JsonSerializer } from "../../../../Mapping/Json/Serializer.js";
+import { HeadersBuilder } from "../../../../Utility/HttpUtil.js";
+
+function hasNoSampleObjectOrSchema(configuration: AiAgentConfiguration) {
+    return (!configuration.outputSchema || configuration.outputSchema.trim() === "")
+        && (!configuration.sampleObject || configuration.sampleObject.trim() === "");
+}
+
+export class AddOrUpdateAiAgentOperation implements IMaintenanceOperation<AiAgentConfigurationResult> {
+    private readonly _configuration: AiAgentConfiguration;
+    private readonly _sampleObject?: unknown;
+
+    public constructor(configuration: AiAgentConfiguration, schemaType?: any) {
+        if (!configuration) {
+            throwError("InvalidArgumentException", "configuration cannot be null or undefined.");
+        }
+
+        if (!configuration.outputSchema && !configuration.sampleObject && !schemaType) {
+            throwError("InvalidArgumentException", "Please provide a non-empty value for either outputSchema or sampleObject.");
+        }
+        this._configuration = configuration;
+        if (schemaType) {
+            this._sampleObject = schemaType;
+        }
+    }
+
+    public get resultType(): OperationResultType {
+        return "CommandResult";
+    }
+
+    public getCommand(conventions: DocumentConventions): RavenCommand<AiAgentConfigurationResult> {
+        return new AddOrUpdateAiAgentCommand(this._configuration, this._sampleObject, conventions);
+    }
+}
+
+
+class AddOrUpdateAiAgentCommand extends RavenCommand<AiAgentConfigurationResult> implements IRaftCommand {
+    private readonly _configuration: AiAgentConfiguration;
+    private readonly _conventions: DocumentConventions;
+    private readonly _sampleSchema?: any;
+
+    public constructor(configuration: AiAgentConfiguration, sampleSchema: any, conventions: DocumentConventions) {
+        super();
+        if (hasNoSampleObjectOrSchema(configuration)) {
+            throw new Error("Please provide a non-empty value for either outputSchema or sampleObject.");
+        }
+        this._configuration = configuration;
+        this._sampleSchema = sampleSchema;
+        this._conventions = conventions;
+    }
+
+    get isReadRequest(): boolean {
+        return false;
+    }
+
+    getRaftUniqueRequestId(): string {
+        return RaftIdGenerator.newId();
+    }
+
+    createRequest(node: ServerNode): HttpRequestParameters {
+        const uri = node.url + "/databases/" + node.database + "/admin/ai/agent";
+        const configToSend = {...this._configuration};
+
+        if (!configToSend.sampleObject && this._sampleSchema) {
+            configToSend.sampleObject = this._sampleSchema;
+        }
+
+        const bodyToSerialize = {
+            ...configToSend,
+            parameters: configToSend.parameters ? Array.from(configToSend.parameters) : []
+        };
+
+        const bodyJson = ObjectUtil.transformObjectKeys(bodyToSerialize, {
+            defaultTransform: ObjectUtil.pascal
+        });
+
+        const body = JsonSerializer.getDefault().serialize(bodyJson);
+
+        const headers = HeadersBuilder
+            .create()
+            .typeAppJson()
+            .build();
+
+        console.log(uri);
+        return {
+            method: "PUT",
+            uri,
+            body,
+            headers
+        } as HttpRequestParameters;
+    }
+
+    async setResponseAsync(bodyStream: Stream, fromCache: boolean): Promise<string> {
+        if (!bodyStream) {
+            this._throwInvalidResponse();
+        }
+        let body = "";
+        const data = await this._defaultPipeline<any>(_ => body = _).process(bodyStream);
+        this.result = {
+            identifier: data?.Identifier ?? data?.identifier,
+            raftCommandIndex: data?.RaftCommandIndex ?? data?.raftCommandIndex
+        } as AiAgentConfigurationResult;
+        return body;
+    }
+}

src/Documents/Operations/AI/Agents/AiAgentActionRequest.ts

@@ -0,0 +1,5 @@
+export interface AiAgentActionRequest {
+    name: string;
+    toolId: string;
+    arguments: string; // JSON string provided by the model
+}

src/Documents/Operations/AI/Agents/AiAgentActionResponse.ts

@@ -0,0 +1,4 @@
+export interface AiAgentActionResponse {
+    toolId: string;
+    content: string; // JSON/string content provided back to the agent
+}

src/Documents/Operations/AI/Agents/AiAgentConfigurationResult.ts

@@ -0,0 +1,4 @@
+export interface AiAgentConfigurationResult {
+    identifier: string;
+    raftCommandIndex: number;
+}

src/Documents/Operations/AI/Agents/AiAgentParameter.ts

@@ -0,0 +1,4 @@
+export interface AiAgentParameter {
+    name: string;
+    description?: string;
+}

src/Documents/Operations/AI/Agents/AiAgentToolAction.ts

@@ -0,0 +1,6 @@
+export interface AiAgentToolAction {
+    name: string;
+    description: string;
+    parametersSampleObject?: string; // JSON string example
+    parametersSchema?: string; // JSON schema string
+}

src/Documents/Operations/AI/Agents/AiAgentToolQuery.ts

@@ -0,0 +1,7 @@
+export interface AiAgentToolQuery {
+    name: string;
+    description: string;
+    query: string;
+    parametersSampleObject?: string; // JSON example of parameters
+    parametersSchema?: string; // JSON schema for parameters
+}