@aigne/openai 0.1.0

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

@@ -0,0 +1,165 @@
+import { type AgentProcessResult, ChatModel, type ChatModelInput, type ChatModelInputMessage, type ChatModelInputTool, type ChatModelOptions, type ChatModelOutput, type Role } from "@aigne/core";
+import { type PromiseOrValue } from "@aigne/core/utils/type-utils.js";
+import OpenAI from "openai";
+import type { ChatCompletionMessageParam, ChatCompletionTool } from "openai/resources";
+import { z } from "zod";
+export interface OpenAIChatModelCapabilities {
+    supportsNativeStructuredOutputs: boolean;
+    supportsEndWithSystemMessage: boolean;
+    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>;
+    model: z.ZodOptional<z.ZodString>;
+    modelOptions: z.ZodOptional<z.ZodObject<{
+        model: z.ZodOptional<z.ZodString>;
+        temperature: z.ZodOptional<z.ZodNumber>;
+        topP: z.ZodOptional<z.ZodNumber>;
+        frequencyPenalty: z.ZodOptional<z.ZodNumber>;
+        presencePenalty: z.ZodOptional<z.ZodNumber>;
+        parallelToolCalls: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+    }, "strip", z.ZodTypeAny, {
+        parallelToolCalls: boolean;
+        model?: string | undefined;
+        temperature?: number | undefined;
+        topP?: number | undefined;
+        frequencyPenalty?: number | undefined;
+        presencePenalty?: number | undefined;
+    }, {
+        model?: string | undefined;
+        temperature?: number | undefined;
+        topP?: number | undefined;
+        frequencyPenalty?: number | undefined;
+        presencePenalty?: number | undefined;
+        parallelToolCalls?: boolean | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    apiKey?: string | undefined;
+    baseURL?: string | undefined;
+    model?: string | undefined;
+    modelOptions?: {
+        parallelToolCalls: boolean;
+        model?: string | undefined;
+        temperature?: number | undefined;
+        topP?: number | undefined;
+        frequencyPenalty?: number | undefined;
+        presencePenalty?: number | undefined;
+    } | undefined;
+}, {
+    apiKey?: string | undefined;
+    baseURL?: string | undefined;
+    model?: string | undefined;
+    modelOptions?: {
+        model?: string | undefined;
+        temperature?: number | undefined;
+        topP?: number | undefined;
+        frequencyPenalty?: number | undefined;
+        presencePenalty?: number | undefined;
+        parallelToolCalls?: boolean | undefined;
+    } | 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/openai-chat-model.test.ts#example-openai-chat-model}
+ *
+ * @example
+ * Here's an example with streaming response:
+ * {@includeCode ../test/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;
+    protected supportsNativeStructuredOutputs: boolean;
+    protected supportsEndWithSystemMessage: boolean;
+    protected supportsToolsUseWithJsonSchema: boolean;
+    protected supportsParallelToolCalls: boolean;
+    protected supportsToolsEmptyParameters: boolean;
+    protected supportsToolStreaming: boolean;
+    protected supportsTemperature: boolean;
+    get client(): OpenAI;
+    get modelOptions(): ChatModelOptions | undefined;
+    /**
+     * 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/esm/openai-chat-model.js

@@ -0,0 +1,405 @@
+import { ChatModel, } from "@aigne/core";
+import { parseJSON } from "@aigne/core/utils/json-schema.js";
+import { mergeUsage } from "@aigne/core/utils/model-utils.js";
+import { getJsonOutputPrompt } from "@aigne/core/utils/prompts.js";
+import { agentResponseStreamToObject } from "@aigne/core/utils/stream-utils.js";
+import { checkArguments, isNonNullable, } from "@aigne/core/utils/type-utils.js";
+import { nanoid } from "nanoid";
+import OpenAI from "openai";
+import { z } from "zod";
+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 },
+};
+/**
+ * @hidden
+ */
+export const openAIChatModelOptionsSchema = z.object({
+    apiKey: z.string().optional(),
+    baseURL: z.string().optional(),
+    model: z.string().optional(),
+    modelOptions: z
+        .object({
+        model: z.string().optional(),
+        temperature: z.number().optional(),
+        topP: z.number().optional(),
+        frequencyPenalty: z.number().optional(),
+        presencePenalty: z.number().optional(),
+        parallelToolCalls: z.boolean().optional().default(true),
+    })
+        .optional(),
+});
+/**
+ * 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/openai-chat-model.test.ts#example-openai-chat-model}
+ *
+ * @example
+ * Here's an example with streaming response:
+ * {@includeCode ../test/openai-chat-model.test.ts#example-openai-chat-model-streaming}
+ */
+export class OpenAIChatModel extends ChatModel {
+    options;
+    constructor(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);
+    }
+    /**
+     * @hidden
+     */
+    _client;
+    apiKeyEnvName = "OPENAI_API_KEY";
+    apiKeyDefault;
+    supportsNativeStructuredOutputs = true;
+    supportsEndWithSystemMessage = true;
+    supportsToolsUseWithJsonSchema = true;
+    supportsParallelToolCalls = true;
+    supportsToolsEmptyParameters = true;
+    supportsToolStreaming = true;
+    supportsTemperature = true;
+    get client() {
+        const apiKey = this.options?.apiKey || process.env[this.apiKeyEnvName] || this.apiKeyDefault;
+        if (!apiKey)
+            throw new Error(`Api Key is required for ${this.name}`);
+        this._client ??= new OpenAI({
+            baseURL: this.options?.baseURL,
+            apiKey,
+        });
+        return this._client;
+    }
+    get modelOptions() {
+        return this.options?.modelOptions;
+    }
+    /**
+     * Process the input and generate a response
+     * @param input The input to process
+     * @returns The generated response
+     */
+    process(input) {
+        return this._process(input);
+    }
+    async _process(input) {
+        const messages = await this.getRunMessages(input);
+        const body = {
+            model: this.options?.model || CHAT_MODEL_OPENAI_DEFAULT_MODEL,
+            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,
+            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,
+        });
+        if (input.responseFormat?.type !== "json_schema") {
+            return await this.extractResultFromStream(stream, false, true);
+        }
+        const result = await this.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) };
+        }
+        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 (!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 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 this.extractResultFromStream(res, jsonMode);
+    }
+    async extractResultFromStream(stream, jsonMode, streaming) {
+        const result = new ReadableStream({
+            start: async (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) {
+                                if (this.supportsToolStreaming && 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) },
+                                    })),
+                                },
+                            },
+                        });
+                    }
+                    controller.close();
+                }
+                catch (error) {
+                    controller.error(error);
+                }
+            },
+        });
+        return streaming ? result : await agentResponseStreamToObject(result);
+    }
+}
+/**
+ * @hidden
+ */
+export const ROLE_MAP = {
+    system: "system",
+    user: "user",
+    agent: "assistant",
+    tool: "tool",
+};
+/**
+ * @hidden
+ */
+export async function contentsFromInputMessages(messages) {
+    return messages.map((i) => ({
+        role: ROLE_MAP[i.role],
+        content: typeof i.content === "string"
+            ? i.content
+            : i.content
+                ?.map((c) => {
+                if (c.type === "text") {
+                    return { type: "text", text: c.text };
+                }
+                if (c.type === "image_url") {
+                    return {
+                        type: "image_url",
+                        image_url: { url: c.url },
+                    };
+                }
+            })
+                .filter(isNonNullable),
+        tool_calls: i.toolCalls?.map((i) => ({
+            ...i,
+            function: {
+                ...i.function,
+                arguments: JSON.stringify(i.function.arguments),
+            },
+        })),
+        tool_call_id: i.toolCallId,
+        name: i.name,
+    }));
+}
+/**
+ * @hidden
+ */
+export function toolsFromInputTools(tools, options) {
+    return tools?.length
+        ? 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;
+}
+/**
+ * @hidden
+ */
+export function jsonSchemaToOpenAIJsonSchema(schema) {
+    if (schema?.type === "object") {
+        const { required, properties } = schema;
+        return {
+            ...schema,
+            properties: Object.fromEntries(Object.entries(properties).map(([key, value]) => {
+                const valueSchema = jsonSchemaToOpenAIJsonSchema(value);
+                // NOTE: All fields must be required https://platform.openai.com/docs/guides/structured-outputs/all-fields-must-be-required
+                return [
+                    key,
+                    required?.includes(key) ? valueSchema : { anyOf: [valueSchema, { type: ["null"] }] },
+                ];
+            })),
+            required: Object.keys(properties),
+        };
+    }
+    if (schema?.type === "array") {
+        const { items } = schema;
+        return {
+            ...schema,
+            items: jsonSchemaToOpenAIJsonSchema(items),
+        };
+    }
+    return schema;
+}
+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/package.json

@@ -0,0 +1 @@
+{"type": "module"}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@aigne/openai",
+  "version": "0.1.0",
+  "description": "AIGNE OpenAI SDK for integrating with OpenAI's GPT models and API services",
+  "publishConfig": {
+    "access": "public"
+  },
+  "author": "Arcblock <blocklet@arcblock.io> https://github.com/blocklet",
+  "homepage": "https://github.com/AIGNE-io/aigne-framework",
+  "license": "Elastic-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AIGNE-io/aigne-framework"
+  },
+  "files": [
+    "lib/cjs",
+    "lib/dts",
+    "lib/esm",
+    "LICENSE",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "type": "module",
+  "main": "./lib/cjs/index.js",
+  "module": "./lib/esm/index.js",
+  "types": "./lib/dts/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./lib/esm/index.js",
+      "require": "./lib/cjs/index.js",
+      "types": "./lib/dts/index.d.ts"
+    }
+  },
+  "dependencies": {
+    "nanoid": "^5.1.5",
+    "openai": "^4.87.3",
+    "zod": "^3.24.4",
+    "@aigne/core": "^1.16.0"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.2.12",
+    "@types/node": "^22.15.15",
+    "npm-run-all": "^4.1.5",
+    "rimraf": "^6.0.1",
+    "typescript": "^5.8.3",
+    "@aigne/test-utils": "^0.3.0"
+  },
+  "scripts": {
+    "lint": "tsc --noEmit",
+    "build": "tsc --build scripts/tsconfig.build.json",
+    "clean": "rimraf lib test/coverage",
+    "test": "bun test",
+    "test:coverage": "bun test --coverage --coverage-reporter=lcov --coverage-reporter=text",
+    "postbuild": "echo '{\"type\": \"module\"}' > lib/esm/package.json && echo '{\"type\": \"commonjs\"}' > lib/cjs/package.json"
+  }
+}