@stackbilt/llm-providers 1.1.0 → 1.3.0

package/dist/factory.js

@@ -2,22 +2,32 @@
  * LLM Provider Factory
  * Creates and manages LLM provider instances with intelligent fallback logic
  */
+import { noopLogger } from './utils/logger';
+import { noopHooks } from './utils/hooks';
 import { OpenAIProvider } from './providers/openai';
 import { AnthropicProvider } from './providers/anthropic';
 import { CloudflareProvider } from './providers/cloudflare';
 import { CerebrasProvider } from './providers/cerebras';
 import { GroqProvider } from './providers/groq';
-import { defaultCostTracker } from './utils/cost-tracker';
+import { CostTracker, defaultCostTracker } from './utils/cost-tracker';
 import { defaultCircuitBreakerManager } from './utils/circuit-breaker';
-import { LLMProviderError, ConfigurationError, CircuitBreakerOpenError, AuthenticationError, RateLimitError } from './errors';
+import { defaultExhaustionRegistry } from './utils/exhaustion';
+import { defaultLatencyHistogram } from './utils/latency-histogram';
+import { LLMProviderError, ConfigurationError, CircuitBreakerOpenError, AuthenticationError, RateLimitError, QuotaExceededError, SchemaDriftError, ToolLoopAbortedError, ToolLoopLimitError, } from './errors';
 export class LLMProviderFactory {
     providers = new Map();
     config;
     costTracker;
     fallbackRules;
+    logger;
+    hooks;
     constructor(config) {
         this.config = config;
-        this.costTracker = defaultCostTracker;
+        this.logger = config.logger ?? noopLogger;
+        this.hooks = config.hooks ?? noopHooks;
+        this.costTracker = config.ledger
+            ? new CostTracker({}, config.ledger, this.logger)
+            : defaultCostTracker;
         this.fallbackRules = config.fallbackRules || this.getDefaultFallbackRules();
         this.initializeProviders();
     }
@@ -25,69 +35,34 @@ export class LLMProviderFactory {
      * Initialize all configured providers
      */
     initializeProviders() {
-        // Initialize OpenAI provider
-        if (this.config.openai) {
-            try {
-                const provider = new OpenAIProvider(this.config.openai);
-                if (provider.validateConfig()) {
-                    this.providers.set('openai', provider);
-                    console.log('[LLMProviderFactory] OpenAI provider initialized');
-                }
-            }
-            catch (error) {
-                console.warn('[LLMProviderFactory] Failed to initialize OpenAI provider:', error);
-            }
-        }
-        // Initialize Anthropic provider
-        if (this.config.anthropic) {
-            try {
-                const provider = new AnthropicProvider(this.config.anthropic);
-                if (provider.validateConfig()) {
-                    this.providers.set('anthropic', provider);
-                    console.log('[LLMProviderFactory] Anthropic provider initialized');
-                }
-            }
-            catch (error) {
-                console.warn('[LLMProviderFactory] Failed to initialize Anthropic provider:', error);
-            }
-        }
-        // Initialize Cloudflare provider
-        if (this.config.cloudflare) {
-            try {
-                const provider = new CloudflareProvider(this.config.cloudflare);
-                if (provider.validateConfig()) {
-                    this.providers.set('cloudflare', provider);
-                    console.log('[LLMProviderFactory] Cloudflare provider initialized');
-                }
-            }
-            catch (error) {
-                console.warn('[LLMProviderFactory] Failed to initialize Cloudflare provider:', error);
-            }
-        }
-        // Initialize Cerebras provider
-        if (this.config.cerebras) {
-            try {
-                const provider = new CerebrasProvider(this.config.cerebras);
-                if (provider.validateConfig()) {
-                    this.providers.set('cerebras', provider);
-                    console.log('[LLMProviderFactory] Cerebras provider initialized');
-                }
-            }
-            catch (error) {
-                console.warn('[LLMProviderFactory] Failed to initialize Cerebras provider:', error);
-            }
-        }
-        // Initialize Groq provider
-        if (this.config.groq) {
+        const providerEntries = [
+            ['openai', OpenAIProvider],
+            ['anthropic', AnthropicProvider],
+            ['cloudflare', CloudflareProvider],
+            ['cerebras', CerebrasProvider],
+            ['groq', GroqProvider],
+        ];
+        for (const [name, ProviderClass] of providerEntries) {
+            const providerConfig = this.config[name];
+            if (!providerConfig)
+                continue;
             try {
-                const provider = new GroqProvider(this.config.groq);
+                const retryConfig = this.config.enableRetries === false && providerConfig.maxRetries === undefined
+                    ? { maxRetries: 0 }
+                    : {};
+                const provider = new ProviderClass({
+                    ...providerConfig,
+                    ...retryConfig,
+                    logger: this.logger,
+                    hooks: this.hooks,
+                });
                 if (provider.validateConfig()) {
-                    this.providers.set('groq', provider);
-                    console.log('[LLMProviderFactory] Groq provider initialized');
+                    this.providers.set(name, provider);
+                    this.logger.info(`[LLMProviderFactory] ${name} provider initialized`);
                 }
             }
             catch (error) {
-                console.warn('[LLMProviderFactory] Failed to initialize Groq provider:', error);
+                this.logger.warn(`[LLMProviderFactory] Failed to initialize ${name} provider:`, error.message);
             }
         }
         if (this.providers.size === 0) {
@@ -99,41 +74,345 @@ export class LLMProviderFactory {
      */
     async generateResponse(request) {
         const providerChain = this.buildProviderChain(request);
+        const providerModels = new Map();
         let lastError = null;
-        for (const providerName of providerChain) {
+        let previousProvider = null;
+        for (let index = 0; index < providerChain.length; index++) {
+            const providerName = providerChain[index];
             try {
                 const provider = this.providers.get(providerName);
                 if (!provider)
                     continue;
+                // Check exhaustion registry
+                if (defaultExhaustionRegistry.isExhausted(providerName)) {
+                    this.logger.warn(`[LLMProviderFactory] Provider ${providerName} is quota-exhausted, skipping`);
+                    continue;
+                }
                 // Check circuit breaker
                 if (this.config.enableCircuitBreaker) {
                     const breaker = defaultCircuitBreakerManager.getBreaker(providerName);
                     if (breaker.isOpen()) {
-                        console.warn(`[LLMProviderFactory] Circuit breaker open for ${providerName}, skipping`);
+                        this.logger.warn(`[LLMProviderFactory] Circuit breaker open for ${providerName}, skipping`);
                         continue;
                     }
                 }
-                console.log(`[LLMProviderFactory] Trying provider: ${providerName}`);
-                const response = await provider.generateResponse(request);
-                // Track cost if enabled
-                if (this.config.costOptimization) {
+                if (this.config.ledger && this.isLedgerLimited(providerName)) {
+                    continue;
+                }
+                // Emit fallback event if this isn't the first provider attempted
+                if (previousProvider && lastError) {
+                    this.hooks.onFallback?.({
+                        fromProvider: previousProvider,
+                        toProvider: providerName,
+                        requestId: request.requestId,
+                        reason: lastError.message,
+                        errorCode: lastError.code,
+                        timestamp: Date.now(),
+                    });
+                }
+                this.logger.debug(`[LLMProviderFactory] Trying provider: ${providerName}`);
+                const providerRequest = this.requestForProvider(request, providerName, providerModels);
+                const model = providerRequest.model || provider.models[0] || 'unknown';
+                await this.checkQuota(providerName, provider, providerRequest, model);
+                this.hooks.onRequestStart?.({
+                    provider: providerName,
+                    model,
+                    requestId: request.requestId,
+                    tenantId: request.tenantId,
+                    timestamp: Date.now(),
+                });
+                const startTime = Date.now();
+                const response = await provider.generateResponse(providerRequest);
+                const durationMs = Date.now() - startTime;
+                this.hooks.onRequestEnd?.({
+                    provider: providerName,
+                    model: response.model,
+                    requestId: request.requestId,
+                    tenantId: request.tenantId,
+                    durationMs,
+                    usage: response.usage,
+                    finishReason: response.finishReason,
+                    timestamp: Date.now(),
+                });
+                // Track spend whenever analytics or ledger accounting is configured.
+                if (this.config.costOptimization || this.config.ledger) {
                     this.costTracker.trackCost(providerName, response);
                 }
-                console.log(`[LLMProviderFactory] Successfully used provider: ${providerName}`);
+                this.recordQuota(providerName, response, providerRequest);
+                this.logger.debug(`[LLMProviderFactory] Successfully used provider: ${providerName}`);
                 return response;
             }
             catch (error) {
-                lastError = error;
-                console.warn(`[LLMProviderFactory] Provider ${providerName} failed:`, error);
-                // Check if we should continue trying other providers
-                if (!this.shouldFallback(error)) {
+                const err = error;
+                lastError = err;
+                previousProvider = providerName;
+                this.logger.warn(`[LLMProviderFactory] Provider ${providerName} failed:`, err.message);
+                this.hooks.onRequestError?.({
+                    provider: providerName,
+                    model: request.model || 'unknown',
+                    requestId: request.requestId,
+                    tenantId: request.tenantId,
+                    error: err,
+                    errorCode: err.code,
+                    attempt: 1,
+                    willRetry: this.shouldFallback(err),
+                    timestamp: Date.now(),
+                });
+                // Auto-mark quota-exhausted providers
+                if (err instanceof QuotaExceededError) {
+                    defaultExhaustionRegistry.markExhausted(providerName);
+                    this.hooks.onQuotaExhausted?.({
+                        provider: providerName,
+                        resetAfterMs: defaultExhaustionRegistry.defaultResetMs,
+                        timestamp: Date.now(),
+                    });
+                }
+                // Schema drift — the upstream API silently changed shape. Surface
+                // structured telemetry so oncall sees the drift before it cascades.
+                if (err instanceof SchemaDriftError) {
+                    this.hooks.onSchemaDrift?.({
+                        provider: providerName,
+                        model: request.model,
+                        requestId: request.requestId,
+                        path: err.path,
+                        expected: err.expected,
+                        actual: err.actual,
+                        timestamp: Date.now(),
+                    });
+                }
+                const fallbackDecision = this.getFallbackDecision(error);
+                if (!fallbackDecision.shouldFallback) {
                     throw error;
                 }
+                this.applyFallbackDecision(fallbackDecision, providerName, providerChain, index, providerModels);
             }
         }
         // All providers failed
         throw lastError || new LLMProviderError('All providers failed', 'ALL_PROVIDERS_FAILED', 'factory', false);
     }
+    async generateResponseStream(request) {
+        const providerChain = this.buildProviderChain({ ...request, stream: true });
+        const providerModels = new Map();
+        let lastError = null;
+        let previousProvider = null;
+        for (let index = 0; index < providerChain.length; index++) {
+            const providerName = providerChain[index];
+            try {
+                const provider = this.providers.get(providerName);
+                if (!provider || !provider.supportsStreaming || !provider.streamResponse)
+                    continue;
+                if (defaultExhaustionRegistry.isExhausted(providerName))
+                    continue;
+                if (this.config.enableCircuitBreaker && defaultCircuitBreakerManager.getBreaker(providerName).isOpen())
+                    continue;
+                if (this.config.ledger && this.isLedgerLimited(providerName))
+                    continue;
+                if (previousProvider && lastError) {
+                    this.hooks.onFallback?.({
+                        fromProvider: previousProvider,
+                        toProvider: providerName,
+                        requestId: request.requestId,
+                        reason: lastError.message,
+                        errorCode: lastError.code,
+                        timestamp: Date.now(),
+                    });
+                }
+                const providerRequest = {
+                    ...this.requestForProvider(request, providerName, providerModels),
+                    stream: true
+                };
+                const model = providerRequest.model || provider.models[0] || 'unknown';
+                const estimatedCost = await this.checkQuota(providerName, provider, providerRequest, model);
+                this.hooks.onRequestStart?.({
+                    provider: providerName,
+                    model,
+                    requestId: request.requestId,
+                    tenantId: request.tenantId,
+                    timestamp: Date.now(),
+                });
+                const startTime = Date.now();
+                const opened = await this.openStreamWithFirstChunk(provider, providerRequest);
+                return this.buildFactoryStream(opened.reader, opened.firstChunk, opened.done, providerName, model, providerRequest, startTime, estimatedCost);
+            }
+            catch (error) {
+                const err = error;
+                lastError = err;
+                previousProvider = providerName;
+                this.hooks.onRequestError?.({
+                    provider: providerName,
+                    model: request.model || 'unknown',
+                    requestId: request.requestId,
+                    tenantId: request.tenantId,
+                    error: err,
+                    errorCode: err.code,
+                    attempt: 1,
+                    willRetry: this.shouldFallback(err),
+                    timestamp: Date.now(),
+                });
+                const fallbackDecision = this.getFallbackDecision(err);
+                if (!fallbackDecision.shouldFallback) {
+                    throw error;
+                }
+                this.applyFallbackDecision(fallbackDecision, providerName, providerChain, index, providerModels);
+            }
+        }
+        throw lastError || new LLMProviderError('All streaming providers failed', 'ALL_PROVIDERS_FAILED', 'factory', false);
+    }
+    async generateResponseWithTools(request, toolExecutor, opts = {}) {
+        const maxIterations = opts.maxIterations ?? 10;
+        let cumulativeCost = 0;
+        let messages = [...request.messages];
+        let lastResponseCost = 0;
+        for (let iteration = 0; iteration <= maxIterations; iteration++) {
+            if (opts.abortSignal?.aborted) {
+                throw new ToolLoopAbortedError('factory');
+            }
+            // Pre-flight cost guard: use the previous iteration's cost as an
+            // estimate for the next one.  This prevents obvious overshoots where
+            // a single expensive response would blow past the cap.  The cap is
+            // still soft (±1 iteration tolerance) because the actual cost is
+            // only known after the response.
+            if (opts.maxCostUSD !== undefined && iteration > 0) {
+                const projectedCost = cumulativeCost + lastResponseCost;
+                if (projectedCost > opts.maxCostUSD) {
+                    throw new ToolLoopLimitError('factory', `Tool loop would exceed max cost ${opts.maxCostUSD} (projected ${projectedCost.toFixed(4)})`);
+                }
+            }
+            const response = await this.generateResponse({ ...request, messages });
+            lastResponseCost = response.usage.cost;
+            cumulativeCost += lastResponseCost;
+            if (opts.maxCostUSD !== undefined && cumulativeCost > opts.maxCostUSD) {
+                throw new ToolLoopLimitError('factory', `Tool loop exceeded max cost ${opts.maxCostUSD}`);
+            }
+            if (!response.toolCalls || response.toolCalls.length === 0) {
+                return {
+                    ...response,
+                    metadata: {
+                        ...response.metadata,
+                        cumulativeCost,
+                        toolIterations: iteration
+                    }
+                };
+            }
+            if (iteration >= maxIterations) {
+                throw new ToolLoopLimitError('factory', `Tool loop exceeded ${maxIterations} iterations`);
+            }
+            const toolResults = [];
+            for (const toolCall of response.toolCalls) {
+                if (opts.abortSignal?.aborted) {
+                    throw new ToolLoopAbortedError('factory');
+                }
+                let parsedArguments;
+                try {
+                    parsedArguments = JSON.parse(toolCall.function.arguments);
+                }
+                catch {
+                    parsedArguments = toolCall.function.arguments;
+                }
+                try {
+                    const output = await toolExecutor.execute(toolCall.function.name, parsedArguments);
+                    toolResults.push({
+                        id: toolCall.id,
+                        output: typeof output === 'string' ? output : JSON.stringify(output)
+                    });
+                }
+                catch (error) {
+                    toolResults.push({
+                        id: toolCall.id,
+                        output: '',
+                        error: error.message
+                    });
+                }
+            }
+            messages = [
+                ...messages,
+                {
+                    role: 'assistant',
+                    content: response.message,
+                    toolCalls: response.toolCalls
+                },
+                {
+                    role: 'user',
+                    content: '',
+                    toolResults
+                }
+            ];
+            const state = {
+                iteration: iteration + 1,
+                cumulativeCost,
+                messageCount: messages.length,
+                lastToolCalls: response.toolCalls
+            };
+            await opts.onIteration?.(iteration + 1, state);
+        }
+        throw new ToolLoopLimitError('factory', `Tool loop exceeded ${maxIterations} iterations`);
+    }
+    async classify(input, options = {}) {
+        const parser = options.schema && typeof options.schema.parse === 'function'
+            ? options.schema.parse
+            : undefined;
+        const schemaDescription = options.schema && !parser
+            ? `\nJSON schema:\n${JSON.stringify(options.schema)}`
+            : '';
+        const systemPrompt = options.systemPrompt ||
+            `Classify the input and return only valid JSON.${schemaDescription}`;
+        const request = typeof input === 'string'
+            ? {
+                messages: [{ role: 'user', content: input }],
+                model: options.model,
+                temperature: options.temperature ?? 0,
+                maxTokens: options.maxTokens,
+                response_format: { type: 'json_object' },
+                systemPrompt,
+                seed: options.seed
+            }
+            : {
+                ...input,
+                model: options.model ?? input.model,
+                temperature: options.temperature ?? input.temperature ?? 0,
+                maxTokens: options.maxTokens ?? input.maxTokens,
+                response_format: { type: 'json_object' },
+                systemPrompt: options.systemPrompt ?? input.systemPrompt ?? systemPrompt,
+                seed: options.seed ?? input.seed
+            };
+        const response = await this.generateResponse(request);
+        const parsed = this.parseJsonResponse(response.message);
+        const data = parser ? parser(parsed) : parsed;
+        const confidenceValue = parsed[options.confidenceField ?? 'confidence'];
+        return {
+            data,
+            confidence: typeof confidenceValue === 'number' ? confidenceValue : undefined,
+            response
+        };
+    }
+    async analyzeImage(input) {
+        return this.generateResponse({
+            messages: [{ role: 'user', content: input.prompt }],
+            images: [input.image],
+            model: input.model ?? this.getDefaultVisionModel(),
+            systemPrompt: input.systemPrompt,
+            temperature: input.temperature,
+            maxTokens: input.maxTokens,
+            response_format: input.response_format,
+            tenantId: input.tenantId,
+            requestId: input.requestId,
+            metadata: input.metadata
+        });
+    }
+    async getProviderBalance(provider) {
+        if (provider) {
+            const balance = await this.getSingleProviderBalance(provider);
+            this.hooks.onProviderBalance?.({ provider, balance, timestamp: Date.now() });
+            return balance;
+        }
+        const result = {};
+        for (const providerName of this.providers.keys()) {
+            const balance = await this.getSingleProviderBalance(providerName);
+            result[providerName] = balance;
+            this.hooks.onProviderBalance?.({ provider: providerName, balance, timestamp: Date.now() });
+        }
+        return result;
+    }
     /**
      * Build provider chain based on request and configuration
      */
@@ -166,12 +445,16 @@ export class LLMProviderFactory {
      * Get prioritized list of providers based on cost optimization and capabilities
      */
     getPrioritizedProviders(request) {
+        const visionOnly = (request.images?.length ?? 0) > 0;
         if (!this.config.costOptimization) {
-            // Default priority: Cloudflare (cheapest) -> Anthropic -> OpenAI
-            return ['cloudflare', 'anthropic', 'openai'];
+            // Default priority: all configured providers, cheapest first
+            return ['cloudflare', 'cerebras', 'groq', 'anthropic', 'openai']
+                .filter(p => this.providers.has(p))
+                .filter(p => !visionOnly || this.providerSupportsVision(p));
         }
         // Cost-optimized routing
-        const providers = Array.from(this.providers.keys());
+        const providers = Array.from(this.providers.keys())
+            .filter(p => !visionOnly || this.providerSupportsVision(p));
         const sortedProviders = [...providers].sort((a, b) => {
             const providerA = this.providers.get(a);
             const providerB = this.providers.get(b);
@@ -203,8 +486,8 @@ export class LLMProviderFactory {
         if (model.startsWith('@cf/')) {
             return 'cloudflare';
         }
-        // Groq models
-        if (model.includes('-versatile') || model.includes('-instant')) {
+        // Groq models (openai/gpt-oss-120b is Groq-hosted, not @cf/ prefixed)
+        if (model.includes('-versatile') || model.includes('-instant') || model === 'openai/gpt-oss-120b') {
             return 'groq';
         }
         // Cerebras models
@@ -218,29 +501,49 @@ export class LLMProviderFactory {
      * Check if we should fallback to another provider
      */
     shouldFallback(error) {
+        return this.getFallbackDecision(error).shouldFallback;
+    }
+    /**
+     * Get fallback routing decision for an error.
+     */
+    getFallbackDecision(error) {
         // Don't fallback for authentication errors
         if (error instanceof AuthenticationError) {
-            return false;
+            return { shouldFallback: false };
         }
         // Don't fallback for configuration errors
         if (error instanceof ConfigurationError) {
-            return false;
+            return { shouldFallback: false };
+        }
+        // Custom fallback rules can provide explicit provider/model routing.
+        for (const rule of this.fallbackRules) {
+            if (this.evaluateFallbackRule(rule, error)) {
+                return {
+                    shouldFallback: true,
+                    fallbackProvider: rule.fallbackProvider,
+                    fallbackModel: rule.fallbackModel
+                };
+            }
         }
         // Fallback for circuit breaker, rate limits, and server errors
         if (error instanceof CircuitBreakerOpenError ||
-            error instanceof RateLimitError ||
-            error.code === 'SERVER_ERROR' ||
-            error.code === 'NETWORK_ERROR' ||
-            error.code === 'TIMEOUT') {
-            return true;
+            error instanceof RateLimitError) {
+            return { shouldFallback: true };
         }
-        // Check custom fallback rules
-        for (const rule of this.fallbackRules) {
-            if (this.evaluateFallbackRule(rule, error)) {
-                return true;
+        // Schema drift: provider's response shape changed. Retry won't help;
+        // only another provider can. Defense against silent API deprecations.
+        if (error instanceof SchemaDriftError) {
+            return { shouldFallback: true };
+        }
+        if (error instanceof LLMProviderError) {
+            if (error.code === 'SERVER_ERROR' ||
+                error.code === 'NETWORK_ERROR' ||
+                error.code === 'TIMEOUT' ||
+                error.code === 'SCHEMA_DRIFT') {
+                return { shouldFallback: true };
             }
         }
-        return false;
+        return { shouldFallback: false };
     }
     /**
      * Evaluate a fallback rule against an error
@@ -364,7 +667,19 @@ export class LLMProviderFactory {
         return recommendations;
     }
     /**
-     * Reset all provider metrics and circuit breakers
+     * Get latency histogram data for all providers
+     */
+    getLatencyHistogram() {
+        return defaultLatencyHistogram.allSummaries();
+    }
+    /**
+     * Get currently exhausted providers
+     */
+    getExhaustedProviders() {
+        return defaultExhaustionRegistry.getExhaustedProviders();
+    }
+    /**
+     * Reset all provider metrics, circuit breakers, exhaustion, and histograms
      */
     reset() {
         for (const [name, provider] of this.providers) {
@@ -373,24 +688,268 @@ export class LLMProviderFactory {
                 defaultCircuitBreakerManager.reset(name);
             }
         }
-        if (this.config.costOptimization) {
+        if (this.config.costOptimization || this.config.ledger) {
             this.costTracker.reset();
         }
+        defaultExhaustionRegistry.reset();
+        defaultLatencyHistogram.reset();
     }
     /**
      * Update factory configuration
      */
     updateConfig(config) {
         this.config = { ...this.config, ...config };
+        if ('ledger' in config) {
+            this.costTracker = config.ledger
+                ? new CostTracker({}, config.ledger, this.logger)
+                : defaultCostTracker;
+        }
         if (config.fallbackRules) {
             this.fallbackRules = config.fallbackRules;
         }
         // Re-initialize providers if configs changed
-        if (config.openai || config.anthropic || config.cloudflare || config.cerebras || config.groq) {
+        if (config.openai ||
+            config.anthropic ||
+            config.cloudflare ||
+            config.cerebras ||
+            config.groq ||
+            config.enableRetries !== undefined) {
             this.providers.clear();
             this.initializeProviders();
         }
     }
+    async openStreamWithFirstChunk(provider, request) {
+        if (!provider.streamResponse) {
+            throw new ConfigurationError(provider.name, 'Provider does not support streaming');
+        }
+        const stream = await provider.streamResponse(request);
+        const reader = stream.getReader();
+        const first = await reader.read();
+        return {
+            reader,
+            firstChunk: first.value,
+            done: first.done
+        };
+    }
+    buildFactoryStream(reader, firstChunk, firstDone, providerName, model, request, startTime, estimatedCost) {
+        return new ReadableStream({
+            start: async (controller) => {
+                try {
+                    if (!firstDone && firstChunk !== undefined) {
+                        controller.enqueue(firstChunk);
+                    }
+                    if (!firstDone) {
+                        while (true) {
+                            const { done, value } = await reader.read();
+                            if (done)
+                                break;
+                            if (value !== undefined)
+                                controller.enqueue(value);
+                        }
+                    }
+                    const usage = { inputTokens: 0, outputTokens: 0, totalTokens: 0, cost: estimatedCost };
+                    this.hooks.onRequestEnd?.({
+                        provider: providerName,
+                        model,
+                        requestId: request.requestId,
+                        tenantId: request.tenantId,
+                        durationMs: Date.now() - startTime,
+                        usage,
+                        finishReason: 'stop',
+                        timestamp: Date.now(),
+                    });
+                    this.recordQuotaInput({
+                        tenantId: request.tenantId,
+                        provider: providerName,
+                        model,
+                        actualCost: estimatedCost,
+                        metadata: request.metadata
+                    });
+                    controller.close();
+                }
+                catch (error) {
+                    controller.error(error);
+                }
+                finally {
+                    reader.releaseLock();
+                }
+            }
+        });
+    }
+    async checkQuota(providerName, provider, request, model) {
+        const estimatedCost = provider.estimateCost(request);
+        if (!this.config.quotaHook) {
+            return estimatedCost;
+        }
+        const input = {
+            tenantId: request.tenantId,
+            provider: providerName,
+            model,
+            estimatedCost,
+            metadata: request.metadata
+        };
+        try {
+            const result = await this.config.quotaHook.check(input);
+            this.hooks.onQuotaCheck?.({ input, result, timestamp: Date.now() });
+            if (!result.allowed) {
+                this.hooks.onQuotaDenied?.({ input, reason: result.reason, timestamp: Date.now() });
+                throw new QuotaExceededError(providerName, result.reason || 'Quota hook denied request');
+            }
+        }
+        catch (error) {
+            if (error instanceof QuotaExceededError) {
+                throw error;
+            }
+            if ((this.config.quotaFailPolicy ?? 'closed') === 'open') {
+                this.logger.warn(`[LLMProviderFactory] Quota check failed open for ${providerName}:`, error.message);
+                return estimatedCost;
+            }
+            const reason = error.message;
+            this.hooks.onQuotaDenied?.({ input, reason, timestamp: Date.now() });
+            throw new QuotaExceededError(providerName, reason);
+        }
+        return estimatedCost;
+    }
+    recordQuota(providerName, response, request) {
+        this.recordQuotaInput({
+            tenantId: request.tenantId,
+            provider: providerName,
+            model: response.model,
+            actualCost: response.usage.cost,
+            inputTokens: response.usage.inputTokens,
+            outputTokens: response.usage.outputTokens,
+            metadata: request.metadata
+        });
+    }
+    recordQuotaInput(input) {
+        if (!this.config.quotaHook)
+            return;
+        void this.config.quotaHook.record(input).catch(error => {
+            this.logger.warn(`[LLMProviderFactory] Quota record failed for ${input.provider}:`, error.message);
+        });
+    }
+    parseJsonResponse(message) {
+        try {
+            return JSON.parse(message);
+        }
+        catch {
+            // Strip markdown fences (```json ... ``` or ``` ... ```) before
+            // falling back to brace extraction so fenced JSON parses cleanly.
+            const fenced = message.replace(/^```(?:json)?\s*\n?/m, '').replace(/\n?```\s*$/m, '');
+            try {
+                return JSON.parse(fenced);
+            }
+            catch {
+                // Last resort: extract outermost braces.
+                const start = fenced.indexOf('{');
+                const end = fenced.lastIndexOf('}');
+                if (start >= 0 && end > start) {
+                    return JSON.parse(fenced.slice(start, end + 1));
+                }
+            }
+            throw new ConfigurationError('factory', 'Classification response was not valid JSON');
+        }
+    }
+    getDefaultVisionModel() {
+        if (this.config.defaultVisionModel)
+            return this.config.defaultVisionModel;
+        if (this.providers.has('anthropic'))
+            return 'claude-haiku-4-5-20251001';
+        if (this.providers.has('openai'))
+            return 'gpt-4o-mini';
+        if (this.providers.has('cloudflare'))
+            return '@cf/google/gemma-4-26b-a4b-it';
+        return undefined;
+    }
+    providerSupportsVision(providerName) {
+        return this.providers.get(providerName)?.supportsVision === true;
+    }
+    async getSingleProviderBalance(providerName) {
+        const ledgerBalance = this.getLedgerBalance(providerName);
+        if (ledgerBalance) {
+            return ledgerBalance;
+        }
+        const provider = this.providers.get(providerName);
+        if (!provider) {
+            return {
+                provider: providerName,
+                status: 'error',
+                source: 'not_supported',
+                message: `Provider '${providerName}' is not configured`
+            };
+        }
+        if (provider.getProviderBalance) {
+            return provider.getProviderBalance();
+        }
+        return {
+            provider: providerName,
+            status: 'unavailable',
+            source: 'not_supported',
+            message: `Provider '${providerName}' does not expose balance reporting`
+        };
+    }
+    getLedgerBalance(providerName) {
+        const acc = this.config.ledger?.getProviderAccumulator(providerName);
+        if (!acc)
+            return undefined;
+        const rateLimits = {};
+        for (const [dimension, window] of Object.entries(acc.rateLimits)) {
+            rateLimits[dimension] = {
+                limit: window.limit,
+                used: window.used,
+                remaining: Math.max(window.limit - window.used, 0)
+            };
+        }
+        return {
+            provider: providerName,
+            status: 'available',
+            source: 'ledger',
+            currentSpend: acc.spend,
+            monthlyBudget: acc.budget ?? undefined,
+            remainingBudget: acc.budget === null ? undefined : acc.budget - acc.spend,
+            usedTokens: acc.inputTokens + acc.outputTokens,
+            requestCount: acc.requestCount,
+            rateLimits
+        };
+    }
+    isLedgerLimited(providerName) {
+        if (!this.config.ledger)
+            return false;
+        for (const dimension of ['rpm', 'rpd', 'tpm', 'tpd']) {
+            const check = this.config.ledger.checkRateLimit(providerName, dimension);
+            if (!check.allowed) {
+                this.logger.warn(`[LLMProviderFactory] Rate limit (${dimension}) exceeded for ${providerName} (${check.used}/${check.limit}), skipping`);
+                return true;
+            }
+        }
+        return false;
+    }
+    requestForProvider(request, providerName, providerModels) {
+        const model = providerModels.get(providerName);
+        if (!model) {
+            return request;
+        }
+        return { ...request, model };
+    }
+    applyFallbackDecision(decision, failedProvider, providerChain, currentIndex, providerModels) {
+        const targetProvider = decision.fallbackProvider;
+        if (!targetProvider || targetProvider === failedProvider || !this.providers.has(targetProvider)) {
+            return;
+        }
+        if (decision.fallbackModel) {
+            providerModels.set(targetProvider, decision.fallbackModel);
+        }
+        const nextIndex = currentIndex + 1;
+        const firstIndex = providerChain.indexOf(targetProvider);
+        if (firstIndex >= 0 && firstIndex <= currentIndex) {
+            return;
+        }
+        const existingIndex = providerChain.indexOf(targetProvider, nextIndex);
+        if (existingIndex >= 0) {
+            providerChain.splice(existingIndex, 1);
+        }
+        providerChain.splice(nextIndex, 0, targetProvider);
+    }
 }
 /**
  * Create a provider factory with common configurations