Repository navigation
Releases
BV-SALA 1.2.3 — fixes from the pre-launch audit
Changed: what you will notice after upgrading
layer.generate({ tools })sends every tool you declare, write and
destructive tools included, as the framework adapters and untyped catalogues
already did. Until now a catalogue that declaredrisklost its write tools on
any request that did not contain one of 11 verbs ("Refund order 4411" was sent
withoutrefund_order). The gate is now opt-in:
new ToolSelector({ withholdWriteTools: true }). A write or destructive tool left
out by the selector is never credited as a saving: it does not count in
tokens.eliminatedInputor incost.*, and thetool-selectortrace lists it
underwithheldWritesNotCredited. If you setmaxTools, it keeps pruning read
tools exactly as before, and outside an action request the write tools are sent
on top of them, so a request can carry more thanmaxToolstools.- The exact cache starts cold. Its key generation moves from
n2ton3(see
the key fix below), so no entry written by an earlier version is read again:
expect fewer exact hits for the first days. Old entries in Redis, KV or
PostgreSQL stay until their TTL runs out. - The exact cache keeps capital letters. The exact key and in-flight coalescing
no longer merge questions that differ only in a capital that changes the meaning:
curl -Oandcurl -o,git branch -Dand-d,5 MWand5 mW,3 Mband
3 MB,[A-Z]+and[a-z]+,Nameandname. Only the capital that opens a
turn is still folded, along with accents, sentence punctuation and whitespace.
Near-duplicates that differ in other capitals (ALL CAPS, a lower-cased proper
noun) are now separate entries: expect fewer exact hits on those. An exact repeat
always hits. The semantic cache (opt-in) is unchanged. - Requests that transform their own text are keyed verbatim. When any turn,
the system prompt included, asks to translate, rewrite, summarize, fix, convert,
format or correct text, each turn enters the exact key as written, trimmed only at
the ends: "Translate to French: I love Polish food" and "…polish food", or "Can you
help me?" and "Can you help me!", never share a cached answer. The word list is
wide on purpose; with one of those words in your system prompt, only exact
repeats hit. - Empty answers and calls without a full usage counter are not cached. They are
served as before, but not written to the exact or semantic cache, so a repeat goes
back to the provider. An endpoint that never reports usage therefore stops using
the cache. - An HTTP 200 without an answer is an error. A 2xx body that carries an error
({"error": …}, Anthropic's{"type": "error"}) or no completion (no
choices[0].message, nocontent, nofinishReason) makesgenerate()throw
instead of returning empty text. Batch results are unchanged. - Models without a list price are
estimated. A model with no catalog row and
none incostModelsordefaultCostModelis still priced at the illustrative
rate, butcost.basisis"estimated", not"measured", and apricetrace
carriespriceSource: "illustrative". Ids with:(gpt-4o-mini:free) and
relatives whose suffix is not an alias of the same model (gpt-4o-mini-tts
no longer takesgpt-4o-mini's row) have no list price; dated,
-latest,-previewand-expids keep their model's. - Random output and the current time are not served from cache. A request
whose user turns ask for random or freshly generated output (a random pick, a new
UUID or password, a dice roll, a coin toss) or for the current time or date skips
the exact and semantic cache. Withseed, a random request is cacheable again; a
time question never is. The phrases are in English and Spanish; a false positive
costs one cache hit. - The arithmetic resolver answers only a bare question: one user message, with
no system prompt, no earlier turns, no tools and no structured data, phrased as a
question with an operator. It declines dates, phone numbers, percentages,2.500,
leading zeros, numbers a double cannot hold exactly, and results it cannot write
exactly in nine decimals (10 / 3). A Mastra agent withinstructionssends the
question to the model. It also declines superscripts, subscripts, circled numbers
and fraction characters: "What is 3² + 4²?" was answered locally as 74 and now goes
to the model. The quickstart (What is 2 + 2 * 3?→"8") is unchanged.
Fixed
- Exact-cache key. Normalization no longer merges different code questions: text
in backticks or code blocks is kept as written, a sign attached to what follows is
an operator (if (ok)andif (!ok)are two questions), and quoted text keeps its
case. It runs in linear time on adversarial input, and the tool selector's
relevance folds backticks and case again. npm installwith current peers. Installing next to@anthropic-ai/sdk1.x
orgpt-tokenizer4 no longer fails with ERESOLVE: the optional peer ranges are
now>=0.103.0 <2and^3 || ^4, andbvsala initpicks the Anthropic SDK
adapter for SDK 1.x. Projects on AI SDK 5, LangChain 0.3 or Mastra below 1.68
still need--legacy-peer-deps; the README lists each adapter's minimum version.- Counting tokens with
gpt-tokenizeris linear. A long run of one kind of
character (400 KB of spaces took 70 s) no longer blocks the process. Counts for
text without such runs are unchanged; inside a run longer than 512 characters the
count can be at most 2 tokens higher per 512 characters, never lower. contentas a list of parts. OpenAI-compatible endpoints that return
contentas a list of parts (for example Mistral reasoning models), also when
streaming, no longer fail withTypeError: me.trim is not a function: the answer
is the text of the text parts.
Gateway and bvsala CLI
- Without a key the gateway meters locally. In community mode every request is
measured on this machine with the provider's usage: log line, exit summary and the
local/_bvsalareport routes. Only sending it to BiVelio needs
BIVELIO_SERVICE_KEY. The exit summary counts the inference requests that went
through, andmeteringin/_bvsala/v1/statusis now alwaystrue. With
BVSALA_GATEWAY_USAGE_INJECT=1,include_usageis injected without a key too. - Subscription traffic keeps its TTL. The cache-write TTL lever (1h→5m) no
longer touches Claude Max/Pro traffic: there is no write premium to save. Traffic
billed per token is unchanged. bvsala claude(andqwen,goose,aider) keeps the base URL you already
had. A pre-setANTHROPIC_BASE_URL(ANTHROPIC_HOSTfor Goose,
OPENAI_BASE_URLorANTHROPIC_API_BASEfor Aider) becomes the gateway's
upstream, with a line that says so. One with a path prefix, or one that disagrees
withBVSALA_GATEWAY_UPSTREAM, stops the wrapper with exit 1 and says why.- A provider cut mid-response reaches the client as a cut, not as a complete
body, and the request is counted as not metered with its reason. - The request path never changes the upstream host. Repeated leading slashes
are collapsed (a base URL ending in/works), an absolute-form target keeps only
its path, and a target that would resolve to another origin, or is not a path
(OPTIONS *), gets a 400 and is not forwarded. --port=Nworks like--port N; any other--port…form is an error.bvsala gatewayandbvsala doctorreject what they do not know. An unknown
or misspelled flag or a stray argument (--upsteam,-p,--Port) exits with 1,
names the flag and suggests the closest one, instead of starting with defaults.bvsala doctorand the README no longer tie the levers to a PRO license: they run
free, with no key. The same now holds for the gateway's startup lines,
bvsala --helpand the terminal guides: in community mode the levers are on and
free, and the startup line names the full switch,BVSALA_GATEWAY_ELISION=0. Only
with an organization license does that license's feature list apply.- Wrappers keep stdout clean.
bvsala <terminal>prints its banner, the
terminal note and the per-request log on stderr, so
bvsala claude -p … --output-format json | jqgets clean JSON.bvsala gateway
on its own is unchanged. - Ctrl-C belongs to the agent. Inside
bvsala aider,bvsala gooseor any
wrapped agent that keeps running after Ctrl-C, the gateway stays up until the
agent exits, then exits with the agent's code. SIGTERM is forwarded to the agent. bvsala gatewayalways stops. Open connections are cut 5 seconds after
Ctrl-C, a stuck streaming response included, and a second Ctrl-C exits at once
(code 130; 143 for SIGTERM).bvsala gemini,codex,opencodeandkilokeep the endpoint you already
had (GOOGLE_GEMINI_BASE_URL,OPENAI_BASE_URL, or abaseURLin the inline
opencode/Kilo config), asbvsala claudealready did: the gateway forwards
there, or the wrapper stops with exit 1 and says why. For codex, opencode and
Kilo the base URL must end in/v1.- Claude Code through
--upstream deepseekis metered and counted in the exit
summary; before, every request was forwarded but reported as not metered. bvsala initwires the cloud from the environment. The code it prints or
writes (andexamples/stacks) haslicenseServerUrlandserviceAccountKey
enabled: withBIVELIO_SERVICE_KEYset, usage reaches the Savings Cloud dashboard
and the license renews itself; with no keys, nothing is sent to BiVelio. The
README's adapter snippets carrylicenseServerUrltoo.
Python client
pyproject.tomllinks the public repository, and the README's LICENSE link is an
absolute GitHub URL (it was a 404 on pypi.org). From the extracted sdist, the
parity tests are skipped with their reason instead of failing.
Catalo...
Python client 1.2.3
Python client 1.2.3, aligned with @bivelio/savings-layer 1.2.3.
pyproject.tomllinks the public repository, and the README's LICENSE link is an absolute GitHub URL (it was a 404 on pypi.org).- The gateway's levers are free and need no key; a BiVelio key only adds Savings Cloud (team dashboard, shared measurement, seats).
- Full changes of this release: see the
v1.2.3release and CHANGELOG.md.
BV-SALA 1.2.1 — README revisado para la comunidad + paper v2.3-r1
Parche de documentación, sin cambios de código: README con primera lectura de ~135 líneas (evidencia medida, pitch, instalación) y manual plegado; enlace al paper v2.3-r1; .zenodo.json listo.
Python client 1.2.1 — alineado con 1.2.1
Parche de documentación: README revisado y paper v2.3-r1 enlazado.
BV-SALA 1.2.0 — cache-aware prompt management + cross-provider shadow + live evidence
BV-SALA 1.2.0 — cache-aware prompt management, cross-provider shadow, live evidence
Three things in this release:
-
Cacheable-prefix reorder (
savings.cachePrefix: true, opt-in). A per-request timestamp, UUID or epoch in yoursystemprompt used to poison the provider's prefix cache: 0 % hit-rate and a full paid cache write on every call. With one flag, the layer moves those lines out of the cacheable prefix and declares only the stable part. Measured live (claude-haiku-4-5): 0 % → 95 % hit-rate, −82.8 % per request, on the provider's own counters. -
Cross-provider shadow (
savings.crossProviderShadow: true, measure-only). What your request's measured usage would have cost on DeepSeek/Qwen/GLM at list prices —basis: "shadow", nothing routed, nothing billed. -
The preregistered roadmap, executed live: the ρ curve (14.7 % / 23.7 %), the dedup × cache_control factorial (85.9 % with attribution) and the cascade non-inferiority (67.9 %, no quality loss on a golden list). Evidence in
benchmarks/evidencia/*-2026-11-15.json; paper §6.6–6.9.
npm i @bivelio/savings-layer · pip install bivelio-savings-layer
Python client 1.2.0 — aligned with 1.2.0
BV-SALA 1.2.0 — cache-aware prompt management, cross-provider shadow, live evidence
Three things in this release:
-
Cacheable-prefix reorder (
savings.cachePrefix: true, opt-in). A per-request timestamp, UUID or epoch in yoursystemprompt used to poison the provider's prefix cache: 0 % hit-rate and a full paid cache write on every call. With one flag, the layer moves those lines out of the cacheable prefix and declares only the stable part. Measured live (claude-haiku-4-5): 0 % → 95 % hit-rate, −82.8 % per request, on the provider's own counters. -
Cross-provider shadow (
savings.crossProviderShadow: true, measure-only). What your request's measured usage would have cost on DeepSeek/Qwen/GLM at list prices —basis: "shadow", nothing routed, nothing billed. -
The preregistered roadmap, executed live: the ρ curve (14.7 % / 23.7 %), the dedup × cache_control factorial (85.9 % with attribution) and the cascade non-inferiority (67.9 %, no quality loss on a golden list). Evidence in
benchmarks/evidencia/*-2026-11-15.json; paper §6.6–6.9.
npm i @bivelio/savings-layer · pip install bivelio-savings-layer
BV-SALA paper v2.3 (open-core release 1.2.0) — PDF
Paper v2.3-r1 «Verifiable Measurement of Cost Savings in LLM Applications — Open-Core Edition» (noviembre 2026, 14 págs).
Corregido tras la revisión externa previa a publicación (informe 2026-11-15): estimador pooled primario (31,50 % / 75,08 % con intervalos exactos), media familiar secundaria (22,88 % / 70,71 %), 41,08 pp descriptivos (no causales), coste con escrituras de caché, identidad de coste de dos factores con prueba, ensayos de noviembre exploratorios, juez de la cascada corregido (24/24 con aceptadas declaradas y respuestas publicadas), referencias [5][26][27] corregidas. Fuente: docs/PAPER.md y docs/paper/main.tex (arXiv-ready).
BV-SALA paper v2.2 (open-core release 1.1.0) — PDF
Paper v2.2 «Verifiable Measurement of Cost Savings in Large Language Model Applications — Open-Core Edition» (noviembre 2026).
PDF compilado con LaTeX (MiKTeX). El fuente está en docs/PAPER.md y docs/paper/main.tex (arXiv-ready). Resultados: 31,5 % [25,7–36,7] en gpt-4o-mini, 75,1 % [69,3–79,6] en claude-sonnet-5, 2,49 % [1,50–3,57] replay del gateway.
BV-SALA 1.1.1 — corrected packaging text
BV-SALA 1.1.1 — corrected packaging text
Patch release: no code changes. Republishes the READMEs with the corrections from the data audit:
- The Python client no longer says "Commercial software … paid to run"; it states the Apache-2.0 open-core license.
- The npm README no longer says "the repository is private" (it is public) and links the paper as v2.2.
npm i @bivelio/savings-layer · pip install bivelio-savings-layer
BV-SALA 1.1.0 — savings levers in the batch, cache audit, cascade 2026
BV-SALA 1.1.0 — savings levers reach the batch surface, cache audit, cascade 2026
On top of the 1.0.0 open-core release (Apache-2.0, no keys, zero telemetry), 1.1.0 adds three things:
-
Cache-break audit. The layer now detects per-request content (ISO/RFC 2822 timestamps, UUID v4, epoch ms/s) in your cacheable
systemprefix and reports it as acache-audittrace plus a one-per-process warning. It tells you why your prompt cache never hits — without rewriting your prompt. -
Levers inside the batch.
layer.batches.submit()runs the same pure, lossless levers asgenerate(): elision by supersession (default-on) and tool-output compaction (opt-in). Plus intra-batch dedup (submit(…, { deduplicate: true })): identical items are sent once and replayed from the first result, and the summary never double-counts the money. -
Cascade 2026. The default model-cascade table now covers the current frontier's same-family cheap siblings (
gpt-5/5.2/5.4 → *-mini,claude-opus-5/-5-5 → claude-haiku-4-5).claude-sonnet-5/-5-5stay without a default pair on purpose (r = 0.50 exact leaves no quality margin).
Install: npm i @bivelio/savings-layer · npx @bivelio/savings-layer claude · full changelog in CHANGELOG.md · paper at savings.bivelio.com/paper.