@strav/brain 1.0.0-alpha.31 → 1.0.0-alpha.34

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@strav/brain",
-  "version": "1.0.0-alpha.31",
+  "version": "1.0.0-alpha.34",
   "description": "Strav AI module — unified Provider interface, BrainManager, threads, prompt caching, tools / agents / MCP. Anthropic + OpenAI providers; Gemini / DeepSeek follow.",
   "type": "module",
   "main": "./src/index.ts",
@@ -9,6 +9,7 @@
     ".": "./src/index.ts",
     "./mcp": "./src/mcp/index.ts",
     "./persistence": "./src/persistence/index.ts",
+    "./translate": "./src/translate/index.ts",
     "./zod": "./src/zod/index.ts"
   },
   "files": [
@@ -25,8 +26,8 @@
     "@anthropic-ai/sdk": "^0.100.0",
     "@google/genai": "^2.7.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "@strav/database": "1.0.0-alpha.31",
-    "@strav/kernel": "1.0.0-alpha.31",
+    "@strav/database": "1.0.0-alpha.34",
+    "@strav/kernel": "1.0.0-alpha.34",
     "openai": "^6.0.0"
   },
   "peerDependencies": {

package/src/translate/index.ts

@@ -0,0 +1,19 @@
+// Public API of `@strav/brain/translate`.
+//
+// LLM-backed translation primitive on top of `BrainManager`. Sonnet-
+// uniform by default (tier='balanced'), with parallel fan-out across
+// target languages, JSON-schema constrained output, prompt caching on
+// the system prompt, and a process-local LRU for repeat strings.
+
+export { TranslateCache, cacheKey } from './translate_cache.ts'
+export {
+  type TranslateConfig,
+  TranslatorProvider,
+} from './translate_provider.ts'
+export {
+  type BatchTranslateOptions,
+  DEFAULT_SYSTEM_PROMPT,
+  type TranslateOptions,
+  Translator,
+  type TranslatorOptions,
+} from './translator.ts'

package/src/translate/translate_cache.ts

@@ -0,0 +1,78 @@
+/**
+ * `TranslateCache` — tiny LRU keyed on `(model, from, to, text)`. Keeps
+ * repeated translations of the same phrase from hitting the model
+ * twice during a single fan-out (or during a batch where the same
+ * field value recurs across drafts).
+ *
+ * Intentionally in-memory + process-local. Apps that want persistent
+ * caching (e.g. across job retries / restarts) wrap their own
+ * Repository around `Translator` and call into it themselves; this
+ * cache exists to make the hot path cheap, not to be a system of
+ * record.
+ *
+ * Eviction is FIFO via Map insertion order — re-inserting on hit
+ * (`delete`+`set`) bumps the entry to the end so cold entries fall
+ * off first. `capacity: 0` disables the cache entirely.
+ */
+
+export class TranslateCache {
+  private readonly store = new Map<string, string>()
+
+  constructor(readonly capacity: number) {}
+
+  get(key: string): string | undefined {
+    if (this.capacity === 0) return undefined
+    const hit = this.store.get(key)
+    if (hit === undefined) return undefined
+    // Bump recency.
+    this.store.delete(key)
+    this.store.set(key, hit)
+    return hit
+  }
+
+  set(key: string, value: string): void {
+    if (this.capacity === 0) return
+    if (this.store.has(key)) this.store.delete(key)
+    this.store.set(key, value)
+    if (this.store.size > this.capacity) {
+      // Evict the oldest entry (the first key in insertion order).
+      const oldest = this.store.keys().next().value
+      if (oldest !== undefined) this.store.delete(oldest)
+    }
+  }
+
+  clear(): void {
+    this.store.clear()
+  }
+
+  get size(): number {
+    return this.store.size
+  }
+}
+
+/**
+ * Stable cache key for a single (text → language) translation.
+ * Inputs are joined with a separator that can't appear in BCP-47
+ * codes; the text is hashed (FNV-1a 32-bit) to keep keys bounded.
+ *
+ * Collision risk on FNV-1a 32-bit is non-zero but acceptable for a
+ * best-effort cache: the cost of a collision is one extra LLM call
+ * the next time the loser's text hashes to the same key.
+ */
+export function cacheKey(input: {
+  model: string
+  from: string | undefined
+  to: string
+  text: string
+}): string {
+  return `${input.model}|${input.from ?? 'auto'}|${input.to}|${fnv1a32(input.text)}`
+}
+
+function fnv1a32(text: string): string {
+  let hash = 0x811c9dc5
+  for (let i = 0; i < text.length; i++) {
+    hash ^= text.charCodeAt(i)
+    hash = (hash + ((hash << 1) + (hash << 4) + (hash << 7) + (hash << 8) + (hash << 24))) >>> 0
+  }
+  return hash.toString(16).padStart(8, '0')
+}

package/src/translate/translate_provider.ts

@@ -0,0 +1,46 @@
+/**
+ * `TranslatorProvider` — `ServiceProvider` that binds a default
+ * `Translator` singleton resolved against the registered
+ * `BrainManager`.
+ *
+ * Reads `config.brain.translate` (optional) for defaults — provider,
+ * tier, model, cacheSize. Apps that need multiple translators with
+ * different defaults (e.g. one for headlines, one for body) skip the
+ * provider and construct `new Translator({ brain, ... })` directly.
+ */
+
+import { type Application, ConfigRepository, ServiceProvider } from '@strav/kernel'
+import { BrainManager } from '../brain_manager.ts'
+import type { ModelTier } from '../types.ts'
+import { Translator } from './translator.ts'
+
+export interface TranslateConfig {
+  provider?: string
+  tier?: ModelTier
+  model?: string
+  systemPrompt?: string
+  cacheSize?: number
+  cache?: boolean
+}
+
+export class TranslatorProvider extends ServiceProvider {
+  override readonly name = 'brain.translate'
+  override readonly dependencies = ['brain']
+
+  override register(app: Application): void {
+    app.singleton(Translator, (c) => {
+      const brain = c.resolve(BrainManager)
+      const cfg =
+        (c.resolve(ConfigRepository).get('brain.translate') as TranslateConfig | undefined) ?? {}
+      return new Translator({
+        brain,
+        ...(cfg.provider !== undefined ? { provider: cfg.provider } : {}),
+        ...(cfg.tier !== undefined ? { tier: cfg.tier } : {}),
+        ...(cfg.model !== undefined ? { model: cfg.model } : {}),
+        ...(cfg.systemPrompt !== undefined ? { systemPrompt: cfg.systemPrompt } : {}),
+        ...(cfg.cacheSize !== undefined ? { cacheSize: cfg.cacheSize } : {}),
+        ...(cfg.cache !== undefined ? { cache: cfg.cache } : {}),
+      })
+    })
+  }
+}

package/src/translate/translator.ts

@@ -0,0 +1,271 @@
+/**
+ * `Translator` — LLM-backed translation primitive on top of
+ * `BrainManager`. Sonnet-uniform by default (`tier: 'balanced'`),
+ * which routes to `claude-sonnet-4-6` on the Anthropic driver — apps
+ * override with `options.model` or `options.provider` per call.
+ *
+ * Two entry points:
+ *
+ *   - `translate(text, { to: [...] })` — fan-out one string into
+ *     every target language in parallel. Returns
+ *     `{ [langCode]: translated }`.
+ *
+ *   - `translateBatch(fields, { to: [...] })` — translate a
+ *     fixed-shape object (`{ title, body }`) into every target
+ *     language. Each target language runs in parallel; within a
+ *     language, all fields land in one model call so the model
+ *     keeps shared context (a `title` and `body` translated
+ *     together stay tonally consistent).
+ *
+ * Cross-cutting:
+ *
+ *   - **Structured output.** Uses `brain.generate(input, schema)`
+ *     with a JSON Schema that locks the response to the expected
+ *     keys, so models never sneak in commentary or transliterations.
+ *
+ *   - **Prompt caching.** The system prompt is identical across
+ *     every call (per-language hints ride in the user message), so
+ *     Anthropic prompt caching kicks in once the cache window warms.
+ *     Set `cache: false` on the constructor to opt out.
+ *
+ *   - **In-memory cache.** Identical `(model, from, to, text)`
+ *     tuples are served from a process-local LRU (default 1000
+ *     entries) — see `TranslateCache`. Pass `cacheSize: 0` to
+ *     disable.
+ *
+ *   - **Source language auto-detect.** Omit `from` and the user
+ *     message tells the model to detect the source. Apps that know
+ *     the source pass it explicitly for marginal quality + token
+ *     savings.
+ */
+
+import type { BrainManager } from '../brain_manager.ts'
+import type { OutputSchema } from '../output_schema.ts'
+import type { ChatOptions, ModelTier } from '../types.ts'
+import { cacheKey, TranslateCache } from './translate_cache.ts'
+
+export interface TranslatorOptions {
+  brain: BrainManager
+  /** Brain provider name. Defaults to the configured `brain.default`. */
+  provider?: string
+  /** Brain tier sugar — overridden by `model`. Default `'balanced'` (Sonnet on Anthropic per ADR-0004-style routing). */
+  tier?: ModelTier
+  /** Explicit model id. Wins over `tier`. */
+  model?: string
+  /** Override the system prompt. Apps localising the prompt itself reach for this. */
+  systemPrompt?: string
+  /** LRU capacity for the translation cache. `0` disables. Default `1000`. */
+  cacheSize?: number
+  /** Enable Anthropic prompt caching on the system prompt. Default `true`. Non-Anthropic providers ignore. */
+  cache?: boolean
+}
+
+export interface TranslateOptions {
+  /** Target BCP-47 language codes (`'th'`, `'zh-Hant'`, `'ja'`). */
+  to: readonly string[]
+  /** Source BCP-47 code. Omit to ask the model to detect. */
+  from?: string
+  /** Per-call model override (wins over the constructor's tier/model). */
+  model?: string
+  /** Per-call provider override. */
+  provider?: string
+  /** Cancellation signal — forwarded to every parallel `brain.generate` call. */
+  signal?: AbortSignal
+}
+
+export type BatchTranslateOptions = TranslateOptions
+
+/**
+ * Default system prompt — kept stable across every call so prompt
+ * caching can warm. Per-call specifics (source/target language,
+ * text, field shape) ride in the user message.
+ */
+export const DEFAULT_SYSTEM_PROMPT = `You are a translation engine.
+
+The user supplies (a) a source-language code (or "auto"), (b) a target BCP-47 language code, and (c) the source text or a JSON object of named source fields. Translate the source into the target language and output ONLY the translation in the required JSON shape.
+
+Rules:
+- Output ONLY the translated text in the requested JSON shape. Do not add explanations, notes, alternatives, or transliterations.
+- Preserve Markdown, HTML tags, links, mentions, hashtags, code spans, and emoji exactly as in the source.
+- Keep numbers, dates, currency symbols, and proper nouns recognisable in the target locale; do not invent translations for brand names.
+- If the source is already in the target language, output it unchanged.
+- For batch translations, every requested field must appear in the output — never drop a field.`
+
+export class Translator {
+  private readonly brain: BrainManager
+  private readonly provider: string | undefined
+  private readonly tier: ModelTier
+  private readonly explicitModel: string | undefined
+  private readonly systemPrompt: string
+  private readonly cache: TranslateCache
+  private readonly promptCache: boolean
+
+  constructor(options: TranslatorOptions) {
+    this.brain = options.brain
+    this.provider = options.provider
+    this.tier = options.tier ?? 'balanced'
+    this.explicitModel = options.model
+    this.systemPrompt = options.systemPrompt ?? DEFAULT_SYSTEM_PROMPT
+    this.cache = new TranslateCache(options.cacheSize ?? 1000)
+    this.promptCache = options.cache ?? true
+  }
+
+  /**
+   * Translate one string into every target language in parallel.
+   * Returns a `{ [lang]: translated }` map containing one entry per
+   * code in `options.to`. Calls fan out concurrently; a single
+   * thrown call rejects the whole `Promise.all`.
+   */
+  async translate(
+    text: string,
+    options: TranslateOptions,
+  ): Promise<Record<string, string>> {
+    if (options.to.length === 0) return {}
+
+    const results = await Promise.all(
+      options.to.map(async (lang) => {
+        const translated = await this.translateOne(text, lang, options)
+        return [lang, translated] as const
+      }),
+    )
+    return Object.fromEntries(results)
+  }
+
+  /**
+   * Translate a fixed-shape object of fields into every target
+   * language. Each target language runs in parallel; within a
+   * language, all fields are translated in one model call so context
+   * is shared.
+   *
+   * Returns `{ [lang]: { ...fields } }`. The shape of every per-
+   * language object matches the input keys exactly — missing keys
+   * are treated as a hard error (the model is instructed to never
+   * drop a field) and surface as a `BrainError` from `generate`'s
+   * schema parser.
+   */
+  async translateBatch<T extends Record<string, string>>(
+    fields: T,
+    options: BatchTranslateOptions,
+  ): Promise<Record<string, T>> {
+    if (options.to.length === 0) return {}
+    const fieldNames = Object.keys(fields) as Array<keyof T & string>
+    if (fieldNames.length === 0) return Object.fromEntries(options.to.map((l) => [l, {} as T]))
+
+    const results = await Promise.all(
+      options.to.map(async (lang) => {
+        const translated = await this.translateBatchOne(fields, fieldNames, lang, options)
+        return [lang, translated] as const
+      }),
+    )
+    return Object.fromEntries(results)
+  }
+
+  /** Drop the in-memory LRU. Useful in tests to keep cases isolated. */
+  clearCache(): void {
+    this.cache.clear()
+  }
+
+  // ─── internals ──────────────────────────────────────────────────────
+
+  private resolvedModel(per: TranslateOptions): string {
+    return per.model ?? this.explicitModel ?? this.tier
+  }
+
+  private buildChatOptions(per: TranslateOptions): ChatOptions {
+    const opts: ChatOptions = {
+      system: this.promptCache
+        ? { text: this.systemPrompt, cache: true }
+        : this.systemPrompt,
+    }
+    if (per.model) opts.model = per.model
+    else if (this.explicitModel) opts.model = this.explicitModel
+    else opts.tier = this.tier
+    if (per.provider ?? this.provider) opts.provider = (per.provider ?? this.provider)!
+    if (per.signal) opts.signal = per.signal
+    return opts
+  }
+
+  private async translateOne(
+    text: string,
+    lang: string,
+    per: TranslateOptions,
+  ): Promise<string> {
+    const model = this.resolvedModel(per)
+    const key = cacheKey({ model, from: per.from, to: lang, text })
+    const hit = this.cache.get(key)
+    if (hit !== undefined) return hit
+
+    const schema: OutputSchema<{ translation: string }> = {
+      name: 'translation',
+      description: `Translation of the source text into ${lang}.`,
+      jsonSchema: {
+        type: 'object',
+        properties: { translation: { type: 'string' } },
+        required: ['translation'],
+        additionalProperties: false,
+      },
+    }
+
+    const userMessage = `SOURCE_LANGUAGE: ${per.from ?? 'auto'}\nTARGET_LANGUAGE: ${lang}\nTEXT:\n${text}`
+
+    const result = await this.brain.generate(userMessage, schema, this.buildChatOptions(per))
+    const translated = result.value.translation
+    this.cache.set(key, translated)
+    return translated
+  }
+
+  private async translateBatchOne<T extends Record<string, string>>(
+    fields: T,
+    fieldNames: readonly (keyof T & string)[],
+    lang: string,
+    per: BatchTranslateOptions,
+  ): Promise<T> {
+    const model = this.resolvedModel(per)
+
+    // Per-field cache: check every field; only call the model when at
+    // least one field is missing. The single model call still covers
+    // all fields (we don't sub-call per missing field — the context
+    // gain from a single call outweighs the extra translation work).
+    const fromCache: Partial<Record<string, string>> = {}
+    let allHit = true
+    for (const name of fieldNames) {
+      const hit = this.cache.get(
+        cacheKey({ model, from: per.from, to: lang, text: fields[name]! }),
+      )
+      if (hit === undefined) {
+        allHit = false
+      } else {
+        fromCache[name] = hit
+      }
+    }
+    if (allHit) return fromCache as T
+
+    const properties: Record<string, unknown> = {}
+    for (const name of fieldNames) properties[name] = { type: 'string' }
+    const schema: OutputSchema<T> = {
+      name: 'batch_translation',
+      description: `Translation of every named field into ${lang}.`,
+      jsonSchema: {
+        type: 'object',
+        properties,
+        required: [...fieldNames],
+        additionalProperties: false,
+      },
+    }
+
+    const fieldsBlock = fieldNames
+      .map((n) => `- ${n}: ${JSON.stringify(fields[n]!)}`)
+      .join('\n')
+    const userMessage = `SOURCE_LANGUAGE: ${per.from ?? 'auto'}\nTARGET_LANGUAGE: ${lang}\nFIELDS:\n${fieldsBlock}\n\nOutput a JSON object with these exact keys: ${fieldNames.join(', ')}.`
+
+    const result = await this.brain.generate(userMessage, schema, this.buildChatOptions(per))
+    const translated = result.value
+    for (const name of fieldNames) {
+      this.cache.set(
+        cacheKey({ model, from: per.from, to: lang, text: fields[name]! }),
+        translated[name]!,
+      )
+    }
+    return translated
+  }
+}