champollion 0.3.4 → 0.4.0

package/lib/methods/direct-llm.js

@@ -2,14 +2,21 @@
  * DirectLLMMethod — shared base class for direct LLM provider integrations.
  *
  * WHY THIS EXISTS:
- *   OpenAI, Anthropic, and Gemini methods share ~90% of their logic:
- *     - Constructor with coaching cache
- *     - translate() with coaching loading, system message building, batch loop
- *     - translateContent() with coaching block prepending
- *     - Dictionary hint injection in per-batch user messages
+ *   OpenAI, Anthropic, Gemini and Local methods share ~90% of their logic:
+ *     - translate() with system message building and the batch loop
+ *     - translateContent()
  *     - JSON response parsing + key validation
  *     - Retry loop with exponential backoff
  *
+ *   THE PROMPT IS THE `llm` METHOD'S, exactly: promptSettingsFor() +
+ *   buildSystemMessage() + buildUserMessage() from llm.js (register, gender
+ *   guidance, prompt context, protected terms, coachingFile text, the
+ *   project glossary, per-key instructions). These methods used to build a
+ *   shorter one of their own — no protected terms, no prompt context, no
+ *   gender guidance — so a brand name could be translated through `local`
+ *   and kept through `llm` (found 2026-10-03). Structured coaching (grammar
+ *   rules, style notes) is the llm-coached method's, on any provider.
+ *
  *   The ONLY things that differ are:
  *     - API endpoint URL + auth header format
  *     - Request body shape (messages, system param, generationConfig)
@@ -20,10 +27,12 @@
  *   set of abstract methods to provide provider-specific HTTP details.
  *
  * RUNTIME MODEL VALIDATION:
+ *   An OpenRouter-style id ("openai/gpt-5.5", or an alias for one) becomes
+ *   the provider's own name, or is refused when the provider has none
+ *   (resolveModelId — pairs.js applies it when the pair graph is built).
  *   On first translate() call, the base class fetches the provider's available
  *   model list and validates the configured model against it. This catches:
  *     - Deprecated/retired model names (the exact bug we fixed twice already)
- *     - OpenRouter-format model strings used with direct providers
  *     - Models from the wrong provider (e.g., claude-* on OpenAI)
  *   The model list is cached per-process to avoid repeated API calls.
  *
@@ -34,9 +43,11 @@
  */
 
 import path from 'node:path';
-import { LLMMethod, buildSystemMessage, buildUserMessage, isUnsafeKey, inferKeyTypes } from './llm.js';
-import { loadCoachingData, findDictionaryMatches, buildCoachedSystemMessage, buildContentCoachingBlock, DEFAULT_COACHING_DIR } from './llm-coached.js';
-import { getEnvOrFileVar } from '../api-key.js';
+import { LLMMethod, buildSystemMessage, buildUserMessage, promptSettingsFor, isUnsafeKey } from './llm.js';
+import { captureRequest, isCapturing, PREVIEW_KEY } from './request-capture.js';
+import { projectGlossary } from './coaching-data.js';
+import { resolveModel } from '../models.js';
+import { getEnvOrFileVar, findEnvOrFileVar } from '../api-key.js';
 import {
   MAX_RETRIES,
   REQUEST_TIMEOUT_MS,
@@ -69,6 +80,16 @@ const MODEL_PATTERNS = {
   },
 };
 
+/**
+ * The vendor segment of the OpenRouter-style ids each direct provider serves
+ * under its own names ("google/gemini-2.5-flash" → gemini "gemini-2.5-flash").
+ */
+const DIRECT_MODEL_VENDORS = {
+  openai: 'openai',
+  anthropic: 'anthropic',
+  gemini: 'google',
+};
+
 /**
  * Per-process cache of available models per provider.
  * Keyed by provider name (e.g., 'openai'), value is a Set of model IDs
@@ -79,8 +100,7 @@ const _modelListCache = new Map();
 class DirectLLMMethod extends LLMMethod {
   constructor(options = {}) {
     super(options);
-    // Coaching data cache — avoids re-reading .champollion/coaching/<locale>.json per batch
-    this._coachingCache = new Map();
+    // (this._coachingCache — the coaching-file cache — comes from LLMMethod.)
     // Track whether we've already validated the model for this instance
     this._modelValidated = false;
   }
@@ -167,7 +187,6 @@ class DirectLLMMethod extends LLMMethod {
     const envVar = this._getApiKeyEnvVar();
     const optKey = this._getApiKeyOptionsKey();
     return options[optKey]
-      || getEnvOrFileVar(envVar)
       || getEnvOrFileVar(envVar, options.cwd);
   }
 
@@ -189,58 +208,195 @@ class DirectLLMMethod extends LLMMethod {
    */
   _getApiBaseEnvVar() { return 'OPENAI_API_BASE'; }
 
+  /**
+   * Every setting that names the endpoint base, in precedence order.
+   * OPENAI_BASE_URL is the OpenAI SDK's own name for OPENAI_API_BASE;
+   * people (and agents) reach for it first, and it used to be ignored
+   * silently — the request went to api.openai.com and failed with a 401
+   * that blamed the key (synthetic app-developer personas, 2026-10-03).
+   * @returns {string[]}
+   */
+  _getApiBaseEnvVars() {
+    const envVar = this._getApiBaseEnvVar();
+    return envVar === 'OPENAI_API_BASE' ? [envVar, 'OPENAI_BASE_URL'] : (envVar ? [envVar] : []);
+  }
+
+  /** How a message names the built-in default endpoint. */
+  _getDefaultApiBaseLabel() { return 'the built-in default'; }
+
   /**
    * Resolve the endpoint base (no /chat/completions). Precedence:
-   * options.baseUrl / this.options.baseUrl > env > subclass default.
-   * Normalizes a trailing slash and a full .../chat/completions path.
+   * options.baseUrl / this.options.baseUrl > env (see _getApiBaseEnvVars) >
+   * subclass default. Normalizes a trailing slash and a full
+   * .../chat/completions path.
    * @returns {string|null}
    */
   _resolveApiBase(options = {}) {
-    const envVar = this._getApiBaseEnvVar();
-    const fromEnv = envVar
-      ? (getEnvOrFileVar(envVar) || getEnvOrFileVar(envVar, options.cwd))
-      : null;
-    const base = options.baseUrl
-      || (this.options && this.options.baseUrl)
-      || fromEnv
-      || this._getDefaultApiBase();
-    if (!base) return null;
+    return this._resolveApiBaseSource(options).base;
+  }
+
+  /**
+   * The endpoint base AND the setting it came from, so a failure can say
+   * "could not reach http://localhost:8000/v1 (LOCAL_API_BASE in .env)"
+   * instead of a bare "fetch failed" (synthetic i18next persona, 2026-10).
+   *
+   * @param {{ baseUrl?: string, cwd?: string }} [options]
+   * @returns {{ base: string|null, from: string|null }}
+   */
+  _resolveApiBaseSource(options = {}) {
+    let base = null;
+    let from = null;
+    if (options.baseUrl) {
+      base = options.baseUrl;
+      from = 'the baseUrl option';
+    } else if (this.options && this.options.baseUrl) {
+      base = this.options.baseUrl;
+      from = 'the baseUrl setting';
+    } else {
+      for (const name of this._getApiBaseEnvVars()) {
+        const found = findEnvOrFileVar(name, options.cwd);
+        if (found) {
+          base = found.value;
+          from = found.origin === 'environment' ? name : `${name} in ${path.relative(process.cwd(), found.file) || found.origin}`;
+          break;
+        }
+      }
+      if (!base) {
+        base = this._getDefaultApiBase();
+        from = base ? this._getDefaultApiBaseLabel() : null;
+      }
+    }
+    if (!base) return { base: null, from: null };
     let b = String(base).replace(/\/+$/, '');
     if (b.endsWith('/chat/completions')) {
       b = b.slice(0, -'/chat/completions'.length);
     }
-    return b;
+    return { base: b, from };
+  }
+
+  /**
+   * Where this method sends its requests, for a failure message:
+   * "http://127.0.0.1:9/v1 (from LOCAL_API_BASE)". Origin and path only —
+   * a query string can carry a key (Gemini). null for a provider whose
+   * requests do not go through a configurable base (it has no default one:
+   * Anthropic and Gemini call their own fixed URLs).
+   * @param {object} [options]
+   * @returns {string|null}
+   */
+  _describeEndpoint(options = {}) {
+    if (!this._getDefaultApiBase()) return null;
+    let resolved;
+    try { resolved = this._resolveApiBaseSource(options); } catch { return null; }
+    if (!resolved.base) return null;
+    let shown = resolved.base;
+    try {
+      const u = new URL(resolved.base);
+      shown = `${u.origin}${u.pathname.replace(/\/+$/, '')}`;
+    } catch { /* not a URL — show it as written */ }
+    return resolved.from ? `${shown} (from ${resolved.from})` : shown;
+  }
+
+  // ── Model ids: the provider's own names, never an OpenRouter slug ──
+
+  /**
+   * The vendor segment of the OpenRouter-style ids ("openai/gpt-4o") this
+   * provider serves under its own names. null = no vendor (a local server
+   * serves whatever names it was given).
+   * @returns {string|null}
+   */
+  _getModelVendor() { return null; }
+
+  /**
+   * An id after the vendor segment, as this provider's API names it.
+   * Override where the two differ (Anthropic: dotted versions).
+   * @param {string} name
+   * @returns {string}
+   */
+  _nativeModelName(name) { return name; }
+
+  /**
+   * True when requests go to the provider's own API, so model ids are its
+   * names. False for an OpenAI-compatible gateway or server set through
+   * OPENAI_API_BASE / LOCAL_API_BASE (Groq, Together, Ollama…): any id —
+   * "meta-llama/Llama-3.3-70B" included — is that server's to judge.
+   * @returns {boolean}
+   */
+  _callsOwnApi(cwd = null) {
+    if (this._getModelVendor() === null) return false;
+    const def = this._getDefaultApiBase();
+    if (!def) return true; // a fixed URL (Anthropic, Gemini)
+    try { return this._resolveApiBase(cwd ? { cwd } : {}) === def.replace(/\/+$/, ''); } catch { return true; }
+  }
+
+  /**
+   * The model id this provider is sent, for a configured model:
+   *   - an alias from shared/model-aliases.json resolves first
+   *     ("gpt" → "openai/gpt-5.5");
+   *   - an OpenRouter-style id of THIS provider's vendor becomes its own
+   *     name ("openai/gpt-5.5" → "gpt-5.5", "anthropic/claude-haiku-4.5" →
+   *     "claude-haiku-4-5") — mirroring the harness's direct providers;
+   *   - an id of another vendor ("google/gemini-2.5-flash" for openai) has
+   *     no name here: REFUSED, naming a model this method can run. It used to
+   *     be sent as is, with a warning, and every request failed.
+   * A gateway or local server (see _callsOwnApi) gets the id as written.
+   *
+   * @param {string|null} model
+   * @param {{ from?: string, cwd?: string }} [where] - Where the id was set, for the refusal
+   *   ("from --model", "from the top-level \"model\""); cwd: the project
+   *   directory (its .env may point the method at a gateway)
+   * @returns {string|null}
+   * @throws {Error} code CHAMPOLLION_MODEL_ROUTE when there is no such model here
+   */
+  resolveModelId(model, { from = null, cwd = null } = {}) {
+    if (!model || typeof model !== 'string' || !this._callsOwnApi(cwd)) return model;
+    const vendor = this._getModelVendor();
+    const resolved = resolveModel(model);
+    const slash = resolved.indexOf('/');
+    if (slash < 0) return this._nativeModelName(resolved);
+    const idVendor = resolved.slice(0, slash);
+    const name = resolved.slice(slash + 1);
+    const plainName = /^[A-Za-z0-9._-]+$/.test(name);
+    if (idVendor === vendor && plainName) return this._nativeModelName(name);
+
+    const notes = [resolved === model ? null : `alias of ${resolved}`, from].filter(Boolean);
+    const what = `"${model}"${notes.length > 0 ? ` (${notes.join(', ')})` : ''}`;
+    const servedBy = Object.entries(DIRECT_MODEL_VENDORS).find(([, v]) => v === idVendor)?.[0] || null;
+    const label = this._getProviderLabel();
+    const ways = [`${/^[aeiou]/i.test(label) ? 'an' : 'a'} ${label} model (e.g. --model ${this._getDefaultModel()})`];
+    if (servedBy && servedBy !== this.name && plainName) ways.push(`--method ${servedBy} (its name for it: "${name}")`);
+    ways.push('--method llm to run it through OpenRouter');
+    const err = new Error(
+      `model ${what} is an OpenRouter model id — ${this.name} calls ${label} directly, `
+      + `which has no model by that name. Use ${ways.slice(0, -1).join(', ')} or ${ways[ways.length - 1]}.`
+    );
+    err.code = 'CHAMPOLLION_MODEL_ROUTE';
+    throw err;
   }
 
   /**
    * Validate the model string before making API calls.
    *
    * Checks:
-   *   1. OpenRouter-format model strings (contain '/') — wrong method
-   *   2. Model belongs to a different provider (e.g., claude-* on OpenAI)
-   *   3. Model exists in the provider's API (runtime fetch, cached)
+   *   1. Model belongs to a different provider (e.g., claude-* on OpenAI)
+   *   2. Model exists in the provider's API (runtime fetch, cached)
+   * (An OpenRouter-style id never gets here: resolveModelId maps or refuses it.)
    *
    * Logs warnings but does NOT block — the provider API will give
-   * the definitive answer. This is a DX aid, not a gate.
+   * the definitive answer. This is a DX aid, not a gate. Skipped for a
+   * gateway or local server: its names are its own, and its key must not
+   * be sent to the provider's model list.
    *
    * @param {string} model - Model ID to validate
    * @param {string} apiKey - API key for model list fetch
    */
-  async _validateModel(model, apiKey) {
+  async _validateModel(model, apiKey, cwd = null) {
     if (this._modelValidated) return;
     this._modelValidated = true;
+    if (!this._callsOwnApi(cwd)) return;
 
     const label = this._getProviderLabel();
 
-    // Check 1: OpenRouter-format model string (contains '/')
-    if (model.includes('/')) {
-      output.warn(`${label}: model "${model}" looks like an OpenRouter path.`);
-      output.warn(`Direct providers use bare model names (e.g., "${this._getDefaultModel()}").`);
-      output.warn(`To use OpenRouter models, set method to 'llm' instead.`);
-      return;
-    }
-
-    // Check 2: Model belongs to a different provider
+    // Check 1: Model belongs to a different provider
     for (const [provider, { prefixes, label: providerLabel }] of Object.entries(MODEL_PATTERNS)) {
       if (provider === this.name) continue; // skip own provider
       const matchesOther = prefixes.some(p => model.startsWith(p));
@@ -253,7 +409,7 @@ class DirectLLMMethod extends LLMMethod {
       }
     }
 
-    // Check 3: Runtime model list validation (cached per-process)
+    // Check 2: Runtime model list validation (cached per-process)
     try {
       let modelSet = _modelListCache.get(this.name);
 
@@ -316,7 +472,8 @@ class DirectLLMMethod extends LLMMethod {
   // ── Core translate() — shared across all direct LLM providers ──
 
   async translate(keys, sourceFlat, pairConfig, options) {
-    const apiKey = this._resolveApiKey(options);
+    // A request preview needs no key: it is shown, never sent.
+    const apiKey = this._resolveApiKey(options) || (isCapturing() ? PREVIEW_KEY : null);
 
     if (!apiKey) {
       output.warn(`${this._getProviderLabel()}: no API key — skipping.`);
@@ -324,33 +481,30 @@ class DirectLLMMethod extends LLMMethod {
     }
 
     const batchSize = pairConfig.batchSize || options.batchSize || DEFAULT_BATCH_SIZE;
-    const model = pairConfig.model || options.model || this._getDefaultModel();
+    // This provider's own name for the model (an OpenRouter slug is mapped
+    // or refused — pairs.js does the same when the pair graph is built).
+    // The project directory (its .env, .env.local): options.cwd, never
+    // whatever process.cwd() happens to be (the MCP server runs elsewhere).
+    const cwd = options.cwd || null;
+    const model = this.resolveModelId(pairConfig.model || options.model || this._getDefaultModel(), { cwd });
     const maxRetries = pairConfig.maxRetries ?? DEFAULT_MAX_RETRIES;
-    const langConfig = {
-      name: pairConfig.name,
-      register: pairConfig.register,
-    };
-
-    // Validate model on first call (logs warnings, does not block)
-    await this._validateModel(model, apiKey);
-
-    // Load coaching data if available (.champollion/coaching/<locale>.json)
-    const cwd = options.cwd || process.cwd();
-    const coachingDir = path.join(cwd, DEFAULT_COACHING_DIR);
-    const coaching = loadCoachingData(coachingDir, pairConfig.target, this._coachingCache);
-
-    // If coaching data exists, use the coached system message (grammar/style in system
-    // prompt for provider-level caching). Otherwise use the standard system message.
-    const systemMessage = coaching
-      ? buildCoachedSystemMessage(langConfig, coaching)
-      : buildSystemMessage(langConfig);
+    // The `llm` method's prompt, exactly (llm.js promptSettingsFor): only
+    // the transport is this provider's.
+    const langConfig = promptSettingsFor(pairConfig);
+
+    // Validate model on first call (logs warnings, does not block). It lists
+    // the provider's models over the network — not while showing a request.
+    if (!isCapturing()) await this._validateModel(model, apiKey, cwd);
+
+    const systemMessage = buildSystemMessage(langConfig);
+    // The project glossary: each batch is told the terms it contains.
+    const glossary = projectGlossary(pairConfig, options, this._coachingCache);
     const allTranslated = {};
 
-    // Wrap the batch function to inject dictionary hints when coaching is active.
     // Thread the resolved temperature so _callProviderBatch doesn't need pairConfig.
     const resolvedTemperature = pairConfig.temperature ?? DEFAULT_TEMPERATURE;
     const descriptions = options.descriptions || null;
-    const batchFn = (batch, opts) => this._callProviderBatch(batch, { ...opts, apiKey, model, coaching, temperature: resolvedTemperature, descriptions });
+    const batchFn = (batch, opts) => this._callProviderBatch(batch, { ...opts, apiKey, model, glossary, temperature: resolvedTemperature, descriptions, cwd });
 
     const batchChunks = [];
     for (let i = 0; i < keys.length; i += batchSize) {
@@ -389,29 +543,23 @@ class DirectLLMMethod extends LLMMethod {
       return null;
     }
 
-    const model = pairConfig.model || options.model || this._getDefaultModel();
-
-    // Prepend coaching context (grammar/style rules) to content prompts when available.
-    // Dictionary matching is skipped for freeform content — it's too unpredictable.
-    const cwd = options.cwd || process.cwd();
-    const coachingDir = path.join(cwd, DEFAULT_COACHING_DIR);
-    const coaching = loadCoachingData(coachingDir, pairConfig.target, this._coachingCache);
-    let augmentedPrompt = prompt;
-    if (coaching) {
-      const block = buildContentCoachingBlock(coaching);
-      if (block) {
-        augmentedPrompt = block + '\n\n' + prompt;
-      }
-    }
+    const cwd = options.cwd || null;
+    const model = this.resolveModelId(pairConfig.model || options.model || this._getDefaultModel(), { cwd });
+
+    // The content prompt is built by the lane (lib/content.js,
+    // lib/segment.js), the same for every method, and sent as is — exactly
+    // as `llm` sends it. Coaching (grammar rules, style notes) is
+    // llm-coached's: its translateContent prepends it for any provider.
 
     // Round 1: standard timeout (2× base = 60s)
     const result = await this._callProviderDirect({
-      prompt: augmentedPrompt,
+      prompt,
       apiKey,
       model,
       temperature: pairConfig.temperature ?? DEFAULT_TEMPERATURE,
       timeoutMs: REQUEST_TIMEOUT_MS * 2,
       label: `${this._getProviderLabel()} Content`,
+      cwd,
     });
 
     if (result) return result;
@@ -422,41 +570,27 @@ class DirectLLMMethod extends LLMMethod {
     await sleep(10_000);
 
     return this._callProviderDirect({
-      prompt: augmentedPrompt,
+      prompt,
       apiKey,
       model,
       temperature: pairConfig.temperature ?? DEFAULT_TEMPERATURE,
       timeoutMs: REQUEST_TIMEOUT_MS * 4,
       label,
+      cwd,
     });
   }
 
-  // ── Shared batch call — builds user message with coaching hints ──
+  // ── Shared batch call — the `llm` user message, this provider's transport ──
 
   async _callProviderBatch(toTranslate, options) {
-    const { apiKey, model, batchNum, systemMessage, coaching, temperature } = options;
-
-    // Build user message — inject dictionary term matches when coaching is active.
-    // Dictionary hints go in the user message (per-batch) rather than the system
-    // message (cached) because they're specific to the current batch's source values.
-    let prompt;
-    if (coaching && coaching.dictionary) {
-      const dictHints = findDictionaryMatches(toTranslate, coaching.dictionary);
-      const typeHints = inferKeyTypes(toTranslate);
-      let userMessage = '';
-      if (dictHints.length > 0) {
-        userMessage += 'REQUIRED TERMINOLOGY (use these exact translations):\n';
-        userMessage += dictHints.map(h => `  • "${h.term}" → "${h.translation}"`).join('\n');
-        userMessage += '\n\n';
-      }
-      if (typeHints.length > 0) {
-        userMessage += `UI context for these keys:\n${typeHints.join('\n')}\n\n`;
-      }
-      userMessage += JSON.stringify(toTranslate, null, 2);
-      prompt = userMessage;
-    } else {
-      prompt = buildUserMessage(toTranslate, options.descriptions || undefined);
-    }
+    const { apiKey, model, batchNum, systemMessage, temperature } = options;
+
+    // The user message every LLM method sends (llm.js buildUserMessage):
+    // the glossary terms this batch contains, then the per-key instructions
+    // (plural forms, ICU categories, gettext context, a gate retry's
+    // feedback), then the batch. Glossary hints go here (per batch), not in
+    // the cached system message, because they depend on the batch's values.
+    const prompt = buildUserMessage(toTranslate, options.descriptions || undefined, options.glossary || null);
 
     const label = this._getProviderLabel();
     const content = await this._callProviderDirect({
@@ -467,6 +601,7 @@ class DirectLLMMethod extends LLMMethod {
       temperature: temperature ?? DEFAULT_TEMPERATURE,
       label: `${label} Batch ${batchNum}`,
       isJsonMode: true,
+      cwd: options.cwd || null,
     });
 
     if (!content) return null;
@@ -498,9 +633,16 @@ class DirectLLMMethod extends LLMMethod {
     timeoutMs = REQUEST_TIMEOUT_MS,
     label,
     isJsonMode = false,
+    cwd = null,
   }) {
     label = label || this._getProviderLabel();
 
+    // `sync --dry --show-prompt`: hand over the exact request, send nothing.
+    if (isCapturing()) {
+      captureRequest(this._buildApiRequest({ prompt, systemMessage, apiKey, model, temperature, isJsonMode, cwd }));
+      return null;
+    }
+
     for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
       try {
         const controller = new AbortController();
@@ -513,6 +655,7 @@ class DirectLLMMethod extends LLMMethod {
           model,
           temperature,
           isJsonMode,
+          cwd,
         });
 
         const response = await fetch(url, {
@@ -562,7 +705,10 @@ class DirectLLMMethod extends LLMMethod {
 
       } catch (err) {
         const isTimeout = err.name === 'AbortError';
-        const errLabel = isTimeout ? 'timeout' : err.message;
+        // A connection failure is "fetch failed" with the real reason
+        // (ECONNREFUSED, ENOTFOUND…) on err.cause.
+        const cause = err && err.cause && (err.cause.code || err.cause.message);
+        const errLabel = isTimeout ? 'timeout' : `${err.message}${cause && !String(err.message).includes(cause) ? ` (${cause})` : ''}`;
 
         if (attempt < MAX_RETRIES) {
           const delay = getBackoffDelay(attempt);
@@ -571,7 +717,9 @@ class DirectLLMMethod extends LLMMethod {
           continue;
         }
 
-        output.error(`${label} failed: ${errLabel}`);
+        // Say WHERE it tried, and which setting chose that address.
+        const endpoint = this._describeEndpoint(cwd ? { cwd } : {});
+        output.error(`${label} failed: ${errLabel}${endpoint ? ` — ${isTimeout ? 'no answer from' : 'could not reach'} ${endpoint}` : ''}`);
         return null;
       }
     }
@@ -582,5 +730,6 @@ class DirectLLMMethod extends LLMMethod {
 export {
   DirectLLMMethod,
   MODEL_PATTERNS,
+  DIRECT_MODEL_VENDORS,
   _modelListCache,
 };