@stackbilt/llm-providers 1.0.0

package/dist/utils/cost-tracker.js

@@ -0,0 +1,272 @@
+/**
+ * Cost Tracker
+ * Tracks and optimizes LLM usage costs across providers
+ */
+export class CostTracker {
+    providers = new Map();
+    config;
+    ledger;
+    constructor(config = {}, ledger) {
+        this.config = {
+            inputTokenCost: config.inputTokenCost ?? 0.001, // $0.001 per 1k tokens default
+            outputTokenCost: config.outputTokenCost ?? 0.002, // $0.002 per 1k tokens default
+            maxMonthlyCost: config.maxMonthlyCost,
+            alertThreshold: config.alertThreshold ?? 0.8 // 80% of max cost
+        };
+        this.ledger = ledger;
+    }
+    /**
+     * Calculate cost for a request
+     */
+    calculateRequestCost(request, capabilities) {
+        const estimatedInputTokens = this.estimateInputTokens(request);
+        const estimatedOutputTokens = request.maxTokens || 1000;
+        const inputCost = (estimatedInputTokens / 1000) * capabilities.inputTokenCost;
+        const outputCost = (estimatedOutputTokens / 1000) * capabilities.outputTokenCost;
+        return inputCost + outputCost;
+    }
+    /**
+     * Track actual cost from response
+     */
+    trackCost(provider, response) {
+        if (!response.usage)
+            return;
+        // Delegate to CreditLedger when present
+        if (this.ledger) {
+            this.ledger.record(provider, response.model || 'unknown', response.usage.cost || 0, response.usage.inputTokens, response.usage.outputTokens);
+        }
+        const entry = this.providers.get(provider) || this.createProviderEntry();
+        entry.totalCost += response.usage.cost || 0;
+        entry.requestCount++;
+        entry.inputTokens += response.usage.inputTokens;
+        entry.outputTokens += response.usage.outputTokens;
+        entry.lastRecordedAt = Date.now();
+        this.providers.set(provider, entry);
+        // Check cost alerts
+        this.checkCostAlerts(provider);
+    }
+    /**
+     * Get the attached CreditLedger (if any)
+     */
+    getLedger() {
+        return this.ledger;
+    }
+    /**
+     * Get total cost across all providers
+     */
+    getTotalCost() {
+        return this.total();
+    }
+    /**
+     * Get cost for specific provider
+     */
+    getProviderCost(provider) {
+        return this.providers.get(provider)?.totalCost || 0;
+    }
+    /**
+     * Get cost breakdown by provider
+     */
+    getCostBreakdown() {
+        const breakdown = {};
+        for (const [provider, entry] of this.providers) {
+            breakdown[provider] = {
+                ...entry,
+                cost: entry.totalCost,
+                requests: entry.requestCount,
+                tokens: {
+                    input: entry.inputTokens,
+                    output: entry.outputTokens
+                },
+                averageCostPerRequest: entry.requestCount > 0 ? entry.totalCost / entry.requestCount : 0
+            };
+        }
+        return breakdown;
+    }
+    /**
+     * Get a provider snapshot aligned with Workers usage reporting.
+     */
+    breakdown() {
+        const snapshot = {};
+        for (const [provider, entry] of this.providers) {
+            snapshot[provider] = { ...entry };
+        }
+        return snapshot;
+    }
+    /**
+     * Get total cost across all providers.
+     */
+    total() {
+        let sum = 0;
+        for (const entry of this.providers.values()) {
+            sum += entry.totalCost;
+        }
+        return sum;
+    }
+    /**
+     * Get most cost-effective provider for a request
+     */
+    getMostCostEffectiveProvider(providers, request) {
+        let minCost = Infinity;
+        let bestProvider = '';
+        for (const [provider, capabilities] of Object.entries(providers)) {
+            const cost = this.calculateRequestCost(request, capabilities);
+            if (cost < minCost) {
+                minCost = cost;
+                bestProvider = provider;
+            }
+        }
+        return bestProvider;
+    }
+    /**
+     * Check if we're approaching cost limits
+     */
+    shouldRouteBasedOnCost(provider) {
+        if (!this.config.maxMonthlyCost)
+            return false;
+        const currentCost = this.getProviderCost(provider);
+        const threshold = this.config.maxMonthlyCost * (this.config.alertThreshold || 0.8);
+        return currentCost >= threshold;
+    }
+    /**
+     * Reset cost tracking (e.g., monthly reset)
+     */
+    reset() {
+        this.providers.clear();
+    }
+    /**
+     * Reset tracking for specific provider
+     */
+    resetProvider(provider) {
+        this.providers.delete(provider);
+    }
+    /**
+     * Drain and reset provider tracking for periodic reporting.
+     */
+    drain() {
+        const snapshot = this.breakdown();
+        this.providers.clear();
+        return snapshot;
+    }
+    /**
+     * Export cost data for analytics
+     */
+    exportData() {
+        return {
+            totalCost: this.getTotalCost(),
+            breakdown: this.getCostBreakdown(),
+            period: {
+                start: Date.now() - 30 * 24 * 60 * 60 * 1000, // 30 days ago
+                end: Date.now()
+            }
+        };
+    }
+    /**
+     * Estimate input tokens from request
+     */
+    estimateInputTokens(request) {
+        // Rough estimation: 1 token ≈ 0.75 words ≈ 4 characters
+        let totalChars = 0;
+        // Count characters in messages
+        for (const message of request.messages) {
+            totalChars += message.content.length;
+        }
+        // Add system prompt if present
+        if (request.systemPrompt) {
+            totalChars += request.systemPrompt.length;
+        }
+        // Convert to tokens (rough approximation)
+        return Math.ceil(totalChars / 4);
+    }
+    /**
+     * Check for cost alerts
+     */
+    checkCostAlerts(provider) {
+        if (!this.config.maxMonthlyCost || !this.config.alertThreshold)
+            return;
+        const currentCost = this.getProviderCost(provider);
+        const alertThreshold = this.config.maxMonthlyCost * this.config.alertThreshold;
+        if (currentCost >= alertThreshold) {
+            console.warn(`[CostTracker] Cost alert for ${provider}: $${currentCost.toFixed(4)} (${((currentCost / this.config.maxMonthlyCost) * 100).toFixed(1)}% of limit)`);
+        }
+    }
+    /**
+     * Update cost configuration
+     */
+    updateConfig(config) {
+        this.config = { ...this.config, ...config };
+    }
+    /**
+     * Get current configuration
+     */
+    getConfig() {
+        return { ...this.config };
+    }
+    createProviderEntry() {
+        return {
+            totalCost: 0,
+            requestCount: 0,
+            inputTokens: 0,
+            outputTokens: 0,
+            lastRecordedAt: 0
+        };
+    }
+}
+/**
+ * Default cost tracker instance
+ */
+export const defaultCostTracker = new CostTracker();
+/**
+ * Cost optimization utilities
+ */
+export class CostOptimizer {
+    /**
+     * Choose optimal provider based on cost and performance
+     */
+    static chooseOptimalProvider(providers, request, costTracker, performanceWeights = { cost: 0.5, latency: 0.3, quality: 0.2 }) {
+        let bestScore = -Infinity;
+        let bestProvider = '';
+        for (const [provider, capabilities] of Object.entries(providers)) {
+            const cost = costTracker.calculateRequestCost(request, capabilities);
+            // Normalize cost (lower is better)
+            const costScore = 1 / (1 + cost * 1000); // Scale cost for scoring
+            // Simple quality score based on model capabilities
+            const qualityScore = capabilities.maxContextLength / 100000; // Normalize context length
+            // Assume latency score (would be tracked from actual usage)
+            const latencyScore = 0.5; // Placeholder
+            const totalScore = costScore * performanceWeights.cost +
+                latencyScore * performanceWeights.latency +
+                qualityScore * performanceWeights.quality;
+            if (totalScore > bestScore) {
+                bestScore = totalScore;
+                bestProvider = provider;
+            }
+        }
+        return bestProvider;
+    }
+    /**
+     * Suggest cost reduction strategies
+     */
+    static suggestOptimizations(costBreakdown) {
+        const suggestions = [];
+        const totalCost = Object.values(costBreakdown).reduce((sum, p) => sum + p.cost, 0);
+        // Find most expensive provider
+        const mostExpensive = Object.entries(costBreakdown)
+            .sort(([, a], [, b]) => b.cost - a.cost)[0];
+        if (mostExpensive && mostExpensive[1].cost > totalCost * 0.5) {
+            suggestions.push(`Consider reducing usage of ${mostExpensive[0]} (${((mostExpensive[1].cost / totalCost) * 100).toFixed(1)}% of total cost)`);
+        }
+        // Check for high per-request costs
+        for (const [provider, data] of Object.entries(costBreakdown)) {
+            if (data.averageCostPerRequest > 0.01) { // $0.01 per request
+                suggestions.push(`${provider} has high per-request cost ($${(data.averageCostPerRequest).toFixed(4)}). Consider using smaller models or reducing max_tokens.`);
+            }
+        }
+        // Suggest batch processing if many small requests
+        const totalRequests = Object.values(costBreakdown).reduce((sum, p) => sum + p.requests, 0);
+        if (totalRequests > 1000 && totalCost / totalRequests < 0.001) {
+            suggestions.push('Consider batch processing for small requests to reduce overhead costs.');
+        }
+        return suggestions;
+    }
+}
+//# sourceMappingURL=cost-tracker.js.map

package/dist/utils/cost-tracker.js.map

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

package/dist/utils/credit-ledger.d.ts

@@ -0,0 +1,161 @@
+/**
+ * Credit Ledger — single source of truth for LLM spend across the ecosystem.
+ *
+ * Tracks per-provider, per-model spend with budgets, rate limits, and
+ * threshold events. Persistence-agnostic: holds state in memory, serializes
+ * via snapshot()/restore() for any storage backend (D1, KV, R2, etc.).
+ */
+export type ThresholdTier = 'warning' | 'critical' | 'emergency';
+export type DepletionTier = 'depletion_warning' | 'depletion_critical' | 'depletion_emergency';
+/** Timestamped spend entry for burn rate calculation. */
+export interface SpendEntry {
+    timestamp: number;
+    provider: string;
+    cost: number;
+}
+/** Burn rate over a rolling window. */
+export interface BurnRate {
+    costPerHour: number;
+    costPerDay: number;
+    windowMs: number;
+    sampleCount: number;
+}
+/** Projected depletion estimate for a provider. */
+export interface DepletionEstimate {
+    remainingBudget: number;
+    burnRate: BurnRate;
+    projectedDepletionDate: Date | null;
+    daysRemaining: number | null;
+}
+/** Windowed spend summary for a provider. */
+export interface SpendSummary {
+    provider: string;
+    spend: number;
+    requestCount: number;
+    inputTokens: number;
+    outputTokens: number;
+    windowMs: number;
+}
+export interface RateLimitWindow {
+    used: number;
+    limit: number;
+    windowStart: number;
+}
+export type RateLimitDimension = 'rpm' | 'rpd' | 'tpm' | 'tpd';
+export interface ModelAccumulator {
+    spend: number;
+    inputTokens: number;
+    outputTokens: number;
+    requestCount: number;
+    lastRecordedAt: number;
+}
+export interface ProviderAccumulator extends ModelAccumulator {
+    models: Record<string, ModelAccumulator>;
+    budget: number | null;
+    rateLimits: Partial<Record<RateLimitDimension, RateLimitWindow>>;
+}
+export interface BudgetConfig {
+    provider: string;
+    model?: string;
+    monthlyBudget?: number;
+    rateLimits?: Partial<Record<RateLimitDimension, number>>;
+}
+export interface ThresholdConfig {
+    warning: number;
+    critical: number;
+    emergency: number;
+}
+export interface ThresholdEvent {
+    type: 'threshold_crossed';
+    provider: string;
+    model?: string;
+    tier: ThresholdTier;
+    spend: number;
+    budget: number;
+    utilizationPct: number;
+}
+export interface DepletionEvent {
+    type: 'depletion_projected';
+    provider: string;
+    tier: DepletionTier;
+    daysRemaining: number;
+    projectedDepletionDate: Date;
+    burnRate: BurnRate;
+}
+export type LedgerEvent = ThresholdEvent | DepletionEvent;
+export type LedgerListener = (event: LedgerEvent) => void;
+export interface RateLimitCheck {
+    allowed: boolean;
+    used: number;
+    limit: number;
+}
+export interface CreditLedgerSnapshot {
+    version: 1;
+    periodStart: number;
+    providers: Record<string, {
+        spend: number;
+        inputTokens: number;
+        outputTokens: number;
+        requestCount: number;
+        lastRecordedAt: number;
+        budget: number | null;
+        models: Record<string, ModelAccumulator>;
+        rateLimits: Partial<Record<RateLimitDimension, RateLimitWindow>>;
+    }>;
+    thresholds: ThresholdConfig;
+    budgets: BudgetConfig[];
+    exportedAt: number;
+    /** Timestamped spend entries for burn rate calculation. Optional for backward compat. */
+    spendHistory?: SpendEntry[];
+}
+export declare class CreditLedger {
+    private providers;
+    private thresholds;
+    private budgets;
+    private listeners;
+    private periodStart;
+    private lastFiredTier;
+    private lastFiredDepletionTier;
+    private spendHistory;
+    private ringBufferSize;
+    constructor(config?: {
+        thresholds?: Partial<ThresholdConfig>;
+        budgets?: BudgetConfig[];
+        ringBufferSize?: number;
+    });
+    record(provider: string, model: string, cost: number, inputTokens: number, outputTokens: number): void;
+    setBudget(config: BudgetConfig): void;
+    removeBudget(provider: string, model?: string): void;
+    remainingBalance(provider: string, model?: string): number | null;
+    utilizationPct(provider: string, model?: string): number;
+    getProviderAccumulator(provider: string): ProviderAccumulator | undefined;
+    getModelAccumulator(provider: string, model: string): ModelAccumulator | undefined;
+    totalSpend(): number;
+    breakdown(): Record<string, ProviderAccumulator>;
+    /**
+     * Calculate burn rate for a provider over a rolling window.
+     * Default window: 24 hours.
+     */
+    getBurnRate(provider: string, windowMs?: number): BurnRate;
+    /**
+     * Project when a provider's budget will be depleted at the current burn rate.
+     * Returns null if the provider has no budget or no spend history.
+     */
+    getDepletionEstimate(provider: string, windowMs?: number): DepletionEstimate | null;
+    /**
+     * Get windowed spend summary for a provider.
+     */
+    getSpendSummary(provider: string, windowMs: number): SpendSummary;
+    /**
+     * Get spend breakdown for all providers over a window.
+     */
+    getSpendBreakdown(windowMs: number): SpendSummary[];
+    checkRateLimit(provider: string, dimension: RateLimitDimension): RateLimitCheck;
+    snapshot(): CreditLedgerSnapshot;
+    restore(snapshot: CreditLedgerSnapshot): void;
+    resetPeriod(): void;
+    on(listener: LedgerListener): () => void;
+    private getOrCreateProvider;
+    private emit;
+}
+//# sourceMappingURL=credit-ledger.d.ts.map

package/dist/utils/credit-ledger.d.ts.map

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