@stackbilt/llm-providers 1.0.0 → 1.2.0

package/README.md

@@ -1,17 +1,20 @@
 # @stackbilt/llm-providers
 
-A multi-provider LLM abstraction layer with automatic failover, circuit breakers, cost tracking, and intelligent retry. Built for Cloudflare Workers but runs anywhere with a standard `fetch` API. Extracted from a production orchestration platform handling 80K+ LOC across multiple services.
+A multi-provider LLM abstraction layer with automatic failover, graduated circuit breakers, cost tracking, and intelligent retry. Built for Cloudflare Workers but runs anywhere with a standard `fetch` API. Extracted from a production orchestration platform handling 80K+ LOC across multiple services.
 
 ## Features
 
-- **Multi-provider failover** -- OpenAI, Anthropic, and Cloudflare Workers AI behind a single interface
-- **Circuit breaker** -- state machine (closed / open / half-open) prevents cascading failures
+- **Multi-provider failover** -- OpenAI, Anthropic, Cloudflare Workers AI, Cerebras, and Groq behind a single interface
+- **Graduated circuit breaker** -- 4-state machine (closed / degraded / recovering / open) with probabilistic traffic routing prevents cascading failures
 - **Exponential backoff retry** -- configurable delays, jitter, and per-error-class behavior
-- **Cost tracking and optimization** -- per-provider cost attribution, budget alerts, automatic routing to cheaper providers
-- **Streaming** -- SSE streaming support for all three providers
-- **Tool/function calling** -- OpenAI and Anthropic tool use with unified response format
-- **Batch processing** -- concurrent request batching with rate-limit awareness
+- **Cost tracking and optimization** -- per-provider cost attribution, budget alerts with CreditLedger, automatic routing to cheaper providers
+- **Rate limit enforcement** -- CreditLedger tracks RPM/RPD/TPM/TPD per provider; factory skips providers that exceed limits
+- **Streaming** -- SSE streaming support for all providers
+- **Tool/function calling** -- OpenAI, Anthropic, Cerebras, and Cloudflare tool use with unified response format
+- **Image generation** -- Cloudflare Workers AI (SDXL, FLUX) and Google Gemini
 - **Health monitoring** -- per-provider health checks, metrics, and circuit breaker state
+- **Structured logging** -- injectable `Logger` interface; silent by default, opt-in to console or custom loggers
+- **Zero runtime dependencies** -- no transitive dependency tree to audit
 
 ## Installation
 
@@ -46,55 +49,75 @@ console.log(response.message);
 console.log(`Provider: ${response.provider}, Cost: $${response.usage.cost}`);
 ```
 
-## Provider Configuration
-
-### OpenAI
+### Auto-Discovery from Environment
 
 ```typescript
-{
-  apiKey: 'sk-...',
-  organization: 'org-...',   // optional
-  project: 'proj-...',       // optional
-  baseUrl: 'https://api.openai.com/v1', // optional, for proxies
-  timeout: 30000,
-  maxRetries: 3,
-}
+import { LLMProviders } from '@stackbilt/llm-providers';
+
+// Scans env for ANTHROPIC_API_KEY, OPENAI_API_KEY, GROQ_API_KEY,
+// CEREBRAS_API_KEY, and AI binding — configures only what's present
+const llm = LLMProviders.fromEnv(env, {
+  costOptimization: true,
+  enableCircuitBreaker: true,
+});
 ```
 
-### Anthropic
+## Providers
+
+| Provider | Models | Streaming | Tools | Notes |
+|----------|--------|-----------|-------|-------|
+| **OpenAI** | GPT-4o, GPT-4o Mini, GPT-4 Turbo, GPT-4 | Yes | Yes | Default: `gpt-4o-mini` |
+| **Anthropic** | Claude Opus 4.6, Sonnet 4.6, Sonnet 4, Haiku 4.5, 3.7 Sonnet, 3.5 Sonnet/Haiku, 3 Opus/Sonnet/Haiku | Yes | Yes | Default: `claude-haiku-4-5` |
+| **Cloudflare** | LLaMA 3.1 8B/70B, GPT-OSS 120B, Mistral 7B, Qwen 1.5, TinyLlama, and more | Yes | GPT-OSS only | Near-zero cost |
+| **Cerebras** | LLaMA 3.1 8B, LLaMA 3.3 70B, ZAI-GLM 4.7, Qwen 3 235B | Yes | GLM/Qwen only | ~2,200 tok/s |
+| **Groq** | LLaMA 3.3 70B Versatile, LLaMA 3.1 8B Instant | Yes | No | Ultra-fast inference |
+
+### Provider Configuration
 
 ```typescript
-{
-  apiKey: 'sk-ant-...',
-  version: '2023-06-01',     // optional
-  baseUrl: 'https://api.anthropic.com', // optional
-  timeout: 30000,
-  maxRetries: 3,
-}
+// OpenAI
+{ apiKey: 'sk-...', organization: 'org-...', project: 'proj-...' }
+
+// Anthropic
+{ apiKey: 'sk-ant-...', version: '2023-06-01' }
+
+// Cloudflare Workers AI
+{ ai: env.AI, accountId: '...' }
+
+// Cerebras
+{ apiKey: 'csk-...' }
+
+// Groq
+{ apiKey: 'gsk_...' }
 ```
 
-### Cloudflare Workers AI
+## Logging
+
+The library is silent by default. Opt in to logging by passing a `Logger`:
 
 ```typescript
-{
-  ai: env.AI,                // Cloudflare AI binding (required)
-  accountId: '...',          // optional
-  timeout: 30000,
-  maxRetries: 3,
-}
+import { LLMProviders, consoleLogger } from '@stackbilt/llm-providers';
+
+const llm = new LLMProviders({
+  anthropic: { apiKey: '...', logger: consoleLogger },
+  logger: consoleLogger, // factory-level logging
+});
 ```
 
+Or implement your own `Logger` interface (`debug`, `info`, `warn`, `error`).
+
 ## Circuit Breaker
 
-Each provider gets its own circuit breaker that tracks consecutive failures.
+Each provider gets a graduated circuit breaker that routes traffic away from failing providers with probabilistic degradation.
 
 | State | Behavior |
 |-------|----------|
-| **Closed** | Requests pass through normally. Failures increment a counter. |
-| **Open** | All requests are immediately rejected. After `resetTimeout` ms, transitions to half-open. |
-| **Half-open** | A single test request is allowed through. Success closes the circuit; failure re-opens it. |
+| **Closed** | 100% traffic to primary. Failures increment counter. |
+| **Degraded** | Traffic splits probabilistically (90% → 70% → 40% → 10%) as failures accumulate. |
+| **Recovering** | Success steps traffic back up one level at a time. |
+| **Open** | 0% traffic. After `resetTimeout` ms, failures decay and traffic resumes. |
 
-Default thresholds: 5 failures to open, 60s reset timeout, 5-minute monitoring window.
+Default: 5-step degradation curve `[1.0, 0.9, 0.7, 0.4, 0.1]`, 60s reset timeout, 5-minute monitoring window.
 
 ```typescript
 import { CircuitBreakerManager } from '@stackbilt/llm-providers';
@@ -103,47 +126,37 @@ const manager = new CircuitBreakerManager({
   failureThreshold: 5,
   resetTimeout: 60000,
   monitoringPeriod: 300000,
+  degradationCurve: [1.0, 0.9, 0.7, 0.4, 0.1],
 });
 
 const breaker = manager.getBreaker('openai');
 console.log(breaker.getHealth());
 ```
 
-## Cost Optimization
-
-When `costOptimization: true`, the factory routes requests to the cheapest available provider. Cloudflare Workers AI is essentially free and gets top priority.
+## Cost Tracking & Budget Management
 
 ```typescript
-import { createCostOptimizedLLMProviders } from '@stackbilt/llm-providers';
+import { CreditLedger, LLMProviders } from '@stackbilt/llm-providers';
 
-const llm = createCostOptimizedLLMProviders({
-  openai: { apiKey: process.env.OPENAI_API_KEY },
-  cloudflare: { ai: env.AI },
+const ledger = new CreditLedger({
+  budgets: [
+    { provider: 'openai', monthlyBudget: 50, rateLimits: { rpm: 60, rpd: 10000 } },
+    { provider: 'anthropic', monthlyBudget: 100 },
+  ],
 });
 
-const analytics = llm.getCostAnalytics();
-// { breakdown: { openai: { cost, requests, tokens }, ... }, total: 0.042, recommendations: [...] }
-```
-
-## Retry with Backoff
-
-Transient errors (rate limits, network errors, server errors) are retried automatically with exponential backoff and jitter.
+// Threshold alerts fire at 80%, 90%, 95% utilization
+ledger.on((event) => {
+  if (event.type === 'threshold_crossed') {
+    console.warn(`${event.provider}: ${event.tier} — ${event.utilizationPct.toFixed(0)}% of budget`);
+  }
+});
 
-```typescript
-import { RetryManager, retry } from '@stackbilt/llm-providers';
-
-// Standalone retry for any async operation
-const result = await retry(
-  () => fetch('https://api.example.com/data'),
-  { maxRetries: 3, initialDelay: 1000, backoffMultiplier: 2 }
-);
-
-// Or configure per-provider via RetryManager
-const retryManager = new RetryManager({
-  maxRetries: 5,
-  initialDelay: 500,
-  maxDelay: 30000,
-  backoffMultiplier: 2,
+const llm = new LLMProviders({
+  openai: { apiKey: '...' },
+  anthropic: { apiKey: '...' },
+  costOptimization: true,
+  ledger, // Factory enforces rate limits and tracks spend
 });
 ```
 
@@ -156,6 +169,7 @@ const llm = new LLMProviders({
   openai: { apiKey: '...' },
   anthropic: { apiKey: '...' },
   cloudflare: { ai: env.AI },
+  cerebras: { apiKey: '...' },
   fallbackRules: [
     { condition: 'rate_limit', fallbackProvider: 'cloudflare' },
     { condition: 'cost', threshold: 10, fallbackProvider: 'cloudflare' },
@@ -164,6 +178,8 @@ const llm = new LLMProviders({
 });
 ```
 
+Default fallback priority includes all configured providers: Cloudflare → Cerebras → Groq → Anthropic → OpenAI.
+
 ## Error Handling
 
 Structured error classes for each failure mode:
@@ -175,7 +191,6 @@ import {
   AuthenticationError,
   CircuitBreakerOpenError,
   TimeoutError,
-  LLMErrorFactory,
 } from '@stackbilt/llm-providers';
 
 try {
@@ -193,14 +208,16 @@ try {
 
 ## Model Constants
 
-Predefined model identifiers for convenience:
-
 ```typescript
 import { MODELS, getRecommendedModel } from '@stackbilt/llm-providers';
 
-MODELS.GPT_4O;              // 'gpt-4o'
-MODELS.CLAUDE_3_5_SONNET;   // 'claude-3-5-sonnet-20241022'
-MODELS.LLAMA_3_1_8B;        // '@cf/meta/llama-3.1-8b-instruct'
+// Current-gen models
+MODELS.CLAUDE_OPUS_4_6;         // 'claude-opus-4-6-20250618'
+MODELS.CLAUDE_SONNET_4_6;       // 'claude-sonnet-4-6-20250618'
+MODELS.CLAUDE_HAIKU_4_5;        // 'claude-haiku-4-5-20251001'
+MODELS.GPT_4O;                  // 'gpt-4o'
+MODELS.GPT_4O_MINI;             // 'gpt-4o-mini'
+MODELS.CEREBRAS_ZAI_GLM_4_7;    // 'zai-glm-4.7'
 
 // Get best model for a use case given available providers
 const model = getRecommendedModel('COST_EFFECTIVE', ['openai', 'cloudflare']);
@@ -214,32 +231,43 @@ const model = getRecommendedModel('COST_EFFECTIVE', ['openai', 'cloudflare']);
 |-------|-------------|
 | `LLMProviders` | High-level facade -- initialize providers, generate responses, check health |
 | `LLMProviderFactory` | Lower-level factory with provider chain building and fallback logic |
-| `OpenAIProvider` | OpenAI GPT models (streaming, tools, batch) |
+| `OpenAIProvider` | OpenAI GPT models (streaming, tools) |
 | `AnthropicProvider` | Anthropic Claude models (streaming, tools) |
-| `CloudflareProvider` | Cloudflare Workers AI (streaming, batch, cost optimization) |
+| `CloudflareProvider` | Cloudflare Workers AI (streaming, tools on GPT-OSS, batch) |
+| `CerebrasProvider` | Cerebras fast inference (streaming, tools on GLM/Qwen) |
+| `GroqProvider` | Groq fast inference (streaming) |
 | `BaseProvider` | Abstract base with shared resiliency, metrics, and cost calculation |
 
 ### Utilities
 
 | Class | Description |
 |-------|-------------|
-| `CircuitBreaker` | Per-provider circuit breaker state machine |
+| `CircuitBreaker` | Graduated 4-state circuit breaker with probabilistic degradation |
 | `CircuitBreakerManager` | Manages circuit breakers across multiple providers |
 | `RetryManager` | Exponential backoff retry with jitter |
 | `CostTracker` | Per-provider cost accumulation and budget alerts |
+| `CreditLedger` | Monthly budgets, rate limits, burn rate projection, threshold events |
 | `CostOptimizer` | Static methods for optimal provider selection |
+| `ImageProvider` | Multi-provider image generation (Cloudflare SDXL/FLUX, Google Gemini) |
+
+### Logger
+
+| Export | Description |
+|--------|-------------|
+| `Logger` | Interface: `debug`, `info`, `warn`, `error` methods |
+| `noopLogger` | Silent logger (default) |
+| `consoleLogger` | Forwards to `console.*` (opt-in) |
 
 ### Key Types
 
 | Type | Description |
 |------|-------------|
-| `LLMRequest` | Unified request: messages, model, temperature, tools, metadata |
-| `LLMResponse` | Unified response: message, usage, provider, cost, tool calls |
-| `LLMProvider` | Provider interface: generateResponse, healthCheck, estimateCost |
-| `ProviderFactoryConfig` | Factory configuration: provider configs, fallback rules, flags |
-| `CircuitBreakerConfig` | Failure threshold, reset timeout, monitoring period |
-| `RetryConfig` | Max retries, delays, backoff multiplier, retryable error codes |
-| `CostConfig` | Token costs, monthly budget, alert threshold |
+| `LLMRequest` | Unified request: messages, model, temperature, tools, response_format |
+| `LLMResponse` | Unified response: message, usage (with cost), provider, tool calls |
+| `TokenUsage` | Token counts and cost (inputTokens, outputTokens, totalTokens, cost) |
+| `ProviderFactoryConfig` | Factory config: provider configs, fallback rules, ledger, logger |
+| `CostAnalytics` | Cost breakdown, total, and recommendations |
+| `ProviderHealthEntry` | Health status, metrics, circuit breaker state, capabilities |
 
 ### Factory Functions
 
@@ -247,8 +275,7 @@ const model = getRecommendedModel('COST_EFFECTIVE', ['openai', 'cloudflare']);
 |----------|-------------|
 | `createLLMProviders(config)` | Create an `LLMProviders` instance |
 | `createCostOptimizedLLMProviders(config)` | Create with cost optimization, circuit breakers, and retries enabled |
-| `createLLMProviderFactory(config)` | Create a bare `LLMProviderFactory` |
-| `createCostOptimizedFactory(config)` | Create a cost-optimized factory |
+| `LLMProviders.fromEnv(env)` | Auto-discover providers from environment variables |
 | `getRecommendedModel(useCase, providers)` | Pick the best model for a use case |
 | `retry(fn, config)` | One-shot retry wrapper for any async function |
 

package/dist/errors.d.ts

@@ -50,11 +50,27 @@ export declare class CircuitBreakerOpenError extends LLMProviderError {
     consecutiveFailures: number;
     constructor(provider: string, retryAfterSec?: number, consecutiveFailures?: number);
 }
+export declare class ToolLoopLimitError extends LLMProviderError {
+    constructor(provider: string, message?: string);
+}
+export declare class ToolLoopAbortedError extends LLMProviderError {
+    constructor(provider: string, message?: string);
+}
 /**
  * Error factory for creating provider-specific errors from HTTP responses
  */
+/** Shape of error response bodies across all LLM providers. */
+interface ErrorResponseBody {
+    message?: string;
+    error?: {
+        message?: string;
+        code?: string;
+        type?: string;
+        param?: string;
+    };
+}
 export declare class LLMErrorFactory {
-    static fromHttpResponse(provider: string, statusCode: number, responseBody?: any, message?: string): LLMProviderError;
+    static fromHttpResponse(provider: string, statusCode: number, responseBody?: ErrorResponseBody, message?: string): LLMProviderError;
     /**
      * Create error from fetch response
      */
@@ -76,4 +92,5 @@ export declare class LLMErrorFactory {
      */
     static getRetryDelay(error: Error): number;
 }
+export {};
 //# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAExC,qBAAa,gBAAiB,SAAQ,KAAM,YAAW,QAAQ;IAC7D,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,OAAO,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,aAAa,CAAC,EAAE,OAAO,CAAC;gBAGtB,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,EAChB,SAAS,GAAE,OAAe,EAC1B,UAAU,CAAC,EAAE,MAAM;CAStB;AAED,qBAAa,cAAe,SAAQ,gBAAgB;gBACtC,QAAQ,EAAE,MAAM,EAAE,OAAO,GAAE,MAA8B;CAItE;AAED,qBAAa,kBAAmB,SAAQ,gBAAgB;gBAC1C,QAAQ,EAAE,MAAM,EAAE,OAAO,GAAE,MAAyB;CAIjE;AAED,qBAAa,mBAAoB,SAAQ,gBAAgB;gBAC3C,QAAQ,EAAE,MAAM,EAAE,OAAO,GAAE,MAAgC;CAGxE;AAED,qBAAa,mBAAoB,SAAQ,gBAAgB;gBAC3C,QAAQ,EAAE,MAAM,EAAE,OAAO,GAAE,MAA0B;CAGlE;AAED,qBAAa,kBAAmB,SAAQ,gBAAgB;gBAC1C,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM;CAG5C;AAED,qBAAa,YAAa,SAAQ,gBAAgB;gBACpC,QAAQ,EAAE,MAAM,EAAE,OAAO,GAAE,MAA0B;CAGlE;AAED,qBAAa,YAAa,SAAQ,gBAAgB;gBACpC,QAAQ,EAAE,MAAM,EAAE,OAAO,GAAE,MAAwB;CAGhE;AAED,qBAAa,WAAY,SAAQ,gBAAgB;gBACnC,QAAQ,EAAE,MAAM,EAAE,OAAO,GAAE,MAAgC,EAAE,UAAU,GAAE,MAAY;CAGlG;AAED,qBAAa,kBAAmB,SAAQ,gBAAgB;gBAC1C,QAAQ,EAAE,MAAM,EAAE,OAAO,GAAE,MAA2B;CAGnE;AAED,qBAAa,eAAgB,SAAQ,gBAAgB;gBACvC,QAAQ,EAAE,MAAM,EAAE,OAAO,GAAE,MAA+B;CAGvE;AAED,qBAAa,kBAAmB,SAAQ,gBAAgB;gBAC1C,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM;CAG9C;AAED,qBAAa,uBAAwB,SAAQ,gBAAgB;IAC3D,aAAa,EAAE,MAAM,CAAC;IACtB,mBAAmB,EAAE,MAAM,CAAC;gBAEhB,QAAQ,EAAE,MAAM,EAAE,aAAa,GAAE,MAAU,EAAE,mBAAmB,GAAE,MAAU;CAWzF;AAED;;GAEG;AACH,qBAAa,eAAe;IAC1B,MAAM,CAAC,gBAAgB,CACrB,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,EAClB,YAAY,CAAC,EAAE,GAAG,EAClB,OAAO,CAAC,EAAE,MAAM,GACf,gBAAgB;IA8CnB;;OAEG;WACU,iBAAiB,CAC5B,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,QAAQ,GACjB,OAAO,CAAC,gBAAgB,CAAC;IAiB5B;;OAEG;IACH,MAAM,CAAC,WAAW,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO;IAazC;;OAEG;IACH,MAAM,CAAC,aAAa,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO;IAI3C;;OAEG;IACH,MAAM,CAAC,eAAe,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO;IAI7C;;OAEG;IACH,MAAM,CAAC,aAAa,CAAC,KAAK,EAAE,KAAK,GAAG,MAAM;CAW3C"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"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"}

package/dist/errors.js

@@ -85,9 +85,16 @@ export class CircuitBreakerOpenError extends LLMProviderError {
         this.consecutiveFailures = consecutiveFailures;
     }
 }
-/**
- * Error factory for creating provider-specific errors from HTTP responses
- */
+export class ToolLoopLimitError extends LLMProviderError {
+    constructor(provider, message = 'Tool loop limit exceeded') {
+        super(message, 'TOOL_LOOP_LIMIT', provider, false, 400);
+    }
+}
+export class ToolLoopAbortedError extends LLMProviderError {
+    constructor(provider, message = 'Tool loop aborted') {
+        super(message, 'TOOL_LOOP_ABORTED', provider, false, 400);
+    }
+}
 export class LLMErrorFactory {
     static fromHttpResponse(provider, statusCode, responseBody, message) {
         const defaultMessage = message || responseBody?.message || responseBody?.error?.message || 'Unknown error';
@@ -102,9 +109,10 @@ export class LLMErrorFactory {
                 return new InvalidRequestError(provider, defaultMessage);
             case 401:
                 return new AuthenticationError(provider, defaultMessage);
-            case 404:
+            case 404: {
                 const model = responseBody?.error?.param || 'unknown';
                 return new ModelNotFoundError(provider, model);
+            }
             case 408:
                 return new TimeoutError(provider, defaultMessage);
             case 429:

package/dist/errors.js.map

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

package/dist/factory.d.ts

@@ -2,7 +2,10 @@
  * LLM Provider Factory
  * Creates and manages LLM provider instances with intelligent fallback logic
  */
-import type { LLMProvider, LLMRequest, LLMResponse, OpenAIConfig, AnthropicConfig, CloudflareConfig, CerebrasConfig, GroqConfig, FallbackRule } from './types';
+import type { LLMProvider, LLMRequest, LLMResponse, AnalyzeImageInput, ClassifyOptions, ClassifyResult, OpenAIConfig, AnthropicConfig, CloudflareConfig, CerebrasConfig, GroqConfig, FallbackRule, ProviderMetrics, CircuitBreakerState, ProviderBalance, QuotaHook, ToolExecutor, ToolLoopOptions } from './types';
+import type { Logger } from './utils/logger';
+import type { ObservabilityHooks } from './utils/hooks';
+import type { ProviderCostBreakdownEntry } from './utils/cost-tracker';
 import type { CreditLedger } from './utils/credit-ledger';
 export interface ProviderFactoryConfig {
     openai?: OpenAIConfig;
@@ -16,12 +19,37 @@ export interface ProviderFactoryConfig {
     enableCircuitBreaker?: boolean;
     enableRetries?: boolean;
     ledger?: CreditLedger;
+    quotaHook?: QuotaHook;
+    quotaFailPolicy?: 'closed' | 'open';
+    defaultVisionModel?: string;
+    logger?: Logger;
+    hooks?: ObservabilityHooks;
+}
+export interface CostAnalytics {
+    breakdown?: Record<string, ProviderCostBreakdownEntry>;
+    total?: number;
+    recommendations?: string[];
+    message?: string;
+}
+export interface ProviderHealthEntry {
+    healthy: boolean;
+    metrics?: ProviderMetrics;
+    circuitBreaker?: CircuitBreakerState | null;
+    models?: string[];
+    capabilities?: {
+        streaming: boolean;
+        tools: boolean;
+        batching: boolean;
+    };
+    error?: string;
 }
 export declare class LLMProviderFactory {
     private providers;
     private config;
     private costTracker;
     private fallbackRules;
+    private logger;
+    private hooks;
     constructor(config: ProviderFactoryConfig);
     /**
      * Initialize all configured providers
@@ -31,6 +59,11 @@ export declare class LLMProviderFactory {
      * Generate response with intelligent provider selection and fallback
      */
     generateResponse(request: LLMRequest): Promise<LLMResponse>;
+    generateResponseStream(request: LLMRequest): Promise<ReadableStream<string>>;
+    generateResponseWithTools(request: LLMRequest, toolExecutor: ToolExecutor, opts?: ToolLoopOptions): Promise<LLMResponse>;
+    classify<T = unknown>(input: string | LLMRequest, options?: ClassifyOptions<T>): Promise<ClassifyResult<T>>;
+    analyzeImage(input: AnalyzeImageInput): Promise<LLMResponse>;
+    getProviderBalance(provider?: string): Promise<ProviderBalance | Record<string, ProviderBalance>>;
     /**
      * Build provider chain based on request and configuration
      */
@@ -47,6 +80,10 @@ export declare class LLMProviderFactory {
      * Check if we should fallback to another provider
      */
     private shouldFallback;
+    /**
+     * Get fallback routing decision for an error.
+     */
+    private getFallbackDecision;
     /**
      * Evaluate a fallback rule against an error
      */
@@ -66,23 +103,44 @@ export declare class LLMProviderFactory {
     /**
      * Get provider health status
      */
-    getProviderHealth(): Promise<Record<string, any>>;
+    getProviderHealth(): Promise<Record<string, ProviderHealthEntry>>;
     /**
      * Get cost analytics
      */
-    getCostAnalytics(): any;
+    getCostAnalytics(): CostAnalytics;
     /**
      * Get cost optimization recommendations
      */
     private getCostRecommendations;
     /**
-     * Reset all provider metrics and circuit breakers
+     * Get latency histogram data for all providers
+     */
+    getLatencyHistogram(): Record<string, import('./utils/latency-histogram').LatencySummary>;
+    /**
+     * Get currently exhausted providers
+     */
+    getExhaustedProviders(): string[];
+    /**
+     * Reset all provider metrics, circuit breakers, exhaustion, and histograms
      */
     reset(): void;
     /**
      * Update factory configuration
      */
     updateConfig(config: Partial<ProviderFactoryConfig>): void;
+    private openStreamWithFirstChunk;
+    private buildFactoryStream;
+    private checkQuota;
+    private recordQuota;
+    private recordQuotaInput;
+    private parseJsonResponse;
+    private getDefaultVisionModel;
+    private providerSupportsVision;
+    private getSingleProviderBalance;
+    private getLedgerBalance;
+    private isLedgerLimited;
+    private requestForProvider;
+    private applyFallbackDecision;
 }
 /**
  * Create a provider factory with common configurations

package/dist/factory.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"factory.d.ts","sourceRoot":"","sources":["../src/factory.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EACV,WAAW,EAEX,UAAU,EACV,WAAW,EACX,YAAY,EACZ,eAAe,EACf,gBAAgB,EAChB,cAAc,EACd,UAAU,EACV,YAAY,EAEb,MAAM,SAAS,CAAC;AAQjB,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAU1D,MAAM,WAAW,qBAAqB;IACpC,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,SAAS,CAAC,EAAE,eAAe,CAAC;IAC5B,UAAU,CAAC,EAAE,gBAAgB,CAAC;IAC9B,QAAQ,CAAC,EAAE,cAAc,CAAC;IAC1B,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB,eAAe,CAAC,EAAE,QAAQ,GAAG,WAAW,GAAG,YAAY,GAAG,UAAU,GAAG,MAAM,GAAG,MAAM,CAAC;IACvF,aAAa,CAAC,EAAE,YAAY,EAAE,CAAC;IAC/B,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,MAAM,CAAC,EAAE,YAAY,CAAC;CACvB;AAED,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,SAAS,CAAuC;IACxD,OAAO,CAAC,MAAM,CAAwB;IACtC,OAAO,CAAC,WAAW,CAAc;IACjC,OAAO,CAAC,aAAa,CAAiB;gBAE1B,MAAM,EAAE,qBAAqB;IAQzC;;OAEG;IACH,OAAO,CAAC,mBAAmB;IAuE3B;;OAEG;IACG,gBAAgB,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,WAAW,CAAC;IAkDjE;;OAEG;IACH,OAAO,CAAC,kBAAkB;IA8B1B;;OAEG;IACH,OAAO,CAAC,uBAAuB;IA2B/B;;OAEG;IACH,OAAO,CAAC,mBAAmB;IA8B3B;;OAEG;IACH,OAAO,CAAC,cAAc;IA8BtB;;OAEG;IACH,OAAO,CAAC,oBAAoB;IAyB5B;;OAEG;IACH,OAAO,CAAC,uBAAuB;IAkB/B;;OAEG;IACH,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS;IAIlD;;OAEG;IACH,qBAAqB,IAAI,MAAM,EAAE;IAIjC;;OAEG;IACG,iBAAiB,IAAI,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAiCvD;;OAEG;IACH,gBAAgB,IAAI,GAAG;IAYvB;;OAEG;IACH,OAAO,CAAC,sBAAsB;IAuB9B;;OAEG;IACH,KAAK,IAAI,IAAI;IAab;;OAEG;IACH,YAAY,CAAC,MAAM,EAAE,OAAO,CAAC,qBAAqB,CAAC,GAAG,IAAI;CAa3D;AAED;;GAEG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,qBAAqB,GAAG,kBAAkB,CAE1F;AAED;;GAEG;AACH,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,qBAAqB,GAAG,kBAAkB,CAa5F"}
+{"version":3,"file":"factory.d.ts","sourceRoot":"","sources":["../src/factory.ts"],"names":[],"mappings":"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"}