llm-retry-kit 0.2.0 → 0.3.0

package/dist/stream.js

@@ -0,0 +1,388 @@
+import { calculateBackoff, createAbortError, extractRetryAfter, isRetryableError, sleep, } from './backoff.js';
+import { BudgetTracker } from './budget.js';
+import { CircuitBreaker, CircuitBreakerOpenError } from './circuit-breaker.js';
+import { BudgetExceededError, LLMRetryError, ProviderTimeoutError } from './retry.js';
+export function llmRetryStream(options) {
+    const stats = {
+        attempts: 0,
+        usedFallback: false,
+        totalCostUSD: 0,
+        totalTokens: 0,
+        chunks: 0,
+        completed: false,
+    };
+    return {
+        stream: createRetryingStream(options, stats),
+        getStats: () => ({ ...stats }),
+    };
+}
+async function* createRetryingStream(options, stats) {
+    const { maxRetries = 3, maxCostUSD, costPer1kTokens = 0.002, initialDelayMs = 1000, maxDelayMs = 30000, timeoutMs, signal, meta, payload, retryMode = 'before-first-chunk', chunkUsageMode = 'delta', getChunkUsage, shouldRetry, shouldFallback, onAttempt, onRetry, onChunk, onSuccess, onFailure, onBudgetExceeded, } = options;
+    validateStreamOptions({ maxRetries, initialDelayMs, maxDelayMs, timeoutMs });
+    const providers = normalizeStreamProviders(options, maxRetries);
+    validateStreamProviders(providers);
+    const startedAt = Date.now();
+    const budget = new BudgetTracker(costPer1kTokens, maxCostUSD);
+    const runtimeSignal = createRuntimeSignal(signal, timeoutMs);
+    let lastError = null;
+    let primaryError = null;
+    let fallbackError = null;
+    let budgetExceededNotified = false;
+    try {
+        for (let providerIndex = 0; providerIndex < providers.length; providerIndex++) {
+            const provider = providers[providerIndex];
+            const providerMaxRetries = provider.maxRetries ?? maxRetries;
+            let providerShouldFallback = false;
+            if (provider.circuitBreaker && !provider.circuitBreaker.canRequest()) {
+                const err = new CircuitBreakerOpenError(provider.name);
+                lastError = err;
+                if (providerIndex === 0) {
+                    primaryError = err;
+                }
+                else {
+                    fallbackError = err;
+                }
+                if (providerIndex < providers.length - 1) {
+                    continue;
+                }
+                break;
+            }
+            for (let retryAttempt = 0; retryAttempt <= providerMaxRetries; retryAttempt++) {
+                if (runtimeSignal.signal?.aborted) {
+                    throw createAbortError();
+                }
+                if (budget.isExceeded()) {
+                    budgetExceededNotified = notifyBudgetExceeded(budget.spent, budget.limit, onBudgetExceeded, budgetExceededNotified);
+                    throw new BudgetExceededError(budget.spent, budget.limit);
+                }
+                stats.attempts += 1;
+                const attemptSignal = createAttemptSignal(runtimeSignal.signal, provider.timeoutMs);
+                const context = createAttemptContext({
+                    attempt: stats.attempts,
+                    retryAttempt,
+                    provider,
+                    providerIndex,
+                    startedAt,
+                    signal: attemptSignal.signal,
+                    lastError,
+                    meta,
+                    payload,
+                });
+                onAttempt?.(context);
+                let emittedChunk = false;
+                let previousCumulativeUsage = null;
+                try {
+                    const iterable = await runWithAbort(Promise.resolve(provider.stream(context)), attemptSignal.signal);
+                    for await (const chunk of iterateWithAbort(iterable, attemptSignal.signal)) {
+                        emittedChunk = true;
+                        stats.chunks += 1;
+                        stats.provider = provider.name;
+                        stats.usedFallback = providerIndex > 0;
+                        const usage = getChunkUsage?.(chunk, context);
+                        if (usage) {
+                            const usageToAdd = chunkUsageMode === 'cumulative'
+                                ? diffCumulativeUsage(usage, previousCumulativeUsage)
+                                : usage;
+                            previousCumulativeUsage = usage;
+                            trackStreamUsage({
+                                usage: usageToAdd,
+                                context,
+                                provider,
+                                defaultCostPer1kTokens: costPer1kTokens,
+                                defaultCostCalculator: options.costCalculator,
+                                budget,
+                                stats,
+                            });
+                            if (budget.isExceeded()) {
+                                budgetExceededNotified = notifyBudgetExceeded(budget.spent, budget.limit, onBudgetExceeded, budgetExceededNotified);
+                                throw new BudgetExceededError(budget.spent, budget.limit);
+                            }
+                        }
+                        onChunk?.(chunk, context);
+                        yield chunk;
+                    }
+                    provider.circuitBreaker?.recordSuccess();
+                    stats.completed = true;
+                    stats.provider = provider.name;
+                    stats.usedFallback = providerIndex > 0;
+                    onSuccess?.({
+                        ...context,
+                        costUSD: 0,
+                        totalCostUSD: budget.spent,
+                        totalTokens: budget.tokens,
+                    });
+                    return;
+                }
+                catch (error) {
+                    const err = error instanceof Error ? error : new Error(String(error));
+                    lastError = err;
+                    stats.lastError = err;
+                    provider.circuitBreaker?.recordFailure();
+                    if (providerIndex === 0) {
+                        primaryError = err;
+                    }
+                    else {
+                        fallbackError = err;
+                    }
+                    const canRepeatStream = retryMode === 'always' || (!emittedChunk && retryMode === 'before-first-chunk');
+                    if (!canRepeatStream) {
+                        throw err;
+                    }
+                    const decisionContext = {
+                        ...context,
+                        maxRetries: providerMaxRetries,
+                        defaultShouldRetry: isRetryableError(err),
+                    };
+                    const retry = await shouldRetryAttempt({
+                        error: err,
+                        context: decisionContext,
+                        shouldRetry,
+                        retryAttempt,
+                        maxRetries: providerMaxRetries,
+                    });
+                    if (!retry) {
+                        providerShouldFallback = await shouldFallbackFromProvider({
+                            error: err,
+                            context,
+                            nextProvider: providers[providerIndex + 1],
+                            nextProviderIndex: providerIndex + 1,
+                            shouldFallback,
+                        });
+                        break;
+                    }
+                    const serverDelay = extractRetryAfter(err);
+                    const delay = serverDelay ?? calculateBackoff(retryAttempt, initialDelayMs, maxDelayMs);
+                    onRetry?.(stats.attempts, err, delay, decisionContext);
+                    await sleep(delay, runtimeSignal.signal);
+                }
+                finally {
+                    attemptSignal.cleanup();
+                }
+            }
+            if (providerIndex < providers.length - 1 && !providerShouldFallback) {
+                break;
+            }
+        }
+        throw new Error(lastError?.message ?? 'No provider returned a successful stream');
+    }
+    catch (error) {
+        const err = error instanceof Error ? error : new Error(String(error));
+        const retryError = new LLMRetryError(`LLM stream failed after ${stats.attempts} attempt${stats.attempts === 1 ? '' : 's'}: ${err.message}`, primaryError ?? lastError, fallbackError, budget.spent, budget.tokens, stats.attempts, providers.map((provider) => provider.name), getFailureReason(err));
+        const failureContext = {
+            attempts: stats.attempts,
+            totalCostUSD: budget.spent,
+            totalTokens: budget.tokens,
+            providers: providers.map((provider) => provider.name),
+            meta,
+            payload,
+        };
+        onFailure?.(retryError, failureContext);
+        throw retryError;
+    }
+    finally {
+        stats.totalCostUSD = budget.spent;
+        stats.totalTokens = budget.tokens;
+        runtimeSignal.cleanup();
+    }
+}
+function normalizeStreamProviders(options, defaultMaxRetries) {
+    if (options.providers && options.providers.length > 0) {
+        if (options.stream || options.fallbackStream) {
+            throw new Error('Use either providers or stream/fallbackStream, not both');
+        }
+        return options.providers.map((provider) => ({
+            ...provider,
+            maxRetries: provider.maxRetries ?? defaultMaxRetries,
+            circuitBreaker: normalizeCircuitBreaker(provider.circuitBreaker),
+        }));
+    }
+    if (!options.stream) {
+        throw new Error('llmRetryStream requires stream or at least one provider');
+    }
+    const providers = [
+        {
+            name: 'primary',
+            stream: options.stream,
+            maxRetries: defaultMaxRetries,
+            costCalculator: options.costCalculator,
+            costPer1kTokens: options.costPer1kTokens,
+        },
+    ];
+    if (options.fallbackStream) {
+        providers.push({
+            name: 'fallback',
+            stream: options.fallbackStream,
+            maxRetries: 0,
+            costCalculator: options.costCalculator,
+            costPer1kTokens: options.costPer1kTokens,
+        });
+    }
+    return providers;
+}
+async function* iterateWithAbort(iterable, signal) {
+    for await (const chunk of iterable) {
+        if (signal.aborted) {
+            throw getAbortReason(signal);
+        }
+        yield chunk;
+    }
+}
+async function shouldRetryAttempt(options) {
+    if (options.error.name === 'AbortError') {
+        return false;
+    }
+    if (options.retryAttempt >= options.maxRetries) {
+        return false;
+    }
+    if (options.shouldRetry) {
+        return options.shouldRetry(options.error, options.context);
+    }
+    return isRetryableError(options.error);
+}
+async function shouldFallbackFromProvider(options) {
+    if (!options.nextProvider) {
+        return false;
+    }
+    const fallbackContext = {
+        ...options.context,
+        defaultShouldFallback: isRetryableError(options.error),
+        nextProvider: options.nextProvider.name,
+        nextProviderIndex: options.nextProviderIndex,
+    };
+    if (options.shouldFallback) {
+        return options.shouldFallback(options.error, fallbackContext);
+    }
+    return fallbackContext.defaultShouldFallback;
+}
+function trackStreamUsage(options) {
+    const calculator = options.provider.costCalculator ?? options.defaultCostCalculator;
+    const costUSD = calculator
+        ? calculator(options.usage, options.context)
+        : (options.usage.totalTokens / 1000) *
+            (options.provider.costPer1kTokens ?? options.defaultCostPer1kTokens);
+    options.budget.add(options.usage, costUSD);
+    options.stats.totalCostUSD = options.budget.spent;
+    options.stats.totalTokens = options.budget.tokens;
+}
+function diffCumulativeUsage(current, previous) {
+    if (!previous) {
+        return current;
+    }
+    return {
+        promptTokens: Math.max(current.promptTokens - previous.promptTokens, 0),
+        completionTokens: Math.max(current.completionTokens - previous.completionTokens, 0),
+        totalTokens: Math.max(current.totalTokens - previous.totalTokens, 0),
+    };
+}
+function createAttemptContext(options) {
+    return {
+        attempt: options.attempt,
+        retryAttempt: options.retryAttempt,
+        provider: options.provider.name,
+        providerIndex: options.providerIndex,
+        elapsedMs: Date.now() - options.startedAt,
+        signal: options.signal,
+        lastError: options.lastError ?? undefined,
+        meta: options.meta,
+        payload: options.payload,
+    };
+}
+function runWithAbort(promise, signal) {
+    if (signal.aborted) {
+        return Promise.reject(getAbortReason(signal));
+    }
+    return new Promise((resolve, reject) => {
+        const abort = () => reject(getAbortReason(signal));
+        signal.addEventListener('abort', abort, { once: true });
+        promise.then((value) => {
+            signal.removeEventListener('abort', abort);
+            resolve(value);
+        }, (error) => {
+            signal.removeEventListener('abort', abort);
+            reject(error);
+        });
+    });
+}
+function createAttemptSignal(parentSignal, timeoutMs) {
+    const controller = new AbortController();
+    const timeout = timeoutMs === undefined
+        ? null
+        : setTimeout(() => controller.abort(new ProviderTimeoutError(timeoutMs)), timeoutMs);
+    const abortFromParent = () => controller.abort(getAbortReason(parentSignal));
+    parentSignal?.addEventListener('abort', abortFromParent, { once: true });
+    return {
+        signal: controller.signal,
+        cleanup: () => {
+            if (timeout) {
+                clearTimeout(timeout);
+            }
+            parentSignal?.removeEventListener('abort', abortFromParent);
+        },
+    };
+}
+function createRuntimeSignal(signal, timeoutMs) {
+    if (timeoutMs === undefined) {
+        return { signal, cleanup: () => undefined };
+    }
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(createAbortError()), timeoutMs);
+    const abortFromParent = () => controller.abort(getAbortReason(signal));
+    signal?.addEventListener('abort', abortFromParent, { once: true });
+    return {
+        signal: controller.signal,
+        cleanup: () => {
+            clearTimeout(timeout);
+            signal?.removeEventListener('abort', abortFromParent);
+        },
+    };
+}
+function getAbortReason(signal) {
+    const reason = signal?.reason;
+    return reason instanceof Error ? reason : createAbortError();
+}
+function notifyBudgetExceeded(spentUSD, limitUSD, callback, alreadyNotified) {
+    if (!alreadyNotified && limitUSD !== null) {
+        callback?.(spentUSD, limitUSD);
+    }
+    return true;
+}
+function normalizeCircuitBreaker(circuitBreaker) {
+    if (!circuitBreaker) {
+        return undefined;
+    }
+    if ('canRequest' in circuitBreaker) {
+        return circuitBreaker;
+    }
+    return new CircuitBreaker(circuitBreaker);
+}
+function validateStreamOptions(options) {
+    if (!Number.isInteger(options.maxRetries) || options.maxRetries < 0) {
+        throw new Error('maxRetries must be a non-negative integer');
+    }
+    if (options.initialDelayMs < 0) {
+        throw new Error('initialDelayMs must be greater than or equal to 0');
+    }
+    if (options.maxDelayMs < options.initialDelayMs) {
+        throw new Error('maxDelayMs must be greater than or equal to initialDelayMs');
+    }
+    if (options.timeoutMs !== undefined && options.timeoutMs < 0) {
+        throw new Error('timeoutMs must be greater than or equal to 0');
+    }
+}
+function validateStreamProviders(providers) {
+    providers.forEach((provider) => {
+        if (provider.timeoutMs !== undefined && provider.timeoutMs < 0) {
+            throw new Error(`timeoutMs for provider "${provider.name}" must be greater than or equal to 0`);
+        }
+    });
+}
+function getFailureReason(error) {
+    if (error instanceof BudgetExceededError) {
+        return 'budget_exceeded';
+    }
+    if (error.name === 'AbortError') {
+        return 'aborted';
+    }
+    return 'failure';
+}
+//# sourceMappingURL=stream.js.map

package/dist/stream.js.map

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

package/dist/types.d.ts

@@ -15,25 +15,62 @@ export interface RetryAttemptContext {
     elapsedMs: number;
     signal?: AbortSignal;
     lastError?: Error;
+    meta?: unknown;
+    payload?: unknown;
 }
 export interface RetryDecisionContext extends RetryAttemptContext {
     maxRetries: number;
+    defaultShouldRetry: boolean;
+}
+export interface FallbackDecisionContext extends RetryAttemptContext {
+    defaultShouldFallback: boolean;
+    nextProvider?: string;
+    nextProviderIndex?: number;
 }
 export interface RetrySuccessContext extends RetryAttemptContext {
     costUSD: number;
     totalCostUSD: number;
     totalTokens: number;
 }
+export interface RetryFailureContext {
+    attempts: number;
+    totalCostUSD: number;
+    totalTokens: number;
+    providers: string[];
+    meta?: unknown;
+    payload?: unknown;
+}
 export type LLMCall<T = unknown> = (context: RetryAttemptContext) => Promise<LLMResponse<T>>;
 export type CostCalculator = (usage: TokenUsage, context: RetryAttemptContext) => number;
 export type ShouldRetry = (error: Error, context: RetryDecisionContext) => boolean | Promise<boolean>;
+export type ShouldFallback = (error: Error, context: FallbackDecisionContext) => boolean | Promise<boolean>;
 export interface RetryProvider<T = unknown> {
     name: string;
     fn: LLMCall<T>;
     maxRetries?: number;
+    timeoutMs?: number;
+    hedgeDelayMs?: number;
+    circuitBreaker?: CircuitBreakerOptions | CircuitBreakerLike;
     costPer1kTokens?: number;
     costCalculator?: CostCalculator;
 }
+export interface CircuitBreakerOptions {
+    failureThreshold: number;
+    windowMs: number;
+    cooldownMs: number;
+}
+export type CircuitBreakerState = 'closed' | 'open' | 'half_open';
+export interface CircuitBreakerSnapshot {
+    state: CircuitBreakerState;
+    failures: number;
+    openedAt: number | null;
+}
+export interface CircuitBreakerLike {
+    canRequest: () => boolean;
+    recordSuccess: () => void;
+    recordFailure: () => void;
+    snapshot?: () => CircuitBreakerSnapshot;
+}
 export interface RetryOptions<T = unknown> {
     fn?: LLMCall<T>;
     fallback?: LLMCall<T>;
@@ -45,12 +82,16 @@ export interface RetryOptions<T = unknown> {
     initialDelayMs?: number;
     maxDelayMs?: number;
     timeoutMs?: number;
+    hedgeDelayMs?: number;
     signal?: AbortSignal;
+    meta?: unknown;
+    payload?: unknown;
     shouldRetry?: ShouldRetry;
+    shouldFallback?: ShouldFallback;
     onAttempt?: (context: RetryAttemptContext) => void;
     onRetry?: (attempt: number, error: Error, delayMs: number, context: RetryDecisionContext) => void;
     onSuccess?: (context: RetrySuccessContext) => void;
-    onFailure?: (error: Error) => void;
+    onFailure?: (error: Error, context: RetryFailureContext) => void;
     onBudgetExceeded?: (spentUSD: number, limitUSD: number) => void;
 }
 export interface RetryResult<T = unknown> {
@@ -62,4 +103,57 @@ export interface RetryResult<T = unknown> {
     totalTokens: number;
 }
 export type RetryableError = 'rate_limit' | 'server_error' | 'timeout' | 'network_error' | 'conflict' | 'overloaded';
+export type StreamRetryMode = 'before-first-chunk' | 'always' | 'never';
+export type StreamUsageMode = 'delta' | 'cumulative';
+export type StreamLLMCall<TChunk = unknown> = (context: RetryAttemptContext) => AsyncIterable<TChunk> | Promise<AsyncIterable<TChunk>>;
+export type StreamUsageExtractor<TChunk = unknown> = (chunk: TChunk, context: RetryAttemptContext) => TokenUsage | undefined;
+export interface StreamRetryProvider<TChunk = unknown> {
+    name: string;
+    stream: StreamLLMCall<TChunk>;
+    maxRetries?: number;
+    timeoutMs?: number;
+    circuitBreaker?: CircuitBreakerOptions | CircuitBreakerLike;
+    costPer1kTokens?: number;
+    costCalculator?: CostCalculator;
+}
+export interface StreamRetryOptions<TChunk = unknown> {
+    stream?: StreamLLMCall<TChunk>;
+    fallbackStream?: StreamLLMCall<TChunk>;
+    providers?: Array<StreamRetryProvider<TChunk>>;
+    maxRetries?: number;
+    maxCostUSD?: number;
+    costPer1kTokens?: number;
+    costCalculator?: CostCalculator;
+    initialDelayMs?: number;
+    maxDelayMs?: number;
+    timeoutMs?: number;
+    signal?: AbortSignal;
+    meta?: unknown;
+    payload?: unknown;
+    retryMode?: StreamRetryMode;
+    getChunkUsage?: StreamUsageExtractor<TChunk>;
+    chunkUsageMode?: StreamUsageMode;
+    shouldRetry?: ShouldRetry;
+    shouldFallback?: ShouldFallback;
+    onAttempt?: (context: RetryAttemptContext) => void;
+    onRetry?: (attempt: number, error: Error, delayMs: number, context: RetryDecisionContext) => void;
+    onChunk?: (chunk: TChunk, context: RetryAttemptContext) => void;
+    onSuccess?: (context: RetrySuccessContext) => void;
+    onFailure?: (error: Error, context: RetryFailureContext) => void;
+    onBudgetExceeded?: (spentUSD: number, limitUSD: number) => void;
+}
+export interface StreamRetryStats {
+    attempts: number;
+    provider?: string;
+    usedFallback: boolean;
+    totalCostUSD: number;
+    totalTokens: number;
+    chunks: number;
+    completed: boolean;
+    lastError?: Error;
+}
+export interface StreamRetryResult<TChunk = unknown> {
+    stream: AsyncIterable<TChunk>;
+    getStats: () => StreamRetryStats;
+}
 //# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "llm-retry-kit",
-  "version": "0.2.0",
-  "description": "Resilience toolkit for LLM APIs with retries, provider fallback, budget tracking, aborts, and observability.",
+  "version": "0.3.0",
+  "description": "Resilience toolkit for LLM APIs with retries, streaming, provider fallback, circuit breakers, hedging, budget tracking, aborts, and observability.",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -37,15 +37,30 @@
     "retry",
     "rate-limit",
     "fallback",
+    "streaming",
+    "circuit-breaker",
+    "hedged-requests",
+    "latency",
     "backoff",
     "ai",
     "gpt",
     "claude"
   ],
-  "author": "llm-retry contributors",
+  "author": "javadrostami",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/JavadRostami3/llm-retry-kit.git"
+  },
+  "bugs": {
+    "url": "https://github.com/JavadRostami3/llm-retry-kit/issues"
+  },
+  "homepage": "https://github.com/JavadRostami3/llm-retry-kit#readme",
   "devDependencies": {
     "typescript": "^5.4.0",
     "vitest": "^4.1.8"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org"
   }
 }