@rebyteai/agent-sdk 0.2.0

package/lib/parser.d.ts

@@ -0,0 +1,150 @@
+import type { ChatCompletion, ChatCompletionCreateParams, ChatCompletionCreateParamsBase, ChatCompletionFunctionTool, ChatCompletionMessage, ChatCompletionMessageFunctionToolCall, ChatCompletionMessageToolCall, ChatCompletionStreamingToolRunnerParams, ChatCompletionStreamingToolRunnerParamsWithContext, ChatCompletionStreamParams, ChatCompletionToolRunnerParams, ChatCompletionToolRunnerParamsWithContext, ParsedChatCompletion } from "../resources/chat/completions.js";
+import type { ResponseFormatTextJSONSchemaConfig } from "../resources/responses/responses.js";
+import type { ResponseFormatJSONSchema } from "../resources/shared.js";
+/** Chat completion creation, parsing, streaming, or tool-runner request parameters. */
+type AnyChatCompletionCreateParams = ChatCompletionCreateParams | ChatCompletionToolRunnerParams<any> | ChatCompletionToolRunnerParamsWithContext<any, any> | ChatCompletionStreamingToolRunnerParams<any> | ChatCompletionStreamingToolRunnerParamsWithContext<any, any> | ChatCompletionStreamParams;
+/** Extracts the element type from an array while preserving non-array values. */
+type Unpacked<T> = T extends (infer U)[] ? U : T;
+/** One optional tool definition accepted by a chat completion request. */
+type ToolCall = Unpacked<ChatCompletionCreateParamsBase['tools']>;
+/** Returns whether an optional chat completion tool contains a function-tool definition. */
+export declare function isChatCompletionFunctionTool(tool: ToolCall): tool is ChatCompletionFunctionTool;
+/** Infers parsed output for each member of a possibly optional response-format union. */
+type ParsedResponseFormat<Format> = [Format] extends [never] ? null : Format extends AutoParseableResponseFormat<infer ParsedT> ? ParsedT : Format extends ResponseFormatJSONSchema ? unknown : null;
+/**
+ * Resolves the type of `message.parsed` / `content[].parsed` for the given params.
+ *
+ * This must stay in sync with {@link isParseableResponseFormat} and
+ * {@link parseResponseFormatContent}: formats built by an SDK helper carry their
+ * parsed type in the brand, while a raw `{ type: 'json_schema' }` format is parsed
+ * with `JSON.parse()` and so can only be described as `unknown`.
+ */
+export type ExtractParsedContentFromParams<Params extends AnyChatCompletionCreateParams> = ParsedResponseFormat<Params['response_format']>;
+/** A Chat Completions JSON Schema response format with an attached structured-output parser. */
+export type AutoParseableResponseFormat<ParsedT> = ResponseFormatJSONSchema & {
+    /** Type-only marker used to infer the parser's output; this property does not exist at runtime. */
+    __output: ParsedT;
+    /** Non-enumerable SDK marker identifying a response format with an attached parser. */
+    $brand: 'auto-parseable-response-format';
+    /** Parses the completed raw assistant text into the response format's output type. */
+    $parseRaw(content: string): ParsedT;
+};
+/** Copies a JSON Schema response format and attaches a non-enumerable structured-output parser. */
+export declare function makeParseableResponseFormat<ParsedT>(response_format: ResponseFormatJSONSchema, parser: (content: string) => ParsedT): AutoParseableResponseFormat<ParsedT>;
+/** A Responses API JSON Schema text format with an attached structured-output parser. */
+export type AutoParseableTextFormat<ParsedT> = ResponseFormatTextJSONSchemaConfig & {
+    /** Type-only marker used to infer the parser's output; this property does not exist at runtime. */
+    __output: ParsedT;
+    /** Non-enumerable SDK marker identifying a text format with an attached parser. */
+    $brand: 'auto-parseable-response-format';
+    /** Parses completed output text into the text format's structured output type. */
+    $parseRaw(content: string): ParsedT;
+};
+/** Copies a Responses API text format and attaches a non-enumerable structured-output parser. */
+export declare function makeParseableTextFormat<ParsedT>(response_format: ResponseFormatTextJSONSchemaConfig, parser: (content: string) => ParsedT): AutoParseableTextFormat<ParsedT>;
+/**
+ * Whether the given format was built by an SDK helper (e.g. `zodResponseFormat()`)
+ * and therefore carries its own `$parseRaw` callback.
+ *
+ * Prefer {@link isParseableResponseFormat} when deciding whether output should be
+ * parsed at all; raw `{ type: 'json_schema' }` formats are parsed too, but are not
+ * branded.
+ */
+export declare function isAutoParsableResponseFormat<ParsedT>(response_format: any): response_format is AutoParseableResponseFormat<ParsedT>;
+/**
+ * The canonical definition of an auto-parseable response format, covering both the
+ * Chat Completions `response_format` and the Responses `text.format` shapes.
+ *
+ * Every gate that decides whether output should be parsed must go through this
+ * predicate so the runtime, the streaming events and
+ * {@link ExtractParsedContentFromParams} cannot drift apart.
+ */
+export declare function isParseableResponseFormat(format: unknown): boolean;
+/**
+ * The canonical parser for auto-parseable response formats. This is the only place
+ * that chooses between an existing `$parseRaw` callback and generic `JSON.parse()`.
+ *
+ * Returns `null` for formats that are not auto-parseable.
+ */
+export declare function parseResponseFormatContent<ParsedT>(format: unknown, content: string): ParsedT | null;
+/** Type-level details used to infer a chat function tool's parser and execution callback. */
+type ToolOptions = {
+    /** Model-visible function name used to match generated tool calls. */
+    name: string;
+    /** Parsed argument value accepted by the optional execution callback. */
+    arguments: any;
+    /** Optional callback invoked by chat completion tool-running helpers. */
+    function?: ((args: any) => any) | undefined;
+};
+/** A Chat Completions function tool with an argument parser and optional executable callback. */
+export type AutoParseableTool<OptionsT extends ToolOptions, HasFunction = OptionsT['function'] extends (...args: never[]) => unknown ? true : false> = ChatCompletionFunctionTool & {
+    /** Type-only marker for parsed tool arguments; this property does not exist at runtime. */
+    __arguments: OptionsT['arguments'];
+    /** Type-only marker for the tool name; this property does not exist at runtime. */
+    __name: OptionsT['name'];
+    /** Type-only marker indicating whether a runnable callback was supplied. */
+    __hasFunction: HasFunction;
+    /** Non-enumerable SDK marker identifying a tool with an attached argument parser. */
+    $brand: 'auto-parseable-tool';
+    /** Optional runnable callback used by `.runTools()` after arguments are parsed. */
+    $callback: ((args: OptionsT['arguments']) => any) | undefined;
+    /** Parses the raw JSON argument string into the callback's typed argument value. */
+    $parseRaw(args: string): OptionsT['arguments'];
+};
+/** Parser and optional callback supplied when creating a custom chat function tool. */
+type ToolParserOptions<OptionsT extends ToolOptions> = {
+    /** Converts the raw JSON argument string into the tool's typed argument value. */
+    parser: (content: string) => OptionsT['arguments'];
+    /** Optional callback invoked by a chat completion tool runner. */
+    callback: ((args: OptionsT['arguments']) => any) | undefined;
+};
+/** Creates a runnable function tool with a guaranteed execution callback. */
+export declare function makeParseableTool<OptionsT extends ToolOptions>(tool: ChatCompletionFunctionTool, options: ToolParserOptions<OptionsT> & {
+    /** Callback invoked with the parsed tool arguments. */
+    callback: (args: OptionsT['arguments']) => any;
+}): AutoParseableTool<OptionsT, true>;
+/** Creates a parse-only function tool without an execution callback. */
+export declare function makeParseableTool<OptionsT extends ToolOptions>(tool: ChatCompletionFunctionTool, options: ToolParserOptions<OptionsT> & {
+    /** No execution callback is attached to this tool. */
+    callback: undefined;
+}): AutoParseableTool<OptionsT, false>;
+/** Creates a function tool whose execution callback may be unavailable. */
+export declare function makeParseableTool<OptionsT extends ToolOptions>(tool: ChatCompletionFunctionTool, options: ToolParserOptions<OptionsT>): AutoParseableTool<OptionsT, boolean>;
+/** Returns whether a Chat Completions tool carries the SDK's argument-parser marker. */
+export declare function isAutoParsableTool(tool: any): tool is AutoParseableTool<any>;
+/**
+ * Adds parsed-content fields to a chat completion, invoking parsers only when the
+ * request includes an auto-parseable response format or a strict function tool.
+ */
+export declare function maybeParseChatCompletion<Params extends ChatCompletionCreateParams | null, ParsedT = Params extends null ? null : ExtractParsedContentFromParams<NonNullable<Params>>>(completion: ChatCompletion, params: Params): ParsedChatCompletion<ParsedT>;
+/**
+ * Parses structured assistant content and strict function-tool arguments.
+ *
+ * @throws {LengthFinishReasonError} If generation stopped at its token limit.
+ * @throws {ContentFilterFinishReasonError} If generation stopped because of content filtering.
+ * @throws {OpenAIError} If the completion contains an unsupported tool-call type.
+ */
+export declare function parseChatCompletion<Params extends ChatCompletionCreateParams, ParsedT = ExtractParsedContentFromParams<Params>>(completion: ChatCompletion, params: Params): ParsedChatCompletion<ParsedT>;
+/** Returns whether a tool call matches a strict or auto-parseable function in the request. */
+export declare function shouldParseToolCall(params: ChatCompletionCreateParams | null | undefined, toolCall: {
+    type?: ChatCompletionMessageToolCall['type'];
+    function?: {
+        name?: string;
+    };
+}): boolean;
+/** Returns whether the request contains an auto-parseable response format or strict function tool. */
+export declare function hasAutoParseableInput(params: AnyChatCompletionCreateParams): boolean;
+/**
+ * Narrows completion tool calls to function calls supported by parsing helpers.
+ *
+ * @throws {OpenAIError} If any tool call has a non-function type.
+ */
+export declare function assertToolCallsAreChatCompletionFunctionToolCalls(toolCalls: ChatCompletionMessage['tool_calls']): asserts toolCalls is ChatCompletionMessageFunctionToolCall[];
+/**
+ * Validates strict function tools while preserving supported custom tools.
+ *
+ * @throws {OpenAIError} If a tool is unsupported or a function is missing `strict: true`.
+ */
+export declare function validateInputTools(tools: ChatCompletionCreateParamsBase['tools']): void;
+export {};
+//# sourceMappingURL=parser.d.ts.map

package/lib/parser.d.ts.map

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

package/lib/parser.js

@@ -0,0 +1,263 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isChatCompletionFunctionTool = isChatCompletionFunctionTool;
+exports.makeParseableResponseFormat = makeParseableResponseFormat;
+exports.makeParseableTextFormat = makeParseableTextFormat;
+exports.isAutoParsableResponseFormat = isAutoParsableResponseFormat;
+exports.isParseableResponseFormat = isParseableResponseFormat;
+exports.parseResponseFormatContent = parseResponseFormatContent;
+exports.makeParseableTool = makeParseableTool;
+exports.isAutoParsableTool = isAutoParsableTool;
+exports.maybeParseChatCompletion = maybeParseChatCompletion;
+exports.parseChatCompletion = parseChatCompletion;
+exports.shouldParseToolCall = shouldParseToolCall;
+exports.hasAutoParseableInput = hasAutoParseableInput;
+exports.assertToolCallsAreChatCompletionFunctionToolCalls = assertToolCallsAreChatCompletionFunctionToolCalls;
+exports.validateInputTools = validateInputTools;
+const error_1 = require("../error.js");
+/** Returns whether an optional chat completion tool contains a function-tool definition. */
+function isChatCompletionFunctionTool(tool) {
+    return tool !== undefined && 'function' in tool && tool.function !== undefined;
+}
+/** Copies a JSON Schema response format and attaches a non-enumerable structured-output parser. */
+function makeParseableResponseFormat(response_format, parser) {
+    const obj = { ...response_format, type: 'json_schema' };
+    obj.json_schema = { ...obj.json_schema };
+    delete obj.toJSON;
+    delete obj.json_schema.toJSON;
+    Object.defineProperties(obj, {
+        $brand: {
+            value: 'auto-parseable-response-format',
+            enumerable: false,
+        },
+        $parseRaw: {
+            value: parser,
+            enumerable: false,
+        },
+    });
+    return obj;
+}
+/** Copies a Responses API text format and attaches a non-enumerable structured-output parser. */
+function makeParseableTextFormat(response_format, parser) {
+    const obj = { ...response_format, type: 'json_schema' };
+    delete obj.toJSON;
+    Object.defineProperties(obj, {
+        $brand: {
+            value: 'auto-parseable-response-format',
+            enumerable: false,
+        },
+        $parseRaw: {
+            value: parser,
+            enumerable: false,
+        },
+    });
+    return obj;
+}
+/**
+ * Whether the given format was built by an SDK helper (e.g. `zodResponseFormat()`)
+ * and therefore carries its own `$parseRaw` callback.
+ *
+ * Prefer {@link isParseableResponseFormat} when deciding whether output should be
+ * parsed at all; raw `{ type: 'json_schema' }` formats are parsed too, but are not
+ * branded.
+ */
+function isAutoParsableResponseFormat(response_format) {
+    return response_format?.['$brand'] === 'auto-parseable-response-format';
+}
+/**
+ * The canonical definition of an auto-parseable response format, covering both the
+ * Chat Completions `response_format` and the Responses `text.format` shapes.
+ *
+ * Every gate that decides whether output should be parsed must go through this
+ * predicate so the runtime, the streaming events and
+ * {@link ExtractParsedContentFromParams} cannot drift apart.
+ */
+function isParseableResponseFormat(format) {
+    return isAutoParsableResponseFormat(format) || format?.type === 'json_schema';
+}
+/**
+ * The canonical parser for auto-parseable response formats. This is the only place
+ * that chooses between an existing `$parseRaw` callback and generic `JSON.parse()`.
+ *
+ * Returns `null` for formats that are not auto-parseable.
+ */
+function parseResponseFormatContent(format, content) {
+    if (!isParseableResponseFormat(format)) {
+        return null;
+    }
+    if (typeof format === 'object' &&
+        format !== null &&
+        '$parseRaw' in format &&
+        typeof format.$parseRaw === 'function') {
+        return format.$parseRaw(content);
+    }
+    try {
+        return JSON.parse(content);
+    }
+    catch (error) {
+        if (error instanceof SyntaxError) {
+            throw new SyntaxError('Error reading response: invalid structured output JSON.');
+        }
+        throw error;
+    }
+}
+/** Copies a function tool and attaches non-enumerable parsing and callback metadata. */
+function makeParseableTool(tool, { parser, callback }) {
+    const obj = { ...tool };
+    Object.defineProperties(obj, {
+        $brand: {
+            value: 'auto-parseable-tool',
+            enumerable: false,
+        },
+        $parseRaw: {
+            value: parser,
+            enumerable: false,
+        },
+        $callback: {
+            value: callback,
+            enumerable: false,
+        },
+    });
+    return obj;
+}
+/** Returns whether a Chat Completions tool carries the SDK's argument-parser marker. */
+function isAutoParsableTool(tool) {
+    return tool?.['$brand'] === 'auto-parseable-tool';
+}
+/**
+ * Adds parsed-content fields to a chat completion, invoking parsers only when the
+ * request includes an auto-parseable response format or a strict function tool.
+ */
+function maybeParseChatCompletion(completion, params) {
+    if (!params || !hasAutoParseableInput(params)) {
+        return {
+            ...completion,
+            choices: completion.choices.map((choice) => ({
+                ...choice,
+                message: {
+                    ...choice.message,
+                    parsed: null,
+                    ...(choice.message.tool_calls
+                        ? {
+                            tool_calls: choice.message.tool_calls,
+                        }
+                        : undefined),
+                },
+            })),
+        };
+    }
+    return parseChatCompletion(completion, params);
+}
+/**
+ * Parses structured assistant content and strict function-tool arguments.
+ *
+ * @throws {LengthFinishReasonError} If generation stopped at its token limit.
+ * @throws {ContentFilterFinishReasonError} If generation stopped because of content filtering.
+ * @throws {OpenAIError} If the completion contains an unsupported tool-call type.
+ */
+function parseChatCompletion(completion, params) {
+    const choices = completion.choices.map((choice) => {
+        if (choice.finish_reason === 'length') {
+            throw new error_1.LengthFinishReasonError();
+        }
+        if (choice.finish_reason === 'content_filter') {
+            throw new error_1.ContentFilterFinishReasonError();
+        }
+        return {
+            ...choice,
+            message: {
+                ...choice.message,
+                ...(choice.message.tool_calls
+                    ? {
+                        tool_calls: choice.message.tool_calls?.map((toolCall) => parseToolCall(params, toolCall)) ?? undefined,
+                    }
+                    : undefined),
+                parsed: choice.message.content !== null &&
+                    choice.message.content !== undefined &&
+                    !choice.message.refusal &&
+                    (choice.message.content !== '' ||
+                        (!choice.message.tool_calls?.length && !choice.message.function_call))
+                    ? parseResponseFormat(params, choice.message.content)
+                    : null,
+            },
+        };
+    });
+    return { ...completion, choices };
+}
+function parseResponseFormat(params, content) {
+    return parseResponseFormatContent(params.response_format, content);
+}
+function parseToolCall(params, toolCall) {
+    if (toolCall.type === 'custom') {
+        return toolCall;
+    }
+    if (toolCall.type !== 'function') {
+        const unsupportedType = toolCall.type;
+        throw new error_1.OpenAIError(`Currently only \`function\` and \`custom\` tool calls are supported; Received \`${unsupportedType}\``);
+    }
+    const inputTool = params.tools?.find((inputTool) => isChatCompletionFunctionTool(inputTool) && inputTool.function?.name === toolCall.function.name); // TS doesn't narrow based on isChatCompletionTool
+    let parsedArguments = null;
+    if (isAutoParsableTool(inputTool)) {
+        parsedArguments = inputTool.$parseRaw(toolCall.function.arguments);
+    }
+    else if (inputTool?.function.strict) {
+        parsedArguments = parseResponseFormatContent({ type: 'json_schema', $parseRaw: undefined }, toolCall.function.arguments);
+    }
+    return {
+        ...toolCall,
+        function: {
+            ...toolCall.function,
+            parsed_arguments: parsedArguments,
+        },
+    };
+}
+/** Returns whether a tool call matches a strict or auto-parseable function in the request. */
+function shouldParseToolCall(params, 
+// accepts partially accumulated tool calls so streaming snapshots can be checked as they build up
+toolCall) {
+    if (!params || !('tools' in params) || !params.tools || toolCall.type !== 'function') {
+        return false;
+    }
+    const inputTool = params.tools?.find((inputTool) => isChatCompletionFunctionTool(inputTool) && inputTool.function?.name === toolCall.function?.name);
+    return (isChatCompletionFunctionTool(inputTool) &&
+        (isAutoParsableTool(inputTool) || inputTool?.function.strict || false));
+}
+/** Returns whether the request contains an auto-parseable response format or strict function tool. */
+function hasAutoParseableInput(params) {
+    if (isParseableResponseFormat(params.response_format)) {
+        return true;
+    }
+    return (params.tools?.some((t) => isAutoParsableTool(t) || (t.type === 'function' && t.function.strict === true)) ?? false);
+}
+/**
+ * Narrows completion tool calls to function calls supported by parsing helpers.
+ *
+ * @throws {OpenAIError} If any tool call has a non-function type.
+ */
+function assertToolCallsAreChatCompletionFunctionToolCalls(toolCalls) {
+    for (const toolCall of toolCalls || []) {
+        if (toolCall.type !== 'function') {
+            throw new error_1.OpenAIError(`Currently only \`function\` tool calls are supported; Received \`${toolCall.type}\``);
+        }
+    }
+}
+/**
+ * Validates strict function tools while preserving supported custom tools.
+ *
+ * @throws {OpenAIError} If a tool is unsupported or a function is missing `strict: true`.
+ */
+function validateInputTools(tools) {
+    for (const tool of tools ?? []) {
+        if (tool.type === 'custom') {
+            continue;
+        }
+        if (tool.type !== 'function') {
+            const unsupportedType = tool.type;
+            throw new error_1.OpenAIError(`Currently only \`function\` and \`custom\` tool types are supported; Received \`${unsupportedType}\``);
+        }
+        if (tool.function.strict !== true) {
+            throw new error_1.OpenAIError(`The \`${tool.function.name}\` tool is not marked with \`strict: true\`. Only strict function tools can be auto-parsed`);
+        }
+    }
+}
+//# sourceMappingURL=parser.js.map

package/lib/parser.js.map

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