@aigne/core 1.13.0 → 1.14.0

package/lib/dts/models/claude-chat-model.d.ts

@@ -1,13 +1,32 @@
 import Anthropic from "@anthropic-ai/sdk";
 import { z } from "zod";
-import type { AgentInvokeOptions, AgentResponse } from "../agents/agent.js";
-import type { Context } from "../aigne/context.js";
+import type { AgentProcessResult } from "../agents/agent.js";
+import { type PromiseOrValue } from "../utils/type-utils.js";
 import { ChatModel, type ChatModelInput, type ChatModelOptions, type ChatModelOutput } from "./chat-model.js";
+/**
+ * Configuration options for Claude Chat Model
+ */
 export interface ClaudeChatModelOptions {
+    /**
+     * API key for Anthropic's Claude API
+     *
+     * If not provided, will look for ANTHROPIC_API_KEY or CLAUDE_API_KEY in environment variables
+     */
     apiKey?: string;
+    /**
+     * Claude model to use
+     *
+     * Defaults to 'claude-3-7-sonnet-latest'
+     */
     model?: string;
+    /**
+     * Additional model options to control behavior
+     */
     modelOptions?: ChatModelOptions;
 }
+/**
+ * @hidden
+ */
 export declare const claudeChatModelOptionsSchema: z.ZodObject<{
     apiKey: z.ZodOptional<z.ZodString>;
     model: z.ZodOptional<z.ZodString>;
@@ -56,13 +75,40 @@ export declare const claudeChatModelOptionsSchema: z.ZodObject<{
     model?: string | undefined;
     apiKey?: string | undefined;
 }>;
+/**
+ * Implementation of the ChatModel interface for Anthropic's Claude API
+ *
+ * This model provides access to Claude's capabilities including:
+ * - Text generation
+ * - Tool use
+ * - JSON structured output
+ *
+ * Default model: 'claude-3-7-sonnet-latest'
+ *
+ * @example
+ * Here's how to create and use a Claude chat model:
+ * {@includeCode ../../test/models/claude-chat-model.test.ts#example-claude-chat-model}
+ *
+ * @example
+ * Here's an example with streaming response:
+ * {@includeCode ../../test/models/claude-chat-model.test.ts#example-claude-chat-model-streaming-async-generator}
+ */
 export declare class ClaudeChatModel extends ChatModel {
     options?: ClaudeChatModelOptions | undefined;
     constructor(options?: ClaudeChatModelOptions | undefined);
+    /**
+     * @hidden
+     */
     protected _client?: Anthropic;
     get client(): Anthropic;
     get modelOptions(): ChatModelOptions | undefined;
-    process(input: ChatModelInput, _context: Context, options?: AgentInvokeOptions): Promise<AgentResponse<ChatModelOutput>>;
+    /**
+     * Process the input using Claude's chat model
+     * @param input - The input to process
+     * @returns The processed output from the model
+     */
+    process(input: ChatModelInput): PromiseOrValue<AgentProcessResult<ChatModelOutput>>;
+    private _process;
     private extractResultFromClaudeStream;
     private requestStructuredOutput;
 }

package/lib/dts/models/deepseek-chat-model.d.ts

@@ -1,4 +1,20 @@
 import { OpenAIChatModel, type OpenAIChatModelOptions } from "./openai-chat-model.js";
+/**
+ * Implementation of the ChatModel interface for DeepSeek's API
+ *
+ * This model uses OpenAI-compatible API format to interact with DeepSeek's models,
+ * but with specific configuration and capabilities for DeepSeek.
+ *
+ * Default model: 'deepseek-chat'
+ *
+ * @example
+ * Here's how to create and use a DeepSeek chat model:
+ * {@includeCode ../../test/models/deepseek-chat-model.test.ts#example-deepseek-chat-model}
+ *
+ * @example
+ * Here's an example with streaming response:
+ * {@includeCode ../../test/models/deepseek-chat-model.test.ts#example-deepseek-chat-model-streaming}
+ */
 export declare class DeepSeekChatModel extends OpenAIChatModel {
     constructor(options?: OpenAIChatModelOptions);
     protected apiKeyEnvName: string;

package/lib/dts/models/gemini-chat-model.d.ts

@@ -1,4 +1,18 @@
 import { OpenAIChatModel, type OpenAIChatModelOptions } from "./openai-chat-model.js";
+/**
+ * Implementation of the ChatModel interface for Google's Gemini API
+ *
+ * This model uses OpenAI-compatible API format to interact with Google's Gemini models,
+ * providing access to models like Gemini 1.5 and Gemini 2.0.
+ *
+ * @example
+ * Here's how to create and use a Gemini chat model:
+ * {@includeCode ../../test/models/gemini-chat-model.test.ts#example-gemini-chat-model}
+ *
+ * @example
+ * Here's an example with streaming response:
+ * {@includeCode ../../test/models/gemini-chat-model.test.ts#example-gemini-chat-model-streaming}
+ */
 export declare class GeminiChatModel extends OpenAIChatModel {
     constructor(options?: OpenAIChatModelOptions);
     protected apiKeyEnvName: string;

package/lib/dts/models/ollama-chat-model.d.ts

@@ -1,4 +1,20 @@
 import { OpenAIChatModel, type OpenAIChatModelOptions } from "./openai-chat-model.js";
+/**
+ * Implementation of the ChatModel interface for Ollama
+ *
+ * This model allows you to run open-source LLMs locally using Ollama,
+ * with an OpenAI-compatible API interface.
+ *
+ * Default model: 'llama3.2'
+ *
+ * @example
+ * Here's how to create and use an Ollama chat model:
+ * {@includeCode ../../test/models/ollama-chat-model.test.ts#example-ollama-chat-model}
+ *
+ * @example
+ * Here's an example with streaming response:
+ * {@includeCode ../../test/models/ollama-chat-model.test.ts#example-ollama-chat-model-streaming}
+ */
 export declare class OllamaChatModel extends OpenAIChatModel {
     constructor(options?: OpenAIChatModelOptions);
     protected apiKeyEnvName: string;

package/lib/dts/models/open-router-chat-model.d.ts

@@ -1,4 +1,20 @@
 import { OpenAIChatModel, type OpenAIChatModelOptions } from "./openai-chat-model.js";
+/**
+ * Implementation of the ChatModel interface for OpenRouter service
+ *
+ * OpenRouter provides access to a variety of large language models through a unified API.
+ * This implementation uses the OpenAI-compatible interface to connect to OpenRouter's service.
+ *
+ * Default model: 'openai/gpt-4o'
+ *
+ * @example
+ * Here's how to create and use an OpenRouter chat model:
+ * {@includeCode ../../test/models/open-router-chat-model.test.ts#example-openrouter-chat-model}
+ *
+ * @example
+ * Here's an example with streaming response:
+ * {@includeCode ../../test/models/open-router-chat-model.test.ts#example-openrouter-chat-model-streaming}
+ */
 export declare class OpenRouterChatModel extends OpenAIChatModel {
     constructor(options?: OpenAIChatModelOptions);
     protected apiKeyEnvName: string;

package/lib/dts/models/openai-chat-model.d.ts

@@ -1,8 +1,8 @@
 import OpenAI from "openai";
 import type { ChatCompletionMessageParam, ChatCompletionTool } from "openai/resources";
 import { z } from "zod";
-import type { AgentInvokeOptions, AgentResponse } from "../agents/agent.js";
-import type { Context } from "../aigne/context.js";
+import type { AgentProcessResult } from "../agents/agent.js";
+import { type PromiseOrValue } from "../utils/type-utils.js";
 import { ChatModel, type ChatModelInput, type ChatModelInputMessage, type ChatModelInputTool, type ChatModelOptions, type ChatModelOutput, type Role } from "./chat-model.js";
 export interface OpenAIChatModelCapabilities {
     supportsNativeStructuredOutputs: boolean;
@@ -13,12 +13,36 @@ export interface OpenAIChatModelCapabilities {
     supportsToolStreaming: boolean;
     supportsTemperature: boolean;
 }
+/**
+ * Configuration options for OpenAI Chat Model
+ */
 export interface OpenAIChatModelOptions {
+    /**
+     * API key for OpenAI API
+     *
+     * If not provided, will look for OPENAI_API_KEY in environment variables
+     */
     apiKey?: string;
+    /**
+     * Base URL for OpenAI API
+     *
+     * Useful for proxies or alternate endpoints
+     */
     baseURL?: string;
+    /**
+     * OpenAI model to use
+     *
+     * Defaults to 'gpt-4o-mini'
+     */
     model?: string;
+    /**
+     * Additional model options to control behavior
+     */
     modelOptions?: ChatModelOptions;
 }
+/**
+ * @hidden
+ */
 export declare const openAIChatModelOptionsSchema: z.ZodObject<{
     apiKey: z.ZodOptional<z.ZodString>;
     baseURL: z.ZodOptional<z.ZodString>;
@@ -70,9 +94,31 @@ export declare const openAIChatModelOptionsSchema: z.ZodObject<{
     apiKey?: string | undefined;
     baseURL?: string | undefined;
 }>;
+/**
+ * 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 declare class OpenAIChatModel extends ChatModel {
     options?: OpenAIChatModelOptions | undefined;
     constructor(options?: OpenAIChatModelOptions | undefined);
+    /**
+     * @hidden
+     */
     protected _client?: OpenAI;
     protected apiKeyEnvName: string;
     protected apiKeyDefault: string | undefined;
@@ -85,18 +131,36 @@ export declare class OpenAIChatModel extends ChatModel {
     protected supportsTemperature: boolean;
     get client(): OpenAI;
     get modelOptions(): ChatModelOptions | undefined;
-    process(input: ChatModelInput, _context: Context, options?: AgentInvokeOptions): Promise<AgentResponse<ChatModelOutput>>;
+    /**
+     * Process the input and generate a response
+     * @param input The input to process
+     * @returns The generated response
+     */
+    process(input: ChatModelInput): PromiseOrValue<AgentProcessResult<ChatModelOutput>>;
+    private _process;
     private getParallelToolCalls;
     private getRunMessages;
     private getRunResponseFormat;
     private requestStructuredOutput;
     private extractResultFromStream;
 }
+/**
+ * @hidden
+ */
 export declare const ROLE_MAP: {
     [key in Role]: ChatCompletionMessageParam["role"];
 };
+/**
+ * @hidden
+ */
 export declare function contentsFromInputMessages(messages: ChatModelInputMessage[]): Promise<ChatCompletionMessageParam[]>;
+/**
+ * @hidden
+ */
 export declare function toolsFromInputTools(tools?: ChatModelInputTool[], options?: {
     addTypeToEmptyParameters?: boolean;
 }): ChatCompletionTool[] | undefined;
+/**
+ * @hidden
+ */
 export declare function jsonSchemaToOpenAIJsonSchema(schema: Record<string, unknown>): Record<string, unknown>;

package/lib/dts/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/dts/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/dts/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/dts/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/dts/server/index.d.ts

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

package/lib/dts/server/server.d.ts

@@ -1,6 +1,12 @@
 import { IncomingMessage, ServerResponse } from "node:http";
 import { z } from "zod";
 import type { AIGNE } from "../aigne/aigne.js";
+/**
+ * Schema for validating agent invocation payloads.
+ * Defines the expected structure for requests to invoke an agent.
+ *
+ * @hidden
+ */
 export declare const invokePayloadSchema: z.ZodObject<{
     agent: z.ZodString;
     input: z.ZodRecord<z.ZodString, z.ZodUnknown>;
@@ -24,31 +30,106 @@ export declare const invokePayloadSchema: z.ZodObject<{
         streaming?: boolean | null | undefined;
     } | null | undefined;
 }>;
+/**
+ * Configuration options for the AIGNEServer.
+ * These options control various aspects of server behavior including
+ * request parsing, payload limits, and response handling.
+ */
 export interface AIGNEServerOptions {
     /**
-     * Maximum body size for the request.
-     * Only used when the request is a Node.js IncomingMessage and no `body` property is present.
+     * Maximum body size for incoming HTTP requests.
+     * This controls the upper limit of request payload size when parsing raw HTTP requests.
+     * Only used when working with Node.js IncomingMessage objects that don't already have
+     * a pre-parsed body property (e.g., when not using Express middleware).
+     *
      * @default "4mb"
      */
     maximumBodySize?: string;
 }
+/**
+ * AIGNEServer provides HTTP API access to AIGNE capabilities.
+ * It handles requests to invoke agents, manages response streaming,
+ * and supports multiple HTTP server frameworks including Node.js http,
+ * Express, and Fetch API compatible environments.
+ *
+ * @example
+ * Here's a simple example of how to use AIGNEServer with express:
+ * {@includeCode ../../test/server/server.test.ts#example-aigne-server-express}
+ *
+ * @example
+ * Here's an example of how to use AIGNEServer with Hono:
+ * {@includeCode ../../test/server/server.test.ts#example-aigne-server-hono}
+ */
 export declare class AIGNEServer {
     engine: AIGNE;
     options?: AIGNEServerOptions | undefined;
+    /**
+     * Creates a new AIGNEServer instance.
+     *
+     * @param engine - The AIGNE engine instance that will process agent invocations
+     * @param options - Configuration options for the server
+     */
     constructor(engine: AIGNE, options?: AIGNEServerOptions | undefined);
     /**
-     * Invoke the agent with the given input.
-     * @param request - The request object, which can be a parsed JSON object, a Fetch API Request object, or a Node.js IncomingMessage object.
-     * @returns The web standard response, you can return it directly in supported frameworks like hono.
+     * Invokes an agent with the provided input and returns a standard web Response.
+     * This method serves as the primary API endpoint for agent invocation.
+     *
+     * The request can be provided in various formats to support different integration scenarios:
+     * - As a pre-parsed JavaScript object
+     * - As a Fetch API Request instance (for modern web frameworks)
+     * - As a Node.js IncomingMessage (for Express, Fastify, etc.)
+     *
+     * @param request - The agent invocation request in any supported format
+     * @returns A web standard Response object that can be returned directly in frameworks
+     *          like Hono, Next.js, or any Fetch API compatible environment
+     *
+     * @example
+     * Here's a simple example of how to use AIGNEServer with Hono:
+     * {@includeCode ../../test/server/server.test.ts#example-aigne-server-hono}
      */
     invoke(request: Record<string, unknown> | Request | IncomingMessage): Promise<Response>;
     /**
-     * Invoke the agent with the given input, and write the SSE response to the Node.js ServerResponse.
-     * @param request - The request object, which can be a parsed JSON object, a Fetch API Request object, or a Node.js IncomingMessage object.
-     * @param response - The Node.js ServerResponse object to write the SSE response to.
+     * Invokes an agent with the provided input and streams the response to a Node.js ServerResponse.
+     * This overload is specifically designed for Node.js HTTP server environments.
+     *
+     * The method handles both regular JSON responses and streaming Server-Sent Events (SSE)
+     * responses based on the options specified in the request.
+     *
+     * @param request - The agent invocation request in any supported format
+     * @param response - The Node.js ServerResponse object to write the response to
+     *
+     * @example
+     * Here's a simple example of how to use AIGNEServer with express:
+     * {@includeCode ../../test/server/server.test.ts#example-aigne-server-express}
      */
     invoke(request: Record<string, unknown> | Request | IncomingMessage, response: ServerResponse): Promise<void>;
+    /**
+     * Internal method that handles the core logic of processing an agent invocation request.
+     * Validates the request payload, finds the requested agent, and processes the invocation
+     * with either streaming or non-streaming response handling.
+     *
+     * @param request - The parsed or raw request to process
+     * @returns A standard Response object with the invocation result
+     * @private
+     */
     _invoke(request: Record<string, unknown> | Request | IncomingMessage): Promise<Response>;
+    /**
+     * Prepares and normalizes the input from various request types.
+     * Handles different request formats (Node.js IncomingMessage, Fetch API Request,
+     * or already parsed object) and extracts the JSON payload.
+     *
+     * @param request - The request object in any supported format
+     * @returns The normalized payload as a JavaScript object
+     * @private
+     */
     _prepareInput(request: Record<string, unknown> | Request | IncomingMessage): Promise<Record<string, unknown>>;
+    /**
+     * Writes a web standard Response object to a Node.js ServerResponse.
+     * Handles streaming responses and error conditions appropriately.
+     *
+     * @param response - The web standard Response object to write
+     * @param res - The Node.js ServerResponse to write to
+     * @private
+     */
     _writeResponse(response: Response, res: ServerResponse): Promise<void>;
 }

package/lib/dts/utils/fs.d.ts

@@ -0,0 +1,2 @@
+export declare function exists(path: string): Promise<boolean>;
+export declare function expandHome(filepath: string): string;

package/lib/dts/utils/prompts.d.ts

@@ -1 +1,2 @@
 export declare function getJsonOutputPrompt(schema: Record<string, unknown> | string): string;
+export declare function getJsonToolInputPrompt(schema: Record<string, unknown> | string): string;

package/lib/dts/utils/type-utils.d.ts

@@ -8,6 +8,7 @@ export declare function isEmpty(obj: unknown): boolean;
 export declare function isNonNullable<T>(value: T): value is NonNullable<T>;
 export declare function isNotEmpty<T>(arr: T[]): arr is [T, ...T[]];
 export declare function duplicates<T>(arr: T[], key?: (item: T) => unknown): T[];
+export declare function remove<T>(arr: T[], remove: T[] | ((item: T) => boolean)): T[];
 export declare function unique<T>(arr: T[], key?: (item: T) => unknown): T[];
 export declare function omitBy<T extends Record<string, unknown>, K extends keyof T>(obj: T, predicate: (value: T[K], key: K) => boolean): Partial<T>;
 export declare function orArrayToArray<T>(value?: T | T[]): T[];