ai-resilience 0.2.0 → 0.3.0

package/README.md

@@ -1,6 +1,6 @@
 # ai-resilience
 
-`ai-resilience` is an axios-retry++ toolkit for modern AI and backend systems. It keeps axios compatibility while adding configurable retry strategies, advanced jitter, semantic recovery, JSON validation and repair, hooks, structured logging, and strong TypeScript types.
+`ai-resilience` is an axios-retry++ toolkit for modern AI and backend systems. It keeps axios compatibility while adding configurable retry strategies, semantic recovery, provider fallback, circuit breakers, distributed coordination, streaming recovery, telemetry hooks, and strong TypeScript types.
 
 ## Install
 
@@ -52,6 +52,10 @@ const result = await requestWithSemanticRetry(client, {
 - JSON validation, Zod schema validation, and JSON repair
 - AI-aware failure detection for empty responses, refusals, truncation, and schema mismatches
 - AI retry policies and semantic lifecycle hooks
+- Provider fallback for OpenAI, Anthropic, Gemini, or custom providers
+- Circuit breaker, provider health tracking, adaptive fallback delay, and provider metrics
+- Redis-compatible retry coordination and distributed rate limiting through lightweight adapters
+- Adaptive routing, streaming recovery, OpenTelemetry-compatible spans, and advanced metrics
 - TypeScript-first public API
 
 ## API
@@ -100,6 +104,98 @@ Parses JSON strings, optionally repairs common model-output issues, and validate
 
 Installs a response interceptor that validates and repairs successful axios responses. Use `requestWithSemanticRetry` when you also want semantic retries.
 
+### `createProviderFallback(providers, options)`
+
+Creates a provider fallback engine with provider routing, circuit breakers, health tracking, adaptive delay, fallback hooks, and metrics.
+
+```ts
+import { createProviderFallback } from "ai-resilience";
+
+const fallback = createProviderFallback(
+  [
+    {
+      id: "openai-primary",
+      type: "openai",
+      priority: 1,
+      request: (input) => openaiClient.responses.create(input),
+    },
+    {
+      id: "anthropic-backup",
+      type: "anthropic",
+      priority: 2,
+      request: (input) => anthropicClient.messages.create(input),
+    },
+  ],
+  {
+    strategy: "priority",
+    circuitBreaker: { failureThreshold: 3, cooldownMs: 30_000 },
+    hooks: {
+      onProviderFallback: ({ fromProviderId, toProviderId }) => {
+        console.log(`fallback ${fromProviderId} -> ${toProviderId}`);
+      },
+    },
+  },
+);
+
+const response = await fallback.request({ prompt: "Summarize this" });
+const metrics = fallback.snapshot();
+```
+
+### `RedisRetryCoordinator`
+
+Coordinates retries and locks across processes. Pass an `ioredis`-compatible client through the `redis` option, or omit it for local in-memory coordination during tests and development.
+
+```ts
+import { RedisRetryCoordinator } from "ai-resilience";
+
+const coordinator = new RedisRetryCoordinator({
+  namespace: "my-api",
+  redis,
+});
+
+await coordinator.incrementRetry("tenant-a:request-123");
+const locked = await coordinator.acquireLock("provider-routing");
+```
+
+### `DistributedRateLimiter`
+
+Provides Redis-compatible fixed-window rate limiting.
+
+```ts
+import { DistributedRateLimiter } from "ai-resilience";
+
+const limiter = new DistributedRateLimiter(redis);
+const result = await limiter.consume({
+  key: "tenant-a:openai",
+  limit: 100,
+  windowSeconds: 60,
+});
+```
+
+### `AdaptiveRouter`
+
+Ranks providers using latency, failure, and cost signals.
+
+```ts
+import { AdaptiveRouter } from "ai-resilience";
+
+const router = new AdaptiveRouter(providers, {
+  latencyWeight: 1,
+  failureWeight: 2,
+  costWeight: 0.5,
+});
+
+const provider = router.select(metricsByProvider);
+```
+
+### `recoverStream(stream, options)`
+
+Collects streaming chunks and calls recovery hooks when chunk gaps exceed a configured threshold.
+
+### `withTelemetry(tracer, name, operation, attributes)`
+
+Wraps an async operation with an OpenTelemetry-style tracer adapter. This package does not force `@opentelemetry/api` into runtime dependencies; pass a tracer with `startSpan`.
+
 ### Retry config
 
 ```ts