@aigne/core 1.12.0 → 1.14.0

package/lib/esm/models/openai-chat-model.js

@@ -12,6 +12,9 @@ const OPENAI_CHAT_MODEL_CAPABILITIES = {
     "o4-mini": { supportsParallelToolCalls: false, supportsTemperature: false },
     "o3-mini": { supportsParallelToolCalls: false, supportsTemperature: false },
 };
+/**
+ * @hidden
+ */
 export const openAIChatModelOptionsSchema = z.object({
     apiKey: z.string().optional(),
     baseURL: z.string().optional(),
@@ -27,6 +30,25 @@ export const openAIChatModelOptionsSchema = z.object({
     })
         .optional(),
 });
+/**
+ * Implementation of the ChatModel interface for OpenAI's API
+ *
+ * This model provides access to OpenAI's capabilities including:
+ * - Text generation
+ * - Tool use with parallel tool calls
+ * - JSON structured output
+ * - Image understanding
+ *
+ * Default model: 'gpt-4o-mini'
+ *
+ * @example
+ * Here's how to create and use an OpenAI chat model:
+ * {@includeCode ../../test/models/openai-chat-model.test.ts#example-openai-chat-model}
+ *
+ * @example
+ * Here's an example with streaming response:
+ * {@includeCode ../../test/models/openai-chat-model.test.ts#example-openai-chat-model-streaming}
+ */
 export class OpenAIChatModel extends ChatModel {
     options;
     constructor(options) {
@@ -37,6 +59,9 @@ export class OpenAIChatModel extends ChatModel {
         const preset = options?.model ? OPENAI_CHAT_MODEL_CAPABILITIES[options.model] : undefined;
         Object.assign(this, preset);
     }
+    /**
+     * @hidden
+     */
     _client;
     apiKeyEnvName = "OPENAI_API_KEY";
     apiKeyDefault;
@@ -45,6 +70,7 @@ export class OpenAIChatModel extends ChatModel {
     supportsToolsUseWithJsonSchema = true;
     supportsParallelToolCalls = true;
     supportsToolsEmptyParameters = true;
+    supportsToolStreaming = true;
     supportsTemperature = true;
     get client() {
         const apiKey = this.options?.apiKey || process.env[this.apiKeyEnvName] || this.apiKeyDefault;
@@ -59,7 +85,15 @@ export class OpenAIChatModel extends ChatModel {
     get modelOptions() {
         return this.options?.modelOptions;
     }
-    async process(input, _context, options) {
+    /**
+     * Process the input and generate a response
+     * @param input The input to process
+     * @returns The generated response
+     */
+    process(input) {
+        return this._process(input);
+    }
+    async _process(input) {
         const messages = await this.getRunMessages(input);
         const body = {
             model: this.options?.model || CHAT_MODEL_OPENAI_DEFAULT_MODEL,
@@ -85,10 +119,10 @@ export class OpenAIChatModel extends ChatModel {
             parallel_tool_calls: this.getParallelToolCalls(input),
             response_format: responseFormat,
         });
-        if (options?.streaming && input.responseFormat?.type !== "json_schema") {
-            return await extractResultFromStream(stream, false, true);
+        if (input.responseFormat?.type !== "json_schema") {
+            return await this.extractResultFromStream(stream, false, true);
         }
-        const result = await extractResultFromStream(stream, jsonMode);
+        const result = await this.extractResultFromStream(stream, jsonMode);
         if (!this.supportsToolsUseWithJsonSchema &&
             !result.toolCalls?.length &&
             input.responseFormat?.type === "json_schema" &&
@@ -154,15 +188,117 @@ export class OpenAIChatModel extends ChatModel {
             ...body,
             response_format: resolvedResponseFormat,
         });
-        return extractResultFromStream(res, jsonMode);
+        return this.extractResultFromStream(res, jsonMode);
+    }
+    async extractResultFromStream(stream, jsonMode, streaming) {
+        const result = new ReadableStream({
+            start: async (controller) => {
+                try {
+                    let text = "";
+                    let refusal = "";
+                    const toolCalls = [];
+                    let model;
+                    for await (const chunk of stream) {
+                        const choice = chunk.choices?.[0];
+                        if (!model) {
+                            model = chunk.model;
+                            controller.enqueue({
+                                delta: {
+                                    json: {
+                                        model,
+                                    },
+                                },
+                            });
+                        }
+                        if (choice?.delta.tool_calls?.length) {
+                            for (const call of choice.delta.tool_calls) {
+                                if (this.supportsToolStreaming && call.index !== undefined) {
+                                    handleToolCallDelta(toolCalls, call);
+                                }
+                                else {
+                                    handleCompleteToolCall(toolCalls, call);
+                                }
+                            }
+                        }
+                        if (choice?.delta.content) {
+                            text += choice.delta.content;
+                            if (!jsonMode) {
+                                controller.enqueue({
+                                    delta: {
+                                        text: {
+                                            text: choice.delta.content,
+                                        },
+                                    },
+                                });
+                            }
+                        }
+                        if (choice?.delta.refusal) {
+                            refusal += choice.delta.refusal;
+                            if (!jsonMode) {
+                                controller.enqueue({
+                                    delta: {
+                                        text: { text: choice.delta.refusal },
+                                    },
+                                });
+                            }
+                        }
+                        if (chunk.usage) {
+                            controller.enqueue({
+                                delta: {
+                                    json: {
+                                        usage: {
+                                            inputTokens: chunk.usage.prompt_tokens,
+                                            outputTokens: chunk.usage.completion_tokens,
+                                        },
+                                    },
+                                },
+                            });
+                        }
+                    }
+                    text = text || refusal;
+                    if (jsonMode && text) {
+                        controller.enqueue({
+                            delta: {
+                                json: {
+                                    json: parseJSON(text),
+                                },
+                            },
+                        });
+                    }
+                    if (toolCalls.length) {
+                        controller.enqueue({
+                            delta: {
+                                json: {
+                                    toolCalls: toolCalls.map(({ args, ...c }) => ({
+                                        ...c,
+                                        function: { ...c.function, arguments: parseJSON(args) },
+                                    })),
+                                },
+                            },
+                        });
+                    }
+                    controller.close();
+                }
+                catch (error) {
+                    controller.error(error);
+                }
+            },
+        });
+        return streaming ? result : await agentResponseStreamToObject(result);
     }
 }
+/**
+ * @hidden
+ */
 export const ROLE_MAP = {
     system: "system",
     user: "user",
     agent: "assistant",
     tool: "tool",
 };
+/**
+ * @hidden
+ */
 export async function contentsFromInputMessages(messages) {
     return messages.map((i) => ({
         role: ROLE_MAP[i.role],
@@ -192,6 +328,9 @@ export async function contentsFromInputMessages(messages) {
         name: i.name,
     }));
 }
+/**
+ * @hidden
+ */
 export function toolsFromInputTools(tools, options) {
     return tools?.length
         ? tools.map((i) => {
@@ -210,6 +349,9 @@ export function toolsFromInputTools(tools, options) {
         })
         : undefined;
 }
+/**
+ * @hidden
+ */
 export function jsonSchemaToOpenAIJsonSchema(schema) {
     if (schema?.type === "object") {
         const { required, properties } = schema;
@@ -235,103 +377,6 @@ export function jsonSchemaToOpenAIJsonSchema(schema) {
     }
     return schema;
 }
-async function extractResultFromStream(stream, jsonMode, streaming) {
-    const result = new ReadableStream({
-        async start(controller) {
-            try {
-                let text = "";
-                let refusal = "";
-                const toolCalls = [];
-                let model;
-                for await (const chunk of stream) {
-                    const choice = chunk.choices?.[0];
-                    if (!model) {
-                        model = chunk.model;
-                        controller.enqueue({
-                            delta: {
-                                json: {
-                                    model,
-                                },
-                            },
-                        });
-                    }
-                    if (choice?.delta.tool_calls?.length) {
-                        for (const call of choice.delta.tool_calls) {
-                            // Gemini not support tool call delta
-                            if (call.index !== undefined) {
-                                handleToolCallDelta(toolCalls, call);
-                            }
-                            else {
-                                handleCompleteToolCall(toolCalls, call);
-                            }
-                        }
-                    }
-                    if (choice?.delta.content) {
-                        text += choice.delta.content;
-                        if (!jsonMode) {
-                            controller.enqueue({
-                                delta: {
-                                    text: {
-                                        text: choice.delta.content,
-                                    },
-                                },
-                            });
-                        }
-                    }
-                    if (choice?.delta.refusal) {
-                        refusal += choice.delta.refusal;
-                        if (!jsonMode) {
-                            controller.enqueue({
-                                delta: {
-                                    text: { text: choice.delta.refusal },
-                                },
-                            });
-                        }
-                    }
-                    if (chunk.usage) {
-                        controller.enqueue({
-                            delta: {
-                                json: {
-                                    usage: {
-                                        inputTokens: chunk.usage.prompt_tokens,
-                                        outputTokens: chunk.usage.completion_tokens,
-                                    },
-                                },
-                            },
-                        });
-                    }
-                }
-                text = text || refusal;
-                if (jsonMode && text) {
-                    controller.enqueue({
-                        delta: {
-                            json: {
-                                json: parseJSON(text),
-                            },
-                        },
-                    });
-                }
-                if (toolCalls.length) {
-                    controller.enqueue({
-                        delta: {
-                            json: {
-                                toolCalls: toolCalls.map(({ args, ...c }) => ({
-                                    ...c,
-                                    function: { ...c.function, arguments: parseJSON(args) },
-                                })),
-                            },
-                        },
-                    });
-                }
-                controller.close();
-            }
-            catch (error) {
-                controller.error(error);
-            }
-        },
-    });
-    return streaming ? result : await agentResponseStreamToObject(result);
-}
 function handleToolCallDelta(toolCalls, call) {
     toolCalls[call.index] ??= {
         id: call.id || nanoid(),

package/lib/esm/models/xai-chat-model.d.ts

@@ -1,4 +1,20 @@
 import { OpenAIChatModel, type OpenAIChatModelOptions } from "./openai-chat-model.js";
+/**
+ * Implementation of the ChatModel interface for X.AI's API (Grok)
+ *
+ * This model uses OpenAI-compatible API format to interact with X.AI models,
+ * providing access to models like Grok.
+ *
+ * Default model: 'grok-2-latest'
+ *
+ * @example
+ * Here's how to create and use an X.AI chat model:
+ * {@includeCode ../../test/models/xai-chat-model.test.ts#example-xai-chat-model}
+ *
+ * @example
+ * Here's an example with streaming response:
+ * {@includeCode ../../test/models/xai-chat-model.test.ts#example-xai-chat-model-streaming}
+ */
 export declare class XAIChatModel extends OpenAIChatModel {
     constructor(options?: OpenAIChatModelOptions);
     protected apiKeyEnvName: string;

package/lib/esm/models/xai-chat-model.js

@@ -1,6 +1,22 @@
 import { OpenAIChatModel } from "./openai-chat-model.js";
 const XAI_DEFAULT_CHAT_MODEL = "grok-2-latest";
 const XAI_BASE_URL = "https://api.x.ai/v1";
+/**
+ * Implementation of the ChatModel interface for X.AI's API (Grok)
+ *
+ * This model uses OpenAI-compatible API format to interact with X.AI models,
+ * providing access to models like Grok.
+ *
+ * Default model: 'grok-2-latest'
+ *
+ * @example
+ * Here's how to create and use an X.AI chat model:
+ * {@includeCode ../../test/models/xai-chat-model.test.ts#example-xai-chat-model}
+ *
+ * @example
+ * Here's an example with streaming response:
+ * {@includeCode ../../test/models/xai-chat-model.test.ts#example-xai-chat-model-streaming}
+ */
 export class XAIChatModel extends OpenAIChatModel {
     constructor(options) {
         super({

package/lib/esm/prompt/prompt-builder.d.ts

@@ -1,20 +1,19 @@
 import type { GetPromptResult } from "@modelcontextprotocol/sdk/types.js";
 import { Agent, type Message } from "../agents/agent.js";
 import type { AIAgent } from "../agents/ai-agent.js";
-import type { AgentMemory } from "../agents/memory.js";
 import type { Context } from "../aigne/context.js";
+import type { MemoryAgent } from "../memory/memory.js";
 import type { ChatModel, ChatModelInput } from "../models/chat-model.js";
 import { ChatMessagesTemplate } from "./template.js";
 export declare const MESSAGE_KEY = "$message";
-export declare const DEFAULT_MAX_HISTORY_MESSAGES = 10;
 export declare function createMessage<I extends Message>(message: string | I): I;
 export declare function getMessage(input: Message): string | undefined;
 export interface PromptBuilderOptions {
     instructions?: string | ChatMessagesTemplate;
 }
 export interface PromptBuilderBuildOptions {
-    memory?: AgentMemory;
-    context?: Context;
+    memory?: MemoryAgent | MemoryAgent[];
+    context: Context;
     agent?: AIAgent;
     input?: Message;
     model?: ChatModel;
@@ -37,6 +36,7 @@ export declare class PromptBuilder {
         toolAgents?: Agent[];
     }>;
     private buildMessages;
+    private convertMemoriesToMessages;
     private buildResponseFormat;
     private buildTools;
 }

package/lib/esm/prompt/prompt-builder.js

@@ -1,11 +1,12 @@
 import { readFile } from "node:fs/promises";
+import { stringify } from "yaml";
 import { ZodObject } from "zod";
 import { Agent } from "../agents/agent.js";
 import { outputSchemaToResponseFormatSchema } from "../utils/json-schema.js";
-import { isNil } from "../utils/type-utils.js";
-import { AgentMessageTemplate, ChatMessagesTemplate, SystemMessageTemplate, UserMessageTemplate, } from "./template.js";
+import { isNil, orArrayToArray, unique } from "../utils/type-utils.js";
+import { MEMORY_MESSAGE_TEMPLATE } from "./prompts/memory-message-template.js";
+import { AgentMessageTemplate, ChatMessagesTemplate, PromptTemplate, SystemMessageTemplate, UserMessageTemplate, } from "./template.js";
 export const MESSAGE_KEY = "$message";
-export const DEFAULT_MAX_HISTORY_MESSAGES = 10;
 export function createMessage(message) {
     return typeof message === "string"
         ? { [MESSAGE_KEY]: message }
@@ -67,26 +68,20 @@ export class PromptBuilder {
     instructions;
     async build(options) {
         return {
-            messages: this.buildMessages(options),
+            messages: await this.buildMessages(options),
             responseFormat: this.buildResponseFormat(options),
             ...this.buildTools(options),
         };
     }
-    buildMessages(options) {
+    async buildMessages(options) {
         const { input } = options;
         const messages = (typeof this.instructions === "string"
             ? ChatMessagesTemplate.from([SystemMessageTemplate.from(this.instructions)])
             : this.instructions)?.format(options.input) ?? [];
-        const memory = options.memory ?? options.agent?.memory;
-        if (memory?.enabled) {
-            const k = memory.maxMemoriesInChat ?? DEFAULT_MAX_HISTORY_MESSAGES;
-            const histories = memory.memories.slice(-k);
-            if (histories?.length)
-                messages.push(...histories.map((i) => ({
-                    role: i.role,
-                    content: convertMessageToContent(i.content),
-                    name: i.source,
-                })));
+        for (const memory of orArrayToArray(options.memory ?? options.agent?.memories)) {
+            const memories = (await memory.retrieve({ search: input && getMessage(input) }, options.context))?.memories;
+            if (memories?.length)
+                messages.push(...this.convertMemoriesToMessages(memories, options));
         }
         const content = input && getMessage(input);
         // add user input if it's not the same as the last message
@@ -95,6 +90,15 @@ export class PromptBuilder {
         }
         return messages;
     }
+    convertMemoriesToMessages(memories, options) {
+        const str = stringify(memories.map((i) => i.content));
+        return [
+            {
+                role: "system",
+                content: PromptTemplate.from(options.agent?.memoryPromptTemplate || MEMORY_MESSAGE_TEMPLATE).format({ memories: str }),
+            },
+        ];
+    }
     buildResponseFormat(options) {
         const outputSchema = options.outputSchema || options.agent?.outputSchema;
         if (!outputSchema)
@@ -112,10 +116,11 @@ export class PromptBuilder {
             : undefined;
     }
     buildTools(options) {
-        const toolAgents = (options.context?.skills ?? [])
+        const toolAgents = unique((options.context?.skills ?? [])
             .concat(options.agent?.skills ?? [])
+            .concat(options.agent?.memoryAgentsAsTools ? options.agent.memories : [])
             // TODO: support nested tools?
-            .flatMap((i) => (i.isInvokable ? i.skills.concat(i) : i.skills));
+            .flatMap((i) => (i.isInvokable ? i.skills.concat(i) : i.skills)), (i) => i.name);
         const tools = toolAgents.map((i) => ({
             type: "function",
             function: {
@@ -169,7 +174,3 @@ function isFromPath(value) {
 function isEmptyObjectType(schema) {
     return schema instanceof ZodObject && Object.keys(schema.shape).length === 0;
 }
-function convertMessageToContent(i) {
-    const str = i[MESSAGE_KEY];
-    return !isNil(str) ? (typeof str === "string" ? str : JSON.stringify(str)) : JSON.stringify(i);
-}

package/lib/esm/prompt/prompts/memory-message-template.d.ts

@@ -0,0 +1 @@
+export declare const MEMORY_MESSAGE_TEMPLATE = "Here are some useful memories to consider:\n\n<memories>\n{{memories}}\n</memories>\n";

package/lib/esm/prompt/prompts/memory-message-template.js

@@ -0,0 +1,7 @@
+export const MEMORY_MESSAGE_TEMPLATE = `\
+Here are some useful memories to consider:
+
+<memories>
+{{memories}}
+</memories>
+`;

package/lib/esm/prompt/template.js

@@ -1,5 +1,7 @@
+import { inspect } from "node:util";
 import Mustache from "mustache";
 import { z } from "zod";
+import { tryOrThrow } from "../utils/type-utils.js";
 export class PromptTemplate {
     template;
     static from(template) {
@@ -76,7 +78,9 @@ export class ToolMessageTemplate extends ChatMessageTemplate {
         return new ToolMessageTemplate(content, toolCallId, name);
     }
     constructor(content, toolCallId, name) {
-        super("tool", typeof content === "string" ? content : JSON.stringify(content), name);
+        super("tool", typeof content === "string"
+            ? content
+            : tryOrThrow(() => JSON.stringify(content), `Failed to stringify tool content. toolCallId: ${toolCallId}, content: ${inspect(content)}`), name);
         this.toolCallId = toolCallId;
     }
     format(variables) {

package/lib/esm/server/error.d.ts

@@ -1,4 +1,15 @@
+/**
+ * Custom error class for AIGNEServer HTTP-related errors.
+ * Extends the standard Error class with an HTTP status code property.
+ * This allows error responses to include appropriate HTTP status codes.
+ */
 export declare class ServerError extends Error {
     status: number;
+    /**
+     * Creates a new ServerError instance.
+     *
+     * @param status - The HTTP status code for this error (e.g., 400, 404, 500)
+     * @param message - The error message describing what went wrong
+     */
     constructor(status: number, message: string);
 }

package/lib/esm/server/error.js

@@ -1,5 +1,16 @@
+/**
+ * Custom error class for AIGNEServer HTTP-related errors.
+ * Extends the standard Error class with an HTTP status code property.
+ * This allows error responses to include appropriate HTTP status codes.
+ */
 export class ServerError extends Error {
     status;
+    /**
+     * Creates a new ServerError instance.
+     *
+     * @param status - The HTTP status code for this error (e.g., 400, 404, 500)
+     * @param message - The error message describing what went wrong
+     */
     constructor(status, message) {
         super(message);
         this.status = status;

package/lib/esm/server/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./error.js";
+export * from "./server.js";

package/lib/esm/server/index.js

@@ -0,0 +1,2 @@
+export * from "./error.js";
+export * from "./server.js";