@aigne/core 1.7.0 → 1.9.0

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

@@ -2,6 +2,8 @@ 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 { checkArguments, isNonNullable } from "../utils/type-utils.js";
 import { ChatModel, } from "./chat-model.js";
 const CHAT_MODEL_OPENAI_DEFAULT_MODEL = "gpt-4o-mini";
@@ -23,16 +25,23 @@ 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);
     }
     _client;
+    apiKeyEnvName = "OPENAI_API_KEY";
+    apiKeyDefault;
+    supportsNativeStructuredOutputs = true;
+    supportsEndWithSystemMessage = true;
+    supportsToolsUseWithJsonSchema = true;
+    supportsParallelToolCalls = true;
+    supportsToolsEmptyParameters = 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,
@@ -43,91 +52,104 @@ export class OpenAIChatModel extends ChatModel {
         return this.options?.modelOptions;
     }
     async process(input) {
-        const res = await this.client.chat.completions.create({
+        const body = {
             model: this.options?.model || CHAT_MODEL_OPENAI_DEFAULT_MODEL,
             temperature: input.modelOptions?.temperature ?? this.modelOptions?.temperature,
             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: await this.getRunMessages(input),
             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,
-                };
-            }
+        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) };
         }
-        const result = {
-            usage,
-            model,
-        };
-        if (input.responseFormat?.type === "json_schema" && text) {
-            result.json = parseJSON(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: "" });
         }
-        else {
-            result.text = text;
+        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),
+            });
         }
-        if (toolCalls.length) {
-            result.toolCalls = toolCalls.map(({ args, ...c }) => ({
-                ...c,
-                function: { ...c.function, arguments: parseJSON(args) },
-            }));
+        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 };
         }
-        return result;
+        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 +178,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 +221,75 @@ function jsonSchemaToOpenAIJsonSchema(schema) {
     }
     return schema;
 }
+export async function extractResultFromStream(stream, jsonMode = false) {
+    let text = "";
+    const toolCalls = [];
+    let usage;
+    let model;
+    for await (const chunk of stream) {
+        const choice = chunk.choices?.[0];
+        model ??= chunk.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 (chunk.usage) {
+            usage = {
+                inputTokens: chunk.usage.prompt_tokens,
+                outputTokens: chunk.usage.completion_tokens,
+            };
+        }
+    }
+    const result = {
+        usage,
+        model,
+    };
+    if (jsonMode && text) {
+        result.json = parseJSON(text);
+    }
+    else {
+        result.text = text;
+    }
+    if (toolCalls.length) {
+        result.toolCalls = toolCalls.map(({ args, ...c }) => ({
+            ...c,
+            function: { ...c.function, arguments: parseJSON(args) },
+        }));
+    }
+    return 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/type-utils.d.ts

@@ -11,5 +11,5 @@ export declare function orArrayToArray<T>(value?: T | T[]): T[];
 export declare function createAccessorArray<T>(array: T[], accessor: (array: T[], name: string) => T | undefined): T[] & {
     [key: string]: T;
 };
-export declare function checkArguments<T>(prefix: string, schema: ZodType<T>, args: T): void;
+export declare function checkArguments<T>(prefix: string, schema: ZodType<T>, args: T): T;
 export declare function tryOrThrow<P extends PromiseOrValue<unknown>>(fn: () => P, error: string | Error | ((error: Error) => Error)): P;

package/lib/esm/utils/type-utils.js

@@ -43,7 +43,7 @@ export function createAccessorArray(array, accessor) {
 }
 export function checkArguments(prefix, schema, args) {
     try {
-        schema.parse(args, {
+        return schema.parse(args, {
             errorMap: (issue, ctx) => {
                 if (issue.code === "invalid_union") {
                     // handle all issues that are not invalid_type

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aigne/core",
-  "version": "1.7.0",
+  "version": "1.9.0",
   "description": "AIGNE core library for building AI-powered applications",
   "publishConfig": {
     "access": "public"
@@ -47,6 +47,9 @@
       "execution-engine/*": [
         "./lib/dts/execution-engine/*"
       ],
+      "loader/*": [
+        "./lib/dts/loader/*"
+      ],
       "models/*": [
         "./lib/dts/models/*"
       ],
@@ -83,11 +86,11 @@
     "@types/bun": "^1.2.9",
     "@types/express": "^5.0.1",
     "@types/mustache": "^4.2.5",
-    "@types/node": "^22.14.0",
+    "@types/node": "^22.14.1",
     "detect-port": "^2.1.0",
     "express": "^5.1.0",
     "npm-run-all": "^4.1.5",
-    "openai": "^4.93.0",
+    "openai": "^4.94.0",
     "rimraf": "^6.0.1",
     "typescript": "^5.8.3"
   },