@dotsetlabs/bellwether 0.10.0

package/dist/llm/factory.js

@@ -0,0 +1,145 @@
+/**
+ * LLM provider factory - creates and auto-detects providers.
+ */
+import { DEFAULT_MODELS } from './client.js';
+import { OpenAIClient } from './openai.js';
+import { AnthropicClient } from './anthropic.js';
+import { OllamaClient } from './ollama.js';
+/**
+ * Create an LLM client from configuration.
+ */
+export function createLLMClient(config) {
+    const apiKey = resolveApiKey(config);
+    switch (config.provider) {
+        case 'openai':
+            return new OpenAIClient({
+                apiKey,
+                model: config.model,
+                baseURL: config.baseUrl,
+                onUsage: config.onUsage,
+            });
+        case 'anthropic':
+            return new AnthropicClient({
+                apiKey,
+                model: config.model,
+                baseURL: config.baseUrl,
+                onUsage: config.onUsage,
+            });
+        case 'ollama':
+            return new OllamaClient({
+                baseUrl: config.baseUrl,
+                model: config.model,
+                onUsage: config.onUsage,
+            });
+        default:
+            throw new Error(`Unknown LLM provider: ${config.provider}`);
+    }
+}
+/**
+ * Resolve API key from config or environment.
+ */
+function resolveApiKey(config) {
+    // Direct API key takes precedence
+    if (config.apiKey) {
+        return config.apiKey;
+    }
+    // Check specified env var
+    if (config.apiKeyEnvVar) {
+        const key = process.env[config.apiKeyEnvVar];
+        if (!key) {
+            throw new Error(`Environment variable ${config.apiKeyEnvVar} is not set`);
+        }
+        return key;
+    }
+    // Default env vars per provider
+    const defaultEnvVars = {
+        openai: 'OPENAI_API_KEY',
+        anthropic: 'ANTHROPIC_API_KEY',
+        ollama: '', // Ollama doesn't need an API key
+    };
+    const defaultVar = defaultEnvVars[config.provider];
+    if (defaultVar) {
+        return process.env[defaultVar];
+    }
+    return undefined;
+}
+/**
+ * Auto-detect the best available provider based on environment.
+ */
+export function detectProvider() {
+    // Check for API keys in order of preference
+    if (process.env.ANTHROPIC_API_KEY) {
+        return 'anthropic';
+    }
+    if (process.env.OPENAI_API_KEY) {
+        return 'openai';
+    }
+    // Fall back to Ollama (local, no API key needed)
+    return 'ollama';
+}
+/**
+ * Create an LLM client with auto-detection.
+ * Uses environment variables to determine the best provider.
+ */
+export function createAutoClient(modelOverride) {
+    const provider = detectProvider();
+    return createLLMClient({
+        provider,
+        model: modelOverride ?? DEFAULT_MODELS[provider],
+    });
+}
+/**
+ * Check which providers are available.
+ */
+export async function checkProviderAvailability() {
+    const results = [];
+    // Check OpenAI
+    if (process.env.OPENAI_API_KEY) {
+        results.push({ provider: 'openai', available: true });
+    }
+    else {
+        results.push({
+            provider: 'openai',
+            available: false,
+            reason: 'OPENAI_API_KEY not set',
+        });
+    }
+    // Check Anthropic
+    if (process.env.ANTHROPIC_API_KEY) {
+        results.push({ provider: 'anthropic', available: true });
+    }
+    else {
+        results.push({
+            provider: 'anthropic',
+            available: false,
+            reason: 'ANTHROPIC_API_KEY not set',
+        });
+    }
+    // Check Ollama
+    const ollama = new OllamaClient();
+    const ollamaAvailable = await ollama.isAvailable();
+    if (ollamaAvailable) {
+        results.push({ provider: 'ollama', available: true });
+    }
+    else {
+        results.push({
+            provider: 'ollama',
+            available: false,
+            reason: 'Ollama not running (start with: ollama serve)',
+        });
+    }
+    return results;
+}
+/**
+ * Get the default model for a provider.
+ */
+export function getDefaultModel(provider) {
+    return DEFAULT_MODELS[provider];
+}
+/**
+ * List all supported providers.
+ */
+export function getSupportedProviders() {
+    return ['openai', 'anthropic', 'ollama'];
+}
+//# sourceMappingURL=factory.js.map

package/dist/llm/fallback.d.ts

@@ -0,0 +1,140 @@
+/**
+ * Fallback LLM client that tries multiple providers in sequence.
+ * Provides resilience through provider failover and model fallback.
+ */
+import type { LLMClient, Message, CompletionOptions, ProviderInfo, LLMConfig, LLMProviderId, StreamingOptions, StreamingResult } from './client.js';
+/**
+ * Health status for a provider.
+ */
+export interface ProviderHealth {
+    provider: LLMProviderId;
+    healthy: boolean;
+    lastChecked: Date;
+    lastError?: string;
+    consecutiveFailures: number;
+}
+/**
+ * Configuration for fallback behavior.
+ */
+export interface FallbackConfig {
+    /** Primary provider configurations in priority order */
+    providers: LLMConfig[];
+    /** Whether to use Ollama as final fallback (default: true) */
+    useOllamaFallback?: boolean;
+    /** Ollama model to use for fallback */
+    ollamaModel?: string;
+    /** Health check interval in ms (default: 60000) */
+    healthCheckIntervalMs?: number;
+    /** Max consecutive failures before marking unhealthy (default: 3) */
+    maxConsecutiveFailures?: number;
+    /** Time to wait before retrying unhealthy provider in ms (default: 300000) */
+    unhealthyRetryDelayMs?: number;
+    /** Callback for usage tracking (applied to all providers) */
+    onUsage?: (inputTokens: number, outputTokens: number) => void;
+}
+/**
+ * Fallback result with metadata.
+ */
+export interface FallbackResult {
+    response: string;
+    provider: LLMProviderId;
+    model: string;
+    attemptedProviders: LLMProviderId[];
+    failedProviders: Array<{
+        provider: LLMProviderId;
+        error: string;
+    }>;
+}
+/**
+ * LLM client with automatic provider failover.
+ */
+export declare class FallbackLLMClient implements LLMClient {
+    private clients;
+    private providerOrder;
+    private health;
+    private config;
+    constructor(config: FallbackConfig);
+    /**
+     * Initialize all provider clients.
+     */
+    private initializeClients;
+    /**
+     * Get combined provider info.
+     */
+    getProviderInfo(): ProviderInfo;
+    /**
+     * Get the current primary (first healthy) client.
+     */
+    private getPrimaryClient;
+    /**
+     * Check if a provider is currently healthy.
+     */
+    private isProviderHealthy;
+    /**
+     * Mark a provider as failed.
+     */
+    private markProviderFailed;
+    /**
+     * Mark a provider as successful.
+     */
+    private markProviderSuccess;
+    /**
+     * Determine if an error should trigger failover to next provider.
+     */
+    private shouldFailover;
+    /**
+     * Execute a completion with fallback.
+     */
+    private executeWithFallback;
+    /**
+     * Chat completion with fallback.
+     */
+    chat(messages: Message[], options?: CompletionOptions): Promise<string>;
+    /**
+     * Single prompt completion with fallback.
+     */
+    complete(prompt: string, options?: CompletionOptions): Promise<string>;
+    /**
+     * Parse JSON from response.
+     */
+    parseJSON<T>(response: string): T;
+    /**
+     * Stream completion from a single prompt with fallback.
+     */
+    stream(prompt: string, options?: StreamingOptions): Promise<StreamingResult>;
+    /**
+     * Stream chat completion with fallback.
+     */
+    streamChat(messages: Message[], options?: StreamingOptions): Promise<StreamingResult>;
+    /**
+     * Get health status for all providers.
+     */
+    getProviderHealth(): ProviderHealth[];
+    /**
+     * Get list of available providers in priority order.
+     */
+    getProviderOrder(): LLMProviderId[];
+    /**
+     * Check health of all providers (for Ollama this pings the server).
+     */
+    checkHealth(): Promise<ProviderHealth[]>;
+    /**
+     * Manually mark a provider as unhealthy.
+     */
+    disableProvider(providerId: LLMProviderId): void;
+    /**
+     * Manually mark a provider as healthy.
+     */
+    enableProvider(providerId: LLMProviderId): void;
+}
+/**
+ * Create a fallback LLM client from available providers.
+ * Automatically detects available API keys and sets up fallback chain.
+ */
+export declare function createFallbackClient(options?: {
+    preferredOrder?: LLMProviderId[];
+    useOllamaFallback?: boolean;
+    ollamaModel?: string;
+    onUsage?: (inputTokens: number, outputTokens: number) => void;
+}): FallbackLLMClient;
+//# sourceMappingURL=fallback.d.ts.map

package/dist/llm/fallback.js

@@ -0,0 +1,379 @@
+/**
+ * Fallback LLM client that tries multiple providers in sequence.
+ * Provides resilience through provider failover and model fallback.
+ */
+import { parseJSONResponse, DEFAULT_MODELS } from './client.js';
+import { createLLMClient } from './factory.js';
+import { OllamaClient } from './ollama.js';
+import { getLogger } from '../logging/logger.js';
+import { LLMAuthError, LLMQuotaError, LLMConnectionError, LLMRateLimitError, } from '../errors/types.js';
+import { TIME_CONSTANTS, RETRY } from '../constants.js';
+const logger = getLogger('fallback-llm');
+/**
+ * LLM client with automatic provider failover.
+ */
+export class FallbackLLMClient {
+    clients = new Map();
+    providerOrder = [];
+    health = new Map();
+    config;
+    constructor(config) {
+        this.config = {
+            providers: config.providers,
+            useOllamaFallback: config.useOllamaFallback ?? true,
+            ollamaModel: config.ollamaModel ?? DEFAULT_MODELS.ollama,
+            healthCheckIntervalMs: config.healthCheckIntervalMs ?? TIME_CONSTANTS.HEALTH_CHECK_INTERVAL,
+            maxConsecutiveFailures: config.maxConsecutiveFailures ?? RETRY.DEFAULT_ATTEMPTS,
+            unhealthyRetryDelayMs: config.unhealthyRetryDelayMs ?? TIME_CONSTANTS.UNHEALTHY_RETRY_DELAY,
+            onUsage: config.onUsage,
+        };
+        this.initializeClients();
+    }
+    /**
+     * Initialize all provider clients.
+     */
+    initializeClients() {
+        for (const providerConfig of this.config.providers) {
+            try {
+                // Apply shared onUsage callback
+                const configWithUsage = {
+                    ...providerConfig,
+                    onUsage: this.config.onUsage,
+                };
+                const client = createLLMClient(configWithUsage);
+                this.clients.set(providerConfig.provider, client);
+                this.providerOrder.push(providerConfig.provider);
+                this.health.set(providerConfig.provider, {
+                    provider: providerConfig.provider,
+                    healthy: true,
+                    lastChecked: new Date(),
+                    consecutiveFailures: 0,
+                });
+                logger.debug({ provider: providerConfig.provider }, 'Initialized provider');
+            }
+            catch (error) {
+                logger.warn({ provider: providerConfig.provider, error: String(error) }, 'Failed to initialize provider');
+            }
+        }
+        // Add Ollama as final fallback if enabled
+        if (this.config.useOllamaFallback && !this.clients.has('ollama')) {
+            try {
+                const ollamaClient = new OllamaClient({
+                    model: this.config.ollamaModel,
+                });
+                this.clients.set('ollama', ollamaClient);
+                this.providerOrder.push('ollama');
+                this.health.set('ollama', {
+                    provider: 'ollama',
+                    healthy: true, // Assume healthy until checked
+                    lastChecked: new Date(),
+                    consecutiveFailures: 0,
+                });
+                logger.debug('Added Ollama as fallback provider');
+            }
+            catch (error) {
+                logger.warn({ error: String(error) }, 'Failed to initialize Ollama fallback');
+            }
+        }
+        if (this.clients.size === 0) {
+            throw new Error('No LLM providers could be initialized');
+        }
+    }
+    /**
+     * Get combined provider info.
+     */
+    getProviderInfo() {
+        const primaryClient = this.getPrimaryClient();
+        const info = primaryClient.getProviderInfo();
+        return {
+            ...info,
+            id: `fallback(${this.providerOrder.join(',')})`,
+            name: `Fallback: ${info.name}`,
+        };
+    }
+    /**
+     * Get the current primary (first healthy) client.
+     */
+    getPrimaryClient() {
+        for (const providerId of this.providerOrder) {
+            if (this.isProviderHealthy(providerId)) {
+                const client = this.clients.get(providerId);
+                if (client)
+                    return client;
+            }
+        }
+        // Return first client as fallback (guaranteed to exist from constructor check)
+        const firstClient = this.clients.values().next().value;
+        if (!firstClient) {
+            throw new Error('No LLM clients available');
+        }
+        return firstClient;
+    }
+    /**
+     * Check if a provider is currently healthy.
+     */
+    isProviderHealthy(providerId) {
+        const health = this.health.get(providerId);
+        if (!health)
+            return false;
+        // If marked unhealthy, check if retry delay has passed
+        if (!health.healthy) {
+            const timeSinceCheck = Date.now() - health.lastChecked.getTime();
+            if (timeSinceCheck >= this.config.unhealthyRetryDelayMs) {
+                // Reset to allow retry
+                health.healthy = true;
+                health.consecutiveFailures = 0;
+                logger.info({ provider: providerId }, 'Resetting unhealthy provider for retry');
+            }
+        }
+        return health.healthy;
+    }
+    /**
+     * Mark a provider as failed.
+     */
+    markProviderFailed(providerId, error) {
+        const health = this.health.get(providerId);
+        if (!health)
+            return;
+        health.consecutiveFailures++;
+        health.lastError = error.message;
+        health.lastChecked = new Date();
+        // Check if we should mark as unhealthy
+        if (health.consecutiveFailures >= this.config.maxConsecutiveFailures) {
+            health.healthy = false;
+            logger.warn({
+                provider: providerId,
+                consecutiveFailures: health.consecutiveFailures,
+                error: error.message,
+            }, 'Marking provider as unhealthy');
+        }
+    }
+    /**
+     * Mark a provider as successful.
+     */
+    markProviderSuccess(providerId) {
+        const health = this.health.get(providerId);
+        if (!health)
+            return;
+        health.healthy = true;
+        health.consecutiveFailures = 0;
+        health.lastChecked = new Date();
+        health.lastError = undefined;
+    }
+    /**
+     * Determine if an error should trigger failover to next provider.
+     */
+    shouldFailover(error) {
+        // Auth and quota errors are terminal for that provider - failover
+        if (error instanceof LLMAuthError || error instanceof LLMQuotaError) {
+            return true;
+        }
+        // Connection errors - failover
+        if (error instanceof LLMConnectionError) {
+            return true;
+        }
+        // Rate limits - failover (they have their own retry logic)
+        if (error instanceof LLMRateLimitError) {
+            return true;
+        }
+        // Check error message for common failover conditions
+        if (error instanceof Error) {
+            const message = error.message.toLowerCase();
+            if (message.includes('econnrefused') ||
+                message.includes('econnreset') ||
+                message.includes('network') ||
+                message.includes('timeout') ||
+                message.includes('unavailable') ||
+                message.includes('503') ||
+                message.includes('502')) {
+                return true;
+            }
+        }
+        return false;
+    }
+    /**
+     * Execute a completion with fallback.
+     */
+    async executeWithFallback(operation, operationName) {
+        const attemptedProviders = [];
+        const errors = [];
+        for (const providerId of this.providerOrder) {
+            if (!this.isProviderHealthy(providerId)) {
+                logger.debug({ provider: providerId }, 'Skipping unhealthy provider');
+                continue;
+            }
+            const client = this.clients.get(providerId);
+            if (!client)
+                continue;
+            attemptedProviders.push(providerId);
+            try {
+                logger.debug({ provider: providerId, operation: operationName }, 'Attempting operation');
+                const result = await operation(client);
+                this.markProviderSuccess(providerId);
+                return { result, provider: providerId };
+            }
+            catch (error) {
+                const err = error instanceof Error ? error : new Error(String(error));
+                errors.push({ provider: providerId, error: err });
+                this.markProviderFailed(providerId, err);
+                logger.warn({
+                    provider: providerId,
+                    operation: operationName,
+                    error: err.message,
+                    shouldFailover: this.shouldFailover(error),
+                }, 'Provider operation failed');
+                if (!this.shouldFailover(error)) {
+                    // Non-failover error - throw immediately
+                    throw error;
+                }
+                // Continue to next provider
+            }
+        }
+        // All providers failed
+        const errorSummary = errors
+            .map(({ provider, error }) => `${provider}: ${error.message}`)
+            .join('; ');
+        throw new Error(`All LLM providers failed for ${operationName}. Errors: ${errorSummary}`);
+    }
+    /**
+     * Chat completion with fallback.
+     */
+    async chat(messages, options) {
+        const { result } = await this.executeWithFallback((client) => client.chat(messages, options), 'chat');
+        return result;
+    }
+    /**
+     * Single prompt completion with fallback.
+     */
+    async complete(prompt, options) {
+        const { result } = await this.executeWithFallback((client) => client.complete(prompt, options), 'complete');
+        return result;
+    }
+    /**
+     * Parse JSON from response.
+     */
+    parseJSON(response) {
+        return parseJSONResponse(response);
+    }
+    /**
+     * Stream completion from a single prompt with fallback.
+     */
+    async stream(prompt, options) {
+        const { result } = await this.executeWithFallback((client) => client.stream(prompt, options), 'stream');
+        return result;
+    }
+    /**
+     * Stream chat completion with fallback.
+     */
+    async streamChat(messages, options) {
+        const { result } = await this.executeWithFallback((client) => client.streamChat(messages, options), 'streamChat');
+        return result;
+    }
+    /**
+     * Get health status for all providers.
+     */
+    getProviderHealth() {
+        return Array.from(this.health.values());
+    }
+    /**
+     * Get list of available providers in priority order.
+     */
+    getProviderOrder() {
+        return [...this.providerOrder];
+    }
+    /**
+     * Check health of all providers (for Ollama this pings the server).
+     */
+    async checkHealth() {
+        const results = [];
+        for (const providerId of this.providerOrder) {
+            const client = this.clients.get(providerId);
+            const health = this.health.get(providerId);
+            if (!client || !health)
+                continue;
+            try {
+                // For Ollama, use isAvailable()
+                if (providerId === 'ollama' && client instanceof OllamaClient) {
+                    const available = await client.isAvailable();
+                    health.healthy = available;
+                    health.lastChecked = new Date();
+                    if (!available) {
+                        health.lastError = 'Ollama server not responding';
+                    }
+                    else {
+                        health.lastError = undefined;
+                        health.consecutiveFailures = 0;
+                    }
+                }
+                else {
+                    // For API providers, we assume healthy if we have credentials
+                    // Actual health is determined by request success/failure
+                    health.lastChecked = new Date();
+                }
+            }
+            catch (error) {
+                health.healthy = false;
+                health.lastError = error instanceof Error ? error.message : String(error);
+                health.lastChecked = new Date();
+            }
+            results.push({ ...health });
+        }
+        return results;
+    }
+    /**
+     * Manually mark a provider as unhealthy.
+     */
+    disableProvider(providerId) {
+        const health = this.health.get(providerId);
+        if (health) {
+            health.healthy = false;
+            health.lastChecked = new Date();
+            logger.info({ provider: providerId }, 'Provider manually disabled');
+        }
+    }
+    /**
+     * Manually mark a provider as healthy.
+     */
+    enableProvider(providerId) {
+        const health = this.health.get(providerId);
+        if (health) {
+            health.healthy = true;
+            health.consecutiveFailures = 0;
+            health.lastError = undefined;
+            health.lastChecked = new Date();
+            logger.info({ provider: providerId }, 'Provider manually enabled');
+        }
+    }
+}
+/**
+ * Create a fallback LLM client from available providers.
+ * Automatically detects available API keys and sets up fallback chain.
+ */
+export function createFallbackClient(options) {
+    const providers = [];
+    const order = options?.preferredOrder ?? ['anthropic', 'openai', 'ollama'];
+    for (const providerId of order) {
+        if (providerId === 'anthropic' && process.env.ANTHROPIC_API_KEY) {
+            providers.push({
+                provider: 'anthropic',
+                model: DEFAULT_MODELS.anthropic,
+            });
+        }
+        else if (providerId === 'openai' && process.env.OPENAI_API_KEY) {
+            providers.push({
+                provider: 'openai',
+                model: DEFAULT_MODELS.openai,
+            });
+        }
+        else if (providerId === 'ollama') {
+            // Ollama will be added as fallback if useOllamaFallback is true
+        }
+    }
+    return new FallbackLLMClient({
+        providers,
+        useOllamaFallback: options?.useOllamaFallback ?? true,
+        ollamaModel: options?.ollamaModel,
+        onUsage: options?.onUsage,
+    });
+}
+//# sourceMappingURL=fallback.js.map

package/dist/llm/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * LLM module - multi-provider language model support.
+ */
+export type { LLMClient, Message, CompletionOptions, ProviderInfo, LLMConfig, LLMProviderId, StreamingOptions, StreamingResult, } from './client.js';
+export { DEFAULT_MODELS, PREMIUM_MODELS, parseJSONResponse } from './client.js';
+export { OpenAIClient } from './openai.js';
+export type { OpenAIClientOptions } from './openai.js';
+export { AnthropicClient } from './anthropic.js';
+export type { AnthropicClientOptions } from './anthropic.js';
+export { OllamaClient } from './ollama.js';
+export type { OllamaClientOptions } from './ollama.js';
+export { createLLMClient, createAutoClient, detectProvider, checkProviderAvailability, getDefaultModel, getSupportedProviders, } from './factory.js';
+export type { ProviderAvailability } from './factory.js';
+export { FallbackLLMClient, createFallbackClient } from './fallback.js';
+export type { FallbackConfig, ProviderHealth, FallbackResult } from './fallback.js';
+export { estimateTokens, estimateMessagesTokens, estimateWithContext, getContextWindow, truncateMessages, truncateText, TokenBudgetTracker, BudgetEnforcedLLMClient, TokenBudgetExceededError, withTokenBudget, } from './token-budget.js';
+export type { TokenBudgetOptions, TokenEstimate, BudgetStatus, } from './token-budget.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/llm/index.js

@@ -0,0 +1,15 @@
+/**
+ * LLM module - multi-provider language model support.
+ */
+export { DEFAULT_MODELS, PREMIUM_MODELS, parseJSONResponse } from './client.js';
+// Provider implementations
+export { OpenAIClient } from './openai.js';
+export { AnthropicClient } from './anthropic.js';
+export { OllamaClient } from './ollama.js';
+// Factory functions
+export { createLLMClient, createAutoClient, detectProvider, checkProviderAvailability, getDefaultModel, getSupportedProviders, } from './factory.js';
+// Fallback client
+export { FallbackLLMClient, createFallbackClient } from './fallback.js';
+// Token budget enforcement
+export { estimateTokens, estimateMessagesTokens, estimateWithContext, getContextWindow, truncateMessages, truncateText, TokenBudgetTracker, BudgetEnforcedLLMClient, TokenBudgetExceededError, withTokenBudget, } from './token-budget.js';
+//# sourceMappingURL=index.js.map