@aigne/openai 0.14.2 → 0.14.3

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## [0.14.3](https://github.com/AIGNE-io/aigne-framework/compare/openai-v0.14.2...openai-v0.14.3) (2025-09-08)
+
+
+### Bug Fixes
+
+* support optional field sturectured output for gemini ([#468](https://github.com/AIGNE-io/aigne-framework/issues/468)) ([70c6279](https://github.com/AIGNE-io/aigne-framework/commit/70c62795039a2862e3333f26707329489bf938de))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @aigne/core bumped to 1.58.3
+  * devDependencies
+    * @aigne/test-utils bumped to 0.5.47
+
 ## [0.14.2](https://github.com/AIGNE-io/aigne-framework/compare/openai-v0.14.1...openai-v0.14.2) (2025-09-05)
 
 

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

@@ -151,6 +151,13 @@ export declare class OpenAIChatModel extends ChatModel {
     private getRunResponseFormat;
     private requestStructuredOutput;
     private extractResultFromStream;
+    /**
+     * Controls how optional fields are handled in JSON schema conversion
+     * - "anyOf": All fields are required but can be null (default)
+     * - "optional": Fields marked as optional in schema remain optional
+     */
+    protected optionalFieldMode?: "anyOf" | "optional";
+    protected jsonSchemaToOpenAIJsonSchema(schema: Record<string, unknown>): Record<string, unknown>;
 }
 /**
  * @hidden
@@ -162,7 +169,3 @@ export declare function contentsFromInputMessages(messages: ChatModelInputMessag
 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/cjs/openai-chat-model.js

@@ -3,7 +3,6 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.OpenAIChatModel = exports.openAIChatModelOptionsSchema = void 0;
 exports.contentsFromInputMessages = contentsFromInputMessages;
 exports.toolsFromInputTools = toolsFromInputTools;
-exports.jsonSchemaToOpenAIJsonSchema = jsonSchemaToOpenAIJsonSchema;
 const core_1 = require("@aigne/core");
 const logger_js_1 = require("@aigne/core/utils/logger.js");
 const model_utils_js_1 = require("@aigne/core/utils/model-utils.js");
@@ -196,7 +195,7 @@ class OpenAIChatModel extends core_1.ChatModel {
                     type: "json_schema",
                     json_schema: {
                         ...input.responseFormat.jsonSchema,
-                        schema: jsonSchemaToOpenAIJsonSchema(input.responseFormat.jsonSchema.schema),
+                        schema: this.jsonSchemaToOpenAIJsonSchema(input.responseFormat.jsonSchema.schema),
                     },
                 },
             };
@@ -312,6 +311,40 @@ class OpenAIChatModel extends core_1.ChatModel {
         });
         return streaming ? result : await (0, stream_utils_js_1.agentResponseStreamToObject)(result);
     }
+    /**
+     * Controls how optional fields are handled in JSON schema conversion
+     * - "anyOf": All fields are required but can be null (default)
+     * - "optional": Fields marked as optional in schema remain optional
+     */
+    optionalFieldMode = "anyOf";
+    jsonSchemaToOpenAIJsonSchema(schema) {
+        if (schema?.type === "object") {
+            const s = schema;
+            const required = this.optionalFieldMode === "anyOf" ? Object.keys(s.properties) : s.required;
+            return {
+                ...schema,
+                properties: Object.fromEntries(Object.entries(s.properties).map(([key, value]) => {
+                    const valueSchema = this.jsonSchemaToOpenAIJsonSchema(value);
+                    // NOTE: All fields must be required https://platform.openai.com/docs/guides/structured-outputs/all-fields-must-be-required
+                    return [
+                        key,
+                        this.optionalFieldMode === "optional" || s.required?.includes(key)
+                            ? valueSchema
+                            : { anyOf: [valueSchema, { type: ["null"] }] },
+                    ];
+                })),
+                required,
+            };
+        }
+        if (schema?.type === "array") {
+            const { items } = schema;
+            return {
+                ...schema,
+                items: this.jsonSchemaToOpenAIJsonSchema(items),
+            };
+        }
+        return schema;
+    }
 }
 exports.OpenAIChatModel = OpenAIChatModel;
 // Create role mapper for OpenAI (uses standard mapping)
@@ -373,34 +406,6 @@ function toolsFromInputTools(tools, options) {
         })
         : undefined;
 }
-/**
- * @hidden
- */
-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 || (0, uuid_1.v7)(),

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

@@ -151,6 +151,13 @@ export declare class OpenAIChatModel extends ChatModel {
     private getRunResponseFormat;
     private requestStructuredOutput;
     private extractResultFromStream;
+    /**
+     * Controls how optional fields are handled in JSON schema conversion
+     * - "anyOf": All fields are required but can be null (default)
+     * - "optional": Fields marked as optional in schema remain optional
+     */
+    protected optionalFieldMode?: "anyOf" | "optional";
+    protected jsonSchemaToOpenAIJsonSchema(schema: Record<string, unknown>): Record<string, unknown>;
 }
 /**
  * @hidden
@@ -162,7 +169,3 @@ export declare function contentsFromInputMessages(messages: ChatModelInputMessag
 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.d.ts

@@ -151,6 +151,13 @@ export declare class OpenAIChatModel extends ChatModel {
     private getRunResponseFormat;
     private requestStructuredOutput;
     private extractResultFromStream;
+    /**
+     * Controls how optional fields are handled in JSON schema conversion
+     * - "anyOf": All fields are required but can be null (default)
+     * - "optional": Fields marked as optional in schema remain optional
+     */
+    protected optionalFieldMode?: "anyOf" | "optional";
+    protected jsonSchemaToOpenAIJsonSchema(schema: Record<string, unknown>): Record<string, unknown>;
 }
 /**
  * @hidden
@@ -162,7 +169,3 @@ export declare function contentsFromInputMessages(messages: ChatModelInputMessag
 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

@@ -190,7 +190,7 @@ export class OpenAIChatModel extends ChatModel {
                     type: "json_schema",
                     json_schema: {
                         ...input.responseFormat.jsonSchema,
-                        schema: jsonSchemaToOpenAIJsonSchema(input.responseFormat.jsonSchema.schema),
+                        schema: this.jsonSchemaToOpenAIJsonSchema(input.responseFormat.jsonSchema.schema),
                     },
                 },
             };
@@ -306,6 +306,40 @@ export class OpenAIChatModel extends ChatModel {
         });
         return streaming ? result : await agentResponseStreamToObject(result);
     }
+    /**
+     * Controls how optional fields are handled in JSON schema conversion
+     * - "anyOf": All fields are required but can be null (default)
+     * - "optional": Fields marked as optional in schema remain optional
+     */
+    optionalFieldMode = "anyOf";
+    jsonSchemaToOpenAIJsonSchema(schema) {
+        if (schema?.type === "object") {
+            const s = schema;
+            const required = this.optionalFieldMode === "anyOf" ? Object.keys(s.properties) : s.required;
+            return {
+                ...schema,
+                properties: Object.fromEntries(Object.entries(s.properties).map(([key, value]) => {
+                    const valueSchema = this.jsonSchemaToOpenAIJsonSchema(value);
+                    // NOTE: All fields must be required https://platform.openai.com/docs/guides/structured-outputs/all-fields-must-be-required
+                    return [
+                        key,
+                        this.optionalFieldMode === "optional" || s.required?.includes(key)
+                            ? valueSchema
+                            : { anyOf: [valueSchema, { type: ["null"] }] },
+                    ];
+                })),
+                required,
+            };
+        }
+        if (schema?.type === "array") {
+            const { items } = schema;
+            return {
+                ...schema,
+                items: this.jsonSchemaToOpenAIJsonSchema(items),
+            };
+        }
+        return schema;
+    }
 }
 // Create role mapper for OpenAI (uses standard mapping)
 const mapRole = createRoleMapper(STANDARD_ROLE_MAP);
@@ -366,34 +400,6 @@ export function toolsFromInputTools(tools, options) {
         })
         : 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 || v7(),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aigne/openai",
-  "version": "0.14.2",
+  "version": "0.14.3",
   "description": "AIGNE OpenAI SDK for integrating with OpenAI's GPT models and API services",
   "publishConfig": {
     "access": "public"
@@ -39,7 +39,7 @@
     "openai": "^5.8.3",
     "uuid": "^11.1.0",
     "zod": "^3.25.67",
-    "@aigne/core": "^1.58.2",
+    "@aigne/core": "^1.58.3",
     "@aigne/platform-helpers": "^0.6.2"
   },
   "devDependencies": {
@@ -48,7 +48,7 @@
     "npm-run-all": "^4.1.5",
     "rimraf": "^6.0.1",
     "typescript": "^5.8.3",
-    "@aigne/test-utils": "^0.5.46"
+    "@aigne/test-utils": "^0.5.47"
   },
   "scripts": {
     "lint": "tsc --noEmit",