free-coding-models 0.1.81 → 0.1.83

package/lib/config.js

@@ -85,6 +85,9 @@
  *   → loadConfig() — Read ~/.free-coding-models.json; auto-migrate old plain-text config if needed
  *   → saveConfig(config) — Write config to ~/.free-coding-models.json with 0o600 permissions
  *   → getApiKey(config, providerKey) — Get effective API key (env var override > config > null)
+ *   → addApiKey(config, providerKey, key) — Append a key (string→array); ignores empty/duplicate
+ *   → removeApiKey(config, providerKey, index?) — Remove key at index (or last); collapses array-of-1 to string; deletes when empty
+ *   → listApiKeys(config, providerKey) — Return all keys for a provider as normalized array
  *   → isProviderEnabled(config, providerKey) — Check if provider is enabled (defaults true)
  *   → saveAsProfile(config, name) — Snapshot current apiKeys/providers/favorites/settings into a named profile
  *   → loadProfile(config, name) — Apply a named profile's values onto the live config
@@ -95,6 +98,7 @@
  *   → _emptyProfileSettings() — Default TUI settings for a profile
  *
  * @exports loadConfig, saveConfig, getApiKey, isProviderEnabled
+ * @exports addApiKey, removeApiKey, listApiKeys — multi-key management helpers
  * @exports saveAsProfile, loadProfile, listProfiles, deleteProfile
  * @exports getActiveProfileName, setActiveProfile
  * @exports CONFIG_PATH — path to the JSON config file
@@ -239,6 +243,124 @@ export function getApiKey(config, providerKey) {
   return null
 }
 
+/**
+ * addApiKey: Append a new API key for a provider.
+ *
+ * - If the provider has no key yet, sets it as a plain string.
+ * - If the provider already has one string key, converts to array [existing, new].
+ * - If the provider already has an array, pushes the new key.
+ * - Ignores empty/whitespace keys.
+ * - Ignores exact duplicates (same string already present).
+ *
+ * @param {object} config — Live config object (will be mutated)
+ * @param {string} providerKey — Provider identifier (e.g. 'groq')
+ * @param {string} key — New API key to add
+ * @returns {boolean} true if added, false if ignored (empty or duplicate)
+ */
+export function addApiKey(config, providerKey, key) {
+  const trimmed = typeof key === 'string' ? key.trim() : ''
+  if (!trimmed) return false
+  if (!config.apiKeys) config.apiKeys = {}
+  const current = config.apiKeys[providerKey]
+  if (!current) {
+    config.apiKeys[providerKey] = trimmed
+    return true
+  }
+  if (typeof current === 'string') {
+    if (current === trimmed) return false // duplicate
+    config.apiKeys[providerKey] = [current, trimmed]
+    return true
+  }
+  if (Array.isArray(current)) {
+    if (current.includes(trimmed)) return false // duplicate
+    current.push(trimmed)
+    return true
+  }
+  // unknown shape — replace
+  config.apiKeys[providerKey] = trimmed
+  return true
+}
+
+/**
+ * removeApiKey: Remove an API key for a provider by index, or remove the last one.
+ *
+ * - Removes the key at `index` if provided, else removes the last key.
+ * - If only one key remains after removal, collapses array to string.
+ * - If the last key is removed, deletes the provider entry entirely.
+ *
+ * @param {object} config — Live config object (will be mutated)
+ * @param {string} providerKey — Provider identifier (e.g. 'groq')
+ * @param {number} [index] — 0-based index to remove; omit to remove last
+ * @returns {boolean} true if a key was removed, false if nothing to remove
+ */
+export function removeApiKey(config, providerKey, index) {
+  if (!config.apiKeys) return false
+  const current = config.apiKeys[providerKey]
+  if (!current) return false
+
+  if (typeof current === 'string') {
+    // Only one key — remove it
+    delete config.apiKeys[providerKey]
+    return true
+  }
+
+  if (Array.isArray(current)) {
+    const idx = (index !== undefined && index >= 0 && index < current.length) ? index : current.length - 1
+    current.splice(idx, 1)
+    if (current.length === 0) {
+      delete config.apiKeys[providerKey]
+    } else if (current.length === 1) {
+      config.apiKeys[providerKey] = current[0] // collapse array-of-1 to string
+    }
+    return true
+  }
+
+  return false
+}
+
+/**
+ * listApiKeys: Return all configured API keys for a provider as a normalized array.
+ * Empty when no key is configured.
+ *
+ * @param {object} config
+ * @param {string} providerKey
+ * @returns {string[]}
+ */
+export function listApiKeys(config, providerKey) {
+  return resolveApiKeys(config, providerKey)
+}
+
+/**
+ * Resolve all API keys for a provider as an array.
+ * Handles: string → [string], string[] → string[], missing → []
+ * Filters empty strings. Falls back to envVarName if no config key.
+ */
+export function resolveApiKeys(config, providerKey, envVarName) {
+  const raw = config?.apiKeys?.[providerKey]
+  let keys = []
+  if (Array.isArray(raw)) {
+    keys = raw
+  } else if (typeof raw === 'string' && raw.length > 0) {
+    keys = [raw]
+  } else if (envVarName && process.env[envVarName]) {
+    keys = [process.env[envVarName]]
+  }
+  return keys.filter(k => typeof k === 'string' && k.length > 0)
+}
+
+/**
+ * Normalize config for disk persistence.
+ * Single-element arrays collapse to string. Multi-element arrays stay.
+ */
+export function normalizeApiKeyConfig(config) {
+  if (!config?.apiKeys) return
+  for (const [key, val] of Object.entries(config.apiKeys)) {
+    if (Array.isArray(val) && val.length === 1) {
+      config.apiKeys[key] = val[0]
+    }
+  }
+}
+
 /**
  * 📖 isProviderEnabled: Check if a provider is enabled in config.
  *

package/lib/error-classifier.js

@@ -0,0 +1,154 @@
+/**
+ * Error types:
+ * - QUOTA_EXHAUSTED: Skip account until quota resets
+ * - RATE_LIMITED: Backoff, try another account
+ * - MODEL_CAPACITY: Server overloaded, retry after delay
+ * - SERVER_ERROR: Backoff, count toward circuit breaker
+ * - AUTH_ERROR: Disable account permanently
+ * - NETWORK_ERROR: Connection failure, try another
+ * - MODEL_NOT_FOUND: Provider does not have/serve this model; skip and try next account
+ * - UNKNOWN: Generic, no retry
+ */
+export const ErrorType = {
+  QUOTA_EXHAUSTED: 'QUOTA_EXHAUSTED',
+  RATE_LIMITED: 'RATE_LIMITED',
+  MODEL_CAPACITY: 'MODEL_CAPACITY',
+  SERVER_ERROR: 'SERVER_ERROR',
+  AUTH_ERROR: 'AUTH_ERROR',
+  NETWORK_ERROR: 'NETWORK_ERROR',
+  MODEL_NOT_FOUND: 'MODEL_NOT_FOUND',
+  UNKNOWN: 'UNKNOWN',
+}
+
+const QUOTA_KEYWORDS = ['quota', 'limit exceeded', 'billing', 'insufficient_quota', 'exceeded your']
+const CAPACITY_KEYWORDS = ['overloaded', 'capacity', 'busy', 'unavailable']
+/**
+ * Keywords that indicate a provider-level 404/410 means the model is not
+ * available on *this account/provider*, not a generic routing 404.
+ * These trigger rotation to the next provider rather than forwarding the error.
+ */
+const MODEL_NOT_FOUND_KEYWORDS = [
+  'model not found',
+  'inaccessible',
+  'not deployed',
+  'model is not available',
+  'model unavailable',
+  'no such model',
+]
+
+/**
+ * Classify the confidence level for a 429 response.
+ *
+ * Returns:
+ * - 'quota_exhaustion_likely' — body contains keywords indicating the account's quota is depleted
+ * - 'generic_rate_limit'      — plain rate-limit with no quota-specific signal (or non-429 status)
+ *
+ * @param {number} statusCode
+ * @param {string} body
+ * @param {Object} headers
+ * @returns {'quota_exhaustion_likely'|'generic_rate_limit'}
+ */
+export function rateLimitConfidence(statusCode, body, headers) {
+  if (statusCode !== 429) return 'generic_rate_limit'
+  const bodyLower = (body || '').toLowerCase()
+  const isQuota = QUOTA_KEYWORDS.some(kw => bodyLower.includes(kw))
+  return isQuota ? 'quota_exhaustion_likely' : 'generic_rate_limit'
+}
+
+/**
+ * Classify an HTTP error response.
+ * @param {number} statusCode - 0 for network errors
+ * @param {string} body - Response body text or error message
+ * @param {Object} headers - Response headers (lowercased keys)
+ * @returns {{ type: string, retryAfterSec: number|null, shouldRetry: boolean, skipAccount: boolean, rateLimitConfidence?: string }}
+ */
+export function classifyError(statusCode, body, headers) {
+  const bodyLower = (body || '').toLowerCase()
+  const retryAfter = headers?.['retry-after']
+  const retryAfterSec = retryAfter ? parseInt(retryAfter, 10) || null : null
+
+  // Network/connection errors
+  if (statusCode === 0 || statusCode === undefined) {
+    return { type: ErrorType.NETWORK_ERROR, retryAfterSec: 5, shouldRetry: true, skipAccount: false }
+  }
+
+  if (statusCode === 401 || statusCode === 403) {
+    return { type: ErrorType.AUTH_ERROR, retryAfterSec: null, shouldRetry: false, skipAccount: true }
+  }
+
+  // Provider-level 404/410: model not found / inaccessible / not deployed on this account.
+  // These are NOT generic routing 404s — they mean this specific provider doesn't serve
+  // the requested model. Rotate to the next account rather than forwarding the error.
+  if (statusCode === 404 || statusCode === 410) {
+    const isModelNotFound = MODEL_NOT_FOUND_KEYWORDS.some(kw => bodyLower.includes(kw))
+    if (isModelNotFound) {
+      return { type: ErrorType.MODEL_NOT_FOUND, retryAfterSec: null, shouldRetry: true, skipAccount: true }
+    }
+    // Generic 404 (wrong URL, endpoint not found, etc.) — not retryable
+    return { type: ErrorType.UNKNOWN, retryAfterSec: null, shouldRetry: false, skipAccount: false }
+  }
+
+  if (statusCode === 429) {
+    const isQuota = QUOTA_KEYWORDS.some(kw => bodyLower.includes(kw))
+    const confidence = isQuota ? 'quota_exhaustion_likely' : 'generic_rate_limit'
+    if (isQuota) {
+      return { type: ErrorType.QUOTA_EXHAUSTED, retryAfterSec, shouldRetry: true, skipAccount: true, rateLimitConfidence: confidence }
+    }
+    return { type: ErrorType.RATE_LIMITED, retryAfterSec, shouldRetry: true, skipAccount: false, rateLimitConfidence: confidence }
+  }
+
+  if (statusCode === 503 || statusCode === 502) {
+    return { type: ErrorType.MODEL_CAPACITY, retryAfterSec: retryAfterSec || 5, shouldRetry: true, skipAccount: false }
+  }
+
+  if (statusCode >= 500) {
+    return { type: ErrorType.SERVER_ERROR, retryAfterSec: retryAfterSec || 10, shouldRetry: true, skipAccount: false }
+  }
+
+  return { type: ErrorType.UNKNOWN, retryAfterSec: null, shouldRetry: false, skipAccount: false }
+}
+
+/**
+ * Circuit breaker: CLOSED → OPEN (after threshold failures) → HALF_OPEN (after cooldown) → CLOSED (on success) or → OPEN (on failure)
+ */
+export class CircuitBreaker {
+  constructor({ threshold = 5, cooldownMs = 60000 } = {}) {
+    this.threshold = threshold
+    this.cooldownMs = cooldownMs
+    this.consecutiveFailures = 0
+    this.openedAt = null
+    this.state = 'CLOSED'
+  }
+
+  recordFailure() {
+    this.consecutiveFailures++
+    if (this.consecutiveFailures >= this.threshold || this.state === 'HALF_OPEN') {
+      this.state = 'OPEN'
+      this.openedAt = Date.now()
+    }
+  }
+
+  recordSuccess() {
+    this.consecutiveFailures = 0
+    this.state = 'CLOSED'
+    this.openedAt = null
+  }
+
+  isOpen() {
+    if (this.state === 'CLOSED') return false
+    if (this.state === 'OPEN' && Date.now() - this.openedAt >= this.cooldownMs) {
+      this.state = 'HALF_OPEN'
+      return false
+    }
+    if (this.state === 'HALF_OPEN') return false
+    return true
+  }
+
+  isHalfOpen() { return this.state === 'HALF_OPEN' }
+
+  reset() {
+    this.consecutiveFailures = 0
+    this.state = 'CLOSED'
+    this.openedAt = null
+  }
+}

package/lib/log-reader.js

@@ -0,0 +1,174 @@
+/**
+ * @file lib/log-reader.js
+ * @description Pure functions to load recent request-log entries from
+ *   ~/.free-coding-models/request-log.jsonl, newest-first, bounded by a
+ *   configurable row limit.
+ *
+ * Design principles:
+ *   - Bounded reads only — never slurp the entire log for every TUI repaint.
+ *   - Tolerates malformed / partially-written JSONL lines by skipping them.
+ *   - No shared mutable state (pure functions, injectable file path for tests).
+ *   - No new npm dependencies — uses only Node.js built-ins.
+ *
+ * Default path:
+ *   ~/.free-coding-models/request-log.jsonl
+ *
+ * Row object shape returned from loadRecentLogs():
+ *   {
+ *     time:     string   // ISO timestamp string  (from entry.timestamp)
+ *     requestType: string // e.g. "chat.completions"
+ *     model:    string   // e.g. "llama-3.3-70b-instruct"
+ *     provider: string   // e.g. "nvidia"
+ *     status:   string   // e.g. "200" | "429" | "error"
+ *     tokens:   number   // promptTokens + completionTokens (0 if unknown)
+ *     latency:  number   // ms (0 if unknown)
+ *   }
+ *
+ * @exports loadRecentLogs
+ * @exports parseLogLine
+ */
+
+import { existsSync, statSync, openSync, readSync, closeSync } from 'node:fs'
+import { join } from 'node:path'
+import { homedir } from 'node:os'
+
+const DEFAULT_LOG_FILE = join(homedir(), '.free-coding-models', 'request-log.jsonl')
+
+/** Maximum bytes to read from the tail of the file to avoid OOM on large logs. */
+const MAX_READ_BYTES = 128 * 1024 // 128 KB
+
+function normalizeTimestamp(raw) {
+  if (typeof raw === 'number' && Number.isFinite(raw)) {
+    return new Date(raw).toISOString()
+  }
+  if (typeof raw === 'string') {
+    const numeric = Number(raw)
+    if (Number.isFinite(numeric)) return new Date(numeric).toISOString()
+    const parsed = new Date(raw)
+    if (!Number.isNaN(parsed.getTime())) return parsed.toISOString()
+  }
+  return null
+}
+
+function inferProvider(entry) {
+  if (entry.providerKey || entry.provider) {
+    return String(entry.providerKey ?? entry.provider)
+  }
+  if (typeof entry.accountId === 'string' && entry.accountId.includes('/')) {
+    return entry.accountId.split('/')[0] || 'unknown'
+  }
+  return 'unknown'
+}
+
+function inferStatus(entry) {
+  if (entry.statusCode !== undefined || entry.status !== undefined) {
+    return String(entry.statusCode ?? entry.status)
+  }
+  if (typeof entry.success === 'boolean') {
+    return entry.success ? '200' : 'error'
+  }
+  return 'unknown'
+}
+
+function inferRequestType(entry) {
+  if (entry.requestType !== undefined || entry.type !== undefined) {
+    return String(entry.requestType ?? entry.type)
+  }
+  if (typeof entry.url === 'string') {
+    if (entry.url.includes('/chat/completions')) return 'chat.completions'
+    if (entry.url.includes('/models')) return 'models'
+  }
+  return 'chat.completions'
+}
+
+/**
+ * Parse a single JSONL line into a normalised log row object.
+ *
+ * Returns `null` for any line that is blank, not valid JSON, or missing
+ * the required `timestamp` field.
+ *
+ * @param {string} line - A single text line from the JSONL file.
+ * @returns {{ time: string, requestType: string, model: string, provider: string, status: string, tokens: number, latency: number } | null}
+ */
+export function parseLogLine(line) {
+  const trimmed = line.trim()
+  if (!trimmed) return null
+  let entry
+  try {
+    entry = JSON.parse(trimmed)
+  } catch {
+    return null
+  }
+  if (!entry || typeof entry !== 'object') return null
+  if (!entry.timestamp) return null
+
+  const normalizedTime = normalizeTimestamp(entry.timestamp)
+  if (!normalizedTime) return null
+
+  const model    = String(entry.modelId    ?? entry.model    ?? 'unknown')
+  const provider = inferProvider(entry)
+  const status   = inferStatus(entry)
+  const requestType = inferRequestType(entry)
+  const tokens   = (Number(entry.usage?.prompt_tokens ?? entry.promptTokens ?? 0) +
+                    Number(entry.usage?.completion_tokens ?? entry.completionTokens ?? 0)) || 0
+  const latency  = Number(entry.latencyMs ?? entry.latency ?? 0) || 0
+
+  return {
+    time: normalizedTime,
+    requestType,
+    model,
+    provider,
+    status,
+    tokens,
+    latency,
+  }
+}
+
+/**
+ * Load the N most-recent log entries from the JSONL file, newest-first.
+ *
+ * Only reads up to MAX_READ_BYTES from the end of the file to avoid
+ * loading the entire log history.  Malformed lines are silently skipped.
+ *
+ * @param {object}  [opts]
+ * @param {string}  [opts.logFile]  - Path to request-log.jsonl (injectable for tests)
+ * @param {number}  [opts.limit]    - Maximum rows to return (default 200)
+ * @returns {Array<{ time: string, requestType: string, model: string, provider: string, status: string, tokens: number, latency: number }>}
+ */
+export function loadRecentLogs({ logFile = DEFAULT_LOG_FILE, limit = 200 } = {}) {
+  try {
+    if (!existsSync(logFile)) return []
+
+    const fileSize = statSync(logFile).size
+    if (fileSize === 0) return []
+
+    // 📖 Read only the tail of the file (bounded by MAX_READ_BYTES) to avoid
+    // 📖 reading multi-megabyte logs on every TUI repaint.
+    const readBytes = Math.min(fileSize, MAX_READ_BYTES)
+    const fileOffset = fileSize - readBytes
+
+    const buf = Buffer.allocUnsafe(readBytes)
+    const fd = openSync(logFile, 'r')
+    try {
+      readSync(fd, buf, 0, readBytes, fileOffset)
+    } finally {
+      closeSync(fd)
+    }
+
+    const text = buf.toString('utf8')
+
+    // 📖 Split on newlines; if we started mid-line (fileOffset > 0), drop
+    // 📖 the first (potentially incomplete) line to avoid corrupt JSON.
+    const rawLines = text.split('\n')
+    const lines = fileOffset > 0 ? rawLines.slice(1) : rawLines
+
+    const rows = []
+    for (let i = lines.length - 1; i >= 0 && rows.length < limit; i--) {
+      const row = parseLogLine(lines[i])
+      if (row) rows.push(row)
+    }
+    return rows
+  } catch {
+    return []
+  }
+}

package/lib/model-merger.js

@@ -0,0 +1,78 @@
+const TIER_RANK = { 'S+': 0, 'S': 1, 'A+': 2, 'A': 3, 'A-': 4, 'B+': 5, 'B': 6, 'C': 7 }
+
+function parseCtxK(ctx) {
+  if (!ctx) return 0
+  const s = ctx.toLowerCase()
+  if (s.endsWith('m')) return parseFloat(s) * 1000
+  return parseFloat(s) || 0
+}
+
+function parseSwePercent(swe) {
+  return parseFloat(swe) || 0
+}
+
+/**
+ * Generate a unique slug from a label.
+ * "DeepSeek V3.2" → "deepseek-v3-2"
+ * Appends suffix if collision detected.
+ */
+function slugify(label, existingSlugs) {
+  let base = label.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '')
+  let slug = base
+  let i = 2
+  while (existingSlugs.has(slug)) {
+    slug = `${base}-${i++}`
+  }
+  existingSlugs.add(slug)
+  return slug
+}
+
+/**
+ * Build merged model list from flat MODELS array.
+ * Groups by display label. Each merged entry contains all providers.
+ *
+ * @param {Array} models - Flat array of [modelId, label, tier, sweScore, ctx, providerKey]
+ * @returns {Array<MergedModel>}
+ *
+ * MergedModel: {
+ *   slug: string,           // unique URL-safe identifier
+ *   label: string,          // display name
+ *   tier: string,           // best tier across providers
+ *   sweScore: string,       // highest SWE score
+ *   ctx: string,            // largest context window
+ *   providerCount: number,
+ *   providers: Array<{ modelId: string, providerKey: string, tier: string }>
+ * }
+ */
+export function buildMergedModels(models) {
+  const groups = new Map()
+
+  for (const [modelId, label, tier, sweScore, ctx, providerKey] of models) {
+    if (!groups.has(label)) {
+      groups.set(label, { label, tier, sweScore, ctx, providers: [] })
+    }
+
+    const group = groups.get(label)
+    group.providers.push({ modelId, providerKey, tier })
+
+    // Keep best tier
+    if ((TIER_RANK[tier] ?? 99) < (TIER_RANK[group.tier] ?? 99)) {
+      group.tier = tier
+    }
+    // Keep highest SWE score
+    if (parseSwePercent(sweScore) > parseSwePercent(group.sweScore)) {
+      group.sweScore = sweScore
+    }
+    // Keep largest context
+    if (parseCtxK(ctx) > parseCtxK(group.ctx)) {
+      group.ctx = ctx
+    }
+  }
+
+  const existingSlugs = new Set()
+  return Array.from(groups.values()).map(g => ({
+    ...g,
+    slug: slugify(g.label, existingSlugs),
+    providerCount: g.providers.length,
+  }))
+}