@startsimpli/llm 0.4.14 → 0.4.16

package/package.json

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

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

@@ -0,0 +1,171 @@
+/**
+ * What the Anthropic provider actually PUTS ON THE WIRE (bd startsim-768w.38).
+ *
+ * These assert the request body, not the response, because the bug they exist
+ * for was a 400 from a parameter we sent — `temperature` is rejected outright by
+ * the Claude 5 family, so a provider that always sends it can never call the
+ * models we want to be on.
+ *
+ * The acceptance boundary below is not invented. It was measured against
+ * api.anthropic.com with a real key on 2026-08-10:
+ *
+ *   claude-sonnet-5      temperature -> 400 `temperature` is deprecated for this model.
+ *   claude-opus-5        temperature -> 400   (same; also top_p, top_k)
+ *   claude-fable-5       temperature -> 400
+ *   claude-opus-4-8      temperature -> 400
+ *   claude-opus-4-7      temperature -> 400
+ *   claude-opus-4-6      temperature -> 200
+ *   claude-sonnet-4-6    temperature -> 200
+ *   claude-sonnet-4-5-*  temperature -> 200
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+
+import { AnthropicProvider } from '../providers/anthropic';
+import { LLMProviderError } from '../errors';
+
+interface Sent {
+  model: string;
+  temperature?: number;
+  top_p?: number;
+  max_tokens: number;
+}
+
+const OK_BODY = {
+  id: 'msg_1',
+  type: 'message',
+  role: 'assistant',
+  content: [{ type: 'text', text: '{"ok":true}' }],
+  model: 'server-reported-model',
+  stop_reason: 'end_turn',
+  usage: { input_tokens: 10, output_tokens: 4 },
+};
+
+function ok() {
+  return {
+    ok: true,
+    status: 200,
+    json: async () => OK_BODY,
+  } as unknown as Response;
+}
+
+function deprecated(param: string) {
+  return {
+    ok: false,
+    status: 400,
+    json: async () => ({
+      type: 'error',
+      error: {
+        type: 'invalid_request_error',
+        message: `\`${param}\` is deprecated for this model.`,
+      },
+    }),
+  } as unknown as Response;
+}
+
+let sent: Sent[];
+let fetchMock: ReturnType<typeof vi.fn>;
+
+function provider(defaultModel: string) {
+  return new AnthropicProvider({ apiKey: 'sk-ant-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();
+  });
+  vi.stubGlobal('fetch', fetchMock);
+});
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+});
+
+describe('AnthropicProvider request body — sampling parameters', () => {
+  it('omits temperature for a Claude 5 model that rejects it', async () => {
+    await provider('claude-sonnet-5').generate('hi', 'sys', { temperature: 0.2 });
+
+    expect(sent).toHaveLength(1);
+    expect(sent[0].model).toBe('claude-sonnet-5');
+    expect(sent[0]).not.toHaveProperty('temperature');
+    // The parameters that ARE required still go, or the call is malformed.
+    expect(sent[0].max_tokens).toBeGreaterThan(0);
+  });
+
+  it.each(['claude-opus-5', 'claude-fable-5', 'claude-opus-4-8', 'claude-opus-4-7'])(
+    'omits temperature for %s',
+    async (model) => {
+      await provider(model).generate('hi', 'sys', { temperature: 0.2 });
+      expect(sent[0]).not.toHaveProperty('temperature');
+    },
+  );
+
+  it('still sends temperature for a 4.6-era model, which accepts it', async () => {
+    await provider('claude-sonnet-4-6').generate('hi', 'sys', { temperature: 0.2 });
+
+    expect(sent[0].model).toBe('claude-sonnet-4-6');
+    expect(sent[0].temperature).toBe(0.2);
+  });
+
+  it.each(['claude-opus-4-6', 'claude-sonnet-4-5-20250929', 'claude-haiku-4-5-20251001'])(
+    'still sends temperature for %s',
+    async (model) => {
+      await provider(model).generate('hi', 'sys', { temperature: 0.35 });
+      expect(sent[0].temperature).toBe(0.35);
+    },
+  );
+
+  it('omits temperature for a model id it has never heard of', async () => {
+    // The whole point of the allowlist shape: an id that does not exist yet gets
+    // the request that CANNOT 400, not the one that historically could.
+    await provider('claude-sonnet-7-hypothetical').generate('hi', 'sys', { temperature: 0.2 });
+    expect(sent[0]).not.toHaveProperty('temperature');
+  });
+
+  it('names a model that is actually callable as the package default', async () => {
+    // The old default, claude-sonnet-4-20250514, was retired and 404s. A default
+    // nobody can call is a broken default.
+    const p = new AnthropicProvider({ apiKey: 'sk-ant-test' });
+    await p.generate('hi', 'sys');
+    expect(sent[0].model).toBe(p.defaultModel);
+    expect(p.availableModels).toContain(p.defaultModel);
+  });
+});
+
+describe('AnthropicProvider — recovering from a parameter the model rejects', () => {
+  it('drops the named parameter and retries once when the API calls it deprecated', async () => {
+    // A model on the allowlist that the API has since changed its mind about:
+    // the safety net must un-break it without waiting for a release.
+    fetchMock.mockImplementationOnce(async (_url: unknown, init: RequestInit) => {
+      sent.push(JSON.parse(String(init.body)) as Sent);
+      return deprecated('temperature');
+    });
+
+    const response = await provider('claude-opus-4-6').generate('hi', 'sys', { temperature: 0.2 });
+
+    expect(sent).toHaveLength(2);
+    expect(sent[0].temperature).toBe(0.2);
+    expect(sent[1]).not.toHaveProperty('temperature');
+    expect(response.content).toBe('{"ok":true}');
+  });
+
+  it('does not retry a 400 that is not about a deprecated parameter', async () => {
+    fetchMock.mockImplementation(async (_url: unknown, init: RequestInit) => {
+      sent.push(JSON.parse(String(init.body)) as Sent);
+      return {
+        ok: false,
+        status: 400,
+        json: async () => ({
+          type: 'error',
+          error: { type: 'invalid_request_error', message: 'messages: at least one message required' },
+        }),
+      } as unknown as Response;
+    });
+
+    await expect(provider('claude-sonnet-4-6').generate('hi', 'sys')).rejects.toBeInstanceOf(
+      LLMProviderError,
+    );
+    expect(sent).toHaveLength(1);
+  });
+});

package/src/index.ts

@@ -23,7 +23,11 @@ export type { ILLMProvider } from './providers/interface';
 
 // Provider implementations
 export { OpenAIProvider, createOpenAIProvider } from './providers/openai';
-export { AnthropicProvider, createAnthropicProvider } from './providers/anthropic';
+export {
+  AnthropicProvider,
+  createAnthropicProvider,
+  supportsSamplingParams,
+} from './providers/anthropic';
 export { MockLLMProvider, setMockBehavior, resetMockBehavior } from './providers/mock';
 export type { MockBehavior } from './providers/mock';
 

package/src/providers/anthropic.ts

@@ -2,7 +2,7 @@
  * Anthropic Provider Implementation
  *
  * Uses native fetch to minimize dependencies.
- * Supports Claude 4 and Claude 3.x models.
+ * Supports the Claude 5 family and the Claude 4.x models still served.
  */
 
 import type { ILLMProvider } from './interface';
@@ -21,6 +21,10 @@ interface AnthropicRequest {
   max_tokens: number;
   messages: AnthropicMessage[];
   system?: string;
+  /**
+   * Sent ONLY for models known to accept it — see `supportsSamplingParams`.
+   * The Claude 5 family rejects it outright.
+   */
   temperature?: number;
 }
 
@@ -45,30 +49,94 @@ interface AnthropicErrorResponse {
   };
 }
 
+/**
+ * The models this provider advertises. Verified callable against
+ * api.anthropic.com on 2026-08-10 — every id in the previous version of this
+ * list except the two 4.6 entries had been retired and returned 404, which is
+ * the same staleness failure the temperature handling below is designed around.
+ */
 const ANTHROPIC_MODELS = [
+  'claude-opus-5',
+  'claude-sonnet-5',
+  'claude-fable-5',
+  'claude-opus-4-8',
+  'claude-opus-4-7',
   'claude-opus-4-6',
-  'claude-opus-4-20250514',
   'claude-sonnet-4-6',
-  'claude-sonnet-4-20250514',
-  'claude-3-5-sonnet-20241022',
-  'claude-3-5-haiku-20241022',
-  'claude-3-opus-20240229',
-  'claude-3-sonnet-20240229',
-  'claude-3-haiku-20240307',
+  'claude-opus-4-5-20251101',
+  'claude-sonnet-4-5-20250929',
+  'claude-haiku-4-5-20251001',
 ] as const;
 
+/** USD per 1K tokens (list prices per million, divided by 1000). */
 const MODEL_COSTS: Record<string, { input: number; output: number }> = {
-  'claude-opus-4-6': { input: 0.015, output: 0.075 },
-  'claude-opus-4-20250514': { input: 0.015, output: 0.075 },
+  'claude-fable-5': { input: 0.01, output: 0.05 },
+  'claude-opus-5': { input: 0.005, output: 0.025 },
+  'claude-opus-4-8': { input: 0.005, output: 0.025 },
+  'claude-opus-4-7': { input: 0.005, output: 0.025 },
+  'claude-opus-4-6': { input: 0.005, output: 0.025 },
+  'claude-opus-4-5-20251101': { input: 0.005, output: 0.025 },
+  'claude-sonnet-5': { input: 0.003, output: 0.015 },
   'claude-sonnet-4-6': { input: 0.003, output: 0.015 },
-  'claude-sonnet-4-20250514': { input: 0.003, output: 0.015 },
-  'claude-3-5-sonnet-20241022': { input: 0.003, output: 0.015 },
-  'claude-3-5-haiku-20241022': { input: 0.0008, output: 0.004 },
-  'claude-3-opus-20240229': { input: 0.015, output: 0.075 },
-  'claude-3-sonnet-20240229': { input: 0.003, output: 0.015 },
-  'claude-3-haiku-20240307': { input: 0.00025, output: 0.00125 },
+  'claude-sonnet-4-5-20250929': { input: 0.003, output: 0.015 },
+  'claude-haiku-4-5-20251001': { input: 0.001, output: 0.005 },
 };
 
+/**
+ * Model-id prefixes KNOWN to accept the sampling parameters (`temperature`,
+ * `top_p`, `top_k`). Anything not on this list is sent WITHOUT them.
+ *
+ * WHY AN ALLOWLIST, NOT A LIST OF MODELS THAT REJECT IT. A deny-list of literal
+ * ids — the shape `OpenAIProvider` uses for its `gpt-5` temperature=1 special
+ * case — is correct exactly until the next model ships, and then it silently
+ * sends a parameter the API refuses. That is not hypothetical: it is the bug
+ * this list exists to fix, and the failure is total (every call 400s) rather
+ * than degraded. Inverting it makes an unknown id — i.e. every future model —
+ * get the request that CANNOT 400. The two error cases are not symmetric:
+ * omitting temperature from a model that would have accepted it costs some
+ * determinism; sending it to a model that rejects it costs the whole feature.
+ *
+ * WHY NOT A VERSION COMPARISON. Measured against api.anthropic.com 2026-08-10:
+ * 4.5 and 4.6 accept `temperature`; 4.7, 4.8 and the entire 5 family return
+ * `400 \`temperature\` is deprecated for this model.` The boundary sits between
+ * 4.6 and 4.7, which no plausible "removed in v5" or "removed in 4.8" rule
+ * predicts — so this is recorded from observation, not derived from a guess.
+ *
+ * The list is also closed in the direction that matters: it can only ever go
+ * stale by omitting a NEW model that would have accepted the parameter, never
+ * by naming one that rejects it. Should that happen, the retry in `generate()`
+ * covers it without a release.
+ */
+const SAMPLING_PARAM_MODEL_PREFIXES = [
+  'claude-3',
+  'claude-opus-4-5',
+  'claude-opus-4-6',
+  'claude-sonnet-4-5',
+  'claude-sonnet-4-6',
+  'claude-haiku-4-5',
+  'claude-haiku-4-6',
+  'claude-opus-4-2025',
+  'claude-sonnet-4-2025',
+  'claude-opus-4-1',
+] as const;
+
+/** True when `model` is known to accept `temperature` / `top_p` / `top_k`. */
+export function supportsSamplingParams(model: string): boolean {
+  const id = model.trim().toLowerCase();
+  return SAMPLING_PARAM_MODEL_PREFIXES.some((prefix) => id.startsWith(prefix));
+}
+
+/**
+ * The parameter named by a "deprecated for this model" 400, if that is what the
+ * error is. Anthropic's message is `` `temperature` is deprecated for this model. ``
+ * and the same wording covers `top_p` and `top_k`, so one matcher handles every
+ * sampling parameter — including ones not yet deprecated when this was written.
+ */
+export function deprecatedParameter(message: string): string | null {
+  const match = /`([a-z_]+)`\s+is\s+deprecated\s+for\s+this\s+model/i.exec(message);
+  return match ? match[1] : null;
+}
+
 const DEFAULTS = {
   baseUrl: 'https://api.anthropic.com/v1',
   model: LLM_DEFAULTS.anthropicModel,
@@ -133,35 +201,32 @@ Please respond with a valid JSON object only. Do not include any text before or
       max_tokens: maxTokens,
       messages: [{ role: 'user', content: jsonWrappedPrompt }],
       system: systemPrompt,
-      temperature,
     };
-
-    const controller = new AbortController();
-    const timeoutId = setTimeout(() => controller.abort(), timeout);
+    // Only for models known to take it. The Claude 5 family answers a request
+    // carrying `temperature` with a 400 and nothing else.
+    if (supportsSamplingParams(model)) {
+      requestBody.temperature = temperature;
+    }
 
     try {
-      const response = await fetch(`${this.config.baseUrl}/messages`, {
-        method: 'POST',
-        headers: {
-          'Content-Type': 'application/json',
-          'x-api-key': this.config.apiKey,
-          'anthropic-version': this.apiVersion,
-        },
-        body: JSON.stringify(requestBody),
-        signal: controller.signal,
-      });
-
-      clearTimeout(timeoutId);
-
-      if (!response.ok) {
-        const errorData = (await response.json().catch(() => ({
-          error: { type: 'unknown', message: 'Unknown error' },
-        }))) as AnthropicErrorResponse;
-        throw this.handleApiError(response.status, errorData);
+      let data: AnthropicResponse;
+      try {
+        data = await this.post(requestBody, timeout);
+      } catch (error) {
+        // SAFETY NET for a parameter the API has since stopped accepting on a
+        // model the allowlist still vouches for. It also covers parameters this
+        // provider does not send today (`top_p`, `top_k`), so adding one later
+        // cannot reintroduce this failure. One retry, only when the API itself
+        // named the offending key — never a blind resend.
+        const param =
+          error instanceof LLMProviderError && error.statusCode === 400
+            ? deprecatedParameter(error.message)
+            : null;
+        if (!param || !(param in requestBody)) throw error;
+        delete (requestBody as unknown as Record<string, unknown>)[param];
+        data = await this.post(requestBody, timeout);
       }
 
-      const data = (await response.json()) as AnthropicResponse;
-
       const textContent = data.content.find((c) => c.type === 'text');
       if (!textContent?.text) {
         throw new LLMProviderError(
@@ -185,8 +250,6 @@ Please respond with a valid JSON object only. Do not include any text before or
         finishReason: data.stop_reason ?? undefined,
       };
     } catch (error) {
-      clearTimeout(timeoutId);
-
       if (error instanceof LLMProviderError) {
         throw error;
       }
@@ -211,6 +274,39 @@ Please respond with a valid JSON object only. Do not include any text before or
     }
   }
 
+  /**
+   * One POST to /messages. Each attempt gets its own timeout — a retry that
+   * strips a rejected parameter is a fresh request, and inheriting an
+   * already-consumed deadline would abort it before it could succeed.
+   */
+  private async post(body: AnthropicRequest, timeout: number): Promise<AnthropicResponse> {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), timeout);
+    try {
+      const response = await fetch(`${this.config.baseUrl}/messages`, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'x-api-key': this.config.apiKey,
+          'anthropic-version': this.apiVersion,
+        },
+        body: JSON.stringify(body),
+        signal: controller.signal,
+      });
+
+      if (!response.ok) {
+        const errorData = (await response.json().catch(() => ({
+          error: { type: 'unknown', message: 'Unknown error' },
+        }))) as AnthropicErrorResponse;
+        throw this.handleApiError(response.status, errorData);
+      }
+
+      return (await response.json()) as AnthropicResponse;
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  }
+
   estimateCost(
     promptTokens: number,
     completionTokens: number,
@@ -269,5 +365,13 @@ export function createAnthropicProvider(): AnthropicProvider | null {
     apiKey,
     baseUrl: process.env.ANTHROPIC_BASE_URL,
     defaultModel: process.env.ANTHROPIC_MODEL,
+    // A DEPLOYMENT CAN BUY ITSELF MORE TIME, and one needs to. The 60-second
+    // default is right for an interactive answer and wrong for a batch job: a
+    // commitment-extraction call over two meeting summaries takes longer than
+    // that (measured — one document 19.6s, two documents timed out), and the
+    // failure is silent, because the caller is written to keep its deterministic
+    // half when the model is unreachable. So the symptom of "too big a batch" is
+    // an extraction that quietly finds nothing.
+    timeoutMs: Number(process.env.LLM_TIMEOUT_MS) || undefined,
   });
 }

package/src/providers/openai.ts

@@ -430,5 +430,9 @@ export function createOpenAIProvider(): OpenAIProvider | null {
     apiKey,
     baseUrl: process.env.OPENAI_BASE_URL,
     defaultModel: process.env.OPENAI_MODEL,
+    // Same knob as the Anthropic factory next door — one provider honouring a
+    // 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,
   });
 }

package/src/types.ts

@@ -133,11 +133,17 @@ export interface LLMServiceConfig {
  */
 export const LLM_DEFAULTS = {
   openaiModel: 'gpt-4o-mini',
-  anthropicModel: 'claude-sonnet-4-20250514',
+  /**
+   * The previous default, `claude-sonnet-4-20250514`, was retired and returns
+   * 404 — a default nobody can call. Verified callable 2026-08-10.
+   */
+  anthropicModel: 'claude-sonnet-5',
   /**
    * Default sampling temperature.
    * Note: base gpt-5 models (gpt-5, gpt-5.1, gpt-5.2) require temperature=1.0
-   * and the OpenAI provider enforces this automatically.
+   * and the OpenAI provider enforces this automatically. On Anthropic the
+   * parameter is not sent at all to models that reject it (Claude 4.7+),
+   * so this is a request, not a guarantee — see providers/anthropic.ts.
    */
   temperature: 0.7,
   maxTokens: 8192,