@doclo/providers-llm 0.1.5

package/dist/index.d.ts

@@ -0,0 +1,1421 @@
+import { JSONSchemaType } from 'ajv';
+import { ObservabilityConfig, TraceContext } from '@doclo/core/observability';
+import { LLMJsonProvider, VLMProvider } from '@doclo/core';
+
+/** Unified internal schema (standard JSON Schema) */
+type UnifiedSchema<T = any> = JSONSchemaType<T>;
+/** Provider types - 'x-ai' is an alias for 'xai' */
+type ProviderType = 'openai' | 'anthropic' | 'google' | 'xai' | 'x-ai';
+/** Access method */
+type AccessMethod = 'openrouter' | 'native';
+/** Resource limit configuration (optional overrides for defaults) */
+interface ResourceLimits {
+    /**
+     * Maximum file size in bytes (default: 100MB)
+     *
+     * SECURITY WARNING: Increasing this limit can expose your application
+     * to memory exhaustion attacks. Only increase if you control the input sources.
+     */
+    maxFileSize?: number;
+    /**
+     * Request timeout in milliseconds (default: 30000ms / 30 seconds)
+     *
+     * SECURITY WARNING: Increasing this timeout can cause hung requests.
+     * Only increase for known slow endpoints (e.g., processing large files).
+     */
+    requestTimeout?: number;
+    /**
+     * Maximum JSON nesting depth (default: 100)
+     *
+     * SECURITY WARNING: Deeply nested JSON can cause stack overflows.
+     * Only increase if you're processing complex nested structures.
+     */
+    maxJsonDepth?: number;
+}
+/** Provider configuration */
+interface ProviderConfig {
+    provider: ProviderType;
+    model: string;
+    via?: AccessMethod;
+    apiKey: string;
+    baseUrl?: string;
+    limits?: ResourceLimits;
+}
+/** Fallback configuration */
+interface FallbackConfig {
+    providers: ProviderConfig[];
+    maxRetries: number;
+    primaryMaxRetries?: number;
+    retryDelay: number;
+    useExponentialBackoff: boolean;
+    circuitBreakerThreshold?: number;
+}
+/** Image input */
+interface ImageInput {
+    url?: string;
+    base64?: string;
+    mimeType: 'image/jpeg' | 'image/png' | 'image/webp' | 'image/gif';
+}
+/** PDF input */
+interface PDFInput {
+    url?: string;
+    base64?: string;
+    fileId?: string;
+}
+/** Multimodal input (unified) */
+interface MultimodalInput {
+    text?: string;
+    images?: ImageInput[];
+    pdfs?: PDFInput[];
+}
+/** Response metrics */
+interface ResponseMetrics {
+    costUSD?: number;
+    inputTokens?: number;
+    outputTokens?: number;
+    latencyMs: number;
+    attemptNumber: number;
+    provider: string;
+    model: string;
+    cacheCreationInputTokens?: number;
+    cacheReadInputTokens?: number;
+    httpStatusCode?: number;
+    httpMethod?: string;
+    httpUrl?: string;
+    responseId?: string;
+    finishReason?: string;
+    modelUsed?: string;
+}
+/** LLM response */
+interface LLMResponse<T = unknown> {
+    json: T;
+    rawText?: string;
+    metrics: ResponseMetrics;
+    reasoning?: string;
+    reasoning_details?: ReasoningDetail[];
+}
+/** Provider capability flags */
+interface ProviderCapabilities {
+    supportsStructuredOutput: boolean;
+    supportsStreaming: boolean;
+    supportsImages: boolean;
+    supportsPDFs: boolean;
+    maxPDFPages?: number;
+    maxPDFSize?: number;
+    maxContextTokens?: number;
+}
+/** JSON output mode */
+type JsonMode = 'strict' | 'relaxed';
+/** Provider interface */
+interface LLMProvider {
+    readonly name: string;
+    readonly capabilities: ProviderCapabilities;
+    completeJson<T>(params: {
+        input: MultimodalInput;
+        schema?: UnifiedSchema<T>;
+        mode?: JsonMode;
+        max_tokens?: number;
+        reasoning?: ReasoningConfig;
+        embedSchemaInPrompt?: boolean;
+    }): Promise<LLMResponse<T>>;
+}
+/** Reasoning configuration (normalized across providers) */
+interface ReasoningConfig {
+    effort?: 'low' | 'medium' | 'high';
+    exclude?: boolean;
+    enabled?: boolean;
+}
+/** Reasoning detail types (from OpenRouter API) */
+type ReasoningDetail = {
+    type: 'reasoning.summary';
+    summary: string;
+    id: string | null;
+    format: string;
+    index?: number;
+} | {
+    type: 'reasoning.encrypted';
+    data: string;
+    id: string | null;
+    format: string;
+    index?: number;
+} | {
+    type: 'reasoning.text';
+    text: string;
+    signature?: string | null;
+    id: string | null;
+    format: string;
+    index?: number;
+};
+/** Circuit breaker state */
+interface CircuitBreakerState {
+    consecutiveFailures: number;
+    lastFailureTime?: number;
+    isOpen: boolean;
+}
+
+/**
+ * Internal JSON Schema representation for schema translation.
+ * This is more flexible than JSONSchemaNode to accommodate:
+ * - Zod schema markers (~standard, _def)
+ * - Provider-specific extensions (propertyOrdering)
+ * - Intermediate conversion states
+ */
+interface FlexibleSchemaNode {
+    type?: string | string[];
+    properties?: Record<string, FlexibleSchemaNode>;
+    items?: FlexibleSchemaNode | FlexibleSchemaNode[];
+    required?: string[];
+    enum?: (string | number | boolean | null)[];
+    nullable?: boolean;
+    anyOf?: FlexibleSchemaNode[];
+    oneOf?: FlexibleSchemaNode[];
+    allOf?: FlexibleSchemaNode[];
+    additionalProperties?: boolean | FlexibleSchemaNode;
+    description?: string;
+    format?: string;
+    default?: unknown;
+    $schema?: string;
+    $defs?: Record<string, FlexibleSchemaNode>;
+    definitions?: Record<string, FlexibleSchemaNode>;
+    '~standard'?: {
+        vendor: string;
+        [key: string]: unknown;
+    };
+    _def?: unknown;
+    propertyOrdering?: string[];
+    [key: string]: unknown;
+}
+/**
+ * Translates unified JSON Schema to provider-specific formats
+ */
+declare class SchemaTranslator {
+    /**
+     * Unified → OpenAI/Grok (standard JSON Schema)
+     * OpenAI strict mode doesn't support nullable: true
+     * Must convert to anyOf: [{ type: "string" }, { type: "null" }]
+     */
+    toOpenAISchema<T>(schema: UnifiedSchema<T>): object;
+    /**
+     * Detect if schema is a Zod schema and convert to JSON Schema
+     * Public method to allow embedding schemas in prompts
+     */
+    convertZodIfNeeded(schema: FlexibleSchemaNode | unknown): FlexibleSchemaNode;
+    /**
+     * Convert nullable fields to anyOf format for OpenAI strict mode
+     * nullable: true is not supported, must use anyOf with null type
+     */
+    private convertNullableToAnyOf;
+    /**
+     * Unified → Claude (Tool Input Schema format)
+     * Claude requires tool calling with input_schema
+     * Claude supports nullable: true directly
+     */
+    toClaudeToolSchema<T>(schema: UnifiedSchema<T>): object;
+    /**
+     * Unified → Claude for OpenRouter
+     * When using Claude via OpenRouter, use anyOf format like OpenAI
+     */
+    toClaudeOpenRouterSchema<T>(schema: UnifiedSchema<T>): object;
+    /**
+     * Unified → Gemini (OpenAPI 3.0 subset with propertyOrdering)
+     * Gemini uses a subset of OpenAPI 3.0 schema
+     */
+    toGeminiSchema<T>(schema: UnifiedSchema<T>): object;
+    /**
+     * Convert individual property to Gemini format
+     */
+    private convertPropertyToGemini;
+}
+
+/**
+ * Utility for converting JSON Schema to human-readable prompt text
+ * that emphasizes exact field name requirements for structured extraction.
+ */
+/**
+ * JSON Schema type used for prompt formatting.
+ * Uses a recursive structure to support nested schemas.
+ */
+interface JSONSchema {
+    type?: string | string[];
+    properties?: Record<string, JSONSchema>;
+    items?: JSONSchema | JSONSchema[];
+    description?: string;
+    required?: string[];
+    enum?: (string | number | boolean | null)[];
+    anyOf?: JSONSchema[];
+    oneOf?: JSONSchema[];
+    allOf?: JSONSchema[];
+    format?: string;
+    [key: string]: unknown;
+}
+/**
+ * Formats a JSON Schema into prompt text that emphasizes exact field names.
+ * This helps LLMs understand they must use the exact field names specified
+ * in the schema, not invent their own based on document content.
+ */
+declare function formatSchemaForPrompt(schema: JSONSchema, indent?: number): string;
+/**
+ * Generates a complete prompt section with schema information and
+ * strict field name instructions.
+ */
+declare function buildSchemaPromptSection(schema: JSONSchema): string;
+/**
+ * Combines schema prompt section with user's custom prompt
+ */
+declare function combineSchemaAndUserPrompt(schema: JSONSchema, userPrompt: string): string;
+
+/**
+ * Factory function type for creating provider instances
+ */
+type ProviderFactory = (config: ProviderConfig) => LLMProvider;
+/**
+ * Provider registry for dynamic provider loading
+ *
+ * This allows provider packages to register themselves when imported,
+ * avoiding hardcoded imports in the core package.
+ */
+declare class ProviderRegistry {
+    private factories;
+    /**
+     * Register a provider factory
+     * Called by each provider package when it's imported
+     */
+    register(type: ProviderType, factory: ProviderFactory): void;
+    /**
+     * Check if a provider is registered
+     */
+    has(type: ProviderType): boolean;
+    /**
+     * Get a provider factory
+     */
+    get(type: ProviderType): ProviderFactory | undefined;
+    /**
+     * Create a provider instance
+     * @throws Error if provider is not registered
+     */
+    create(config: ProviderConfig): LLMProvider;
+    /**
+     * Get all registered provider types
+     */
+    getRegisteredTypes(): ProviderType[];
+    /**
+     * Clear all registrations (for testing)
+     */
+    clear(): void;
+}
+/**
+ * Global provider registry instance
+ */
+declare const providerRegistry: ProviderRegistry;
+/**
+ * Register a provider factory
+ * Convenience function for provider packages
+ */
+declare function registerProvider(type: ProviderType, factory: ProviderFactory): void;
+/**
+ * Create a provider instance from the registry
+ */
+declare function createProviderFromRegistry(config: ProviderConfig): LLMProvider;
+
+declare class OpenAIProvider implements LLMProvider {
+    readonly name: string;
+    readonly capabilities: ProviderCapabilities;
+    private config;
+    private translator;
+    private limits;
+    constructor(config: ProviderConfig);
+    completeJson<T>(params: {
+        input: MultimodalInput;
+        schema?: UnifiedSchema<T>;
+        mode?: JsonMode;
+        max_tokens?: number;
+        reasoning?: ReasoningConfig;
+        embedSchemaInPrompt?: boolean;
+    }): Promise<LLMResponse<T>>;
+    private buildReasoningConfig;
+    private buildMessages;
+    /**
+     * Extract base64 data from a data URL or return as-is if already raw base64
+     */
+    private extractBase64;
+    private calculateCost;
+}
+
+declare class AnthropicProvider implements LLMProvider {
+    readonly name: string;
+    readonly capabilities: ProviderCapabilities;
+    private config;
+    private translator;
+    private limits;
+    constructor(config: ProviderConfig);
+    completeJson<T>(params: {
+        input: MultimodalInput;
+        schema?: UnifiedSchema<T>;
+        mode?: JsonMode;
+        max_tokens?: number;
+        reasoning?: ReasoningConfig;
+        embedSchemaInPrompt?: boolean;
+    }): Promise<LLMResponse<T>>;
+    private buildNativeThinkingConfig;
+    private translateToOpenRouterFormat;
+    private buildReasoningConfig;
+    private supportsNewStructuredOutputs;
+    private fixSchemaForStrictMode;
+    private buildMessages;
+    private urlToBase64;
+    /**
+     * Extract base64 data from a data URL or return as-is if already raw base64
+     */
+    private extractBase64;
+    private calculateCost;
+    /**
+     * Detect if a parsed JSON object looks like unwrapped JSON Schema properties
+     * (e.g., missing the root "type": "object" and "properties": {...} wrapper)
+     */
+    private looksLikeUnwrappedProperties;
+    /**
+     * Wrap unwrapped properties into a proper JSON Schema structure
+     */
+    private wrapAsSchema;
+}
+
+declare class GoogleProvider implements LLMProvider {
+    readonly name: string;
+    readonly capabilities: ProviderCapabilities;
+    private config;
+    private translator;
+    private limits;
+    constructor(config: ProviderConfig);
+    completeJson<T>(params: {
+        input: MultimodalInput;
+        schema?: UnifiedSchema<T>;
+        mode?: JsonMode;
+        max_tokens?: number;
+        reasoning?: ReasoningConfig;
+        embedSchemaInPrompt?: boolean;
+    }): Promise<LLMResponse<T>>;
+    private buildNativeThinkingConfig;
+    private translateToOpenRouterFormat;
+    private buildReasoningConfig;
+    private buildContents;
+    private urlToBase64;
+    /**
+     * Extract base64 data from a data URL or return as-is if already raw base64
+     */
+    private extractBase64;
+    private calculateCost;
+}
+
+declare class XAIProvider implements LLMProvider {
+    readonly name: string;
+    readonly capabilities: ProviderCapabilities;
+    private config;
+    private translator;
+    private limits;
+    constructor(config: ProviderConfig);
+    completeJson<T>(params: {
+        input: MultimodalInput;
+        schema?: UnifiedSchema<T>;
+        mode?: JsonMode;
+        max_tokens?: number;
+        reasoning?: ReasoningConfig;
+        embedSchemaInPrompt?: boolean;
+    }): Promise<LLMResponse<T>>;
+    private buildReasoningConfig;
+    private buildMessages;
+    /**
+     * Extract base64 data from a data URL or return as-is if already raw base64
+     */
+    private extractBase64;
+    private calculateCost;
+}
+
+declare class FallbackManager {
+    private config;
+    private circuitBreakers;
+    constructor(config: FallbackConfig);
+    executeWithFallback<T>(input: MultimodalInput, schema: UnifiedSchema<T>, max_tokens?: number, reasoning?: ReasoningConfig, mode?: JsonMode, observability?: {
+        config?: ObservabilityConfig;
+        flowId?: string;
+        executionId?: string;
+        stepId?: string;
+        traceContext?: TraceContext;
+        metadata?: Record<string, unknown>;
+    }): Promise<LLMResponse<T>>;
+    private createProvider;
+    private validateResponse;
+    private isRetryable;
+    private calculateDelay;
+    private sleep;
+    private isCircuitOpen;
+    private recordSuccess;
+    private recordFailure;
+}
+
+/**
+ * Adapter to make new LLMProvider compatible with core LLMJsonProvider interface
+ */
+declare function adaptToCoreLLMProvider(provider: LLMProvider): LLMJsonProvider;
+
+/**
+ * LLM Provider Metadata
+ *
+ * Comprehensive metadata for all LLM/VLM providers including:
+ * - Supported file types (inline/base64 encoded)
+ * - Input/output formats
+ * - Pricing
+ * - Capabilities
+ * - Native API vs OpenRouter differences
+ */
+declare const SUPPORTED_IMAGE_TYPES: {
+    readonly COMMON: readonly ["image/png", "image/jpeg", "image/webp", "image/gif"];
+    readonly EXTENDED: readonly ["image/png", "image/jpeg", "image/webp", "image/gif", "image/bmp", "image/tiff", "image/heif"];
+};
+/**
+ * Input type requirements for providers.
+ * - 'raw-document': Needs FlowInput with base64/url
+ * - 'parsed-text': Needs DocumentIR text output
+ * - 'any': Can work with either (LLM providers with vision)
+ */
+type ProviderInputType = 'raw-document' | 'parsed-text' | 'any';
+/**
+ * Model-level metadata for per-model capability overrides
+ */
+type LLMModelMetadata = {
+    /** Model ID as used in API calls */
+    id: string;
+    /** Human-readable name */
+    name?: string;
+    /** OpenRouter model ID (e.g., 'openai/gpt-4.1') */
+    openRouterId: string;
+    /** Capability overrides (inherit from provider if unset) */
+    capabilities?: {
+        supportsReasoning?: boolean;
+        supportsImages?: boolean;
+        supportsPDFs?: boolean;
+        supportsStructuredOutput?: boolean;
+    };
+    /** Model-specific limits */
+    limits?: {
+        maxContextTokens?: number;
+        maxOutputTokens?: number;
+    };
+    /** Model-specific pricing (USD per 1k tokens) */
+    pricing?: {
+        inputPer1k?: number;
+        outputPer1k?: number;
+    };
+};
+type LLMProviderMetadata = {
+    id: string;
+    name: string;
+    vendor: 'openai' | 'anthropic' | 'google' | 'xai';
+    models: string[];
+    /**
+     * Detailed per-model metadata with capability overrides.
+     * Use this for model-specific reasoning, pricing, and limits.
+     */
+    detailedModels?: LLMModelMetadata[];
+    accessMethods: {
+        native: {
+            available: boolean;
+            endpoint: string;
+            requiresApiKey: boolean;
+        };
+        openrouter: {
+            available: boolean;
+            modelPrefix: string;
+        };
+    };
+    capabilities: {
+        supportsImages: boolean;
+        supportsPDFs: boolean;
+        supportsReasoning: boolean;
+        supportsStreaming: boolean;
+        supportsStructuredOutput: boolean;
+    };
+    /**
+     * Input requirements for this provider.
+     * LLM providers with vision can accept either raw documents OR parsed text.
+     */
+    inputRequirements?: {
+        inputType: ProviderInputType;
+        acceptedMethods?: readonly ('url' | 'base64')[];
+    };
+    compatibleNodes: {
+        parse: boolean;
+        extract: boolean;
+        categorize: boolean;
+        qualify: boolean;
+        split: boolean;
+    };
+    inputFormats: {
+        images: {
+            mimeTypes: readonly string[];
+            methods: ('url' | 'base64')[];
+            maxSize?: number;
+            maxDimensions?: {
+                width: number;
+                height: number;
+            };
+            notes?: string;
+        };
+        pdfs: {
+            supported: boolean;
+            methods: ('url' | 'base64' | 'fileId')[];
+            maxSize?: number;
+            maxPages?: number;
+            notes?: string;
+        };
+    };
+    outputFormat: {
+        supportsJSON: boolean;
+        supportsReasoning: boolean;
+        tokenTracking: boolean;
+        costTracking: boolean;
+    };
+    pricing: {
+        model: 'per-token';
+        inputPer1k: number;
+        outputPer1k: number;
+        currency: 'USD';
+        notes?: string;
+    };
+    limits: {
+        maxContextTokens: number;
+        maxOutputTokens?: number;
+        requestsPerMinute?: number;
+    };
+    nativeAPI: {
+        imageFormat: string;
+        pdfFormat: string;
+        reasoningConfig: string;
+    };
+    openRouterAPI: {
+        imageFormat: string;
+        pdfFormat: string;
+        reasoningConfig: string;
+        differences: string[];
+    };
+};
+declare const PROVIDER_METADATA: {
+    readonly openai: {
+        readonly id: "openai";
+        readonly name: "OpenAI";
+        readonly vendor: "openai";
+        readonly models: ["gpt-5.1", "gpt-4.1", "gpt-4.1-mini", "o3", "o3-mini", "o4-mini"];
+        readonly detailedModels: [{
+            readonly id: "gpt-4.1";
+            readonly name: "GPT-4.1";
+            readonly openRouterId: "openai/gpt-4.1";
+            readonly capabilities: {
+                readonly supportsReasoning: false;
+            };
+            readonly limits: {
+                readonly maxContextTokens: 128000;
+                readonly maxOutputTokens: 16384;
+            };
+            readonly pricing: {
+                readonly inputPer1k: 0.002;
+                readonly outputPer1k: 0.008;
+            };
+        }, {
+            readonly id: "gpt-4.1-mini";
+            readonly name: "GPT-4.1 Mini";
+            readonly openRouterId: "openai/gpt-4.1-mini";
+            readonly capabilities: {
+                readonly supportsReasoning: false;
+            };
+            readonly limits: {
+                readonly maxContextTokens: 128000;
+                readonly maxOutputTokens: 16384;
+            };
+            readonly pricing: {
+                readonly inputPer1k: 0.0004;
+                readonly outputPer1k: 0.0016;
+            };
+        }, {
+            readonly id: "o3";
+            readonly name: "o3";
+            readonly openRouterId: "openai/o3";
+            readonly capabilities: {
+                readonly supportsReasoning: true;
+            };
+            readonly limits: {
+                readonly maxContextTokens: 200000;
+                readonly maxOutputTokens: 100000;
+            };
+            readonly pricing: {
+                readonly inputPer1k: 0.01;
+                readonly outputPer1k: 0.04;
+            };
+        }, {
+            readonly id: "o3-mini";
+            readonly name: "o3-mini";
+            readonly openRouterId: "openai/o3-mini";
+            readonly capabilities: {
+                readonly supportsReasoning: true;
+            };
+            readonly limits: {
+                readonly maxContextTokens: 200000;
+                readonly maxOutputTokens: 100000;
+            };
+            readonly pricing: {
+                readonly inputPer1k: 0.0011;
+                readonly outputPer1k: 0.0044;
+            };
+        }, {
+            readonly id: "o4-mini";
+            readonly name: "o4-mini";
+            readonly openRouterId: "openai/o4-mini";
+            readonly capabilities: {
+                readonly supportsReasoning: true;
+            };
+            readonly limits: {
+                readonly maxContextTokens: 200000;
+                readonly maxOutputTokens: 100000;
+            };
+            readonly pricing: {
+                readonly inputPer1k: 0.0011;
+                readonly outputPer1k: 0.0044;
+            };
+        }, {
+            readonly id: "gpt-5.1";
+            readonly name: "GPT-5.1";
+            readonly openRouterId: "openai/gpt-5.1";
+            readonly capabilities: {
+                readonly supportsReasoning: true;
+            };
+            readonly limits: {
+                readonly maxContextTokens: 256000;
+                readonly maxOutputTokens: 32768;
+            };
+            readonly pricing: {
+                readonly inputPer1k: 0.005;
+                readonly outputPer1k: 0.015;
+            };
+        }];
+        readonly accessMethods: {
+            readonly native: {
+                readonly available: true;
+                readonly endpoint: "https://api.openai.com/v1";
+                readonly requiresApiKey: true;
+            };
+            readonly openrouter: {
+                readonly available: true;
+                readonly modelPrefix: "openai/";
+            };
+        };
+        readonly capabilities: {
+            readonly supportsImages: true;
+            readonly supportsPDFs: true;
+            readonly supportsReasoning: true;
+            readonly supportsStreaming: true;
+            readonly supportsStructuredOutput: true;
+        };
+        readonly inputRequirements: {
+            readonly inputType: "any";
+            readonly acceptedMethods: readonly ["url", "base64"];
+        };
+        readonly compatibleNodes: {
+            readonly parse: true;
+            readonly extract: true;
+            readonly categorize: true;
+            readonly qualify: true;
+            readonly split: true;
+        };
+        readonly inputFormats: {
+            readonly images: {
+                readonly mimeTypes: readonly ["image/png", "image/jpeg", "image/webp", "image/gif"];
+                readonly methods: ["url", "base64"];
+                readonly maxSize: 20;
+                readonly maxDimensions: undefined;
+                readonly notes: "Inline via image_url with data URL or HTTP URL. Large images auto-resized.";
+            };
+            readonly pdfs: {
+                readonly supported: true;
+                readonly methods: ["base64", "fileId"];
+                readonly maxSize: 50;
+                readonly maxPages: 100;
+                readonly notes: "Inline via type: file with base64, or via Files API. Extracts text + images of each page. File URLs NOT supported for chat completions.";
+            };
+        };
+        readonly outputFormat: {
+            readonly supportsJSON: true;
+            readonly supportsReasoning: true;
+            readonly tokenTracking: true;
+            readonly costTracking: true;
+        };
+        readonly pricing: {
+            readonly model: "per-token";
+            readonly inputPer1k: 0.005;
+            readonly outputPer1k: 0.015;
+            readonly currency: "USD";
+            readonly notes: "Cost calculated from tokens. OpenRouter may include cost in response. GPT-4.1 baseline.";
+        };
+        readonly limits: {
+            readonly maxContextTokens: 128000;
+            readonly maxOutputTokens: 16384;
+            readonly requestsPerMinute: undefined;
+        };
+        readonly nativeAPI: {
+            readonly imageFormat: "type: \"image_url\", image_url: { url: \"data:image/jpeg;base64,...\" }";
+            readonly pdfFormat: "type: \"file\", file: { file_id: \"...\" } OR file: { filename: \"...\", file_data: \"data:application/pdf;base64,...\" }";
+            readonly reasoningConfig: "reasoning: { effort: \"low\"|\"medium\"|\"high\", exclude?: boolean }";
+        };
+        readonly openRouterAPI: {
+            readonly imageFormat: "Same as native (OpenAI-compatible)";
+            readonly pdfFormat: "Same as native (OpenAI-compatible)";
+            readonly reasoningConfig: "Same as native (OpenAI-compatible)";
+            readonly differences: ["File URLs not supported (base64 only)", "Cost may be available via usage.total_cost or generation endpoint"];
+        };
+    };
+    readonly anthropic: {
+        readonly id: "anthropic";
+        readonly name: "Anthropic (Claude)";
+        readonly vendor: "anthropic";
+        readonly models: ["claude-opus-4.5", "claude-sonnet-4.5", "claude-haiku-4.5", "claude-opus-4", "claude-sonnet-4"];
+        readonly detailedModels: [{
+            readonly id: "claude-opus-4.5";
+            readonly name: "Claude Opus 4.5";
+            readonly openRouterId: "anthropic/claude-opus-4.5";
+            readonly capabilities: {
+                readonly supportsReasoning: true;
+            };
+            readonly limits: {
+                readonly maxContextTokens: 200000;
+                readonly maxOutputTokens: 32000;
+            };
+            readonly pricing: {
+                readonly inputPer1k: 0.015;
+                readonly outputPer1k: 0.075;
+            };
+        }, {
+            readonly id: "claude-sonnet-4.5";
+            readonly name: "Claude Sonnet 4.5";
+            readonly openRouterId: "anthropic/claude-sonnet-4.5";
+            readonly capabilities: {
+                readonly supportsReasoning: true;
+            };
+            readonly limits: {
+                readonly maxContextTokens: 200000;
+                readonly maxOutputTokens: 16000;
+            };
+            readonly pricing: {
+                readonly inputPer1k: 0.003;
+                readonly outputPer1k: 0.015;
+            };
+        }, {
+            readonly id: "claude-haiku-4.5";
+            readonly name: "Claude Haiku 4.5";
+            readonly openRouterId: "anthropic/claude-haiku-4.5";
+            readonly capabilities: {
+                readonly supportsReasoning: true;
+            };
+            readonly limits: {
+                readonly maxContextTokens: 200000;
+                readonly maxOutputTokens: 8192;
+            };
+            readonly pricing: {
+                readonly inputPer1k: 0.0008;
+                readonly outputPer1k: 0.004;
+            };
+        }, {
+            readonly id: "claude-opus-4";
+            readonly name: "Claude Opus 4";
+            readonly openRouterId: "anthropic/claude-opus-4";
+            readonly capabilities: {
+                readonly supportsReasoning: true;
+            };
+            readonly limits: {
+                readonly maxContextTokens: 200000;
+                readonly maxOutputTokens: 32000;
+            };
+            readonly pricing: {
+                readonly inputPer1k: 0.015;
+                readonly outputPer1k: 0.075;
+            };
+        }, {
+            readonly id: "claude-sonnet-4";
+            readonly name: "Claude Sonnet 4";
+            readonly openRouterId: "anthropic/claude-sonnet-4";
+            readonly capabilities: {
+                readonly supportsReasoning: true;
+            };
+            readonly limits: {
+                readonly maxContextTokens: 200000;
+                readonly maxOutputTokens: 16000;
+            };
+            readonly pricing: {
+                readonly inputPer1k: 0.003;
+                readonly outputPer1k: 0.015;
+            };
+        }];
+        readonly accessMethods: {
+            readonly native: {
+                readonly available: true;
+                readonly endpoint: "https://api.anthropic.com/v1";
+                readonly requiresApiKey: true;
+            };
+            readonly openrouter: {
+                readonly available: true;
+                readonly modelPrefix: "anthropic/";
+            };
+        };
+        readonly capabilities: {
+            readonly supportsImages: true;
+            readonly supportsPDFs: true;
+            readonly supportsReasoning: true;
+            readonly supportsStreaming: true;
+            readonly supportsStructuredOutput: true;
+        };
+        readonly inputRequirements: {
+            readonly inputType: "any";
+            readonly acceptedMethods: readonly ["base64"];
+        };
+        readonly compatibleNodes: {
+            readonly parse: true;
+            readonly extract: true;
+            readonly categorize: true;
+            readonly qualify: true;
+            readonly split: true;
+        };
+        readonly inputFormats: {
+            readonly images: {
+                readonly mimeTypes: readonly ["image/png", "image/jpeg", "image/webp", "image/gif"];
+                readonly methods: ["base64"];
+                readonly maxSize: 5;
+                readonly maxDimensions: {
+                    readonly width: 8000;
+                    readonly height: 8000;
+                };
+                readonly notes: "Native API requires base64. Max 100 images/request. Optimal at 1568px max dimension.";
+            };
+            readonly pdfs: {
+                readonly supported: true;
+                readonly methods: ["base64", "fileId"];
+                readonly maxSize: 32;
+                readonly maxPages: 100;
+                readonly notes: "Inline via type: document with base64, or via Files API (beta). PDFs over 100 pages: text-only processing.";
+            };
+        };
+        readonly outputFormat: {
+            readonly supportsJSON: true;
+            readonly supportsReasoning: true;
+            readonly tokenTracking: true;
+            readonly costTracking: true;
+        };
+        readonly pricing: {
+            readonly model: "per-token";
+            readonly inputPer1k: 0.003;
+            readonly outputPer1k: 0.015;
+            readonly currency: "USD";
+            readonly notes: "Cost calculated from tokens. OpenRouter may include cost in response. Claude 3.5 Sonnet baseline.";
+        };
+        readonly limits: {
+            readonly maxContextTokens: 200000;
+            readonly maxOutputTokens: 8192;
+            readonly requestsPerMinute: undefined;
+        };
+        readonly nativeAPI: {
+            readonly imageFormat: "type: \"image\", source: { type: \"base64\", media_type: \"image/jpeg\", data: \"...\" }";
+            readonly pdfFormat: "type: \"document\", source: { type: \"base64\"|\"file\", media_type: \"application/pdf\", data: \"...\" | file_id: \"...\" }";
+            readonly reasoningConfig: "thinking: { type: \"enabled\", budget_tokens: 1024-32000 }";
+        };
+        readonly openRouterAPI: {
+            readonly imageFormat: "type: \"image_url\", image_url: { url: \"data:image/jpeg;base64,...\" }";
+            readonly pdfFormat: "type: \"file\", file: { filename: \"...\", file_data: \"data:application/pdf;base64,...\" }";
+            readonly reasoningConfig: "reasoning: { max_tokens: number, exclude?: boolean }";
+            readonly differences: ["Uses OpenAI-compatible format (image_url, file types)", "Reasoning uses max_tokens instead of budget_tokens", "Response prefill trick ({ role: \"assistant\", content: \"{\" }) for strict JSON", "Tool calling instead of native structured output"];
+        };
+    };
+    readonly google: {
+        readonly id: "google";
+        readonly name: "Google (Gemini)";
+        readonly vendor: "google";
+        readonly models: ["gemini-3-pro", "gemini-2.5-pro", "gemini-2.5-flash", "gemini-2.5-flash-lite"];
+        readonly detailedModels: [{
+            readonly id: "gemini-3-pro";
+            readonly name: "Gemini 3 Pro";
+            readonly openRouterId: "google/gemini-3-pro";
+            readonly capabilities: {
+                readonly supportsReasoning: true;
+            };
+            readonly limits: {
+                readonly maxContextTokens: 1000000;
+                readonly maxOutputTokens: 65536;
+            };
+            readonly pricing: {
+                readonly inputPer1k: 0.00125;
+                readonly outputPer1k: 0.005;
+            };
+        }, {
+            readonly id: "gemini-2.5-pro";
+            readonly name: "Gemini 2.5 Pro";
+            readonly openRouterId: "google/gemini-2.5-pro-preview-06-05";
+            readonly capabilities: {
+                readonly supportsReasoning: true;
+            };
+            readonly limits: {
+                readonly maxContextTokens: 1000000;
+                readonly maxOutputTokens: 65536;
+            };
+            readonly pricing: {
+                readonly inputPer1k: 0.00125;
+                readonly outputPer1k: 0.005;
+            };
+        }, {
+            readonly id: "gemini-2.5-flash";
+            readonly name: "Gemini 2.5 Flash";
+            readonly openRouterId: "google/gemini-2.5-flash-preview-09-2025";
+            readonly capabilities: {
+                readonly supportsReasoning: false;
+            };
+            readonly limits: {
+                readonly maxContextTokens: 1000000;
+                readonly maxOutputTokens: 8192;
+            };
+            readonly pricing: {
+                readonly inputPer1k: 0.00015;
+                readonly outputPer1k: 0.0006;
+            };
+        }, {
+            readonly id: "gemini-2.5-flash-lite";
+            readonly name: "Gemini 2.5 Flash Lite";
+            readonly openRouterId: "google/gemini-2.5-flash-lite";
+            readonly capabilities: {
+                readonly supportsReasoning: false;
+            };
+            readonly limits: {
+                readonly maxContextTokens: 1000000;
+                readonly maxOutputTokens: 8192;
+            };
+            readonly pricing: {
+                readonly inputPer1k: 0.000075;
+                readonly outputPer1k: 0.0003;
+            };
+        }];
+        readonly accessMethods: {
+            readonly native: {
+                readonly available: true;
+                readonly endpoint: "https://generativelanguage.googleapis.com/v1beta";
+                readonly requiresApiKey: true;
+            };
+            readonly openrouter: {
+                readonly available: true;
+                readonly modelPrefix: "google/";
+            };
+        };
+        readonly capabilities: {
+            readonly supportsImages: true;
+            readonly supportsPDFs: true;
+            readonly supportsReasoning: true;
+            readonly supportsStreaming: true;
+            readonly supportsStructuredOutput: true;
+        };
+        readonly inputRequirements: {
+            readonly inputType: "any";
+            readonly acceptedMethods: readonly ["base64"];
+        };
+        readonly compatibleNodes: {
+            readonly parse: true;
+            readonly extract: true;
+            readonly categorize: true;
+            readonly qualify: true;
+            readonly split: true;
+        };
+        readonly inputFormats: {
+            readonly images: {
+                readonly mimeTypes: readonly ["image/png", "image/jpeg", "image/webp", "image/gif", "image/bmp", "image/tiff", "image/heif"];
+                readonly methods: ["base64"];
+                readonly maxSize: 20;
+                readonly maxDimensions: {
+                    readonly width: 3072;
+                    readonly height: 3072;
+                };
+                readonly notes: "Inline via inlineData. Max 3000 images/request. File API supports larger files (stored 48 hours).";
+            };
+            readonly pdfs: {
+                readonly supported: true;
+                readonly methods: ["base64", "fileId"];
+                readonly maxSize: 50;
+                readonly maxPages: 1000;
+                readonly notes: "Inline via inlineData OR File API. Pages scaled to 3072x3072 max. Native text not charged.";
+            };
+        };
+        readonly outputFormat: {
+            readonly supportsJSON: true;
+            readonly supportsReasoning: true;
+            readonly tokenTracking: true;
+            readonly costTracking: true;
+        };
+        readonly pricing: {
+            readonly model: "per-token";
+            readonly inputPer1k: 0.00025;
+            readonly outputPer1k: 0.001;
+            readonly currency: "USD";
+            readonly notes: "Cost calculated from tokens. OpenRouter may include cost in response. Gemini 2.5 Flash baseline.";
+        };
+        readonly limits: {
+            readonly maxContextTokens: 1000000;
+            readonly maxOutputTokens: 8192;
+            readonly requestsPerMinute: undefined;
+        };
+        readonly nativeAPI: {
+            readonly imageFormat: "inlineData: { mimeType: \"image/jpeg\", data: \"...\" }";
+            readonly pdfFormat: "inlineData: { mimeType: \"application/pdf\", data: \"...\" } OR fileData: { fileUri: \"...\", mimeType: \"application/pdf\" }";
+            readonly reasoningConfig: "generationConfig.thinking_config: { thinking_budget: number } (max 24576)";
+        };
+        readonly openRouterAPI: {
+            readonly imageFormat: "type: \"image_url\", image_url: { url: \"data:image/jpeg;base64,...\" }";
+            readonly pdfFormat: "type: \"file\", file: { filename: \"...\", file_data: \"data:application/pdf;base64,...\" }";
+            readonly reasoningConfig: "reasoning: { max_tokens: number, exclude?: boolean }";
+            readonly differences: ["Uses OpenAI-compatible format instead of parts/inlineData", "Reasoning uses max_tokens instead of thinking_budget", "Different content structure (messages vs contents.parts)"];
+        };
+    };
+    readonly xai: {
+        readonly id: "xai";
+        readonly name: "xAI (Grok)";
+        readonly vendor: "xai";
+        readonly models: ["grok-4.1", "grok-4.1-fast", "grok-4", "grok-4-fast"];
+        readonly detailedModels: [{
+            readonly id: "grok-4.1";
+            readonly name: "Grok 4.1";
+            readonly openRouterId: "x-ai/grok-4.1";
+            readonly capabilities: {
+                readonly supportsReasoning: true;
+            };
+            readonly limits: {
+                readonly maxContextTokens: 256000;
+                readonly maxOutputTokens: 32768;
+            };
+            readonly pricing: {
+                readonly inputPer1k: 0.003;
+                readonly outputPer1k: 0.015;
+            };
+        }, {
+            readonly id: "grok-4.1-fast";
+            readonly name: "Grok 4.1 Fast";
+            readonly openRouterId: "x-ai/grok-4.1-fast";
+            readonly capabilities: {
+                readonly supportsReasoning: false;
+            };
+            readonly limits: {
+                readonly maxContextTokens: 2000000;
+                readonly maxOutputTokens: 32768;
+            };
+            readonly pricing: {
+                readonly inputPer1k: 0.005;
+                readonly outputPer1k: 0.025;
+            };
+        }, {
+            readonly id: "grok-4";
+            readonly name: "Grok 4";
+            readonly openRouterId: "x-ai/grok-4";
+            readonly capabilities: {
+                readonly supportsReasoning: true;
+            };
+            readonly limits: {
+                readonly maxContextTokens: 256000;
+                readonly maxOutputTokens: 32768;
+            };
+            readonly pricing: {
+                readonly inputPer1k: 0.003;
+                readonly outputPer1k: 0.015;
+            };
+        }, {
+            readonly id: "grok-4-fast";
+            readonly name: "Grok 4 Fast";
+            readonly openRouterId: "x-ai/grok-4-fast";
+            readonly capabilities: {
+                readonly supportsReasoning: false;
+            };
+            readonly limits: {
+                readonly maxContextTokens: 2000000;
+                readonly maxOutputTokens: 32768;
+            };
+            readonly pricing: {
+                readonly inputPer1k: 0.005;
+                readonly outputPer1k: 0.025;
+            };
+        }];
+        readonly accessMethods: {
+            readonly native: {
+                readonly available: true;
+                readonly endpoint: "https://api.x.ai/v1";
+                readonly requiresApiKey: true;
+            };
+            readonly openrouter: {
+                readonly available: true;
+                readonly modelPrefix: "xai/";
+            };
+        };
+        readonly capabilities: {
+            readonly supportsImages: true;
+            readonly supportsPDFs: true;
+            readonly supportsReasoning: true;
+            readonly supportsStreaming: false;
+            readonly supportsStructuredOutput: true;
+        };
+        readonly inputRequirements: {
+            readonly inputType: "any";
+            readonly acceptedMethods: readonly ["url", "base64"];
+        };
+        readonly compatibleNodes: {
+            readonly parse: true;
+            readonly extract: true;
+            readonly categorize: true;
+            readonly qualify: true;
+            readonly split: true;
+        };
+        readonly inputFormats: {
+            readonly images: {
+                readonly mimeTypes: readonly ["image/jpeg", "image/png"];
+                readonly methods: ["url", "base64"];
+                readonly maxSize: 30;
+                readonly maxDimensions: undefined;
+                readonly notes: "OpenAI-compatible format. Max 10 images via API. Only JPEG/PNG supported.";
+            };
+            readonly pdfs: {
+                readonly supported: true;
+                readonly methods: ["url", "base64"];
+                readonly maxSize: 30;
+                readonly maxPages: undefined;
+                readonly notes: "OpenAI-compatible format. Inline via type: file. Also supports DOCX, TXT, MD, CSV.";
+            };
+        };
+        readonly outputFormat: {
+            readonly supportsJSON: true;
+            readonly supportsReasoning: true;
+            readonly tokenTracking: true;
+            readonly costTracking: true;
+        };
+        readonly pricing: {
+            readonly model: "per-token";
+            readonly inputPer1k: 0.005;
+            readonly outputPer1k: 0.015;
+            readonly currency: "USD";
+            readonly notes: "Cost calculated from tokens. OpenRouter may include cost in response. Grok-4 baseline.";
+        };
+        readonly limits: {
+            readonly maxContextTokens: 131072;
+            readonly maxOutputTokens: undefined;
+            readonly requestsPerMinute: undefined;
+        };
+        readonly nativeAPI: {
+            readonly imageFormat: "type: \"image_url\", image_url: { url: \"data:image/jpeg;base64,...\" }";
+            readonly pdfFormat: "type: \"file\", file: { filename: \"...\", file_data: \"data:application/pdf;base64,...\" }";
+            readonly reasoningConfig: "reasoning: { effort: \"low\"|\"medium\"|\"high\", exclude?: boolean }";
+        };
+        readonly openRouterAPI: {
+            readonly imageFormat: "Same as native (OpenAI-compatible)";
+            readonly pdfFormat: "Same as native (OpenAI-compatible)";
+            readonly reasoningConfig: "Same as native (OpenAI-compatible)";
+            readonly differences: ["Minimal differences - xAI uses OpenAI-compatible format", "Cost tracking via usage.total_cost field in OpenRouter"];
+        };
+    };
+};
+/**
+ * Check if an image MIME type is supported by a provider
+ *
+ * @param providerId - Provider ID
+ * @param mimeType - MIME type to check
+ * @returns True if supported
+ *
+ * @example
+ * ```typescript
+ * isImageTypeSupported('openai', 'image/png')  // true
+ * isImageTypeSupported('openai', 'image/bmp')  // false
+ * isImageTypeSupported('google', 'image/bmp')  // true
+ * ```
+ */
+declare function isImageTypeSupported(providerId: keyof typeof PROVIDER_METADATA, mimeType: string): boolean;
+/**
+ * Check if a provider supports PDFs inline (base64)
+ *
+ * @param providerId - Provider ID
+ * @returns True if inline PDFs are supported
+ *
+ * @example
+ * ```typescript
+ * supportsPDFsInline('openai')     // true
+ * supportsPDFsInline('anthropic')  // true
+ * supportsPDFsInline('google')     // true
+ * ```
+ */
+declare function supportsPDFsInline(providerId: keyof typeof PROVIDER_METADATA): boolean;
+/**
+ * Get providers compatible with a specific node type
+ *
+ * @param nodeType - Node type to check
+ * @returns Array of compatible provider metadata
+ *
+ * @example
+ * ```typescript
+ * // Get providers that work with parse()
+ * const parseProviders = getProvidersForNode('parse');
+ * // Returns: [openai, anthropic, google, xai] (all VLM providers)
+ *
+ * // Get providers that work with extract()
+ * const extractProviders = getProvidersForNode('extract');
+ * // Returns: [openai, anthropic, google, xai] (all VLM providers)
+ * ```
+ */
+declare function getProvidersForNode(nodeType: 'parse' | 'extract' | 'categorize' | 'qualify' | 'split'): LLMProviderMetadata[];
+/**
+ * Check if a provider is compatible with a node type
+ *
+ * @param providerId - Provider ID
+ * @param nodeType - Node type to check
+ * @returns True if compatible
+ *
+ * @example
+ * ```typescript
+ * isProviderCompatibleWithNode('openai', 'parse');      // true
+ * isProviderCompatibleWithNode('openai', 'extract');    // true
+ * isProviderCompatibleWithNode('anthropic', 'qualify'); // true
+ * ```
+ */
+declare function isProviderCompatibleWithNode(providerId: keyof typeof PROVIDER_METADATA, nodeType: 'parse' | 'extract' | 'categorize' | 'qualify' | 'split'): boolean;
+/**
+ * Estimate cost for a request
+ *
+ * @param providerId - Provider ID
+ * @param inputTokens - Number of input tokens
+ * @param outputTokens - Number of output tokens
+ * @returns Estimated cost in USD
+ *
+ * @example
+ * ```typescript
+ * const cost = estimateCost('openai', 1000, 500);
+ * console.log(`$${cost.toFixed(4)}`); // "$0.0125"
+ *
+ * const cost = estimateCost('google', 10000, 1000);
+ * console.log(`$${cost.toFixed(4)}`); // "$0.0035"
+ * ```
+ */
+declare function estimateCost(providerId: keyof typeof PROVIDER_METADATA, inputTokens: number, outputTokens: number): number;
+/**
+ * Get the cheapest provider for a given workload
+ *
+ * @param inputTokens - Number of input tokens
+ * @param outputTokens - Number of output tokens
+ * @returns Cheapest provider metadata
+ *
+ * @example
+ * ```typescript
+ * const cheapest = getCheapestProvider(10000, 1000);
+ * console.log(cheapest.name); // "Google (Gemini)"
+ * ```
+ */
+declare function getCheapestProvider(inputTokens: number, outputTokens: number): LLMProviderMetadata;
+/**
+ * Compare native vs OpenRouter for a provider
+ *
+ * @param providerId - Provider ID
+ * @returns Comparison object with key differences
+ *
+ * @example
+ * ```typescript
+ * const comparison = compareNativeVsOpenRouter('anthropic');
+ * console.log(comparison.differences);
+ * // ['Uses OpenAI-compatible format...', 'Response prefill trick...']
+ * ```
+ */
+declare function compareNativeVsOpenRouter(providerId: keyof typeof PROVIDER_METADATA): {
+    provider: string;
+    nativeAvailable: boolean;
+    openRouterAvailable: boolean;
+    differences: string[];
+};
+type LLMProviderType = keyof typeof PROVIDER_METADATA;
+type SupportedImageMimeType = typeof SUPPORTED_IMAGE_TYPES.COMMON[number];
+type NodeType = 'parse' | 'extract' | 'categorize' | 'qualify' | 'split';
+
+/**
+ * Create a single VLM provider with direct instantiation (no retry/fallback logic).
+ *
+ * Use this for:
+ * - Simple scripts and quick prototypes
+ * - Testing individual provider behavior
+ * - Benchmarking (no retry overhead)
+ * - Cases where you want immediate failures without retry logic
+ *
+ * For production applications requiring resilience, use `buildLLMProvider()` instead.
+ *
+ * @example
+ * ```typescript
+ * const provider = createVLMProvider({
+ *   provider: 'google',
+ *   model: 'gemini-2.5-flash-preview-09-2025',
+ *   apiKey: process.env.OPENROUTER_API_KEY,
+ *   via: 'openrouter'
+ * });
+ * ```
+ *
+ * @param config - Provider configuration
+ * @returns CoreVLMProvider instance (no retry/fallback wrapper)
+ */
+declare function createVLMProvider(config: {
+    provider: 'openai' | 'anthropic' | 'google' | 'xai' | 'x-ai';
+    model: string;
+    apiKey: string;
+    via?: 'openrouter';
+    baseUrl?: string;
+}): VLMProvider;
+/**
+ * Build a production-ready LLM provider with retry logic, fallback support, and circuit breakers.
+ *
+ * Features:
+ * - **Retry Logic**: Configurable retries with exponential backoff for transient failures
+ * - **Fallback Chain**: Automatically tries next provider if current one fails
+ * - **Circuit Breaker**: Temporarily skips providers with repeated failures
+ * - **Observability**: Full integration with observability hooks for monitoring
+ * - **Mode Support**: Supports both strict and relaxed JSON modes
+ *
+ * Works with single OR multiple providers:
+ * - Single provider: Gets retry logic and circuit breaker protection
+ * - Multiple providers: Adds fallback to alternative providers
+ *
+ * Use this for:
+ * - Production applications requiring high availability
+ * - Cases where you need retry logic even with a single provider
+ * - Multi-provider fallback chains
+ * - Advanced error handling and monitoring
+ *
+ * @example Single provider with retry
+ * ```typescript
+ * const provider = buildLLMProvider({
+ *   providers: [{
+ *     provider: 'google',
+ *     model: 'gemini-2.5-flash-preview-09-2025',
+ *     apiKey: process.env.OPENROUTER_API_KEY,
+ *     via: 'openrouter'
+ *   }],
+ *   maxRetries: 2,
+ *   retryDelay: 1000,
+ *   useExponentialBackoff: true,
+ *   circuitBreakerThreshold: 3
+ * });
+ * ```
+ *
+ * @example Multi-provider fallback
+ * ```typescript
+ * const provider = buildLLMProvider({
+ *   providers: [
+ *     { provider: 'google', model: 'gemini-2.5-flash', apiKey: key1 },
+ *     { provider: 'openai', model: 'gpt-4.1', apiKey: key2 },
+ *     { provider: 'anthropic', model: 'claude-haiku-4.5', apiKey: key3 }
+ *   ],
+ *   maxRetries: 2,
+ *   retryDelay: 1000,
+ *   useExponentialBackoff: true
+ * });
+ * ```
+ *
+ * @param config - Fallback configuration with providers array and retry settings
+ * @returns CoreVLMProvider with retry/fallback capabilities (compatible with flow interface)
+ */
+declare function buildLLMProvider(config: FallbackConfig): VLMProvider;
+
+export { type AccessMethod, AnthropicProvider, type CircuitBreakerState, type FallbackConfig, FallbackManager, GoogleProvider, type ImageInput, type JsonMode, type LLMModelMetadata, type LLMProvider, type LLMProviderMetadata, type LLMProviderType, type LLMResponse, type MultimodalInput, type NodeType, OpenAIProvider, type PDFInput, PROVIDER_METADATA, type ProviderCapabilities, type ProviderConfig, type ProviderFactory, type ProviderInputType, type ProviderType, type ReasoningConfig, type ReasoningDetail, type ResourceLimits, type ResponseMetrics, SUPPORTED_IMAGE_TYPES, SchemaTranslator, type SupportedImageMimeType, type UnifiedSchema, XAIProvider, adaptToCoreLLMProvider, buildLLMProvider, buildSchemaPromptSection, combineSchemaAndUserPrompt, compareNativeVsOpenRouter, createProviderFromRegistry, createVLMProvider, estimateCost, formatSchemaForPrompt, getCheapestProvider, getProvidersForNode, isImageTypeSupported, isProviderCompatibleWithNode, providerRegistry, registerProvider, supportsPDFsInline };