@startsimpli/llm 0.4.16 → 0.4.18

package/src/translation/types.ts

@@ -0,0 +1,300 @@
+/**
+ * The translation engine's CONTRACT (bd startsim-ob4d, RED).
+ *
+ * Types only. The behaviour is stubbed in `./index` and unimplemented on
+ * purpose — the tests in `./__tests__` are written against this surface first
+ * and are expected to fail until bd startsim-h1q8 (GREEN) implements it.
+ *
+ * THE THREE DESIGN DECISIONS THIS FILE ENCODES, so a reader does not have to
+ * rediscover them from the tests:
+ *
+ *   `docs/design/translation/startsim-yfot-…` — the batch is N segments in ONE
+ *   prompt with echoed ids, cut by CHARACTER budget, and the id-echo contract
+ *   is exact: the returned id set equals the requested id set.
+ *
+ *   `docs/design/translation/startsim-r9q8-…` — quality is proven by comparing
+ *   SOURCE TO OUTPUT, never by judging the output's language. Hence
+ *   `MechanicalChecks`: glossary adherence, do-not-translate, numeric fidelity.
+ *
+ *   `docs/design/translation/startsim-bfem-…` — assert invariants, never
+ *   wording. `temperature: 0` is not available on the default model, so nothing
+ *   here may assume a reproducible string.
+ *
+ * NO LOCALE IS NAMED ANYWHERE IN THIS PACKAGE. `sourceLocale`/`targetLocale`
+ * are opaque BCP-47 strings supplied per request. A branch on a locale code is
+ * the leak `startsim-jb1z` bans, and the two-locale fixture set exists to catch
+ * one.
+ */
+
+import type { ILLMProvider } from '../providers/interface';
+
+/** A BCP-47 tag. Data, never a branch. */
+export type Locale = string;
+
+/**
+ * One unit of text to translate.
+ *
+ * `id` IS OPAQUE. The engine assigns nothing, parses nothing out of it, and
+ * round-trips it byte-for-byte. The caller owns segmentation, so the caller
+ * owns the naming.
+ */
+export interface TranslationSegment {
+  id: string;
+  text: string;
+}
+
+/**
+ * A term the client has ruled on.
+ *
+ * `binding` means the approved `target` MUST appear when `source` occurred.
+ * `doNotTranslate` means `source` must survive VERBATIM — brand names, product
+ * names, legal entity names — and `target` is ignored for those.
+ */
+export interface GlossaryTerm {
+  source: string;
+  target: string;
+  binding: boolean;
+  doNotTranslate?: boolean;
+}
+
+/** A previously approved pair, reusable by exact match. */
+export interface MemoryUnit {
+  sourceText: string;
+  targetText: string;
+  sourceLocale: Locale;
+  targetLocale: Locale;
+}
+
+export interface TranslationRequest {
+  segments: TranslationSegment[];
+  sourceLocale: Locale;
+  targetLocale: Locale;
+  /** Only the terms occurring in THIS batch are injected. See `renderTranslatePrompt`. */
+  glossary?: readonly GlossaryTerm[];
+  /**
+   * Approved pairs, used two ways: an EXACT source match is served without a
+   * provider call at all, and the remainder ride along as labelled examples.
+   *
+   * THE CALLER BOUNDS THIS. The engine injects what it is given, so handing it a
+   * whole translation memory puts a whole translation memory in every prompt —
+   * the failure the glossary is filtered to avoid. `startsim-jb1z` specs the
+   * store side as `nearest(segmentText, targetLocale, limit)` for exactly this
+   * reason; the engine does not re-rank, because it has no retriever.
+   */
+  memory?: readonly MemoryUnit[];
+}
+
+/**
+ * What produced a unit. Without it, a quality regression after a route change
+ * is unattributable (`startsim-jb1z`'s artifact model).
+ */
+export interface TranslationProvenance {
+  provider: string;
+  model: string;
+  promptVersion: string;
+}
+
+/** One term's verdict. `present` is a substring question, not a judgement. */
+export interface TermCheck {
+  term: string;
+  present: boolean;
+}
+
+/**
+ * The gates that run on EVERY batch in production, not only in tests
+ * (`startsim-r9q8`). All are computed source-to-output and need no reader of
+ * the target language.
+ */
+export interface MechanicalChecks {
+  glossaryAdherence: TermCheck[];
+  doNotTranslate: TermCheck[];
+  /** Numbers, dates and percentages in the source that are absent from the target. */
+  missingNumerics: string[];
+  /** False when any binding term, do-not-translate string or numeric is missing. */
+  ok: boolean;
+}
+
+export interface TranslatedSegment {
+  id: string;
+  /**
+   * Storage form. Carries NO bidi isolate characters — isolation happens at
+   * render time (`packages/i18n/src/bidi.ts`), so a stored string stays
+   * comparable.
+   */
+  targetText: string;
+  provenance: TranslationProvenance;
+  /** True when served from memory, which means no provider call was made. */
+  fromMemory: boolean;
+  checks: MechanicalChecks;
+}
+
+export type FailureReason =
+  | 'missing_id'
+  | 'empty_text'
+  | 'mechanical_check'
+  | 'provider_error';
+
+export interface TranslationFailure {
+  id: string;
+  reason: FailureReason;
+}
+
+export interface TranslationResult {
+  translated: TranslatedSegment[];
+  failed: TranslationFailure[];
+  /** Ids re-queued individually after the batch response omitted them. */
+  requeued: string[];
+  /** Provider calls actually made. A memory-only request must report 0. */
+  providerCalls: number;
+}
+
+// ---------------------------------------------------------------------------
+//  the envelope
+// ---------------------------------------------------------------------------
+
+/**
+ * The parse of one provider response, per `startsim-yfot`'s id-echo contract.
+ *
+ * A MISSING id is survivable — it fails only its own segment, which is
+ * re-queued. An UNKNOWN or DUPLICATE id is not: the model has attributed text
+ * to a segment that did not ask for it, and in a product whose selling point is
+ * that one client's material never appears against another's, that is a
+ * correctness alarm. Never map an unknown id positionally.
+ */
+export type EnvelopeRejection = 'unknown_id' | 'duplicate_id' | 'malformed';
+
+export interface EnvelopeAccepted {
+  ok: true;
+  segments: TranslationSegment[];
+  /** Requested ids the response did not carry. Re-queued individually. */
+  missing: string[];
+  /** Present ids whose text was blank — a failure, never an empty translation. */
+  empty: string[];
+}
+
+export interface EnvelopeRejected {
+  ok: false;
+  reason: EnvelopeRejection;
+  /** The offending ids, for the operator. NEVER the response text. */
+  offendingIds: string[];
+}
+
+export type EnvelopeResult = EnvelopeAccepted | EnvelopeRejected;
+
+// ---------------------------------------------------------------------------
+//  structure
+// ---------------------------------------------------------------------------
+
+/**
+ * A document as the CALLER models it. Structure never enters the model
+ * (`startsim-jb1z`), so the engine segments and reassembles and the round trip
+ * is deterministic by construction.
+ *
+ * `kind` is free-form — `heading`, `paragraph`, `list_item`, `table_cell`,
+ * `code`. The engine does not interpret it; it carries it through.
+ */
+export interface DocumentNode {
+  kind: string;
+  /** Leaf text. Absent on a container. */
+  text?: string;
+  children?: DocumentNode[];
+  /** Nodes flagged here are carried through untranslated (product codes, ids). */
+  translatable?: boolean;
+}
+
+export interface StructuredDocument {
+  nodes: DocumentNode[];
+}
+
+/**
+ * The extraction result: the translatable leaves, plus whatever the
+ * reassembler needs to put them back. The skeleton is opaque to the caller.
+ */
+export interface SegmentedDocument {
+  segments: TranslationSegment[];
+  skeleton: StructuredDocument;
+}
+
+// ---------------------------------------------------------------------------
+//  batching
+// ---------------------------------------------------------------------------
+
+/**
+ * Provisional, and explicitly so (`startsim-yfot`, Unverified). 4,000 chars sits
+ * below the MEASURED 6,000-char extraction budget because translation output
+ * scales with input and extraction's does not; 25 segments caps the id-matching
+ * burden on a page of one-line table cells.
+ *
+ * These are to be REPLACED by a measurement of translation itself.
+ */
+export interface BatchLimits {
+  maxCharsPerBatch: number;
+  maxSegmentsPerBatch: number;
+}
+
+export const DEFAULT_BATCH_LIMITS: BatchLimits = {
+  maxCharsPerBatch: 4_000,
+  maxSegmentsPerBatch: 25,
+};
+
+// ---------------------------------------------------------------------------
+//  routing
+// ---------------------------------------------------------------------------
+
+/**
+ * The retention posture, which is what picks the provider — not the model's
+ * quality (`startsim-hopl`, `startsim-yfot`).
+ *
+ * `walled` carries the paying client's confidential material and CANNOT fall
+ * back: if the configured provider is unavailable the call fails and is retried
+ * later against the same provider. `open` carries material that is not
+ * confidential in that sense and may fall back within the posture.
+ */
+export type RetentionPosture = 'walled' | 'open';
+
+export interface TranslationRoute {
+  posture: RetentionPosture;
+  provider: string;
+  model: string;
+  /** Boot-time allow-list. A model outside it must stop the service starting. */
+  allowedModels: readonly string[];
+  fallback: boolean;
+}
+
+/**
+ * Where the engine writes operational detail.
+ *
+ * IT IS AN INJECTED SEAM SO A TEST CAN CAPTURE IT. The confidentiality
+ * guarantee breaks on the failure path — `startsim-bfem` names the live
+ * precedent, a Django handler that logs the model's raw response on a
+ * JSON-parse failure — so "no client text reaches a log" has to be an
+ * assertion, not a code-review habit.
+ */
+export interface TranslationLogger {
+  debug(message: string, meta?: Record<string, unknown>): void;
+  info(message: string, meta?: Record<string, unknown>): void;
+  warn(message: string, meta?: Record<string, unknown>): void;
+  error(message: string, meta?: Record<string, unknown>): void;
+}
+
+export interface TranslationDeps {
+  provider: ILLMProvider;
+  logger?: TranslationLogger;
+  limits?: BatchLimits;
+  /** Attempts at a malformed envelope before the batch fails. */
+  maxEnvelopeRetries?: number;
+}
+
+export interface TranslationService {
+  translate(request: TranslationRequest): Promise<TranslationResult>;
+  readonly route: TranslationRoute;
+}
+
+/** Context the batch prompt is rendered from. */
+export interface PromptContext {
+  sourceLocale: Locale;
+  targetLocale: Locale;
+  glossary?: readonly GlossaryTerm[];
+  /** Labelled separately so the model can tell an EXAMPLE from a thing to translate. */
+  memoryExamples?: readonly MemoryUnit[];
+}