bob-plugin-ollama-translator: Instructions file for Codex

Repository Guidelines

Bob (macOS translation app) plugin exposing AI translation/interpretation over any OpenAI-compatible chat-completions endpoint. CLAUDE.md documents build commands and the provider-addition checklist — this file complements it; follow both.

Project Overview

• Single-purpose Bob plugin (identifier bob-plugin-ollama-translator): word/text translation (translate pattern) and encyclopedia-style explanation (interpret pattern), streamed via SSE.
• Supports 8 providers — ollama, deepseek, openai, grok, claude, gemini, zhipu, other — all through the OpenAI chat-completions shape (Claude included, via api.anthropic.com/v1/...).
• Plugin version lives in public/info.json (manifest, currently ahead of package.json — release only bumps info.json).

Architecture & Data Flow

Runtime is Bob's injected JavaScriptCore globals — no Node APIs, no fetch. Two ambient globals: $option (declared locally in src/types.d.ts, ~25 keys) and $http (from @bob-translate/types).

Bob → src/main.ts (exports translate + supportLanguages)
    → src/translate.ts (orchestrator)
        ├─ src/service.ts    resolve provider/url/apikey/model from $option
        ├─ src/precheck.ts   ALL config validation (base URL/model/language) — before the cache
        ├─ src/cache.ts      in-memory Map, FIFO-evict at 100
        ├─ src/params.ts     build chat-completions body (stream:true)
        │    ├─ src/prompt.ts  system/user prompts, {var} templates
        │    └─ src/wordlookup.ts  word-lookup decision (predicate + qwen-mt exemption), detail tiers, dict prompts
        ├─ src/result.ts     frame streams/completions (finish suffixes, <think> handling)
        ├─ $http.streamRequest (Bob's HTTP, Bearer auth, SSE)
        └─ src/parser.ts     eventsource-parser → OpenAI chunks
             → query.onStream() per chunk → query.onCompletion() at finish

Key patterns an assistant must preserve:

• Never throw across the Bob boundary. Every failure routes through handleGeneralError(query, error) (src/util.ts) → query.onCompletion({error}). ServiceError types: param, api, secretKey, unsupportedLanguage.
• Callback-based, not await-based. translate() is async but awaits nothing; completion is fire-once via a completed flag guard.
• Streaming only. $http.streamRequest + stream: true; no non-streaming path. finish_reason of stop or a known suffix completes; anything else keeps streaming. Invalid API keys are detected by regex on stream text (/Invalid token/i).
• Results always carry thinkInfo: {content: "", splitThinkTag: true} so Bob strips <think> reasoning blocks. Word lookup (ADR-003) is the deliberate exception: thinkInfo appears only when the model produced reasoning, with splitThinkTag: false (tags already stripped in dict.ts). Delta-style reasoning (reasoning_content/reasoning on the chunk delta — DeepSeek R1, QwQ) is captured in translate.ts, streamed live via onStream frames on both paths, and re-wrapped as a <think> block at completion, so both render paths and the cache see one format. Capture is unconditional — the thinking menu is display-side (rendering hides reasoning when off), so cached entries replay thinking after re-enabling.
• Provider registry is closed. Provider union + PROVIDERS + the keyed-literal tables (SERVICE_BASE_URLS, API_KEY_OPTIONS, MODEL_OPTIONS) in src/service.ts are the single source of truth; adding a provider means touching those plus public/info.json options and src/types.d.ts — follow the 5-step checklist in CLAUDE.md. ollama (keyless) and other (user URL) are intentionally asymmetric (Partial<Record<...>>).
• Word lookup is decided once. src/wordlookup.ts owns the predicate (translate pattern + single English token), the qwen-mt exemption, the wordDetail tiers and the JSON dict prompts; params.ts calls lookupEnabled(query, model) once and passes the boolean down as a fact. Prompts, framing and the cache never re-derive it.
• Qwen MT special case: model name matching /qwen-mt/ bypasses prompt.ts entirely — single user message + translation_options instead of prompts. Don't "fix" prompts assuming they always apply.
• Config validation has one seam: preCheck(query, service) (src/precheck.ts) owns every config check and runs before the cache lookup — the cache never masks a broken config, and translate.ts keeps no guards of its own. Error precedence: base URL → custom model → target language.
• Cache key uses query.from/query.to while the rest of the code uses detectFrom/detectTo — different fields, don't unify casually.
• langMap (bob→api codes) is used only for validation in precheck.ts; outgoing prompts/target_lang get raw Bob codes.