@astack-tech/integrations 0.1.1-beta.6 → 0.2.0-beta.11

package/dist/model-provider/index.d.ts

@@ -1,195 +1,275 @@
-import { Component } from '@astack-tech/core';
+import { Component, Port } from '@astack-tech/core';
 
 /**
- * Deepseek 模型提供者配置
+ * Options for a provider that speaks the OpenAI chat completions API.
  */
-interface DeepseekConfig {
-    /**
-     * API 密钥
-     */
+interface OpenAICompatibleConfig {
+    /** API key of the provider. */
     apiKey: string;
+    /** Model name, for example `gpt-4o-mini`, `qwen-plus` or `llama3.1`. */
+    model: string;
+    /** API base URL. Defaults to `https://api.openai.com/v1`. */
+    baseURL?: string | undefined;
+    /** Provider name used in errors and logs. Defaults to `The model API`. */
+    name?: string | undefined;
+    /** Sampling temperature. Defaults to `0.7`. */
+    temperature?: number | undefined;
+    /** Maximum number of generated tokens. */
+    maxTokens?: number | undefined;
+    /** Nucleus sampling probability. */
+    topP?: number | undefined;
+    /** System prompt added before every request. */
+    systemPrompt?: string | undefined;
     /**
-     * 使用的模型名称
-     * 默认为 'deepseek-chat'
-     */
-    model?: string;
-    /**
-     * 自定义 API 基础 URL
-     * 默认为 Deepseek 官方 API 地址
-     */
-    baseURL?: string;
-    /**
-     * 温度参数，控制输出的随机性
+     * Tools given as `{ name, description, parameters }` objects.
+     * When this list is not empty, it takes precedence over `tools`.
      */
-    temperature?: number;
-    /**
-     * 最大生成的 token 数
-     */
-    maxTokens?: number;
-    /**
-     * 采样概率
-     */
-    topP?: number;
-    /**
-     * 系统提示消息
-     */
-    systemPrompt?: string;
-    /**
-     * 工具实例数组，直接传递工具实例
-     * 每个工具应具有 name、description 和 parameters 属性
-     */
-    rawTools?: Array<{
-        name: string;
-        description: string;
-        parameters?: Record<string, unknown>;
-    }>;
-    /**
-     * API 格式的工具定义数组，与 rawTools 二选一
-     * 使用 OpenAI 兼容的工具定义格式
-     */
-    tools?: unknown[];
-    /**
-     * dangerouslyAllowBrowser
-     * 是否允许在浏览器等非安全环境内运行
-     */
-    dangerouslyAllowBrowser?: boolean;
+    rawTools?: RawTool[] | undefined;
+    /** Tools in the OpenAI-compatible `{ type: 'function', function }` format. */
+    tools?: unknown[] | undefined;
+    /** Allows the OpenAI client to run in a browser. Defaults to `false`. */
+    dangerouslyAllowBrowser?: boolean | undefined;
+    /** Logs API errors to the console. Defaults to `false`. */
+    verbose?: boolean | undefined;
+}
+/**
+ * Tool description accepted by `rawTools` and `temporaryTools`.
+ */
+interface RawTool {
+    /** Unique tool name. */
+    name: string;
+    /** Description that tells the model when to use the tool. */
+    description: string;
+    /** JSON Schema of the arguments. Defaults to `{}`. */
+    parameters?: Record<string, unknown> | undefined;
 }
 /**
- * 消息角色类型
+ * Role of a chat message.
  */
 type MessageRole = 'system' | 'user' | 'assistant' | 'tool';
 /**
- * 工具调用
+ * Tool call in the internal format.
  */
 interface ToolCall {
-    /**
-     * 工具调用 ID
-     */
-    id?: string;
-    /**
-     * 工具名称
-     */
+    /** Identifier assigned by the API. */
+    id?: string | undefined;
+    /** Name of the tool. */
     tool_name: string;
-    /**
-     * 工具调用参数
-     */
+    /** Parsed arguments. */
     arguments: Record<string, unknown>;
 }
 /**
- * Token 使用统计
+ * Tool call returned by `chatCompletion`. It carries both the OpenAI shape
+ * (`type`, `function`) and the internal shape (`tool_name`, `arguments`).
+ */
+interface ResponseToolCall {
+    /** Identifier assigned by the API. A `tool` message answers the call with it. */
+    id: string;
+    /** Always `function`. */
+    type: 'function';
+    /** The call in the OpenAI shape: function name and raw JSON arguments. An empty argument string is sent as `{}`. */
+    function: {
+        /** Name of the tool to call. */
+        name: string;
+        /** Arguments as JSON text. */
+        arguments: string;
+    };
+    /** Name of the tool, same as `function.name`. */
+    tool_name: string;
+    /** Parsed arguments. JSON that is not an object becomes `{}`. */
+    arguments: Record<string, unknown>;
+}
+/**
+ * Partial tool call emitted while streaming. `arguments` holds the raw JSON fragment.
+ */
+interface StreamToolCall {
+    /** Identifier assigned by the API. Only the first delta of a call carries it; later deltas have `''`. */
+    id: string;
+    /** Always `function`. */
+    type: 'function';
+    /** The delta in the OpenAI shape. `arguments` holds only this delta's JSON fragment. */
+    function: {
+        /** Name of the tool to call. */
+        name: string;
+        /** Arguments as JSON text. */
+        arguments: string;
+    };
+    /** Name of the tool when this delta carries it, otherwise `''`. */
+    tool_name: string;
+    /** Raw JSON fragment of this delta. Concatenate the fragments of a call to get its arguments. */
+    arguments: string;
+}
+/**
+ * Token usage reported by the API.
  */
 interface TokenUsage {
-    /**
-     * 完成部分的 token 数量
-     */
+    /** Tokens in the generated reply. */
     completion_tokens: number;
-    /**
-     * 提示部分的 token 数量
-     */
+    /** Tokens in the request. */
     prompt_tokens: number;
-    /**
-     * 提示缓存命中的 token 数量（可选）
-     */
-    prompt_cache_hit_tokens?: number;
-    /**
-     * 提示缓存未命中的 token 数量（可选）
-     */
-    prompt_cache_miss_tokens?: number;
-    /**
-     * 总 token 数量
-     */
+    /** Prompt tokens served from the provider's context cache (reported by DeepSeek). */
+    prompt_cache_hit_tokens?: number | undefined;
+    /** Prompt tokens not served from the cache. */
+    prompt_cache_miss_tokens?: number | undefined;
+    /** Sum of prompt and completion tokens. */
     total_tokens: number;
 }
 /**
- * 对话消息类型
+ * Chat message accepted as input. It matches the agent message contract in
+ * `@astack-tech/components`, so agent histories can be passed directly.
  */
 interface Message {
-    /**
-     * 消息角色
-     */
-    role: MessageRole;
-    /**
-     * 消息内容
-     */
-    content?: string;
-    /**
-     * 工具调用
-     */
-    tool_calls?: ToolCall[];
-    /**
-     * 工具调用 ID，用于工具响应消息
-     */
-    tool_call_id?: string;
-    /**
-     * Token 使用统计（可选）
-     */
-    usage?: TokenUsage;
+    /** One of `system`, `user`, `assistant` or `tool` (see `MessageRole`). */
+    role: string;
+    /** Text content. Omitted content is sent as no content. */
+    content?: string | undefined;
+    /** Accepted for compatibility. Assistant tool calls are not forwarded to the API. */
+    tool_calls?: readonly unknown[] | undefined;
+    /** Identifier of the call that a `tool` message answers. */
+    tool_call_id?: string | undefined;
+    /** Ignored on input. Present so agent histories can be passed unchanged. */
+    usage?: TokenUsage | undefined;
 }
 /**
- * Deepseek 组件
- *
- * 使用 OpenAI 兼容接口调用 Deepseek 模型
- *
- * 输入:
- *   - prompt: 文本提示
- *   - messages: 对话消息数组
+ * Assistant message returned by `chatCompletion`.
+ */
+interface AssistantMessage {
+    /** Always `assistant`. */
+    role: 'assistant';
+    /** Reply text. Empty when the model only calls tools. */
+    content: string;
+    /** Tool calls requested by the model, if any. */
+    tool_calls?: ResponseToolCall[] | undefined;
+    /** Token usage of this request, when the API reports it. */
+    usage?: TokenUsage | undefined;
+}
+/**
+ * Chunk yielded by `streamChatCompletion`.
+ */
+interface StreamChunk {
+    /** Always `assistant`. */
+    role: 'assistant';
+    /** Text delta. Empty in chunks that carry tool calls or usage. */
+    content: string;
+    /** Tool-call deltas in this chunk. */
+    tool_calls?: StreamToolCall[] | undefined;
+    /** Token usage. Sent once, in the final chunk, when the API reports it. */
+    usage?: TokenUsage | undefined;
+}
+/**
+ * Per-call options.
+ */
+interface ChatCompletionOptions {
+    /** Tools for this call only. They replace the configured tools. */
+    temporaryTools?: unknown[] | undefined;
+}
+/**
+ * Model provider for any API that speaks the OpenAI chat completions protocol:
+ * OpenAI itself, and the compatible endpoints of DeepSeek, Qwen, Moonshot, Ollama,
+ * vLLM and others. Set `baseURL` and `model` for the provider you use.
  *
- * 输出:
- *   - completion: 生成的文本完成
- *   - message: 生成的响应消息
+ * Ports:
+ * - `prompt` (in): a text prompt. The answer is sent on `completion`.
+ * - `messages` (in): a list of chat messages. The reply is sent on `message`.
  */
-declare class Deepseek extends Component {
-    private client;
-    private model;
-    private temperature;
-    private maxTokens?;
-    private topP?;
-    private systemPrompt?;
-    private tools?;
-    constructor(config: DeepseekConfig);
+declare class OpenAICompatible extends Component {
+    private readonly client;
+    private readonly model;
+    private readonly temperature;
+    private readonly maxTokens;
+    private readonly topP;
+    private readonly systemPrompt;
+    private readonly tools;
+    private readonly verbose;
+    private readonly name;
+    constructor(config: OpenAICompatibleConfig);
     /**
-     * 生成文本完成
-     * @param prompt 提示文本
-     * @returns 生成的文本
+     * Generates a completion for a single prompt.
+     *
+     * @returns The text answer, or the JSON-encoded assistant message when it contains tool calls.
      */
     generateCompletion(prompt: string): Promise<string>;
     /**
-     * 流式处理对话消息
-     * @param messages 对话消息数组
-     * @param options 可选的调用选项，包含临时工具列表
-     * @returns 生成的流式响应消息异步生成器
+     * Sends a conversation and returns the assistant reply.
      */
-    streamChatCompletion(messages: Message[], options?: {
-        temporaryTools?: unknown[];
-    }): AsyncGenerator<Partial<Message>>;
+    chatCompletion(messages: Message[], options?: ChatCompletionOptions): Promise<AssistantMessage>;
     /**
-     * 处理对话消息
-     * @param messages 对话消息数组
-     * @param options 可选的调用选项，包含临时工具列表
-     * @returns 生成的响应消息
+     * Streams the assistant reply. Each chunk holds a text delta, tool-call deltas, or usage.
      */
-    chatCompletion(messages: Message[], options?: {
-        temporaryTools?: unknown[];
-    }): Promise<Message>;
+    streamChatCompletion(messages: Message[], options?: ChatCompletionOptions): AsyncGenerator<StreamChunk>;
     /**
-     * 在独立模式下运行组件
-     * @param input 输入参数，可以是提示文本或对话消息数组
-     * @returns 生成的文本或响应消息
+     * Runs the model outside a pipeline.
+     *
+     * @param input - A prompt string or a list of messages.
      */
-    run(input: string | Message[]): Promise<string | Message>;
+    run(input: string | Message[]): Promise<string | AssistantMessage>;
     /**
-     * 在流水线中运行组件
-     * @param $i 输入端口
-     * @param $o 输出端口
+     * Connects the `prompt` and `messages` input ports to the model.
+     * API errors produce a fallback value so the pipeline keeps flowing. Input of the wrong
+     * type fails the pipeline run with a `TypeError` before the API is called.
      */
-    _transform($i: any, $o: any): void;
+    _transform($i: Port, $o: Port): void;
+    private baseRequest;
+    private toolsParam;
+    private systemMessages;
+    /**
+     * Converts input messages to API messages. Assistant `tool_calls` are not forwarded:
+     * agents send tool results back as user messages, and the API rejects assistant tool
+     * calls that are not followed by tool messages.
+     */
+    private formatMessages;
+    /**
+     * Converts one input message to its API shape.
+     *
+     * @throws Error when the role is not one of `MessageRole`, or a `tool` message has no
+     * `tool_call_id`. The API would reject both.
+     */
+    private toApiMessage;
+    private firstMessage;
+    private logError;
+}
+
+/**
+ * Options for the DeepSeek model provider. They are the options of
+ * `OpenAICompatible`, with DeepSeek's endpoint and model as defaults.
+ */
+interface DeepseekConfig extends Omit<OpenAICompatibleConfig, 'model' | 'name'> {
+    /** Model name. Defaults to `deepseek-chat`. */
+    model?: string | undefined;
+    /** API base URL. Defaults to `https://api.deepseek.com/v1`. */
+    baseURL?: string | undefined;
+}
+/**
+ * DeepSeek model provider: `OpenAICompatible` set up for the DeepSeek API.
+ *
+ * Ports:
+ * - `prompt` (in): a text prompt. The answer is sent on `completion`.
+ * - `messages` (in): a list of chat messages. The reply is sent on `message`.
+ */
+declare class Deepseek extends OpenAICompatible {
+    constructor(config: DeepseekConfig);
 }
 
+type index_AssistantMessage = AssistantMessage;
+type index_ChatCompletionOptions = ChatCompletionOptions;
 type index_Deepseek = Deepseek;
 declare const index_Deepseek: typeof Deepseek;
 type index_DeepseekConfig = DeepseekConfig;
+type index_Message = Message;
+type index_MessageRole = MessageRole;
+type index_OpenAICompatible = OpenAICompatible;
+declare const index_OpenAICompatible: typeof OpenAICompatible;
+type index_OpenAICompatibleConfig = OpenAICompatibleConfig;
+type index_RawTool = RawTool;
+type index_ResponseToolCall = ResponseToolCall;
+type index_StreamChunk = StreamChunk;
+type index_StreamToolCall = StreamToolCall;
+type index_TokenUsage = TokenUsage;
+type index_ToolCall = ToolCall;
 declare namespace index {
-  export { index_Deepseek as Deepseek, type index_DeepseekConfig as DeepseekConfig, type Message as DeepseekMessage, type MessageRole as DeepseekMessageRole, type ToolCall as DeepseekToolCall };
+  export { index_Deepseek as Deepseek, index_OpenAICompatible as OpenAICompatible };
+  export type { index_AssistantMessage as AssistantMessage, index_ChatCompletionOptions as ChatCompletionOptions, AssistantMessage as DeepseekAssistantMessage, ChatCompletionOptions as DeepseekChatCompletionOptions, index_DeepseekConfig as DeepseekConfig, Message as DeepseekMessage, MessageRole as DeepseekMessageRole, RawTool as DeepseekRawTool, ResponseToolCall as DeepseekResponseToolCall, StreamChunk as DeepseekStreamChunk, StreamToolCall as DeepseekStreamToolCall, TokenUsage as DeepseekTokenUsage, ToolCall as DeepseekToolCall, index_Message as Message, index_MessageRole as MessageRole, index_OpenAICompatibleConfig as OpenAICompatibleConfig, index_RawTool as RawTool, index_ResponseToolCall as ResponseToolCall, index_StreamChunk as StreamChunk, index_StreamToolCall as StreamToolCall, index_TokenUsage as TokenUsage, index_ToolCall as ToolCall };
 }
 
-export { Deepseek, type DeepseekConfig, type Message as DeepseekMessage, type MessageRole as DeepseekMessageRole, type ToolCall as DeepseekToolCall, index as i };
+export { Deepseek, OpenAICompatible, index as i };
+export type { AssistantMessage, ChatCompletionOptions, AssistantMessage as DeepseekAssistantMessage, ChatCompletionOptions as DeepseekChatCompletionOptions, DeepseekConfig, Message as DeepseekMessage, MessageRole as DeepseekMessageRole, RawTool as DeepseekRawTool, ResponseToolCall as DeepseekResponseToolCall, StreamChunk as DeepseekStreamChunk, StreamToolCall as DeepseekStreamToolCall, TokenUsage as DeepseekTokenUsage, ToolCall as DeepseekToolCall, Message, MessageRole, OpenAICompatibleConfig, RawTool, ResponseToolCall, StreamChunk, StreamToolCall, TokenUsage, ToolCall };