adaptive-memory-multi-model-router 2.2.5 → 2.2.7

package/dist/cache/cacheKeyGenerator.d.ts

@@ -0,0 +1,67 @@
+/**
+ * A3M Router - Cross-Provider Cache Key Generator
+ *
+ * Normalizes prompts so same semantic content maps to same cache key
+ * regardless of provider-specific formatting, system prompts, etc.
+ *
+ * Usage:
+ *   const cacheKey = generateCacheKey("What is Python?", { provider: "openai" });
+ *   const key2 = generateCacheKey("What is Python?", { provider: "anthropic" });
+ *   // key === key2 (same semantic content = same key)
+ */
+export interface CacheKeyOptions {
+    /** Target provider (affects normalization rules) */
+    provider?: string;
+    /** Target model (for model-specific normalization) */
+    model?: string;
+    /** Whether to include system prompt in normalization */
+    includeSystemPrompt?: boolean;
+    /** Custom normalization rules */
+    customRules?: NormalizationRule[];
+}
+export interface NormalizationRule {
+    pattern: RegExp;
+    replacement: string;
+}
+export interface CacheKeyResult {
+    /** The normalized cache key string */
+    key: string;
+    /** Hash of the normalized content */
+    hash: string;
+    /** Metadata about what was normalized */
+    metadata: {
+        originalLength: number;
+        normalizedLength: number;
+        rulesApplied: number;
+        provider?: string;
+    };
+}
+/**
+ * Normalize text for cross-provider cache key generation.
+ * Removes provider-specific formatting while preserving semantic content.
+ */
+export declare function normalizeForCacheKey(text: string, options?: CacheKeyOptions): string;
+/**
+ * Generate a deterministic cache key from a query.
+ * Same semantic content = same key across providers.
+ */
+export declare function generateCacheKey(query: string, options?: CacheKeyOptions): CacheKeyResult;
+/**
+ * Add cross-provider cache key methods to existing SemanticCache.
+ * Call this to enhance the cache with provider-normalized lookups.
+ */
+export declare function createCacheKeyGenerator(defaultOptions?: CacheKeyOptions): {
+    generateKey: (query: string, options?: CacheKeyOptions) => CacheKeyResult;
+    createNormalizedMatcher: (cache: Map<string, any>) => (query: string, options?: CacheKeyOptions) => string | null;
+};
+/**
+ * Quick cache key generation (simplified API).
+ * Use this for simple cross-provider cache lookups.
+ *
+ * @example
+ * const key1 = toCacheKey("What is Python?", "openai");
+ * const key2 = toCacheKey("What is Python?", "anthropic");
+ * console.log(key1 === key2); // true
+ */
+export declare function toCacheKey(query: string, provider?: string): string;
+//# sourceMappingURL=cacheKeyGenerator.d.ts.map

package/dist/cache/cacheKeyGenerator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cacheKeyGenerator.d.ts","sourceRoot":"","sources":["../../src/cache/cacheKeyGenerator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAQH,MAAM,WAAW,eAAe;IAC9B,oDAAoD;IACpD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,sDAAsD;IACtD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,wDAAwD;IACxD,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B,iCAAiC;IACjC,WAAW,CAAC,EAAE,iBAAiB,EAAE,CAAC;CACnC;AAED,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,cAAc;IAC7B,sCAAsC;IACtC,GAAG,EAAE,MAAM,CAAC;IACZ,qCAAqC;IACrC,IAAI,EAAE,MAAM,CAAC;IACb,yCAAyC;IACzC,QAAQ,EAAE;QACR,cAAc,EAAE,MAAM,CAAC;QACvB,gBAAgB,EAAE,MAAM,CAAC;QACzB,YAAY,EAAE,MAAM,CAAC;QACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;KACnB,CAAC;CACH;AA2BD;;;GAGG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,eAAoB,GAC5B,MAAM,CA8CR;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,eAAoB,GAC5B,cAAc,CAwChB;AAMD;;;GAGG;AACH,wBAAgB,uBAAuB,CACrC,cAAc,CAAC,EAAE,eAAe,GAC/B;IACD,WAAW,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,eAAe,KAAK,cAAc,CAAC;IAC1E,uBAAuB,EAAE,CAAC,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,eAAe,KAAK,MAAM,GAAG,IAAI,CAAC;CACnH,CAkCA;AAMD;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAEnE"}

package/dist/cache/cacheKeyGenerator.js

@@ -0,0 +1,211 @@
+"use strict";
+/**
+ * A3M Router - Cross-Provider Cache Key Generator
+ *
+ * Normalizes prompts so same semantic content maps to same cache key
+ * regardless of provider-specific formatting, system prompts, etc.
+ *
+ * Usage:
+ *   const cacheKey = generateCacheKey("What is Python?", { provider: "openai" });
+ *   const key2 = generateCacheKey("What is Python?", { provider: "anthropic" });
+ *   // key === key2 (same semantic content = same key)
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeForCacheKey = normalizeForCacheKey;
+exports.generateCacheKey = generateCacheKey;
+exports.createCacheKeyGenerator = createCacheKeyGenerator;
+exports.toCacheKey = toCacheKey;
+const crypto = __importStar(require("crypto"));
+// ============================================================
+// Provider-specific system prompt patterns
+// ============================================================
+const PROVIDER_SYSTEM_PATTERNS = {
+    anthropic: [
+        /<anthropic_thinking>[\s\S]*?<\/anthropic_thinking>/gi,
+        /<thinking>[\s\S]*?<\/thinking>/gi,
+        /Human:/gi,
+        /Assistant:/gi,
+    ],
+    openai: [
+        /<|im_start|>/gi,
+        /<|im_end|>/gi,
+    ],
+    google: [
+        /<content>[\s\S]*?<\/content>/gi,
+        /[\Parts|thought]/gi,
+    ],
+};
+// ============================================================
+// Core normalizer
+// ============================================================
+/**
+ * Normalize text for cross-provider cache key generation.
+ * Removes provider-specific formatting while preserving semantic content.
+ */
+function normalizeForCacheKey(text, options = {}) {
+    let normalized = text;
+    // Step 1: Unicode normalization (NFC)
+    normalized = normalized.normalize('NFC');
+    // Step 2: Collapse whitespace
+    normalized = normalized.replace(/\s+/g, ' ');
+    // Step 3: Remove control characters
+    normalized = normalized.replace(/[\x00-\x1F\x7F]/g, '');
+    // Step 4: Strip provider-specific formatting
+    if (options.provider) {
+        const patterns = PROVIDER_SYSTEM_PATTERNS[options.provider] || [];
+        for (const pattern of patterns) {
+            normalized = normalized.replace(pattern, '');
+        }
+    }
+    // Step 5: General system/assistant role removal
+    normalized = normalized
+        .replace(/\b(system|user|assistant|human|bot)\s*:/gi, '')
+        .replace(/^(system|user|assistant|human|bot)\s*/gim, '');
+    // Step 6: Remove markdown formatting (often provider-specific)
+    normalized = normalized
+        .replace(/```[\s\S]*?```/g, '[CODE_BLOCK]') // Preserve code block indicator
+        .replace(/`([^`]+)`/g, '$1') // Inline code content
+        .replace(/\*\*([^*]+)\*\*/g, '$1') // Bold
+        .replace(/_([^_]+)_/g, '$1') // Italic
+        .replace(/#+\s*/g, '') // Headers
+        .replace(/^\s*[-*+]\s+/gm, '') // List bullets
+        .replace(/^\s*\d+\.\s+/gm, ''); // Numbered lists
+    // Step 7: Apply custom rules
+    if (options.customRules) {
+        for (const rule of options.customRules) {
+            normalized = normalized.replace(rule.pattern, rule.replacement);
+        }
+    }
+    // Step 8: Collapse whitespace again after removals
+    normalized = normalized.replace(/\s+/g, ' ').trim();
+    return normalized;
+}
+/**
+ * Generate a deterministic cache key from a query.
+ * Same semantic content = same key across providers.
+ */
+function generateCacheKey(query, options = {}) {
+    const originalLength = query.length;
+    // Normalize the query
+    let normalized = normalizeForCacheKey(query, {
+        ...options,
+        includeSystemPrompt: false, // Always exclude for user query matching
+    });
+    // Count rules that were applied (approximate)
+    let rulesApplied = 3; // Base normalizations
+    if (options.provider)
+        rulesApplied += 2;
+    if (options.customRules)
+        rulesApplied += options.customRules.length;
+    // Generate hash
+    const hash = crypto
+        .createHash('sha256')
+        .update(normalized)
+        .digest('hex')
+        .substring(0, 16); // First 16 chars = 64-bit key
+    // Final key format: v1:{hash}:{provider?[:model]?}
+    let key = `v1:${hash}`;
+    if (options.provider) {
+        key += `:${options.provider}`;
+        if (options.model) {
+            key += `:${options.model}`;
+        }
+    }
+    return {
+        key,
+        hash,
+        metadata: {
+            originalLength,
+            normalizedLength: normalized.length,
+            rulesApplied,
+            provider: options.provider,
+        },
+    };
+}
+// ============================================================
+// SemanticCache enhancement
+// ============================================================
+/**
+ * Add cross-provider cache key methods to existing SemanticCache.
+ * Call this to enhance the cache with provider-normalized lookups.
+ */
+function createCacheKeyGenerator(defaultOptions) {
+    return {
+        /**
+         * Generate a cache key for a query.
+         */
+        generateKey: (query, options) => {
+            return generateCacheKey(query, { ...defaultOptions, ...options });
+        },
+        /**
+         * Create a matcher function that finds existing cache entries
+         * by comparing normalized keys.
+         */
+        createNormalizedMatcher: (cache) => {
+            return (query, options) => {
+                const { key } = generateCacheKey(query, { ...defaultOptions, ...options });
+                // Check exact match
+                if (cache.has(key)) {
+                    return key;
+                }
+                // Check hash-only match (v1:{hash} prefix)
+                const hashPrefix = key.split(':').slice(0, 2).join(':');
+                for (const cachedKey of cache.keys()) {
+                    if (cachedKey.startsWith(hashPrefix + ':')) {
+                        return cachedKey;
+                    }
+                }
+                return null;
+            };
+        },
+    };
+}
+// ============================================================
+// Convenience exports
+// ============================================================
+/**
+ * Quick cache key generation (simplified API).
+ * Use this for simple cross-provider cache lookups.
+ *
+ * @example
+ * const key1 = toCacheKey("What is Python?", "openai");
+ * const key2 = toCacheKey("What is Python?", "anthropic");
+ * console.log(key1 === key2); // true
+ */
+function toCacheKey(query, provider) {
+    return generateCacheKey(query, { provider }).key;
+}
+//# sourceMappingURL=cacheKeyGenerator.js.map

package/dist/cache/cacheKeyGenerator.js.map

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

package/dist/cost/preCallCostEstimator.d.ts

@@ -0,0 +1,114 @@
+/**
+ * A3M Router - Pre-Call Cost Estimator
+ *
+ * Estimates cost BEFORE making an API call based on input features.
+ * Uses historical data patterns and token count estimation via character ratio.
+ *
+ * No external API calls - all estimation is local.
+ *
+ * Usage:
+ *   const estimator = new PreCallCostEstimator();
+ *   const estimate = estimator.estimate({
+ *     query: "What is Python?",
+ *     modelTier: 'mid',
+ *     provider: 'groq'
+ *   });
+ *   console.log(estimate); // { estimatedTokens: 24, estimatedCost: 0.0014, estimatedLatency: 200 }
+ */
+import { ProviderTier } from '../providers/providerConfig';
+export interface CostEstimateInput {
+    /** Query text to estimate tokens for */
+    query: string;
+    /** Model tier (free|cheap|mid|premium|enterprise) */
+    modelTier?: ProviderTier;
+    /** Provider ID for provider-specific cost lookup */
+    provider?: string;
+    /** Optional: explicit token count (if already known) */
+    explicitTokens?: number;
+    /** System prompt length (if using a system prompt) */
+    systemPromptLength?: number;
+}
+export interface CostEstimate {
+    /** Estimated total tokens (input + output) */
+    estimatedTokens: number;
+    /** Estimated input tokens */
+    estimatedInputTokens: number;
+    /** Estimated output tokens */
+    estimatedOutputTokens: number;
+    /** Estimated cost in USD */
+    estimatedCost: number;
+    /** Estimated latency in milliseconds */
+    estimatedLatency: number;
+    /** Confidence score 0-1 */
+    confidence: number;
+    /** Breakdown of estimation */
+    breakdown: {
+        inputCostPerM: number;
+        outputCostPerM: number;
+        charToTokenRatio: number;
+    };
+}
+export interface ProviderCostConfig {
+    input: number;
+    output: number;
+}
+export declare class PreCallCostEstimator {
+    private historicalData;
+    private slope;
+    private intercept;
+    private latencyHistory;
+    private ewmaAlpha;
+    constructor(historicalData?: Array<{
+        chars: number;
+        tokens: number;
+    }>);
+    /**
+     * Main estimation method - estimates tokens, cost, and latency.
+     */
+    estimate(input: CostEstimateInput): CostEstimate;
+    /**
+     * Estimate input tokens using character-to-token ratio.
+     * Uses linear regression if historical data is available.
+     */
+    estimateTokens(text: string, systemPromptLength?: number): number;
+    /**
+     * Estimate output tokens based on query complexity.
+     * More complex queries (code, analysis) tend to need more output.
+     */
+    estimateOutputTokens(query: string, inputTokens: number): number;
+    /**
+     * Calculate cost in USD.
+     */
+    calculateCost(totalTokens: number, config: ProviderCostConfig): number;
+    /**
+     * Estimate latency in milliseconds.
+     */
+    estimateLatency(tier: ProviderTier, inputTokens: number, totalTokens: number): number;
+    /**
+     * Record actual tokens for future regression improvements.
+     */
+    recordActualTokens(queryLength: number, actualTokens: number): void;
+    /**
+     * Record actual latency for EWMA updates.
+     */
+    recordActualLatency(latencyMs: number): void;
+    /**
+     * Fit linear regression to historical data.
+     * Uses ordinary least squares.
+     */
+    fitLinearRegression(data: Array<{
+        chars: number;
+        tokens: number;
+    }>): void;
+    private getCostConfig;
+    private containsKeyword;
+    private calculateEwma;
+    private calculateConfidence;
+    private estimateInputTokensFromTotal;
+    private estimateOutputTokensFromTotal;
+}
+export declare function createPreCallCostEstimator(historicalData?: Array<{
+    chars: number;
+    tokens: number;
+}>): PreCallCostEstimator;
+//# sourceMappingURL=preCallCostEstimator.d.ts.map

package/dist/cost/preCallCostEstimator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"preCallCostEstimator.d.ts","sourceRoot":"","sources":["../../src/cost/preCallCostEstimator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAM3D,MAAM,WAAW,iBAAiB;IAChC,wCAAwC;IACxC,KAAK,EAAE,MAAM,CAAC;IACd,qDAAqD;IACrD,SAAS,CAAC,EAAE,YAAY,CAAC;IACzB,oDAAoD;IACpD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,wDAAwD;IACxD,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,sDAAsD;IACtD,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,YAAY;IAC3B,8CAA8C;IAC9C,eAAe,EAAE,MAAM,CAAC;IACxB,6BAA6B;IAC7B,oBAAoB,EAAE,MAAM,CAAC;IAC7B,8BAA8B;IAC9B,qBAAqB,EAAE,MAAM,CAAC;IAC9B,4BAA4B;IAC5B,aAAa,EAAE,MAAM,CAAC;IACtB,wCAAwC;IACxC,gBAAgB,EAAE,MAAM,CAAC;IACzB,2BAA2B;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,8BAA8B;IAC9B,SAAS,EAAE;QACT,aAAa,EAAE,MAAM,CAAC;QACtB,cAAc,EAAE,MAAM,CAAC;QACvB,gBAAgB,EAAE,MAAM,CAAC;KAC1B,CAAC;CACH;AAED,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAeD,qBAAa,oBAAoB;IAE/B,OAAO,CAAC,cAAc,CAAgD;IAEtE,OAAO,CAAC,KAAK,CAAQ;IACrB,OAAO,CAAC,SAAS,CAAM;IAEvB,OAAO,CAAC,cAAc,CAAgB;IACtC,OAAO,CAAC,SAAS,CAAO;gBAEZ,cAAc,CAAC,EAAE,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IAMrE;;OAEG;IACH,QAAQ,CAAC,KAAK,EAAE,iBAAiB,GAAG,YAAY;IA+ChD;;;OAGG;IACH,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,kBAAkB,SAAI,GAAG,MAAM;IAY5D;;;OAGG;IACH,oBAAoB,CAAC,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM;IAwBhE;;OAEG;IACH,aAAa,CAAC,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,kBAAkB,GAAG,MAAM;IAMtE;;OAEG;IACH,eAAe,CAAC,IAAI,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM;IAmBrF;;OAEG;IACH,kBAAkB,CAAC,WAAW,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,IAAI;IAcnE;;OAEG;IACH,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAO5C;;;OAGG;IACH,mBAAmB,CAAC,IAAI,EAAE,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,GAAG,IAAI;IA4BzE,OAAO,CAAC,aAAa;IA8BrB,OAAO,CAAC,eAAe;IAIvB,OAAO,CAAC,aAAa;IASrB,OAAO,CAAC,mBAAmB;IAQ3B,OAAO,CAAC,4BAA4B;IAIpC,OAAO,CAAC,6BAA6B;CAGtC;AAMD,wBAAgB,0BAA0B,CACxC,cAAc,CAAC,EAAE,KAAK,CAAC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,GACxD,oBAAoB,CAEtB"}

package/dist/cost/preCallCostEstimator.js

@@ -0,0 +1,256 @@
+"use strict";
+/**
+ * A3M Router - Pre-Call Cost Estimator
+ *
+ * Estimates cost BEFORE making an API call based on input features.
+ * Uses historical data patterns and token count estimation via character ratio.
+ *
+ * No external API calls - all estimation is local.
+ *
+ * Usage:
+ *   const estimator = new PreCallCostEstimator();
+ *   const estimate = estimator.estimate({
+ *     query: "What is Python?",
+ *     modelTier: 'mid',
+ *     provider: 'groq'
+ *   });
+ *   console.log(estimate); // { estimatedTokens: 24, estimatedCost: 0.0014, estimatedLatency: 200 }
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PreCallCostEstimator = void 0;
+exports.createPreCallCostEstimator = createPreCallCostEstimator;
+// Default latency estimates per tier (ms)
+const TIER_LATENCY = {
+    free: { min: 500, max: 5000, avg: 2000 },
+    cheap: { min: 100, max: 800, avg: 300 },
+    mid: { min: 200, max: 1500, avg: 600 },
+    premium: { min: 300, max: 2000, avg: 800 },
+    enterprise: { min: 200, max: 1500, avg: 500 },
+};
+// ============================================================
+// PreCallCostEstimator
+// ============================================================
+class PreCallCostEstimator {
+    // Historical data for regression: [charCount, actualTokens][] tuples
+    historicalData = [];
+    // Linear regression coefficients
+    slope = 0.25; // chars per token ratio
+    intercept = 10;
+    // EWMA for latency estimation
+    latencyHistory = [];
+    ewmaAlpha = 0.3;
+    constructor(historicalData) {
+        if (historicalData && historicalData.length > 0) {
+            this.fitLinearRegression(historicalData);
+        }
+    }
+    /**
+     * Main estimation method - estimates tokens, cost, and latency.
+     */
+    estimate(input) {
+        const { query, modelTier = 'mid', provider, explicitTokens, systemPromptLength = 0, } = input;
+        // Token estimation
+        let inputTokens;
+        if (explicitTokens !== undefined) {
+            inputTokens = explicitTokens;
+        }
+        else {
+            inputTokens = this.estimateTokens(query, systemPromptLength);
+        }
+        // Output token estimation based on query complexity
+        const outputTokens = this.estimateOutputTokens(query, inputTokens);
+        const totalTokens = inputTokens + outputTokens;
+        // Cost estimation
+        const costConfig = this.getCostConfig(provider, modelTier);
+        const estimatedCost = this.calculateCost(totalTokens, costConfig);
+        // Latency estimation
+        const estimatedLatency = this.estimateLatency(modelTier, inputTokens, totalTokens);
+        // Confidence based on amount of historical data we have
+        const confidence = this.calculateConfidence();
+        return {
+            estimatedTokens: totalTokens,
+            estimatedInputTokens: inputTokens,
+            estimatedOutputTokens: outputTokens,
+            estimatedCost: Math.round(estimatedCost * 1000000) / 1000000, // 6 decimal places
+            estimatedLatency,
+            confidence,
+            breakdown: {
+                inputCostPerM: costConfig.input,
+                outputCostPerM: costConfig.output,
+                charToTokenRatio: this.slope,
+            },
+        };
+    }
+    /**
+     * Estimate input tokens using character-to-token ratio.
+     * Uses linear regression if historical data is available.
+     */
+    estimateTokens(text, systemPromptLength = 0) {
+        const totalChars = text.length + systemPromptLength;
+        if (this.historicalData.length >= 5) {
+            // Use linear regression
+            return Math.max(1, Math.round(this.slope * totalChars + this.intercept));
+        }
+        // Fallback: general English average ~4 chars per token
+        return Math.max(1, Math.round(totalChars / 4));
+    }
+    /**
+     * Estimate output tokens based on query complexity.
+     * More complex queries (code, analysis) tend to need more output.
+     */
+    estimateOutputTokens(query, inputTokens) {
+        const lower = query.toLowerCase();
+        // Base estimate: ~30% of input tokens as output
+        let multiplier = 0.3;
+        // Complexity adjustments
+        if (this.containsKeyword(lower, ['code', 'implement', 'function', 'class', 'algorithm'])) {
+            multiplier = 0.5; // Code needs more output
+        }
+        else if (this.containsKeyword(lower, ['explain', 'describe', 'what is', 'how does'])) {
+            multiplier = 0.35; // Explanations need moderate output
+        }
+        else if (this.containsKeyword(lower, ['list', 'count', 'find all'])) {
+            multiplier = 0.4; // List queries need more output
+        }
+        else if (this.containsKeyword(lower, ['yes', 'no', 'is', 'are', 'does'])) {
+            multiplier = 0.1; // Simple questions need minimal output
+        }
+        // Cap to reasonable bounds
+        return Math.min(Math.max(10, Math.round(inputTokens * multiplier)), 4000 // Max 4k output tokens
+        );
+    }
+    /**
+     * Calculate cost in USD.
+     */
+    calculateCost(totalTokens, config) {
+        const inputM = this.estimateInputTokensFromTotal(totalTokens) / 1_000_000;
+        const outputM = this.estimateOutputTokensFromTotal(totalTokens) / 1_000_000;
+        return inputM * config.input + outputM * config.output;
+    }
+    /**
+     * Estimate latency in milliseconds.
+     */
+    estimateLatency(tier, inputTokens, totalTokens) {
+        const tierLatency = TIER_LATENCY[tier];
+        // Base latency from tier
+        let latency = tierLatency.avg;
+        // Scale by token count (rough linear approximation)
+        const tokenScale = totalTokens / 100;
+        latency *= Math.max(0.5, Math.min(3, tokenScale));
+        // Adjust for historical EWMA if available
+        if (this.latencyHistory.length > 0) {
+            const ewmaLatency = this.calculateEwma();
+            latency = latency * 0.7 + ewmaLatency * 0.3;
+        }
+        return Math.round(latency);
+    }
+    /**
+     * Record actual tokens for future regression improvements.
+     */
+    recordActualTokens(queryLength, actualTokens) {
+        this.historicalData.push({ chars: queryLength, tokens: actualTokens });
+        // Keep only last 100 data points
+        if (this.historicalData.length > 100) {
+            this.historicalData.shift();
+        }
+        // Refit regression periodically
+        if (this.historicalData.length % 10 === 0) {
+            this.fitLinearRegression(this.historicalData);
+        }
+    }
+    /**
+     * Record actual latency for EWMA updates.
+     */
+    recordActualLatency(latencyMs) {
+        this.latencyHistory.push(latencyMs);
+        if (this.latencyHistory.length > 50) {
+            this.latencyHistory.shift();
+        }
+    }
+    /**
+     * Fit linear regression to historical data.
+     * Uses ordinary least squares.
+     */
+    fitLinearRegression(data) {
+        if (data.length < 2)
+            return;
+        const n = data.length;
+        let sumX = 0, sumY = 0, sumXY = 0, sumX2 = 0;
+        for (const { chars, tokens } of data) {
+            sumX += chars;
+            sumY += tokens;
+            sumXY += chars * tokens;
+            sumX2 += chars * chars;
+        }
+        const denominator = n * sumX2 - sumX * sumX;
+        if (denominator === 0)
+            return;
+        this.slope = (n * sumXY - sumX * sumY) / denominator;
+        this.intercept = (sumY - this.slope * sumX) / n;
+        // Sanity check
+        if (this.slope <= 0 || this.slope > 1) {
+            this.slope = 0.25; // Reset to default if outlier
+            this.intercept = 10;
+        }
+    }
+    // ---- Private helpers ----
+    getCostConfig(provider, tier) {
+        // Provider-specific costs (from providerConfig.ts patterns)
+        const providerCosts = {
+            groq: { input: 0.59, output: 0.79 },
+            cerebras: { input: 0.60, output: 0.60 },
+            deepseek: { input: 0.14, output: 0.28 },
+            deepinfra: { input: 0.05, output: 0.05 },
+            together: { input: 0.18, output: 0.18 },
+            fireworks: { input: 0.20, output: 0.20 },
+            mistral: { input: 0.20, output: 0.60 },
+            openai: { input: 2.50, output: 10.00 },
+            anthropic: { input: 3.00, output: 15.00 },
+        };
+        if (provider && providerCosts[provider]) {
+            return providerCosts[provider];
+        }
+        // Tier fallback
+        const tierCosts = {
+            free: { input: 0, output: 0 },
+            cheap: { input: 0.20, output: 0.40 },
+            mid: { input: 1.00, output: 3.00 },
+            premium: { input: 3.00, output: 12.00 },
+            enterprise: { input: 5.00, output: 20.00 },
+        };
+        return tier ? tierCosts[tier] : tierCosts.mid;
+    }
+    containsKeyword(text, keywords) {
+        return keywords.some(kw => text.includes(kw));
+    }
+    calculateEwma() {
+        if (this.latencyHistory.length === 0)
+            return 0;
+        let ewma = this.latencyHistory[0];
+        for (let i = 1; i < this.latencyHistory.length; i++) {
+            ewma = this.ewmaAlpha * this.latencyHistory[i] + (1 - this.ewmaAlpha) * ewma;
+        }
+        return ewma;
+    }
+    calculateConfidence() {
+        // More historical data = higher confidence
+        const dataFactor = Math.min(this.historicalData.length / 50, 1.0);
+        // More latency history = higher confidence
+        const latencyFactor = Math.min(this.latencyHistory.length / 20, 1.0);
+        return Math.round((dataFactor * 0.6 + latencyFactor * 0.4) * 100) / 100;
+    }
+    estimateInputTokensFromTotal(total) {
+        return Math.round(total * 0.7); // Assume 70% input
+    }
+    estimateOutputTokensFromTotal(total) {
+        return Math.round(total * 0.3); // Assume 30% output
+    }
+}
+exports.PreCallCostEstimator = PreCallCostEstimator;
+// ============================================================
+// Factory
+// ============================================================
+function createPreCallCostEstimator(historicalData) {
+    return new PreCallCostEstimator(historicalData);
+}
+//# sourceMappingURL=preCallCostEstimator.js.map