@axplusb/kepler 0.0.1 → 1.0.1

package/src/core/pricing.mjs

@@ -0,0 +1,314 @@
+/**
+ * Model Pricing — per-model cost calculation.
+ *
+ * Two sources of truth:
+ * 1. OpenRouter /api/v1/models endpoint (live pricing, fetched at startup)
+ * 2. Static fallback table (for non-OpenRouter providers: Anthropic, OpenAI, Google)
+ *
+ * All prices in USD per million tokens (MTok).
+ *
+ * PRD-028: Phase 1 — CLI-side pricing with live OpenRouter fetch.
+ */
+
+// ── Static Fallback Table (non-OpenRouter providers) ─────────
+
+const STATIC_PRICING = {
+    // ── Anthropic (direct API, not via OpenRouter) ──
+    'claude-opus-4':              { input: 15,    output: 75,   cache_read: 1.50,  cache_write: 18.75 },
+    'claude-sonnet-4':            { input: 3,     output: 15,   cache_read: 0.30,  cache_write: 3.75  },
+    'claude-haiku-3-5':           { input: 0.80,  output: 4,    cache_read: 0.08,  cache_write: 1.0   },
+
+    // ── OpenAI (direct API) ──
+    'gpt-4o':                     { input: 2.50,  output: 10   },
+    'gpt-4.1':                    { input: 2,     output: 8    },
+    'gpt-4.1-mini':               { input: 0.40,  output: 1.60 },
+    'gpt-4.1-nano':               { input: 0.10,  output: 0.40 },
+    'o3':                         { input: 2,     output: 8    },
+    'o3-mini':                    { input: 1.10,  output: 4.40 },
+    'o4-mini':                    { input: 1.10,  output: 4.40 },
+
+    // ── Google (direct API) ──
+    'gemini-2.5-pro':             { input: 1.25,  output: 10   },
+    'gemini-2.5-flash':           { input: 0.30,  output: 2.50 },
+    'gemini-2.0-flash':           { input: 0.10,  output: 0.40 },
+
+    // ── Bedrock (Anthropic models via AWS) ──
+    'us.anthropic.claude-sonnet-4-6-20260401-v1:0': { input: 3, output: 15, cache_read: 0.30, cache_write: 3.75 },
+    'us.anthropic.claude-haiku-4-5-20251001-v1:0':  { input: 0.80, output: 4, cache_read: 0.08, cache_write: 1.0 },
+};
+
+const DEFAULT_PRICING = { input: 3, output: 15 };
+
+// ── Live OpenRouter Pricing Cache ────────────────────────────
+
+let _openRouterPricing = null;  // Map<model_id, { input, output }>
+let _fetchPromise = null;
+
+/**
+ * Fetch live pricing from OpenRouter's /api/v1/models endpoint.
+ * Called once at startup, cached for the session.
+ * Non-blocking — returns immediately, populates cache in background.
+ */
+export async function fetchOpenRouterPricing() {
+    if (_openRouterPricing) return _openRouterPricing;
+    if (_fetchPromise) return _fetchPromise;
+
+    _fetchPromise = (async () => {
+        try {
+            const controller = new AbortController();
+            const timeout = setTimeout(() => controller.abort(), 8000);
+
+            const res = await fetch('https://openrouter.ai/api/v1/models', {
+                signal: controller.signal,
+                headers: { 'Accept': 'application/json' },
+            });
+            clearTimeout(timeout);
+
+            if (!res.ok) return null;
+
+            const data = await res.json();
+            const models = data.data || [];
+            const pricing = new Map();
+
+            for (const m of models) {
+                const id = m.id;
+                const p = m.pricing;
+                if (!id || !p) continue;
+
+                // OpenRouter returns per-token prices as strings
+                const input = parseFloat(p.prompt || '0') * 1_000_000;   // convert to per-MTok
+                const output = parseFloat(p.completion || '0') * 1_000_000;
+
+                pricing.set(id, { input, output });
+            }
+
+            _openRouterPricing = pricing;
+            return pricing;
+        } catch {
+            // Network error, timeout, or parse error — fall back to static
+            return null;
+        } finally {
+            _fetchPromise = null;
+        }
+    })();
+
+    return _fetchPromise;
+}
+
+/**
+ * Start fetching OpenRouter pricing in the background.
+ * Call this at CLI startup — non-blocking.
+ */
+export function prefetchPricing() {
+    fetchOpenRouterPricing().catch(() => {});
+}
+
+// ── Model ID Normalization ───────────────────────────────────
+
+/**
+ * Normalize a model ID for pricing lookup.
+ * Strips version suffixes, date stamps, provider prefixes (openrouter/).
+ */
+function normalizeModelId(model) {
+    if (!model) return '';
+    let id = model.trim().toLowerCase();
+
+    // Strip 'openrouter/' prefix
+    id = id.replace(/^openrouter\//, '');
+
+    // Strip date suffixes like -20250514 or -preview-05-06
+    id = id.replace(/-\d{8}$/, '');
+    id = id.replace(/-preview[-\d]*$/, '');
+
+    return id;
+}
+
+/**
+ * Look up pricing for a model ID.
+ *
+ * Search order:
+ * 1. OpenRouter live pricing (exact match)
+ * 2. Static table (exact → normalized → provider-stripped)
+ * 3. Default fallback ($3/$15 Sonnet)
+ *
+ * @param {string} model
+ * @returns {{ input: number, output: number, cache_read?: number, cache_write?: number }}
+ */
+export function lookupPricing(model) {
+    if (!model) return DEFAULT_PRICING;
+
+    // 1. OpenRouter live cache (exact match — OpenRouter IDs are canonical)
+    if (_openRouterPricing) {
+        const orPrice = _openRouterPricing.get(model);
+        if (orPrice) return orPrice;
+
+        // Try normalized
+        const normalized = normalizeModelId(model);
+        const orNorm = _openRouterPricing.get(normalized);
+        if (orNorm) return orNorm;
+    }
+
+    // 2. Static table — exact match
+    if (STATIC_PRICING[model]) return STATIC_PRICING[model];
+
+    // Normalized match
+    const normalized = normalizeModelId(model);
+    if (STATIC_PRICING[normalized]) return STATIC_PRICING[normalized];
+
+    // Try without provider prefix (e.g. 'google/gemini-2.5-pro' → 'gemini-2.5-pro')
+    const withoutProvider = normalized.replace(/^[^/]+\//, '');
+    if (STATIC_PRICING[withoutProvider]) return STATIC_PRICING[withoutProvider];
+
+    // Try with common provider prefixes
+    for (const prefix of ['deepseek/', 'xiaomi/', 'google/', 'meta/', 'qwen/', 'moonshotai/']) {
+        if (STATIC_PRICING[prefix + withoutProvider]) return STATIC_PRICING[prefix + withoutProvider];
+    }
+
+    // 3. OpenRouter fuzzy match (without provider prefix)
+    if (_openRouterPricing) {
+        for (const [id, price] of _openRouterPricing) {
+            if (id.endsWith('/' + withoutProvider)) return price;
+        }
+    }
+
+    return DEFAULT_PRICING;
+}
+
+// ── Cost Calculation ─────────────────────────────────────────
+
+/**
+ * Calculate cost from a usage object.
+ *
+ * Supports two formats:
+ * 1. New format (with per-model breakdown):
+ *    { models: [{ model, input_tokens, output_tokens, cache_read_tokens, cache_creation_tokens }] }
+ *
+ * 2. Legacy format (flat tokens, no model):
+ *    { input_tokens, output_tokens }
+ *
+ * @param {Object} usage - Usage object from backend complete event
+ * @returns {{ total: number, breakdown: Array, accurate: boolean }}
+ */
+export function calculateCost(usage) {
+    if (!usage) return { total: 0, breakdown: [], accurate: false };
+
+    // Best case: backend computed cost from live OpenRouter pricing
+    if (typeof usage.total_cost === 'number' && usage.models && usage.models.length > 0) {
+        const breakdown = usage.models.map(m => ({
+            model: m.model,
+            role: m.role || 'unknown',
+            input_tokens: m.input_tokens || 0,
+            output_tokens: m.output_tokens || 0,
+            cache_read_tokens: m.cache_read_tokens || 0,
+            cache_creation_tokens: m.cache_creation_tokens || 0,
+            cost: m.cost || 0,
+            free: (m.cost || 0) === 0 && (m.input_tokens || 0) > 0,
+            pricingSource: 'backend',
+        }));
+
+        return {
+            total: usage.total_cost,
+            breakdown,
+            accurate: true,
+        };
+    }
+
+    // Fallback: per-model breakdown without backend cost — CLI computes
+    if (usage.models && usage.models.length > 0) {
+        const breakdown = usage.models.map(m => {
+            const pricing = lookupPricing(m.model);
+            const inputCost = (m.input_tokens || 0) * pricing.input / 1_000_000;
+            const outputCost = (m.output_tokens || 0) * pricing.output / 1_000_000;
+            const cacheReadCost = (m.cache_read_tokens || 0) * (pricing.cache_read || pricing.input) / 1_000_000;
+            const cacheWriteCost = (m.cache_creation_tokens || 0) * (pricing.cache_write || pricing.input) / 1_000_000;
+            const cost = inputCost + outputCost + cacheReadCost + cacheWriteCost;
+
+            const usedLivePricing = _openRouterPricing?.has(m.model) || false;
+            const usedStaticPricing = STATIC_PRICING[m.model] || STATIC_PRICING[normalizeModelId(m.model)];
+
+            return {
+                model: m.model,
+                role: m.role || 'unknown',
+                input_tokens: m.input_tokens || 0,
+                output_tokens: m.output_tokens || 0,
+                cache_read_tokens: m.cache_read_tokens || 0,
+                cache_creation_tokens: m.cache_creation_tokens || 0,
+                cost,
+                free: pricing.input === 0 && pricing.output === 0,
+                pricingSource: usedLivePricing ? 'openrouter' : usedStaticPricing ? 'static' : 'default',
+            };
+        });
+
+        const allAccurate = breakdown.every(b => b.pricingSource !== 'default');
+
+        return {
+            total: breakdown.reduce((sum, b) => sum + b.cost, 0),
+            breakdown,
+            accurate: allAccurate,
+        };
+    }
+
+    // Legacy format: flat tokens, unknown model — use default pricing
+    const inputTokens = usage.total_input_tokens || usage.input_tokens || 0;
+    const outputTokens = usage.total_output_tokens || usage.output_tokens || 0;
+    const total = (inputTokens * DEFAULT_PRICING.input + outputTokens * DEFAULT_PRICING.output) / 1_000_000;
+
+    return {
+        total,
+        breakdown: [{
+            model: 'unknown',
+            role: 'unknown',
+            input_tokens: inputTokens,
+            output_tokens: outputTokens,
+            cost: total,
+            free: false,
+            pricingSource: 'default',
+        }],
+        accurate: false,
+    };
+}
+
+// ── Formatting ───────────────────────────────────────────────
+
+/**
+ * Format a cost value as a dollar string.
+ * @param {number} cost
+ * @returns {string}
+ */
+export function formatCostValue(cost) {
+    if (cost === 0) return '$0.00';
+    if (cost < 0.01) return `$${cost.toFixed(4)}`;
+    return `$${cost.toFixed(2)}`;
+}
+
+/**
+ * Format a token count for display (e.g. 42100 → '42.1k').
+ * @param {number} tokens
+ * @returns {string}
+ */
+export function formatTokens(tokens) {
+    if (tokens === 0) return '0';
+    if (tokens < 1000) return String(tokens);
+    return `${(tokens / 1000).toFixed(1)}k`;
+}
+
+/**
+ * Check if a model is free-tier.
+ * @param {string} model
+ * @returns {boolean}
+ */
+export function isFreeModel(model) {
+    const pricing = lookupPricing(model);
+    return pricing.input === 0 && pricing.output === 0;
+}
+
+/**
+ * Get pricing status (for /status display).
+ * @returns {{ source: string, modelCount: number }}
+ */
+export function getPricingStatus() {
+    if (_openRouterPricing) {
+        return { source: 'openrouter-live', modelCount: _openRouterPricing.size };
+    }
+    return { source: 'static-fallback', modelCount: Object.keys(STATIC_PRICING).length };
+}

package/src/core/providers.mjs

@@ -0,0 +1,219 @@
+/**
+ * Multi-Provider — unified provider config and request/response transforms.
+ *
+ * Supports: Anthropic, OpenAI, Google, Bedrock (stub), Vertex (stub).
+ * Each provider defines endpoint, auth headers, and optional transforms.
+ */
+
+const PROVIDERS = {
+    anthropic: {
+        name: 'Anthropic',
+        endpoint: 'https://api.anthropic.com/v1/messages',
+        envKey: 'ANTHROPIC_API_KEY',
+        authHeader(key) {
+            return {
+                'x-api-key': key,
+                'anthropic-version': '2023-06-01',
+                'Content-Type': 'application/json',
+            };
+        },
+        models: ['claude-sonnet-4-6', 'claude-haiku-4-5', 'claude-opus-4-6'],
+    },
+
+    openai: {
+        name: 'OpenAI',
+        endpoint: 'https://api.openai.com/v1/chat/completions',
+        envKey: 'OPENAI_API_KEY',
+        authHeader(key) {
+            return {
+                'Authorization': `Bearer ${key}`,
+                'Content-Type': 'application/json',
+            };
+        },
+        models: ['gpt-4o', 'gpt-4o-mini', 'o1-preview', 'o1-mini', 'o3-mini'],
+        transformRequest(body) {
+            const messages = [];
+            if (body.system) {
+                messages.push({ role: 'system', content: body.system });
+            }
+            for (const msg of body.messages || []) {
+                if (typeof msg.content === 'string') {
+                    messages.push({ role: msg.role, content: msg.content });
+                } else if (Array.isArray(msg.content)) {
+                    for (const block of msg.content) {
+                        if (block.type === 'tool_result') {
+                            messages.push({
+                                role: 'tool',
+                                tool_call_id: block.tool_use_id,
+                                content: block.content,
+                            });
+                        }
+                    }
+                }
+            }
+
+            const tools = (body.tools || []).map(t => ({
+                type: 'function',
+                function: { name: t.name, description: t.description, parameters: t.input_schema },
+            }));
+
+            return {
+                model: body.model,
+                messages,
+                ...(tools.length > 0 && { tools }),
+                ...(body.max_tokens && { max_tokens: body.max_tokens }),
+                ...(body.stream && { stream: true }),
+            };
+        },
+        transformResponse(data) {
+            const choice = data.choices?.[0];
+            if (!choice) throw new Error('No choices in OpenAI response');
+
+            const content = [];
+            if (choice.message?.content) {
+                content.push({ type: 'text', text: choice.message.content });
+            }
+            if (choice.message?.tool_calls) {
+                for (const tc of choice.message.tool_calls) {
+                    content.push({
+                        type: 'tool_use',
+                        id: tc.id,
+                        name: tc.function.name,
+                        input: JSON.parse(tc.function.arguments || '{}'),
+                    });
+                }
+            }
+
+            return {
+                content,
+                stop_reason: choice.finish_reason === 'stop' ? 'end_turn' : choice.finish_reason,
+                usage: {
+                    input_tokens: data.usage?.prompt_tokens || 0,
+                    output_tokens: data.usage?.completion_tokens || 0,
+                },
+            };
+        },
+    },
+
+    google: {
+        name: 'Google',
+        endpoint: 'https://generativelanguage.googleapis.com/v1beta/models',
+        envKey: 'GOOGLE_API_KEY',
+        altEnvKey: 'GEMINI_API_KEY',
+        authHeader(key) {
+            return { 'Content-Type': 'application/json' };
+        },
+        models: ['gemini-2.0-flash', 'gemini-2.0-pro', 'gemini-1.5-flash'],
+        transformRequest(body) {
+            const contents = [];
+            for (const msg of body.messages || []) {
+                const role = msg.role === 'assistant' ? 'model' : 'user';
+                if (typeof msg.content === 'string') {
+                    contents.push({ role, parts: [{ text: msg.content }] });
+                }
+            }
+
+            return {
+                contents,
+                ...(body.system && {
+                    systemInstruction: { parts: [{ text: body.system }] },
+                }),
+            };
+        },
+        transformResponse(data) {
+            const candidate = data.candidates?.[0];
+            if (!candidate) throw new Error('No candidates in Google response');
+
+            const content = [];
+            for (const part of candidate.content?.parts || []) {
+                if (part.text) content.push({ type: 'text', text: part.text });
+            }
+
+            return {
+                content,
+                stop_reason: 'end_turn',
+                usage: {
+                    input_tokens: data.usageMetadata?.promptTokenCount || 0,
+                    output_tokens: data.usageMetadata?.candidatesTokenCount || 0,
+                },
+            };
+        },
+    },
+
+    bedrock: {
+        name: 'AWS Bedrock',
+        endpoint: null, // Dynamic based on region
+        envKey: 'AWS_ACCESS_KEY_ID',
+        models: ['anthropic.claude-3-sonnet', 'anthropic.claude-3-haiku'],
+        authHeader() {
+            // AWS SigV4 signing would go here
+            return { 'Content-Type': 'application/json' };
+        },
+        getEndpoint(model, region = 'us-east-1') {
+            return `https://bedrock-runtime.${region}.amazonaws.com/model/${model}/invoke`;
+        },
+    },
+
+    vertex: {
+        name: 'Google Vertex AI',
+        endpoint: null, // Dynamic based on project/region
+        envKey: 'GOOGLE_APPLICATION_CREDENTIALS',
+        models: ['claude-sonnet-4-6@anthropic'],
+        authHeader() {
+            // GCP bearer token would go here
+            return { 'Content-Type': 'application/json' };
+        },
+        getEndpoint(model, project, region = 'us-central1') {
+            return `https://${region}-aiplatform.googleapis.com/v1/projects/${project}/locations/${region}/publishers/anthropic/models/${model}:rawPredict`;
+        },
+    },
+};
+
+/**
+ * Get the provider configuration for a given model.
+ * @param {string} model - model name
+ * @returns {object} provider config
+ */
+export function getProvider(model) {
+    if (model.startsWith('claude') || model.startsWith('anthropic')) return PROVIDERS.anthropic;
+    if (model.startsWith('gpt') || model.startsWith('o1') || model.startsWith('o3')) return PROVIDERS.openai;
+    if (model.startsWith('gemini')) return PROVIDERS.google;
+    return PROVIDERS.anthropic; // default
+}
+
+/**
+ * Get a provider by name.
+ * @param {string} name
+ * @returns {object|undefined}
+ */
+export function getProviderByName(name) {
+    return PROVIDERS[name];
+}
+
+/**
+ * List all supported providers.
+ * @returns {Array<{ name: string, envKey: string, models: string[] }>}
+ */
+export function listProviders() {
+    return Object.entries(PROVIDERS).map(([key, p]) => ({
+        id: key,
+        name: p.name,
+        envKey: p.envKey,
+        models: p.models || [],
+        hasEndpoint: !!p.endpoint,
+    }));
+}
+
+/**
+ * Check which providers have API keys configured.
+ * @returns {Array<{ id: string, name: string, configured: boolean }>}
+ */
+export function checkProviderKeys() {
+    return Object.entries(PROVIDERS).map(([key, p]) => ({
+        id: key,
+        name: p.name,
+        configured: !!(process.env[p.envKey] || (p.altEnvKey && process.env[p.altEnvKey])),
+    }));
+}
+
+export { PROVIDERS };

package/src/core/rate-limiter.mjs

@@ -0,0 +1,119 @@
+/**
+ * Rate Limiter — handle 429 and 529 API responses.
+ *
+ * Implements exponential backoff with jitter for rate-limited
+ * and overloaded API responses. Tracks retry state per-instance.
+ */
+
+export class RateLimiter {
+    /**
+     * @param {object} [options]
+     * @param {number} [options.maxRetries] - max number of retries (default: 5)
+     * @param {number} [options.baseDelay] - base delay in ms (default: 1000)
+     * @param {number} [options.maxDelay] - max delay in ms (default: 60000)
+     */
+    constructor(options = {}) {
+        this.maxRetries = options.maxRetries ?? 5;
+        this.baseDelay = options.baseDelay ?? 1000;
+        this.maxDelay = options.maxDelay ?? 60000;
+        this.retryAfter = 0;
+        this.retryCount = 0;
+        this.lastRetryAt = null;
+    }
+
+    /**
+     * Handle an API response and determine whether to retry.
+     * @param {{ status: number, headers: { get: (name: string) => string|null } }} response
+     * @returns {Promise<'ok'|'retry'|'fail'>}
+     */
+    async handleResponse(response) {
+        if (response.status === 429) {
+            // Rate limited
+            if (this.retryCount >= this.maxRetries) return 'fail';
+
+            const retryAfter = parseInt(response.headers?.get?.('retry-after') || '10', 10);
+            const delayMs = Math.min(retryAfter * 1000, this.maxDelay);
+            this.retryAfter = Date.now() + delayMs;
+            this.retryCount++;
+            this.lastRetryAt = new Date().toISOString();
+
+            await this.wait(delayMs);
+            return 'retry';
+        }
+
+        if (response.status === 529) {
+            // API overloaded
+            if (this.retryCount >= this.maxRetries) return 'fail';
+
+            const delay = this.calculateBackoff();
+            this.retryAfter = Date.now() + delay;
+            this.retryCount++;
+            this.lastRetryAt = new Date().toISOString();
+
+            await this.wait(delay);
+            return 'retry';
+        }
+
+        // Success — reset retry count
+        this.retryCount = 0;
+        return 'ok';
+    }
+
+    /**
+     * Calculate exponential backoff with jitter.
+     * @returns {number} delay in milliseconds
+     */
+    calculateBackoff() {
+        const exponential = this.baseDelay * Math.pow(2, this.retryCount);
+        const jitter = Math.random() * this.baseDelay;
+        return Math.min(exponential + jitter, this.maxDelay);
+    }
+
+    /**
+     * Check if we should wait before making a request.
+     * @returns {boolean}
+     */
+    shouldWait() {
+        return Date.now() < this.retryAfter;
+    }
+
+    /**
+     * Get remaining wait time in ms.
+     * @returns {number}
+     */
+    remainingWait() {
+        return Math.max(0, this.retryAfter - Date.now());
+    }
+
+    /**
+     * Reset all retry state.
+     */
+    reset() {
+        this.retryAfter = 0;
+        this.retryCount = 0;
+        this.lastRetryAt = null;
+    }
+
+    /**
+     * Get current limiter status.
+     */
+    status() {
+        return {
+            retryCount: this.retryCount,
+            maxRetries: this.maxRetries,
+            retryAfter: this.retryAfter,
+            lastRetryAt: this.lastRetryAt,
+            isWaiting: this.shouldWait(),
+            remainingMs: this.remainingWait(),
+        };
+    }
+
+    /**
+     * Wait for the specified duration.
+     * @param {number} ms
+     * @returns {Promise<void>}
+     */
+    wait(ms) {
+        return new Promise(resolve => setTimeout(resolve, ms));
+    }
+}