universal-llm-client 3.1.0 → 4.1.0

package/dist/structured-output.js

@@ -0,0 +1,397 @@
+/**
+ * Structured Output Core Types
+ *
+ * Core types for structured output support in universal-llm-client.
+ * Zero-dependency — works with raw JSON Schema and optional validate functions.
+ *
+ * For Zod integration, use the `universal-llm-client/zod` entrypoint.
+ *
+ * @module structured-output
+ */
+/**
+ * Custom error class for structured output validation failures.
+ *
+ * Thrown when:
+ * - JSON parsing of LLM response fails
+ * - Schema validation fails
+ *
+ * Features:
+ * - `rawOutput` property containing the original LLM response
+ * - `cause` property for the underlying error
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const result = await model.generateStructured(schema, messages);
+ * } catch (error) {
+ *   if (error instanceof StructuredOutputError) {
+ *     console.log('Raw LLM output:', error.rawOutput);
+ *     console.log('Cause:', error.cause);
+ *   }
+ * }
+ * ```
+ */
+export class StructuredOutputError extends Error {
+    /** The raw output from the LLM that failed validation */
+    rawOutput;
+    /** The underlying cause (e.g., validation error) */
+    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.
+ */
+export function isStructuredOutputSuccess(result) {
+    return result.ok === true;
+}
+/**
+ * Type guard to check if a structured output result is a failure.
+ */
+export function isStructuredOutputFailure(result) {
+    return result.ok === false;
+}
+// ============================================================================
+// Schema Conversion Utilities
+// ============================================================================
+/**
+ * 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 a SchemaConfig or StructuredOutputOptions.
+ *
+ * @param options The structured output options
+ * @returns JSON Schema
+ */
+export function getJsonSchema(options) {
+    if (options.schemaConfig) {
+        return normalizeJsonSchema(options.schemaConfig.jsonSchema);
+    }
+    if (options.jsonSchema) {
+        return normalizeJsonSchema(options.jsonSchema);
+    }
+    throw new Error('Either schemaConfig or jsonSchema must be provided');
+}
+/**
+ * Get the JSON Schema from a SchemaConfig directly.
+ */
+export function getJsonSchemaFromConfig(config) {
+    return normalizeJsonSchema(config.jsonSchema);
+}
+/**
+ * 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
+ */
+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
+ */
+export function convertToProviderSchema(provider, options) {
+    // Get the JSON Schema
+    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 ?? options.schemaConfig?.name ?? 'response';
+    return {
+        schema,
+        name,
+        description: options.description ?? options.schemaConfig?.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 using the SchemaConfig's validate function (if provided)
+ * 3. Throws StructuredOutputError on failure
+ *
+ * @param config The schema configuration with optional validator
+ * @param rawOutput The raw string output from the LLM
+ * @returns The validated and typed data
+ * @throws StructuredOutputError if JSON parsing fails or validation fails
+ */
+export function parseStructured(config, 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 if validator is provided
+    if (config.validate) {
+        try {
+            return config.validate(parsed);
+        }
+        catch (error) {
+            const validationError = error instanceof Error ? error : new Error(String(error));
+            throw new StructuredOutputError(`Validation failed: ${validationError.message}`, { rawOutput, cause: validationError });
+        }
+    }
+    // No validator — return as-is (unsafe cast, user chose to skip validation)
+    return parsed;
+}
+/**
+ * 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 config The schema configuration with optional validator
+ * @param rawOutput The raw string output from the LLM
+ * @returns A result object: `{ ok: true, value }` on success, `{ ok: false, error, rawOutput }` on failure
+ */
+export function tryParseStructured(config, rawOutput) {
+    try {
+        const value = parseStructured(config, 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 using a SchemaConfig's validator.
+ *
+ * This is useful when you have already parsed JSON and need to validate it.
+ *
+ * @param config The schema configuration with optional validator
+ * @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 validation fails
+ */
+export function validateStructuredOutput(config, data, rawOutput) {
+    if (config.validate) {
+        try {
+            return config.validate(data);
+        }
+        catch (error) {
+            const rawData = rawOutput ?? JSON.stringify(data);
+            const validationError = error instanceof Error ? error : new Error(String(error));
+            throw new StructuredOutputError(`Validation failed: ${validationError.message}`, { rawOutput: rawData, cause: validationError });
+        }
+    }
+    return 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 = '';
+    validateFn;
+    constructor(config) {
+        this.validateFn = config.validate;
+    }
+    /**
+     * 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 validation, or undefined if not yet valid.
+     */
+    feed(chunk) {
+        this.buffer += chunk;
+        // Try to parse as complete JSON first
+        try {
+            const parsed = JSON.parse(this.buffer);
+            if (this.validateFn) {
+                try {
+                    const validated = this.validateFn(parsed);
+                    return { partial: validated, complete: true };
+                }
+                catch {
+                    // Validation failed on complete JSON — return parsed but not validated
+                }
+            }
+            return { partial: parsed, 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);
+            if (this.validateFn) {
+                try {
+                    return this.validateFn(parsed);
+                }
+                catch {
+                    // Partial validation failed — that's expected for partials
+                }
+            }
+            return parsed;
+        }
+        catch {
+            // Silently fail for partial JSON
+        }
+        return undefined;
+    }
+}
+//# 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/dist/zod-adapter.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Zod Adapter for Universal LLM Client
+ *
+ * Optional entrypoint for projects that use Zod for schema validation.
+ * Import from 'universal-llm-client/zod' to use.
+ *
+ * @module universal-llm-client/zod
+ */
+import { z } from 'zod';
+import type { SchemaConfig } from './structured-output.js';
+/**
+ * Create a SchemaConfig from a Zod schema.
+ *
+ * This bridges Zod's type-safe schema definitions to the library's
+ * generic SchemaConfig interface, using Zod 4's native `z.toJSONSchema()`.
+ *
+ * @template T The type inferred from the Zod schema
+ * @param schema The Zod schema
+ * @param options Optional name and description for LLM guidance
+ * @returns SchemaConfig ready for use with generateStructured, etc.
+ *
+ * @example
+ * ```typescript
+ * import { fromZod } from 'universal-llm-client/zod';
+ * import { z } from 'zod';
+ *
+ * const UserSchema = z.object({
+ *   name: z.string(),
+ *   age: z.number(),
+ * });
+ *
+ * const config = fromZod(UserSchema, { name: 'User' });
+ *
+ * const user = await model.generateStructured(config, messages);
+ * // user.name: string, user.age: number (fully typed)
+ * ```
+ */
+export declare function fromZod<T>(schema: z.ZodType<T>, options?: {
+    name?: string;
+    description?: string;
+}): SchemaConfig<T>;
+export { z } from 'zod';
+export type { SchemaConfig } from './structured-output.js';
+//# sourceMappingURL=zod-adapter.d.ts.map

package/dist/zod-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"zod-adapter.d.ts","sourceRoot":"","sources":["../src/zod-adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAE3D;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,OAAO,CAAC,CAAC,EACrB,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,EACpB,OAAO,CAAC,EAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAAE,GAClD,YAAY,CAAC,CAAC,CAAC,CAuBjB;AAGD,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,YAAY,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC"}

package/dist/zod-adapter.js

@@ -0,0 +1,61 @@
+/**
+ * Zod Adapter for Universal LLM Client
+ *
+ * Optional entrypoint for projects that use Zod for schema validation.
+ * Import from 'universal-llm-client/zod' to use.
+ *
+ * @module universal-llm-client/zod
+ */
+import { z } from 'zod';
+/**
+ * Create a SchemaConfig from a Zod schema.
+ *
+ * This bridges Zod's type-safe schema definitions to the library's
+ * generic SchemaConfig interface, using Zod 4's native `z.toJSONSchema()`.
+ *
+ * @template T The type inferred from the Zod schema
+ * @param schema The Zod schema
+ * @param options Optional name and description for LLM guidance
+ * @returns SchemaConfig ready for use with generateStructured, etc.
+ *
+ * @example
+ * ```typescript
+ * import { fromZod } from 'universal-llm-client/zod';
+ * import { z } from 'zod';
+ *
+ * const UserSchema = z.object({
+ *   name: z.string(),
+ *   age: z.number(),
+ * });
+ *
+ * const config = fromZod(UserSchema, { name: 'User' });
+ *
+ * const user = await model.generateStructured(config, messages);
+ * // user.name: string, user.age: number (fully typed)
+ * ```
+ */
+export function fromZod(schema, options) {
+    // Convert Zod schema to JSON Schema using Zod 4's native method
+    const rawJsonSchema = z.toJSONSchema(schema, {
+        target: 'draft-07',
+        unrepresentable: 'any',
+    });
+    // Clean up — remove $schema since providers don't need it
+    const jsonSchema = { ...rawJsonSchema };
+    delete jsonSchema.$schema;
+    return {
+        jsonSchema: jsonSchema,
+        validate: (data) => {
+            const result = schema.safeParse(data);
+            if (!result.success) {
+                throw result.error;
+            }
+            return result.data;
+        },
+        name: options?.name,
+        description: options?.description,
+    };
+}
+// Re-export z for convenience (users importing from /zod likely want it)
+export { z } from 'zod';
+//# sourceMappingURL=zod-adapter.js.map

package/dist/zod-adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"zod-adapter.js","sourceRoot":"","sources":["../src/zod-adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,UAAU,OAAO,CACnB,MAAoB,EACpB,OAAiD;IAEjD,gEAAgE;IAChE,MAAM,aAAa,GAAG,CAAC,CAAC,YAAY,CAAC,MAAM,EAAE;QACzC,MAAM,EAAE,UAAU;QAClB,eAAe,EAAE,KAAK;KACzB,CAAC,CAAC;IAEH,0DAA0D;IAC1D,MAAM,UAAU,GAAG,EAAE,GAAG,aAAa,EAA6B,CAAC;IACnE,OAAO,UAAU,CAAC,OAAO,CAAC;IAE1B,OAAO;QACH,UAAU,EAAE,UAAyD;QACrE,QAAQ,EAAE,CAAC,IAAa,EAAK,EAAE;YAC3B,MAAM,MAAM,GAAG,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;YACtC,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;gBAClB,MAAM,MAAM,CAAC,KAAK,CAAC;YACvB,CAAC;YACD,OAAO,MAAM,CAAC,IAAI,CAAC;QACvB,CAAC;QACD,IAAI,EAAE,OAAO,EAAE,IAAI;QACnB,WAAW,EAAE,OAAO,EAAE,WAAW;KACpC,CAAC;AACN,CAAC;AAED,yEAAyE;AACzE,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "universal-llm-client",
-  "version": "3.1.0",
+  "version": "4.1.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,10 +29,19 @@
     "./http": {
       "import": "./dist/http.js",
       "types": "./dist/http.d.ts"
+    },
+    "./structured-output": {
+      "import": "./dist/structured-output.js",
+      "types": "./dist/structured-output.d.ts"
+    },
+    "./zod": {
+      "import": "./dist/zod-adapter.js",
+      "types": "./dist/zod-adapter.d.ts"
     }
   },
   "files": [
     "dist",
+    "src",
     "README.md",
     "CHANGELOG.md",
     "LICENSE"
@@ -46,7 +55,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,14 +82,21 @@
   "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": {
       "optional": true
+    },
+    "zod": {
+      "optional": true
     }
   },
   "engines": {