@modelrelay/sdk 0.24.0 → 0.27.0

package/dist/index.cjs

@@ -38,6 +38,8 @@ __export(index_exports, {
   ResponseFormatTypes: () => ResponseFormatTypes,
   SDK_VERSION: () => SDK_VERSION,
   StopReasons: () => StopReasons,
+  StructuredDecodeError: () => StructuredDecodeError,
+  StructuredExhaustedError: () => StructuredExhaustedError,
   StructuredJSONStream: () => StructuredJSONStream,
   TiersClient: () => TiersClient,
   ToolArgsError: () => ToolArgsError,
@@ -60,6 +62,7 @@ __export(index_exports, {
   createUsage: () => createUsage,
   createUserMessage: () => createUserMessage,
   createWebTool: () => createWebTool,
+  defaultRetryHandler: () => defaultRetryHandler,
   executeWithRetry: () => executeWithRetry,
   firstToolCall: () => firstToolCall,
   formatToolErrorForModel: () => formatToolErrorForModel,
@@ -80,12 +83,14 @@ __export(index_exports, {
   parseToolArgs: () => parseToolArgs,
   parseToolArgsRaw: () => parseToolArgsRaw,
   respondToToolCall: () => respondToToolCall,
+  responseFormatFromZod: () => responseFormatFromZod,
   stopReasonToString: () => stopReasonToString,
   toolChoiceAuto: () => toolChoiceAuto,
   toolChoiceNone: () => toolChoiceNone,
   toolChoiceRequired: () => toolChoiceRequired,
   toolResultMessage: () => toolResultMessage,
   tryParseToolArgs: () => tryParseToolArgs,
+  validateWithZod: () => validateWithZod,
   zodToJsonSchema: () => zodToJsonSchema
 });
 module.exports = __toCommonJS(index_exports);
@@ -432,7 +437,7 @@ function isTokenReusable(token) {
 // package.json
 var package_default = {
   name: "@modelrelay/sdk",
-  version: "0.24.0",
+  version: "0.27.0",
   description: "TypeScript SDK for the ModelRelay API",
   type: "module",
   main: "dist/index.cjs",
@@ -1192,6 +1197,58 @@ async function executeWithRetry(registry, toolCalls, options = {}) {
   return Array.from(successfulResults.values());
 }
 
+// src/structured.ts
+var StructuredDecodeError = class extends Error {
+  constructor(message, rawJson, attempt) {
+    super(`structured output decode error (attempt ${attempt}): ${message}`);
+    this.name = "StructuredDecodeError";
+    this.rawJson = rawJson;
+    this.attempt = attempt;
+  }
+};
+var StructuredExhaustedError = class extends Error {
+  constructor(lastRawJson, allAttempts, finalError) {
+    const errorMsg = finalError.kind === "decode" ? finalError.message : finalError.issues.map((i) => i.message).join("; ");
+    super(
+      `structured output failed after ${allAttempts.length} attempts: ${errorMsg}`
+    );
+    this.name = "StructuredExhaustedError";
+    this.lastRawJson = lastRawJson;
+    this.allAttempts = allAttempts;
+    this.finalError = finalError;
+  }
+};
+var defaultRetryHandler = {
+  onValidationError(_attempt, _rawJson, error, _originalMessages) {
+    const errorMsg = error.kind === "decode" ? error.message : error.issues.map((i) => `${i.path ?? ""}: ${i.message}`).join("; ");
+    return [
+      {
+        role: "user",
+        content: `The previous response did not match the expected schema. Error: ${errorMsg}. Please provide a response that matches the schema exactly.`
+      }
+    ];
+  }
+};
+function responseFormatFromZod(schema, name = "response") {
+  const jsonSchema = zodToJsonSchema(schema);
+  return {
+    type: "json_schema",
+    json_schema: {
+      name,
+      schema: jsonSchema,
+      strict: true
+    }
+  };
+}
+function validateWithZod(schema, data) {
+  const result = schema.safeParse(data);
+  if (result.success) {
+    return { success: true, data: result.data };
+  }
+  const errorMsg = result.error && typeof result.error === "object" && "message" in result.error ? String(result.error.message) : "validation failed";
+  return { success: false, error: errorMsg };
+}
+
 // src/chat.ts
 var CUSTOMER_ID_HEADER = "X-ModelRelay-Customer-Id";
 var REQUEST_ID_HEADER = "X-ModelRelay-Chat-Request-Id";
@@ -1389,6 +1446,158 @@ var ChatCompletionsClient = class {
       trace
     );
   }
+  /**
+   * Send a structured output request with a Zod schema.
+   *
+   * Auto-generates JSON schema from the Zod schema, validates the response,
+   * and retries on validation failure if configured.
+   *
+   * @param schema - A Zod schema defining the expected response structure
+   * @param params - Chat completion parameters (excluding responseFormat)
+   * @param options - Request options including retry configuration
+   * @returns A typed result with the parsed value
+   *
+   * @example
+   * ```typescript
+   * import { z } from 'zod';
+   *
+   * const PersonSchema = z.object({
+   *   name: z.string(),
+   *   age: z.number(),
+   * });
+   *
+   * const result = await client.chat.completions.structured(
+   *   PersonSchema,
+   *   { model: "claude-sonnet-4-20250514", messages: [...] },
+   *   { maxRetries: 2 }
+   * );
+   * ```
+   */
+  async structured(schema, params, options = {}) {
+    const {
+      maxRetries = 0,
+      retryHandler = defaultRetryHandler,
+      schemaName,
+      ...requestOptions
+    } = options;
+    const responseFormat = responseFormatFromZod(schema, schemaName);
+    const fullParams = {
+      ...params,
+      responseFormat,
+      stream: false
+    };
+    let messages = [...params.messages];
+    const attempts = [];
+    const maxAttempts = maxRetries + 1;
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+      const response = await this.create(
+        { ...fullParams, messages },
+        { ...requestOptions, stream: false }
+      );
+      const rawJson = response.content.join("");
+      const requestId = response.requestId;
+      try {
+        const parsed = JSON.parse(rawJson);
+        const validated = validateWithZod(schema, parsed);
+        if (validated.success) {
+          return {
+            value: validated.data,
+            attempts: attempt,
+            requestId
+          };
+        }
+        const error = {
+          kind: "validation",
+          issues: [{ message: validated.error }]
+        };
+        attempts.push({ attempt, rawJson, error });
+        if (attempt >= maxAttempts) {
+          throw new StructuredExhaustedError(rawJson, attempts, error);
+        }
+        const retryMessages = retryHandler.onValidationError(
+          attempt,
+          rawJson,
+          error,
+          params.messages
+        );
+        if (!retryMessages) {
+          throw new StructuredExhaustedError(rawJson, attempts, error);
+        }
+        messages = [
+          ...params.messages,
+          { role: "assistant", content: rawJson },
+          ...retryMessages
+        ];
+      } catch (e) {
+        if (e instanceof StructuredExhaustedError) {
+          throw e;
+        }
+        const error = {
+          kind: "decode",
+          message: e instanceof Error ? e.message : String(e)
+        };
+        attempts.push({ attempt, rawJson, error });
+        if (attempt >= maxAttempts) {
+          throw new StructuredExhaustedError(rawJson, attempts, error);
+        }
+        const retryMessages = retryHandler.onValidationError(
+          attempt,
+          rawJson,
+          error,
+          params.messages
+        );
+        if (!retryMessages) {
+          throw new StructuredExhaustedError(rawJson, attempts, error);
+        }
+        messages = [
+          ...params.messages,
+          { role: "assistant", content: rawJson },
+          ...retryMessages
+        ];
+      }
+    }
+    throw new Error(
+      `Internal error: structured output loop exited unexpectedly after ${maxAttempts} attempts (this is a bug, please report it)`
+    );
+  }
+  /**
+   * Stream structured output with a Zod schema.
+   *
+   * Auto-generates JSON schema from the Zod schema. Note that streaming
+   * does not support retries - for retry behavior, use `structured()`.
+   *
+   * @param schema - A Zod schema defining the expected response structure
+   * @param params - Chat completion parameters (excluding responseFormat)
+   * @param options - Request options
+   * @returns A structured JSON stream
+   *
+   * @example
+   * ```typescript
+   * import { z } from 'zod';
+   *
+   * const PersonSchema = z.object({
+   *   name: z.string(),
+   *   age: z.number(),
+   * });
+   *
+   * const stream = await client.chat.completions.streamStructured(
+   *   PersonSchema,
+   *   { model: "claude-sonnet-4-20250514", messages: [...] },
+   * );
+   *
+   * for await (const event of stream) {
+   *   console.log(event.type, event.payload);
+   * }
+   * ```
+   */
+  async streamStructured(schema, params, options = {}) {
+    const { schemaName, ...requestOptions } = options;
+    const responseFormat = responseFormatFromZod(schema, schemaName);
+    return this.streamJSON(
+      { ...params, responseFormat },
+      requestOptions
+    );
+  }
 };
 var CustomerChatClient = class {
   constructor(http, auth, customerId, defaultMetadata, metrics, trace) {
@@ -1553,6 +1762,123 @@ var CustomerChatClient = class {
       trace
     );
   }
+  /**
+   * Send a structured output request with a Zod schema for customer-attributed calls.
+   *
+   * Auto-generates JSON schema from the Zod schema, validates the response,
+   * and retries on validation failure if configured.
+   *
+   * @param schema - A Zod schema defining the expected response structure
+   * @param params - Customer chat parameters (excluding responseFormat)
+   * @param options - Request options including retry configuration
+   * @returns A typed result with the parsed value
+   */
+  async structured(schema, params, options = {}) {
+    const {
+      maxRetries = 0,
+      retryHandler = defaultRetryHandler,
+      schemaName,
+      ...requestOptions
+    } = options;
+    const responseFormat = responseFormatFromZod(schema, schemaName);
+    const fullParams = {
+      ...params,
+      responseFormat,
+      stream: false
+    };
+    let messages = [...params.messages];
+    const attempts = [];
+    const maxAttempts = maxRetries + 1;
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+      const response = await this.create(
+        { ...fullParams, messages },
+        { ...requestOptions, stream: false }
+      );
+      const rawJson = response.content.join("");
+      const requestId = response.requestId;
+      try {
+        const parsed = JSON.parse(rawJson);
+        const validated = validateWithZod(schema, parsed);
+        if (validated.success) {
+          return {
+            value: validated.data,
+            attempts: attempt,
+            requestId
+          };
+        }
+        const error = {
+          kind: "validation",
+          issues: [{ message: validated.error }]
+        };
+        attempts.push({ attempt, rawJson, error });
+        if (attempt >= maxAttempts) {
+          throw new StructuredExhaustedError(rawJson, attempts, error);
+        }
+        const retryMessages = retryHandler.onValidationError(
+          attempt,
+          rawJson,
+          error,
+          params.messages
+        );
+        if (!retryMessages) {
+          throw new StructuredExhaustedError(rawJson, attempts, error);
+        }
+        messages = [
+          ...params.messages,
+          { role: "assistant", content: rawJson },
+          ...retryMessages
+        ];
+      } catch (e) {
+        if (e instanceof StructuredExhaustedError) {
+          throw e;
+        }
+        const error = {
+          kind: "decode",
+          message: e instanceof Error ? e.message : String(e)
+        };
+        attempts.push({ attempt, rawJson, error });
+        if (attempt >= maxAttempts) {
+          throw new StructuredExhaustedError(rawJson, attempts, error);
+        }
+        const retryMessages = retryHandler.onValidationError(
+          attempt,
+          rawJson,
+          error,
+          params.messages
+        );
+        if (!retryMessages) {
+          throw new StructuredExhaustedError(rawJson, attempts, error);
+        }
+        messages = [
+          ...params.messages,
+          { role: "assistant", content: rawJson },
+          ...retryMessages
+        ];
+      }
+    }
+    throw new Error(
+      `Internal error: structured output loop exited unexpectedly after ${maxAttempts} attempts (this is a bug, please report it)`
+    );
+  }
+  /**
+   * Stream structured output with a Zod schema for customer-attributed calls.
+   *
+   * Auto-generates JSON schema from the Zod schema. Note that streaming
+   * does not support retries - for retry behavior, use `structured()`.
+   *
+   * @param schema - A Zod schema defining the expected response structure
+   * @param params - Customer chat parameters (excluding responseFormat)
+   * @param options - Request options
+   * @returns A structured JSON stream
+   */
+  async streamStructured(schema, params, options = {}) {
+    const { schemaName, ...requestOptions } = options;
+    const responseFormat = responseFormatFromZod(schema, schemaName);
+    return this.streamJSON(
+      { ...params, responseFormat },
+      requestOptions
+    );
+  }
 };
 var ChatCompletionsStream = class {
   constructor(response, requestId, context, metrics, trace) {
@@ -1572,7 +1898,13 @@ var ChatCompletionsStream = class {
     this.closed = true;
     try {
       await this.response.body?.cancel(reason);
-    } catch {
+    } catch (err) {
+      if (this.trace?.streamError) {
+        this.trace.streamError({
+          context: this.context,
+          error: err instanceof Error ? err : new Error(String(err))
+        });
+      }
     }
   }
   async *[Symbol.asyncIterator]() {
@@ -1671,7 +2003,13 @@ var StructuredJSONStream = class {
     this.closed = true;
     try {
       await this.response.body?.cancel(reason);
-    } catch {
+    } catch (err) {
+      if (this.trace?.streamError) {
+        this.trace.streamError({
+          context: this.context,
+          error: err instanceof Error ? err : new Error(String(err))
+        });
+      }
     }
   }
   async *[Symbol.asyncIterator]() {
@@ -1785,11 +2123,13 @@ var StructuredJSONStream = class {
     if (rawType === "completion") {
       this.sawTerminal = true;
     }
+    const completeFieldsArray = Array.isArray(obj.complete_fields) ? obj.complete_fields.filter((f) => typeof f === "string") : [];
     const event = {
       type: rawType,
       // biome-ignore lint/suspicious/noExplicitAny: payload is untyped json
       payload: obj.payload,
-      requestId: this.requestId
+      requestId: this.requestId,
+      completeFields: new Set(completeFieldsArray)
     };
     return event;
   }
@@ -1872,7 +2212,7 @@ function mapChatEvent(raw, requestId) {
   if (raw.data) {
     try {
       parsed = JSON.parse(raw.data);
-    } catch {
+    } catch (err) {
       parsed = raw.data;
     }
   }
@@ -2785,6 +3125,8 @@ function resolveBaseUrl(override) {
   ResponseFormatTypes,
   SDK_VERSION,
   StopReasons,
+  StructuredDecodeError,
+  StructuredExhaustedError,
   StructuredJSONStream,
   TiersClient,
   ToolArgsError,
@@ -2807,6 +3149,7 @@ function resolveBaseUrl(override) {
   createUsage,
   createUserMessage,
   createWebTool,
+  defaultRetryHandler,
   executeWithRetry,
   firstToolCall,
   formatToolErrorForModel,
@@ -2827,11 +3170,13 @@ function resolveBaseUrl(override) {
   parseToolArgs,
   parseToolArgsRaw,
   respondToToolCall,
+  responseFormatFromZod,
   stopReasonToString,
   toolChoiceAuto,
   toolChoiceNone,
   toolChoiceRequired,
   toolResultMessage,
   tryParseToolArgs,
+  validateWithZod,
   zodToJsonSchema
 });