champollion 0.3.3

package/lib/methods/openrouter-client.js

@@ -0,0 +1,327 @@
+/**
+ * OpenRouter API Client — shared HTTP client for all LLM-based methods.
+ *
+ * Centralizes the OpenRouter chat-completion call pattern that was
+ * previously duplicated across llm.js, llm-coached.js, and their
+ * translateContent variants. Each call site only needed to differ in:
+ *   - prompt text
+ *   - temperature
+ *   - timeout multiplier
+ *   - log label
+ *
+ * This module provides two functions:
+ *   callOpenRouter()      — raw text response (for content translation)
+ *   callOpenRouterJSON()  — parsed + validated JSON (for key-value translation)
+ */
+
+import {
+  MAX_RETRIES, REQUEST_TIMEOUT_MS,
+  isRetryable, getBackoffDelay, sleep, stripCodeFences,
+} from './http-utils.js';
+import { DEFAULT_TEMPERATURE } from '../config.js';
+import { output } from '../output.js';
+import { recordTranslationError } from './translation-error.js';
+
+const OPENROUTER_URL = 'https://openrouter.ai/api/v1/chat/completions';
+
+/**
+ * Call OpenRouter's chat completion API with retry and backoff.
+ *
+ * Returns the raw text content from the model, with code fences stripped.
+ * Returns null on permanent failure (non-retryable error or exhausted retries).
+ *
+ * @param {object} options
+ * @param {string} options.prompt - The user message content
+ * @param {string} options.apiKey - OpenRouter API key
+ * @param {string} options.model - Model identifier (e.g. 'openai/gpt-4o-mini')
+ * @param {number} [options.temperature=0.3] - Sampling temperature
+ * @param {number} [options.timeoutMs] - Override timeout (default: REQUEST_TIMEOUT_MS)
+ * @param {string} [options.label='LLM'] - Label for log messages (e.g. 'Batch 3', 'Coached batch 1')
+ * @param {string} [options.xTitle='champollion'] - X-Title header value
+ * @param {string} [options.systemMessage] - Optional system message for prompt caching.
+ *   When provided, the system preamble (register, rules) is sent as a separate
+ *   role:system message, enabling provider-level prompt caching across batches
+ *   that share the same preamble for a given locale. The prompt parameter then
+ *   contains only the batch-specific payload (JSON key-value pairs).
+ * @returns {Promise<string|null>} Model response text, or null on failure
+ */
+async function callOpenRouter({
+  prompt,
+  apiKey,
+  model,
+  temperature = DEFAULT_TEMPERATURE,
+  timeoutMs = REQUEST_TIMEOUT_MS,
+  label = 'LLM',
+  xTitle = 'champollion',
+  systemMessage = null,
+}) {
+  for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+    try {
+      const controller = new AbortController();
+      const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+
+      // Build messages array — when systemMessage is provided, split preamble
+      // from payload to enable provider-level prompt caching. The system message
+      // (register + rules) is identical across batches for a given locale, so
+      // providers like Anthropic and Google cache it automatically.
+      const messages = systemMessage
+        ? [{ role: 'system', content: systemMessage }, { role: 'user', content: prompt }]
+        : [{ role: 'user', content: prompt }];
+
+      const response = await fetch(OPENROUTER_URL, {
+        method: 'POST',
+        headers: {
+          'Authorization': `Bearer ${apiKey}`,
+          'Content-Type': 'application/json',
+          'HTTP-Referer': 'https://github.com/gamedaysuits/Champollion',
+          'X-Title': xTitle,
+        },
+        body: JSON.stringify({
+          model,
+          messages,
+          temperature,
+        }),
+        signal: controller.signal,
+      });
+
+      clearTimeout(timeoutId);
+
+      // Retryable status (429, 5xx) — back off and try again
+      if (isRetryable(response.status)) {
+        if (attempt < MAX_RETRIES) {
+          const delay = getBackoffDelay(attempt);
+          output.warn(`⏳ ${label}: ${response.status} — retry ${attempt + 1}/${MAX_RETRIES} in ${Math.round(delay / 1000)}s...`);
+          await sleep(delay);
+          continue;
+        }
+        output.error(`${label}: ${response.status} after ${MAX_RETRIES + 1} attempts`);
+        recordTranslationError(response.status);
+        return null;
+      }
+
+      if (!response.ok) {
+        output.error(`${label}: API error ${response.status}`);
+        recordTranslationError(response.status);
+        return null;
+      }
+
+      const data = await response.json();
+      const content = data.choices?.[0]?.message?.content?.trim();
+      if (!content) {
+        // Empty responses are common with some models (especially for long
+        // markdown). Retry with backoff — same as HTTP errors — instead of
+        // giving up immediately and returning null (which skips the key).
+        if (attempt < MAX_RETRIES) {
+          const delay = getBackoffDelay(attempt);
+          output.warn(`⏳ ${label}: empty response — retry ${attempt + 1}/${MAX_RETRIES} in ${Math.round(delay / 1000)}s...`);
+          await sleep(delay);
+          continue;
+        }
+        output.error(`${label}: empty response after ${MAX_RETRIES + 1} attempts`);
+        return null;
+      }
+
+      // Strip markdown code fences if the model wraps its response
+      return stripCodeFences(content);
+
+    } catch (err) {
+      const isTimeout = err.name === 'AbortError';
+      const errLabel = isTimeout ? 'timeout' : err.message;
+
+      if (attempt < MAX_RETRIES) {
+        const delay = getBackoffDelay(attempt);
+        output.warn(`⏳ ${label}: ${errLabel} — retry ${attempt + 1}/${MAX_RETRIES} in ${Math.round(delay / 1000)}s...`);
+        await sleep(delay);
+        continue;
+      }
+
+      output.error(`${label} failed: ${errLabel}`);
+      return null;
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Call OpenRouter and parse the response as validated JSON key-value pairs.
+ *
+ * This is the standard pattern for key-value batch translation:
+ *   1. Send prompt to model
+ *   2. Parse JSON response
+ *   3. Validate: only accept keys from expectedKeys set
+ *   4. Block prototype-pollution keys
+ *
+ * @param {object} options - Same as callOpenRouter, plus:
+ * @param {Set<string>} options.expectedKeys - Set of keys to accept in the response
+ * @param {function} options.isUnsafeKey - Function to check for unsafe key segments
+ * @returns {Promise<object|null>} Validated key-value map, or null on failure
+ */
+async function callOpenRouterJSON({ expectedKeys, isUnsafeKey, ...callOptions }) {
+  const content = await callOpenRouter(callOptions);
+  if (!content) return null;
+
+  let parsed;
+  try {
+    parsed = JSON.parse(content);
+  } catch (err) {
+    // Models translating quoted text (e.g. `never “not a language.”`) often
+    // downgrade typographic quotes to unescaped ASCII quotes inside the JSON
+    // string value, which kills the parse. At temperature 0 a blind retry
+    // returns byte-identical output, so the cascade can never recover —
+    // repair the response instead of rejecting it.
+    try {
+      parsed = JSON.parse(repairUnescapedQuotes(content));
+      output.warn(`${callOptions.label || 'LLM'}: repaired unescaped quotes in model JSON.`);
+    } catch {
+      // Second recovery tier: the response keys are known exactly (models
+      // keep keys as-is per the prompt rules), so values can be extracted
+      // by anchoring on the key tokens even when quote damage confuses the
+      // in-string heuristic above (e.g. an inner quote directly before a
+      // comma: `... "geen taal", zei ...`).
+      parsed = extractByExpectedKeys(content, expectedKeys);
+      if (parsed) {
+        output.warn(`${callOptions.label || 'LLM'}: recovered ${Object.keys(parsed).length} value(s) from malformed model JSON via key anchors.`);
+      } else {
+        // Return structured error instead of null — the retry cascade needs to
+        // distinguish "API returned nothing" (null) from "API returned garbage
+        // JSON that we can retry with a smaller batch" (_parseError).
+        output.error(`${callOptions.label || 'LLM'}: JSON parse error — ${err.message}`);
+        return { _parseError: true, rawContent: content, error: err.message };
+      }
+    }
+  }
+
+  // Validate: only accept keys we sent, block prototype pollution
+  const validated = {};
+  for (const [key, value] of Object.entries(parsed)) {
+    if (expectedKeys.has(key) && typeof value === 'string' && !isUnsafeKey(key)) {
+      validated[key] = value;
+    }
+  }
+
+  return Object.keys(validated).length > 0 ? validated : null;
+}
+
+/**
+ * Escape unescaped ASCII double quotes inside JSON string values.
+ *
+ * Walks the text tracking in-string state. Inside a string, a `"` only
+ * terminates it when the next non-whitespace character is a JSON structural
+ * character (`:`, `,`, `}`, `]`) or end-of-input; any other `"` is an inner
+ * quote the model forgot to escape and becomes `\"`.
+ *
+ * The heuristic can misread an inner quote that directly precedes a comma
+ * (e.g. a value containing `"yes",`), in which case the repaired text still
+ * fails to parse and the caller falls back to the retry cascade — the repair
+ * never makes a previously-parseable response worse because it only runs
+ * after JSON.parse has already failed.
+ *
+ * @param {string} text - Raw model output that failed JSON.parse
+ * @returns {string} Text with inner quotes escaped
+ */
+function repairUnescapedQuotes(text) {
+  let out = '';
+  let inString = false;
+  for (let i = 0; i < text.length; i++) {
+    const ch = text[i];
+    if (!inString) {
+      if (ch === '"') inString = true;
+      out += ch;
+      continue;
+    }
+    if (ch === '\\') {
+      // Preserve existing escape pairs untouched
+      out += ch + (text[i + 1] ?? '');
+      i++;
+      continue;
+    }
+    if (ch === '"') {
+      let j = i + 1;
+      while (j < text.length && /\s/.test(text[j])) j++;
+      const next = text[j];
+      if (next === undefined || next === ':' || next === ',' || next === '}' || next === ']') {
+        inString = false;
+        out += ch;
+      } else {
+        out += '\\"';
+      }
+      continue;
+    }
+    out += ch;
+  }
+  return out;
+}
+
+/**
+ * Extract string values from a malformed JSON response by anchoring on the
+ * known key set.
+ *
+ * The prompt instructs models to keep keys exactly as sent, so every key in
+ * the response appears as a literal `"<key>"` token. The value for a key is
+ * the text between the quote that opens its value and the last quote before
+ * the next key's token (or the end of the response). This survives arbitrary
+ * unescaped-quote damage inside values — the failure mode that defeats both
+ * JSON.parse and the in-string repair heuristic.
+ *
+ * Only used as the last recovery tier after JSON.parse and
+ * repairUnescapedQuotes have both failed; extracted values still pass
+ * through the caller's key validation and the downstream quality gate.
+ *
+ * @param {string} text - Raw model output that failed to parse
+ * @param {Set<string>} expectedKeys - Keys that were sent in the batch
+ * @returns {object|null} Recovered key→value map, or null if nothing anchored
+ */
+function extractByExpectedKeys(text, expectedKeys) {
+  if (!expectedKeys || expectedKeys.size === 0) return null;
+
+  const anchors = [];
+  for (const key of expectedKeys) {
+    const token = JSON.stringify(key);
+    const idx = text.indexOf(token);
+    if (idx >= 0) anchors.push({ key, idx, token });
+  }
+  if (anchors.length === 0) return null;
+  anchors.sort((a, b) => a.idx - b.idx);
+
+  const result = {};
+  for (let i = 0; i < anchors.length; i++) {
+    const { key, idx, token } = anchors[i];
+
+    // Walk past `"<key>"` + whitespace + `:` + whitespace + opening `"`
+    let p = idx + token.length;
+    while (p < text.length && /\s/.test(text[p])) p++;
+    if (text[p] !== ':') continue;
+    p++;
+    while (p < text.length && /\s/.test(text[p])) p++;
+    if (text[p] !== '"') continue;
+
+    const valStart = p + 1;
+    const endLimit = i + 1 < anchors.length ? anchors[i + 1].idx : text.length;
+    const segment = text.slice(valStart, endLimit);
+    const lastQuote = segment.lastIndexOf('"');
+    if (lastQuote < 0) continue;
+    const raw = segment.slice(0, lastQuote);
+
+    // Normalize quotes to escaped form (both already-escaped and bare), keep
+    // every other escape sequence for JSON to decode, then parse as a single
+    // JSON string. A value that still fails to decode is skipped — the
+    // retry cascade handles it. U+0001 is a safe sentinel: raw control
+    // characters are invalid inside JSON strings, so it cannot occur in
+    // model output that reached us through the API's own JSON layer.
+    const SENTINEL = '\u0001';
+    const normalized = raw
+      .replace(/\\"/g, SENTINEL)
+      .replace(/"/g, '\\"')
+      .split(SENTINEL).join('\\"');
+    try {
+      result[key] = JSON.parse(`"${normalized}"`);
+    } catch {
+      continue;
+    }
+  }
+
+  return Object.keys(result).length > 0 ? result : null;
+}
+
+export { callOpenRouter, callOpenRouterJSON, repairUnescapedQuotes, extractByExpectedKeys, OPENROUTER_URL };

package/lib/methods/openrouter-pricing.js

@@ -0,0 +1,156 @@
+/**
+ * OpenRouter Pricing — fetch live model pricing for cost estimation.
+ *
+ * WHY: The LLM and LLM-Coached methods use OpenRouter, which aggregates
+ * 100+ models, each with different pricing. We can't hardcode rates.
+ * OpenRouter provides a public `/api/v1/models` endpoint with per-token
+ * pricing for every model — no auth required.
+ *
+ * HOW IT WORKS:
+ *   1. Fetches the model list from OpenRouter (cached for the process lifetime)
+ *   2. Looks up the specific model's input/output pricing
+ *   3. Estimates cost based on average tokens per key
+ *
+ * CACHE: Pricing is fetched once per process and cached in memory.
+ * This avoids hammering the API during large multi-pair syncs.
+ *
+ * FALLBACK: If the fetch fails (offline, rate-limited, etc.), returns
+ * null pricing — the cost table will show "unknown" for that method.
+ * This never blocks a sync.
+ */
+
+import { EST_INPUT_TOKENS_PER_KEY, EST_OUTPUT_TOKENS_PER_KEY } from '../config.js';
+
+const OPENROUTER_MODELS_URL = 'https://openrouter.ai/api/v1/models';
+
+// Coached methods inject grammar rules and dictionary matches into the
+// prompt — roughly 2.5x the input tokens of a standard prompt.
+const COACHED_INPUT_MULTIPLIER = 2.5;
+
+// In-memory cache: fetched once per process
+let _pricingCache = null;
+let _pricingFetchPromise = null;
+
+/**
+ * Fetch pricing for all OpenRouter models.
+ *
+ * Returns a Map of model ID → { input, output } (cost per token in USD).
+ * Caches the result for the lifetime of the process.
+ *
+ * @returns {Promise<Map<string, {input: number, output: number}>>}
+ */
+async function fetchModelPricing() {
+  // Return cached result if available
+  if (_pricingCache) return _pricingCache;
+
+  // Deduplicate concurrent fetches — if one is in flight, share the promise
+  if (_pricingFetchPromise) return _pricingFetchPromise;
+
+  _pricingFetchPromise = _doFetch();
+  try {
+    _pricingCache = await _pricingFetchPromise;
+    return _pricingCache;
+  } finally {
+    _pricingFetchPromise = null;
+  }
+}
+
+async function _doFetch() {
+  try {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), 5000);
+
+    const response = await fetch(OPENROUTER_MODELS_URL, {
+      headers: { 'User-Agent': 'champollion' },
+      signal: controller.signal,
+    });
+
+    clearTimeout(timeoutId);
+
+    if (!response.ok) return new Map();
+
+    const json = await response.json();
+    const models = json.data || [];
+    const pricing = new Map();
+
+    for (const model of models) {
+      if (model.id && model.pricing) {
+        pricing.set(model.id, {
+          input: parseFloat(model.pricing.prompt) || 0,
+          output: parseFloat(model.pricing.completion) || 0,
+        });
+      }
+    }
+
+    return pricing;
+  } catch {
+    // Offline, timeout, or API issue — return empty map
+    // Cost estimation degrades gracefully to "unknown"
+    return new Map();
+  }
+}
+
+/**
+ * Estimate cost for translating N keys with a specific model via OpenRouter.
+ *
+ * Uses real pricing from the OpenRouter models API when available.
+ * Falls back to a rough estimate when the model isn't found.
+ *
+ * Token estimation uses the shared EST_*_TOKENS_PER_KEY constants from
+ * config.js (~200 in / ~30 out — see the rationale there). They are the
+ * single source of truth for per-key token heuristics: this module used to
+ * hardcode 200/30 while config.js exported 60/10, so estimates disagreed
+ * between OpenRouter-routed and direct-provider engines.
+ * Coached methods use a 2.5x multiplier on input due to grammar/dictionary injection.
+ *
+ * @param {number} keyCount - Number of keys to translate
+ * @param {string} model - OpenRouter model ID (e.g., 'openai/gpt-4o-mini')
+ * @param {object} options
+ * @param {boolean} [options.coached=false] - Whether this is a coached method (larger prompts)
+ * @returns {Promise<{estimatedCost: number|null, currency: string, source: string, note: string}>}
+ */
+async function estimateOpenRouterCost(keyCount, model, options = {}) {
+  const coached = options.coached || false;
+  const pricing = await fetchModelPricing();
+
+  const modelPricing = pricing.get(model);
+  if (!modelPricing) {
+    return {
+      estimatedCost: null,
+      currency: 'USD',
+      source: 'unknown',
+      note: `Model "${model}" not found in OpenRouter pricing. Cost cannot be estimated.`,
+    };
+  }
+
+  // Token estimation: amortized system message + per-key payload,
+  // from the shared config.js constants (SSOT for all engines).
+  const inputTokensPerKey = coached
+    ? Math.round(EST_INPUT_TOKENS_PER_KEY * COACHED_INPUT_MULTIPLIER)
+    : EST_INPUT_TOKENS_PER_KEY;
+  const outputTokensPerKey = EST_OUTPUT_TOKENS_PER_KEY;
+
+  const totalInputTokens = keyCount * inputTokensPerKey;
+  const totalOutputTokens = keyCount * outputTokensPerKey;
+
+  const inputCost = totalInputTokens * modelPricing.input;
+  const outputCost = totalOutputTokens * modelPricing.output;
+  const totalCost = inputCost + outputCost;
+
+  return {
+    estimatedCost: Math.round(totalCost * 10000) / 10000,
+    currency: 'USD',
+    source: `openrouter (${model})`,
+    note: `Based on ${model} pricing: $${modelPricing.input}/tok in, $${modelPricing.output}/tok out.`,
+  };
+}
+
+/**
+ * Clear the pricing cache. Useful for testing.
+ */
+function clearPricingCache() {
+  _pricingCache = null;
+  _pricingFetchPromise = null;
+}
+
+export { fetchModelPricing, estimateOpenRouterCost, clearPricingCache };

package/lib/methods/provider-env.js

@@ -0,0 +1,115 @@
+/**
+ * Provider environment-variable SSOT.
+ *
+ * WHY: The translation method *loader* (`_resolveApiKey`), the preflight
+ * *readiness* check (`checkReadiness`), the `doctor` command, and the setup
+ * *help* text each used to hardcode their own env-var names. They drifted —
+ * e.g. the Microsoft loader read only MICROSOFT_TRANSLATOR_API_KEY while
+ * `doctor` checked only AZURE_TRANSLATOR_KEY. A user who set
+ * AZURE_TRANSLATOR_KEY got a green `doctor` ("✓ ready") but the loader
+ * returned null at run time and the sync silently produced nothing.
+ *
+ * This module is the single source of truth: one canonical name per provider
+ * plus the aliases the loader accepts. Every surface resolves keys through
+ * here, so `doctor` can never report a key "ready" under a name the loader
+ * won't read, and never report "not set" for a name the loader *would* read.
+ *
+ * The loader reads aliases too (so existing users with either name keep
+ * working); the canonical name is what we print in help/setup guidance.
+ */
+
+import { getEnvOrFileVar } from '../api-key.js';
+
+/**
+ * provider method name → { canonical, aliases, kind }
+ *
+ * `kind: 'url'` marks an endpoint URL (LibreTranslate) rather than a secret
+ * key — callers that only care about secrets can skip those.
+ *
+ * Keep these in sync with the harness loaders in
+ * arena/mt_eval_harness/methods/*.py (which already accept the same aliases
+ * via `_env_first(canonical, alias)`).
+ */
+export const PROVIDER_ENV = {
+  'deepl': {
+    canonical: 'DEEPL_API_KEY',
+    aliases: [],
+  },
+  'google-translate': {
+    canonical: 'GOOGLE_TRANSLATE_API_KEY',
+    aliases: ['GOOGLE_API_KEY'],
+  },
+  'microsoft-translator': {
+    canonical: 'MICROSOFT_TRANSLATOR_API_KEY',
+    aliases: ['AZURE_TRANSLATOR_KEY'],
+  },
+  'libretranslate': {
+    canonical: 'LIBRETRANSLATE_API_URL',
+    aliases: ['LIBRETRANSLATE_URL', 'LIBRE_URL'],
+    kind: 'url',
+  },
+  'tilde': {
+    canonical: 'TILDE_API_KEY',
+    aliases: [],
+  },
+  // Lara authenticates with a key PAIR; the adapter's readiness probe checks
+  // the secret (LARA_ACCESS_KEY_SECRET) alongside this canonical id.
+  'translated': {
+    canonical: 'LARA_ACCESS_KEY_ID',
+    aliases: [],
+  },
+};
+
+/**
+ * Ordered list of env var names for a provider: [canonical, ...aliases].
+ * Empty array for an unknown provider.
+ *
+ * @param {string} method - Provider method name (e.g. 'google-translate')
+ * @returns {string[]}
+ */
+export function providerEnvNames(method) {
+  const entry = PROVIDER_ENV[method];
+  return entry ? [entry.canonical, ...entry.aliases] : [];
+}
+
+/**
+ * The canonical env var name for a provider (what help/setup text should show).
+ *
+ * @param {string} method - Provider method name
+ * @returns {string|null}
+ */
+export function canonicalEnvName(method) {
+  return PROVIDER_ENV[method]?.canonical ?? null;
+}
+
+/**
+ * Resolve a provider's key by checking the canonical name then each alias,
+ * across process.env AND .env.local/.env (via getEnvOrFileVar) — exactly the
+ * surface the method loaders read. This is what readiness/doctor should use
+ * so they agree with the loader.
+ *
+ * @param {string} method - Provider method name
+ * @param {string} [cwd] - Project root for .env file lookup
+ * @returns {{ value: string|null, name: string|null }}
+ *   value: the resolved key/url, or null. name: the env var it came from.
+ */
+export function resolveProviderEnv(method, cwd) {
+  for (const name of providerEnvNames(method)) {
+    const value = getEnvOrFileVar(name, cwd);
+    if (value) return { value, name };
+  }
+  return { value: null, name: null };
+}
+
+/**
+ * Human-readable "NAME (or ALIAS)" string for messages.
+ *
+ * @param {string} method - Provider method name
+ * @returns {string}
+ */
+export function envNamesLabel(method) {
+  const names = providerEnvNames(method);
+  if (names.length === 0) return '';
+  if (names.length === 1) return names[0];
+  return `${names[0]} (or ${names.slice(1).join(', ')})`;
+}