champollion 0.3.3

package/lib/methods/anthropic.js

@@ -0,0 +1,140 @@
+/**
+ * Anthropic Translation Method — direct Anthropic Messages API.
+ *
+ * Extends DirectLLMMethod to provide Anthropic-specific:
+ *   - API endpoint (https://api.anthropic.com/v1/messages)
+ *   - Auth header format (x-api-key + anthropic-version)
+ *   - Request body (messages, system param, temperature)
+ *   - Response parsing (content[0].text)
+ *   - Model listing via GET /v1/models
+ *   - Pricing (claude-sonnet, claude-haiku, claude-opus)
+ *
+ * All shared logic (translate, translateContent, coaching, retry, validation)
+ * lives in DirectLLMMethod.
+ */
+
+import { DirectLLMMethod } from './direct-llm.js';
+import { fetchAvailableModels } from '../models.js';
+import { estimateLlmCost } from './provider-pricing.js';
+
+// The default model, named ONCE. It was previously written twice — in
+// _getDefaultModel() and again as an inline `pairConfig.model || '...'`
+// fallback in estimateCost() — so the two could drift and price a run
+// against a model it did not use.
+const DEFAULT_MODEL = 'claude-sonnet-4-6';
+
+class AnthropicMethod extends DirectLLMMethod {
+  constructor(options = {}) {
+    super(options);
+    this.name = 'anthropic';
+  }
+
+  // ── Provider identity ────────────────────────────────────────────
+
+  _getApiKeyEnvVar()     { return 'ANTHROPIC_API_KEY'; }
+  _getApiKeyOptionsKey() { return 'anthropicApiKey'; }
+  _getDefaultModel()     { return DEFAULT_MODEL; }
+  _getProviderLabel()    { return 'Anthropic'; }
+
+  // ── API request/response shape ───────────────────────────────────
+
+  _buildApiRequest({ prompt, systemMessage, apiKey, model, temperature }) {
+    // Anthropic uses a separate 'system' field rather than a system message in
+    // the messages array. This is important for prompt caching — the system
+    // field is cached independently by Anthropic's infrastructure.
+    // Anthropic requires max_tokens as a mandatory parameter.
+    // Set generously high — the model stops naturally when done.
+    // A low value (e.g., 4096) risks truncating large translation batches.
+    const body = {
+      model,
+      messages: [{ role: 'user', content: prompt }],
+      max_tokens: 16384,
+      temperature,
+    };
+
+    if (systemMessage) {
+      body.system = systemMessage;
+    }
+
+    return {
+      url: 'https://api.anthropic.com/v1/messages',
+      headers: {
+        'x-api-key': apiKey,
+        'anthropic-version': '2023-06-01',
+        'Content-Type': 'application/json',
+      },
+      body,
+    };
+  }
+
+  _extractResponseText(json) {
+    return json.content?.[0]?.text || null;
+  }
+
+  // ── Runtime model listing ────────────────────────────────────────
+
+  async _fetchModels(apiKey) {
+    // Delegate to the shared models.js module — single source of truth for
+    // model listing used by init wizard, `champollion models`, and validation.
+    return fetchAvailableModels('anthropic', apiKey);
+  }
+
+  // ── Model-aware quality tier ─────────────────────────────────────
+
+  _getModelTier(model) {
+    if (model.includes('haiku')) return 'budget';
+    if (model.includes('opus')) return 'premium';
+    return 'standard';  // sonnet
+  }
+
+  // ── Pricing ──────────────────────────────────────────────────────
+
+  async estimateCost(keyCount, pairConfig = {}) {
+    return estimateLlmCost('anthropic', pairConfig.model || DEFAULT_MODEL, keyCount);
+  }
+
+  // ── Provenance ───────────────────────────────────────────────────
+
+  checkReadiness(context) {
+    // Resolve through the same chain translate() uses (options → env →
+    // .env.local/.env in cwd) so readiness can never fail for a key the
+    // loader *would* read — e.g. ANTHROPIC_API_KEY set only in .env.local.
+    if (!this._resolveApiKey(context || {})) {
+      return { ready: false, reason: 'No Anthropic API key (ANTHROPIC_API_KEY).' };
+    }
+    return { ready: true };
+  }
+
+  getProvenance() {
+    return {
+      resources: [
+        {
+          name: 'Anthropic Messages API',
+          license: 'Proprietary (Anthropic ToS)',
+          type: 'api',
+        },
+      ],
+      commercialReady: true,
+      flags: [],
+    };
+  }
+
+  getSetupHelp() {
+    const apiKey = process.env.ANTHROPIC_API_KEY;
+    if (!apiKey) {
+      return [
+        '',
+        '  ┌─ Missing API Key ─────────────────────────────────────────────┐',
+        '  │ The Anthropic method requires an Anthropic API key.             │',
+        '  │                                                                │',
+        '  │ 1. Sign up at https://console.anthropic.com                     │',
+        '  │ 2. Run: export ANTHROPIC_API_KEY=sk-ant-...                    │',
+        '  │ 3. Or add to .env.local: ANTHROPIC_API_KEY=sk-ant-...          │',
+        '  └────────────────────────────────────────────────────────────────┘',
+      ];
+    }
+    return this._apiFailureHelp('Anthropic console');
+  }
+}
+
+export { AnthropicMethod };

package/lib/methods/apertium.js

@@ -0,0 +1,163 @@
+/**
+ * Apertium Translation Method — free/open-source RULE-BASED MT via the public
+ * Apertium APy REST API. Mirrors the harness ApertiumMethod
+ * (arena/mt_eval_harness/methods/apertium.py): same endpoint, env vars, and
+ * GET/responseData shape, so config is interchangeable between CLI and harness.
+ *
+ *   Endpoint: GET <base>/translate?langpair=<src>|<tgt>&q=<text>&markUnknown=no
+ *             default https://apertium.org/apy
+ *   Auth:     none (public). Keyed APy deployments accept ?key=<key>.
+ *   Env:      APERTIUM_API_URL (optional), APERTIUM_API_KEY (optional)
+ *   Locale:   pass-through (accepts ISO 639-1 'es' or 639-3 'spa')
+ *   License:  GPL — called as a separate service, never bundled.
+ *
+ * Only installed pairs work (strongest on related languages). An uninstalled
+ * pair returns HTTP 400 and is surfaced honestly, never faked.
+ */
+
+import { TranslationMethod } from './base.js';
+import { getEnvOrFileVar } from '../api-key.js';
+import { DEFAULT_METHOD_CONCURRENCY } from '../config.js';
+import { extractContentBody } from './content-separator.js';
+import { output } from '../output.js';
+import { fetchWithRetry } from './fetch-with-retry.js';
+import { pMap } from '../concurrent.js';
+
+const APERTIUM_DEFAULT_BASE = 'https://apertium.org/apy';
+const APERTIUM_USER_AGENT =
+  'Champollion-MT-Eval/0.1 (+https://champollion.dev; champollion CLI)';
+const APERTIUM_TIMEOUT_MS = 15000;
+
+class ApertiumMethod extends TranslationMethod {
+  constructor(options = {}) {
+    super('apertium', options);
+  }
+
+  _resolveEndpoint(options = {}) {
+    let ep = options.apertiumApiUrl
+      || getEnvOrFileVar('APERTIUM_API_URL')
+      || getEnvOrFileVar('APERTIUM_API_URL', options.cwd)
+      || APERTIUM_DEFAULT_BASE;
+    ep = ep.replace(/\/+$/, '');
+    if (ep.endsWith('/translate')) ep = ep.slice(0, -'/translate'.length);
+    return ep;
+  }
+
+  _resolveApiKey(options = {}) {
+    return options.apertiumApiKey
+      || getEnvOrFileVar('APERTIUM_API_KEY')
+      || getEnvOrFileVar('APERTIUM_API_KEY', options.cwd);
+  }
+
+  _buildUrl(base, langpair, text, apiKey) {
+    const params = new URLSearchParams({ langpair, q: text, markUnknown: 'no' });
+    if (apiKey) params.set('key', apiKey);
+    return `${base}/translate?${params.toString()}`;
+  }
+
+  async _translateOne(base, langpair, text, apiKey, label) {
+    const res = await fetchWithRetry(
+      this._buildUrl(base, langpair, text, apiKey),
+      { method: 'GET', headers: { 'User-Agent': APERTIUM_USER_AGENT } },
+      { label, timeoutMs: APERTIUM_TIMEOUT_MS },
+    );
+    if (!res) return null;
+    if (!res.ok) {
+      const body = await res.text();
+      output.error(`Apertium ${label}: ${res.status} — ${body.slice(0, 200)}`);
+      return null;
+    }
+    const json = await res.json();
+    const translated = json?.responseData?.translatedText;
+    return typeof translated === 'string' ? translated : null;
+  }
+
+  async translate(keys, sourceFlat, pairConfig, options) {
+    const base = this._resolveEndpoint(options);
+    const apiKey = this._resolveApiKey(options);
+    const langpair = `${pairConfig.source || 'en'}|${pairConfig.target}`;
+    const allTranslated = {};
+
+    const items = keys.filter(
+      (k) => typeof sourceFlat[k] === 'string' && sourceFlat[k],
+    );
+    await pMap(items, async (key) => {
+      const out = await this._translateOne(base, langpair, sourceFlat[key], apiKey, `key ${key}`);
+      if (out !== null) allTranslated[key] = out;
+    }, { concurrency: DEFAULT_METHOD_CONCURRENCY });
+
+    return Object.keys(allTranslated).length > 0 ? allTranslated : null;
+  }
+
+  async translateContent(prompt, pairConfig, options) {
+    const base = this._resolveEndpoint(options);
+    const apiKey = this._resolveApiKey(options);
+    const bodyText = extractContentBody(prompt);
+    if (!bodyText.trim()) return null;
+    const langpair = `${pairConfig.source || 'en'}|${pairConfig.target}`;
+    return this._translateOne(base, langpair, bodyText, apiKey, 'content');
+  }
+
+  async checkReadiness(context) {
+    const base = this._resolveEndpoint(context || {});
+    try {
+      const controller = new AbortController();
+      const timeoutId = setTimeout(() => controller.abort(), 5000);
+      const res = await fetch(`${base}/listPairs`, {
+        method: 'GET',
+        headers: { 'User-Agent': APERTIUM_USER_AGENT },
+        signal: controller.signal,
+      });
+      clearTimeout(timeoutId);
+      if (!res.ok) {
+        return { ready: false, reason: `Apertium API at ${base} responded ${res.status}.` };
+      }
+      return { ready: true };
+    } catch (err) {
+      return {
+        ready: false,
+        reason:
+          `Cannot reach Apertium API at ${base}: ` +
+          `${err.name === 'AbortError' ? 'timeout' : err.message}. ` +
+          `Override with APERTIUM_API_URL or self-host APy.`,
+      };
+    }
+  }
+
+  estimateCost(_keyCount) {
+    // The public Apertium API is free (rate-limited) — there is no per-character
+    // charge, so $0 is honest here (unlike local LLMs, whose compute cost is
+    // genuinely unknown).
+    return {
+      estimatedCost: 0,
+      currency: 'USD',
+      source: 'apertium-free-public-api',
+      note: 'Apertium public API is free (rate-limited; self-host for volume).',
+    };
+  }
+
+  getQualityTier() {
+    return 'standard';
+  }
+
+  getProvenance() {
+    return {
+      resources: [
+        { name: 'Apertium (rule-based MT)', license: 'GPL-3.0+', type: 'api' },
+      ],
+      commercialReady: false,
+      flags: ['rule-based', 'gpl'],
+    };
+  }
+
+  getSetupHelp() {
+    return [
+      '  Apertium (rule-based, free public API):',
+      '   • No API key needed — uses https://apertium.org/apy by default.',
+      '   • Only installed pairs work (strong on related languages, e.g. es↔ca, eng↔spa).',
+      '   • Self-host or point elsewhere: export APERTIUM_API_URL=https://your-apy',
+    ];
+  }
+}
+
+export { ApertiumMethod };

package/lib/methods/api.js

@@ -0,0 +1,316 @@
+/**
+ * API Translation Method — thin HTTP client for remote translation endpoints.
+ *
+ * This method contains ZERO translation logic. It is purely a transport layer
+ * that delegates translation to a remote server. All prompts, coaching data,
+ * grammar rules, and linguistic pipelines live server-side.
+ *
+ * HOW IT WORKS:
+ *   1. Reads the endpoint URL from the plugin manifest
+ *   2. Reads API key from CHAMPOLLION_API_KEY env var
+ *   3. POSTs keys to the endpoint per the champollion API contract
+ *   4. Receives translations + billing metadata
+ *   5. Returns the key-value map to the sync pipeline
+ *
+ * WHY THIS IS A DUMB PIPE:
+ *   The entire point of the API method is IP protection. The prompts,
+ *   coaching data, and evaluation techniques stay on the server. This
+ *   method ships in the open-source npm package and must contain nothing
+ *   proprietary. It sends keys out, gets translations back. That's it.
+ *
+ * REQUEST FORMAT (what champollion sends):
+ *   {
+ *     source_locale: "en",
+ *     target_locale: "crk",
+ *     method: "crk-coached-v1",
+ *     keys: { "hero.title": "Welcome", ... }
+ *   }
+ *
+ * RESPONSE FORMAT (what the API returns):
+ *   {
+ *     translations: { "hero.title": "tawâw...", ... },
+ *     meta: { model, cost_usd, quality_tier, ... }
+ *   }
+ *
+ * COST PROFILE: Varies by method — determined server-side
+ * QUALITY TIER: Varies by method — read from plugin manifest
+ */
+
+import { TranslationMethod } from './base.js';
+import {
+  MAX_RETRIES, REQUEST_TIMEOUT_MS,
+  getBackoffDelay, sleep,
+} from './http-utils.js';
+import { pMap } from '../concurrent.js';
+import { DEFAULT_METHOD_CONCURRENCY } from '../config.js';
+import { output } from '../output.js';
+
+// Maximum keys per API request (server-side limit)
+const MAX_KEYS_PER_REQUEST = 100;
+
+class APIMethod extends TranslationMethod {
+  constructor(options = {}) {
+    super('api', options);
+
+    // These come from the plugin manifest, set by the orchestrator
+    this.endpoint = options.endpoint || null;
+    this.methodName = options.methodName || null;
+    this.methodVersion = options.methodVersion || null;
+    this.qualityTier = options.qualityTier || 'standard';
+    this.pluginProvenance = options.provenance || null;
+  }
+
+  /**
+   * Translate a batch of key-value pairs via a remote API.
+   *
+   * @param {string[]} keys - Flat dot-notation keys to translate
+   * @param {object} sourceFlat - Full flattened source locale
+   * @param {object} pairConfig - Pair config (target, source, endpoint, etc.)
+   * @param {object} options - { apiKey } or reads from env
+   * @returns {object|null} Map of key → translated value, or null
+   */
+  async translate(keys, sourceFlat, pairConfig, options) {
+    const apiKey = options.apiKey
+      || process.env.CHAMPOLLION_API_KEY;
+
+    if (!apiKey) {
+      output.error('API method: No API key found.');
+      output.error('Set CHAMPOLLION_API_KEY in your environment.');
+      return null;
+    }
+
+    // Endpoint comes from the plugin manifest or the pair config
+    const endpoint = this.endpoint
+      || pairConfig.endpoint
+      || options.endpoint;
+
+    if (!endpoint) {
+      output.error('API method: No endpoint configured.');
+      output.error('Install a plugin: champollion plugin install <method-name>');
+      return null;
+    }
+
+    const sourceLocale = pairConfig.source || 'en';
+    const targetLocale = pairConfig.target;
+    const method = this.methodName || pairConfig.methodPlugin || 'default';
+
+    const allTranslated = {};
+
+    const batchChunks = [];
+    for (let i = 0; i < keys.length; i += MAX_KEYS_PER_REQUEST) {
+      batchChunks.push(keys.slice(i, i + MAX_KEYS_PER_REQUEST));
+    }
+
+    await pMap(batchChunks, async (chunk, idx) => {
+      // Build the key-value payload for this batch
+      const keysPayload = {};
+      for (const key of chunk) {
+        const value = sourceFlat[key];
+        if (value && typeof value === 'string') {
+          keysPayload[key] = value;
+        }
+      }
+
+      if (Object.keys(keysPayload).length === 0) return;
+
+      const result = await this._translateBatchWithRetry(
+        keysPayload,
+        sourceLocale,
+        targetLocale,
+        method,
+        endpoint,
+        apiKey,
+        idx + 1,
+      );
+
+      if (result) {
+        Object.assign(allTranslated, result);
+      }
+    }, { concurrency: DEFAULT_METHOD_CONCURRENCY });
+
+    return Object.keys(allTranslated).length > 0 ? allTranslated : null;
+  }
+
+  /**
+   * Freeform content translation via the API.
+   *
+   * The API method could support this in the future, but for now
+   * we only support key-value translation. Return null so the
+   * orchestrator falls back to the local LLM method.
+   */
+  async translateContent(_prompt, _pairConfig, _options) {
+    return null;
+  }
+
+  /**
+   * POST to the remote API with exponential backoff retry.
+   *
+   * @param {object} keysPayload - Map of key → source value
+   * @param {string} sourceLocale - Source language code
+   * @param {string} targetLocale - Target language code
+   * @param {string} method - Method name from plugin manifest
+   * @param {string} endpoint - API endpoint URL
+   * @param {string} apiKey - Remote API key
+   * @param {number} batchNum - Batch number for logging
+   * @returns {object|null} Map of key → translated value
+   */
+  async _translateBatchWithRetry(keysPayload, sourceLocale, targetLocale, method, endpoint, apiKey, batchNum) {
+    const keyCount = Object.keys(keysPayload).length;
+
+    for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+      try {
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
+
+        const response = await fetch(endpoint, {
+          method: 'POST',
+          headers: {
+            'Authorization': `Bearer ${apiKey}`,
+            'Content-Type': 'application/json',
+            'User-Agent': 'champollion',
+          },
+          body: JSON.stringify({
+            source_locale: sourceLocale,
+            target_locale: targetLocale,
+            method,
+            keys: keysPayload,
+          }),
+          signal: controller.signal,
+        });
+
+        clearTimeout(timeoutId);
+
+        // Handle rate limiting with retry
+        if (response.status === 429) {
+          if (attempt < MAX_RETRIES) {
+            // Respect Retry-After header if present
+            const retryAfter = response.headers.get('Retry-After');
+            const delay = retryAfter
+              ? parseInt(retryAfter, 10) * 1000
+              : getBackoffDelay(attempt);
+            output.warn(`⏳ API batch ${batchNum}: Rate limited — retrying in ${Math.round(delay / 1000)}s...`);
+            await sleep(delay);
+            continue;
+          }
+          output.error(`API batch ${batchNum}: Rate limited after ${MAX_RETRIES + 1} attempts`);
+          return null;
+        }
+
+        // Handle server errors with retry
+        if (response.status >= 500) {
+          if (attempt < MAX_RETRIES) {
+            const delay = getBackoffDelay(attempt);
+            output.warn(`⏳ API batch ${batchNum}: ${response.status} — retrying in ${Math.round(delay / 1000)}s...`);
+            await sleep(delay);
+            continue;
+          }
+          output.error(`API batch ${batchNum}: ${response.status} after ${MAX_RETRIES + 1} attempts`);
+          return null;
+        }
+
+        // Handle auth errors (no retry)
+        if (response.status === 401) {
+          const body = await response.json().catch(() => ({}));
+          output.error(`API method: Unauthorized — ${body.error?.message || 'Invalid API key'}`);
+          output.error('Check your CHAMPOLLION_API_KEY environment variable.');
+          return null;
+        }
+
+        // Handle payment required (no retry)
+        if (response.status === 402) {
+          const body = await response.json().catch(() => ({}));
+          output.error(`API method: ${body.error?.message || 'Payment required — usage limit exceeded.'}`);
+          return null;
+        }
+
+        // Handle method not found (no retry)
+        if (response.status === 404) {
+          const body = await response.json().catch(() => ({}));
+          output.error(`API method: Method "${method}" not found — ${body.error?.message || 'Unknown method'}`);
+          return null;
+        }
+
+        // Handle other client errors (no retry)
+        if (!response.ok) {
+          const body = await response.json().catch(() => ({}));
+          output.error(`API batch ${batchNum}: ${response.status} — ${body.error?.message || 'Unknown error'}`);
+          return null;
+        }
+
+        const json = await response.json();
+
+        // Handle partial success (207)
+        if (response.status === 207 && json.errors) {
+          const errorCount = Object.keys(json.errors).length;
+          output.warn(`API batch ${batchNum}: ${errorCount} key(s) failed`);
+          for (const [key, err] of Object.entries(json.errors)) {
+            output.warn(`${key}: ${err.message}`);
+          }
+        }
+
+        if (!json.translations || typeof json.translations !== 'object') {
+          output.error(`API batch ${batchNum}: Invalid response — no translations object`);
+          return null;
+        }
+
+        const translatedCount = Object.keys(json.translations).length;
+        const costStr = json.meta?.cost_usd ? ` $${json.meta.cost_usd.toFixed(4)}` : '';
+        output.info(`✓ API batch ${batchNum} (${translatedCount}/${keyCount} keys${costStr})`);
+
+        return json.translations;
+
+      } catch (err) {
+        if (err.name === 'AbortError') {
+          if (attempt < MAX_RETRIES) {
+            output.warn(`⏳ API batch ${batchNum}: Timeout — retrying...`);
+            continue;
+          }
+          output.error(`API batch ${batchNum}: Timeout after ${MAX_RETRIES + 1} attempts`);
+          return null;
+        }
+
+        if (attempt < MAX_RETRIES) {
+          const delay = getBackoffDelay(attempt);
+          output.warn(`⏳ API batch ${batchNum}: ${err.message} — retrying in ${Math.round(delay / 1000)}s...`);
+          await sleep(delay);
+        } else {
+          output.error(`API batch ${batchNum}: ${err.message} after ${MAX_RETRIES + 1} attempts`);
+          return null;
+        }
+      }
+    }
+    return null;
+  }
+
+  /**
+   * Cost estimation — API method pricing is determined by the remote server.
+   * We cannot estimate cost without querying the endpoint.
+   */
+  estimateCost(keyCount) {
+    return {
+      estimatedCost: null,
+      currency: 'USD',
+      source: 'server-determined',
+      note: 'Cost is determined by the remote API. Contact the provider for pricing.',
+    };
+  }
+
+  getQualityTier() {
+    return this.qualityTier;
+  }
+
+  getProvenance() {
+    if (this.pluginProvenance) {
+      return this.pluginProvenance;
+    }
+    return {
+      resources: [
+        { name: 'Remote Translation API', license: 'Provider ToS', type: 'api' },
+      ],
+      commercialReady: true,
+      flags: [],
+    };
+  }
+}
+
+export { APIMethod };