@aigne/core 1.8.0 → 1.10.0

package/lib/esm/models/open-router-chat-model.js

@@ -0,0 +1,14 @@
+import { OpenAIChatModel } from "./openai-chat-model.js";
+const OPEN_ROUTER_DEFAULT_CHAT_MODEL = "openai/gpt-4o";
+const OPEN_ROUTER_BASE_URL = "https://openrouter.ai/api/v1";
+export class OpenRouterChatModel extends OpenAIChatModel {
+    constructor(options) {
+        super({
+            ...options,
+            model: options?.model || OPEN_ROUTER_DEFAULT_CHAT_MODEL,
+            baseURL: options?.baseURL || OPEN_ROUTER_BASE_URL,
+        });
+    }
+    apiKeyEnvName = "OPEN_ROUTER_API_KEY";
+    supportsParallelToolCalls = false;
+}

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

@@ -1,6 +1,17 @@
 import OpenAI from "openai";
+import type { ChatCompletionMessageParam, ChatCompletionTool } from "openai/resources";
 import { z } from "zod";
-import { ChatModel, type ChatModelInput, type ChatModelOptions, type ChatModelOutput } from "./chat-model.js";
+import type { AgentCallOptions, AgentResponse } from "../agents/agent.js";
+import type { Context } from "../execution-engine/context.js";
+import { ChatModel, type ChatModelInput, type ChatModelInputMessage, type ChatModelInputTool, type ChatModelOptions, type ChatModelOutput, type Role } from "./chat-model.js";
+export interface OpenAIChatModelCapabilities {
+    supportsNativeStructuredOutputs: boolean;
+    supportsEndWithSystemMessage: boolean;
+    supportsToolsUseWithJsonSchema: boolean;
+    supportsParallelToolCalls: boolean;
+    supportsToolsEmptyParameters: boolean;
+    supportsTemperature: boolean;
+}
 export interface OpenAIChatModelOptions {
     apiKey?: string;
     baseURL?: string;
@@ -62,7 +73,27 @@ export declare class OpenAIChatModel extends ChatModel {
     options?: OpenAIChatModelOptions | undefined;
     constructor(options?: OpenAIChatModelOptions | undefined);
     protected _client?: OpenAI;
+    protected apiKeyEnvName: string;
+    protected apiKeyDefault: string | undefined;
+    protected supportsNativeStructuredOutputs: boolean;
+    protected supportsEndWithSystemMessage: boolean;
+    protected supportsToolsUseWithJsonSchema: boolean;
+    protected supportsParallelToolCalls: boolean;
+    protected supportsToolsEmptyParameters: boolean;
+    protected supportsTemperature: boolean;
     get client(): OpenAI;
     get modelOptions(): ChatModelOptions | undefined;
-    process(input: ChatModelInput): Promise<ChatModelOutput>;
+    process(input: ChatModelInput, _context: Context, options?: AgentCallOptions): Promise<AgentResponse<ChatModelOutput>>;
+    private getParallelToolCalls;
+    private getRunMessages;
+    private getRunResponseFormat;
+    private requestStructuredOutput;
 }
+export declare const ROLE_MAP: {
+    [key in Role]: ChatCompletionMessageParam["role"];
+};
+export declare function contentsFromInputMessages(messages: ChatModelInputMessage[]): Promise<ChatCompletionMessageParam[]>;
+export declare function toolsFromInputTools(tools?: ChatModelInputTool[], options?: {
+    addTypeToEmptyParameters?: boolean;
+}): ChatCompletionTool[] | undefined;
+export declare function jsonSchemaToOpenAIJsonSchema(schema: Record<string, unknown>): Record<string, unknown>;

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

@@ -2,9 +2,16 @@ import { nanoid } from "nanoid";
 import OpenAI from "openai";
 import { z } from "zod";
 import { parseJSON } from "../utils/json-schema.js";
+import { mergeUsage } from "../utils/model-utils.js";
+import { getJsonOutputPrompt } 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";
 const CHAT_MODEL_OPENAI_DEFAULT_MODEL = "gpt-4o-mini";
+const OPENAI_CHAT_MODEL_CAPABILITIES = {
+    "o4-mini": { supportsParallelToolCalls: false, supportsTemperature: false },
+    "o3-mini": { supportsParallelToolCalls: false, supportsTemperature: false },
+};
 export const openAIChatModelOptionsSchema = z.object({
     apiKey: z.string().optional(),
     baseURL: z.string().optional(),
@@ -23,16 +30,26 @@ export const openAIChatModelOptionsSchema = z.object({
 export class OpenAIChatModel extends ChatModel {
     options;
     constructor(options) {
-        if (options)
-            checkArguments("OpenAIChatModel", openAIChatModelOptionsSchema, options);
         super();
         this.options = options;
+        if (options)
+            checkArguments(this.name, openAIChatModelOptionsSchema, options);
+        const preset = options?.model ? OPENAI_CHAT_MODEL_CAPABILITIES[options.model] : undefined;
+        Object.assign(this, preset);
     }
     _client;
+    apiKeyEnvName = "OPENAI_API_KEY";
+    apiKeyDefault;
+    supportsNativeStructuredOutputs = true;
+    supportsEndWithSystemMessage = true;
+    supportsToolsUseWithJsonSchema = true;
+    supportsParallelToolCalls = true;
+    supportsToolsEmptyParameters = true;
+    supportsTemperature = true;
     get client() {
-        const apiKey = this.options?.apiKey || process.env.OPENAI_API_KEY;
+        const apiKey = this.options?.apiKey || process.env[this.apiKeyEnvName] || this.apiKeyDefault;
         if (!apiKey)
-            throw new Error("Api Key is required for OpenAIChatModel");
+            throw new Error(`Api Key is required for ${this.name}`);
         this._client ??= new OpenAI({
             baseURL: this.options?.baseURL,
             apiKey,
@@ -42,92 +59,111 @@ export class OpenAIChatModel extends ChatModel {
     get modelOptions() {
         return this.options?.modelOptions;
     }
-    async process(input) {
-        const res = await this.client.chat.completions.create({
+    async process(input, _context, options) {
+        const messages = await this.getRunMessages(input);
+        const body = {
             model: this.options?.model || CHAT_MODEL_OPENAI_DEFAULT_MODEL,
-            temperature: input.modelOptions?.temperature ?? this.modelOptions?.temperature,
+            temperature: this.supportsTemperature
+                ? (input.modelOptions?.temperature ?? this.modelOptions?.temperature)
+                : undefined,
             top_p: input.modelOptions?.topP ?? this.modelOptions?.topP,
             frequency_penalty: input.modelOptions?.frequencyPenalty ?? this.modelOptions?.frequencyPenalty,
             presence_penalty: input.modelOptions?.presencePenalty ?? this.modelOptions?.presencePenalty,
-            messages: await contentsFromInputMessages(input.messages),
-            tools: toolsFromInputTools(input.tools),
-            tool_choice: input.toolChoice,
-            parallel_tool_calls: !input.tools?.length
-                ? undefined
-                : (input.modelOptions?.parallelToolCalls ?? this.modelOptions?.parallelToolCalls),
-            response_format: input.responseFormat?.type === "json_schema"
-                ? {
-                    type: "json_schema",
-                    json_schema: {
-                        ...input.responseFormat.jsonSchema,
-                        schema: jsonSchemaToOpenAIJsonSchema(input.responseFormat.jsonSchema.schema),
-                    },
-                }
-                : undefined,
+            messages,
             stream_options: {
                 include_usage: true,
             },
             stream: true,
+        };
+        const { jsonMode, responseFormat } = await this.getRunResponseFormat(input);
+        const stream = await this.client.chat.completions.create({
+            ...body,
+            tools: toolsFromInputTools(input.tools, {
+                addTypeToEmptyParameters: !this.supportsToolsEmptyParameters,
+            }),
+            tool_choice: input.toolChoice,
+            parallel_tool_calls: this.getParallelToolCalls(input),
+            response_format: responseFormat,
         });
-        let text = "";
-        const toolCalls = [];
-        let usage;
-        let model;
-        for await (const chunk of res) {
-            const choice = chunk.choices?.[0];
-            model ??= chunk.model;
-            if (choice?.delta.tool_calls?.length) {
-                for (const call of choice.delta.tool_calls) {
-                    toolCalls[call.index] ??= {
-                        id: call.id || nanoid(),
-                        type: "function",
-                        function: { name: "", arguments: {} },
-                        args: "",
-                    };
-                    const c = toolCalls[call.index];
-                    if (!c)
-                        throw new Error("Tool call not found");
-                    if (call.type)
-                        c.type = call.type;
-                    c.function.name = c.function.name + (call.function?.name || "");
-                    c.args = c.args.concat(call.function?.arguments || "");
-                }
-            }
-            if (choice?.delta.content)
-                text += choice.delta.content;
-            if (chunk.usage) {
-                usage = {
-                    inputTokens: chunk.usage.prompt_tokens,
-                    outputTokens: chunk.usage.completion_tokens,
-                };
-            }
+        if (options?.streaming && input.responseFormat?.type !== "json_schema") {
+            return await extractResultFromStream(stream, false, true);
         }
-        const result = {
-            usage,
-            model,
-        };
-        if (input.responseFormat?.type === "json_schema" && text) {
-            result.json = parseJSON(text);
+        const result = await extractResultFromStream(stream, jsonMode);
+        if (!this.supportsToolsUseWithJsonSchema &&
+            !result.toolCalls?.length &&
+            input.responseFormat?.type === "json_schema" &&
+            result.text) {
+            const output = await this.requestStructuredOutput(body, input.responseFormat);
+            return { ...output, usage: mergeUsage(result.usage, output.usage) };
         }
-        else {
-            result.text = text;
+        return result;
+    }
+    getParallelToolCalls(input) {
+        if (!this.supportsParallelToolCalls)
+            return undefined;
+        if (!input.tools?.length)
+            return undefined;
+        return input.modelOptions?.parallelToolCalls ?? this.modelOptions?.parallelToolCalls;
+    }
+    async getRunMessages(input) {
+        const messages = await contentsFromInputMessages(input.messages);
+        if (!this.supportsEndWithSystemMessage && messages.at(-1)?.role !== "user") {
+            messages.push({ role: "user", content: "" });
         }
-        if (toolCalls.length) {
-            result.toolCalls = toolCalls.map(({ args, ...c }) => ({
-                ...c,
-                function: { ...c.function, arguments: parseJSON(args) },
-            }));
+        if (!this.supportsToolsUseWithJsonSchema && input.tools?.length)
+            return messages;
+        if (this.supportsNativeStructuredOutputs)
+            return messages;
+        if (input.responseFormat?.type === "json_schema") {
+            messages.unshift({
+                role: "system",
+                content: getJsonOutputPrompt(input.responseFormat.jsonSchema.schema),
+            });
         }
-        return result;
+        return messages;
+    }
+    async getRunResponseFormat(input) {
+        if (!this.supportsToolsUseWithJsonSchema && input.tools?.length)
+            return { jsonMode: false, responseFormat: undefined };
+        if (!this.supportsNativeStructuredOutputs) {
+            const jsonMode = input.responseFormat?.type === "json_schema";
+            return { jsonMode, responseFormat: jsonMode ? { type: "json_object" } : undefined };
+        }
+        if (input.responseFormat?.type === "json_schema") {
+            return {
+                jsonMode: true,
+                responseFormat: {
+                    type: "json_schema",
+                    json_schema: {
+                        ...input.responseFormat.jsonSchema,
+                        schema: jsonSchemaToOpenAIJsonSchema(input.responseFormat.jsonSchema.schema),
+                    },
+                },
+            };
+        }
+        return { jsonMode: false, responseFormat: undefined };
+    }
+    async requestStructuredOutput(body, responseFormat) {
+        if (responseFormat?.type !== "json_schema") {
+            throw new Error("Expected json_schema response format");
+        }
+        const { jsonMode, responseFormat: resolvedResponseFormat } = await this.getRunResponseFormat({
+            responseFormat,
+        });
+        const res = await this.client.chat.completions.create({
+            ...body,
+            response_format: resolvedResponseFormat,
+        });
+        return extractResultFromStream(res, jsonMode);
     }
 }
-const ROLE_MAP = {
+export const ROLE_MAP = {
     system: "system",
     user: "user",
     agent: "assistant",
     tool: "tool",
 };
-async function contentsFromInputMessages(messages) {
+export async function contentsFromInputMessages(messages) {
     return messages.map((i) => ({
         role: ROLE_MAP[i.role],
         content: typeof i.content === "string"
@@ -156,19 +192,25 @@ async function contentsFromInputMessages(messages) {
         name: i.name,
     }));
 }
-function toolsFromInputTools(tools) {
+export function toolsFromInputTools(tools, options) {
     return tools?.length
-        ? tools.map((i) => ({
-            type: "function",
-            function: {
-                name: i.function.name,
-                description: i.function.description,
-                parameters: i.function.parameters,
-            },
-        }))
+        ? tools.map((i) => {
+            const parameters = i.function.parameters;
+            if (options?.addTypeToEmptyParameters && Object.keys(parameters).length === 0) {
+                parameters.type = "object";
+            }
+            return {
+                type: "function",
+                function: {
+                    name: i.function.name,
+                    description: i.function.description,
+                    parameters,
+                },
+            };
+        })
         : undefined;
 }
-function jsonSchemaToOpenAIJsonSchema(schema) {
+export function jsonSchemaToOpenAIJsonSchema(schema) {
     if (schema?.type === "object") {
         const { required, properties } = schema;
         return {
@@ -193,3 +235,128 @@ function jsonSchemaToOpenAIJsonSchema(schema) {
     }
     return schema;
 }
+async function extractResultFromStream(stream, jsonMode, streaming) {
+    const result = new ReadableStream({
+        async start(controller) {
+            try {
+                let text = "";
+                let refusal = "";
+                const toolCalls = [];
+                let model;
+                for await (const chunk of stream) {
+                    const choice = chunk.choices?.[0];
+                    if (!model) {
+                        model = chunk.model;
+                        controller.enqueue({
+                            delta: {
+                                json: {
+                                    model,
+                                },
+                            },
+                        });
+                    }
+                    if (choice?.delta.tool_calls?.length) {
+                        for (const call of choice.delta.tool_calls) {
+                            // Gemini not support tool call delta
+                            if (call.index !== undefined) {
+                                handleToolCallDelta(toolCalls, call);
+                            }
+                            else {
+                                handleCompleteToolCall(toolCalls, call);
+                            }
+                        }
+                    }
+                    if (choice?.delta.content) {
+                        text += choice.delta.content;
+                        if (!jsonMode) {
+                            controller.enqueue({
+                                delta: {
+                                    text: {
+                                        text: choice.delta.content,
+                                    },
+                                },
+                            });
+                        }
+                    }
+                    if (choice?.delta.refusal) {
+                        refusal += choice.delta.refusal;
+                        if (!jsonMode) {
+                            controller.enqueue({
+                                delta: {
+                                    text: { text: choice.delta.refusal },
+                                },
+                            });
+                        }
+                    }
+                    if (chunk.usage) {
+                        controller.enqueue({
+                            delta: {
+                                json: {
+                                    usage: {
+                                        inputTokens: chunk.usage.prompt_tokens,
+                                        outputTokens: chunk.usage.completion_tokens,
+                                    },
+                                },
+                            },
+                        });
+                    }
+                }
+                text = text || refusal;
+                if (jsonMode && text) {
+                    controller.enqueue({
+                        delta: {
+                            json: {
+                                json: parseJSON(text),
+                            },
+                        },
+                    });
+                }
+                if (toolCalls.length) {
+                    controller.enqueue({
+                        delta: {
+                            json: {
+                                toolCalls: toolCalls.map(({ args, ...c }) => ({
+                                    ...c,
+                                    function: { ...c.function, arguments: parseJSON(args) },
+                                })),
+                            },
+                        },
+                    });
+                }
+            }
+            catch (error) {
+                controller.error(error);
+            }
+            finally {
+                controller.close();
+            }
+        },
+    });
+    return streaming ? result : await agentResponseStreamToObject(result);
+}
+function handleToolCallDelta(toolCalls, call) {
+    toolCalls[call.index] ??= {
+        id: call.id || nanoid(),
+        type: "function",
+        function: { name: "", arguments: {} },
+        args: "",
+    };
+    const c = toolCalls[call.index];
+    if (!c)
+        throw new Error("Tool call not found");
+    if (call.type)
+        c.type = call.type;
+    c.function.name = c.function.name + (call.function?.name || "");
+    c.args = c.args.concat(call.function?.arguments || "");
+}
+function handleCompleteToolCall(toolCalls, call) {
+    toolCalls.push({
+        id: call.id || nanoid(),
+        type: "function",
+        function: {
+            name: call.function?.name || "",
+            arguments: parseJSON(call.function?.arguments || "{}"),
+        },
+        args: call.function?.arguments || "",
+    });
+}

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

@@ -1,13 +1,5 @@
-import OpenAI from "openai";
-import type { ChatModelOptions } from "./chat-model.js";
-import { OpenAIChatModel } from "./openai-chat-model.js";
-export interface XAIChatModelOptions {
-    apiKey?: string;
-    model?: string;
-    modelOptions?: ChatModelOptions;
-    baseURL?: string;
-}
+import { OpenAIChatModel, type OpenAIChatModelOptions } from "./openai-chat-model.js";
 export declare class XAIChatModel extends OpenAIChatModel {
-    constructor(options?: XAIChatModelOptions);
-    get client(): OpenAI;
+    constructor(options?: OpenAIChatModelOptions);
+    protected apiKeyEnvName: string;
 }

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

@@ -1,4 +1,3 @@
-import OpenAI from "openai";
 import { OpenAIChatModel } from "./openai-chat-model.js";
 const XAI_DEFAULT_CHAT_MODEL = "grok-2-latest";
 const XAI_BASE_URL = "https://api.x.ai/v1";
@@ -10,14 +9,5 @@ export class XAIChatModel extends OpenAIChatModel {
             baseURL: options?.baseURL || XAI_BASE_URL,
         });
     }
-    get client() {
-        const apiKey = this.options?.apiKey || process.env.XAI_API_KEY;
-        if (!apiKey)
-            throw new Error("Api Key is required for XAIChatModel");
-        this._client ??= new OpenAI({
-            baseURL: this.options?.baseURL,
-            apiKey,
-        });
-        return this._client;
-    }
+    apiKeyEnvName = "XAI_API_KEY";
 }

package/lib/esm/prompt/prompt-builder.js

@@ -127,6 +127,7 @@ export class PromptBuilder {
             },
         }));
         let toolChoice;
+        const modelOptions = {};
         // use manual choice if configured in the agent
         const manualChoice = options.agent?.toolChoice;
         if (manualChoice) {
@@ -141,6 +142,7 @@ export class PromptBuilder {
             }
             else if (manualChoice === "router") {
                 toolChoice = "required";
+                modelOptions.parallelToolCalls = false;
             }
             else {
                 toolChoice = manualChoice;
@@ -154,6 +156,7 @@ export class PromptBuilder {
             toolAgents: toolAgents.length ? toolAgents : undefined,
             tools: tools.length ? tools : undefined,
             toolChoice,
+            modelOptions: Object.keys(modelOptions).length ? modelOptions : undefined,
         };
     }
 }

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

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

package/lib/esm/utils/prompts.js

@@ -0,0 +1,10 @@
+export function getJsonOutputPrompt(schema) {
+    let prompt = "Provide your output as a JSON containing the following fields:";
+    if (typeof schema === "string") {
+        prompt += `\n<json_fields>\n${schema}\n</json_fields>`;
+    }
+    else {
+        prompt += `\n<json_fields>\n${JSON.stringify(schema)}\n</json_fields>`;
+    }
+    return prompt;
+}

package/lib/esm/utils/stream-utils.d.ts

@@ -0,0 +1,15 @@
+import type { AgentProcessAsyncGenerator, AgentResponseChunk, AgentResponseStream, Message } from "../agents/agent.js";
+import { type PromiseOrValue } from "./type-utils.js";
+export declare function objectToAgentResponseStream<T extends Message>(json: T): AgentResponseStream<T>;
+export declare function mergeAgentResponseChunk<T extends Message>(output: T, chunk: AgentResponseChunk<T>): T;
+export declare function agentResponseStreamToObject<T extends Message>(stream: AgentResponseStream<T> | AgentProcessAsyncGenerator<T>): Promise<T>;
+export declare function asyncGeneratorToReadableStream<T extends Message>(generator: AgentProcessAsyncGenerator<T>): AgentResponseStream<T>;
+export declare function onAgentResponseStreamEnd<T extends Message>(stream: AgentResponseStream<T>, callback: (result: T) => PromiseOrValue<Partial<T> | void>, options?: {
+    errorCallback?: (error: Error) => Error;
+    processChunk?: (chunk: AgentResponseChunk<T>) => AgentResponseChunk<T>;
+}): ReadableStream<any>;
+export declare function isAsyncGenerator<T extends AsyncGenerator>(value: AsyncGenerator | unknown): value is T;
+export declare function arrayToAgentProcessAsyncGenerator<T extends Message>(chunks: (AgentResponseChunk<T> | Error)[], result?: Partial<T>): AgentProcessAsyncGenerator<T>;
+export declare function arrayToAgentResponseStream<T>(chunks: (AgentResponseChunk<T> | Error)[]): AgentResponseStream<T>;
+export declare function readableStreamToArray<T>(stream: ReadableStream<T>): Promise<T[]>;
+export declare function readableStreamToAsyncIterator<T>(stream: ReadableStream<T>): AsyncIterable<T>;