@aigne/core 1.12.0 → 1.14.0

package/lib/cjs/models/chat-model.js

@@ -3,6 +3,29 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.ChatModel = void 0;
 const zod_1 = require("zod");
 const agent_js_1 = require("../agents/agent.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}
+ */
 class ChatModel extends agent_js_1.Agent {
     constructor() {
         super({
@@ -10,12 +33,41 @@ class ChatModel extends agent_js_1.Agent {
             outputSchema: chatModelOutputSchema,
         });
     }
+    /**
+     * Indicates whether the model supports parallel tool calls
+     *
+     * Defaults to true, subclasses can override this property based on
+     * specific model capabilities
+     */
     supportsParallelToolCalls = true;
+    /**
+     * Gets the model's supported capabilities
+     *
+     * Currently returns capabilities including: whether parallel tool calls are supported
+     *
+     * @returns An object containing model capabilities
+     */
     getModelCapabilities() {
         return {
             supportsParallelToolCalls: this.supportsParallelToolCalls,
         };
     }
+    validateToolNames(tools) {
+        for (const tool of tools ?? []) {
+            if (!/^[a-zA-Z0-9_]+$/.test(tool.function.name)) {
+                throw new Error(`Tool name "${tool.function.name}" can only contain letters, numbers, and underscores`);
+            }
+        }
+    }
+    /**
+     * 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
+     */
     preprocess(input, context) {
         super.preprocess(input, context);
         const { limits, usage } = context;
@@ -23,7 +75,17 @@ class ChatModel extends agent_js_1.Agent {
         if (limits?.maxTokens && usedTokens >= limits.maxTokens) {
             throw new Error(`Exceeded max tokens ${usedTokens}/${limits.maxTokens}`);
         }
+        this.validateToolNames(input.tools);
     }
+    /**
+     * 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
+     */
     postprocess(input, output, context) {
         super.postprocess(input, output, context);
         const { usage } = output;

package/lib/cjs/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/cjs/models/claude-chat-model.js

@@ -12,6 +12,9 @@ const stream_utils_js_1 = require("../utils/stream-utils.js");
 const type_utils_js_1 = require("../utils/type-utils.js");
 const chat_model_js_1 = require("./chat-model.js");
 const CHAT_MODEL_CLAUDE_DEFAULT_MODEL = "claude-3-7-sonnet-latest";
+/**
+ * @hidden
+ */
 exports.claudeChatModelOptionsSchema = zod_1.z.object({
     apiKey: zod_1.z.string().optional(),
     model: zod_1.z.string().optional(),
@@ -26,6 +29,24 @@ exports.claudeChatModelOptionsSchema = zod_1.z.object({
     })
         .optional(),
 });
+/**
+ * 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}
+ */
 class ClaudeChatModel extends chat_model_js_1.ChatModel {
     options;
     constructor(options) {
@@ -34,6 +55,9 @@ class ClaudeChatModel extends chat_model_js_1.ChatModel {
         super();
         this.options = options;
     }
+    /**
+     * @hidden
+     */
     _client;
     get client() {
         const apiKey = this.options?.apiKey || process.env.ANTHROPIC_API_KEY || process.env.CLAUDE_API_KEY;
@@ -45,7 +69,15 @@ class ClaudeChatModel extends chat_model_js_1.ChatModel {
     get modelOptions() {
         return this.options?.modelOptions;
     }
-    async process(input, _context, options) {
+    /**
+     * Process the input using Claude's chat model
+     * @param input - The input to process
+     * @returns The processed output from the model
+     */
+    process(input) {
+        return this._process(input);
+    }
+    async _process(input) {
         const model = this.options?.model || CHAT_MODEL_CLAUDE_DEFAULT_MODEL;
         const disableParallelToolUse = input.modelOptions?.parallelToolCalls === false ||
             this.modelOptions?.parallelToolCalls === false;
@@ -62,7 +94,7 @@ class ClaudeChatModel extends chat_model_js_1.ChatModel {
             ...body,
             stream: true,
         });
-        if (options?.streaming && input.responseFormat?.type !== "json_schema") {
+        if (input.responseFormat?.type !== "json_schema") {
             return this.extractResultFromClaudeStream(stream, true);
         }
         const result = await this.extractResultFromClaudeStream(stream);

package/lib/cjs/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/cjs/models/deepseek-chat-model.js

@@ -4,6 +4,22 @@ exports.DeepSeekChatModel = void 0;
 const openai_chat_model_js_1 = require("./openai-chat-model.js");
 const DEEPSEEK_DEFAULT_CHAT_MODEL = "deepseek-chat";
 const DEEPSEEK_BASE_URL = "https://api.deepseek.com";
+/**
+ * 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}
+ */
 class DeepSeekChatModel extends openai_chat_model_js_1.OpenAIChatModel {
     constructor(options) {
         super({

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

@@ -1,8 +1,23 @@
 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;
     protected supportsEndWithSystemMessage: boolean;
     protected supportsToolsUseWithJsonSchema: boolean;
     protected supportsParallelToolCalls: boolean;
+    protected supportsToolStreaming: boolean;
 }

package/lib/cjs/models/gemini-chat-model.js

@@ -4,6 +4,20 @@ exports.GeminiChatModel = void 0;
 const openai_chat_model_js_1 = require("./openai-chat-model.js");
 const GEMINI_BASE_URL = "https://generativelanguage.googleapis.com/v1beta/openai";
 const GEMINI_DEFAULT_CHAT_MODEL = "gemini-2.0-flash";
+/**
+ * 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}
+ */
 class GeminiChatModel extends openai_chat_model_js_1.OpenAIChatModel {
     constructor(options) {
         super({
@@ -16,5 +30,6 @@ class GeminiChatModel extends openai_chat_model_js_1.OpenAIChatModel {
     supportsEndWithSystemMessage = false;
     supportsToolsUseWithJsonSchema = false;
     supportsParallelToolCalls = false;
+    supportsToolStreaming = false;
 }
 exports.GeminiChatModel = GeminiChatModel;

package/lib/cjs/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/cjs/models/ollama-chat-model.js

@@ -4,6 +4,22 @@ exports.OllamaChatModel = void 0;
 const openai_chat_model_js_1 = require("./openai-chat-model.js");
 const OLLAMA_DEFAULT_BASE_URL = "http://localhost:11434/v1";
 const OLLAMA_DEFAULT_CHAT_MODEL = "llama3.2";
+/**
+ * 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}
+ */
 class OllamaChatModel extends openai_chat_model_js_1.OpenAIChatModel {
     constructor(options) {
         super({

package/lib/cjs/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/cjs/models/open-router-chat-model.js

@@ -4,6 +4,22 @@ exports.OpenRouterChatModel = void 0;
 const openai_chat_model_js_1 = require("./openai-chat-model.js");
 const OPEN_ROUTER_DEFAULT_CHAT_MODEL = "openai/gpt-4o";
 const OPEN_ROUTER_BASE_URL = "https://openrouter.ai/api/v1";
+/**
+ * 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}
+ */
 class OpenRouterChatModel extends openai_chat_model_js_1.OpenAIChatModel {
     constructor(options) {
         super({

package/lib/cjs/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;
@@ -10,14 +10,39 @@ export interface OpenAIChatModelCapabilities {
     supportsToolsUseWithJsonSchema: boolean;
     supportsParallelToolCalls: boolean;
     supportsToolsEmptyParameters: boolean;
+    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>;
@@ -69,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;
@@ -80,20 +127,40 @@ export declare class OpenAIChatModel extends ChatModel {
     protected supportsToolsUseWithJsonSchema: boolean;
     protected supportsParallelToolCalls: boolean;
     protected supportsToolsEmptyParameters: boolean;
+    protected supportsToolStreaming: boolean;
     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>;