@rebyteai/agent-sdk 0.2.0

package/helpers/zod.d.ts

@@ -0,0 +1,196 @@
+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.
+     * Use this to reuse large shared schemas instead of inlining them at every occurrence.
+     */
+    schemaDefinitions?: ZodSchemaDefinitions | undefined;
+};
+/**
+ * Creates a chat completion `JSONSchema` response format object from
+ * the given Zod schema.
+ *
+ * If this is passed to the `.parse()`, `.stream()` or `.runTools()`
+ * chat completion methods then the response message will contain a
+ * `.parsed` property that is the result of parsing the content with
+ * the given Zod object.
+ *
+ * ```ts
+ * const completion = await client.chat.completions.parse({
+ *    model: 'gpt-4o-2024-08-06',
+ *    messages: [
+ *      { role: 'system', content: 'You are a helpful math tutor.' },
+ *      { role: 'user', content: 'solve 8x + 31 = 2' },
+ *    ],
+ *    response_format: zodResponseFormat(
+ *      z.object({
+ *        steps: z.array(z.object({
+ *          explanation: z.string(),
+ *          answer: z.string(),
+ *        })),
+ *        final_answer: z.string(),
+ *      }),
+ *      'math_answer',
+ *    ),
+ *  });
+ *  const message = completion.choices[0]?.message;
+ *  if (message?.parsed) {
+ *    console.log(message.parsed);
+ *    console.log(message.parsed.final_answer);
+ * }
+ * ```
+ *
+ * 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>>;
+/** Model-facing settings and an optional execution callback for a Zod function tool. */
+interface ZodFunctionOptions<Parameters extends ZodTypeLike> {
+    /** 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;
+}
+/** A Zod function tool retaining its inferred argument and callback types. */
+type ZodFunctionTool<Parameters extends ZodTypeLike, Callback extends ZodFunctionOptions<Parameters>['function']> = 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 availability determines whether the tool can be executed. */
+    function: Callback;
+}>;
+/**
+ * Creates a chat completion `function` tool that can be invoked automatically
+ * by `.runTools()` or parsed by `.parse()` / `.stream()`.
+ *
+ * Arguments are converted to strict JSON Schema and validated with the supplied
+ * Zod schema before the callback receives them.
+ *
+ * @param options Model-visible function name, Zod parameter schema, description,
+ * and callback used by `chat.completions.runTools()`.
+ */
+export declare function zodFunction<Parameters extends ZodTypeLike>(options: ZodFunctionOptions<Parameters> & {
+    /** Callback invoked with validated arguments by chat `runTools()`. */
+    function: NonNullable<ZodFunctionOptions<Parameters>['function']>;
+}): ZodFunctionTool<Parameters, NonNullable<ZodFunctionOptions<Parameters>['function']>>;
+/**
+ * Creates a strict chat completion function tool for `.parse()` / `.stream()`.
+ * Without a guaranteed callback, the tool cannot be executed by `.runTools()`.
+ *
+ * @param options Model-visible function details and an optional callback.
+ */
+export declare function zodFunction<Parameters extends ZodTypeLike>(options: ZodFunctionOptions<Parameters>): ZodFunctionTool<Parameters, ZodFunctionOptions<Parameters>['function']>;
+/**
+ * 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;
+}>;
+/**
+ * Creates a Realtime API `function` tool definition from the given Zod schema.
+ *
+ * Unlike {@link zodResponsesFunction}, this helper does not add `strict`
+ * because Realtime function tools do not support that field.
+ *
+ * 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 {};
+//# sourceMappingURL=zod.d.ts.map

package/helpers/zod.d.ts.map

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

package/helpers/zod.js

@@ -0,0 +1,305 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.zodResponseFormat = zodResponseFormat;
+exports.zodTextFormat = zodTextFormat;
+exports.zodFunction = zodFunction;
+exports.zodResponsesFunction = zodResponsesFunction;
+exports.zodRealtimeFunction = zodRealtimeFunction;
+const tslib_1 = require("../internal/tslib.js");
+const z4 = tslib_1.__importStar(require("zod/v4"));
+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 && (0, values_1.hasOwn)(schemaDefinitions, '__proto__')) {
+        throw new Error('schemaDefinitions cannot include "__proto__" as a definition name');
+    }
+}
+function escapeSchemaDefinitionRefs(schema, definitionNames) {
+    const refReplacements = new Map([...definitionNames].map(([id, name]) => [
+        `#/definitions/${id}`,
+        `#/definitions/${encodeSchemaDefinitionRefToken(name)}`,
+    ]));
+    if (refReplacements.size === 0) {
+        return schema;
+    }
+    const visited = new Set();
+    const visit = (value) => {
+        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') {
+            const replacement = refReplacements.get(ref);
+            if (replacement !== undefined && replacement !== ref) {
+                record['$ref'] = replacement;
+            }
+        }
+        (0, transform_1.forEachJSONSchemaChild)(record, [], visit);
+    };
+    visit(schema);
+    return schema;
+}
+function getZodV3RootName(name, schemaDefinitions) {
+    if (!schemaDefinitions) {
+        return name;
+    }
+    let rootName = name;
+    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,
+        name: rootName,
+        nameStrategy: 'duplicate-ref',
+        $refStrategy: 'extract-to-root',
+        nullableStrategy: 'property',
+        ...(options.schemaDefinitions
+            ? { definitions: options.schemaDefinitions }
+            : undefined),
+    });
+    const escapedSchema = escapeSchemaDefinitionRefs(jsonSchema, new Map(Object.keys(options.schemaDefinitions ?? {}).map((name) => [name, name])));
+    (0, zod_v3_strict_schema_1.assertJSONSerializableSchema)(escapedSchema);
+    return escapedSchema;
+}
+function zodV4ToJsonSchema(schema, options = {}) {
+    const metadata = options.schemaDefinitions ? z4.registry() : undefined;
+    const definitionNames = new Map();
+    for (const [name, definition] of Object.entries(options.schemaDefinitions ?? {})) {
+        // Avoid `/` and `~` so Zod versions that escape JSON Pointer tokens emit the same IDs.
+        const id = encodeURIComponent(name).replace(/~/g, '%7E');
+        definitionNames.set(id, name);
+        metadata?.add(definition, { id });
+    }
+    const jsonSchema = z4.toJSONSchema(schema, {
+        target: 'draft-7',
+        ...(metadata ? { metadata } : undefined),
+        override: ({ zodSchema, jsonSchema, path }) => {
+            const def = zodSchema._zod.def;
+            if (def.type === 'object' && (0, values_1.hasOwn)(def.shape, '__proto__')) {
+                const propertyPath = [...path, 'properties', '__proto__']
+                    .map((part) => encodeSchemaDefinitionRefToken(String(part)))
+                    .join('/');
+                throw new Error(`Zod field at \`#/${propertyPath}\` uses unsupported property name \`__proto__\`, which Zod omits from parsed output.`);
+            }
+            if (def.type === 'union' && 'discriminator' in def && Array.isArray(jsonSchema.oneOf)) {
+                if (jsonSchema.anyOf !== undefined) {
+                    throw new Error('Zod discriminated union generated both `anyOf` and `oneOf`, which cannot be represented in an OpenAI strict schema');
+                }
+                // Discriminator values are mutually exclusive, so anyOf preserves the
+                // union while staying inside the API's supported JSON Schema subset.
+                jsonSchema.anyOf = jsonSchema.oneOf;
+                delete jsonSchema.oneOf;
+            }
+        },
+    });
+    const escapedSchema = escapeSchemaDefinitionRefs(jsonSchema, definitionNames);
+    if (escapedSchema.definitions) {
+        escapedSchema.definitions = Object.fromEntries(Object.entries(escapedSchema.definitions).map(([id, definition]) => [
+            definitionNames.get(id) ?? id,
+            definition,
+        ]));
+    }
+    return (0, transform_1.toStrictJsonSchema)(escapedSchema);
+}
+function zodV3ToNonStrictJsonSchema(schema, options) {
+    return (0, zod_to_json_schema_1.zodToJsonSchema)(schema, {
+        name: options.name,
+        nameStrategy: 'duplicate-ref',
+        $refStrategy: 'extract-to-root',
+        pipeStrategy: 'input',
+    });
+}
+function zodV4ToNonStrictJsonSchema(schema) {
+    return z4.toJSONSchema(schema, {
+        target: 'draft-7',
+        io: 'input',
+    });
+}
+function isZodV4(zodObject) {
+    return '_zod' in zodObject;
+}
+function parseZodObject(zodObject, content) {
+    const parsed = (0, parser_1.parseResponseFormatContent)({ type: 'json_schema', $parseRaw: undefined }, content);
+    const parser = zodObject.parse;
+    if (typeof parser === 'function') {
+        const result = parser.call(zodObject, parsed);
+        if (!isZodV4(zodObject)) {
+            (0, zod_v3_strict_schema_1.assertJSONSerializableSchema)(result);
+        }
+        return result;
+    }
+    return z4.parse(zodObject, parsed);
+}
+/**
+ * Creates a chat completion `JSONSchema` response format object from
+ * the given Zod schema.
+ *
+ * If this is passed to the `.parse()`, `.stream()` or `.runTools()`
+ * chat completion methods then the response message will contain a
+ * `.parsed` property that is the result of parsing the content with
+ * the given Zod object.
+ *
+ * ```ts
+ * const completion = await client.chat.completions.parse({
+ *    model: 'gpt-4o-2024-08-06',
+ *    messages: [
+ *      { role: 'system', content: 'You are a helpful math tutor.' },
+ *      { role: 'user', content: 'solve 8x + 31 = 2' },
+ *    ],
+ *    response_format: zodResponseFormat(
+ *      z.object({
+ *        steps: z.array(z.object({
+ *          explanation: z.string(),
+ *          answer: z.string(),
+ *        })),
+ *        final_answer: z.string(),
+ *      }),
+ *      'math_answer',
+ *    ),
+ *  });
+ *  const message = completion.choices[0]?.message;
+ *  if (message?.parsed) {
+ *    console.log(message.parsed);
+ *    console.log(message.parsed.final_answer);
+ * }
+ * ```
+ *
+ * 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;
+    const { schemaDefinitions, ...responseFormatProps } = props ?? {};
+    validateSchemaDefinitions(schemaDefinitions);
+    return (0, parser_1.makeParseableResponseFormat)({
+        type: 'json_schema',
+        json_schema: {
+            ...responseFormatProps,
+            name,
+            strict: true,
+            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)({
+        type: 'json_schema',
+        ...props,
+        name,
+        strict: true,
+        schema: isZodV4(zodSchema) ? zodV4ToJsonSchema(zodSchema) : zodV3ToJsonSchema(zodSchema, { name }),
+    }, (content) => parseZodObject(zodObject, content));
+}
+/** Builds a strict Chat Completions function tool from the supplied Zod schema. */
+function zodFunction(options) {
+    const parameters = options.parameters;
+    const zodSchema = parameters;
+    return (0, parser_1.makeParseableTool)({
+        type: 'function',
+        function: {
+            name: options.name,
+            parameters: isZodV4(zodSchema)
+                ? zodV4ToJsonSchema(zodSchema)
+                : zodV3ToJsonSchema(zodSchema, { name: options.name }),
+            strict: true,
+            ...(options.description ? { description: options.description } : undefined),
+        },
+    }, {
+        callback: options.function,
+        parser: (args) => parseZodObject(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 parameters = options.parameters;
+    const zodSchema = parameters;
+    return (0, ResponsesParser_1.makeParseableResponseTool)({
+        type: 'function',
+        name: options.name,
+        parameters: isZodV4(zodSchema)
+            ? zodV4ToJsonSchema(zodSchema)
+            : zodV3ToJsonSchema(zodSchema, { name: options.name }),
+        strict: true,
+        ...(options.description ? { description: options.description } : undefined),
+    }, {
+        callback: options.function,
+        parser: (args) => parseZodObject(parameters, args),
+    });
+}
+/**
+ * Creates a Realtime API `function` tool definition from the given Zod schema.
+ *
+ * Unlike {@link zodResponsesFunction}, this helper does not add `strict`
+ * because Realtime function tools do not support that field.
+ *
+ * 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)
+            : zodV3ToNonStrictJsonSchema(zodSchema, { name: options.name }),
+        ...(options.description ? { description: options.description } : undefined),
+    };
+}
+//# sourceMappingURL=zod.js.map

package/helpers/zod.js.map

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