@startsimpli/llm 0.4.18 → 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.18",
+  "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

@@ -32,6 +32,7 @@ interface Sent {
   temperature?: number;
   max_tokens?: number;
   max_completion_tokens?: number;
+  reasoning_effort?: string;
 }
 
 const OK_BODY = {
@@ -92,7 +93,9 @@ describe('the token-limit parameter', () => {
   });
 
   it('honours an explicit maxTokens on whichever parameter the model takes', async () => {
-    await provider('gpt-5.2').generate('u', 's', { maxTokens: 123 });
+    // 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);
@@ -100,6 +103,57 @@ describe('the token-limit parameter', () => {
   });
 });
 
+/*
+ * 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',
@@ -124,3 +178,11 @@ describe('temperature', () => {
     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';
@@ -35,6 +36,8 @@ interface OpenAIRequest {
   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' };
 }
 
@@ -54,12 +57,36 @@ function isGpt5Family(model: string): boolean {
  * 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> {
+function tokenLimitParam(model: string, maxTokens: number, effort?: ReasoningEffort): Partial<OpenAIRequest> {
   return isGpt5Family(model)
-    ? { max_completion_tokens: maxTokens }
+    ? { 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;
@@ -139,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 = {
@@ -149,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;
   }
@@ -180,6 +208,7 @@ export class OpenAIProvider implements ILLMProvider {
       ? 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 = {
@@ -189,7 +218,8 @@ export class OpenAIProvider implements ILLMProvider {
         { role: 'user', content: userPrompt },
       ],
       temperature,
-      ...tokenLimitParam(model, maxTokens),
+      ...tokenLimitParam(model, maxTokens, effort),
+      ...reasoningParam(model, effort),
       response_format: { type: 'json_object' },
     };
 
@@ -236,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,
       };
@@ -295,6 +326,7 @@ export class OpenAIProvider implements ILLMProvider {
       ? 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[] = [
@@ -322,7 +354,8 @@ export class OpenAIProvider implements ILLMProvider {
       model,
       messages: oaiMessages,
       temperature,
-      ...tokenLimitParam(model, 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 },
@@ -459,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;