@elsium-ai/gateway 0.6.0 → 0.7.0

package/README.md

@@ -919,6 +919,14 @@ interface ProviderEntry {
 ### `ProviderMeshConfig`
 
 ```ts
+interface MeshAuditLogger {
+  log(
+    type: string,
+    data: Record<string, unknown>,
+    options?: { actor?: string; traceId?: string },
+  ): void
+}
+
 interface ProviderMeshConfig {
   providers: ProviderEntry[]
   strategy: RoutingStrategy
@@ -928,6 +936,7 @@ interface ProviderMeshConfig {
     complexityThreshold?: number
   }
   circuitBreaker?: CircuitBreakerConfig | boolean
+  audit?: MeshAuditLogger
 }
 ```
 
@@ -937,6 +946,7 @@ interface ProviderMeshConfig {
 | `strategy` | `RoutingStrategy` | Routing strategy to use. |
 | `costOptimizer` | `CostOptimizerConfig` | Configuration for the `cost-optimized` strategy. |
 | `circuitBreaker` | `CircuitBreakerConfig \| boolean` | Enable circuit breakers per provider. Pass `true` for defaults or an object to configure thresholds. |
+| `audit` | `MeshAuditLogger` | Optional audit logger. When provided, the mesh logs `provider_failover` and `circuit_breaker_state_change` events. Compatible with `AuditTrail` from `@elsium-ai/observe`. |
 
 ### `ProviderMesh`
 
@@ -1042,6 +1052,41 @@ const response = await mesh.complete({
 })
 ```
 
+#### Failover Audit Trail
+
+Pass an audit trail to the mesh to get tamper-evident records of every provider failover and circuit breaker state change:
+
+```ts
+import { createProviderMesh } from '@elsium-ai/gateway'
+import { createAuditTrail } from '@elsium-ai/observe'
+
+const audit = createAuditTrail({
+  hashChain: true,
+  batch: { size: 500, intervalMs: 100 },
+})
+
+const mesh = createProviderMesh({
+  providers: [
+    { name: 'anthropic', config: { apiKey: process.env.ANTHROPIC_API_KEY! }, model: 'claude-sonnet-4-6' },
+    { name: 'openai', config: { apiKey: process.env.OPENAI_API_KEY! }, model: 'gpt-4o' },
+  ],
+  strategy: 'fallback',
+  circuitBreaker: { failureThreshold: 5, resetTimeoutMs: 30_000 },
+  audit,
+})
+
+// If Anthropic fails and OpenAI succeeds, the audit trail records:
+//   { type: 'provider_failover', data: { fromProvider: 'anthropic', toProvider: 'openai', strategy: 'fallback', reason: '...' } }
+//
+// If the circuit breaker trips:
+//   { type: 'circuit_breaker_state_change', data: { provider: 'anthropic', fromState: 'closed', toState: 'open' } }
+
+const failovers = await audit.query({ type: 'provider_failover' })
+const breakerEvents = await audit.query({ type: ['circuit_breaker_state_change'] })
+```
+
+The `MeshAuditLogger` interface is intentionally minimal — any object with a `log(type, data, options?)` method works, so you can use `AuditTrail` from `@elsium-ai/observe` or your own logger.
+
 ---
 
 ## Part of ElsiumAI

package/dist/index.d.ts

@@ -19,5 +19,5 @@ export { calculateCost, registerPricing, estimateCost } from './pricing';
 export { createBatch } from './batch';
 export type { BatchConfig, BatchResult, BatchResultItem } from './batch';
 export { createProviderMesh } from './router';
-export type { ProviderMeshConfig, ProviderEntry, RoutingStrategy, ProviderMesh } from './router';
+export type { ProviderMeshConfig, ProviderEntry, RoutingStrategy, ProviderMesh, MeshAuditLogger, } from './router';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAE,uBAAuB,EAAE,MAAM,WAAW,CAAA;AAC5D,YAAY,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAGvD,YAAY,EACX,WAAW,EACX,eAAe,EACf,gBAAgB,EAChB,YAAY,EACZ,SAAS,GACT,MAAM,YAAY,CAAA;AACnB,OAAO,EACN,gBAAgB,EAChB,kBAAkB,EAClB,aAAa,EACb,wBAAwB,EACxB,mBAAmB,GACnB,MAAM,YAAY,CAAA;AAGnB,OAAO,EAAE,uBAAuB,EAAE,MAAM,uBAAuB,CAAA;AAC/D,OAAO,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAA;AACzD,OAAO,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAA;AAGzD,OAAO,EACN,iBAAiB,EACjB,uBAAuB,EACvB,iBAAiB,EACjB,sBAAsB,EACtB,cAAc,GACd,MAAM,cAAc,CAAA;AACrB,YAAY,EAAE,SAAS,EAAE,MAAM,cAAc,CAAA;AAG7C,OAAO,EACN,kBAAkB,EAClB,qBAAqB,EACrB,eAAe,EACf,aAAa,EACb,oBAAoB,EACpB,eAAe,GACf,MAAM,YAAY,CAAA;AACnB,YAAY,EACX,wBAAwB,EACxB,iBAAiB,EACjB,cAAc,EACd,kBAAkB,EAClB,oBAAoB,GACpB,MAAM,YAAY,CAAA;AAGnB,OAAO,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAA;AAC/D,YAAY,EAAE,cAAc,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAA;AAG1D,OAAO,EAAE,eAAe,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAA;AAC9D,YAAY,EAAE,YAAY,EAAE,UAAU,EAAE,qBAAqB,EAAE,MAAM,SAAS,CAAA;AAG9E,OAAO,EAAE,yBAAyB,EAAE,MAAM,qBAAqB,CAAA;AAC/D,YAAY,EACX,qBAAqB,EACrB,mBAAmB,EACnB,eAAe,GACf,MAAM,qBAAqB,CAAA;AAG5B,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,WAAW,CAAA;AAGxE,OAAO,EAAE,WAAW,EAAE,MAAM,SAAS,CAAA;AACrC,YAAY,EAAE,WAAW,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,SAAS,CAAA;AAGxE,OAAO,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAA;AAC7C,YAAY,EAAE,kBAAkB,EAAE,aAAa,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,UAAU,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAE,uBAAuB,EAAE,MAAM,WAAW,CAAA;AAC5D,YAAY,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAGvD,YAAY,EACX,WAAW,EACX,eAAe,EACf,gBAAgB,EAChB,YAAY,EACZ,SAAS,GACT,MAAM,YAAY,CAAA;AACnB,OAAO,EACN,gBAAgB,EAChB,kBAAkB,EAClB,aAAa,EACb,wBAAwB,EACxB,mBAAmB,GACnB,MAAM,YAAY,CAAA;AAGnB,OAAO,EAAE,uBAAuB,EAAE,MAAM,uBAAuB,CAAA;AAC/D,OAAO,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAA;AACzD,OAAO,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAA;AAGzD,OAAO,EACN,iBAAiB,EACjB,uBAAuB,EACvB,iBAAiB,EACjB,sBAAsB,EACtB,cAAc,GACd,MAAM,cAAc,CAAA;AACrB,YAAY,EAAE,SAAS,EAAE,MAAM,cAAc,CAAA;AAG7C,OAAO,EACN,kBAAkB,EAClB,qBAAqB,EACrB,eAAe,EACf,aAAa,EACb,oBAAoB,EACpB,eAAe,GACf,MAAM,YAAY,CAAA;AACnB,YAAY,EACX,wBAAwB,EACxB,iBAAiB,EACjB,cAAc,EACd,kBAAkB,EAClB,oBAAoB,GACpB,MAAM,YAAY,CAAA;AAGnB,OAAO,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAA;AAC/D,YAAY,EAAE,cAAc,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAA;AAG1D,OAAO,EAAE,eAAe,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAA;AAC9D,YAAY,EAAE,YAAY,EAAE,UAAU,EAAE,qBAAqB,EAAE,MAAM,SAAS,CAAA;AAG9E,OAAO,EAAE,yBAAyB,EAAE,MAAM,qBAAqB,CAAA;AAC/D,YAAY,EACX,qBAAqB,EACrB,mBAAmB,EACnB,eAAe,GACf,MAAM,qBAAqB,CAAA;AAG5B,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,WAAW,CAAA;AAGxE,OAAO,EAAE,WAAW,EAAE,MAAM,SAAS,CAAA;AACrC,YAAY,EAAE,WAAW,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,SAAS,CAAA;AAGxE,OAAO,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAA;AAC7C,YAAY,EACX,kBAAkB,EAClB,aAAa,EACb,eAAe,EACf,YAAY,EACZ,eAAe,GACf,MAAM,UAAU,CAAA"}

package/dist/index.js

@@ -2989,6 +2989,7 @@ function createProviderMesh(config) {
   const sortedProviders = [...config.providers];
   const gateways = new Map;
   const circuitBreakers = new Map;
+  const audit = config.audit;
   for (const entry of sortedProviders) {
     const gw = gateway({
       provider: entry.name,
@@ -2999,7 +3000,19 @@ function createProviderMesh(config) {
     gateways.set(entry.name, gw);
     if (config.circuitBreaker) {
       const cbConfig = typeof config.circuitBreaker === "boolean" ? {} : config.circuitBreaker;
-      circuitBreakers.set(entry.name, createCircuitBreaker(cbConfig));
+      const providerName = entry.name;
+      const wrappedConfig = {
+        ...cbConfig,
+        onStateChange(from, to) {
+          cbConfig.onStateChange?.(from, to);
+          audit?.log("circuit_breaker_state_change", {
+            provider: providerName,
+            fromState: from,
+            toState: to
+          });
+        }
+      };
+      circuitBreakers.set(entry.name, createCircuitBreaker(wrappedConfig));
     }
   }
   function callWithCircuitBreaker(providerName, fn) {
@@ -3021,23 +3034,41 @@ function createProviderMesh(config) {
     }
     return gw;
   }
-  async function fallbackComplete(request) {
+  function attemptProvider(entry, request) {
+    const gw = getGateway(entry.name);
+    return callWithCircuitBreaker(entry.name, () => gw.complete({ ...request, model: request.model ?? entry.model }));
+  }
+  function logFailover(fromProvider, toProvider, reason) {
+    audit?.log("provider_failover", {
+      fromProvider,
+      toProvider,
+      strategy: config.strategy,
+      reason
+    });
+  }
+  function toError2(err2) {
+    return err2 instanceof Error ? err2 : new Error(String(err2));
+  }
+  async function tryProvidersWithAudit(providers, request, errorMessage) {
     let lastError = null;
-    for (const entry of sortedProviders) {
+    let failedProvider = null;
+    for (const entry of providers) {
       if (!isProviderAvailable(entry.name))
         continue;
       try {
-        const gw = getGateway(entry.name);
-        return await callWithCircuitBreaker(entry.name, () => gw.complete({ ...request, model: request.model ?? entry.model }));
+        const response = await attemptProvider(entry, request);
+        if (failedProvider)
+          logFailover(failedProvider, entry.name, lastError?.message);
+        return response;
       } catch (err2) {
-        lastError = err2 instanceof Error ? err2 : new Error(String(err2));
+        failedProvider = entry.name;
+        lastError = toError2(err2);
       }
     }
-    throw lastError ?? new ElsiumError({
-      code: "PROVIDER_ERROR",
-      message: "All providers failed",
-      retryable: false
-    });
+    throw lastError ?? new ElsiumError({ code: "PROVIDER_ERROR", message: errorMessage, retryable: false });
+  }
+  async function fallbackComplete(request) {
+    return tryProvidersWithAudit(sortedProviders, request, "All providers failed");
   }
   async function costOptimizedComplete(request) {
     const optimizer = config.costOptimizer;
@@ -3050,7 +3081,13 @@ function createProviderMesh(config) {
     const gw = getGateway(target.provider);
     try {
       return await gw.complete({ ...request, model: target.model });
-    } catch {
+    } catch (err2) {
+      audit?.log("provider_failover", {
+        fromProvider: target.provider,
+        toProvider: "fallback-chain",
+        strategy: "cost-optimized",
+        reason: err2 instanceof Error ? err2.message : String(err2)
+      });
       return fallbackComplete(request);
     }
   }
@@ -3094,31 +3131,13 @@ function createProviderMesh(config) {
       return capabilities.every((c) => providerCaps.includes(c));
     });
   }
-  async function tryProviders(providers, request) {
-    let lastError = null;
-    for (const entry of providers) {
-      if (!isProviderAvailable(entry.name))
-        continue;
-      try {
-        const gw = getGateway(entry.name);
-        return await callWithCircuitBreaker(entry.name, () => gw.complete({ ...request, model: request.model ?? entry.model }));
-      } catch (err2) {
-        lastError = err2 instanceof Error ? err2 : new Error(String(err2));
-      }
-    }
-    throw lastError ?? new ElsiumError({
-      code: "PROVIDER_ERROR",
-      message: "No capable provider succeeded",
-      retryable: false
-    });
-  }
   async function capabilityAwareComplete(request) {
     const capabilities = detectRequiredCapabilities(request);
     const capable = filterCapableProviders(capabilities);
     if (capable.length === 0) {
       return fallbackComplete(request);
     }
-    return tryProviders(capable, request);
+    return tryProvidersWithAudit(capable, request, "No capable provider succeeded");
   }
   function defaultCapabilities(provider) {
     const meta = getProviderMetadata(provider);

package/dist/router.d.ts

@@ -21,11 +21,18 @@ export interface CostOptimizerConfig {
     };
     complexityThreshold?: number;
 }
+export interface MeshAuditLogger {
+    log(type: string, data: Record<string, unknown>, options?: {
+        actor?: string;
+        traceId?: string;
+    }): void;
+}
 export interface ProviderMeshConfig {
     providers: ProviderEntry[];
     strategy: RoutingStrategy;
     costOptimizer?: CostOptimizerConfig;
     circuitBreaker?: CircuitBreakerConfig | boolean;
+    audit?: MeshAuditLogger;
 }
 export interface ProviderMesh {
     complete(request: CompletionRequest): Promise<LLMResponse>;

package/dist/router.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"router.d.ts","sourceRoot":"","sources":["../src/router.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAA;AACrE,OAAO,EAEN,KAAK,oBAAoB,EAEzB,YAAY,EAEZ,MAAM,iBAAiB,CAAA;AAKxB,MAAM,MAAM,eAAe,GACxB,UAAU,GACV,gBAAgB,GAChB,mBAAmB,GACnB,kBAAkB,CAAA;AAErB,MAAM,WAAW,aAAa;IAC7B,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;IAC5C,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,YAAY,CAAC,EAAE,MAAM,EAAE,CAAA;CACvB;AAED,MAAM,WAAW,mBAAmB;IACnC,WAAW,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAA;IAChD,YAAY,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAA;IACjD,mBAAmB,CAAC,EAAE,MAAM,CAAA;CAC5B;AAED,MAAM,WAAW,kBAAkB;IAClC,SAAS,EAAE,aAAa,EAAE,CAAA;IAC1B,QAAQ,EAAE,eAAe,CAAA;IACzB,aAAa,CAAC,EAAE,mBAAmB,CAAA;IACnC,cAAc,CAAC,EAAE,oBAAoB,GAAG,OAAO,CAAA;CAC/C;AAED,MAAM,WAAW,YAAY;IAC5B,QAAQ,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,WAAW,CAAC,CAAA;IAC1D,MAAM,CAAC,OAAO,EAAE,iBAAiB,GAAG,YAAY,CAAA;IAChD,QAAQ,CAAC,SAAS,EAAE,MAAM,EAAE,CAAA;IAC5B,QAAQ,CAAC,QAAQ,EAAE,eAAe,CAAA;CAClC;AAoDD,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,kBAAkB,GAAG,YAAY,CAgQ3E"}
+{"version":3,"file":"router.d.ts","sourceRoot":"","sources":["../src/router.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAA;AACrE,OAAO,EAEN,KAAK,oBAAoB,EAEzB,YAAY,EAEZ,MAAM,iBAAiB,CAAA;AAKxB,MAAM,MAAM,eAAe,GACxB,UAAU,GACV,gBAAgB,GAChB,mBAAmB,GACnB,kBAAkB,CAAA;AAErB,MAAM,WAAW,aAAa;IAC7B,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;IAC5C,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,YAAY,CAAC,EAAE,MAAM,EAAE,CAAA;CACvB;AAED,MAAM,WAAW,mBAAmB;IACnC,WAAW,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAA;IAChD,YAAY,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAA;IACjD,mBAAmB,CAAC,EAAE,MAAM,CAAA;CAC5B;AAED,MAAM,WAAW,eAAe;IAC/B,GAAG,CACF,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,GAC5C,IAAI,CAAA;CACP;AAED,MAAM,WAAW,kBAAkB;IAClC,SAAS,EAAE,aAAa,EAAE,CAAA;IAC1B,QAAQ,EAAE,eAAe,CAAA;IACzB,aAAa,CAAC,EAAE,mBAAmB,CAAA;IACnC,cAAc,CAAC,EAAE,oBAAoB,GAAG,OAAO,CAAA;IAC/C,KAAK,CAAC,EAAE,eAAe,CAAA;CACvB;AAED,MAAM,WAAW,YAAY;IAC5B,QAAQ,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,WAAW,CAAC,CAAA;IAC1D,MAAM,CAAC,OAAO,EAAE,iBAAiB,GAAG,YAAY,CAAA;IAChD,QAAQ,CAAC,SAAS,EAAE,MAAM,EAAE,CAAA;IAC5B,QAAQ,CAAC,QAAQ,EAAE,eAAe,CAAA;CAClC;AAoDD,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,kBAAkB,GAAG,YAAY,CAgR3E"}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@elsium-ai/gateway",
-	"version": "0.6.0",
+	"version": "0.7.0",
 	"description": "Multi-provider LLM gateway for ElsiumAI",
 	"license": "MIT",
 	"author": "Eric Utrera <ebutrera9103@gmail.com>",
@@ -26,7 +26,7 @@
 		"dev": "bun --watch src/index.ts"
 	},
 	"dependencies": {
-		"@elsium-ai/core": "^0.6.0",
+		"@elsium-ai/core": "^0.7.0",
 		"zod": "^3.24.0"
 	},
 	"devDependencies": {