openai 7.4.0 → 7.6.0

package/helpers/zod.d.ts

@@ -1,25 +1,36 @@
-import { ResponseFormatJSONSchema } from "../resources/index.js";
-import { AutoParseableResponseFormat, AutoParseableTextFormat, AutoParseableTool } from "../lib/parser.js";
-import { AutoParseableResponseTool } from "../lib/ResponsesParser.js";
-import { type ResponseFormatTextJSONSchemaConfig } from "../resources/responses/responses.js";
-import { type RealtimeFunctionTool } from "../resources/realtime/realtime.js";
+import type { ResponseFormatJSONSchema } from "../resources/index.js";
+import type { AutoParseableResponseFormat, AutoParseableTextFormat, AutoParseableTool } from "../lib/parser.js";
+import type { AutoParseableResponseTool } from "../lib/ResponsesParser.js";
+import type { ResponseFormatTextJSONSchemaConfig } from "../resources/responses/responses.js";
+import type { RealtimeFunctionTool } from "../resources/realtime/realtime.js";
+/** Minimal Zod v3, v4, or v4 Mini schema shape accepted by the public parsing helpers. */
 type ZodTypeLike = ({
+    /** Inferred parsed-output type exposed by Zod v3 and compatible Zod schemas. */
     _output: unknown;
 } | {
+    /** Zod v4 schema metadata that exposes the inferred parsed-output type. */
     _zod: {
+        /** Inferred value produced after successful schema validation. */
         output: unknown;
     };
 }) & {
+    /** Synchronous schema parser when the validator exposes an instance-level parse method. */
     parse?: (data: unknown) => unknown;
 };
+/** Extracts the validated output type from a supported Zod schema. */
 type InferZodType<T extends ZodTypeLike> = T extends {
+    /** Parsed output type exposed directly by Zod v3 and compatible schemas. */
     _output: infer Output;
 } ? Output : T extends {
+    /** Zod v4 schema metadata containing its inferred parsed-output type. */
     _zod: {
+        /** Parsed value type inferred from the Zod v4 schema. */
         output: infer Output;
     };
 } ? Output : never;
+/** Named reusable Zod schemas extracted into a generated JSON Schema definitions object. */
 type ZodSchemaDefinitions = Record<string, ZodTypeLike>;
+/** Optional model-visible metadata and reusable schema definitions for a chat response format. */
 type ZodResponseFormatProps = Omit<ResponseFormatJSONSchema.JSONSchema, 'schema' | 'strict' | 'name'> & {
     /**
      * Schemas to extract into the generated JSON Schema definitions.
@@ -63,32 +74,90 @@ type ZodResponseFormatProps = Omit<ResponseFormatJSONSchema.JSONSchema, 'schema'
  *
  * This can be passed directly to the `.create()` method but will not
  * result in any automatic parsing, you'll have to parse the response yourself.
+ *
+ * Supports schemas from `zod/v3`, `zod/v4`, and `zod/v4-mini`.
+ *
+ * @param zodObject Zod schema used to generate and validate structured model output.
+ * @param name Model-visible name of the generated strict JSON Schema.
+ * @param props Optional response-format metadata and named reusable schema definitions.
  */
 export declare function zodResponseFormat<ZodInput extends ZodTypeLike>(zodObject: ZodInput, name: string, props?: ZodResponseFormatProps): AutoParseableResponseFormat<InferZodType<ZodInput>>;
+/**
+ * Creates a strict Responses API text format that validates output with a Zod schema.
+ *
+ * Pass the returned format as `text.format` to `client.responses.parse()` to
+ * populate `response.output_parsed` with the schema's inferred output type.
+ * Calling `responses.create()` with the same format does not enable automatic
+ * parsing. Schemas from `zod/v3`, `zod/v4`, and `zod/v4-mini` are supported.
+ *
+ * ```ts
+ * const response = await client.responses.parse({
+ *   model: 'gpt-5.5',
+ *   input: 'Describe the weather.',
+ *   text: { format: zodTextFormat(Weather, 'weather') },
+ * });
+ * console.log(response.output_parsed);
+ * ```
+ *
+ * @param zodObject Zod schema used to generate and validate structured model output.
+ * @param name Model-visible name of the generated strict JSON Schema.
+ * @param props Optional model-visible text-format metadata, such as a description.
+ */
 export declare function zodTextFormat<ZodInput extends ZodTypeLike>(zodObject: ZodInput, name: string, props?: Omit<ResponseFormatTextJSONSchemaConfig, 'schema' | 'type' | 'strict' | 'name'>): AutoParseableTextFormat<InferZodType<ZodInput>>;
 /**
  * Creates a chat completion `function` tool that can be invoked
  * automatically by the chat completion `.runTools()` method or automatically
  * parsed by `.parse()` / `.stream()`.
+ *
+ * Arguments are converted to strict JSON Schema and validated with the supplied
+ * Zod schema before the optional callback receives them.
+ *
+ * @param options Model-visible function name, Zod parameter schema, description,
+ * and optional callback used by `chat.completions.runTools()`.
  */
 export declare function zodFunction<Parameters extends ZodTypeLike>(options: {
+    /** Model-visible function name used to identify matching tool calls. */
     name: string;
+    /** Zod schema used to describe and validate the function's JSON arguments. */
     parameters: Parameters;
+    /** Optional callback invoked with validated arguments by chat `runTools()`. */
     function?: ((args: InferZodType<Parameters>) => unknown | Promise<unknown>) | undefined;
+    /** Optional model-visible explanation of when and how the function should be used. */
     description?: string | undefined;
 }): AutoParseableTool<{
+    /** Inferred argument type produced by the Zod parameter schema. */
     arguments: InferZodType<Parameters>;
+    /** Model-visible name used to match generated function calls. */
     name: string;
+    /** Callback signature associated with validated function-call arguments. */
     function: (args: InferZodType<Parameters>) => unknown;
 }>;
+/**
+ * Creates a strict Responses API function tool with Zod-validated arguments.
+ *
+ * Passing this tool to `client.responses.parse()` populates
+ * `function_call.parsed_arguments` with the inferred schema output. Parsing a
+ * response does not invoke the optional callback or submit tool results; the
+ * application remains responsible for its function-execution loop.
+ *
+ * @param options Model-visible function name, Zod parameter schema, optional
+ * description, and optional callback metadata.
+ */
 export declare function zodResponsesFunction<Parameters extends ZodTypeLike>(options: {
+    /** Model-visible function name used to identify matching tool calls. */
     name: string;
+    /** Zod schema used to describe and validate the function's JSON arguments. */
     parameters: Parameters;
+    /** Optional callback retained on the tool; `responses.parse()` does not execute it. */
     function?: ((args: InferZodType<Parameters>) => unknown | Promise<unknown>) | undefined;
+    /** Optional model-visible explanation of when and how the function should be used. */
     description?: string | undefined;
 }): AutoParseableResponseTool<{
+    /** Inferred argument type produced by the Zod parameter schema. */
     arguments: InferZodType<Parameters>;
+    /** Model-visible name used to match generated function calls. */
     name: string;
+    /** Callback signature associated with validated function-call arguments. */
     function: (args: InferZodType<Parameters>) => unknown;
 }>;
 /**
@@ -99,10 +168,15 @@ export declare function zodResponsesFunction<Parameters extends ZodTypeLike>(opt
  *
  * This helper only creates the tool definition. Parse function-call arguments
  * from Realtime events with the original Zod schema.
+ *
+ * @param options Model-visible function name, Zod parameter schema, and description.
  */
 export declare function zodRealtimeFunction<Parameters extends ZodTypeLike>(options: {
+    /** Model-visible function name used to identify Realtime function calls. */
     name: string;
+    /** Zod schema converted into the Realtime function's non-strict JSON Schema. */
     parameters: Parameters;
+    /** Optional model-visible explanation of when and how the function should be used. */
     description?: string | undefined;
 }): RealtimeFunctionTool;
 export {};

package/helpers/zod.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"zod.d.ts","sourceRoot":"","sources":["../src/helpers/zod.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"zod.d.ts","sourceRoot":"","sources":["../src/helpers/zod.ts"],"names":[],"mappings":"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"}

package/helpers/zod.js

@@ -11,11 +11,13 @@ const parser_1 = require("../lib/parser.js");
 const zod_to_json_schema_1 = require("../_vendor/zod-to-json-schema/index.js");
 const ResponsesParser_1 = require("../lib/ResponsesParser.js");
 const transform_1 = require("../lib/transform.js");
+const values_1 = require("../internal/utils/values.js");
+const zod_v3_strict_schema_1 = require("./zod-v3-strict-schema.js");
 function encodeSchemaDefinitionRefToken(token) {
     return encodeURIComponent(token.replace(/~/g, '~0').replace(/\//g, '~1'));
 }
 function validateSchemaDefinitions(schemaDefinitions) {
-    if (schemaDefinitions && Object.prototype.hasOwnProperty.call(schemaDefinitions, '__proto__')) {
+    if (schemaDefinitions && (0, values_1.hasOwn)(schemaDefinitions, '__proto__')) {
         throw new Error('schemaDefinitions cannot include "__proto__" as a definition name');
     }
 }
@@ -24,33 +26,40 @@ function escapeSchemaDefinitionRefs(schema, schemaDefinitions) {
         `#/definitions/${name}`,
         `#/definitions/${encodeSchemaDefinitionRefToken(name)}`,
     ]));
+    if (refReplacements.size === 0) {
+        return schema;
+    }
+    const visited = new Set();
     const visit = (value) => {
-        if (!value || typeof value !== 'object')
-            return;
-        if (Array.isArray(value)) {
-            for (const child of value)
-                visit(child);
+        if (!value || typeof value !== 'object' || Array.isArray(value) || visited.has(value)) {
             return;
         }
+        visited.add(value);
         const record = value;
         const ref = record['$ref'];
         if (typeof ref === 'string') {
-            record['$ref'] = refReplacements.get(ref) ?? ref;
+            const replacement = refReplacements.get(ref);
+            if (replacement !== undefined && replacement !== ref) {
+                record['$ref'] = replacement;
+            }
         }
-        for (const child of Object.values(record))
-            visit(child);
+        (0, transform_1.forEachJSONSchemaChild)(record, [], visit);
     };
     visit(schema);
     return schema;
 }
 function getZodV3RootName(name, schemaDefinitions) {
+    if (!schemaDefinitions) {
+        return name;
+    }
     let rootName = name;
-    while (schemaDefinitions && Object.prototype.hasOwnProperty.call(schemaDefinitions, rootName)) {
+    while ((0, values_1.hasOwn)(schemaDefinitions, rootName)) {
         rootName = `${rootName}_root`;
     }
     return rootName;
 }
 function zodV3ToJsonSchema(schema, options) {
+    (0, zod_v3_strict_schema_1.assertSupportedZodV3Schema)(schema, options.schemaDefinitions);
     const rootName = getZodV3RootName(options.name, options.schemaDefinitions);
     const jsonSchema = (0, zod_to_json_schema_1.zodToJsonSchema)(schema, {
         openaiStrictMode: true,
@@ -58,11 +67,13 @@ function zodV3ToJsonSchema(schema, options) {
         nameStrategy: 'duplicate-ref',
         $refStrategy: 'extract-to-root',
         nullableStrategy: 'property',
-        ...(options.schemaDefinitions ?
-            { definitions: options.schemaDefinitions }
+        ...(options.schemaDefinitions
+            ? { definitions: options.schemaDefinitions }
             : undefined),
     });
-    return escapeSchemaDefinitionRefs(jsonSchema, options.schemaDefinitions);
+    const escapedSchema = escapeSchemaDefinitionRefs(jsonSchema, options.schemaDefinitions);
+    (0, zod_v3_strict_schema_1.assertJSONSerializableSchema)(escapedSchema);
+    return escapedSchema;
 }
 function zodV4ToJsonSchema(schema, options = {}) {
     const metadata = options.schemaDefinitions ? z4.registry() : undefined;
@@ -106,10 +117,14 @@ function isZodV4(zodObject) {
     return '_zod' in zodObject;
 }
 function parseZodObject(zodObject, content) {
-    const parsed = JSON.parse(content);
+    const parsed = (0, parser_1.parseResponseFormatContent)({ type: 'json_schema', $parseRaw: undefined }, content);
     const parser = zodObject.parse;
     if (typeof parser === 'function') {
-        return parser.call(zodObject, parsed);
+        const result = parser.call(zodObject, parsed);
+        if (!isZodV4(zodObject)) {
+            (0, zod_v3_strict_schema_1.assertJSONSerializableSchema)(result);
+        }
+        return result;
     }
     return z4.parse(zodObject, parsed);
 }
@@ -149,6 +164,12 @@ function parseZodObject(zodObject, content) {
  *
  * This can be passed directly to the `.create()` method but will not
  * result in any automatic parsing, you'll have to parse the response yourself.
+ *
+ * Supports schemas from `zod/v3`, `zod/v4`, and `zod/v4-mini`.
+ *
+ * @param zodObject Zod schema used to generate and validate structured model output.
+ * @param name Model-visible name of the generated strict JSON Schema.
+ * @param props Optional response-format metadata and named reusable schema definitions.
  */
 function zodResponseFormat(zodObject, name, props) {
     const zodSchema = zodObject;
@@ -160,12 +181,33 @@ function zodResponseFormat(zodObject, name, props) {
             ...responseFormatProps,
             name,
             strict: true,
-            schema: isZodV4(zodSchema) ?
-                zodV4ToJsonSchema(zodSchema, { schemaDefinitions })
+            schema: isZodV4(zodSchema)
+                ? zodV4ToJsonSchema(zodSchema, { schemaDefinitions })
                 : zodV3ToJsonSchema(zodSchema, { name, schemaDefinitions }),
         },
     }, (content) => parseZodObject(zodObject, content));
 }
+/**
+ * Creates a strict Responses API text format that validates output with a Zod schema.
+ *
+ * Pass the returned format as `text.format` to `client.responses.parse()` to
+ * populate `response.output_parsed` with the schema's inferred output type.
+ * Calling `responses.create()` with the same format does not enable automatic
+ * parsing. Schemas from `zod/v3`, `zod/v4`, and `zod/v4-mini` are supported.
+ *
+ * ```ts
+ * const response = await client.responses.parse({
+ *   model: 'gpt-5.5',
+ *   input: 'Describe the weather.',
+ *   text: { format: zodTextFormat(Weather, 'weather') },
+ * });
+ * console.log(response.output_parsed);
+ * ```
+ *
+ * @param zodObject Zod schema used to generate and validate structured model output.
+ * @param name Model-visible name of the generated strict JSON Schema.
+ * @param props Optional model-visible text-format metadata, such as a description.
+ */
 function zodTextFormat(zodObject, name, props) {
     const zodSchema = zodObject;
     return (0, parser_1.makeParseableTextFormat)({
@@ -180,6 +222,12 @@ function zodTextFormat(zodObject, name, props) {
  * Creates a chat completion `function` tool that can be invoked
  * automatically by the chat completion `.runTools()` method or automatically
  * parsed by `.parse()` / `.stream()`.
+ *
+ * Arguments are converted to strict JSON Schema and validated with the supplied
+ * Zod schema before the optional callback receives them.
+ *
+ * @param options Model-visible function name, Zod parameter schema, description,
+ * and optional callback used by `chat.completions.runTools()`.
  */
 function zodFunction(options) {
     const zodSchema = options.parameters;
@@ -188,8 +236,8 @@ function zodFunction(options) {
         type: 'function',
         function: {
             name: options.name,
-            parameters: isZodV4(zodSchema) ?
-                zodV4ToJsonSchema(zodSchema)
+            parameters: isZodV4(zodSchema)
+                ? zodV4ToJsonSchema(zodSchema)
                 : zodV3ToJsonSchema(zodSchema, { name: options.name }),
             strict: true,
             ...(options.description ? { description: options.description } : undefined),
@@ -199,13 +247,24 @@ function zodFunction(options) {
         parser: (args) => parseZodObject(options.parameters, args),
     });
 }
+/**
+ * Creates a strict Responses API function tool with Zod-validated arguments.
+ *
+ * Passing this tool to `client.responses.parse()` populates
+ * `function_call.parsed_arguments` with the inferred schema output. Parsing a
+ * response does not invoke the optional callback or submit tool results; the
+ * application remains responsible for its function-execution loop.
+ *
+ * @param options Model-visible function name, Zod parameter schema, optional
+ * description, and optional callback metadata.
+ */
 function zodResponsesFunction(options) {
     const zodSchema = options.parameters;
     return (0, ResponsesParser_1.makeParseableResponseTool)({
         type: 'function',
         name: options.name,
-        parameters: isZodV4(zodSchema) ?
-            zodV4ToJsonSchema(zodSchema)
+        parameters: isZodV4(zodSchema)
+            ? zodV4ToJsonSchema(zodSchema)
             : zodV3ToJsonSchema(zodSchema, { name: options.name }),
         strict: true,
         ...(options.description ? { description: options.description } : undefined),
@@ -222,14 +281,16 @@ function zodResponsesFunction(options) {
  *
  * This helper only creates the tool definition. Parse function-call arguments
  * from Realtime events with the original Zod schema.
+ *
+ * @param options Model-visible function name, Zod parameter schema, and description.
  */
 function zodRealtimeFunction(options) {
     const zodSchema = options.parameters;
     return {
         type: 'function',
         name: options.name,
-        parameters: isZodV4(zodSchema) ?
-            zodV4ToNonStrictJsonSchema(zodSchema)
+        parameters: isZodV4(zodSchema)
+            ? zodV4ToNonStrictJsonSchema(zodSchema)
             : zodV3ToNonStrictJsonSchema(zodSchema, { name: options.name }),
         ...(options.description ? { description: options.description } : undefined),
     };

package/helpers/zod.js.map

@@ -1 +1 @@
-{"version":3,"file":"zod.js","sourceRoot":"","sources":["../src/helpers/zod.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"zod.js","sourceRoot":"","sources":["../src/helpers/zod.ts"],"names":[],"mappings":"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"}

package/helpers/zod.mjs

@@ -1,13 +1,15 @@
 import * as z4 from 'zod/v4';
-import { makeParseableResponseFormat, makeParseableTextFormat, makeParseableTool, } from "../lib/parser.mjs";
+import { makeParseableResponseFormat, makeParseableTextFormat, makeParseableTool, parseResponseFormatContent, } from "../lib/parser.mjs";
 import { zodToJsonSchema as _zodToJsonSchema } from "../_vendor/zod-to-json-schema/index.mjs";
 import { makeParseableResponseTool } from "../lib/ResponsesParser.mjs";
-import { toStrictJsonSchema } from "../lib/transform.mjs";
+import { forEachJSONSchemaChild, toStrictJsonSchema } from "../lib/transform.mjs";
+import { hasOwn } from "../internal/utils/values.mjs";
+import { assertJSONSerializableSchema, assertSupportedZodV3Schema } from "./zod-v3-strict-schema.mjs";
 function encodeSchemaDefinitionRefToken(token) {
     return encodeURIComponent(token.replace(/~/g, '~0').replace(/\//g, '~1'));
 }
 function validateSchemaDefinitions(schemaDefinitions) {
-    if (schemaDefinitions && Object.prototype.hasOwnProperty.call(schemaDefinitions, '__proto__')) {
+    if (schemaDefinitions && hasOwn(schemaDefinitions, '__proto__')) {
         throw new Error('schemaDefinitions cannot include "__proto__" as a definition name');
     }
 }
@@ -16,33 +18,40 @@ function escapeSchemaDefinitionRefs(schema, schemaDefinitions) {
         `#/definitions/${name}`,
         `#/definitions/${encodeSchemaDefinitionRefToken(name)}`,
     ]));
+    if (refReplacements.size === 0) {
+        return schema;
+    }
+    const visited = new Set();
     const visit = (value) => {
-        if (!value || typeof value !== 'object')
-            return;
-        if (Array.isArray(value)) {
-            for (const child of value)
-                visit(child);
+        if (!value || typeof value !== 'object' || Array.isArray(value) || visited.has(value)) {
             return;
         }
+        visited.add(value);
         const record = value;
         const ref = record['$ref'];
         if (typeof ref === 'string') {
-            record['$ref'] = refReplacements.get(ref) ?? ref;
+            const replacement = refReplacements.get(ref);
+            if (replacement !== undefined && replacement !== ref) {
+                record['$ref'] = replacement;
+            }
         }
-        for (const child of Object.values(record))
-            visit(child);
+        forEachJSONSchemaChild(record, [], visit);
     };
     visit(schema);
     return schema;
 }
 function getZodV3RootName(name, schemaDefinitions) {
+    if (!schemaDefinitions) {
+        return name;
+    }
     let rootName = name;
-    while (schemaDefinitions && Object.prototype.hasOwnProperty.call(schemaDefinitions, rootName)) {
+    while (hasOwn(schemaDefinitions, rootName)) {
         rootName = `${rootName}_root`;
     }
     return rootName;
 }
 function zodV3ToJsonSchema(schema, options) {
+    assertSupportedZodV3Schema(schema, options.schemaDefinitions);
     const rootName = getZodV3RootName(options.name, options.schemaDefinitions);
     const jsonSchema = _zodToJsonSchema(schema, {
         openaiStrictMode: true,
@@ -50,11 +59,13 @@ function zodV3ToJsonSchema(schema, options) {
         nameStrategy: 'duplicate-ref',
         $refStrategy: 'extract-to-root',
         nullableStrategy: 'property',
-        ...(options.schemaDefinitions ?
-            { definitions: options.schemaDefinitions }
+        ...(options.schemaDefinitions
+            ? { definitions: options.schemaDefinitions }
             : undefined),
     });
-    return escapeSchemaDefinitionRefs(jsonSchema, options.schemaDefinitions);
+    const escapedSchema = escapeSchemaDefinitionRefs(jsonSchema, options.schemaDefinitions);
+    assertJSONSerializableSchema(escapedSchema);
+    return escapedSchema;
 }
 function zodV4ToJsonSchema(schema, options = {}) {
     const metadata = options.schemaDefinitions ? z4.registry() : undefined;
@@ -98,10 +109,14 @@ function isZodV4(zodObject) {
     return '_zod' in zodObject;
 }
 function parseZodObject(zodObject, content) {
-    const parsed = JSON.parse(content);
+    const parsed = parseResponseFormatContent({ type: 'json_schema', $parseRaw: undefined }, content);
     const parser = zodObject.parse;
     if (typeof parser === 'function') {
-        return parser.call(zodObject, parsed);
+        const result = parser.call(zodObject, parsed);
+        if (!isZodV4(zodObject)) {
+            assertJSONSerializableSchema(result);
+        }
+        return result;
     }
     return z4.parse(zodObject, parsed);
 }
@@ -141,6 +156,12 @@ function parseZodObject(zodObject, content) {
  *
  * This can be passed directly to the `.create()` method but will not
  * result in any automatic parsing, you'll have to parse the response yourself.
+ *
+ * Supports schemas from `zod/v3`, `zod/v4`, and `zod/v4-mini`.
+ *
+ * @param zodObject Zod schema used to generate and validate structured model output.
+ * @param name Model-visible name of the generated strict JSON Schema.
+ * @param props Optional response-format metadata and named reusable schema definitions.
  */
 export function zodResponseFormat(zodObject, name, props) {
     const zodSchema = zodObject;
@@ -152,12 +173,33 @@ export function zodResponseFormat(zodObject, name, props) {
             ...responseFormatProps,
             name,
             strict: true,
-            schema: isZodV4(zodSchema) ?
-                zodV4ToJsonSchema(zodSchema, { schemaDefinitions })
+            schema: isZodV4(zodSchema)
+                ? zodV4ToJsonSchema(zodSchema, { schemaDefinitions })
                 : zodV3ToJsonSchema(zodSchema, { name, schemaDefinitions }),
         },
     }, (content) => parseZodObject(zodObject, content));
 }
+/**
+ * Creates a strict Responses API text format that validates output with a Zod schema.
+ *
+ * Pass the returned format as `text.format` to `client.responses.parse()` to
+ * populate `response.output_parsed` with the schema's inferred output type.
+ * Calling `responses.create()` with the same format does not enable automatic
+ * parsing. Schemas from `zod/v3`, `zod/v4`, and `zod/v4-mini` are supported.
+ *
+ * ```ts
+ * const response = await client.responses.parse({
+ *   model: 'gpt-5.5',
+ *   input: 'Describe the weather.',
+ *   text: { format: zodTextFormat(Weather, 'weather') },
+ * });
+ * console.log(response.output_parsed);
+ * ```
+ *
+ * @param zodObject Zod schema used to generate and validate structured model output.
+ * @param name Model-visible name of the generated strict JSON Schema.
+ * @param props Optional model-visible text-format metadata, such as a description.
+ */
 export function zodTextFormat(zodObject, name, props) {
     const zodSchema = zodObject;
     return makeParseableTextFormat({
@@ -172,6 +214,12 @@ export function zodTextFormat(zodObject, name, props) {
  * Creates a chat completion `function` tool that can be invoked
  * automatically by the chat completion `.runTools()` method or automatically
  * parsed by `.parse()` / `.stream()`.
+ *
+ * Arguments are converted to strict JSON Schema and validated with the supplied
+ * Zod schema before the optional callback receives them.
+ *
+ * @param options Model-visible function name, Zod parameter schema, description,
+ * and optional callback used by `chat.completions.runTools()`.
  */
 export function zodFunction(options) {
     const zodSchema = options.parameters;
@@ -180,8 +228,8 @@ export function zodFunction(options) {
         type: 'function',
         function: {
             name: options.name,
-            parameters: isZodV4(zodSchema) ?
-                zodV4ToJsonSchema(zodSchema)
+            parameters: isZodV4(zodSchema)
+                ? zodV4ToJsonSchema(zodSchema)
                 : zodV3ToJsonSchema(zodSchema, { name: options.name }),
             strict: true,
             ...(options.description ? { description: options.description } : undefined),
@@ -191,13 +239,24 @@ export function zodFunction(options) {
         parser: (args) => parseZodObject(options.parameters, args),
     });
 }
+/**
+ * Creates a strict Responses API function tool with Zod-validated arguments.
+ *
+ * Passing this tool to `client.responses.parse()` populates
+ * `function_call.parsed_arguments` with the inferred schema output. Parsing a
+ * response does not invoke the optional callback or submit tool results; the
+ * application remains responsible for its function-execution loop.
+ *
+ * @param options Model-visible function name, Zod parameter schema, optional
+ * description, and optional callback metadata.
+ */
 export function zodResponsesFunction(options) {
     const zodSchema = options.parameters;
     return makeParseableResponseTool({
         type: 'function',
         name: options.name,
-        parameters: isZodV4(zodSchema) ?
-            zodV4ToJsonSchema(zodSchema)
+        parameters: isZodV4(zodSchema)
+            ? zodV4ToJsonSchema(zodSchema)
             : zodV3ToJsonSchema(zodSchema, { name: options.name }),
         strict: true,
         ...(options.description ? { description: options.description } : undefined),
@@ -214,14 +273,16 @@ export function zodResponsesFunction(options) {
  *
  * This helper only creates the tool definition. Parse function-call arguments
  * from Realtime events with the original Zod schema.
+ *
+ * @param options Model-visible function name, Zod parameter schema, and description.
  */
 export function zodRealtimeFunction(options) {
     const zodSchema = options.parameters;
     return {
         type: 'function',
         name: options.name,
-        parameters: isZodV4(zodSchema) ?
-            zodV4ToNonStrictJsonSchema(zodSchema)
+        parameters: isZodV4(zodSchema)
+            ? zodV4ToNonStrictJsonSchema(zodSchema)
             : zodV3ToNonStrictJsonSchema(zodSchema, { name: options.name }),
         ...(options.description ? { description: options.description } : undefined),
     };