@bivelio/savings-layer 0.1.0

package/LICENSE

@@ -0,0 +1,69 @@
+BiVelio Inc. — BV-SALA Commercial Software License Agreement
+
+Copyright (c) 2026 BiVelio Inc. All Rights Reserved.
+
+IMPORTANT — READ BEFORE USE. This Commercial Software License Agreement (the
+"Agreement") governs your use of the "@bivelio/savings-layer" software, also known
+as "BV-SALA" (the "Software"), published by BiVelio Inc. ("BiVelio"). By installing,
+copying, or using the Software, you agree to this Agreement. If you do not agree, do
+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.
+
+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,
+   or termination of your subscription immediately ends the license granted in
+   Section 1, and the Software will cease to function. You will not circumvent,
+   disable, remove, or tamper with the Software's licensing, metering, or revocation
+   mechanisms, nor use the Software after your license has ended.
+
+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.
+
+4. OWNERSHIP. The Software is the exclusive property of BiVelio and its licensors and
+   embodies valuable proprietary information and trade secrets. BiVelio retains all
+   right, title, and interest in and to the Software and all intellectual property
+   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.
+
+6. 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.
+
+7. 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
+   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,
+   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
+   between you and BiVelio regarding the Software. Unauthorized use, reproduction, or
+   distribution of the Software may result in civil and criminal penalties.
+
+For licensing and compliance inquiries, contact: BiVelio Inc. — privacy@bivelio.com

package/README.md

@@ -0,0 +1,152 @@
+# @bivelio/savings-layer — BV‑SALA
+
+**A provider‑neutral LLM execution optimizer.** BV‑SALA sits in front of any LLM
+provider and, for every request, picks the **cheapest execution that still meets
+your quality bar** — then hands you a full, auditable `SavingsReport`.
+
+It is **not** a prompt compressor. Compression is the *fourth* thing it tries, not
+the first.
+
+> **Commercial software — © 2026 BiVelio Inc.** Free to install, **paid to run**:
+> BV‑SALA is **fail‑closed** and executes only with a valid, active BiVelio license
+> key. Verification is **offline** (no phone‑home to answer a request) and **your
+> prompts never leave your infrastructure** — only counts and cost are ever reported.
+> Use is governed by the [LICENSE](./LICENSE) and the BiVelio Terms. Not affiliated
+> with, and not a wrapper around, any third‑party library.
+
+## Install
+
+```bash
+pnpm add @bivelio/savings-layer
+# or: npm i @bivelio/savings-layer  ·  yarn add @bivelio/savings-layer
+```
+
+You also need a **license key**. Try the optimizer **free in your browser** — paste
+your own data and watch the meter — at **[savings.bivelio.com](https://savings.bivelio.com)**,
+then subscribe (**$4 / seat / month** or **$39 / seat / year**, USD) to get your key.
+
+## Quick start
+
+```ts
+import { createSavingsLayer } from "@bivelio/savings-layer";
+
+const layer = createSavingsLayer({
+  provider: yourProvider,                        // any OpenAI-compatible / self-hosted provider
+  licenseKey: process.env.BIVELIO_LICENSE_KEY,   // required — from your savings.bivelio.com dashboard
+  licenseServerUrl: "https://savings.bivelio.com", // license check + kill-switch
+});
+
+const { data, text, report } = await layer.generate({
+  model: "openai/gpt-4o-mini",
+  messages: [{ role: "user", content: "What is 2 + 2 * 3?" }],
+  response: { contractId: "answer:v1", schema, maxOutputTokens: 220 },
+});
+
+console.log(text);                   // "8"  (computed locally — no LLM call)
+console.log(report.calls.avoidedLlm); // → whole calls you never paid for
+console.log(report.cost.netSavings);  // → verified savings, per request
+```
+
+The hard requirements are a `provider` and a valid `licenseKey`: BV‑SALA is a paid
+product and **refuses to run unlicensed, expired, or tampered** (it throws
+`LicenseError` at the `generate()` entry). Get a key at
+[savings.bivelio.com](https://savings.bivelio.com).
+
+> The `devUnlicensed` flag and `BVSALA_DEV_OPEN=1` are development‑only, honored
+> **only when building from source** (this repo's tests and benchmarks). They are
+> **disabled in this published package** — a valid `licenseKey` is the only way to
+> run it. They are not a way to use the product for free.
+
+Every component ships with an in‑memory default and is independently swappable
+(Redis exact cache, pgvector/Qdrant semantic cache, a real tokenizer, an LLMLingua
+sidecar, XGrammar/llguidance backends, …).
+
+## The optimization order (cheapest first)
+
+1. **Avoid the call entirely** — resolvers, exact & semantic cache, singleflight.
+2. **Avoid auxiliary calls** — retrieval, tools, planners, validators, retries.
+3. **Eliminate unnecessary context** before trying to compress it.
+4. **Compress** the tokens that genuinely must be sent.
+5. **Constrain generation** to emit only the structure and length required.
+
+Provider prompt/KV caching is treated as a cost/latency saving — **never** as a
+reduction of the logical prompt size.
+
+## Four separate ledgers (never summed)
+
+Mixing these produces misleading metrics, so BV‑SALA keeps them apart:
+
+| Ledger | Meaning |
+| --- | --- |
+| `avoided_calls` | LLM / retrieval / tool calls that never executed |
+| `eliminated_tokens` | information dropped because it was not needed |
+| `compressed_tokens` | information kept, but encoded with fewer tokens |
+| `provider_cached_tokens` | tokens still in the prompt, billed/processed more cheaply |
+
+A cache hit removes a whole call. A re‑encode makes a payload smaller. Compression
+drops redundant words. A prefix cache makes tokens cheaper without removing them.
+Four different things — summing them would lie to you, so the report never does.
+
+## The decision cascade
+
+```
+Request
+  → Canonicalize + Policy (risk & freshness)
+  → Deterministic resolvers ─────────────► answer (0 calls)
+  → Exact cache ─────────────────────────► answer (0 calls)
+  → Singleflight (coalesce in-flight)
+      → Safe semantic cache ─────────────► answer (0 calls)
+      → Execution router (NO / SINGLE / MULTI / TOOL)
+      → Tool selector (drop irrelevant, gate writes)
+      → Retrieval: retrieve → dedupe → rerank → adaptive-k
+      → Context projection (memory deltas)
+      → Compression (only when net-positive)
+      → JSON / TOON / CSV selector (tokenizer-aware)
+      → Output contract + constrained decoding
+      → ONE primary LLM call
+      → Structural + semantic validation (+ ≤1 repair)
+      → Local render / transcode / cache write
+  → SavingsReport + traces
+```
+
+## Why formats are chosen, not assumed
+
+A compact encoding can be *larger* than plain JSON on nested/non‑uniform data, so
+BV‑SALA counts — with the destination model's tokenizer — before switching:
+
+```
+tokens(encoded payload) + tokens(instruction to understand it) + quality penalty
+```
+
+…and only moves away from JSON when a challenger clears both an absolute (`≥64`
+tokens) and a relative (`≥8%`) threshold:
+
+```
+big uniform table   → json 1716, toon 708  → chosen: toon (−58.7%)
+small nested object → json 44,   toon 116  → chosen: json-compact
+```
+
+## What's inside
+
+Canonicalization & safe cache keys · risk/freshness policy · exact + singleflight +
+safe semantic cache · deterministic resolvers · Adaptive‑RAG execution router & tool
+selector · retrieval dedupe→rerank→adaptive‑k · conversation memory & context
+projection · tokenizer‑aware JSON/TOON/CSV selection · JSON‑Schema validation &
+constrained decoding · net‑positive compression · a provider‑neutral adapter · and a
+trace collector that builds the `SavingsReport`. Every piece is pluggable.
+
+## Licensing & privacy
+
+BV‑SALA is commercial, per‑seat software (**$4 / seat / month** or **$39 / seat /
+year**, USD). The license is a signed token your SDK verifies **offline**; the
+managed control plane (semantic cache, learned thresholds, dashboards) 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)**.
+Onboarding & general questions: **support@bivelio.com** · licensing & compliance:
+**privacy@bivelio.com** · technical: **team@bivelio.com**.
+
+---
+
+© 2026 BiVelio Inc. All rights reserved. BV‑SALA is a trademark of BiVelio Inc.