@timmeck/brain-core 2.36.12 → 2.36.15

package/dist/llm/anthropic-provider.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Anthropic Claude Provider — Cloud LLM
+ *
+ * Standard-Provider für das Brain Ecosystem.
+ * Nutzt die Anthropic Messages API direkt via fetch.
+ *
+ * Einrichten:
+ *   In .env: ANTHROPIC_API_KEY=sk-ant-...
+ *   Oder:    new AnthropicProvider({ apiKey: '...' })
+ */
+import type { LLMProvider, LLMMessage, LLMCallOptions, LLMProviderResponse } from './provider.js';
+export interface AnthropicProviderConfig {
+    /** API key. Falls back to ANTHROPIC_API_KEY env var. */
+    apiKey?: string;
+    /** Model to use. Default: claude-sonnet-4-20250514 */
+    model?: string;
+    /** Max tokens per request. Default: 2048 */
+    maxTokens?: number;
+    /** API base URL. Default: https://api.anthropic.com */
+    baseUrl?: string;
+}
+export declare class AnthropicProvider implements LLMProvider {
+    readonly name = "anthropic";
+    readonly costTier: "expensive";
+    readonly capabilities: {
+        chat: boolean;
+        generate: boolean;
+        embed: boolean;
+        reasoning: boolean;
+    };
+    private readonly apiKey;
+    private readonly model;
+    private readonly maxTokens;
+    private readonly baseUrl;
+    private readonly log;
+    constructor(config?: AnthropicProviderConfig);
+    isAvailable(): Promise<boolean>;
+    chat(messages: LLMMessage[], options?: LLMCallOptions): Promise<LLMProviderResponse>;
+    generate(prompt: string, options?: LLMCallOptions): Promise<string>;
+    embed(_text: string): Promise<number[]>;
+}

package/dist/llm/anthropic-provider.js

@@ -0,0 +1,86 @@
+/**
+ * Anthropic Claude Provider — Cloud LLM
+ *
+ * Standard-Provider für das Brain Ecosystem.
+ * Nutzt die Anthropic Messages API direkt via fetch.
+ *
+ * Einrichten:
+ *   In .env: ANTHROPIC_API_KEY=sk-ant-...
+ *   Oder:    new AnthropicProvider({ apiKey: '...' })
+ */
+import { getLogger } from '../utils/logger.js';
+export class AnthropicProvider {
+    name = 'anthropic';
+    costTier = 'expensive';
+    capabilities = {
+        chat: true,
+        generate: true,
+        embed: false,
+        reasoning: false,
+    };
+    apiKey;
+    model;
+    maxTokens;
+    baseUrl;
+    log = getLogger();
+    constructor(config = {}) {
+        this.apiKey = config.apiKey ?? process.env.ANTHROPIC_API_KEY ?? null;
+        this.model = config.model ?? 'claude-sonnet-4-20250514';
+        this.maxTokens = config.maxTokens ?? 2048;
+        this.baseUrl = config.baseUrl ?? 'https://api.anthropic.com';
+    }
+    async isAvailable() {
+        return this.apiKey !== null && this.apiKey.length > 0;
+    }
+    async chat(messages, options) {
+        if (!this.apiKey) {
+            throw new Error('AnthropicProvider: No API key configured');
+        }
+        // Separate system message from conversation
+        const systemMessages = messages.filter(m => m.role === 'system');
+        const conversationMessages = messages.filter(m => m.role !== 'system');
+        const systemPrompt = systemMessages.map(m => m.content).join('\n') || undefined;
+        const start = Date.now();
+        const response = await fetch(`${this.baseUrl}/v1/messages`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'x-api-key': this.apiKey,
+                'anthropic-version': '2023-06-01',
+            },
+            body: JSON.stringify({
+                model: this.model,
+                max_tokens: options?.maxTokens ?? this.maxTokens,
+                ...(options?.temperature !== undefined ? { temperature: options.temperature } : {}),
+                ...(systemPrompt ? { system: systemPrompt } : {}),
+                messages: conversationMessages.map(m => ({ role: m.role, content: m.content })),
+            }),
+        });
+        const durationMs = Date.now() - start;
+        if (!response.ok) {
+            const errText = await response.text();
+            throw new Error(`Anthropic API error (${response.status}): ${errText.substring(0, 200)}`);
+        }
+        const data = await response.json();
+        const text = data.content
+            ?.filter(c => c.type === 'text')
+            .map(c => c.text ?? '')
+            .join('\n') ?? '';
+        return {
+            text,
+            inputTokens: data.usage?.input_tokens ?? 0,
+            outputTokens: data.usage?.output_tokens ?? 0,
+            model: this.model,
+            durationMs,
+        };
+    }
+    async generate(prompt, options) {
+        const result = await this.chat([{ role: 'user', content: prompt }], options);
+        return result.text;
+    }
+    async embed(_text) {
+        // Anthropic doesn't provide embeddings
+        return [];
+    }
+}
+//# sourceMappingURL=anthropic-provider.js.map

package/dist/llm/anthropic-provider.js.map

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

package/dist/llm/index.d.ts

@@ -1,2 +1,10 @@
 export { LLMService, runLLMServiceMigration } from './llm-service.js';
-export type { LLMServiceConfig, LLMResponse, LLMUsageStats, PromptTemplate, } from './llm-service.js';
+export type { LLMServiceConfig, LLMResponse, LLMUsageStats, PromptTemplate, ProviderInfo, } from './llm-service.js';
+export type { LLMProvider, LLMMessage, LLMCallOptions, LLMProviderResponse, RoutingTier, } from './provider.js';
+export { TaskRouter } from './provider.js';
+export { AnthropicProvider } from './anthropic-provider.js';
+export type { AnthropicProviderConfig } from './anthropic-provider.js';
+export { OllamaProvider } from './ollama-provider.js';
+export type { OllamaProviderConfig, OllamaStatus, OllamaModelInfo, OllamaRunningModel } from './ollama-provider.js';
+export { OllamaEmbeddingProvider } from './ollama-embedding.js';
+export type { OllamaEmbeddingConfig } from './ollama-embedding.js';

package/dist/llm/index.js

@@ -1,2 +1,6 @@
 export { LLMService, runLLMServiceMigration } from './llm-service.js';
+export { TaskRouter } from './provider.js';
+export { AnthropicProvider } from './anthropic-provider.js';
+export { OllamaProvider } from './ollama-provider.js';
+export { OllamaEmbeddingProvider } from './ollama-embedding.js';
 //# sourceMappingURL=index.js.map

package/dist/llm/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/llm/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,sBAAsB,EAAE,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/llm/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,sBAAsB,EAAE,MAAM,kBAAkB,CAAC;AAQtE,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAE3C,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAG5D,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAGtD,OAAO,EAAE,uBAAuB,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/llm/llm-service.d.ts

@@ -1,4 +1,6 @@
 import type Database from 'better-sqlite3';
+import type { LLMProvider } from './provider.js';
+import { TaskRouter } from './provider.js';
 export interface LLMServiceConfig {
     /** Anthropic API key. Falls back to ANTHROPIC_API_KEY env var. */
     apiKey?: string;
@@ -6,16 +8,18 @@ export interface LLMServiceConfig {
     model?: string;
     /** Max tokens per request. Default: 2048 */
     maxTokens?: number;
-    /** Max API calls per hour. Default: 30 */
+    /** Max API calls per hour (for paid providers). Default: 30 */
     maxCallsPerHour?: number;
-    /** Max tokens per hour budget. Default: 100_000 */
+    /** Max tokens per hour budget (for paid providers). Default: 100_000 */
     tokenBudgetPerHour?: number;
-    /** Max tokens per day budget. Default: 500_000 */
+    /** Max tokens per day budget (for paid providers). Default: 500_000 */
     tokenBudgetPerDay?: number;
     /** Cache TTL in ms. Default: 3_600_000 (1 hour) */
     cacheTtlMs?: number;
     /** Max cache entries. Default: 500 */
     maxCacheEntries?: number;
+    /** Prefer local providers for simple tasks. Default: true */
+    preferLocal?: boolean;
 }
 export interface LLMResponse {
     text: string;
@@ -25,6 +29,8 @@ export interface LLMResponse {
     cached: boolean;
     model: string;
     durationMs: number;
+    /** Which provider handled this request */
+    provider: string;
 }
 export interface LLMUsageStats {
     totalCalls: number;
@@ -42,12 +48,24 @@ export interface LLMUsageStats {
     errors: number;
     lastCallAt: number | null;
     model: string;
+    /** Active providers and their status */
+    providers: ProviderInfo[];
+}
+export interface ProviderInfo {
+    name: string;
+    available: boolean;
+    costTier: 'free' | 'cheap' | 'expensive';
+    capabilities: {
+        chat: boolean;
+        generate: boolean;
+        embed: boolean;
+        reasoning: boolean;
+    };
 }
 export type PromptTemplate = 'explain' | 'ask' | 'synthesize_debate' | 'creative_hypothesis' | 'research_question' | 'summarize' | 'analyze_contradiction' | 'custom';
 export declare function runLLMServiceMigration(db: Database.Database): void;
 export declare class LLMService {
     private db;
-    private readonly apiKey;
     private readonly model;
     private readonly maxTokens;
     private readonly maxCallsPerHour;
@@ -56,23 +74,49 @@ export declare class LLMService {
     private readonly cacheTtlMs;
     private readonly maxCacheEntries;
     private readonly log;
+    private readonly router;
+    private providers;
     private cache;
     private callHistory;
     private stats;
     private stmtInsertUsage;
     constructor(db: Database.Database, config?: LLMServiceConfig);
-    /** Check if LLM is available (API key set). */
+    /**
+     * Register an additional LLM provider.
+     *
+     * Example:
+     * ```typescript
+     * import { OllamaProvider } from '@timmeck/brain-core';
+     * llmService.registerProvider(new OllamaProvider());
+     * ```
+     */
+    registerProvider(provider: LLMProvider): void;
+    /** Remove a provider by name. */
+    removeProvider(name: string): void;
+    /** Get all registered providers. */
+    getProviders(): LLMProvider[];
+    /** Get the task router (for MCP tools / debugging). */
+    getRouter(): TaskRouter;
+    /** Check if any provider with chat capability is available. */
     isAvailable(): boolean;
     /**
-     * Main entry point: call Claude with a template + context.
-     * Returns null if budget exhausted or API key not set (caller should fallback to heuristic).
+     * Main entry point: call an LLM with a template + context.
+     * Returns null if budget exhausted or no provider available (caller should fallback to heuristic).
+     *
+     * The TaskRouter selects the best provider based on template complexity:
+     * - Simple tasks (summarize) → local provider first (free)
+     * - Complex tasks (debate, hypothesis) → cloud provider (quality)
+     * - Fallback chain: if preferred provider fails → try next
      */
     call(template: PromptTemplate, userMessage: string, options?: {
         maxTokens?: number;
         temperature?: number;
+        provider?: string;
     }): Promise<LLMResponse | null>;
     /** Get usage statistics. */
     getStats(): LLMUsageStats;
+    /** Get provider info with async availability checks. */
+    getProviderStatus(): Promise<ProviderInfo[]>;
     /** Get usage history from DB (for dashboard). */
     getUsageHistory(hours?: number): Array<{
         hour: string;
@@ -87,6 +131,10 @@ export declare class LLMService {
         tokens: number;
         avg_tokens: number;
     }>;
+    /** Gracefully shutdown all providers. */
+    shutdown(): Promise<void>;
+    /** Get sorted provider chain for a template, with availability pre-checked. */
+    private getProviderChain;
     private checkRateLimit;
     private checkTokenBudget;
     private getCacheKey;

package/dist/llm/llm-service.js

@@ -1,5 +1,7 @@
 import { createHash } from 'node:crypto';
 import { getLogger } from '../utils/logger.js';
+import { TaskRouter } from './provider.js';
+import { AnthropicProvider } from './anthropic-provider.js';
 // ── Migration ───────────────────────────────────────────
 export function runLLMServiceMigration(db) {
     db.exec(`
@@ -18,6 +20,13 @@ export function runLLMServiceMigration(db) {
     CREATE INDEX IF NOT EXISTS idx_llm_usage_created ON llm_usage(created_at);
     CREATE INDEX IF NOT EXISTS idx_llm_usage_template ON llm_usage(template);
   `);
+    // Add provider column if not exists (migration for existing DBs)
+    try {
+        db.exec(`ALTER TABLE llm_usage ADD COLUMN provider TEXT NOT NULL DEFAULT 'anthropic'`);
+    }
+    catch {
+        // Column already exists — ignore
+    }
 }
 // ── Prompt Templates ────────────────────────────────────
 const SYSTEM_PROMPTS = {
@@ -65,7 +74,6 @@ Follow the user's instructions precisely.`,
 // ── Service ─────────────────────────────────────────────
 export class LLMService {
     db;
-    apiKey;
     model;
     maxTokens;
     maxCallsPerHour;
@@ -74,6 +82,9 @@ export class LLMService {
     cacheTtlMs;
     maxCacheEntries;
     log = getLogger();
+    router;
+    // Providers
+    providers = [];
     // In-memory state
     cache = new Map();
     callHistory = [];
@@ -91,7 +102,6 @@ export class LLMService {
     stmtInsertUsage = null;
     constructor(db, config = {}) {
         this.db = db;
-        this.apiKey = config.apiKey ?? process.env.ANTHROPIC_API_KEY ?? null;
         this.model = config.model ?? 'claude-sonnet-4-20250514';
         this.maxTokens = config.maxTokens ?? 2048;
         this.maxCallsPerHour = config.maxCallsPerHour ?? 30;
@@ -99,34 +109,72 @@ export class LLMService {
         this.tokenBudgetPerDay = config.tokenBudgetPerDay ?? 500_000;
         this.cacheTtlMs = config.cacheTtlMs ?? 3_600_000;
         this.maxCacheEntries = config.maxCacheEntries ?? 500;
+        this.router = new TaskRouter(config.preferLocal ?? true);
         runLLMServiceMigration(db);
-        this.stmtInsertUsage = db.prepare('INSERT INTO llm_usage (prompt_hash, template, model, input_tokens, output_tokens, total_tokens, duration_ms, cached) VALUES (?, ?, ?, ?, ?, ?, ?, ?)');
-        this.log.debug(`[LLMService] Initialized (model=${this.model}, apiKey=${this.apiKey ? 'set' : 'NOT SET'}, budget=${this.tokenBudgetPerHour}/h)`);
+        this.stmtInsertUsage = db.prepare('INSERT INTO llm_usage (prompt_hash, template, model, input_tokens, output_tokens, total_tokens, duration_ms, cached, provider) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)');
+        // Auto-register Anthropic provider from config
+        const anthropicConfig = {
+            apiKey: config.apiKey,
+            model: config.model,
+            maxTokens: config.maxTokens,
+        };
+        const anthropic = new AnthropicProvider(anthropicConfig);
+        this.providers.push(anthropic);
+        this.log.debug(`[LLMService] Initialized (model=${this.model}, providers=[anthropic], preferLocal=${config.preferLocal ?? true})`);
+    }
+    /**
+     * Register an additional LLM provider.
+     *
+     * Example:
+     * ```typescript
+     * import { OllamaProvider } from '@timmeck/brain-core';
+     * llmService.registerProvider(new OllamaProvider());
+     * ```
+     */
+    registerProvider(provider) {
+        // Don't register duplicates
+        if (this.providers.some(p => p.name === provider.name)) {
+            this.log.debug(`[LLMService] Provider '${provider.name}' already registered, skipping`);
+            return;
+        }
+        this.providers.push(provider);
+        this.log.debug(`[LLMService] Registered provider: ${provider.name} (${provider.costTier})`);
+    }
+    /** Remove a provider by name. */
+    removeProvider(name) {
+        this.providers = this.providers.filter(p => p.name !== name);
+    }
+    /** Get all registered providers. */
+    getProviders() {
+        return [...this.providers];
     }
-    /** Check if LLM is available (API key set). */
+    /** Get the task router (for MCP tools / debugging). */
+    getRouter() {
+        return this.router;
+    }
+    /** Check if any provider with chat capability is available. */
     isAvailable() {
-        return this.apiKey !== null && this.apiKey.length > 0;
+        // Synchronous check: at least one provider could potentially be available
+        // For Anthropic: API key set. For Ollama: we assume yes (async check done at call time).
+        return this.providers.some(p => {
+            if (p.name === 'anthropic') {
+                // Quick sync check for anthropic
+                return p.capabilities.chat;
+            }
+            return p.capabilities.chat;
+        });
     }
     /**
-     * Main entry point: call Claude with a template + context.
-     * Returns null if budget exhausted or API key not set (caller should fallback to heuristic).
+     * Main entry point: call an LLM with a template + context.
+     * Returns null if budget exhausted or no provider available (caller should fallback to heuristic).
+     *
+     * The TaskRouter selects the best provider based on template complexity:
+     * - Simple tasks (summarize) → local provider first (free)
+     * - Complex tasks (debate, hypothesis) → cloud provider (quality)
+     * - Fallback chain: if preferred provider fails → try next
      */
     async call(template, userMessage, options) {
-        if (!this.isAvailable())
-            return null;
-        // Check rate limit
-        if (!this.checkRateLimit()) {
-            this.stats.rateLimitHits++;
-            this.log.debug('[LLMService] Rate limit reached, falling back to heuristic');
-            return null;
-        }
-        // Check token budget
-        if (!this.checkTokenBudget()) {
-            this.stats.rateLimitHits++;
-            this.log.debug('[LLMService] Token budget exhausted, falling back to heuristic');
-            return null;
-        }
-        // Check cache
+        // Check cache first (provider-agnostic)
         const cacheKey = this.getCacheKey(template, userMessage);
         const cached = this.getFromCache(cacheKey);
         if (cached) {
@@ -135,67 +183,71 @@ export class LLMService {
             return { ...cached, cached: true };
         }
         this.stats.cacheMisses++;
-        // Make API call
+        // Build provider chain (priority order)
+        const providerChain = await this.getProviderChain(template, options?.provider);
+        if (providerChain.length === 0) {
+            this.log.debug('[LLMService] No available providers');
+            return null;
+        }
+        // Check rate limit + budget (only for paid providers)
         const systemPrompt = SYSTEM_PROMPTS[template];
-        const start = Date.now();
-        try {
-            const response = await fetch('https://api.anthropic.com/v1/messages', {
-                method: 'POST',
-                headers: {
-                    'Content-Type': 'application/json',
-                    'x-api-key': this.apiKey,
-                    'anthropic-version': '2023-06-01',
-                },
-                body: JSON.stringify({
-                    model: this.model,
-                    max_tokens: options?.maxTokens ?? this.maxTokens,
-                    ...(options?.temperature !== undefined ? { temperature: options.temperature } : {}),
-                    system: systemPrompt,
-                    messages: [{ role: 'user', content: userMessage }],
-                }),
-            });
-            const durationMs = Date.now() - start;
-            if (!response.ok) {
-                const errText = await response.text();
+        const messages = [
+            { role: 'system', content: systemPrompt },
+            { role: 'user', content: userMessage },
+        ];
+        // Try each provider in order
+        for (const provider of providerChain) {
+            // Rate limit only applies to paid providers
+            if (provider.costTier !== 'free') {
+                if (!this.checkRateLimit()) {
+                    this.stats.rateLimitHits++;
+                    this.log.debug(`[LLMService] Rate limit reached for ${provider.name}, trying next`);
+                    continue;
+                }
+                if (!this.checkTokenBudget()) {
+                    this.stats.rateLimitHits++;
+                    this.log.debug(`[LLMService] Token budget exhausted for ${provider.name}, trying next`);
+                    continue;
+                }
+            }
+            try {
+                const providerResponse = await provider.chat(messages, {
+                    maxTokens: options?.maxTokens ?? this.maxTokens,
+                    temperature: options?.temperature,
+                });
+                const totalTokens = providerResponse.inputTokens + providerResponse.outputTokens;
+                const result = {
+                    text: providerResponse.text,
+                    tokensUsed: totalTokens,
+                    inputTokens: providerResponse.inputTokens,
+                    outputTokens: providerResponse.outputTokens,
+                    cached: false,
+                    model: providerResponse.model,
+                    durationMs: providerResponse.durationMs,
+                    provider: provider.name,
+                };
+                // Update stats
+                this.stats.totalCalls++;
+                this.stats.totalTokens += totalTokens;
+                this.stats.totalLatencyMs += providerResponse.durationMs;
+                this.stats.lastCallAt = Date.now();
+                this.callHistory.push({ timestamp: Date.now(), tokens: totalTokens, provider: provider.name });
+                // Cache the response
+                this.setCache(cacheKey, result);
+                // Record to DB
+                this.recordUsage(cacheKey, template, result, false);
+                this.log.debug(`[LLMService] ${template} via ${provider.name}: ${totalTokens} tokens, ${providerResponse.durationMs}ms`);
+                return result;
+            }
+            catch (err) {
                 this.stats.errors++;
-                this.log.warn(`[LLMService] API error (${response.status}): ${errText.substring(0, 200)}`);
-                return null;
+                this.log.warn(`[LLMService] Provider '${provider.name}' failed: ${err.message}, trying next`);
+                continue;
             }
-            const data = await response.json();
-            const text = data.content
-                ?.filter(c => c.type === 'text')
-                .map(c => c.text ?? '')
-                .join('\n') ?? '';
-            const inputTokens = data.usage?.input_tokens ?? 0;
-            const outputTokens = data.usage?.output_tokens ?? 0;
-            const totalTokens = inputTokens + outputTokens;
-            const result = {
-                text,
-                tokensUsed: totalTokens,
-                inputTokens,
-                outputTokens,
-                cached: false,
-                model: this.model,
-                durationMs,
-            };
-            // Update stats
-            this.stats.totalCalls++;
-            this.stats.totalTokens += totalTokens;
-            this.stats.totalLatencyMs += durationMs;
-            this.stats.lastCallAt = Date.now();
-            this.callHistory.push({ timestamp: Date.now(), tokens: totalTokens });
-            // Cache the response
-            this.setCache(cacheKey, result);
-            // Record to DB
-            this.recordUsage(cacheKey, template, result, false);
-            this.log.debug(`[LLMService] ${template}: ${totalTokens} tokens, ${durationMs}ms`);
-            return result;
-        }
-        catch (err) {
-            this.stats.errors++;
-            this.log.warn(`[LLMService] Call failed: ${err.message}`);
-            return null;
         }
+        // All providers failed
+        this.log.warn('[LLMService] All providers failed, returning null');
+        return null;
     }
     /** Get usage statistics. */
     getStats() {
@@ -206,6 +258,13 @@ export class LLMService {
         const callsThisHour = this.callHistory.filter(c => c.timestamp > oneHourAgo).length;
         const tokensThisHour = this.callHistory.filter(c => c.timestamp > oneHourAgo).reduce((s, c) => s + c.tokens, 0);
         const tokensToday = this.callHistory.filter(c => c.timestamp > oneDayAgo).reduce((s, c) => s + c.tokens, 0);
+        // Build provider info (sync — use cached availability)
+        const providers = this.providers.map(p => ({
+            name: p.name,
+            available: p.name === 'anthropic' ? (p.capabilities.chat) : true, // best effort sync
+            costTier: p.costTier,
+            capabilities: { ...p.capabilities },
+        }));
         return {
             totalCalls: this.stats.totalCalls,
             totalTokens: this.stats.totalTokens,
@@ -224,8 +283,18 @@ export class LLMService {
             errors: this.stats.errors,
             lastCallAt: this.stats.lastCallAt,
             model: this.model,
+            providers,
         };
     }
+    /** Get provider info with async availability checks. */
+    async getProviderStatus() {
+        return Promise.all(this.providers.map(async (p) => ({
+            name: p.name,
+            available: await p.isAvailable(),
+            costTier: p.costTier,
+            capabilities: { ...p.capabilities },
+        })));
+    }
     /** Get usage history from DB (for dashboard). */
     getUsageHistory(hours = 24) {
         try {
@@ -262,10 +331,43 @@ export class LLMService {
             return [];
         }
     }
+    /** Gracefully shutdown all providers. */
+    async shutdown() {
+        for (const provider of this.providers) {
+            if (provider.shutdown) {
+                try {
+                    await provider.shutdown();
+                }
+                catch {
+                    // Best effort
+                }
+            }
+        }
+    }
     // ── Private Helpers ────────────────────────────────────
+    /** Get sorted provider chain for a template, with availability pre-checked. */
+    async getProviderChain(template, forcedProvider) {
+        if (forcedProvider) {
+            const p = this.providers.find(p => p.name === forcedProvider);
+            if (p && await p.isAvailable())
+                return [p];
+            return [];
+        }
+        // Get routing preference
+        const sorted = this.router.route(template, this.providers);
+        // Filter to available providers
+        const available = [];
+        for (const p of sorted) {
+            if (await p.isAvailable()) {
+                available.push(p);
+            }
+        }
+        return available;
+    }
     checkRateLimit() {
         const oneHourAgo = Date.now() - 3_600_000;
         this.pruneCallHistory();
+        // Only count paid provider calls for rate limiting
         const recentCalls = this.callHistory.filter(c => c.timestamp > oneHourAgo).length;
         return recentCalls < this.maxCallsPerHour;
     }
@@ -282,7 +384,7 @@ export class LLMService {
         return true;
     }
     getCacheKey(template, userMessage) {
-        const input = `${template}:${this.model}:${userMessage}`;
+        const input = `${template}:${userMessage}`;
         return createHash('sha256').update(input).digest('hex');
     }
     getFromCache(key) {
@@ -313,7 +415,7 @@ export class LLMService {
     }
     recordUsage(hash, template, response, cached) {
         try {
-            this.stmtInsertUsage?.run(hash, template, response.model, response.inputTokens, response.outputTokens, response.tokensUsed, response.durationMs, cached ? 1 : 0);
+            this.stmtInsertUsage?.run(hash, template, response.model, response.inputTokens, response.outputTokens, response.tokensUsed, response.durationMs, cached ? 1 : 0, response.provider ?? 'anthropic');
         }
         catch {
             // Best effort — don't crash on DB error