llm-retry-kit 0.2.0 → 0.3.0

package/README.md

@@ -1,15 +1,59 @@
 # llm-retry-kit
 
-Small resilience layer for production LLM calls. It gives you retries,
-provider fallback, jittered exponential backoff, `Retry-After` handling,
-budget tracking, cancellation, timeouts, and observability hooks.
-
-## Install
+[![npm](https://img.shields.io/npm/v/llm-retry-kit?label=npm)](https://www.npmjs.com/package/llm-retry-kit)
+[![downloads](https://img.shields.io/npm/dm/llm-retry-kit?label=downloads)](https://www.npmjs.com/package/llm-retry-kit)
+[![license](https://img.shields.io/npm/l/llm-retry-kit?label=license)](./LICENSE)
+[![node](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](./package.json)
+[![TypeScript](https://img.shields.io/badge/TypeScript-strict-blue)](./tsconfig.json)
+[![CI](https://img.shields.io/github/actions/workflow/status/JavadRostami3/llm-retry-kit/ci.yml?label=CI)](https://github.com/JavadRostami3/llm-retry-kit/actions)
+
+Small resilience layer for production LLM calls. `llm-retry-kit` gives you
+provider-aware retries, fallback chains, jittered exponential backoff,
+`Retry-After` handling, streaming retries, circuit breakers, hedged requests,
+budget tracking, cancellation, timeouts, and observability hooks without
+runtime dependencies.
 
 ```bash
 npm install llm-retry-kit
 ```
 
+## Why llm-retry-kit?
+
+LLM APIs fail in ways that normal API wrappers often do not model well:
+
+- `429` rate limits need backoff, not immediate loops.
+- `500`, `503`, `504`, and Anthropic `529 overloaded_error` are usually
+  transient and often worth retrying or failing over.
+- `400`, `401`, `403`, and request-too-large errors are usually request or
+  credential problems and should not blindly retry or fallback.
+- Failed retry attempts can still count toward provider rate limits.
+- Production apps need cancellation, budget limits, and logs around every
+  attempt.
+
+This package keeps the core primitive small: you provide the actual SDK call,
+and `llm-retry-kit` manages the reliability policy around it.
+
+## Features
+
+- Retry transient LLM failures with exponential backoff and jitter.
+- Respect `Retry-After` headers from provider errors.
+- Chain named providers or models with explicit fallback behavior.
+- Avoid fallback on non-transient client errors by default.
+- Customize retry and fallback decisions with `shouldRetry` and
+  `shouldFallback`.
+- Track token usage and estimated cost.
+- Use custom input/output token pricing through `costCalculator`.
+- Wrap streaming responses with retry-before-first-chunk safety.
+- Track partial stream token usage from provider events.
+- Skip unhealthy providers with `CircuitBreaker`.
+- Set timeout budgets per provider/model.
+- Start hedged requests to reduce tail latency.
+- Pass request `meta` and `payload` through every context for logging.
+- Abort long calls and retry sleeps with `AbortSignal` or `timeoutMs`.
+- Observe attempts, retries, success, failure, and budget events.
+- Strict TypeScript types.
+- ESM package with no runtime dependencies.
+
 ## Quick Start
 
 ```ts
@@ -40,64 +84,257 @@ const result = await llmRetry({
     }
   },
   maxRetries: 3,
+  initialDelayMs: 1000,
+  maxDelayMs: 30000,
 })
 
 console.log(result.data)
 console.log(result.provider)
+console.log(result.attempts)
 console.log(result.totalCostUSD)
 ```
 
-## Provider Fallback Chain
+## Complete Provider Fallback Example
 
-Use `providers` when you want explicit model or vendor failover. Each provider
-can have its own retry count and cost calculator.
+This example tries OpenAI first, then falls back to Anthropic only for transient
+failures. Client errors like invalid requests or bad credentials stop the chain
+by default.
 
 ```ts
+import Anthropic from '@anthropic-ai/sdk'
+import OpenAI from 'openai'
+import { llmRetry } from 'llm-retry-kit'
+
+const openai = new OpenAI()
+const anthropic = new Anthropic()
+
+const prompt = 'Summarize the following support ticket...'
+
 const result = await llmRetry({
   providers: [
     {
-      name: 'openai:gpt-4o',
-      fn: async (context) => callOpenAI(context),
+      name: 'openai:gpt-4o-mini',
       maxRetries: 2,
+      fn: async ({ signal }) => {
+        const response = await openai.chat.completions.create(
+          {
+            model: 'gpt-4o-mini',
+            messages: [{ role: 'user', content: prompt }],
+          },
+          { signal }
+        )
+
+        return {
+          data: response.choices[0]?.message.content ?? '',
+          usage: response.usage
+            ? {
+                promptTokens: response.usage.prompt_tokens,
+                completionTokens: response.usage.completion_tokens,
+                totalTokens: response.usage.total_tokens,
+              }
+            : undefined,
+        }
+      },
     },
     {
-      name: 'anthropic:sonnet',
-      fn: async (context) => callAnthropic(context),
+      name: 'anthropic:claude-sonnet',
       maxRetries: 1,
+      fn: async ({ signal }) => {
+        const response = await anthropic.messages.create(
+          {
+            model: 'claude-sonnet-4-6',
+            max_tokens: 1024,
+            messages: [{ role: 'user', content: prompt }],
+          },
+          { signal }
+        )
+
+        const text = response.content
+          .filter((block) => block.type === 'text')
+          .map((block) => block.text)
+          .join('')
+
+        return {
+          data: text,
+          usage: {
+            promptTokens: response.usage.input_tokens,
+            completionTokens: response.usage.output_tokens,
+            totalTokens: response.usage.input_tokens + response.usage.output_tokens,
+          },
+        }
+      },
     },
   ],
+  timeoutMs: 45_000,
 })
 
-console.log(result.provider)
-console.log(result.usedFallback)
+console.log({
+  provider: result.provider,
+  usedFallback: result.usedFallback,
+  attempts: result.attempts,
+  answer: result.data,
+})
 ```
 
-The older `fn` + `fallback` API still works:
+## Streaming
+
+OpenAI and Anthropic both expose streaming APIs, but their event formats and
+resume behavior are provider-specific. `llm-retry-kit` therefore keeps the
+stream wrapper provider-agnostic and conservative:
+
+- By default, it retries only if the stream fails before the first chunk.
+- After a chunk has been yielded, retrying could duplicate output, so it stops
+  unless you explicitly set `retryMode: 'always'`.
+- Token usage can be tracked from stream events with `getChunkUsage`.
+- Use `chunkUsageMode: 'cumulative'` for providers that send cumulative usage
+  snapshots during a stream.
+
+```ts
+import { llmRetryStream } from 'llm-retry-kit'
+
+const result = llmRetryStream({
+  stream: async ({ signal }) => {
+    const stream = await openai.responses.create({
+      model: 'gpt-4o-mini',
+      input: 'Write a short incident summary.',
+      stream: true,
+    }, { signal })
+
+    return stream
+  },
+  retryMode: 'before-first-chunk',
+  getChunkUsage: (event) => {
+    if (!('usage' in event) || !event.usage) return undefined
+
+    return {
+      promptTokens: event.usage.input_tokens ?? 0,
+      completionTokens: event.usage.output_tokens ?? 0,
+      totalTokens: event.usage.total_tokens ?? 0,
+    }
+  },
+  chunkUsageMode: 'cumulative',
+})
+
+for await (const event of result.stream) {
+  // Send provider events to your UI, parser, or SSE response.
+}
+
+console.log(result.getStats())
+```
+
+## Advanced Production Controls
+
+### Circuit Breaker
+
+Keep one `CircuitBreaker` instance per provider/model at application scope. If
+the failure threshold is reached inside the time window, later calls skip that
+provider until the cooldown expires.
+
+```ts
+import { CircuitBreaker, llmRetry } from 'llm-retry-kit'
+
+const openaiBreaker = new CircuitBreaker({
+  failureThreshold: 5,
+  windowMs: 60_000,
+  cooldownMs: 120_000,
+})
+
+await llmRetry({
+  providers: [
+    {
+      name: 'openai:gpt-4o-mini',
+      fn: callOpenAI,
+      circuitBreaker: openaiBreaker,
+    },
+    {
+      name: 'anthropic:claude-sonnet',
+      fn: callAnthropic,
+    },
+  ],
+})
+```
+
+### Per-Provider Timeout
+
+Use global `timeoutMs` for the whole workflow and provider `timeoutMs` for a
+single attempt.
+
+```ts
+await llmRetry({
+  providers: [
+    { name: 'openai:fast', fn: callOpenAI, timeoutMs: 3_000, maxRetries: 1 },
+    { name: 'anthropic:steady', fn: callAnthropic, timeoutMs: 10_000 },
+  ],
+  timeoutMs: 30_000,
+})
+```
+
+### Hedged Requests
+
+Hedging starts the next provider in parallel if the current provider has not
+answered after `hedgeDelayMs`. The first successful response wins and the
+slower request is aborted through the context signal.
+
+```ts
+await llmRetry({
+  providers: [
+    { name: 'primary', fn: callPrimary },
+    { name: 'hedge', fn: callBackup },
+  ],
+  hedgeDelayMs: 750,
+})
+```
+
+Hedging is best for latency-sensitive read paths. It can increase provider
+traffic, so pair it with budget tracking and conservative delay values.
+
+### Metadata And Payload Tracking
+
+Attach request metadata once and it flows into provider calls and hooks.
+
+```ts
+await llmRetry({
+  fn: callModel,
+  meta: { requestId: 'req_123', tenant: 'acme' },
+  payload: { prompt: 'Classify this ticket', userId: 'user_42' },
+  onAttempt: (context) => {
+    console.log(context.meta, context.payload)
+  },
+  onFailure: (error, context) => {
+    console.error(context.meta, error)
+  },
+})
+```
+
+## Simple Fallback API
+
+For smaller apps, `fn` plus `fallback` is still supported.
 
 ```ts
 const result = await llmRetry({
   fn: async () => callPrimaryModel(),
   fallback: async () => callFallbackModel(),
+  maxRetries: 2,
 })
 ```
 
-## Custom Retry Policy
+## Configuration
+
+### Retry Timing
 
 ```ts
-const result = await llmRetry({
+await llmRetry({
   fn: myLLMCall,
-  shouldRetry: (error, context) => {
-    if (error.message.includes('quota exceeded')) return false
-    return context.retryAttempt < context.maxRetries
-  },
+  maxRetries: 4,
+  initialDelayMs: 500,
+  maxDelayMs: 60_000,
 })
 ```
 
-Without `shouldRetry`, the package retries common transient failures such as
-HTTP `408`, `409`, `429`, `5xx`, Anthropic `529`, timeout, network, and
-overload errors.
+Retries use exponential backoff with jitter. If the provider exposes a
+`Retry-After` header, that delay is preferred.
 
-## Timeouts And Cancellation
+### Timeout And Cancellation
 
 ```ts
 const controller = new AbortController()
@@ -109,36 +346,81 @@ const result = await llmRetry({
 })
 ```
 
-`timeoutMs` aborts the wrapper and retry waits. Passing `signal` into your SDK
-call lets the underlying HTTP request stop too, when the SDK supports it.
+`timeoutMs` aborts the wrapper and retry sleeps. Passing `signal` into your SDK
+call also lets the underlying request stop when the SDK supports it.
 
-## Budget Tracking
-
-Simple mode:
+### Budget Tracking
 
 ```ts
 const result = await llmRetry({
   fn: myLLMCall,
   maxCostUSD: 0.5,
   costPer1kTokens: 0.002,
+  onBudgetExceeded: (spent, limit) => {
+    console.warn(`Budget exceeded: $${spent.toFixed(4)} / $${limit}`)
+  },
 })
 ```
 
-Provider pricing is often more nuanced than one flat token price, so production
-apps should prefer `costCalculator`:
+For real provider pricing, prefer `costCalculator`:
 
 ```ts
 const result = await llmRetry({
   fn: myLLMCall,
   costCalculator: (usage) => {
-    const input = usage.promptTokens * 0.00000015
-    const output = usage.completionTokens * 0.0000006
-    return input + output
+    const inputCost = usage.promptTokens * 0.00000015
+    const outputCost = usage.completionTokens * 0.0000006
+    return inputCost + outputCost
+  },
+})
+```
+
+Budget tracking is based on the `usage` object returned by your function. A
+wrapper cannot know the final cost of an in-flight LLM call before the provider
+returns usage, so `maxCostUSD` is a guard for later attempts and fallback calls.
+
+### Custom Retry Policy
+
+Use `context.defaultShouldRetry` to compose with the built-in transient error
+detection.
+
+```ts
+await llmRetry({
+  fn: myLLMCall,
+  shouldRetry: (error, context) => {
+    if (error.message.includes('insufficient quota')) return false
+    return context.defaultShouldRetry
+  },
+})
+```
+
+By default, `llm-retry-kit` retries common transient failures such as HTTP
+`408`, `409`, `429`, `5xx`, Anthropic `529`, timeout, network, and overload
+errors.
+
+### Custom Fallback Policy
+
+Fallback is a separate decision from retry. By default, fallback is allowed only
+after transient failures. If you intentionally want to fallback for a known
+client-side case, opt in explicitly.
+
+```ts
+await llmRetry({
+  providers: [
+    { name: 'small-context-model', fn: callSmallModel },
+    { name: 'large-context-model', fn: callLargeModel },
+  ],
+  shouldFallback: (error, context) => {
+    if (error.message.includes('context length')) {
+      return context.nextProvider === 'large-context-model'
+    }
+
+    return context.defaultShouldFallback
   },
 })
 ```
 
-## Observability
+### Observability
 
 ```ts
 await llmRetry({
@@ -153,13 +435,13 @@ await llmRetry({
   onSuccess: (context) => {
     console.log(`Cost so far: $${context.totalCostUSD}`)
   },
-  onFailure: (error) => {
-    console.error(error)
+  onFailure: (error, context) => {
+    console.error(context.meta, error)
   },
 })
 ```
 
-## API
+## API Reference
 
 ### `llmRetry(options)`
 
@@ -175,14 +457,64 @@ await llmRetry({
 | `initialDelayMs` | `number` | `1000` | Initial retry delay. |
 | `maxDelayMs` | `number` | `30000` | Maximum retry delay. |
 | `timeoutMs` | `number` | optional | Abort wrapper after this time. |
+| `hedgeDelayMs` | `number` | optional | Start the next provider after this delay if the current provider is still pending. |
 | `signal` | `AbortSignal` | optional | External cancellation signal. |
+| `meta` | `unknown` | optional | User metadata copied into attempt/failure contexts. |
+| `payload` | `unknown` | optional | Request payload copied into attempt/failure contexts. |
 | `shouldRetry` | `(error, context) => boolean \| Promise<boolean>` | optional | Override retry decisions. |
+| `shouldFallback` | `(error, context) => boolean \| Promise<boolean>` | optional | Override provider fallback decisions. |
 | `onAttempt` | `(context) => void` | optional | Called before each attempt. |
 | `onRetry` | `(attempt, error, delayMs, context) => void` | optional | Called before retry wait. |
 | `onSuccess` | `(context) => void` | optional | Called after a successful response. |
-| `onFailure` | `(error) => void` | optional | Called before final failure is thrown. |
+| `onFailure` | `(error, context) => void` | optional | Called before final failure is thrown. |
 | `onBudgetExceeded` | `(spentUSD, limitUSD) => void` | optional | Called when budget is exhausted. |
 
+### `RetryProvider<T>`
+
+```ts
+{
+  name: string
+  fn: (context: RetryAttemptContext) => Promise<LLMResponse<T>>
+  maxRetries?: number
+  timeoutMs?: number
+  hedgeDelayMs?: number
+  circuitBreaker?: CircuitBreaker | CircuitBreakerOptions
+  costPer1kTokens?: number
+  costCalculator?: (usage, context) => number
+}
+```
+
+### `llmRetryStream(options)`
+
+Returns `{ stream, getStats }`. The request begins when the returned async
+iterable is consumed.
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `stream` | `(context) => AsyncIterable<TChunk> \| Promise<AsyncIterable<TChunk>>` | optional | Primary stream call for the simple API. |
+| `fallbackStream` | `(context) => AsyncIterable<TChunk> \| Promise<AsyncIterable<TChunk>>` | optional | Backup stream call. |
+| `providers` | `StreamRetryProvider<TChunk>[]` | optional | Explicit stream provider chain. |
+| `retryMode` | `'before-first-chunk' \| 'always' \| 'never'` | `'before-first-chunk'` | Controls whether interrupted streams are retried. |
+| `getChunkUsage` | `(chunk, context) => TokenUsage \| undefined` | optional | Extract token usage from stream chunks/events. |
+| `chunkUsageMode` | `'delta' \| 'cumulative'` | `'delta'` | Interpret chunk usage as incremental or cumulative. |
+| `maxRetries` | `number` | `3` | Retries after the first attempt. |
+| `timeoutMs` | `number` | optional | Abort the whole stream workflow after this time. |
+| `meta` | `unknown` | optional | User metadata copied into contexts. |
+| `payload` | `unknown` | optional | Request payload copied into contexts. |
+
+### `CircuitBreaker`
+
+```ts
+new CircuitBreaker({
+  failureThreshold: 5,
+  windowMs: 60_000,
+  cooldownMs: 120_000,
+})
+```
+
+`snapshot()` returns `{ state, failures, openedAt }`, where state is
+`'closed'`, `'open'`, or `'half_open'`.
+
 ### `RetryResult<T>`
 
 ```ts
@@ -196,11 +528,43 @@ await llmRetry({
 }
 ```
 
-## Notes
+### `LLMRetryError`
 
-Budget tracking is based on the `usage` object returned by your function. A
-wrapper cannot know the final cost of an in-flight LLM call before the provider
-returns usage, so `maxCostUSD` is a guard for later attempts and fallback calls.
+```ts
+{
+  name: 'LLMRetryError'
+  primaryError: Error | null
+  fallbackError: Error | null
+  totalCostUSD: number
+  totalTokens: number
+  attempts: number
+  providers: string[]
+  reason: 'failure' | 'budget_exceeded' | 'aborted'
+}
+```
+
+## Defaults
+
+| Setting | Default |
+| --- | --- |
+| `maxRetries` | `3` |
+| `initialDelayMs` | `1000` |
+| `maxDelayMs` | `30000` |
+| `costPer1kTokens` | `0.002` |
+| stream retry mode | `before-first-chunk` |
+| fallback on client errors | `false` |
+| fallback on transient errors | `true` |
+| runtime dependencies | none |
+
+## Development
+
+```bash
+npm install
+npm run typecheck
+npm test
+npm run build
+npm pack --dry-run
+```
 
 ## License
 

package/dist/backoff.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"backoff.d.ts","sourceRoot":"","sources":["../src/backoff.ts"],"names":[],"mappings":"AAAA,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,MAAM,EACf,cAAc,EAAE,MAAM,EACtB,UAAU,EAAE,MAAM,GACjB,MAAM,CAMR;AAED,wBAAgB,KAAK,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAiBrE;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CA2DxD;AAED,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CA4B/D;AAED,wBAAgB,gBAAgB,IAAI,KAAK,CAIxC"}
+{"version":3,"file":"backoff.d.ts","sourceRoot":"","sources":["../src/backoff.ts"],"names":[],"mappings":"AAAA,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,MAAM,EACf,cAAc,EAAE,MAAM,EACtB,UAAU,EAAE,MAAM,GACjB,MAAM,CAMR;AAED,wBAAgB,KAAK,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAiBrE;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CA2DxD;AAED,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAkC/D;AAED,wBAAgB,gBAAgB,IAAI,KAAK,CAIxC"}

package/dist/backoff.js

@@ -78,11 +78,16 @@ export function extractRetryAfter(error) {
     if (!headerValue) {
         return null;
     }
-    const seconds = Number(headerValue);
+    const trimmedHeaderValue = headerValue.trim();
+    const isNumericDelay = /^\d+(\.\d+)?$/.test(trimmedHeaderValue);
+    const seconds = Number(trimmedHeaderValue);
     if (Number.isFinite(seconds)) {
         return seconds * 1000;
     }
-    const dateMs = Date.parse(headerValue);
+    if (isNumericDelay) {
+        return null;
+    }
+    const dateMs = Date.parse(trimmedHeaderValue);
     if (Number.isFinite(dateMs)) {
         return Math.max(dateMs - Date.now(), 0);
     }

package/dist/backoff.js.map

@@ -1 +1 @@
-{"version":3,"file":"backoff.js","sourceRoot":"","sources":["../src/backoff.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"backoff.js","sourceRoot":"","sources":["../src/backoff.ts"],"names":[],"mappings":"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"}

package/dist/circuit-breaker.d.ts

@@ -0,0 +1,17 @@
+import type { CircuitBreakerOptions, CircuitBreakerSnapshot } from './types.js';
+export declare class CircuitBreaker {
+    private readonly options;
+    private failureTimestamps;
+    private state;
+    private openedAt;
+    constructor(options: CircuitBreakerOptions);
+    canRequest(): boolean;
+    recordSuccess(): void;
+    recordFailure(): void;
+    snapshot(): CircuitBreakerSnapshot;
+}
+export declare class CircuitBreakerOpenError extends Error {
+    readonly provider: string;
+    constructor(provider: string);
+}
+//# sourceMappingURL=circuit-breaker.d.ts.map

package/dist/circuit-breaker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"circuit-breaker.d.ts","sourceRoot":"","sources":["../src/circuit-breaker.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,qBAAqB,EACrB,sBAAsB,EAEvB,MAAM,YAAY,CAAA;AAEnB,qBAAa,cAAc;IAKb,OAAO,CAAC,QAAQ,CAAC,OAAO;IAJpC,OAAO,CAAC,iBAAiB,CAAe;IACxC,OAAO,CAAC,KAAK,CAAgC;IAC7C,OAAO,CAAC,QAAQ,CAAsB;gBAET,OAAO,EAAE,qBAAqB;IAI3D,UAAU,IAAI,OAAO;IAcrB,aAAa,IAAI,IAAI;IAMrB,aAAa,IAAI,IAAI;IAiBrB,QAAQ,IAAI,sBAAsB;CAOnC;AAED,qBAAa,uBAAwB,SAAQ,KAAK;aACpB,QAAQ,EAAE,MAAM;gBAAhB,QAAQ,EAAE,MAAM;CAI7C"}