ai-lcr 0.1.0 → 0.2.0

package/README.md

@@ -108,6 +108,68 @@ The same pattern works for any vendor's native SDK provider — `@ai-sdk/anthrop
   <img src="assets/ai-lcr-routing.svg" alt="routing diagram: cheapest first, fallback on failure, recover after idle" width="820">
 </p>
 
+## See what happened (`onCall`)
+
+`onError`/`onCost` fire separately and uncorrelated, so a failover is hard to read after the fact. `onCall` gives you **one record per request** — the full chain, the winner, the reason for each failed hop, latency, and cost — and `formatCallRecord` turns it into a one-liner you can scan:
+
+```ts
+import { createLCR, formatCallRecord } from "ai-lcr";
+
+const lcr = createLCR({
+  models: { /* … */ },
+  onCall: (record) => console.log(formatCallRecord(record)),
+});
+```
+
+```text
+✓ text  tokenmart                      412ms  $0.0003
+⚠ text  tokenmart→openrouter           910ms  $0.0004  ⤷ tokenmart 502
+✗ text  deepseek→tokenmart→openrouter  1240ms FAILED   ⤷ deepseek 401, tokenmart 502, openrouter 429
+```
+
+`✓` served on the first try · `⚠` failed over but recovered · `✗` every provider failed. The `⤷` shows which provider died and why.
+
+**Persist it anywhere — zero lock-in.** `record` is a plain `CallRecord` object. Log the JSON and point any log drain at it (Axiom, Datadog, your own DB); ai-lcr never decides where it goes:
+
+```ts
+onCall: (record) => console.log(JSON.stringify(record)),
+```
+
+Or ship each record to an HTTP collector with the built-in `createHttpSink` (fire-and-forget, never throws, dashboard-agnostic):
+
+```ts
+import { createLCR, createHttpSink } from "ai-lcr";
+import { after } from "next/server"; // serverless: don't block the response
+
+const lcr = createLCR({
+  models: { /* … */ },
+  onCall: createHttpSink({
+    url: `${process.env.LCR_INGEST_URL}/api/ingest`,
+    headers: { authorization: `Bearer ${process.env.LCR_INGEST_KEY}` },
+    project: process.env.LCR_PROJECT, // optional tag if one collector serves several apps
+    dispatch: after,                  // run after the response is sent (serverless-safe)
+  }),
+});
+```
+
+Point `url` at anything that accepts the `CallRecord` JSON — including the self-hostable companion dashboard, **[ai-lcr-dashboard](https://github.com/victorzhrn/ai-lcr-dashboard)** (Spend / Calls / Failover rate + a live failover feed). You run your own instance, so the data never leaves your infrastructure; a [db9](https://db9.ai) database can be provisioned in seconds if you don't want to stand one up yourself.
+
+```ts
+interface CallRecord {
+  id: string;                // correlation id, one per request
+  model: string;             // logical model name
+  attempts: { provider: string; ok: boolean; latencyMs: number; errorClass?: string }[];
+  winner?: string;           // provider that served; undefined if all failed
+  ok: boolean;
+  failedOver: boolean;       // more than one provider was tried
+  latencyMs: number;
+  inputTokens: number;
+  outputTokens: number;
+  costUsd: number;            // what the winner charged for these tokens
+  baselineUsd: number;        // what the priciest configured route would cost → savings = baselineUsd - costUsd
+}
+```
+
 ## Supported providers
 
 Any OpenAI-compatible endpoint works — and so does any AI SDK provider package, including a model vendor's own official API.
@@ -225,6 +287,7 @@ Two OpenAI-compatible providers, same probe, same day. Cells cover both families
 
 - [x] Own failover engine — cheapest-first routing + streaming-safe fallback, no external routing dependency
 - [x] Real per-call cost accounting (`onCost`)
+- [x] One correlated record per request with the full failover chain (`onCall` + `formatCallRecord`)
 - [x] Auto cheapest-first ordering (`autoSort`) from per-provider `cost`
 - [x] Offline capability + cost check (`scripts/check-provider.sh`) → per-model trust matrix
 - [ ] Bundled price table for zero-config pricing (drop the manual `cost` numbers)