@aigne/core 1.13.0 → 1.14.0

package/lib/esm/memory/memory.js

@@ -0,0 +1,127 @@
+import { v7 } from "uuid";
+import { z } from "zod";
+import { Agent } from "../agents/agent.js";
+import { checkArguments, remove } from "../utils/type-utils.js";
+export const newMemoryId = () => v7();
+/**
+ * A specialized agent responsible for managing, storing, and retrieving memories within the agent system.
+ *
+ * MemoryAgent serves as a bridge between application logic and memory storage/retrieval mechanisms.
+ * It delegates the actual memory operations to specialized recorder and retriever agents that
+ * are attached as skills. This agent doesn't directly process messages like other agents but
+ * instead provides memory management capabilities to the system.
+ */
+export class MemoryAgent extends Agent {
+    /**
+     * Creates a new MemoryAgent instance.
+     */
+    constructor(options) {
+        checkArguments("MemoryAgent", memoryAgentOptionsSchema, options);
+        super({
+            subscribeTopic: options.subscribeTopic,
+            skills: options.skills,
+        });
+        this.recorder = options.recorder;
+        this.retriever = options.retriever;
+        this.autoUpdate = options.autoUpdate;
+    }
+    _retriever;
+    /**
+     * Agent used for retrieving memories from storage.
+     *
+     * This retriever is automatically added to the agent's skills when set.
+     * Setting a new retriever will remove any previously set retriever from skills.
+     */
+    get retriever() {
+        return this._retriever;
+    }
+    set retriever(value) {
+        if (this._retriever)
+            remove(this.skills, [this._retriever]);
+        this._retriever = value;
+        if (value)
+            this.skills.push(value);
+    }
+    _recorder;
+    /**
+     * Agent used for recording and storing new memories.
+     *
+     * This recorder is automatically added to the agent's skills when set.
+     * Setting a new recorder will remove any previously set recorder from skills.
+     */
+    get recorder() {
+        return this._recorder;
+    }
+    set recorder(value) {
+        if (this._recorder)
+            remove(this.skills, [this._recorder]);
+        this._recorder = value;
+        if (value)
+            this.skills.push(value);
+    }
+    /**
+     * Controls whether to automatically update the memory when agent call completes.
+     *
+     * When true, the agent will automatically record any relevant information
+     * after completing operations, creating a history of interactions.
+     */
+    autoUpdate;
+    /**
+     * Indicates whether this agent can be directly called.
+     *
+     * MemoryAgent is designed to be used as a supporting component rather than
+     * being directly invoked for processing, so this returns false.
+     */
+    get isCallable() {
+        return false;
+    }
+    /**
+     * The standard message processing method required by the Agent interface.
+     *
+     * MemoryAgent doesn't directly process messages like other agents, so this method
+     * throws an error when called. Use the specialized retrieve() and record() methods instead.
+     */
+    async process(_input, _context) {
+        throw new Error("Method not implemented.");
+    }
+    /**
+     * Retrieves memories based on the provided input criteria.
+     *
+     * Delegates the actual retrieval operation to the configured retriever agent.
+     *
+     * @param input - The retrieval parameters (can include search terms, limits, etc.)
+     * @param context - The execution context
+     * @returns A promise resolving to the retrieved memories
+     * @throws Error - If no retriever has been initialized
+     */
+    async retrieve(input, context) {
+        if (!this.retriever)
+            throw new Error("MemoryAgent retriever not initialized");
+        return context.invoke(this.retriever, input);
+    }
+    /**
+     * Records new memories based on the provided input content.
+     *
+     * Delegates the actual recording operation to the configured recorder agent.
+     *
+     * @param input - The content to be recorded as memories
+     * @param context - The execution context
+     * @returns A promise resolving to the recorded memories
+     * @throws Error - If no recorder has been initialized
+     */
+    async record(input, context) {
+        if (!this.recorder)
+            throw new Error("MemoryAgent recorder not initialized");
+        return context.invoke(this.recorder, input);
+    }
+    async onMessage({ role, source, message, context }) {
+        this.record({ content: [{ role, source, content: message }] }, context);
+    }
+}
+const memoryAgentOptionsSchema = z.object({
+    retriever: z.custom().optional(),
+    recorder: z.custom().optional(),
+    autoUpdate: z.boolean().optional(),
+    subscribeTopic: z.union([z.string(), z.array(z.string())]).optional(),
+    skills: z.array(z.custom()).optional(),
+});

package/lib/esm/memory/recorder.d.ts

@@ -0,0 +1,86 @@
+import { type ZodType, z } from "zod";
+import { Agent, type AgentOptions, type Message } from "../agents/agent.js";
+import type { Memory } from "./memory.js";
+/**
+ * Input for memory recording operations.
+ *
+ * This interface represents the data needed to record new memories
+ * in the system. The content array can contain any type of data that
+ * should be stored as memories.
+ */
+export interface MemoryRecorderInput extends Message {
+    /**
+     * Array of content items to record as memories.
+     * Each item in this array will typically be converted into a separate memory entry.
+     */
+    content: unknown[];
+}
+/**
+ * @hidden
+ */
+export declare const memoryRecorderInputSchema: ZodType<MemoryRecorderInput>;
+/**
+ * Output from memory recording operations.
+ *
+ * This interface represents the result of recording new memories,
+ * including the newly created memory objects with their IDs and timestamps.
+ */
+export interface MemoryRecorderOutput extends Message {
+    /**
+     * Array of newly created memory objects.
+     * Each memory includes a unique ID, the stored content, and a creation timestamp.
+     */
+    memories: Memory[];
+}
+/**
+ * @hidden
+ */
+export declare const memoryRecorderOutputSchema: z.ZodObject<{
+    memories: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        content: ZodType<{}, z.ZodTypeDef, {}>;
+        createdAt: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        content: {};
+        id: string;
+        createdAt: string;
+    }, {
+        content: {};
+        id: string;
+        createdAt: string;
+    }>, "many">;
+}, "strip", z.ZodTypeAny, {
+    memories: {
+        content: {};
+        id: string;
+        createdAt: string;
+    }[];
+}, {
+    memories: {
+        content: {};
+        id: string;
+        createdAt: string;
+    }[];
+}>;
+/**
+ * Abstract base class for agents that record and store memories.
+ *
+ * The MemoryRecorder serves as a foundation for implementing specific memory storage
+ * mechanisms. Implementations of this class are responsible for:
+ *
+ * 1. Converting input content into standardized memory objects
+ * 2. Assigning unique IDs to new memories
+ * 3. Storing memories in an appropriate backend (database, file system, etc.)
+ * 4. Ensuring proper timestamping of memories
+ *
+ * Custom implementations should extend this class and provide concrete
+ * implementations of the process method to handle the actual storage logic.
+ */
+export declare abstract class MemoryRecorder extends Agent<MemoryRecorderInput, MemoryRecorderOutput> {
+    /**
+     * Creates a new MemoryRecorder instance with predefined input and output schemas.
+     *
+     * @param options - Configuration options for the memory recorder agent
+     */
+    constructor(options: Omit<AgentOptions<MemoryRecorderInput, MemoryRecorderOutput>, "inputSchema" | "outputSchema">);
+}

package/lib/esm/memory/recorder.js

@@ -0,0 +1,46 @@
+import { z } from "zod";
+import { Agent } from "../agents/agent.js";
+/**
+ * @hidden
+ */
+export const memoryRecorderInputSchema = z.object({
+    content: z.array(z.unknown()),
+});
+/**
+ * @hidden
+ */
+export const memoryRecorderOutputSchema = z.object({
+    memories: z.array(z.object({
+        id: z.string(),
+        content: z.custom(),
+        createdAt: z.string().datetime(),
+    })),
+});
+/**
+ * Abstract base class for agents that record and store memories.
+ *
+ * The MemoryRecorder serves as a foundation for implementing specific memory storage
+ * mechanisms. Implementations of this class are responsible for:
+ *
+ * 1. Converting input content into standardized memory objects
+ * 2. Assigning unique IDs to new memories
+ * 3. Storing memories in an appropriate backend (database, file system, etc.)
+ * 4. Ensuring proper timestamping of memories
+ *
+ * Custom implementations should extend this class and provide concrete
+ * implementations of the process method to handle the actual storage logic.
+ */
+export class MemoryRecorder extends Agent {
+    /**
+     * Creates a new MemoryRecorder instance with predefined input and output schemas.
+     *
+     * @param options - Configuration options for the memory recorder agent
+     */
+    constructor(options) {
+        super({
+            ...options,
+            inputSchema: memoryRecorderInputSchema,
+            outputSchema: memoryRecorderOutputSchema,
+        });
+    }
+}

package/lib/esm/memory/retriever.d.ts

@@ -0,0 +1,99 @@
+import { z } from "zod";
+import { Agent, type AgentOptions, type Message } from "../agents/agent.js";
+import type { Memory } from "./memory.js";
+/**
+ * Input for memory retrieval operations.
+ *
+ * This interface defines the parameters that can be used to query and filter
+ * memories when retrieving them from storage.
+ */
+export interface MemoryRetrieverInput extends Message {
+    /**
+     * Maximum number of memories to retrieve.
+     * Used for pagination or limiting result set size.
+     */
+    limit?: number;
+    /**
+     * Search term to filter memories by.
+     * How the search is implemented depends on the specific retriever implementation.
+     */
+    search?: string;
+}
+/**
+ * Output from memory retrieval operations.
+ *
+ * This interface represents the result of retrieving memories from storage,
+ * containing an array of memory objects that match the query criteria.
+ */
+export interface MemoryRetrieverOutput extends Message {
+    /**
+     * Array of retrieved memory objects.
+     * Each memory includes its ID, content, and creation timestamp.
+     */
+    memories: Memory[];
+}
+/**
+ * @hidden
+ */
+export declare const memoryRetrieverInputSchema: z.ZodObject<{
+    limit: z.ZodOptional<z.ZodNumber>;
+    search: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    limit?: number | undefined;
+    search?: string | undefined;
+}, {
+    limit?: number | undefined;
+    search?: string | undefined;
+}>;
+/**
+ * @hidden
+ */
+export declare const memoryRetrieverOutputSchema: z.ZodObject<{
+    memories: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        content: z.ZodType<{}, z.ZodTypeDef, {}>;
+        createdAt: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        content: {};
+        id: string;
+        createdAt: string;
+    }, {
+        content: {};
+        id: string;
+        createdAt: string;
+    }>, "many">;
+}, "strip", z.ZodTypeAny, {
+    memories: {
+        content: {};
+        id: string;
+        createdAt: string;
+    }[];
+}, {
+    memories: {
+        content: {};
+        id: string;
+        createdAt: string;
+    }[];
+}>;
+/**
+ * Abstract base class for agents that retrieve memories from storage.
+ *
+ * The MemoryRetriever serves as a foundation for implementing specific memory
+ * retrieval mechanisms. Implementations of this class are responsible for:
+ *
+ * 1. Querying a memory storage backend to find relevant memories
+ * 2. Filtering memories based on search criteria
+ * 3. Limiting the number of results returned
+ * 4. Potentially implementing sorting, ranking, or relevance-based retrieval
+ *
+ * Custom implementations should extend this class and provide concrete
+ * implementations of the process method to handle the actual retrieval logic.
+ */
+export declare abstract class MemoryRetriever extends Agent<MemoryRetrieverInput, MemoryRetrieverOutput> {
+    /**
+     * Creates a new MemoryRetriever instance with predefined input and output schemas.
+     *
+     * @param options - Configuration options for the memory retriever agent
+     */
+    constructor(options: Omit<AgentOptions<MemoryRetrieverInput, MemoryRetrieverOutput>, "inputSchema" | "outputSchema">);
+}

package/lib/esm/memory/retriever.js

@@ -0,0 +1,47 @@
+import { z } from "zod";
+import { Agent } from "../agents/agent.js";
+/**
+ * @hidden
+ */
+export const memoryRetrieverInputSchema = z.object({
+    limit: z.number().optional(),
+    search: z.string().optional(),
+});
+/**
+ * @hidden
+ */
+export const memoryRetrieverOutputSchema = z.object({
+    memories: z.array(z.object({
+        id: z.string(),
+        content: z.custom(),
+        createdAt: z.string().datetime(),
+    })),
+});
+/**
+ * Abstract base class for agents that retrieve memories from storage.
+ *
+ * The MemoryRetriever serves as a foundation for implementing specific memory
+ * retrieval mechanisms. Implementations of this class are responsible for:
+ *
+ * 1. Querying a memory storage backend to find relevant memories
+ * 2. Filtering memories based on search criteria
+ * 3. Limiting the number of results returned
+ * 4. Potentially implementing sorting, ranking, or relevance-based retrieval
+ *
+ * Custom implementations should extend this class and provide concrete
+ * implementations of the process method to handle the actual retrieval logic.
+ */
+export class MemoryRetriever extends Agent {
+    /**
+     * Creates a new MemoryRetriever instance with predefined input and output schemas.
+     *
+     * @param options - Configuration options for the memory retriever agent
+     */
+    constructor(options) {
+        super({
+            ...options,
+            inputSchema: memoryRetrieverInputSchema,
+            outputSchema: memoryRetrieverOutputSchema,
+        });
+    }
+}

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

@@ -1,8 +1,10 @@
 import { BedrockRuntimeClient } from "@aws-sdk/client-bedrock-runtime";
 import { z } from "zod";
-import type { AgentInvokeOptions, AgentResponse } from "../agents/agent.js";
-import type { Context } from "../aigne/context.js";
+import type { AgentResponse } from "../agents/agent.js";
 import { ChatModel, type ChatModelInput, type ChatModelOptions, type ChatModelOutput } from "./chat-model.js";
+/**
+ * @hidden
+ */
 export declare function extractLastJsonObject(text: string): string | null;
 export interface BedrockChatModelOptions {
     accessKeyId?: string;
@@ -11,6 +13,9 @@ export interface BedrockChatModelOptions {
     model?: string;
     modelOptions?: ChatModelOptions;
 }
+/**
+ * @hidden
+ */
 export declare const bedrockChatModelOptionsSchema: z.ZodObject<{
     region: z.ZodOptional<z.ZodString>;
     model: z.ZodOptional<z.ZodString>;
@@ -62,9 +67,13 @@ export declare const bedrockChatModelOptionsSchema: z.ZodObject<{
 export declare class BedrockChatModel extends ChatModel {
     options?: BedrockChatModelOptions | undefined;
     constructor(options?: BedrockChatModelOptions | undefined);
+    /**
+     * @hidden
+     */
     protected _client?: BedrockRuntimeClient;
     get client(): BedrockRuntimeClient;
     get modelOptions(): ChatModelOptions | undefined;
-    process(input: ChatModelInput, _context: Context, options?: AgentInvokeOptions): Promise<AgentResponse<ChatModelOutput>>;
+    process(input: ChatModelInput): Promise<AgentResponse<ChatModelOutput>>;
     private extractResultFromStream;
+    private requestStructuredOutput;
 }

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

@@ -1,15 +1,22 @@
-import { BedrockRuntimeClient, ConverseStreamCommand, } from "@aws-sdk/client-bedrock-runtime";
+import { BedrockRuntimeClient, ConverseCommand, ConverseStreamCommand, } from "@aws-sdk/client-bedrock-runtime";
 import { nanoid } from "nanoid";
 import { z } from "zod";
 import { parseJSON } from "../utils/json-schema.js";
-import { getJsonOutputPrompt } from "../utils/prompts.js";
+import { mergeUsage } from "../utils/model-utils.js";
+import { getJsonToolInputPrompt } from "../utils/prompts.js";
 import { agentResponseStreamToObject } from "../utils/stream-utils.js";
 import { checkArguments, isNonNullable } from "../utils/type-utils.js";
 import { ChatModel, } from "./chat-model.js";
+/**
+ * @hidden
+ */
 export function extractLastJsonObject(text) {
     return text.replace(/<thinking>[\s\S]*?<\/thinking>/g, "").trim();
 }
 const BEDROCK_DEFAULT_CHAT_MODEL = "us.amazon.nova-lite-v1:0";
+/**
+ * @hidden
+ */
 export const bedrockChatModelOptionsSchema = z.object({
     region: z.string().optional(),
     model: z.string().optional(),
@@ -32,6 +39,9 @@ export class BedrockChatModel extends ChatModel {
         super();
         this.options = options;
     }
+    /**
+     * @hidden
+     */
     _client;
     get client() {
         const credentials = this.options?.accessKeyId && this.options?.secretAccessKey
@@ -49,7 +59,7 @@ export class BedrockChatModel extends ChatModel {
     get modelOptions() {
         return this.options?.modelOptions;
     }
-    async process(input, _context, options) {
+    async process(input) {
         const modelId = input.modelOptions?.model ?? this.modelOptions?.model ?? BEDROCK_DEFAULT_CHAT_MODEL;
         const { messages, system } = getRunMessages(input);
         const toolConfig = convertTools(input);
@@ -66,13 +76,17 @@ export class BedrockChatModel extends ChatModel {
         const command = new ConverseStreamCommand(body);
         const response = await this.client.send(command);
         const jsonMode = input.responseFormat?.type === "json_schema";
-        if (options?.streaming && !jsonMode) {
-            return this.extractResultFromStream(response.stream, modelId, false, true);
+        if (!jsonMode) {
+            return this.extractResultFromStream(response.stream, modelId, true);
+        }
+        const result = await this.extractResultFromStream(response.stream, modelId, false);
+        if (!result.toolCalls?.length && jsonMode && result.text) {
+            const output = await this.requestStructuredOutput(body, input.responseFormat);
+            return { ...output, usage: mergeUsage(result.usage, output.usage) };
         }
-        const result = await this.extractResultFromStream(response.stream, modelId, jsonMode, false);
         return result;
     }
-    async extractResultFromStream(stream, modelId, jsonMode, streaming) {
+    async extractResultFromStream(stream, modelId, streaming) {
         if (!stream)
             throw new Error("Unable to get AI model response.");
         const result = new ReadableStream({
@@ -80,7 +94,6 @@ export class BedrockChatModel extends ChatModel {
                 try {
                     controller.enqueue({ delta: { json: { model: modelId } } });
                     const toolCalls = [];
-                    let text = "";
                     let usage;
                     for await (const chunk of stream) {
                         if (chunk.contentBlockStart?.start?.toolUse) {
@@ -103,10 +116,7 @@ export class BedrockChatModel extends ChatModel {
                             const block = chunk.contentBlockDelta;
                             const delta = block.delta;
                             if (delta?.text) {
-                                text += delta.text;
-                                if (!jsonMode) {
-                                    controller.enqueue({ delta: { text: { text: delta.text } } });
-                                }
+                                controller.enqueue({ delta: { text: { text: delta.text } } });
                             }
                             if (delta?.toolUse) {
                                 if (block.contentBlockIndex === undefined)
@@ -121,14 +131,6 @@ export class BedrockChatModel extends ChatModel {
                             usage = chunk.metadata.usage;
                         }
                     }
-                    if (jsonMode && text) {
-                        const match = extractLastJsonObject(text);
-                        if (!match)
-                            throw new Error("Failed to extract JSON object from model output");
-                        controller.enqueue({
-                            delta: { json: { json: parseJSON(match) } },
-                        });
-                    }
                     if (toolCalls.length) {
                         controller.enqueue({
                             delta: {
@@ -153,8 +155,41 @@ export class BedrockChatModel extends ChatModel {
         });
         return streaming ? result : await agentResponseStreamToObject(result);
     }
+    async requestStructuredOutput(body, responseFormat) {
+        if (responseFormat?.type !== "json_schema") {
+            throw new Error("Expected json_schema response format");
+        }
+        const system = [
+            ...(body.system ?? []),
+            {
+                text: `Use the generate_json tool to generate a json result. ${getJsonToolInputPrompt(responseFormat.jsonSchema.schema)}`,
+            },
+        ];
+        const toolConfig = {
+            tools: [
+                {
+                    toolSpec: {
+                        name: "generate_json",
+                        description: "Generate a json result by given context",
+                        inputSchema: { json: responseFormat.jsonSchema.schema },
+                    },
+                },
+            ],
+            toolChoice: { tool: { name: "generate_json" } },
+        };
+        const command = new ConverseCommand({ ...body, system, toolConfig });
+        const response = await this.client.send(command);
+        const jsonTool = response.output?.message?.content?.find((i) => i.toolUse?.name === "generate_json");
+        if (!jsonTool)
+            throw new Error("Json tool not found");
+        return {
+            json: jsonTool.toolUse?.input,
+            model: body.modelId,
+            usage: response.usage,
+        };
+    }
 }
-const getRunMessages = ({ messages: msgs, responseFormat, }) => {
+const getRunMessages = ({ messages: msgs, }) => {
     const system = [];
     const messages = [];
     for (const msg of msgs) {
@@ -216,11 +251,6 @@ const getRunMessages = ({ messages: msgs, responseFormat, }) => {
     if (messages.at(0)?.role !== "user") {
         messages.unshift({ role: "user", content: [{ text: "." }] });
     }
-    if (responseFormat?.type === "json_schema") {
-        system.push({
-            text: getJsonOutputPrompt(responseFormat.jsonSchema.schema),
-        });
-    }
     return { messages, system };
 };
 function convertContent(content) {