universal-llm-client 3.1.0 → 4.0.0

package/dist/structured-output.js

@@ -0,0 +1,505 @@
+/**
+ * Structured Output Core Types
+ *
+ * Core types for structured output support in universal-llm-client.
+ * Provides type-safe Zod schema integration and JSON Schema support.
+ *
+ * @module structured-output
+ */
+import { z } from 'zod';
+/**
+ * Custom error class for structured output validation failures.
+ *
+ * Thrown when:
+ * - JSON parsing of LLM response fails
+ * - Zod schema validation fails
+ *
+ * Features:
+ * - `rawOutput` property containing the original LLM response
+ * - `cause` property for the underlying error (ZodError, SyntaxError, etc.)
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const result = await model.generateStructured(UserSchema, messages);
+ * } catch (error) {
+ *   if (error instanceof StructuredOutputError) {
+ *     console.log('Raw LLM output:', error.rawOutput);
+ *     if (error.cause instanceof z.ZodError) {
+ *       console.log('Validation issues:', error.cause.issues);
+ *     }
+ *   }
+ * }
+ * ```
+ */
+export class StructuredOutputError extends Error {
+    /** The raw output from the LLM that failed validation */
+    rawOutput;
+    /** The underlying cause (e.g., ZodError for schema validation failures) */
+    cause;
+    constructor(message, options) {
+        super(message);
+        this.rawOutput = options.rawOutput;
+        this.cause = options.cause;
+        // Maintains proper stack trace for where error was thrown (only available in V8)
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, StructuredOutputError);
+        }
+    }
+}
+// ============================================================================
+// Type Guards
+// ============================================================================
+/**
+ * Type guard to check if a structured output result is successful.
+ *
+ * @param result The result to check
+ * @returns true if the result is successful
+ *
+ * @example
+ * ```typescript
+ * const result = await model.tryParseStructured(UserSchema, messages);
+ *
+ * if (isStructuredOutputSuccess(result)) {
+ *   console.log('User:', result.value.name);
+ * } else {
+ *   console.log('Error:', result.error.message);
+ * }
+ * ```
+ */
+export function isStructuredOutputSuccess(result) {
+    return result.ok === true;
+}
+/**
+ * Type guard to check if a structured output result is a failure.
+ *
+ * @param result The result to check
+ * @returns true if the result is a failure
+ *
+ * @example
+ * ```typescript
+ * const result = await model.tryParseStructured(UserSchema, messages);
+ *
+ * if (isStructuredOutputFailure(result)) {
+ *   console.log('Error:', result.error.message);
+ *   console.log('Raw:', result.rawOutput);
+ * }
+ * ```
+ */
+export function isStructuredOutputFailure(result) {
+    return result.ok === false;
+}
+// ============================================================================
+// Schema Conversion Utilities
+// ============================================================================
+/**
+ * Convert a Zod schema to JSON Schema.
+ *
+ * Uses Zod 4's native `z.toJSONSchema()` for conversion.
+ * Handles all Zod types including objects, arrays, primitives, enums, and nested structures.
+ *
+ * @param schema The Zod schema to convert
+ * @returns JSON Schema representation
+ *
+ * @example
+ * ```typescript
+ * const UserSchema = z.object({
+ *   name: z.string(),
+ *   age: z.number(),
+ * });
+ *
+ * const jsonSchema = zodToJsonSchema(UserSchema);
+ * // { type: 'object', properties: { name: { type: 'string' }, ... }, required: ['name', 'age'] }
+ * ```
+ */
+export function zodToJsonSchema(schema) {
+    const result = z.toJSONSchema(schema, {
+        target: 'draft-07',
+        unrepresentable: 'any',
+    });
+    // Cast to our JSONSchema type and clean up
+    const cleanResult = result;
+    delete cleanResult.$schema;
+    return cleanResult;
+}
+/**
+ * Normalize a raw JSON Schema.
+ *
+ * Currently passes through without modification.
+ * Future versions may add normalization for provider compatibility.
+ *
+ * @param schema The JSON Schema to normalize
+ * @returns Normalized JSON Schema
+ */
+export function normalizeJsonSchema(schema) {
+    // Deep clone to avoid mutating the input
+    return JSON.parse(JSON.stringify(schema));
+}
+/**
+ * Get the JSON Schema from options.
+ *
+ * Converts Zod schema to JSON Schema if necessary, or normalizes raw JSON Schema.
+ *
+ * @param options The structured output options
+ * @returns JSON Schema
+ */
+export function getJsonSchema(options) {
+    if (options.schema) {
+        return zodToJsonSchema(options.schema);
+    }
+    if (options.jsonSchema) {
+        return normalizeJsonSchema(options.jsonSchema);
+    }
+    throw new Error('Either schema or jsonSchema must be provided');
+}
+/**
+ * Features that some providers don't support.
+ * These are removed when transforming schemas for those providers.
+ */
+const GOOGLE_UNSUPPORTED_FEATURES = [
+    'pattern',
+    'minLength',
+    'maxLength',
+    'minimum',
+    'maximum',
+    'exclusiveMinimum',
+    'exclusiveMaximum',
+    // Google doesn't support additionalProperties in response schema
+    'additionalProperties',
+];
+/**
+ * Strip unsupported features from a JSON Schema for a specific provider.
+ *
+ * Google/Gemini doesn't support certain JSON Schema features like pattern, min/max.
+ * This function removes those recursively.
+ *
+ * @param schema The JSON Schema to transform
+ * @param provider The target provider
+ * @returns Cleaned JSON Schema
+ *
+ * @example
+ * ```typescript
+ * const schema = {
+ *   type: 'string',
+ *   pattern: '^[a-z]+$',
+ *   minLength: 1,
+ * };
+ *
+ * const cleaned = stripUnsupportedFeatures(schema, 'google');
+ * // { type: 'string' } - pattern and minLength removed
+ * ```
+ */
+export function stripUnsupportedFeatures(schema, provider) {
+    // Only Google needs transformation currently
+    if (provider !== 'google') {
+        return schema;
+    }
+    // Deep clone to avoid mutating input
+    const result = JSON.parse(JSON.stringify(schema));
+    // Remove unsupported top-level properties
+    for (const feature of GOOGLE_UNSUPPORTED_FEATURES) {
+        delete result[feature];
+    }
+    // Recursively clean nested schemas
+    if (result.properties) {
+        for (const key of Object.keys(result.properties)) {
+            if (result.properties[key]) {
+                result.properties[key] = stripUnsupportedFeatures(result.properties[key], provider);
+            }
+        }
+    }
+    if (result.items) {
+        if (Array.isArray(result.items)) {
+            result.items = result.items.map(item => stripUnsupportedFeatures(item, provider));
+        }
+        else {
+            result.items = stripUnsupportedFeatures(result.items, provider);
+        }
+    }
+    // Handle oneOf, anyOf, allOf
+    for (const key of ['oneOf', 'anyOf', 'allOf']) {
+        const schemas = result[key];
+        if (Array.isArray(schemas)) {
+            result[key] = schemas.map(s => stripUnsupportedFeatures(s, provider));
+        }
+    }
+    return result;
+}
+/**
+ * Convert structured output options to a provider-specific schema.
+ *
+ * This function:
+ * 1. Extracts/converts the JSON Schema from options
+ * 2. Applies provider-specific transformations (e.g., removing unsupported features for Google)
+ * 3. Adds name/description for LLM guidance
+ *
+ * @param provider The target provider
+ * @param options The structured output options
+ * @returns Provider-ready schema with name and description
+ *
+ * @example
+ * ```typescript
+ * const result = convertToProviderSchema('openai', {
+ *   schema: z.object({ name: z.string() }),
+ *   name: 'User',
+ *   description: 'A user object',
+ * });
+ *
+ * // result.schema - JSON Schema
+ * // result.name - 'User'
+ * // result.description - 'A user object'
+ * ```
+ */
+export function convertToProviderSchema(provider, options) {
+    // Get the JSON Schema (convert from Zod or normalize raw)
+    const jsonSchema = getJsonSchema(options);
+    // Apply provider-specific transformations
+    const schema = stripUnsupportedFeatures(jsonSchema, provider);
+    // Generate a default name if not provided (some providers require it)
+    const name = options.name ?? 'response';
+    return {
+        schema,
+        name,
+        description: options.description,
+    };
+}
+// ============================================================================
+// Validation Functions
+// ============================================================================
+/**
+ * Parse and validate structured output from raw LLM response text.
+ *
+ * This function:
+ * 1. Parses JSON from the raw output string
+ * 2. Validates the parsed data against the Zod schema
+ * 3. Throws StructuredOutputError on failure
+ *
+ * @param schema The Zod schema to validate against
+ * @param rawOutput The raw string output from the LLM
+ * @returns The validated and typed data
+ * @throws StructuredOutputError if JSON parsing fails or schema validation fails
+ *
+ * @example
+ * ```typescript
+ * const schema = z.object({ name: z.string(), age: z.number() });
+ * const rawOutput = '{"name": "Alice", "age": 30}';
+ * const result = parseStructured(schema, rawOutput); // { name: "Alice", age: 30 }
+ * ```
+ */
+export function parseStructured(schema, rawOutput) {
+    // Step 1: Parse JSON
+    let parsed;
+    try {
+        parsed = JSON.parse(rawOutput);
+    }
+    catch (error) {
+        // JSON parsing failed - wrap in StructuredOutputError
+        const syntaxError = error instanceof SyntaxError
+            ? error
+            : new SyntaxError(String(error));
+        throw new StructuredOutputError(`Failed to parse JSON: ${syntaxError.message}`, { rawOutput, cause: syntaxError });
+    }
+    // Step 2: Validate against Zod schema
+    const result = schema.safeParse(parsed);
+    if (!result.success) {
+        // Schema validation failed - throw with ZodError as cause
+        throw new StructuredOutputError(`Validation failed: ${result.error.issues.map((e) => e.message).join(', ')}`, { rawOutput, cause: result.error });
+    }
+    return result.data;
+}
+/**
+ * Try to parse and validate structured output, returning a result object.
+ *
+ * This is the non-throwing variant of `parseStructured`. Instead of throwing
+ * on validation failure, it returns a result object with `ok: false` and
+ * the error details.
+ *
+ * @param schema The Zod schema to validate against
+ * @param rawOutput The raw string output from the LLM
+ * @returns A result object: `{ ok: true, value }` on success, `{ ok: false, error, rawOutput }` on failure
+ *
+ * @example
+ * ```typescript
+ * const schema = z.object({ name: z.string(), age: z.number() });
+ *
+ * // Success case
+ * const result1 = tryParseStructured(schema, '{"name": "Alice", "age": 30}');
+ * if (result1.ok) {
+ *   console.log(result1.value.name); // "Alice"
+ * }
+ *
+ * // Failure case
+ * const result2 = tryParseStructured(schema, 'invalid json');
+ * if (!result2.ok) {
+ *   console.log(result2.error.message); // Error message
+ *   console.log(result2.rawOutput); // Original output
+ * }
+ * ```
+ */
+export function tryParseStructured(schema, rawOutput) {
+    try {
+        const value = parseStructured(schema, rawOutput);
+        return { ok: true, value };
+    }
+    catch (error) {
+        if (error instanceof StructuredOutputError) {
+            return {
+                ok: false,
+                error,
+                rawOutput,
+            };
+        }
+        // Re-throw unexpected errors
+        throw error;
+    }
+}
+/**
+ * Validate already-parsed data against a Zod schema.
+ *
+ * This is useful when you have already parsed JSON and need to validate
+ * it against a schema, with optional raw output for error messages.
+ *
+ * @param schema The Zod schema to validate against
+ * @param data The parsed data to validate
+ * @param rawOutput Optional raw output string for error messages
+ * @returns The validated and typed data
+ * @throws StructuredOutputError if schema validation fails
+ *
+ * @example
+ * ```typescript
+ * const schema = z.object({ name: z.string(), age: z.number() });
+ * const data = JSON.parse('{"name": "Alice", "age": 30}');
+ * const result = validateStructuredOutput(schema, data); // { name: "Alice", age: 30 }
+ * ```
+ */
+export function validateStructuredOutput(schema, data, rawOutput) {
+    const result = schema.safeParse(data);
+    if (!result.success) {
+        const rawData = rawOutput ?? JSON.stringify(data);
+        throw new StructuredOutputError(`Validation failed: ${result.error.issues.map((e) => e.message).join(', ')}`, { rawOutput: rawData, cause: result.error });
+    }
+    return result.data;
+}
+// ============================================================================
+// Streaming JSON Parsing
+// ============================================================================
+/**
+ * Incremental JSON parser for streaming structured output.
+ *
+ * Allows parsing partial JSON as it streams in, returning validated partial
+ * objects when possible. Useful for structured output streaming where you
+ * want to see partial results before the complete JSON arrives.
+ */
+export class StreamingJsonParser {
+    buffer = '';
+    schema;
+    constructor(schema) {
+        this.schema = schema;
+    }
+    /**
+     * Feed a chunk of JSON text to the parser.
+     * Returns a validated partial object if the current buffer can be parsed
+     * as valid JSON that passes the schema, or undefined if not yet valid.
+     *
+     * For partial objects, this attempts to:
+     * 1. Add closing braces/brackets to make valid JSON
+     * 2. Fill in missing required fields with null/empty values
+     * 3. Validate against schema
+     *
+     * @param chunk Text chunk from the stream
+     * @returns Validated partial object or undefined
+     */
+    feed(chunk) {
+        this.buffer += chunk;
+        // Try to parse as complete JSON first
+        try {
+            const parsed = JSON.parse(this.buffer);
+            const result = this.schema.safeParse(parsed);
+            if (result.success) {
+                return { partial: result.data, complete: true };
+            }
+        }
+        catch {
+            // Not yet valid complete JSON
+        }
+        // Try to create a valid partial by closing braces
+        const partialResult = this.tryParsePartial();
+        return { partial: partialResult, complete: false };
+    }
+    /**
+     * Get the current buffer content.
+     */
+    getBuffer() {
+        return this.buffer;
+    }
+    /**
+     * Reset the parser state.
+     */
+    reset() {
+        this.buffer = '';
+    }
+    /**
+     * Attempt to parse partial JSON by adding closing brackets.
+     */
+    tryParsePartial() {
+        // Count unclosed brackets and braces
+        let braceCount = 0;
+        let bracketCount = 0;
+        let inString = false;
+        let escaped = false;
+        for (let i = 0; i < this.buffer.length; i++) {
+            const char = this.buffer[i];
+            if (escaped) {
+                escaped = false;
+                continue;
+            }
+            if (char === '\\' && inString) {
+                escaped = true;
+                continue;
+            }
+            if (char === '"') {
+                inString = !inString;
+                continue;
+            }
+            if (inString)
+                continue;
+            if (char === '{')
+                braceCount++;
+            else if (char === '}')
+                braceCount--;
+            else if (char === '[')
+                bracketCount++;
+            else if (char === ']')
+                bracketCount--;
+        }
+        // Build closing sequence
+        let closing = '';
+        while (bracketCount > 0) {
+            closing += ']';
+            bracketCount--;
+        }
+        while (braceCount > 0) {
+            closing += '}';
+            braceCount--;
+        }
+        // Try parsing with closing
+        const candidate = this.buffer + closing;
+        try {
+            const parsed = JSON.parse(candidate);
+            const result = this.schema.safeParse(parsed);
+            if (result.success) {
+                return result.data;
+            }
+        }
+        catch {
+            // Silently fail for partial JSON
+        }
+        return undefined;
+    }
+}
+// ============================================================================
+// Re-exports for Convenience
+// ============================================================================
+// Re-export Zod for users who need it
+export { z } from 'zod';
+//# sourceMappingURL=structured-output.js.map

package/dist/structured-output.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "universal-llm-client",
-  "version": "3.1.0",
+  "version": "4.0.0",
   "type": "module",
   "description": "A universal LLM client with transparent provider failover, streaming tool execution, pluggable reasoning, and native observability.",
   "main": "./dist/index.js",
@@ -29,6 +29,10 @@
     "./http": {
       "import": "./dist/http.js",
       "types": "./dist/http.d.ts"
+    },
+    "./structured-output": {
+      "import": "./dist/structured-output.js",
+      "types": "./dist/structured-output.d.ts"
     }
   },
   "files": [
@@ -46,7 +50,10 @@
     "test": "bun test",
     "typecheck": "tsc --noEmit",
     "lint": "tsc --noEmit --strict",
-    "prepack": "bun run build"
+    "prepack": "bun run build",
+    "docs:dev": "vitepress dev docs",
+    "docs:build": "vitepress build docs",
+    "docs:preview": "vitepress preview docs"
   },
   "keywords": [
     "llm",
@@ -70,10 +77,14 @@
   "devDependencies": {
     "@types/node": "^22.0.0",
     "rimraf": "^6.0.1",
-    "typescript": "^5.8.3"
+    "typescript": "^5.8.3",
+    "vitepress": "^1.6.4",
+    "vue": "^3.5.30",
+    "zod": "^4.0.0"
   },
   "peerDependencies": {
-    "@modelcontextprotocol/sdk": ">=1.24.0"
+    "@modelcontextprotocol/sdk": ">=1.24.0",
+    "zod": "^4.0.0"
   },
   "peerDependenciesMeta": {
     "@modelcontextprotocol/sdk": {