ai-resilience 0.1.3 → 0.3.0

package/README.md

@@ -1,6 +1,6 @@
 # ai-resilience
 
-`ai-resilience` is an axios-retry++ foundation for modern AI and backend systems. It keeps axios compatibility while adding configurable retry strategies, advanced jitter, retry conditions, 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
 
@@ -12,7 +12,8 @@ npm install ai-resilience axios axios-retry
 
 ```ts
 import axios from "axios";
-import { applyAiResilience, ConsoleRetryLogger } from "ai-resilience";
+import { applyAiResilience, ConsoleRetryLogger, requestWithSemanticRetry } from "ai-resilience";
+import { z } from "zod";
 
 const client = axios.create({ baseURL: "https://api.example.com" });
 
@@ -29,6 +30,13 @@ applyAiResilience(client, {
     },
   },
 });
+
+const result = await requestWithSemanticRetry(client, {
+  request: { method: "post", url: "/chat/completions", data: { prompt: "Return JSON" } },
+  schema: z.object({ answer: z.string() }),
+  repairJson: true,
+  requireJson: true,
+});
 ```
 
 ## Features
@@ -40,6 +48,14 @@ applyAiResilience(client, {
 - Async custom retry conditions
 - EventEmitter-based hooks plus direct hook callbacks
 - Structured logger interface and console logger
+- Semantic retry for valid HTTP responses with invalid AI payloads
+- 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
@@ -52,6 +68,134 @@ Installs retry behavior on an existing axios instance and returns `{ axios, hook
 
 Creates a new axios instance with retry behavior already applied.
 
+### `requestWithSemanticRetry(instance, config)`
+
+Runs an axios request and retries when the response is semantically invalid, such as malformed JSON, a schema mismatch, an empty body, a refusal, or a truncated answer.
+
+```ts
+import { requestWithSemanticRetry } from "ai-resilience";
+import { z } from "zod";
+
+const data = await requestWithSemanticRetry(client, {
+  request: { url: "/generate", method: "post", data: { prompt } },
+  schema: z.object({
+    title: z.string(),
+    tags: z.array(z.string()),
+  }),
+  repairJson: true,
+  requireJson: true,
+  hooks: {
+    onSemanticRetry: ({ issue, attempt }) => {
+      console.log(`semantic retry ${attempt}: ${issue.kind}`);
+    },
+  },
+});
+```
+
+### `semanticRetry(operation, policy)`
+
+Wraps any async operation that returns either an axios response or raw data and retries until the payload passes semantic validation.
+
+### `parseJsonResponse(data, options)`
+
+Parses JSON strings, optionally repairs common model-output issues, and validates against a Zod schema.
+
+### `applySemanticRecovery(instance, policy)`
+
+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
@@ -70,6 +214,26 @@ type AiResilienceRetryConfig = {
 };
 ```
 
+### Semantic policy
+
+```ts
+type AiRetryPolicy = {
+  maxSemanticRetries?: number;
+  retryOnFailureKinds?: Array<
+    "invalid_json" | "schema_mismatch" | "empty_response" | "refusal" | "truncated"
+  >;
+  repairJson?: boolean;
+  requireJson?: boolean;
+  detectRefusals?: boolean;
+  detectTruncation?: boolean;
+  schema?: z.ZodType;
+  validate?: (data, response) => SemanticValidationResult | Promise<SemanticValidationResult>;
+  hooks?: SemanticRetryHooks;
+  logger?: RetryLogger;
+  metadata?: Record<string, unknown>;
+};
+```
+
 ## Scripts
 
 ```sh