@startsimpli/llm 0.4.17 → 0.4.19

package/README.md

@@ -60,6 +60,7 @@ The factories read from `process.env` and return `null` when nothing is configur
 | `OPENAI_API_KEY` | `createOpenAIProvider()` | unset → provider disabled |
 | `OPENAI_BASE_URL` | `createOpenAIProvider()` | `https://api.openai.com/v1` |
 | `OPENAI_MODEL` | `createOpenAIProvider()` | `gpt-4o-mini` (`LLM_DEFAULTS.openaiModel`) |
+| `OPENAI_REASONING_EFFORT` | `createOpenAIProvider()` | unset (API default). gpt-5 family only: `none`, `low`, `medium`, `high` (gpt-5.5 rejects `minimal`). `maxTokens` stays the answer budget; reasoning headroom is added on top. |
 | `ANTHROPIC_API_KEY` | `createAnthropicProvider()` | unset → provider disabled |
 | `ANTHROPIC_BASE_URL` | `createAnthropicProvider()` | `https://api.anthropic.com/v1` |
 | `ANTHROPIC_MODEL` | `createAnthropicProvider()` | `claude-sonnet-4-20250514` (`LLM_DEFAULTS.anthropicModel`) |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@startsimpli/llm",
-  "version": "0.4.17",
+  "version": "0.4.19",
   "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,188 @@
+/**
+ * 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;
+  reasoning_effort?: string;
+}
+
+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 () => {
+    // For the gpt-5 family maxTokens is the ANSWER budget; reasoning headroom is
+    // added on top (see the reasoning describe below). none = no reasoning.
+    await provider('gpt-5.2').generate('u', 's', { maxTokens: 123, reasoningEffort: 'none' });
+    await provider('gpt-4o').generate('u', 's', { maxTokens: 123 });
+
+    expect(sent[0]!.max_completion_tokens).toBe(123);
+    expect(sent[1]!.max_tokens).toBe(123);
+  });
+});
+
+/*
+ * MEASURED 2026-10-02 against gpt-5.5-2026-04-23, a 256-token structured call:
+ *   effort unset (API default) -> empty content: reasoning ate the whole cap
+ *   none   -> 2.3s, 35 completion tokens, 0 reasoning
+ *   low    -> 2.8s, 130 completion tokens, 91 reasoning
+ *   medium -> 42.8s, 412 completion tokens, 377 reasoning
+ *   minimal -> 400 "does not support 'minimal' with this model"
+ * crochet's assembly pipeline asked for 256 tokens per connection call and got
+ * an empty answer 11 times out of 11. Hidden reasoning is billed against
+ * max_completion_tokens, so a caller's answer budget must get headroom.
+ */
+describe('reasoning (gpt-5 family)', () => {
+  it('sends reasoning_effort when one is given, to gpt-5 models only', async () => {
+    await provider('gpt-5.5').generate('u', 's', { reasoningEffort: 'low' });
+    await provider('gpt-4o').generate('u', 's', { reasoningEffort: 'low' });
+    expect(sent[0]!.reasoning_effort).toBe('low');
+    expect(sent[1]!.reasoning_effort).toBeUndefined();
+  });
+
+  it('omits reasoning_effort when none is configured (the API default applies)', async () => {
+    await provider('gpt-5.5').generate('u', 's');
+    expect(sent[0]!.reasoning_effort).toBeUndefined();
+  });
+
+  it('takes the default effort from the provider config', async () => {
+    await new OpenAIProvider({ apiKey: 'k', defaultModel: 'gpt-5.5', defaultReasoningEffort: 'low' }).generate('u', 's');
+    expect(sent[0]!.reasoning_effort).toBe('low');
+  });
+
+  it('adds reasoning headroom on top of the answer budget, scaled to the effort', async () => {
+    await provider('gpt-5.5').generate('u', 's', { maxTokens: 256, reasoningEffort: 'none' });
+    await provider('gpt-5.5').generate('u', 's', { maxTokens: 256, reasoningEffort: 'low' });
+    await provider('gpt-5.5').generate('u', 's', { maxTokens: 256 });
+    const [none, low, unset] = sent.map((b) => b.max_completion_tokens!);
+    expect(none).toBe(256);
+    expect(low).toBeGreaterThanOrEqual(256 + 1000);
+    // unset means the API's default effort (medium), which reasons the most of these
+    expect(unset).toBeGreaterThan(low);
+  });
+
+  it('applies to the tool-calling path too', async () => {
+    fetchMock.mockImplementationOnce(async (_url: unknown, init: RequestInit) => {
+      sent.push(JSON.parse(String(init.body)) as Sent);
+      return { ok: true, status: 200, json: async () => ({ ...OK_BODY, choices: [{ index: 0, message: { role: 'assistant', content: 'done' }, finish_reason: 'stop' }] }) } as unknown as Response;
+    });
+    await provider('gpt-5.5').generateWithTools([{ role: 'user', content: 'hi' }], 's', [], { maxTokens: 100, reasoningEffort: 'low' });
+    expect(sent[0]!.reasoning_effort).toBe('low');
+    expect(sent[0]!.max_completion_tokens).toBeGreaterThan(100);
+  });
+});
+
+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);
+  });
+});
+
+describe('response provenance', () => {
+  it('reports the provider and the model the API says answered', async () => {
+    const res = await provider('gpt-5.5').generate('u', 's');
+    expect(res.provider).toBe('openai');
+    expect(res.model).toBe('server-reported-model');
+  });
+});

package/src/index.ts

@@ -7,6 +7,7 @@ export type {
   TokenUsage,
   LLMResponse,
   GenerateOptions,
+  ReasoningEffort,
   ProviderConfig,
   JsonExtractionResult,
   ValidationResult,

package/src/providers/anthropic.ts

@@ -151,7 +151,7 @@ export class AnthropicProvider implements ILLMProvider {
   readonly availableModels = ANTHROPIC_MODELS;
   readonly defaultModel: string;
 
-  private readonly config: Required<ProviderConfig>;
+  private readonly config: Required<Omit<ProviderConfig, 'defaultReasoningEffort'>>;
   private readonly apiVersion: string;
 
   constructor(config: ProviderConfig, apiVersion?: string) {
@@ -246,6 +246,7 @@ Please respond with a valid JSON object only. Do not include any text before or
           totalTokens: data.usage.input_tokens + data.usage.output_tokens,
         },
         model: data.model,
+        provider: this.name,
         responseId: data.id,
         finishReason: data.stop_reason ?? undefined,
       };

package/src/providers/mock.ts

@@ -88,6 +88,7 @@ export class MockLLMProvider implements ILLMProvider {
         content: mockBehavior.customResponse,
         usage: { promptTokens: 100, completionTokens: 500, totalTokens: 600 },
         model: this.defaultModel,
+        provider: this.name,
         responseId: `mock-${this.callCount}`,
         finishReason: 'stop',
       };
@@ -98,6 +99,7 @@ export class MockLLMProvider implements ILLMProvider {
         content: getInvalidResponse(),
         usage: { promptTokens: 100, completionTokens: 200, totalTokens: 300 },
         model: this.defaultModel,
+        provider: this.name,
         responseId: `mock-${this.callCount}`,
         finishReason: 'stop',
       };
@@ -107,6 +109,7 @@ export class MockLLMProvider implements ILLMProvider {
       content: getDefaultResponse(),
       usage: { promptTokens: 150, completionTokens: 800, totalTokens: 950 },
       model: this.defaultModel,
+      provider: this.name,
       responseId: `mock-${this.callCount}`,
       finishReason: 'stop',
     };

package/src/providers/openai.ts

@@ -17,6 +17,7 @@ import type {
   NativeToolSpec,
   NativeChatMessage,
   NativeToolResponse,
+  ReasoningEffort,
 } from '../types';
 import { LLM_DEFAULTS } from '../types';
 import { LLMProviderError } from '../errors';
@@ -31,10 +32,61 @@ 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;
+  /** gpt-5 family only. */
+  reasoning_effort?: ReasoningEffort;
   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, effort?: ReasoningEffort): Partial<OpenAIRequest> {
+  return isGpt5Family(model)
+    ? { max_completion_tokens: maxTokens + reasoningHeadroom(effort) }
+    : { max_tokens: maxTokens };
+}
+
+/**
+ * Tokens to allow for hidden reasoning, which the gpt-5 family bills against
+ * max_completion_tokens: a caller's maxTokens is the size of the ANSWER. Unset
+ * means the API's default effort (medium). Measured on gpt-5.5: low reasoned
+ * ~90 tokens and medium ~380 on a small structured call; large outputs reason
+ * far more, so these are generous ceilings, not estimates.
+ */
+function reasoningHeadroom(effort?: ReasoningEffort): number {
+  switch (effort) {
+    case 'none': return 0;
+    case 'minimal': return 1024;
+    case 'low': return 4096;
+    case 'high': return 24576;
+    case 'xhigh': return 32768;
+    case 'medium':
+    default: return 12288;
+  }
+}
+
+/** reasoning_effort for a gpt-5 model, when one is configured. */
+function reasoningParam(model: string, effort?: ReasoningEffort): Partial<OpenAIRequest> {
+  return isGpt5Family(model) && effort ? { reasoning_effort: effort } : {};
+}
+
 interface OpenAIResponse {
   id: string;
   object: string;
@@ -114,7 +166,7 @@ export class OpenAIProvider implements ILLMProvider {
   readonly availableModels = OPENAI_MODELS;
   readonly defaultModel: string;
 
-  private readonly config: Required<ProviderConfig>;
+  private readonly config: Required<Omit<ProviderConfig, 'defaultReasoningEffort'>> & Pick<ProviderConfig, 'defaultReasoningEffort'>;
 
   constructor(config: ProviderConfig) {
     this.config = {
@@ -124,6 +176,7 @@ export class OpenAIProvider implements ILLMProvider {
       defaultTemperature: config.defaultTemperature ?? DEFAULTS.temperature,
       defaultMaxTokens: config.defaultMaxTokens ?? DEFAULTS.maxTokens,
       timeoutMs: config.timeoutMs ?? DEFAULTS.timeoutMs,
+      defaultReasoningEffort: config.defaultReasoningEffort,
     };
     this.defaultModel = this.config.defaultModel;
   }
@@ -149,12 +202,13 @@ 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;
+    const effort = options?.reasoningEffort ?? this.config.defaultReasoningEffort;
     const timeout = options?.timeout ?? this.config.timeoutMs;
 
     const requestBody: OpenAIRequest = {
@@ -164,7 +218,8 @@ export class OpenAIProvider implements ILLMProvider {
         { role: 'user', content: userPrompt },
       ],
       temperature,
-      max_tokens: maxTokens,
+      ...tokenLimitParam(model, maxTokens, effort),
+      ...reasoningParam(model, effort),
       response_format: { type: 'json_object' },
     };
 
@@ -211,6 +266,7 @@ export class OpenAIProvider implements ILLMProvider {
           totalTokens: data.usage.total_tokens,
         },
         model: data.model,
+        provider: this.name,
         responseId: data.id,
         finishReason: data.choices[0].finish_reason,
       };
@@ -264,12 +320,13 @@ 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;
+    const effort = options?.reasoningEffort ?? this.config.defaultReasoningEffort;
     const timeout = options?.timeout ?? this.config.timeoutMs;
 
     const oaiMessages: OpenAIToolMessage[] = [
@@ -297,7 +354,8 @@ export class OpenAIProvider implements ILLMProvider {
       model,
       messages: oaiMessages,
       temperature,
-      max_tokens: maxTokens,
+      ...tokenLimitParam(model, maxTokens, effort),
+      ...reasoningParam(model, effort),
       tools: tools.map((t) => ({
         type: 'function' as const,
         function: { name: t.name, description: t.description, parameters: t.parameters },
@@ -434,5 +492,8 @@ export function createOpenAIProvider(): OpenAIProvider | null {
     // deployment's timeout and the other ignoring it is the kind of asymmetry
     // that only shows up as a provider-dependent bug at 3am.
     timeoutMs: Number(process.env.LLM_TIMEOUT_MS) || undefined,
+    // gpt-5 family only; unset leaves the API's default (medium, the slowest
+    // that answers small structured calls: see reasoningHeadroom).
+    defaultReasoningEffort: (process.env.OPENAI_REASONING_EFFORT || undefined) as ReasoningEffort | undefined,
   });
 }

package/src/types.ts

@@ -17,8 +17,10 @@ export interface LLMResponse {
   content: string;
   /** Token usage statistics */
   usage: TokenUsage;
-  /** Model identifier used for generation */
+  /** Model identifier used for generation, as the API reports it (e.g. the dated snapshot `gpt-5.5-2026-04-23`). */
   model: string;
+  /** Which provider answered (`openai`, `anthropic`, `mock`). */
+  provider?: string;
   /** Response ID for debugging/logging */
   responseId?: string;
   /** Finish reason (e.g., 'stop', 'length', 'content_filter') */
@@ -37,6 +39,12 @@ export interface GenerateOptions {
   maxTokens?: number;
   /** Request timeout in milliseconds */
   timeout?: number;
+  /**
+   * How much a reasoning model (OpenAI gpt-5 family) thinks before answering.
+   * Unset = the API's default. `maxTokens` stays the answer budget; the
+   * provider adds headroom for the reasoning on top.
+   */
+  reasoningEffort?: ReasoningEffort;
   /** Arbitrary extra data the caller wants to thread through (e.g. domain preferences) */
   extra?: Record<string, unknown>;
 }
@@ -82,8 +90,13 @@ export interface NativeToolResponse {
 /**
  * Provider configuration — everything needed to construct a provider instance.
  */
+/** OpenAI reasoning effort. Not every model takes every value (gpt-5.5 rejects 'minimal'). */
+export type ReasoningEffort = 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh';
+
 export interface ProviderConfig {
   apiKey: string;
+  /** Default reasoning effort for reasoning models (see GenerateOptions.reasoningEffort). */
+  defaultReasoningEffort?: ReasoningEffort;
   baseUrl?: string;
   defaultModel?: string;
   defaultTemperature?: number;