@startsimpli/llm 0.4.17 → 0.4.18

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@startsimpli/llm",
-  "version": "0.4.17",
+  "version": "0.4.18",
   "description": "Generic LLM service infrastructure — provider abstraction, retry logic, JSON extraction",
   "main": "./src/index.ts",
   "types": "./src/index.ts",

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 },