@startsimpli/llm 0.4.16 → 0.4.18

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@startsimpli/llm",
-  "version": "0.4.16",
+  "version": "0.4.18",
   "description": "Generic LLM service infrastructure — provider abstraction, retry logic, JSON extraction",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
   "exports": {
-    ".": "./src/index.ts"
+    ".": "./src/index.ts",
+    "./translation": "./src/translation/index.ts"
   },
   "files": [
     "src",
@@ -15,7 +16,8 @@
     "access": "public"
   },
   "dependencies": {
-    "zod": "^4.3.6"
+    "zod": "^4.3.6",
+    "@startsimpli/i18n": "^0.1.3"
   },
   "devDependencies": {
     "@types/node": "^20.19.39",

package/src/__tests__/openai-provider.test.ts

@@ -0,0 +1,126 @@
+/**
+ * What the OpenAI provider actually PUTS ON THE WIRE.
+ *
+ * The sibling of `anthropic-provider.test.ts`, and it exists for the same class
+ * of bug: a 400 caused by a parameter WE send, which no amount of response
+ * handling can recover from.
+ *
+ * The acceptance boundary below is not invented. It was measured against
+ * api.openai.com with a real key on 2026-08-19, while debugging why a live
+ * translation on marketing-agents failed:
+ *
+ *   gpt-5.2  max_tokens            -> 400 Unsupported parameter: 'max_tokens' is not
+ *                                          supported with this model. Use
+ *                                          'max_completion_tokens' instead.
+ *   gpt-5.2  max_completion_tokens -> 200
+ *   gpt-4o   max_tokens            -> 200
+ *
+ * So the provider as written could never call ANY gpt-5 model: it always sent
+ * `max_tokens`. That is a total outage of the newest family, not an edge case.
+ *
+ * The second thing pinned here is the FAMILY TEST. bd startsim-768w.38.26 filed
+ * the literal-id deny-list (`model === 'gpt-5' || 'gpt-5.1' || 'gpt-5.2'`) as a
+ * bug, because it is "correct only until OpenAI ships gpt-5.3". These tests use
+ * an unreleased id on purpose, so the rule has to be about the FAMILY.
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+
+import { OpenAIProvider } from '../providers/openai';
+
+interface Sent {
+  model: string;
+  temperature?: number;
+  max_tokens?: number;
+  max_completion_tokens?: number;
+}
+
+const OK_BODY = {
+  id: 'chatcmpl-1',
+  object: 'chat.completion',
+  created: 0,
+  model: 'server-reported-model',
+  choices: [{ index: 0, message: { role: 'assistant', content: '{"ok":true}' }, finish_reason: 'stop' }],
+  usage: { prompt_tokens: 10, completion_tokens: 4, total_tokens: 14 },
+};
+
+let sent: Sent[];
+let fetchMock: ReturnType<typeof vi.fn>;
+
+function provider(defaultModel: string) {
+  return new OpenAIProvider({ apiKey: 'sk-test', defaultModel, defaultTemperature: 0.2 });
+}
+
+beforeEach(() => {
+  sent = [];
+  fetchMock = vi.fn(async (_url: unknown, init: RequestInit) => {
+    sent.push(JSON.parse(String(init.body)) as Sent);
+    return { ok: true, status: 200, json: async () => OK_BODY } as unknown as Response;
+  });
+  vi.stubGlobal('fetch', fetchMock);
+});
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+});
+
+describe('the token-limit parameter', () => {
+  it.each(['gpt-5', 'gpt-5.1', 'gpt-5.2'])(
+    '%s gets max_completion_tokens and never max_tokens',
+    async (model) => {
+      await provider(model).generate('u', 's');
+
+      expect(sent[0]!.max_completion_tokens).toBeGreaterThan(0);
+      expect(sent[0]!.max_tokens).toBeUndefined();
+    },
+  );
+
+  it('an UNRELEASED gpt-5 model is handled by family, not by a hardcoded list', async () => {
+    // bd startsim-768w.38.26. The day this id ships, a literal deny-list sends
+    // it max_tokens and every call 400s — silently, from the caller's view.
+    await provider('gpt-5.3').generate('u', 's');
+
+    expect(sent[0]!.max_completion_tokens).toBeGreaterThan(0);
+    expect(sent[0]!.max_tokens).toBeUndefined();
+  });
+
+  it('gpt-4o keeps max_tokens, which it accepts', async () => {
+    // The fix must not break the models that were working.
+    await provider('gpt-4o').generate('u', 's');
+
+    expect(sent[0]!.max_tokens).toBeGreaterThan(0);
+    expect(sent[0]!.max_completion_tokens).toBeUndefined();
+  });
+
+  it('honours an explicit maxTokens on whichever parameter the model takes', async () => {
+    await provider('gpt-5.2').generate('u', 's', { maxTokens: 123 });
+    await provider('gpt-4o').generate('u', 's', { maxTokens: 123 });
+
+    expect(sent[0]!.max_completion_tokens).toBe(123);
+    expect(sent[1]!.max_tokens).toBe(123);
+  });
+});
+
+describe('temperature', () => {
+  it.each(['gpt-5', 'gpt-5.1', 'gpt-5.2', 'gpt-5.3'])(
+    '%s is sent temperature 1.0, whatever the deployment configured',
+    async (model) => {
+      // Base gpt-5 models reject any other value.
+      await provider(model).generate('u', 's', { temperature: 0.2 });
+
+      expect(sent[0]!.temperature).toBe(1.0);
+    },
+  );
+
+  it('a FINE-TUNED gpt-5 keeps the configured temperature', async () => {
+    // The existing carve-out, preserved: ft: models do accept it.
+    await provider('ft:gpt-5.2:acme::abc123').generate('u', 's', { temperature: 0.2 });
+
+    expect(sent[0]!.temperature).toBe(0.2);
+  });
+
+  it('gpt-4o keeps the configured temperature', async () => {
+    await provider('gpt-4o').generate('u', 's', { temperature: 0.2 });
+
+    expect(sent[0]!.temperature).toBe(0.2);
+  });
+});

package/src/providers/openai.ts

@@ -31,10 +31,35 @@ interface OpenAIRequest {
   model: string;
   messages: OpenAIMessage[];
   temperature?: number;
+  /** Pre-gpt-5 models. Rejected outright by the gpt-5 family. */
   max_tokens?: number;
+  /** The gpt-5 family's replacement for `max_tokens`. */
+  max_completion_tokens?: number;
   response_format?: { type: 'json_object' | 'text' };
 }
 
+/**
+ * Is this the gpt-5 FAMILY? Matched by prefix, deliberately, not by a list of
+ * ids (bd startsim-768w.38.26 filed the literal-id deny-list as a bug: it is
+ * "correct only until OpenAI ships gpt-5.3", and the failure is a silent 400).
+ * `ft:gpt-5…` fine-tunes are still gpt-5 models on the wire.
+ */
+function isGpt5Family(model: string): boolean {
+  return /^gpt-5/.test(model.startsWith('ft:') ? model.slice(3) : model);
+}
+
+/**
+ * The token-limit parameter this model accepts. MEASURED against api.openai.com
+ * on 2026-08-19: gpt-5.2 rejects `max_tokens` with "Unsupported parameter ...
+ * Use 'max_completion_tokens' instead", while gpt-4o accepts `max_tokens`.
+ * Sending the wrong one is a total outage of that model, not a degraded call.
+ */
+function tokenLimitParam(model: string, maxTokens: number): Partial<OpenAIRequest> {
+  return isGpt5Family(model)
+    ? { max_completion_tokens: maxTokens }
+    : { max_tokens: maxTokens };
+}
+
 interface OpenAIResponse {
   id: string;
   object: string;
@@ -149,9 +174,9 @@ export class OpenAIProvider implements ILLMProvider {
 
     const model = options?.model ?? this.config.defaultModel;
     // Base gpt-5 models require temperature=1.0, but fine-tuned models use configured temperature
-    const isBaseGpt5 = model === 'gpt-5' || model === 'gpt-5.1' || model === 'gpt-5.2';
     const isFineTuned = model.startsWith('ft:');
-    const temperature = isBaseGpt5 && !isFineTuned
+    const isBaseGpt5 = isGpt5Family(model) && !isFineTuned;
+    const temperature = isBaseGpt5
       ? 1.0
       : (options?.temperature ?? this.config.defaultTemperature);
     const maxTokens = options?.maxTokens ?? this.config.defaultMaxTokens;
@@ -164,7 +189,7 @@ export class OpenAIProvider implements ILLMProvider {
         { role: 'user', content: userPrompt },
       ],
       temperature,
-      max_tokens: maxTokens,
+      ...tokenLimitParam(model, maxTokens),
       response_format: { type: 'json_object' },
     };
 
@@ -264,9 +289,9 @@ export class OpenAIProvider implements ILLMProvider {
     }
 
     const model = options?.model ?? this.config.defaultModel;
-    const isBaseGpt5 = model === 'gpt-5' || model === 'gpt-5.1' || model === 'gpt-5.2';
     const isFineTuned = model.startsWith('ft:');
-    const temperature = isBaseGpt5 && !isFineTuned
+    const isBaseGpt5 = isGpt5Family(model) && !isFineTuned;
+    const temperature = isBaseGpt5
       ? 1.0
       : (options?.temperature ?? this.config.defaultTemperature);
     const maxTokens = options?.maxTokens ?? this.config.defaultMaxTokens;
@@ -297,7 +322,7 @@ export class OpenAIProvider implements ILLMProvider {
       model,
       messages: oaiMessages,
       temperature,
-      max_tokens: maxTokens,
+      ...tokenLimitParam(model, maxTokens),
       tools: tools.map((t) => ({
         type: 'function' as const,
         function: { name: t.name, description: t.description, parameters: t.parameters },

package/src/translation/__fixtures__/golden-pairs.ts

@@ -0,0 +1,243 @@
+/**
+ * THE SYNTHETIC GOLDEN SET (bd startsim-bfem, decision 1).
+ *
+ * ────────────────────────────────────────────────────────────────────────────
+ * READ THIS BEFORE TRUSTING A TARGET STRING BELOW.
+ *
+ * Every `targetText` here is CONSTRUCTED, not translated. Nobody on our side
+ * reads Arabic or Chinese, so authoring convincing prose in either was never on
+ * the table — and pretending otherwise would put unreviewable text in the repo
+ * that a future reader mistakes for a reference.
+ *
+ * What these strings ARE: scaffolds built so the mechanical checks have
+ * something TRUE to assert. Each one carries, verbatim, the things a check
+ * looks for — the approved glossary term, the do-not-translate brand, every
+ * number and date — wrapped in filler that is honestly marked as filler
+ * (`نص تجريبي` / `示例文本`, both meaning roughly "sample text"). They are not
+ * fluent, they are not idiomatic, and no conclusion about translation QUALITY
+ * may be drawn from them. They pin down INVARIANTS, which is all the design
+ * permits a test to assert anyway (`startsim-bfem`, decision 2: assert
+ * relations between input and output, never the output itself).
+ *
+ * `provenance: 'reviewed'` is reserved for the two honest pairs — one per
+ * locale — that a named target-language reviewer contributes once. There are
+ * none yet: that is the `startsim-r9q8` blocker, and it is a people problem.
+ * Until then every pair here reads `constructed`, and a reader who cannot read
+ * the language can tell the difference by looking at one field.
+ * ────────────────────────────────────────────────────────────────────────────
+ *
+ * THE REAL SET LIVES OUTSIDE THIS REPOSITORY — 200 stratified segments in the
+ * client's own tenant, per `startsim-r9q8`. It never enters git. This set is
+ * its proxy and SHARES ITS SHAPE on purpose: the same assertions must run over
+ * either, or the synthetic set stops being a proxy and becomes a second thing
+ * to maintain.
+ *
+ * TWO LOCALES, ONE RTL AND ONE LTR, AND THAT IS THE ENFORCEMENT MECHANISM.
+ * `startsim-jb1z` bans naming a language in the engine. A test that needs to
+ * know which locale it is running has caught a leak — so every suite here is
+ * driven by `describe.each(GOLDEN_SETS)` over one shared body. EN→ZH is not
+ * decoration either: OGMC needs it, and it is the pair whose reviewer already
+ * exists.
+ */
+
+import type { GlossaryTerm, Locale, TranslationSegment } from '../types';
+
+/** How a target string came to exist. See the header. */
+export type PairProvenance = 'constructed' | 'reviewed';
+
+export interface GoldenPair {
+  /** Stable across locales, so one test body can ask both sets for the same case. */
+  id: string;
+  /** What this pair exists to exercise. */
+  covers: string;
+  sourceText: string;
+  targetText: string;
+  provenance: PairProvenance;
+}
+
+export interface GoldenSet {
+  sourceLocale: Locale;
+  targetLocale: Locale;
+  /**
+   * Present so a TEST can label its own output, never so the ENGINE can branch.
+   * Nothing in `packages/llm/src/translation/` may read this field — the engine
+   * takes direction from `dirFor()` at render time or not at all.
+   */
+  rtl: boolean;
+  glossary: GlossaryTerm[];
+  pairs: GoldenPair[];
+}
+
+/** The source side is shared: the same English drives both target locales. */
+const SOURCE_LOCALE = 'en';
+
+const SOURCES = {
+  plain: 'The quarterly report is ready for your review.',
+  glossaryTerm: 'Please review the settlement agreement before Friday.',
+  doNotTranslate: 'Contact Northwind Logistics about the delay.',
+  numerics: 'Revenue grew 12.5% to $4,200,000 on 2026-03-31.',
+  numberOnly: '2,750',
+  empty: '',
+  quoteAndNewline: 'She said "we accept the terms".\nThe contract is enclosed.',
+} as const;
+
+/** The one brand string that must survive verbatim into every target. */
+export const DNT_BRAND = 'Northwind Logistics';
+
+/** The numerics the `numerics` pair must round-trip, as a multiset. */
+export const NUMERICS_IN_FIXTURE = ['12.5%', '$4,200,000', '2026-03-31'] as const;
+
+const AR: GoldenSet = {
+  sourceLocale: SOURCE_LOCALE,
+  targetLocale: 'ar',
+  rtl: true,
+  glossary: [
+    { source: 'settlement agreement', target: 'اتفاقية التسوية', binding: true },
+    { source: DNT_BRAND, target: DNT_BRAND, binding: true, doNotTranslate: true },
+  ],
+  pairs: [
+    {
+      id: 'plain',
+      covers: 'a plain sentence with nothing special in it',
+      sourceText: SOURCES.plain,
+      targetText: 'نص تجريبي: التقرير ربع السنوي جاهز للمراجعة.',
+      provenance: 'constructed',
+    },
+    {
+      id: 'glossary-term',
+      covers: 'a binding glossary term that must appear in its approved form',
+      sourceText: SOURCES.glossaryTerm,
+      targetText: 'نص تجريبي: يرجى مراجعة اتفاقية التسوية قبل يوم الجمعة.',
+      provenance: 'constructed',
+    },
+    {
+      id: 'do-not-translate',
+      covers: 'a brand name that must survive verbatim',
+      sourceText: SOURCES.doNotTranslate,
+      targetText: `نص تجريبي: يرجى الاتصال بـ ${DNT_BRAND} بشأن التأخير.`,
+      provenance: 'constructed',
+    },
+    {
+      id: 'numerics',
+      covers: 'a percentage, a currency amount and an ISO date',
+      sourceText: SOURCES.numerics,
+      targetText: 'نص تجريبي: نمت الإيرادات 12.5% إلى $4,200,000 في 2026-03-31.',
+      provenance: 'constructed',
+    },
+    {
+      id: 'number-only',
+      covers: 'a segment that is nothing but a number',
+      sourceText: SOURCES.numberOnly,
+      targetText: '2,750',
+      provenance: 'constructed',
+    },
+    {
+      id: 'empty',
+      covers: 'an empty segment — the caller handed us nothing',
+      sourceText: SOURCES.empty,
+      targetText: '',
+      provenance: 'constructed',
+    },
+    {
+      id: 'quote-and-newline',
+      covers: 'an embedded quotation mark and a newline — the XML-block escaping case',
+      sourceText: SOURCES.quoteAndNewline,
+      targetText: 'نص تجريبي: قالت «نقبل الشروط».\nالعقد مرفق.',
+      provenance: 'constructed',
+    },
+  ],
+};
+
+const ZH: GoldenSet = {
+  sourceLocale: SOURCE_LOCALE,
+  targetLocale: 'zh',
+  rtl: false,
+  glossary: [
+    { source: 'settlement agreement', target: '和解协议', binding: true },
+    { source: DNT_BRAND, target: DNT_BRAND, binding: true, doNotTranslate: true },
+  ],
+  pairs: [
+    {
+      id: 'plain',
+      covers: 'a plain sentence with nothing special in it',
+      sourceText: SOURCES.plain,
+      targetText: '示例文本：季度报告已可供审阅。',
+      provenance: 'constructed',
+    },
+    {
+      id: 'glossary-term',
+      covers: 'a binding glossary term that must appear in its approved form',
+      sourceText: SOURCES.glossaryTerm,
+      targetText: '示例文本：请在星期五之前审阅和解协议。',
+      provenance: 'constructed',
+    },
+    {
+      id: 'do-not-translate',
+      covers: 'a brand name that must survive verbatim',
+      sourceText: SOURCES.doNotTranslate,
+      targetText: `示例文本：请联系 ${DNT_BRAND} 了解延误情况。`,
+      provenance: 'constructed',
+    },
+    {
+      id: 'numerics',
+      covers: 'a percentage, a currency amount and an ISO date',
+      sourceText: SOURCES.numerics,
+      targetText: '示例文本：收入增长 12.5% 至 $4,200,000，日期为 2026-03-31。',
+      provenance: 'constructed',
+    },
+    {
+      id: 'number-only',
+      covers: 'a segment that is nothing but a number',
+      sourceText: SOURCES.numberOnly,
+      targetText: '2,750',
+      provenance: 'constructed',
+    },
+    {
+      id: 'empty',
+      covers: 'an empty segment — the caller handed us nothing',
+      sourceText: SOURCES.empty,
+      targetText: '',
+      provenance: 'constructed',
+    },
+    {
+      id: 'quote-and-newline',
+      covers: 'an embedded quotation mark and a newline — the XML-block escaping case',
+      sourceText: SOURCES.quoteAndNewline,
+      targetText: '示例文本：她说“我们接受这些条款”。\n合同已附上。',
+      provenance: 'constructed',
+    },
+  ],
+};
+
+/**
+ * THE LOADER. One entry point, shared with the real set — the point of the
+ * split is that the same assertions run over either.
+ */
+export const GOLDEN_SETS: readonly GoldenSet[] = [AR, ZH];
+
+export function goldenSet(targetLocale: Locale): GoldenSet {
+  const found = GOLDEN_SETS.find((set) => set.targetLocale === targetLocale);
+  if (!found) throw new Error(`no golden set for target locale ${targetLocale}`);
+  return found;
+}
+
+export function pairIn(set: GoldenSet, id: string): GoldenPair {
+  const found = set.pairs.find((pair) => pair.id === id);
+  if (!found) throw new Error(`no golden pair '${id}' in ${set.targetLocale}`);
+  return found;
+}
+
+/** The set as translation input — ids are the pair ids, which are opaque here. */
+export function segmentsOf(set: GoldenSet): TranslationSegment[] {
+  return set.pairs.map((pair) => ({ id: pair.id, text: pair.sourceText }));
+}
+
+/** A well-formed provider response for `set`, as the engine should receive it. */
+export function envelopeFor(
+  set: GoldenSet,
+  ids: readonly string[] = set.pairs.map((pair) => pair.id),
+): string {
+  return JSON.stringify({
+    segments: ids.map((id) => ({ id, text: pairIn(set, id).targetText })),
+  });
+}