@aigne/core 1.13.0 → 1.14.0

package/lib/dts/memory/memory.d.ts

@@ -0,0 +1,89 @@
+import { Agent, type AgentOptions, type Message } from "../agents/agent.js";
+import type { Context } from "../aigne/context.js";
+import type { MessagePayload } from "../aigne/message-queue.js";
+import type { MemoryRecorder, MemoryRecorderInput, MemoryRecorderOutput } from "./recorder.js";
+import type { MemoryRetriever, MemoryRetrieverInput, MemoryRetrieverOutput } from "./retriever.js";
+export interface Memory {
+    id: string;
+    content: unknown;
+    createdAt: string;
+}
+export declare const newMemoryId: () => string;
+export interface MemoryAgentOptions extends Partial<Pick<MemoryAgent, "recorder" | "retriever" | "autoUpdate">>, Pick<AgentOptions, "subscribeTopic" | "skills"> {
+}
+/**
+ * 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 declare class MemoryAgent extends Agent {
+    /**
+     * Creates a new MemoryAgent instance.
+     */
+    constructor(options: MemoryAgentOptions);
+    private _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(): MemoryRetriever | undefined;
+    set retriever(value: MemoryRetriever | undefined);
+    private _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(): MemoryRecorder | undefined;
+    set recorder(value: MemoryRecorder | undefined);
+    /**
+     * 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?: boolean;
+    /**
+     * 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(): boolean;
+    /**
+     * 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.
+     */
+    process(_input: Message, _context: Context): Promise<Message>;
+    /**
+     * 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
+     */
+    retrieve(input: MemoryRetrieverInput, context: Context): Promise<MemoryRetrieverOutput>;
+    /**
+     * 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
+     */
+    record(input: MemoryRecorderInput, context: Context): Promise<MemoryRecorderOutput>;
+    onMessage({ role, source, message, context }: MessagePayload): Promise<void>;
+}

package/lib/dts/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/dts/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/dts/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/dts/models/chat-model.d.ts

@@ -1,26 +1,154 @@
-import { Agent, type Message } from "../agents/agent.js";
+import { Agent, type AgentProcessResult, type Message } from "../agents/agent.js";
 import type { Context } from "../aigne/context.js";
+import type { PromiseOrValue } from "../utils/type-utils.js";
+/**
+ * ChatModel is an abstract base class for interacting with Large Language Models (LLMs).
+ *
+ * This class extends the Agent class and provides a common interface for handling model inputs,
+ * outputs, and capabilities. Specific model implementations (like OpenAI, Anthropic, etc.)
+ * should inherit from this class and implement their specific functionalities.
+ *
+ * @example
+ * Here's how to implement a custom ChatModel:
+ * {@includeCode ../../test/models/chat-model.test.ts#example-chat-model}
+ *
+ * @example
+ * Here's an example showing streaming response with readable stream:
+ * {@includeCode ../../test/models/chat-model.test.ts#example-chat-model-streaming}
+ *
+ * @example
+ * Here's an example showing streaming response with async generator:
+ * {@includeCode ../../test/models/chat-model.test.ts#example-chat-model-streaming-async-generator}
+ *
+ * @example
+ * Here's an example with tool calls:
+ * {@includeCode ../../test/models/chat-model.test.ts#example-chat-model-tools}
+ */
 export declare abstract class ChatModel extends Agent<ChatModelInput, ChatModelOutput> {
     constructor();
+    /**
+     * Indicates whether the model supports parallel tool calls
+     *
+     * Defaults to true, subclasses can override this property based on
+     * specific model capabilities
+     */
     protected supportsParallelToolCalls: boolean;
+    /**
+     * Gets the model's supported capabilities
+     *
+     * Currently returns capabilities including: whether parallel tool calls are supported
+     *
+     * @returns An object containing model capabilities
+     */
     getModelCapabilities(): {
         supportsParallelToolCalls: boolean;
     };
     private validateToolNames;
+    /**
+     * Performs preprocessing operations before handling input
+     *
+     * Primarily checks if token usage exceeds limits, throwing an exception if limits are exceeded
+     *
+     * @param input Input message
+     * @param context Execution context
+     * @throws Error if token usage exceeds maximum limit
+     */
     protected preprocess(input: ChatModelInput, context: Context): void;
+    /**
+     * Performs postprocessing operations after handling output
+     *
+     * Primarily updates token usage statistics in the context
+     *
+     * @param input Input message
+     * @param output Output message
+     * @param context Execution context
+     */
     protected postprocess(input: ChatModelInput, output: ChatModelOutput, context: Context): void;
+    /**
+     * Processes input messages and generates model responses
+     *
+     * This is the core method that must be implemented by all ChatModel subclasses.
+     * It handles the communication with the underlying language model,
+     * processes the input messages, and generates appropriate responses.
+     *
+     * Implementations should handle:
+     * - Conversion of input format to model-specific format
+     * - Sending requests to the language model
+     * - Processing model responses
+     * - Handling streaming responses if supported
+     * - Proper error handling and retries
+     * - Token counting and usage tracking
+     * - Tool call processing if applicable
+     *
+     * @param input - The standardized input containing messages and model options
+     * @param context - The execution context with settings and state
+     * @returns A promise or direct value containing the model's response
+     */
+    abstract process(input: ChatModelInput, context: Context): PromiseOrValue<AgentProcessResult<ChatModelOutput>>;
 }
+/**
+ * Input message format for ChatModel
+ *
+ * Contains an array of messages to send to the model, response format settings,
+ * tool definitions, and model-specific options
+ *
+ * @example
+ * Here's a basic ChatModel input example:
+ * {@includeCode ../../test/models/chat-model.test.ts#example-chat-model}
+ *
+ * @example
+ * Here's an example with tool calling:
+ * {@includeCode ../../test/models/chat-model.test.ts#example-chat-model-tools}
+ */
 export interface ChatModelInput extends Message {
+    /**
+     * Array of messages to send to the model
+     */
     messages: ChatModelInputMessage[];
+    /**
+     * Specifies the expected response format
+     */
     responseFormat?: ChatModelInputResponseFormat;
+    /**
+     * List of tools available for the model to use
+     */
     tools?: ChatModelInputTool[];
+    /**
+     * Specifies the tool selection strategy
+     */
     toolChoice?: ChatModelInputToolChoice;
+    /**
+     * Model-specific configuration options
+     */
     modelOptions?: ChatModelOptions;
 }
+/**
+ * Message role types
+ *
+ * - system: System instructions
+ * - user: User messages
+ * - agent: Agent/assistant messages
+ * - tool: Tool call responses
+ */
 export type Role = "system" | "user" | "agent" | "tool";
+/**
+ * Structure of input messages
+ *
+ * Defines the format of each message sent to the model, including
+ * role, content, and tool call related information
+ */
 export interface ChatModelInputMessage {
+    /**
+     * Role of the message (system, user, agent, or tool)
+     */
     role: Role;
+    /**
+     * Message content, can be text or multimodal content array
+     */
     content?: ChatModelInputMessageContent;
+    /**
+     * Tool call details when the agent wants to execute tool calls
+     */
     toolCalls?: {
         id: string;
         type: "function";
@@ -29,18 +157,44 @@ export interface ChatModelInputMessage {
             arguments: Message;
         };
     }[];
+    /**
+     * For tool response messages, specifies the corresponding tool call ID
+     */
     toolCallId?: string;
+    /**
+     * Name of the message sender (for multi-agent scenarios)
+     */
     name?: string;
 }
+/**
+ * Type of input message content
+ *
+ * Can be a simple string, or a mixed array of text and image content
+ */
 export type ChatModelInputMessageContent = string | (TextContent | ImageUrlContent)[];
+/**
+ * Text content type
+ *
+ * Used for text parts of message content
+ */
 export type TextContent = {
     type: "text";
     text: string;
 };
+/**
+ * Image URL content type
+ *
+ * Used for image parts of message content, referencing images via URL
+ */
 export type ImageUrlContent = {
     type: "image_url";
     url: string;
 };
+/**
+ * Model response format settings
+ *
+ * Can be specified as plain text format or according to a JSON Schema
+ */
 export type ChatModelInputResponseFormat = {
     type: "text";
 } | {
@@ -52,14 +206,51 @@ export type ChatModelInputResponseFormat = {
         strict?: boolean;
     };
 };
+/**
+ * Tool definition provided to the model
+ *
+ * Defines a function tool, including name, description and parameter structure
+ *
+ * @example
+ * Here's an example showing how to use tools:
+ * {@includeCode ../../test/models/chat-model.test.ts#example-chat-model-tools}
+ */
 export interface ChatModelInputTool {
+    /**
+     * Tool type, currently only "function" is supported
+     */
     type: "function";
+    /**
+     * Function tool definition
+     */
     function: {
+        /**
+         * Function name
+         */
         name: string;
+        /**
+         * Function description
+         */
         description?: string;
+        /**
+         * Function parameter structure definition
+         */
         parameters: object;
     };
 }
+/**
+ * Tool selection strategy
+ *
+ * Determines how the model selects and uses tools:
+ * - "auto": Automatically decides whether to use tools
+ * - "none": Does not use any tools
+ * - "required": Must use tools
+ * - object: Specifies a particular tool function
+ *
+ * @example
+ * Here's an example showing how to use tools:
+ * {@includeCode ../../test/models/chat-model.test.ts#example-chat-model-tools}
+ */
 export type ChatModelInputToolChoice = "auto" | "none" | "required" | {
     type: "function";
     function: {
@@ -67,30 +258,116 @@ export type ChatModelInputToolChoice = "auto" | "none" | "required" | {
         description?: string;
     };
 };
+/**
+ * Model-specific configuration options
+ *
+ * Contains various parameters for controlling model behavior, such as model name, temperature, etc.
+ */
 export interface ChatModelOptions {
+    /**
+     * Model name or version
+     */
     model?: string;
+    /**
+     * Temperature parameter, controls randomness (0-1)
+     */
     temperature?: number;
+    /**
+     * Top-p parameter, controls vocabulary diversity
+     */
     topP?: number;
+    /**
+     * Frequency penalty parameter, reduces repetition
+     */
     frequencyPenalty?: number;
+    /**
+     * Presence penalty parameter, encourages diversity
+     */
     presencePenalty?: number;
+    /**
+     * Whether to allow parallel tool calls
+     */
     parallelToolCalls?: boolean;
 }
+/**
+ * Output message format for ChatModel
+ *
+ * Contains model response content, which can be text, JSON data, tool calls, and usage statistics
+ *
+ * @example
+ * Here's a basic output example:
+ * {@includeCode ../../test/models/chat-model.test.ts#example-chat-model}
+ *
+ * @example
+ * Here's an example with tool calls:
+ * {@includeCode ../../test/models/chat-model.test.ts#example-chat-model-tools}
+ */
 export interface ChatModelOutput extends Message {
+    /**
+     * Text format response content
+     */
     text?: string;
+    /**
+     * JSON format response content
+     */
     json?: object;
+    /**
+     * List of tools the model requested to call
+     */
     toolCalls?: ChatModelOutputToolCall[];
+    /**
+     * Token usage statistics
+     */
     usage?: ChatModelOutputUsage;
+    /**
+     * Model name or version used
+     */
     model?: string;
 }
+/**
+ * Tool call information in model output
+ *
+ * Describes tool calls requested by the model, including tool ID and call parameters
+ *
+ * @example
+ * Here's an example with tool calls:
+ * {@includeCode ../../test/models/chat-model.test.ts#example-chat-model-tools}
+ */
 export interface ChatModelOutputToolCall {
+    /**
+     * Unique ID of the tool call
+     */
     id: string;
+    /**
+     * Tool type, currently only "function" is supported
+     */
     type: "function";
+    /**
+     * Function call details
+     */
     function: {
+        /**
+         * Name of the function being called
+         */
         name: string;
+        /**
+         * Arguments for the function call
+         */
         arguments: Message;
     };
 }
+/**
+ * Model usage statistics
+ *
+ * Records the number of input and output tokens for tracking model usage
+ */
 export interface ChatModelOutputUsage {
+    /**
+     * Number of input tokens
+     */
     inputTokens: number;
+    /**
+     * Number of output tokens
+     */
     outputTokens: number;
 }