@aigne/openai 0.8.2 → 0.9.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## [0.9.0](https://github.com/AIGNE-io/aigne-framework/compare/openai-v0.8.2...openai-v0.9.0) (2025-07-10)
+
+
+### Features
+
+* **model:** reduce unnecessary LLM requests for structured output ([#241](https://github.com/AIGNE-io/aigne-framework/issues/241)) ([e28813c](https://github.com/AIGNE-io/aigne-framework/commit/e28813c021ed35c0251e198e2e007e2d746ab3d8))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @aigne/core bumped to 1.33.0
+  * devDependencies
+    * @aigne/test-utils bumped to 0.5.5
+
 ## [0.8.2](https://github.com/AIGNE-io/aigne-framework/compare/openai-v0.8.1...openai-v0.8.2) (2025-07-09)
 
 

package/README.md

@@ -6,8 +6,6 @@
 [![NPM Version](https://img.shields.io/npm/v/@aigne/openai)](https://www.npmjs.com/package/@aigne/openai)
 [![Elastic-2.0 licensed](https://img.shields.io/npm/l/@aigne/openai)](https://github.com/AIGNE-io/aigne-framework/blob/main/LICENSE.md)
 
-**English** | [中文](README.zh.md)
-
 AIGNE OpenAI SDK for integrating with OpenAI's GPT models and API services within the [AIGNE Framework](https://github.com/AIGNE-io/aigne-framework).
 
 ## Introduction

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

@@ -139,6 +139,7 @@ export declare class OpenAIChatModel extends ChatModel {
      * @returns The generated response
      */
     process(input: ChatModelInput): PromiseOrValue<AgentProcessResult<ChatModelOutput>>;
+    private ajv;
     private _process;
     private getParallelToolCalls;
     protected getRunMessages(input: ChatModelInput): Promise<ChatCompletionMessageParam[]>;

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

@@ -8,11 +8,13 @@ exports.contentsFromInputMessages = contentsFromInputMessages;
 exports.toolsFromInputTools = toolsFromInputTools;
 exports.jsonSchemaToOpenAIJsonSchema = jsonSchemaToOpenAIJsonSchema;
 const core_1 = require("@aigne/core");
-const json_schema_js_1 = require("@aigne/core/utils/json-schema.js");
+const logger_js_1 = require("@aigne/core/utils/logger.js");
 const model_utils_js_1 = require("@aigne/core/utils/model-utils.js");
 const prompts_js_1 = require("@aigne/core/utils/prompts.js");
 const stream_utils_js_1 = require("@aigne/core/utils/stream-utils.js");
 const type_utils_js_1 = require("@aigne/core/utils/type-utils.js");
+const ajv_1 = require("ajv");
+const jaison_1 = __importDefault(require("jaison"));
 const nanoid_1 = require("nanoid");
 const openai_1 = __importDefault(require("openai"));
 const zod_1 = require("zod");
@@ -102,6 +104,7 @@ class OpenAIChatModel extends core_1.ChatModel {
     process(input) {
         return this._process(input);
     }
+    ajv = new ajv_1.Ajv();
     async _process(input) {
         const messages = await this.getRunMessages(input);
         const body = {
@@ -118,6 +121,11 @@ class OpenAIChatModel extends core_1.ChatModel {
             },
             stream: true,
         };
+        // For models that do not support tools use with JSON schema in same request,
+        // so we need to handle the case where tools are not used and responseFormat is json
+        if (!input.tools?.length && input.responseFormat?.type === "json_schema") {
+            return await this.requestStructuredOutput(body, input.responseFormat);
+        }
         const { jsonMode, responseFormat } = await this.getRunResponseFormat(input);
         const stream = (await this.client.chat.completions.create({
             ...body,
@@ -132,14 +140,18 @@ class OpenAIChatModel extends core_1.ChatModel {
             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: (0, model_utils_js_1.mergeUsage)(result.usage, output.usage) };
+        // Just return the result if it has tool calls
+        if (result.toolCalls?.length || result.json)
+            return result;
+        // Try to parse the text response as JSON
+        // If it matches the json_schema, return it as json
+        const json = safeParseJSON(result.text || "");
+        if (this.ajv.validate(input.responseFormat.jsonSchema.schema, json)) {
+            return { ...result, json, text: undefined };
         }
-        return result;
+        logger_js_1.logger.warn(`${this.name}: Text response does not match JSON schema, trying to use tool to extract json `, { text: result.text });
+        const output = await this.requestStructuredOutput(body, input.responseFormat);
+        return { ...output, usage: (0, model_utils_js_1.mergeUsage)(result.usage, output.usage) };
     }
     getParallelToolCalls(input) {
         if (!this.supportsParallelToolCalls)
@@ -150,15 +162,14 @@ class OpenAIChatModel extends core_1.ChatModel {
     }
     async getRunMessages(input) {
         const messages = await contentsFromInputMessages(input.messages);
-        if (!this.supportsToolsUseWithJsonSchema && input.tools?.length)
-            return messages;
-        if (this.supportsNativeStructuredOutputs)
-            return messages;
         if (input.responseFormat?.type === "json_schema") {
-            messages.unshift({
-                role: "system",
-                content: (0, prompts_js_1.getJsonOutputPrompt)(input.responseFormat.jsonSchema.schema),
-            });
+            if (!this.supportsNativeStructuredOutputs ||
+                (!this.supportsToolsUseWithJsonSchema && input.tools?.length)) {
+                messages.unshift({
+                    role: "system",
+                    content: (0, prompts_js_1.getJsonOutputPrompt)(input.responseFormat.jsonSchema.schema),
+                });
+            }
         }
         return messages;
     }
@@ -269,7 +280,7 @@ class OpenAIChatModel extends core_1.ChatModel {
                         controller.enqueue({
                             delta: {
                                 json: {
-                                    json: (0, json_schema_js_1.parseJSON)(text),
+                                    json: safeParseJSON(text),
                                 },
                             },
                         });
@@ -280,7 +291,7 @@ class OpenAIChatModel extends core_1.ChatModel {
                                 json: {
                                     toolCalls: toolCalls.map(({ args, ...c }) => ({
                                         ...c,
-                                        function: { ...c.function, arguments: (0, json_schema_js_1.parseJSON)(args) },
+                                        function: { ...c.function, arguments: safeParseJSON(args) },
                                     })),
                                 },
                             },
@@ -408,7 +419,7 @@ function handleCompleteToolCall(toolCalls, call) {
         type: "function",
         function: {
             name: call.function?.name || "",
-            arguments: (0, json_schema_js_1.parseJSON)(call.function?.arguments || "{}"),
+            arguments: safeParseJSON(call.function?.arguments || "{}"),
         },
         args: call.function?.arguments || "",
     });
@@ -422,3 +433,13 @@ class CustomOpenAI extends openai_1.default {
         return super.makeStatusError(status, error, message, headers);
     }
 }
+function safeParseJSON(text) {
+    if (!text)
+        return null;
+    try {
+        return (0, jaison_1.default)(text);
+    }
+    catch {
+        return null;
+    }
+}

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

@@ -139,6 +139,7 @@ export declare class OpenAIChatModel extends ChatModel {
      * @returns The generated response
      */
     process(input: ChatModelInput): PromiseOrValue<AgentProcessResult<ChatModelOutput>>;
+    private ajv;
     private _process;
     private getParallelToolCalls;
     protected getRunMessages(input: ChatModelInput): Promise<ChatCompletionMessageParam[]>;

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

@@ -139,6 +139,7 @@ export declare class OpenAIChatModel extends ChatModel {
      * @returns The generated response
      */
     process(input: ChatModelInput): PromiseOrValue<AgentProcessResult<ChatModelOutput>>;
+    private ajv;
     private _process;
     private getParallelToolCalls;
     protected getRunMessages(input: ChatModelInput): Promise<ChatCompletionMessageParam[]>;

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

@@ -1,9 +1,11 @@
 import { ChatModel, } from "@aigne/core";
-import { parseJSON } from "@aigne/core/utils/json-schema.js";
+import { logger } from "@aigne/core/utils/logger.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 { Ajv } from "ajv";
+import jaison from "jaison";
 import { nanoid } from "nanoid";
 import OpenAI from "openai";
 import { z } from "zod";
@@ -93,6 +95,7 @@ export class OpenAIChatModel extends ChatModel {
     process(input) {
         return this._process(input);
     }
+    ajv = new Ajv();
     async _process(input) {
         const messages = await this.getRunMessages(input);
         const body = {
@@ -109,6 +112,11 @@ export class OpenAIChatModel extends ChatModel {
             },
             stream: true,
         };
+        // For models that do not support tools use with JSON schema in same request,
+        // so we need to handle the case where tools are not used and responseFormat is json
+        if (!input.tools?.length && input.responseFormat?.type === "json_schema") {
+            return await this.requestStructuredOutput(body, input.responseFormat);
+        }
         const { jsonMode, responseFormat } = await this.getRunResponseFormat(input);
         const stream = (await this.client.chat.completions.create({
             ...body,
@@ -123,14 +131,18 @@ export class OpenAIChatModel extends ChatModel {
             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) };
+        // Just return the result if it has tool calls
+        if (result.toolCalls?.length || result.json)
+            return result;
+        // Try to parse the text response as JSON
+        // If it matches the json_schema, return it as json
+        const json = safeParseJSON(result.text || "");
+        if (this.ajv.validate(input.responseFormat.jsonSchema.schema, json)) {
+            return { ...result, json, text: undefined };
         }
-        return result;
+        logger.warn(`${this.name}: Text response does not match JSON schema, trying to use tool to extract json `, { text: result.text });
+        const output = await this.requestStructuredOutput(body, input.responseFormat);
+        return { ...output, usage: mergeUsage(result.usage, output.usage) };
     }
     getParallelToolCalls(input) {
         if (!this.supportsParallelToolCalls)
@@ -141,15 +153,14 @@ export class OpenAIChatModel extends ChatModel {
     }
     async getRunMessages(input) {
         const messages = await contentsFromInputMessages(input.messages);
-        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 (!this.supportsNativeStructuredOutputs ||
+                (!this.supportsToolsUseWithJsonSchema && input.tools?.length)) {
+                messages.unshift({
+                    role: "system",
+                    content: getJsonOutputPrompt(input.responseFormat.jsonSchema.schema),
+                });
+            }
         }
         return messages;
     }
@@ -260,7 +271,7 @@ export class OpenAIChatModel extends ChatModel {
                         controller.enqueue({
                             delta: {
                                 json: {
-                                    json: parseJSON(text),
+                                    json: safeParseJSON(text),
                                 },
                             },
                         });
@@ -271,7 +282,7 @@ export class OpenAIChatModel extends ChatModel {
                                 json: {
                                     toolCalls: toolCalls.map(({ args, ...c }) => ({
                                         ...c,
-                                        function: { ...c.function, arguments: parseJSON(args) },
+                                        function: { ...c.function, arguments: safeParseJSON(args) },
                                     })),
                                 },
                             },
@@ -398,7 +409,7 @@ function handleCompleteToolCall(toolCalls, call) {
         type: "function",
         function: {
             name: call.function?.name || "",
-            arguments: parseJSON(call.function?.arguments || "{}"),
+            arguments: safeParseJSON(call.function?.arguments || "{}"),
         },
         args: call.function?.arguments || "",
     });
@@ -412,3 +423,13 @@ class CustomOpenAI extends OpenAI {
         return super.makeStatusError(status, error, message, headers);
     }
 }
+function safeParseJSON(text) {
+    if (!text)
+        return null;
+    try {
+        return jaison(text);
+    }
+    catch {
+        return null;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aigne/openai",
-  "version": "0.8.2",
+  "version": "0.9.0",
   "description": "AIGNE OpenAI SDK for integrating with OpenAI's GPT models and API services",
   "publishConfig": {
     "access": "public"
@@ -32,10 +32,12 @@
     }
   },
   "dependencies": {
+    "ajv": "^8.17.1",
+    "jaison": "^2.0.2",
     "nanoid": "^5.1.5",
     "openai": "^5.8.2",
     "zod": "^3.25.67",
-    "@aigne/core": "^1.32.2"
+    "@aigne/core": "^1.33.0"
   },
   "devDependencies": {
     "@types/bun": "^1.2.17",
@@ -43,7 +45,7 @@
     "npm-run-all": "^4.1.5",
     "rimraf": "^6.0.1",
     "typescript": "^5.8.3",
-    "@aigne/test-utils": "^0.5.4"
+    "@aigne/test-utils": "^0.5.5"
   },
   "scripts": {
     "lint": "tsc --noEmit",

package/README.zh.md

@@ -1,114 +0,0 @@
-# @aigne/openai
-
-[![GitHub star chart](https://img.shields.io/github/stars/AIGNE-io/aigne-framework?style=flat-square)](https://star-history.com/#AIGNE-io/aigne-framework)
-[![Open Issues](https://img.shields.io/github/issues-raw/AIGNE-io/aigne-framework?style=flat-square)](https://github.com/AIGNE-io/aigne-framework/issues)
-[![codecov](https://codecov.io/gh/AIGNE-io/aigne-framework/graph/badge.svg?token=DO07834RQL)](https://codecov.io/gh/AIGNE-io/aigne-framework)
-[![NPM Version](https://img.shields.io/npm/v/@aigne/openai)](https://www.npmjs.com/package/@aigne/openai)
-[![Elastic-2.0 licensed](https://img.shields.io/npm/l/@aigne/openai)](https://github.com/AIGNE-io/aigne-framework/blob/main/LICENSE.md)
-
-[English](README.md) | **中文**
-
-AIGNE OpenAI SDK，用于在 [AIGNE 框架](https://github.com/AIGNE-io/aigne-framework) 中集成 OpenAI 的 GPT 模型和 API 服务。
-
-## 简介
-
-`@aigne/openai` 提供了 AIGNE 框架与 OpenAI 强大的语言模型和 API 之间的无缝集成。该包使开发者能够在 AIGNE 应用程序中轻松利用 OpenAI 的 GPT 模型，同时提供框架内一致的接口，充分发挥 OpenAI 先进的 AI 能力。
-
-## 特性
-
-* **OpenAI API 集成**：使用官方 SDK 直接连接到 OpenAI 的 API 服务
-* **聊天完成**：支持 OpenAI 的聊天完成 API 和所有可用模型
-* **函数调用**：内置支持 OpenAI 的函数调用功能
-* **流式响应**：支持流式响应，提供更高响应性的应用程序体验
-* **类型安全**：为所有 API 和模型提供全面的 TypeScript 类型定义
-* **一致接口**：兼容 AIGNE 框架的模型接口
-* **错误处理**：健壮的错误处理和重试机制
-* **完整配置**：丰富的配置选项用于微调行为
-
-## 安装
-
-### 使用 npm
-
-```bash
-npm install @aigne/openai @aigne/core
-```
-
-### 使用 yarn
-
-```bash
-yarn add @aigne/openai @aigne/core
-```
-
-### 使用 pnpm
-
-```bash
-pnpm add @aigne/openai @aigne/core
-```
-
-## 基本用法
-
-```typescript file="test/openai-chat-model.test.ts" region="example-openai-chat-model"
-import { OpenAIChatModel } from "@aigne/openai";
-
-const model = new OpenAIChatModel({
-  // Provide API key directly or use environment variable OPENAI_API_KEY
-  apiKey: "your-api-key", // Optional if set in env variables
-  model: "gpt-4o", // Defaults to "gpt-4o-mini" if not specified
-  modelOptions: {
-    temperature: 0.7,
-  },
-});
-
-const result = await model.invoke({
-  messages: [{ role: "user", content: "Hello, who are you?" }],
-});
-
-console.log(result);
-/* Output:
-  {
-    text: "Hello! How can I assist you today?",
-    model: "gpt-4o",
-    usage: {
-      inputTokens: 10,
-      outputTokens: 9
-    }
-  }
-  */
-```
-
-## 流式响应
-
-```typescript file="test/openai-chat-model.test.ts" region="example-openai-chat-model-stream"
-import { isAgentResponseDelta } from "@aigne/core";
-import { OpenAIChatModel } from "@aigne/openai";
-
-const model = new OpenAIChatModel({
-  apiKey: "your-api-key",
-  model: "gpt-4o",
-});
-
-const stream = await model.invoke(
-  {
-    messages: [{ role: "user", content: "Hello, who are you?" }],
-  },
-  { streaming: true },
-);
-
-let fullText = "";
-const json = {};
-
-for await (const chunk of stream) {
-  if (isAgentResponseDelta(chunk)) {
-    const text = chunk.delta.text?.text;
-    if (text) fullText += text;
-    if (chunk.delta.json) Object.assign(json, chunk.delta.json);
-  }
-}
-
-console.log(fullText); // Output: "Hello! How can I assist you today?"
-console.log(json); // { model: "gpt-4o", usage: { inputTokens: 10, outputTokens: 9 } }
-```
-
-## 许可证
-
-Elastic-2.0