@bivelio/savings-layer 0.4.24 → 0.4.25

package/LICENSE

@@ -9,11 +9,12 @@ copying, or using the Software, you agree to this Agreement. If you do not agree
 not install or use the Software.
 
 1. LICENSE GRANT. Subject to your continuous compliance with this Agreement and to
-   an active, paid BiVelio subscription with a valid license key ("License Key"),
-   BiVelio grants you a limited, non-exclusive, non-transferable, non-sublicensable,
-   revocable license to install and use the Software, as published, solely for your
-   own internal business purposes, and only for the number of seats covered by your
-   subscription. The Software is licensed, not sold.
+   an active BiVelio subscription (paid, or granted by BiVelio at no charge, for
+   example through a promotional code or a pilot) with a valid license key
+   ("License Key"), BiVelio grants you a limited, non-exclusive, non-transferable,
+   non-sublicensable, revocable license to install and use the Software, as
+   published, solely for your own internal business purposes, and only for the
+   number of seats covered by your subscription. The Software is licensed, not sold.
 
 2. LICENSE KEY; FAIL-CLOSED OPERATION. The Software requires a valid, active License
    Key and does not operate without one. Expiry, non-payment, revocation, suspension,
@@ -25,13 +26,13 @@ not install or use the Software.
 3. RESTRICTIONS. Except as expressly permitted above, you will not: (a) distribute,
    publish, resell, rent, lease, lend, offer as a hosted or managed service, or
    otherwise make the Software available to any third party; (b) sublicense, assign,
-   or transfer your rights; (c) use the Software for more seats than you have paid
-   for, or share a License Key across more machines or service identities than your
-   subscription covers; (d) remove, alter, or obscure any proprietary or copyright
-   notice; (e) reverse engineer, decompile, or disassemble the Software, except to
-   the limited extent applicable law expressly permits notwithstanding this
-   restriction; or (f) use the Software to develop, train, or improve a product or
-   service that competes with the Software.
+   or transfer your rights; (c) use the Software for more seats than your
+   subscription covers, or share a License Key across more machines or service
+   identities than it covers; (d) remove, alter, or obscure any proprietary or
+   copyright notice; (e) reverse engineer, decompile, or disassemble the Software,
+   except to the limited extent applicable law expressly permits notwithstanding
+   this restriction; or (f) use the Software to develop, train, or improve a product
+   or service that competes with the Software.
 
 4. OWNERSHIP. The Software is the exclusive property of BiVelio and its licensors and
    embodies valuable proprietary information and trade secrets. BiVelio retains all
@@ -39,27 +40,110 @@ not install or use the Software.
    rights therein. No rights are granted to you except as expressly set out in this
    Agreement, whether by implication, estoppel, or otherwise.
 
-5. YOUR DATA; PRIVACY. Your prompts, completions, and content are processed within
-   your own infrastructure and are not transmitted to BiVelio in order to serve a
-   request. BiVelio's control plane receives only usage counts and cost metadata, as
-   described in the BiVelio documentation and privacy terms.
+5. YOUR DATA; PRIVACY.
+   (a) What the Software never sends to BiVelio. The Software never transmits to
+   BiVelio the content of your requests or responses (including prompts, system
+   instructions, messages, tool definitions, tool arguments and results, retrieved
+   documents, and completions) or the credentials you use with your LLM provider
+   (API keys, OAuth tokens, or other authorization headers). That content and those
+   credentials travel only between your systems and the LLM provider you configure.
+   (b) What the Software sends to BiVelio. The SDK contacts BiVelio only when you
+   configure a license server or metering URL; the local gateway always does. With a
+   BiVelio service-account key, the Software sends BiVelio's control plane usage
+   records for the requests it meters, each limited to:
+     (i) identifiers: a request identifier generated on your side (at random, or by
+         your own generator); for a repeated request valued by reference, the
+         identifier and timestamp of the earlier request whose provider counter is
+         used; a seat identifier, which is either a value you set or an opaque value
+         computed on your machine as a keyed hash (HMAC-SHA-256 wherever the
+         runtime provides it), keyed with your service-account key, of the
+         platform, CPU architecture, runtime executable path, host name,
+         operating-system user name, and home directory (those underlying values
+         are never sent); for traffic through the local gateway,
+         the session and sub-agent identifiers that your coding agent attaches to
+         its own requests (for example, Claude Code's session id), only when they
+         are plain identifiers; an organization hint; and a flag marking CI or
+         ephemeral runners;
+     (ii) the identifier of the model that served the request (the model named in
+         the request or, where the Software sent the request to another model under
+         a setting you enabled, that model; for a self-hosted or Azure deployment,
+         the name you gave it) and the time of the request;
+     (iii) counts: LLM calls executed and avoided; input and output tokens before
+         and after the Software's optimizations, including tokens removed,
+         compressed, or read from the provider's cache; and the cache outcome; and
+     (iv) cost figures computed by the Software from its price catalogue (or from
+         a cost model you supply): baseline cost, actual cost, the net-saving
+         ratio, the basis of the figures (measured, reference, estimated, shadow,
+         or unmeasured), and the value, at the provider's cache-read price, of
+         input tokens your provider reported as cleared from context.
+   Each batch of records also carries the Software's surface and version (for
+   example, "gateway/0.4.23"). BiVelio's ingest rejects any record that carries a
+   field not listed above. Separately, the Software fetches from BiVelio its current
+   license token, the signed license revocation list and, for the gateway, your
+   organization's feature entitlements; these requests carry your service-account
+   key where authentication is required, and no request data. Like any HTTPS
+   request, all of the above also reveals ordinary network metadata, such as your
+   IP address. If you enable the SDK's optional verification, which is off by
+   default, the SDK also sends BiVelio, through a separate channel and for each
+   request it samples: a label marking the record as a verification sample; the
+   request identifier and time; the model requested and the model that served it;
+   the cache outcome; the category of the request and the outcome of the check;
+   the input, cached-input, and output token counts and the cost of the served
+   request and of the unoptimized copy the SDK sent to your LLM provider; how
+   that copy finished and whether it met the response contract; and the per-token
+   prices applied; together with daily counts of requests per category and a
+   random batch identifier. That channel likewise rejects any field not listed
+   here, and none of it is used to calculate the fees in Section 6.
+   (c) BiVelio uses this data to operate licensing and revocation, show your
+   dashboard, count billable seats, and calculate the fees in Section 6. Each
+   field, and how long BiVelio keeps it, is further described at
+   https://savings.bivelio.com/privacy.
 
-6. TERM AND TERMINATION. This Agreement remains in effect while your subscription is
+6. FEES. Your subscription is subject to BiVelio's pricing as published at
+   https://savings.bivelio.com/pricing (the "Published Pricing") for each billing
+   period:
+   (a) a subscription fee per seat, payable whether or not the Software produces any
+   saving; and (b) a commission, at tiered marginal rates, charged only on measured
+   savings, meaning savings whose basis is labelled "measured" or "reference" in
+   your usage records (Section 5(b)(iv)). A "measured" saving is established from
+   your LLM provider's own usage counter for that request; a "reference" saving, for
+   a repeated request the Software served without calling your provider, from your
+   provider's counter for the identical earlier request that did run. Both are
+   valued at the per-token prices the Software applied to that request: those of a
+   cost model you configure, where you configure one, and otherwise your provider's
+   list prices in the price catalogue included in the Software. Savings labelled
+   "estimated", "shadow", or "unmeasured" never carry commission. Traffic the
+   Software identifies as a flat-rate provider subscription (a Claude or ChatGPT
+   subscription used through the local gateway) is metered but credited no measured
+   saving, so it carries no commission. A period with no measured savings carries no
+   commission. The first calendar month (UTC) in which your organization reports any
+   usage is a calibration period, however little of that month remains, and carries
+   no commission. Nor is commission charged for a period that BiVelio closes while
+   your account is exempt from it. Your account is exempt if BiVelio grants it an
+   exemption and, until a payment is made on the account, if its subscription was
+   activated with a promotional code that waives the subscription fee in full for
+   its entire term. For a calibration or exempt period the statement still shows the
+   commission that would have applied. Each period's commission is
+   itemized on a statement in your dashboard, together with the exchange rate
+   applied. Rates, tier thresholds, and currency are those of the Published Pricing
+   and are not restated here.
+
+7. TERM AND TERMINATION. This Agreement remains in effect while your subscription is
    active. BiVelio may terminate this Agreement immediately if you breach it. Upon
    expiry or termination you must cease all use of the Software and destroy your
-   copies. Sections 2 through 9 survive termination.
+   copies. Sections 2 through 10 survive termination.
 
-7. DISCLAIMER OF WARRANTY. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY
+8. DISCLAIMER OF WARRANTY. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY
    KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
    MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT.
 
-8. LIMITATION OF LIABILITY. TO THE MAXIMUM EXTENT PERMITTED BY LAW, IN NO EVENT SHALL
+9. LIMITATION OF LIABILITY. TO THE MAXIMUM EXTENT PERMITTED BY LAW, IN NO EVENT SHALL
    BIVELIO INC. BE LIABLE FOR ANY INDIRECT, INCIDENTAL, SPECIAL, CONSEQUENTIAL, OR
    EXEMPLARY DAMAGES, OR FOR ANY LOSS OF PROFITS, REVENUE, OR DATA, ARISING FROM OR
    RELATED TO THE SOFTWARE OR THIS AGREEMENT. BIVELIO'S TOTAL LIABILITY SHALL NOT
    EXCEED THE FEES YOU PAID FOR THE SOFTWARE IN THE TWELVE MONTHS PRECEDING THE CLAIM.
 
-9. GENERAL. This Agreement is governed by the laws of the State of Delaware, USA,
+10. GENERAL. This Agreement is governed by the laws of the State of Delaware, USA,
    without regard to its conflict-of-laws rules. If any provision is held
    unenforceable, the remaining provisions remain in effect. This Agreement, together
    with the applicable BiVelio subscription terms, constitutes the entire agreement

package/README.md

@@ -19,17 +19,24 @@
 Every request your app sends to an AI is paid for by the text going in and out.
 **Savings** sits on that path and lets through only what's needed — skipping calls
 that don't have to happen, and trimming what does — so you pay for less. It is not a
-promise you take on faith: **every saving we charge on is measured with the provider's
-official meter, the same one on your bill**, and every saving — measured or estimated,
-and labelled as such — is handed back to you request by request.
-
-**We only earn when you save.** Your first month carries no commission at all: we
-measure everything and show you the statement of what it would have cost. After
-that, the commission comes out of the **measured** saving only — never out of your
-pocket, and never from estimates: a tiered rate from 10 % down to 4 % of what you
-saved, so **you always keep at least 90 % of every euro saved**, and a month with no
-saving is zero commission. And your prompts **never leave your infrastructure**:
-BiVelio only ever sees counts and cost, never your content.
+promise you take on faith: **every saving we charge on is measured with your provider's
+own usage counter, the one your bill is built from** (for a repeat served without
+calling the provider, the counter of the identical call that ran), and every saving —
+measured or estimated, and labelled as such — is handed back to you request by request.
+
+**A small per‑seat fee, and a commission only on savings measured against your
+provider's counter.** The seat fee is paid whether or not you save. Your
+first month carries no commission at all — it is the first calendar month (UTC) in
+which your organization reports usage, so starting late in a month makes it a short one —
+and at its close you see the statement of what the commission would have been. After
+that, the commission is charged on the **measured** saving only — never from estimates:
+a tiered rate from 10 % down to 4 % of what you saved, so **you keep
+at least 90 % of every euro saved** (before the invoice is rounded to the cent; the
+seat fee is separate). A month with no measured saving is zero commission. And your
+prompts and completions **never reach BiVelio**: what BiVelio receives is per‑request
+usage — token counts, cost, the model id and opaque ids — never your content
+([LICENSE](./LICENSE) §5 lists every field; [savings.bivelio.com/privacy](https://savings.bivelio.com/privacy)
+explains each one and how long it is kept).
 
 ### For engineers, in one line
 
@@ -43,9 +50,11 @@ goes straight from your app to your provider; the SDK is never a middleman serve
 > BV‑SALA is fail‑closed and executes only with an active BiVelio license key.
 > The license signature is verified **offline**; with `licenseServerUrl` set, the SDK
 > also calls `savings.bivelio.com` for the revocation list, license renewal and usage
-> metering. **Your prompts never leave your infrastructure** — what travels is token
-> counts, cost, the model id and opaque seat/session ids, never content. Use is governed by the [LICENSE](./LICENSE)
-> and the BiVelio Terms. Not a wrapper around any third‑party library.
+> metering. **Your prompts, completions and provider keys never reach BiVelio** — what
+> travels is per‑request usage: token counts, cost, the model id, a request id and
+> opaque seat and session ids (the exact list is in [LICENSE](./LICENSE) §5). Use is
+> governed by the LICENSE, which also sets out the seat fee and the commission, and the
+> BiVelio Terms. Not a wrapper around any third‑party library.
 
 ## Where it installs
 
@@ -83,6 +92,20 @@ subscription there is no per-token invoice, so that traffic is metered at
 list-price equivalent and never carries commission; the per-seat license applies
 as for any other use.
 
+**The gateway forwards what your terminal sends.** With no lever armed, your
+provider receives the request body byte for byte and every header your client
+sends (see the limits): `cache_control` and its 1-hour TTL, tool search and
+`tool_reference` blocks, the advisor, every `anthropic-beta` value. An armed lever
+changes only what it declares, and a request it cannot rewrite exactly travels
+untouched. A test suite checks this against a fake upstream on every change
+(`test/gateway-no-empeora.test.ts`; the repository is private, so the linked
+section lists exactly what it checks). The gateway also logs, once per session,
+requests that come out worse than your client asked for: cache markers the
+provider ignored, a 1-hour TTL written at 5 minutes upstream, and tool search off
+(Claude Code turns it off by default behind any proxy, this one included;
+`bvsala claude` turns it back on). What it checks, and its limits:
+[docs/terminales/README.md](./docs/terminales/README.md#what-the-gateway-guarantees-it-forwards-what-your-client-sends).
+
 ### Python and any other language: the local gateway
 
 The same gateway sits in front of any SDK that lets you set a base URL, whatever
@@ -228,6 +251,135 @@ still writing cancels its request, and nothing is cached or recorded; once its a
 is complete, or when it arrives in one piece, nothing is cancelled.
 `await stream.result` tells you which happened.
 
+## Inside your framework
+
+Already on an agent framework? The layer plugs in at that framework's own extension
+point, from a subpath of this same package. The four adapters behave alike:
+
+- **They answer without calling the model when they can** — a computed answer (the
+  arithmetic above), an exact repeat of a request that already ran, an identical
+  request already in flight — and otherwise let your framework make exactly the call
+  it was going to make. They never rewrite what your framework sends.
+- **Tools are treated as having side effects** unless you list them in
+  `readOnlyTools`: a request that offers any other tool is never answered from a
+  cache, because the action has to run.
+- **Fail‑closed, like the SDK**: without an active license the call fails with
+  `LicenseError` (a framework may wrap it, keeping its name and message) and the
+  model is not called. **Put the adapter last**, so nothing sits between it and the
+  model.
+
+Every model call gets the same `SavingsReport` as with the SDK — its `basis` says
+whether a figure comes from your provider's own counter — and `onReport` receives it
+too.
+
+### Vercel AI SDK
+
+`pnpm add @bivelio/savings-layer ai @ai-sdk/openai` — a `LanguageModelMiddleware`
+for `ai` 6 or 7:
+
+```ts
+import { generateText, wrapLanguageModel } from "ai";
+import { openai } from "@ai-sdk/openai";
+import { savingsMiddleware, getSavingsReport } from "@bivelio/savings-layer/ai-sdk";
+
+const savings = savingsMiddleware({
+  licenseKey: process.env.BIVELIO_LICENSE_KEY,
+  licenseServerUrl: "https://savings.bivelio.com",
+  serviceAccountKey: process.env.BIVELIO_SERVICE_KEY,
+  readOnlyTools: ["get_weather"],
+});
+const model = wrapLanguageModel({ model: openai("gpt-4o-mini"), middleware: savings }); // last in the list
+
+const result = await generateText({
+  model,
+  prompt: "What is 2 + 2 * 3?",
+  providerOptions: { bivelio: { context: { sessionId: "user-42" } } },
+});
+console.log(getSavingsReport(result)?.cost.basis); // "estimated": answered without calling the model
+```
+
+For `streamText`, read it with `getSavingsReport({ providerMetadata: await result.providerMetadata })`.
+
+### Mastra
+
+`pnpm add @bivelio/savings-layer @mastra/core` — an input processor for
+`@mastra/core` 1.x:
+
+```ts
+import { Agent } from "@mastra/core/agent";
+import { savingsProcessor } from "@bivelio/savings-layer/mastra";
+
+const bivelio = savingsProcessor({
+  licenseKey: process.env.BIVELIO_LICENSE_KEY,
+  licenseServerUrl: "https://savings.bivelio.com",
+  serviceAccountKey: process.env.BIVELIO_SERVICE_KEY,
+  onReport: (r) => console.log(r.cost.basis),
+});
+const agent = new Agent({
+  id: "support",
+  name: "Support",
+  instructions: "Answer briefly.",
+  model: "openai/gpt-4o-mini",
+  inputProcessors: [bivelio], // last in the list
+});
+console.log((await agent.generate("What is 2 + 2 * 3?")).text); // "8"
+```
+
+It covers `generate()` and `stream()`, not `generateLegacy()`/`streamLegacy()` or a
+durable agent that resumes in another process; identical requests in flight are not
+shared here. `emitReportPart: true` also streams each report as a
+`data-bivelio-savings-report` part.
+
+### LangChain.js
+
+`pnpm add @bivelio/savings-layer langchain @langchain/core` — an agent middleware for
+`createAgent` in `langchain` 1.x:
+
+```ts
+import { createAgent } from "langchain";
+import { savingsAgentMiddleware, getSavingsReportFromMessage } from "@bivelio/savings-layer/langchain";
+
+const agentSavings = savingsAgentMiddleware({
+  licenseKey: process.env.BIVELIO_LICENSE_KEY,
+  licenseServerUrl: "https://savings.bivelio.com",
+  serviceAccountKey: process.env.BIVELIO_SERVICE_KEY,
+});
+const lcAgent = createAgent({ model: "openai:gpt-4o-mini", tools: [], middleware: [agentSavings] }); // last
+const state = await lcAgent.invoke({ messages: [{ role: "user", content: "What is 2 + 2 * 3?" }] });
+console.log(getSavingsReportFromMessage(state.messages.at(-1))?.cost.basis);
+```
+
+The model call is measured when it finishes; tokens you stream with
+`streamMode: "messages"` keep coming from the model as usual. A chat model with its
+own `cache` set is reported as `unmeasured`: its counter may be a cached copy.
+
+### Anthropic TypeScript SDK
+
+`pnpm add @bivelio/savings-layer @anthropic-ai/sdk` — a client middleware for
+`@anthropic-ai/sdk` 0.103 or later:
+
+```ts
+import Anthropic from "@anthropic-ai/sdk";
+import { anthropicSavings } from "@bivelio/savings-layer/anthropic-sdk";
+
+const claudeSavings = anthropicSavings({
+  licenseKey: process.env.BIVELIO_LICENSE_KEY,
+  licenseServerUrl: "https://savings.bivelio.com",
+  serviceAccountKey: process.env.BIVELIO_SERVICE_KEY,
+});
+const client = new Anthropic({ middleware: [claudeSavings.middleware] }); // last in the list
+const message = await client.messages.create({
+  model: "claude-opus-5",
+  max_tokens: 256,
+  messages: [{ role: "user", content: "What is 2 + 2 * 3?" }],
+});
+console.log(claudeSavings.reportFor(message)?.cost.basis);
+```
+
+It runs once per HTTP attempt, inside the SDK's retries: an attempt the provider
+rejects reaches the SDK unchanged and is not recorded. Only message creation goes
+through the layer; `countTokens`, batches, models and files pass untouched.
+
 ## What you get on every request
 
 A `SavingsReport` with the numbers behind every claim, kept in **four separate
@@ -240,6 +392,16 @@ ledgers** that are never summed into one flattering figure:
 | `compressed_tokens` | information kept, but encoded with fewer tokens |
 | `provider_cached_tokens` | tokens still in the prompt, billed/processed more cheaply |
 
+**Quality, kept apart from money.** `report.qualityLedger` records how the answer you
+received earned its place: whether it came from your provider, a replay, or the answer
+to a reworded question (with its similarity score); whether it was checked against your
+output contract, repaired or cut off by the output limit; and what the model cascade
+decided. It holds no money, is never added to the four ledgers, and never leaves your
+process. Reusing answers to reworded questions is opt-in, and by default it covers
+single-shot requests only: requests that declare tools, carry tool calls or results, or
+hold more than one user turn are left out unless you set
+`savings.semanticCache: "include-agentic"`.
+
 And a promise you can hold it to: **never worse than your JSON.** Payload encodings
 are chosen by counting real tokens with the destination model's own tokenizer, and
 BV‑SALA only moves away from plain JSON when the saving clearly clears the bar —
@@ -295,6 +457,65 @@ and every pair as a CSV download.
 
 </details>
 
+<details>
+<summary><b>Provider price levers (opt-in, off by default)</b></summary>
+
+Two request flags ask your provider for a lower price on the same tokens. Neither
+changes the answer, and what they are worth is reported next to the four ledgers:
+never folded into `cost.*`, never part of any commission.
+
+**`savings.deferrable`** asks for the provider's Flex tier: OpenAI, and Gemini through
+its OpenAI‑compatible endpoint. Anthropic has no cheaper synchronous tier (its
+discount lives only in Message Batches, which the layer does not support yet).
+Bedrock and DeepSeek off‑peak pricing are not supported.
+
+- **Latency.** OpenAI publishes no latency commitment for Flex; Google publishes a
+  target of minutes. Keep deferrable requests off user‑facing paths.
+  `report.deferred.latency` quotes what the provider documents.
+- **Risk.** Without capacity the provider refuses the request (429, or 503 on Gemini)
+  instead of waiting; OpenAI documents that the refusal is not charged. With
+  `priceLevers: { onCapacityError: "standard" }` the layer repeats it once at the
+  standard tier and price, and says so in `report.deferred.capacityFallback`.
+- **What it is worth.** Your provider's usage counter for that call, priced at the two
+  published rate cards (standard, and the tier that actually served it), component
+  by component, with the date the prices were checked. It is `measured` only when
+  the served tier was read back from the provider's own API, the prices are list
+  prices and the counter says how much of the input was read from (or written to)
+  the prompt cache; otherwise `estimated`, and `basisReason` says why. It never
+  exceeds the difference between the two published rate cards, even with your own
+  `costModels`. A tier the provider did not confirm is never credited.
+
+**`savings.standalone`** (GPT‑5.6 and later, on OpenAI's own API) declares that nothing
+after the stable prefix of this request will be sent again. The provider then writes
+its prompt cache only at the end of that prefix, or nowhere, instead of at the end of
+your message, which on these models costs more than plain input. The trade‑off:
+repeats and continuations of this exact prompt lose the cache reads the provider
+default would give them, so leave it off conversation turns you will continue. Its
+figure, `report.cacheWrites.avoidedWritePremium`, is always `estimated`: the provider
+default was not run.
+
+```ts
+const leveredLayer = createSavingsLayer({
+  provider,
+  licenseKey: process.env.BIVELIO_LICENSE_KEY,
+  priceLevers: { deferrable: true, onCapacityError: "standard" }, // layer-wide defaults
+});
+
+const { report } = await leveredLayer.generate({
+  model: "openai/gpt-5.6-luna",
+  messages: [
+    { role: "system", content: "…your long, fixed instructions…" },
+    { role: "user", content: "Classify ticket 42." },
+  ],
+  savings: { standalone: true }, // a request's own value always wins
+});
+
+report.deferred?.tierSaving; // { amount, basis, standardCost, appliedCost, pricesCheckedOn, basisReason }
+report.cacheWrites;          // { mode, breakpoints, avoidedWritePremium?, reason }
+```
+
+</details>
+
 <details>
 <summary><b>Structured output — validated <code>data</code>, not just text</b></summary>
 
@@ -368,6 +589,144 @@ an action that has not run yet cannot be a saving.
 
 </details>
 
+<details>
+<summary><b>Your ledgers in your tracing — OpenTelemetry, Langfuse, Datadog</b></summary>
+
+Wrap the layer once and every request becomes a span on the OpenTelemetry pipeline
+you already run (`@opentelemetry/api` is an optional peer; the SDK never imports it):
+
+```ts
+import { trace } from "@opentelemetry/api";
+import { instrumentSavingsLayer } from "@bivelio/savings-layer";
+
+// One span per request, on the OpenTelemetry pipeline you already run.
+const traced = instrumentSavingsLayer(layer, { tracer: trace });
+const { report: tracedReport } = await traced.generate({
+  model: "openai/gpt-4o-mini",
+  messages: [{ role: "user", content: "What is 2 + 2 * 3?" }],
+});
+console.log(tracedReport.cost.basis); // the span carries the same figures
+```
+
+- **Standard spans, plus your ledgers.** Spans follow the
+  [GenAI semantic conventions](https://github.com/open-telemetry/semantic-conventions/blob/v1.41.1/model/gen-ai/registry.yaml)
+  as last published (OpenTelemetry semantic conventions v1.41.1): `chat {model}`,
+  kind CLIENT, provider, model and usage from your provider's counter (0 on an avoided
+  call: no token was billed). On top, `com.bivelio.*` carries the four ledgers, the
+  `basis`, the cost and the ids; `com.bivelio.request_id` is the same id as your usage
+  record. Same results, same errors: `traced` hands back the very objects `layer` does.
+- **Money is kept apart by basis.** The money saved is
+  `com.bivelio.cost.saved.measured`, `.reference` or `.estimated` — one key per span,
+  the one of its basis — so a sum over one key never mixes measured and estimated
+  money; `unmeasured` spans carry counts and no money. `report.cost.netSavings` is a
+  ratio and goes out as `com.bivelio.cost.net_savings_ratio`; the money is
+  `baselineEstimate − actual`, and that is what `saved.*` holds.
+- **None of this talks to BiVelio.** Spans go to your exporter; files stay where you
+  write them. Your prompts, completions and provider keys never reach BiVelio, and no
+  span carries them either: ids, counts, money and enums only, and a failed request
+  records its `error.type`, never its message.
+- **Langfuse.** Add the `LangfuseSpanProcessor` from `@langfuse/otel` to your tracer
+  provider. These spans carry `gen_ai.*`, so its default filter exports them
+  ([Langfuse OpenTelemetry docs](https://langfuse.com/integrations/native/opentelemetry)).
+  `instrumentSavingsLayer(layer, { tracer: trace, langfuse: { metadata: true } })`
+  makes the figures filterable metadata, and `langfuse: { cost: true }` hands Langfuse
+  the report's own cost (in USD) instead of its estimate. Tracing with `@langfuse/tracing` by
+  hand? Pass `toLangfuseGeneration(report)` to `generation.update()`.
+- **Datadog LLM Observability** reads these spans over OTLP
+  ([Datadog OpenTelemetry docs](https://docs.datadoghq.com/llm_observability/instrumentation/otel_instrumentation/)):
+
+  ```bash
+  OTEL_EXPORTER_OTLP_TRACES_PROTOCOL=http/protobuf
+  OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=<your Datadog site's OTLP traces endpoint>
+  OTEL_EXPORTER_OTLP_TRACES_HEADERS=dd-api-key=<your Datadog API key>,dd-otlp-source=llmobs
+  ```
+
+  The `com.bivelio.*` attributes arrive as tags; with `datadog: { metadata: true }`
+  they also arrive as span metadata. Datadog drops spans that carry no `gen_ai.*`
+  attribute, so use `instrumentSavingsLayer` there rather than `recordSavingsOnSpan`
+  (which writes `com.bivelio.*` on a span you already have, and no `gen_ai.*` unless
+  you ask for it with `genAi: true`).
+
+| Attribute | What it holds |
+| --- | --- |
+| `gen_ai.operation.name`, `gen_ai.provider.name`, `gen_ai.request.model`, `gen_ai.response.model` | `chat`, the provider and the model (without a known provider prefix) |
+| `gen_ai.usage.input_tokens`, `.output_tokens`, `.cache_read.input_tokens` | your provider's counter; absent when it reported no usage |
+| `com.bivelio.cost.basis`, `.currency`, `.baseline`, `.actual` | where the money comes from, its currency (USD by default), and both sides |
+| `com.bivelio.cost.saved.measured` \| `.reference` \| `.estimated` | the money saved, in the key of its basis only |
+| `com.bivelio.cost.net_savings_ratio` | `cost.netSavings`, a 0..1 ratio — not money |
+| `com.bivelio.calls.*`, `com.bivelio.tokens.*` | the four ledgers: avoided calls, eliminated, compressed and provider‑cached tokens |
+| `com.bivelio.request_id`, `.model.id`, `.cache.result`, `.quality.status` | ids and outcomes |
+
+</details>
+
+<details>
+<summary><b>Your ledgers in your FinOps tool — FOCUS rows and a daily savings series</b></summary>
+
+Keep each report with the time it came back, and export whenever you like:
+
+```ts
+import { writeFileSync } from "node:fs";
+import { toFocusRows, toSavingsSeries, toCsv, type SavingsRecord } from "@bivelio/savings-layer";
+
+const records: SavingsRecord[] = [];
+const answer = await layer.generate({
+  model: "openai/gpt-4o-mini",
+  messages: [{ role: "user", content: "What is 2 + 2 * 3?" }],
+});
+records.push({ at: Date.now(), report: answer.report }); // keep reports as they come back
+
+// FOCUS 1.4 rows, one per day, model and basis. Every cost column is 0 by design:
+// your provider's bill already has the spend, so these rows add savings, never cost.
+const rows = toFocusRows(records, { billingAccountId: "org-XXXXXXXX" }); // your provider billing account id
+writeFileSync("bv-sala-focus.csv", toCsv(rows));
+
+// A daily series for tools that take savings as a metric: one file per basis.
+const measured = toSavingsSeries(records).filter((r) => r.measuredSavings !== null);
+writeFileSync(
+  "vantage-measured-savings.csv",
+  toCsv(measured.map((r) => ({ date: r.date, amount: r.measuredSavings, model: r.model }))),
+);
+```
+
+The rows follow [FOCUS 1.4](https://github.com/FinOps-Open-Cost-and-Usage-Spec/FOCUS_Spec/tree/v1.4),
+the FinOps Open Cost and Usage Specification: `ChargeCategory` is `Adjustment`, the
+service provider is the one in the model id (`OpenAI`, `Anthropic`…; pass
+`serviceProviderName`, `invoiceIssuerName` or `hostProviderName` when a cloud or a
+gateway bills you), and no SKU or unit price is invented. Nothing is sent anywhere:
+`toFocusRows`, `toSavingsSeries` and `toCsv` are plain functions over the reports you
+kept. Where each file goes, as each tool documents it in September 2026:
+
+- **A FOCUS data lake or warehouse** reads every column, the `x_BiVelio*` ones included.
+- **[Finout](https://docs.finout.io/get-started-with-finout/cost-and-usage-types/focus-in-finout)**
+  loads a FOCUS CSV as a custom cost center; you send the file to Finout support.
+- **[Vantage](https://docs.vantage.sh/connecting_custom_providers)** Custom Providers
+  accept FOCUS 1.1–1.3 files but use only a few columns for cost reporting, and say
+  nothing about `x_` columns, so the savings would not show. Upload the series as a
+  [Business Metric](https://docs.vantage.sh/per_unit_costs) instead
+  (`date,amount,<labels>`), one file per basis, so a metric never mixes bases.
+  Vantage rejects two rows with the same date and labels: with `dimensions`, add
+  them as label columns too.
+- **[CloudZero](https://docs.cloudzero.com/docs/anycost-common-bill-format-cbf)** AnyCost
+  takes its own Common Bill Format; the series can go in as a
+  [Telemetry Stream](https://docs.cloudzero.com/docs/telemetry-streams).
+
+The custom columns, in the currency you pass (`currency`, USD by default):
+
+| Column | What it holds |
+| --- | --- |
+| `x_BiVelioBasis`, `x_BiVelioModelId` | the basis of every figure in the row, and the model id |
+| `x_BiVelioRequestCount`, `x_BiVelioProviderCallCount`, `x_BiVelioAvoidedCallCount` | requests, calls that reached the provider, calls avoided |
+| `x_BiVelioBaselineCost`, `x_BiVelioActualCost` | both sides of the saving; empty when the basis is `unmeasured` |
+| `x_BiVelioMeasuredSavings`, `x_BiVelioReferenceSavings`, `x_BiVelioEstimatedSavings` | `baseline − actual`, in the column of the row's basis only; negative when the layer cost you money |
+| `x_BiVelioEliminatedInputFloorCost` | the separate floor lane for context your provider cleared |
+| `x_BiVelio…InputTokens`, `x_BiVelio…OutputTokens` | the token ledgers: baseline, actual, eliminated, compressed, provider‑cached |
+
+`Tags` carries `bivelio/basis` and `bivelio/model`, plus any tags you return from the
+`tags` option. Sum `measured` and `reference` for what you can check against your
+provider invoice; `estimated` has its own column on purpose.
+
+</details>
+
 <details>
 <summary><b>Running a fleet? Seats and renewals</b></summary>
 
@@ -390,6 +749,10 @@ BVSALA_SEAT_ID=worker-03   # stable per replica; [A-Za-z0-9._:/-], max 128 chars
 
 - **Node ≥ 20.** The package is **ESM‑only** (`"type": "module"`); from CommonJS,
   `require()` works on Node ≥ 22.
+- Framework adapters: `ai` 6 or 7, `@mastra/core` ≥ 1.68 < 2, `langchain` ≥ 1.1 < 2
+  with `@langchain/core` ≥ 1.1 < 2, and `@anthropic-ai/sdk` ≥ 0.103 < 1 — optional
+  peers, needed only for the adapter you import. `ai` 7 and `@mastra/core` declare
+  Node ≥ 22 in their own `engines`.
 - Optional peer `gpt-tokenizer` for exact OpenAI token counts, loaded automatically
   when installed — without it a built‑in estimator is used. It improves the accuracy
   of estimated figures; what reaches your invoice is `measured` and `reference`, which
@@ -402,14 +765,20 @@ BVSALA_SEAT_ID=worker-03   # stable per replica; [A-Za-z0-9._:/-], max 128 chars
 
 ## Licensing & privacy
 
-BV‑SALA is commercial, per‑seat software (**€4 / seat / month** or **€39 / seat /
-year**, EUR; VAT not included). No free tier and no trial: what you can check before
-paying is the published measurement. The license is a signed token your SDK and the gateway verify **offline**; the
-managed control plane and the revocation kill‑switch are served from BiVelio. Your
-LLM traffic goes **straight to your provider** — BiVelio sees counts and cost,
-never prompts or completions.
-
-Get a key and read the terms at **[savings.bivelio.com](https://savings.bivelio.com)**.
+BV‑SALA is commercial software: a per‑seat subscription (**€4 / seat / month** or
+**€39 / seat / year**, EUR; VAT not included), paid whether or not you save, plus a
+tiered commission on measured savings only, as described at the top of this page, in
+[LICENSE](./LICENSE) §6 and in the Published Pricing it refers to,
+**[savings.bivelio.com/pricing](https://savings.bivelio.com/pricing)**. No free tier and no trial: what you can check before
+paying is the published measurement. The license is a signed token your SDK and the
+gateway verify **offline**; the managed control plane and the revocation kill‑switch
+are served from BiVelio. Your LLM traffic goes **straight to your provider** —
+BiVelio receives per‑request usage (counts, cost, the model id and opaque ids), never
+prompts, completions or provider keys; [LICENSE](./LICENSE) §5 lists every field, and
+**[savings.bivelio.com/privacy](https://savings.bivelio.com/privacy)** says how long
+each one is kept.
+
+Get a key at **[savings.bivelio.com](https://savings.bivelio.com)**.
 Onboarding & general questions: **support@bivelio.com** · licensing & compliance:
 **privacy@bivelio.com** · technical: **team@bivelio.com**.