universal-llm-client 3.1.0 → 4.0.0

package/CHANGELOG.md

@@ -5,6 +5,45 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [4.0.0] - 2026-03-13
+
+### ⚠ BREAKING CHANGES
+
+- **Zod 4 required** — `zod@^4.0.0` is now a peer dependency (upgraded from Zod 3). Consumers must install `zod@^4.0.0`.
+- **Zero-dependency core** — Removed `zod-to-json-schema` from dependencies. Schema conversion now uses Zod 4's native `z.toJSONSchema()`. The library has no runtime dependencies (only peer deps).
+
+### Added
+
+- **Structured Output** — First-class structured output with Zod schema validation
+  - `generateStructured(schema, messages, options)` — returns typed, validated output
+  - `tryParseStructured(schema, messages, options)` — non-throwing variant returning `Result<T>`
+  - `generateStructuredStream(schema, messages, options)` — streaming with partial validated objects
+  - `chat(messages, { output: { schema } })` — structured output via `output` parameter on `chat()`
+  - Custom `StructuredOutputError` with `rawOutput` and `cause` for debuggability
+- **Provider Structured Output Support** — Native format negotiation per provider
+  - OpenAI: `response_format: { type: 'json_schema' }` with configurable `strict` mode
+  - Google/Vertex AI: `responseMimeType` + `responseSchema` with automatic unsupported feature stripping
+  - Ollama: `format` parameter with JSON Schema objects
+- **Streaming JSON Parser** — `StreamingJsonParser` for progressive partial object validation
+- **Audit Events** — `structured_request`, `structured_response`, `structured_validation_error` events
+- **Schema Utilities** — `zodToJsonSchema()`, `normalizeJsonSchema()`, `stripUnsupportedFeatures()`, `getJsonSchema()`
+- **`./structured-output` sub-path export** — Direct import of structured output utilities
+
+### Fixed
+
+- Validation logic deduplicated into `BaseLLMClient` (was copy-pasted across 3 providers)
+- Removed double validation (Router + Provider both validated the same response)
+- Audit events no longer log `"assistant"` as the model name
+- `chatStream()` now throws a clear error if `output` parameter is provided (use `generateStructuredStream()`)
+- `zodToJsonSchema()` preserves `definitions`/`$defs` when `$ref` references exist in the schema tree
+- OpenAI `strict` mode is now configurable via `output.strict` (defaults to `true`)
+
+### Deprecated
+
+- `ChatOptions.schema`, `.jsonSchema`, `.schemaName`, `.schemaDescription` — use `output` parameter or `generateStructured()` instead
+
+---
+
 ## [3.1.0] - 2026-03-12
 
 ### Added

package/README.md

@@ -27,6 +27,7 @@ const response = await model.chat([
 
 - 🔄 **Transparent Failover** — Priority-ordered provider chain with retries, health tracking, and cooldowns
 - 🛠️ **Tool Calling** — Register tools once, works across all providers. Autonomous multi-turn execution loop
+- 📋 **Structured Output** — Zod schema validation, JSON Schema support, streaming, and type-safe responses
 - 🌊 **Streaming** — First-class async generator streaming with pluggable decoder strategies
 - 🧠 **Reasoning** — Native `<think>` tag parsing, interleaved reasoning, and model thinking support
 - 🔍 **Observability** — Built-in auditor interface for logging, cost tracking, and behavioral analysis
@@ -183,6 +184,133 @@ const vectors = await embedModel.embedArray(['Hello', 'World']);
 // [[0.006, ...], [0.012, ...]]
 ```
 
+### Structured Output
+
+Get typed, validated JSON responses from any LLM using Zod schemas:
+
+```typescript
+import { AIModel } from 'universal-llm-client';
+import { z } from 'zod';
+
+const model = new AIModel({
+    model: 'gemini-2.5-flash',
+    providers: [
+        { type: 'google', apiKey: process.env.GOOGLE_API_KEY },
+        { type: 'ollama' },
+    ],
+});
+
+// Define your schema
+const UserSchema = z.object({
+    name: z.string(),
+    age: z.number(),
+    email: z.string().email(),
+    interests: z.array(z.string()),
+});
+
+// Method 1: generateStructured (throws on validation failure)
+const user = await model.generateStructured(UserSchema, [
+    { role: 'user', content: 'Generate a user profile for a software developer' },
+]);
+
+console.log(user.name);     // TypeScript knows this is string
+console.log(user.age);      // TypeScript knows this is number
+console.log(user.email);    // TypeScript knows this is string
+console.log(user.interests); // TypeScript knows this is string[]
+```
+
+**Non-throwing variant:**
+
+```typescript
+// Method 2: tryParseStructured (returns result object, never throws)
+const result = await model.tryParseStructured(UserSchema, messages);
+
+if (result.ok) {
+    console.log('User:', result.value.name);
+} else {
+    console.log('Error:', result.error.message);
+    console.log('Raw LLM output:', result.rawOutput);
+}
+```
+
+**Via chat options:**
+
+```typescript
+// Method 3: chat with output parameter
+const response = await model.chat(messages, {
+    output: { schema: UserSchema },
+});
+
+// response.structured is typed as { name: string, age: number, ... }
+if (response.structured) {
+    console.log(response.structured.name);
+}
+```
+
+**Streaming structured output:**
+
+```typescript
+// Stream partial validated objects as JSON generates
+for await (const partial of model.generateStructuredStream(UserSchema, messages)) {
+    console.log('Partial:', partial);
+    // Partial: { name: 'Alice' }
+    // Partial: { name: 'Alice', age: 30 }
+    // Partial: { name: 'Alice', age: 30, email: 'alice@example.com' }
+}
+```
+
+**Raw JSON Schema (without Zod):**
+
+```typescript
+const response = await model.chat(messages, {
+    jsonSchema: {
+        type: 'object',
+        properties: {
+            name: { type: 'string' },
+            age: { type: 'number' },
+        },
+        required: ['name', 'age'],
+    },
+    name: 'Person',  // Optional, used for LLM guidance
+});
+```
+
+**Separate module import (tree-shaking):**
+
+```typescript
+// Import only structured output types if you don't need the full client
+import {
+    StructuredOutputError,
+    type StructuredOutputResult,
+    type StructuredOutputOptions,
+    parseStructured,
+    tryParseStructured,
+    zodToJsonSchema,
+} from 'universal-llm-client/structured-output';
+```
+
+**Vision with structured output:**
+
+```typescript
+const ImageAnalysisSchema = z.object({
+    objects: z.array(z.string()),
+    scene: z.string(),
+    mood: z.string(),
+});
+
+const response = await model.generateStructured(ImageAnalysisSchema, [
+    multimodalMessage('Analyze this image', ['https://example.com/photo.jpg']),
+]);
+```
+
+**Provider compatibility:**
+
+| Provider | Method | Notes |
+|----------|--------|-------|
+| OpenAI | `response_format.json_schema` | Strict mode enabled |
+| Ollama | `format: { schema }` | Model must support grammar |
+| Google | `responseMimeType + responseSchema` | Some features stripped |
+
 ### Observability
 
 ```typescript
@@ -308,6 +436,9 @@ new AIModel(config: AIModelConfig)
 | `chat(messages, options?)` | `Promise<LLMChatResponse>` | Send chat request |
 | `chatWithTools(messages, options?)` | `Promise<LLMChatResponse>` | Chat with autonomous tool execution |
 | `chatStream(messages, options?)` | `AsyncGenerator<DecodedEvent>` | Stream chat response |
+| `generateStructured(schema, messages, options?)` | `Promise<T>` | Generate typed JSON validated against Zod schema |
+| `tryParseStructured(schema, messages, options?)` | `Promise<StructuredOutputResult<T>>` | Non-throwing variant returning result object |
+| `generateStructuredStream(schema, messages, options?)` | `AsyncGenerator<T, T>` | Stream partial validated objects as JSON generates |
 | `embed(text)` | `Promise<number[]>` | Generate single embedding |
 | `embedArray(texts)` | `Promise<number[][]>` | Generate batch embeddings |
 | `registerTool(name, desc, params, handler)` | `void` | Register a callable tool |
@@ -318,6 +449,52 @@ new AIModel(config: AIModelConfig)
 | `setModel(name)` | `void` | Switch model at runtime |
 | `dispose()` | `Promise<void>` | Clean shutdown |
 
+### Structured Output
+
+```typescript
+import { z } from 'zod';
+
+// Define your schema
+const UserSchema = z.object({
+    name: z.string(),
+    age: z.number(),
+    email: z.string().email(),
+});
+
+// Generate typed JSON
+const user = await model.generateStructured(UserSchema, messages);
+// TypeScript infers: { name: string; age: number; email: string }
+
+// Non-throwing variant
+const result = await model.tryParseStructured(UserSchema, messages);
+if (result.ok) {
+    console.log(result.value.name);  // Fully typed
+} else {
+    console.log(result.error.message);
+}
+
+// Stream partial objects
+for await (const partial of model.generateStructuredStream(UserSchema, messages)) {
+    console.log(partial);  // Partial validated objects
+}
+```
+
+**Separate module import (tree-shaking):**
+
+```typescript
+import {
+    StructuredOutputError,
+    type StructuredOutputResult,
+    parseStructured,
+    tryParseStructured,
+    zodToJsonSchema,
+} from 'universal-llm-client/structured-output';
+
+// Use without importing the full client
+const schema = z.object({ name: z.string() });
+const jsonSchema = zodToJsonSchema(schema);
+```
+
 ### `ToolBuilder` / `ToolExecutor`
 
 ```typescript

package/dist/ai-model.d.ts

@@ -9,6 +9,8 @@
 import { type AIModelConfig, type LLMChatMessage, type LLMChatResponse, type ChatOptions, type ModelMetadata, type LLMFunction, type ToolHandler } from './interfaces.js';
 import type { DecodedEvent } from './stream-decoder.js';
 import { type ProviderStatus } from './router.js';
+import { type StructuredOutputResult } from './structured-output.js';
+import { z } from 'zod';
 export declare class AIModel {
     private router;
     private auditor;
@@ -22,6 +24,93 @@ export declare class AIModel {
     }): Promise<LLMChatResponse>;
     /** Stream chat response with pluggable decoder strategy */
     chatStream(messages: LLMChatMessage[], options?: ChatOptions): AsyncGenerator<DecodedEvent, LLMChatResponse | void, unknown>;
+    /**
+     * Generate structured output from the LLM with automatic failover.
+     * Validates the response against the provided Zod schema.
+     * Throws StructuredOutputError on validation failure.
+     *
+     * @template T The type inferred from the Zod schema
+     * @param schema Zod schema for validation
+     * @param messages Chat messages to send
+     * @param options Additional options (temperature, maxTokens, etc.)
+     * @returns Promise resolving to validated structured output
+     * @throws StructuredOutputError if JSON parsing fails or schema validation fails
+     *
+     * @example
+     * ```typescript
+     * const UserSchema = z.object({
+     *   name: z.string(),
+     *   age: z.number(),
+     * });
+     *
+     * const user = await model.generateStructured(UserSchema, [
+     *   { role: 'user', content: 'Generate a user profile' },
+     * ]);
+     * // user.name: string, user.age: number
+     * ```
+     */
+    generateStructured<T>(schema: z.ZodType<T>, messages: LLMChatMessage[], options?: ChatOptions): Promise<T>;
+    /**
+     * Try to generate structured output, returning a result object instead of throwing.
+     * Same as generateStructured but returns { ok: true, value } on success
+     * and { ok: false, error, rawOutput } on failure.
+     *
+     * @template T The type inferred from the Zod schema
+     * @param schema Zod schema for validation
+     * @param messages Chat messages to send
+     * @param options Additional options (temperature, maxTokens, etc.)
+     * @returns StructuredOutputResult<T> - either success with value or failure with error
+     *
+     * @example
+     * ```typescript
+     * const result = await model.tryParseStructured(UserSchema, messages);
+     *
+     * if (result.ok) {
+     *   console.log('User:', result.value.name);
+     * } else {
+     *   console.log('Error:', result.error.message);
+     *   console.log('Raw output:', result.rawOutput);
+     * }
+     * ```
+     */
+    tryParseStructured<T>(schema: z.ZodType<T>, messages: LLMChatMessage[], options?: ChatOptions): Promise<StructuredOutputResult<T>>;
+    /**
+     * Stream structured output with partial validated objects.
+     *
+     * Yields partial validated objects as JSON generates, then returns the
+     * complete validated object on stream completion.
+     *
+     * For invalid partial JSON, no yield occurs (partial validation is best-effort).
+     * On stream completion, if the final JSON fails validation, throws StructuredOutputError.
+     *
+     * @template T The type inferred from the Zod schema
+     * @param schema Zod schema for validation
+     * @param messages Chat messages to send
+     * @param options Additional options (temperature, maxTokens, etc.)
+     * @yields Partial validated objects as the JSON stream progresses
+     * @returns Complete validated object on stream completion
+     * @throws StructuredOutputError if final validation fails
+     *
+     * @example
+     * ```typescript
+     * const UserSchema = z.object({
+     *   name: z.string(),
+     *   age: z.number(),
+     * });
+     *
+     * const stream = model.generateStructuredStream(UserSchema, [
+     *   { role: 'user', content: 'Generate a user' },
+     * ]);
+     *
+     * for await (const partial of stream) {
+     *   console.log('Partial user:', partial);
+     *   // Partial user: { name: 'Alice' }
+     *   // Partial user: { name: 'Alice', age: 30 }
+     * }
+     * // Stream returns complete validated object on completion
+     * ```
+     */
+    generateStructuredStream<T>(schema: z.ZodType<T>, messages: LLMChatMessage[], options?: ChatOptions): AsyncGenerator<T, T, unknown>;
     /** Generate embedding for a single text */
     embed(text: string): Promise<number[]>;
     /** Generate embeddings for multiple texts */

package/dist/ai-model.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ai-model.d.ts","sourceRoot":"","sources":["../src/ai-model.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAEH,KAAK,aAAa,EAGlB,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,KAAK,WAAW,EAChB,KAAK,aAAa,EAClB,KAAK,WAAW,EAChB,KAAK,WAAW,EACnB,MAAM,iBAAiB,CAAC;AACzB,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,EAA6B,KAAK,cAAc,EAAE,MAAM,aAAa,CAAC;AAuB7E,qBAAa,OAAO;IAChB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,OAAO,CAAU;IACzB,OAAO,CAAC,MAAM,CAAgB;gBAElB,MAAM,EAAE,aAAa;IA6BjC,mEAAmE;IAC7D,IAAI,CACN,QAAQ,EAAE,cAAc,EAAE,EAC1B,OAAO,CAAC,EAAE,WAAW,GACtB,OAAO,CAAC,eAAe,CAAC;IAI3B,2DAA2D;IACrD,aAAa,CACf,QAAQ,EAAE,cAAc,EAAE,EAC1B,OAAO,CAAC,EAAE,WAAW,GAAG;QAAE,aAAa,CAAC,EAAE,MAAM,CAAA;KAAE,GACnD,OAAO,CAAC,eAAe,CAAC;IAI3B,2DAA2D;IACpD,UAAU,CACb,QAAQ,EAAE,cAAc,EAAE,EAC1B,OAAO,CAAC,EAAE,WAAW,GACtB,cAAc,CAAC,YAAY,EAAE,eAAe,GAAG,IAAI,EAAE,OAAO,CAAC;IAQhE,2CAA2C;IACrC,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAI5C,6CAA6C;IACvC,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC;IAQtD,uEAAuE;IACvE,YAAY,CACR,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,MAAM,EACnB,UAAU,EAAE,WAAW,CAAC,YAAY,CAAC,EACrC,OAAO,EAAE,WAAW,GACrB,IAAI;IAIP,sCAAsC;IACtC,aAAa,CACT,KAAK,EAAE,KAAK,CAAC;QACT,IAAI,EAAE,MAAM,CAAC;QACb,WAAW,EAAE,MAAM,CAAC;QACpB,UAAU,EAAE,WAAW,CAAC,YAAY,CAAC,CAAC;QACtC,OAAO,EAAE,WAAW,CAAC;KACxB,CAAC,GACH,IAAI;IAQP,yDAAyD;IACnD,SAAS,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;IAIpC,0EAA0E;IACpE,YAAY,IAAI,OAAO,CAAC,aAAa,CAAC;IAI5C,sDAAsD;IACtD,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAM5B,iCAAiC;IACjC,IAAI,KAAK,IAAI,MAAM,CAElB;IAMD,oDAAoD;IACpD,iBAAiB,IAAI,cAAc,EAAE;IAQrC,2DAA2D;IACrD,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAQ9B,OAAO,CAAC,YAAY;IAmCpB,OAAO,CAAC,aAAa;CAGxB"}
+{"version":3,"file":"ai-model.d.ts","sourceRoot":"","sources":["../src/ai-model.ts"],"names":[],"mappings":"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"}

package/dist/ai-model.js

@@ -64,6 +64,102 @@ export class AIModel {
         return yield* this.router.chatStream(messages, options);
     }
     // ========================================================================
+    // Structured Output
+    // ========================================================================
+    /**
+     * Generate structured output from the LLM with automatic failover.
+     * Validates the response against the provided Zod schema.
+     * Throws StructuredOutputError on validation failure.
+     *
+     * @template T The type inferred from the Zod schema
+     * @param schema Zod schema for validation
+     * @param messages Chat messages to send
+     * @param options Additional options (temperature, maxTokens, etc.)
+     * @returns Promise resolving to validated structured output
+     * @throws StructuredOutputError if JSON parsing fails or schema validation fails
+     *
+     * @example
+     * ```typescript
+     * const UserSchema = z.object({
+     *   name: z.string(),
+     *   age: z.number(),
+     * });
+     *
+     * const user = await model.generateStructured(UserSchema, [
+     *   { role: 'user', content: 'Generate a user profile' },
+     * ]);
+     * // user.name: string, user.age: number
+     * ```
+     */
+    async generateStructured(schema, messages, options) {
+        return this.router.generateStructured(schema, messages, options);
+    }
+    /**
+     * Try to generate structured output, returning a result object instead of throwing.
+     * Same as generateStructured but returns { ok: true, value } on success
+     * and { ok: false, error, rawOutput } on failure.
+     *
+     * @template T The type inferred from the Zod schema
+     * @param schema Zod schema for validation
+     * @param messages Chat messages to send
+     * @param options Additional options (temperature, maxTokens, etc.)
+     * @returns StructuredOutputResult<T> - either success with value or failure with error
+     *
+     * @example
+     * ```typescript
+     * const result = await model.tryParseStructured(UserSchema, messages);
+     *
+     * if (result.ok) {
+     *   console.log('User:', result.value.name);
+     * } else {
+     *   console.log('Error:', result.error.message);
+     *   console.log('Raw output:', result.rawOutput);
+     * }
+     * ```
+     */
+    async tryParseStructured(schema, messages, options) {
+        return this.router.tryParseStructured(schema, messages, options);
+    }
+    /**
+     * Stream structured output with partial validated objects.
+     *
+     * Yields partial validated objects as JSON generates, then returns the
+     * complete validated object on stream completion.
+     *
+     * For invalid partial JSON, no yield occurs (partial validation is best-effort).
+     * On stream completion, if the final JSON fails validation, throws StructuredOutputError.
+     *
+     * @template T The type inferred from the Zod schema
+     * @param schema Zod schema for validation
+     * @param messages Chat messages to send
+     * @param options Additional options (temperature, maxTokens, etc.)
+     * @yields Partial validated objects as the JSON stream progresses
+     * @returns Complete validated object on stream completion
+     * @throws StructuredOutputError if final validation fails
+     *
+     * @example
+     * ```typescript
+     * const UserSchema = z.object({
+     *   name: z.string(),
+     *   age: z.number(),
+     * });
+     *
+     * const stream = model.generateStructuredStream(UserSchema, [
+     *   { role: 'user', content: 'Generate a user' },
+     * ]);
+     *
+     * for await (const partial of stream) {
+     *   console.log('Partial user:', partial);
+     *   // Partial user: { name: 'Alice' }
+     *   // Partial user: { name: 'Alice', age: 30 }
+     * }
+     * // Stream returns complete validated object on completion
+     * ```
+     */
+    async *generateStructuredStream(schema, messages, options) {
+        return yield* this.router.generateStructuredStream(schema, messages, options);
+    }
+    // ========================================================================
     // Embeddings
     // ========================================================================
     /** Generate embedding for a single text */

package/dist/ai-model.js.map

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

package/dist/auditor.d.ts

@@ -6,7 +6,7 @@
  * Auditor for dashboards, cost tracking, or behavioral scoring.
  */
 import type { TokenUsageInfo, ToolExecutionResult } from './interfaces.js';
-export type AuditEventType = 'request' | 'response' | 'stream_start' | 'stream_end' | 'tool_call' | 'tool_result' | 'error' | 'retry' | 'failover';
+export type AuditEventType = 'request' | 'response' | 'stream_start' | 'stream_end' | 'tool_call' | 'tool_result' | 'error' | 'retry' | 'failover' | 'structured_request' | 'structured_response' | 'structured_validation_error';
 export interface AuditEvent {
     /** Unix timestamp in ms */
     timestamp: number;
@@ -26,6 +26,10 @@ export interface AuditEvent {
     error?: string;
     /** Arbitrary metadata for framework-specific data */
     metadata?: Record<string, unknown>;
+    /** Schema name for structured output events */
+    schemaName?: string;
+    /** Raw output snippet for validation errors */
+    rawOutput?: string;
 }
 /**
  * Interface for LLM observability.

package/dist/auditor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"auditor.d.ts","sourceRoot":"","sources":["../src/auditor.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAM3E,MAAM,MAAM,cAAc,GACpB,SAAS,GACT,UAAU,GACV,cAAc,GACd,YAAY,GACZ,WAAW,GACX,aAAa,GACb,OAAO,GACP,OAAO,GACP,UAAU,CAAC;AAEjB,MAAM,WAAW,UAAU;IACvB,2BAA2B;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,iBAAiB;IACjB,IAAI,EAAE,cAAc,CAAC;IACrB,yCAAyC;IACzC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,iBAAiB;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,kDAAkD;IAClD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,wCAAwC;IACxC,KAAK,CAAC,EAAE,cAAc,CAAC;IACvB,gEAAgE;IAChE,aAAa,CAAC,EAAE,mBAAmB,CAAC;IACpC,6CAA6C;IAC7C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,qDAAqD;IACrD,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACtC;AAMD;;;;;GAKG;AACH,MAAM,WAAW,OAAO;IACpB,4BAA4B;IAC5B,MAAM,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI,CAAC;IAChC,2CAA2C;IAC3C,KAAK,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3B;AAMD;;;GAGG;AACH,qBAAa,WAAY,YAAW,OAAO;IACvC,MAAM,CAAC,MAAM,EAAE,UAAU,GAAG,IAAI;CAGnC;AAED;;;GAGG;AACH,qBAAa,cAAe,YAAW,OAAO;IAC1C,OAAO,CAAC,MAAM,CAAS;gBAEX,MAAM,GAAE,MAAgB;IAIpC,MAAM,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI;CAkDlC;AAED;;;GAGG;AACH,qBAAa,eAAgB,YAAW,OAAO;IAC3C,OAAO,CAAC,MAAM,CAAoB;IAClC,OAAO,CAAC,aAAa,CAAS;IAC9B,OAAO,CAAC,OAAO,CAAC,CAA0C;gBAE9C,OAAO,GAAE;QACjB,aAAa,CAAC,EAAE,MAAM,CAAC;QACvB,OAAO,CAAC,EAAE,CAAC,MAAM,EAAE,UAAU,EAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;KAChD;IAKN,MAAM,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI;IAQ/B,8BAA8B;IAC9B,SAAS,IAAI,aAAa,CAAC,UAAU,CAAC;IAItC,mDAAmD;IAC7C,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAQ5B,iDAAiD;IACjD,KAAK,IAAI,IAAI;CAGhB"}
+{"version":3,"file":"auditor.d.ts","sourceRoot":"","sources":["../src/auditor.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAM3E,MAAM,MAAM,cAAc,GACpB,SAAS,GACT,UAAU,GACV,cAAc,GACd,YAAY,GACZ,WAAW,GACX,aAAa,GACb,OAAO,GACP,OAAO,GACP,UAAU,GACV,oBAAoB,GACpB,qBAAqB,GACrB,6BAA6B,CAAC;AAEpC,MAAM,WAAW,UAAU;IACvB,2BAA2B;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,iBAAiB;IACjB,IAAI,EAAE,cAAc,CAAC;IACrB,yCAAyC;IACzC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,iBAAiB;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,kDAAkD;IAClD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,wCAAwC;IACxC,KAAK,CAAC,EAAE,cAAc,CAAC;IACvB,gEAAgE;IAChE,aAAa,CAAC,EAAE,mBAAmB,CAAC;IACpC,6CAA6C;IAC7C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,qDAAqD;IACrD,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,+CAA+C;IAC/C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,+CAA+C;IAC/C,SAAS,CAAC,EAAE,MAAM,CAAC;CACtB;AAMD;;;;;GAKG;AACH,MAAM,WAAW,OAAO;IACpB,4BAA4B;IAC5B,MAAM,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI,CAAC;IAChC,2CAA2C;IAC3C,KAAK,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3B;AAMD;;;GAGG;AACH,qBAAa,WAAY,YAAW,OAAO;IACvC,MAAM,CAAC,MAAM,EAAE,UAAU,GAAG,IAAI;CAGnC;AAED;;;GAGG;AACH,qBAAa,cAAe,YAAW,OAAO;IAC1C,OAAO,CAAC,MAAM,CAAS;gBAEX,MAAM,GAAE,MAAgB;IAIpC,MAAM,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI;CAwElC;AAED;;;GAGG;AACH,qBAAa,eAAgB,YAAW,OAAO;IAC3C,OAAO,CAAC,MAAM,CAAoB;IAClC,OAAO,CAAC,aAAa,CAAS;IAC9B,OAAO,CAAC,OAAO,CAAC,CAA0C;gBAE9C,OAAO,GAAE;QACjB,aAAa,CAAC,EAAE,MAAM,CAAC;QACvB,OAAO,CAAC,EAAE,CAAC,MAAM,EAAE,UAAU,EAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;KAChD;IAKN,MAAM,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI;IAQ/B,8BAA8B;IAC9B,SAAS,IAAI,aAAa,CAAC,UAAU,CAAC;IAItC,mDAAmD;IAC7C,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAQ5B,iDAAiD;IACjD,KAAK,IAAI,IAAI;CAGhB"}

package/dist/auditor.js

@@ -61,6 +61,15 @@ export class ConsoleAuditor {
             case 'failover':
                 console.warn(parts.join(' '), '→', event.metadata?.['nextProvider'] ?? '');
                 break;
+            case 'structured_request':
+                console.log(parts.join(' '), `schema=${event.schemaName ?? 'unknown'}`, '→');
+                break;
+            case 'structured_response':
+                console.log(parts.join(' '), event.duration ? `${event.duration}ms` : '', `schema=${event.schemaName ?? 'unknown'}`);
+                break;
+            case 'structured_validation_error':
+                console.error(parts.join(' '), `schema=${event.schemaName ?? 'unknown'}`, event.error ?? 'Validation failed', event.rawOutput ? `raw=${event.rawOutput.slice(0, 50)}...` : '');
+                break;
         }
     }
 }

package/dist/auditor.js.map

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

package/dist/client.d.ts

@@ -5,7 +5,9 @@
  * Handles tool registration, execution, and the autonomous
  * multi-turn tool execution loop.
  */
+import { z } from 'zod';
 import type { LLMClientOptions, LLMChatMessage, LLMChatResponse, LLMToolDefinition, LLMToolCall, LLMFunction, ToolRegistry, ToolHandler, ToolExecutionResult, ChatOptions, ModelMetadata } from './interfaces.js';
+import { type StructuredOutputOptions } from './structured-output.js';
 import type { DecodedEvent } from './stream-decoder.js';
 import type { Auditor } from './auditor.js';
 export declare abstract class BaseLLMClient {
@@ -71,5 +73,17 @@ export declare abstract class BaseLLMClient {
      * Generate a unique ID for tool calls when the provider doesn't provide one.
      */
     protected generateToolCallId(): string;
+    /**
+     * Extract schema options from ChatOptions.
+     * Returns null if no schema is provided.
+     */
+    protected extractSchemaOptions(options?: ChatOptions): (StructuredOutputOptions<unknown> & {
+        schema: z.ZodType<unknown>;
+    }) | null;
+    /**
+     * Validate structured response against Zod schema.
+     * Throws StructuredOutputError on failure.
+     */
+    protected validateStructuredResponse(content: string, schema: z.ZodType<unknown>): void;
 }
 //# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

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

package/dist/client.js

@@ -5,6 +5,8 @@
  * Handles tool registration, execution, and the autonomous
  * multi-turn tool execution loop.
  */
+import { z } from 'zod';
+import { StructuredOutputError, } from './structured-output.js';
 import { NoopAuditor } from './auditor.js';
 // ============================================================================
 // Abstract Base Client
@@ -236,5 +238,55 @@ export class BaseLLMClient {
     generateToolCallId() {
         return `call_${Date.now()}_${Math.random().toString(36).slice(2, 9)}`;
     }
+    // ========================================================================
+    // Structured Output Helpers (shared across all providers)
+    // ========================================================================
+    /**
+     * Extract schema options from ChatOptions.
+     * Returns null if no schema is provided.
+     */
+    extractSchemaOptions(options) {
+        if (!options)
+            return null;
+        if (options.schema) {
+            return {
+                schema: options.schema,
+                name: options.schemaName,
+                description: options.schemaDescription,
+            };
+        }
+        if (options.jsonSchema) {
+            return {
+                jsonSchema: options.jsonSchema,
+                name: options.schemaName,
+                description: options.schemaDescription,
+                schema: z.unknown(),
+            };
+        }
+        return null;
+    }
+    /**
+     * Validate structured response against Zod schema.
+     * Throws StructuredOutputError on failure.
+     */
+    validateStructuredResponse(content, schema) {
+        if (!content) {
+            throw new StructuredOutputError('Empty response from LLM', { rawOutput: content });
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(content);
+        }
+        catch (error) {
+            const syntaxError = error instanceof SyntaxError
+                ? error
+                : new SyntaxError(String(error));
+            throw new StructuredOutputError(`Failed to parse JSON: ${syntaxError.message}`, { rawOutput: content, cause: syntaxError });
+        }
+        const result = schema.safeParse(parsed);
+        if (!result.success) {
+            throw new StructuredOutputError(`Validation failed: ${result.error.issues.map((e) => e.message).join(', ')}`, { rawOutput: content, cause: result.error });
+        }
+    }
 }
 //# sourceMappingURL=client.js.map