@modelrelay/sdk 0.24.0 → 0.25.1

package/README.md

@@ -205,6 +205,155 @@ const final = await stream.collect();
 console.log(final.items.length);
 ```
 
+### Type-safe structured outputs with Zod schemas
+
+For automatic schema generation and validation, use `structured()` with Zod:
+
+```ts
+import { ModelRelay } from "@modelrelay/sdk";
+import { z } from "zod";
+
+const mr = new ModelRelay({ key: "mr_sk_..." });
+
+// Define your output type with Zod
+const PersonSchema = z.object({
+  name: z.string(),
+  age: z.number(),
+});
+
+// structured() auto-generates JSON schema and validates responses
+const result = await mr.chat.completions.structured(
+  PersonSchema,
+  {
+    model: "claude-sonnet-4-20250514",
+    messages: [{ role: "user", content: "Extract: John Doe is 30 years old" }],
+  },
+  { maxRetries: 2 } // Retry on validation failures
+);
+
+console.log(`Name: ${result.value.name}, Age: ${result.value.age}`);
+console.log(`Succeeded on attempt ${result.attempts}`);
+```
+
+#### Schema features
+
+Zod schemas map to JSON Schema properties:
+
+```ts
+const StatusSchema = z.object({
+  // Required string field
+  code: z.string(),
+
+  // Optional field (not in "required" array)
+  notes: z.string().optional(),
+
+  // Description for documentation
+  email: z.string().email().describe("User's email address"),
+
+  // Enum constraint
+  priority: z.enum(["low", "medium", "high"]),
+
+  // Nested objects are fully supported
+  address: z.object({
+    city: z.string(),
+    country: z.string(),
+  }),
+
+  // Arrays
+  tags: z.array(z.string()),
+});
+```
+
+#### Handling validation errors
+
+When validation fails after all retries:
+
+```ts
+import { StructuredExhaustedError } from "@modelrelay/sdk";
+
+try {
+  const result = await mr.chat.completions.structured(
+    PersonSchema,
+    { model: "claude-sonnet-4-20250514", messages },
+    { maxRetries: 2 }
+  );
+} catch (err) {
+  if (err instanceof StructuredExhaustedError) {
+    console.log(`Failed after ${err.allAttempts.length} attempts`);
+    for (const attempt of err.allAttempts) {
+      console.log(`Attempt ${attempt.attempt}: ${attempt.rawJson}`);
+      if (attempt.error.kind === "validation" && attempt.error.issues) {
+        for (const issue of attempt.error.issues) {
+          console.log(`  - ${issue.path ?? "root"}: ${issue.message}`);
+        }
+      } else if (attempt.error.kind === "decode") {
+        console.log(`  Decode error: ${attempt.error.message}`);
+      }
+    }
+  }
+}
+```
+
+#### Custom retry handlers
+
+Customize retry behavior:
+
+```ts
+import type { RetryHandler } from "@modelrelay/sdk";
+
+const customHandler: RetryHandler = {
+  onValidationError(attempt, rawJson, error, messages) {
+    if (attempt >= 3) {
+      return null; // Stop retrying
+    }
+    return [
+      {
+        role: "user",
+        content: `Invalid response. Issues: ${JSON.stringify(error.issues)}. Try again.`,
+      },
+    ];
+  },
+};
+
+const result = await mr.chat.completions.structured(
+  PersonSchema,
+  { model: "claude-sonnet-4-20250514", messages },
+  { maxRetries: 3, retryHandler: customHandler }
+);
+```
+
+#### Streaming structured outputs
+
+For streaming with Zod schema (no retries):
+
+```ts
+const stream = await mr.chat.completions.streamStructured(
+  PersonSchema,
+  {
+    model: "claude-sonnet-4-20250514",
+    messages: [{ role: "user", content: "Extract: Jane, 25" }],
+  }
+);
+
+for await (const evt of stream) {
+  if (evt.type === "completion") {
+    console.log("Final:", evt.payload);
+  }
+}
+```
+
+#### Customer-attributed structured outputs
+
+Works with customer-attributed requests too:
+
+```ts
+const result = await mr.chat.forCustomer("customer-123").structured(
+  PersonSchema,
+  { messages: [{ role: "user", content: "Extract: John, 30" }] },
+  { maxRetries: 2 }
+);
+```
+
 ### Telemetry & metrics hooks
 
 Provide lightweight callbacks to observe latency and usage without extra deps:

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.25.1",
   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]() {
@@ -1872,7 +2210,7 @@ function mapChatEvent(raw, requestId) {
   if (raw.data) {
     try {
       parsed = JSON.parse(raw.data);
-    } catch {
+    } catch (err) {
       parsed = raw.data;
     }
   }
@@ -2785,6 +3123,8 @@ function resolveBaseUrl(override) {
   ResponseFormatTypes,
   SDK_VERSION,
   StopReasons,
+  StructuredDecodeError,
+  StructuredExhaustedError,
   StructuredJSONStream,
   TiersClient,
   ToolArgsError,
@@ -2807,6 +3147,7 @@ function resolveBaseUrl(override) {
   createUsage,
   createUserMessage,
   createWebTool,
+  defaultRetryHandler,
   executeWithRetry,
   firstToolCall,
   formatToolErrorForModel,
@@ -2827,11 +3168,13 @@ function resolveBaseUrl(override) {
   parseToolArgs,
   parseToolArgsRaw,
   respondToToolCall,
+  responseFormatFromZod,
   stopReasonToString,
   toolChoiceAuto,
   toolChoiceNone,
   toolChoiceRequired,
   toolResultMessage,
   tryParseToolArgs,
+  validateWithZod,
   zodToJsonSchema
 });