bivelio-savings-layer 0.1.0__tar.gz

bivelio_savings_layer-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+# Artefactos de Python: nada de esto se versiona.
+__pycache__/
+*.py[cod]
+.pytest_cache/
+dist/
+build/
+*.egg-info/

bivelio_savings_layer-0.1.0/LICENSE

@@ -0,0 +1,163 @@
+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 BiVelio subscription (paid, or granted by BiVelio at no charge, for
+   example through a promotional code, a pilot, or the free Measure license) 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. Under a Measure license the Software runs in shadow mode only: it
+   forwards your requests to your provider unchanged, applies no optimization, and
+   reports estimated savings that are never billed.
+
+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; when a paid subscription
+   ends, BiVelio may instead grant you a Measure license, under which the Software
+   continues in shadow mode only. 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 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
+   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.
+   (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), the value, at the provider's cache-read price, of
+         input tokens your provider reported as cleared from context, and the
+         discount your provider's own prompt cache gave the request and the
+         cache-write premium it billed, which are shown apart and never used to
+         calculate the fees in Section 6.
+   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. 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 or for a plan that includes a number of seats,
+   payable whether or not the Software produces any saving; and (b) only if your
+   subscription is on a plan that the Published Pricing lists as carrying a
+   commission, 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 10 survive termination.
+
+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.
+
+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.
+
+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
+   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

bivelio_savings_layer-0.1.0/PKG-INFO

@@ -0,0 +1,161 @@
+Metadata-Version: 2.4
+Name: bivelio-savings-layer
+Version: 0.1.0
+Summary: Python client for the BiVelio Savings Layer gateway: route the official OpenAI and Anthropic SDKs through your local bvsala gateway and get each request's report, measured with your provider's own usage counter.
+Project-URL: Homepage, https://savings.bivelio.com
+Project-URL: Pricing, https://savings.bivelio.com/pricing
+Project-URL: Privacy, https://savings.bivelio.com/privacy
+Project-URL: Gateway (npm), https://www.npmjs.com/package/@bivelio/savings-layer
+Author-email: "BiVelio Inc." <support@bivelio.com>
+License-Expression: LicenseRef-BiVelio-Commercial
+License-File: LICENSE
+Keywords: anthropic,cost-optimization,llm,llm-costs,openai,token-accounting
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# BiVelio Savings Layer for Python
+
+A thin client for the local **bvsala gateway**. It routes the official OpenAI
+and Anthropic Python SDKs through the gateway and hands you, for each request,
+the report the gateway recorded for your BiVelio dashboard: the provider's own
+token counts, the cost at the model's list price, and where the figure comes
+from (`cost.basis`).
+
+- **The gateway does the work.** It ships in the npm package
+  [`@bivelio/savings-layer`](https://www.npmjs.com/package/@bivelio/savings-layer),
+  holds your BiVelio license, forwards each request to your provider and
+  measures it with the provider's usage counter. This package prices nothing
+  itself, so its numbers are exactly the dashboard's.
+- **Fail-closed.** Without a running gateway and a live license, `wrap()`
+  raises. It never falls back to calling your provider directly.
+- **No dependencies.** Standard library only. It does not import the OpenAI or
+  Anthropic SDKs; you bring them.
+- **Your prompts never reach BiVelio.** The client only talks to the gateway on
+  `127.0.0.1`, ignoring any HTTP proxy settings, and the gateway forwards your
+  requests to your provider. What it sends to BiVelio is per-request usage
+  (token counts, cost, the model id and opaque ids), never your content: the
+  LICENSE, section 5, lists every field.
+
+This package measures. The saving levers of the TypeScript SDK do not run in
+Python; the gateway's own levers apply to Anthropic `/v1/messages` traffic with
+a PRO license.
+
+## Requirements
+
+- Python 3.10 or newer.
+- Node.js 20 or newer, for the gateway, and a BiVelio license with a service key
+  (`BIVELIO_SERVICE_KEY`): the gateway does not start without them.
+
+## Install
+
+```bash
+pip install bivelio-savings-layer
+```
+
+The package is `bivelio-savings-layer` on PyPI and `bvsala` in your code
+(`import bvsala`). From a checkout of the repository, to try unreleased changes:
+
+```bash
+pip install ./packages/python
+```
+
+## Start a gateway
+
+One gateway per provider:
+
+```bash
+export BIVELIO_SERVICE_KEY=…
+npx -p @bivelio/savings-layer bvsala gateway                                 # Anthropic, on 8402
+npx -p @bivelio/savings-layer bvsala gateway --upstream openai --port 8403   # OpenAI, on 8403
+python -m bvsala --url http://127.0.0.1:8403 status                          # version, upstream, license
+```
+
+## Use it
+
+```python
+import bvsala
+from openai import OpenAI
+
+gw = bvsala.Gateway("http://127.0.0.1:8403")
+client = gw.wrap(OpenAI())          # a copy that goes through the gateway; OpenAI() is untouched
+
+resp = client.chat.completions.create(
+    model="gpt-4o-mini", messages=[{"role": "user", "content": "Hi"}],
+)
+report = gw.report(resp)
+print(report.summary())             # gpt-4o-mini · measured · $0.000024 (in 100, cached 40, out 20)
+print(report.cost.actual, report.cost.basis, report.tokens.actual_output)
+```
+
+Streaming works the same way. For OpenAI Chat Completions, ask for usage in the
+request, or the provider sends no counter and the report says so:
+
+```python
+stream = client.chat.completions.create(
+    model="gpt-4o-mini", messages=[{"role": "user", "content": "Hi"}],
+    stream=True, stream_options={"include_usage": True},
+)
+for chunk in stream:
+    if chunk.choices:
+        print(chunk.choices[0].delta.content or "", end="")
+print(gw.report(stream).summary())
+```
+
+Anthropic:
+
+```python
+from anthropic import Anthropic
+
+gw = bvsala.Gateway()                # $BVSALA_GATEWAY_URL or http://127.0.0.1:8402
+claude = gw.wrap(Anthropic())
+msg = claude.messages.create(model="claude-haiku-4-5", max_tokens=256,
+                             messages=[{"role": "user", "content": "Hi"}])
+print(gw.report(msg).summary())
+```
+
+`gw.report()` accepts a response, a stream you have read, any chunk or event of
+it, a raw response from `with_raw_response`, or an id string. It also reads a
+LiteLLM response sent with `extra_headers=bvsala.REPORT_HEADERS`, from the
+provider headers LiteLLM keeps in `_hidden_params` (checked against LiteLLM's
+source, not yet end to end).
+
+`gw.report()` waits up to `wait` seconds (5 by default) for a request still in
+flight; after that the report comes back with `status == "pending"`. In async
+code use `await gw.areport(resp)`; `wrap()` also takes `AsyncOpenAI`,
+`AzureOpenAI` and `AsyncAnthropic`.
+
+`gw.totals()` adds up the reports this process fetched. Savings stay split by
+basis (`measured`, `reference`, `estimated`), never added into one figure.
+
+### Any other client
+
+The gateway side works with any HTTP client: send `x-bvsala-report: 1`, read
+the `x-bvsala-request-id` response header, then
+`GET /_bvsala/v1/reports/<id>` on the gateway. `bvsala.REPORT_HEADERS` is that
+header as a dict, for `extra_headers=` or `default_headers=`.
+
+## Errors
+
+| Exception | When |
+|---|---|
+| `GatewayUnavailable` | nothing answers at the URL, or it is not a bvsala gateway with local reports (0.4.26 or later is needed) |
+| `LicenseInactive` | the gateway's license does not serve new requests; `.state` says why |
+| `GatewayMismatch` | the client points at a different provider than the one the gateway forwards to |
+| `ReportNotFound` | the gateway holds no report for that id (only requests sent with `x-bvsala-report: 1` have one, kept for at most an hour) |
+
+## License
+
+Commercial software, © 2026 BiVelio Inc. Free to install, paid to run: see
+[LICENSE](./LICENSE) and [savings.bivelio.com](https://savings.bivelio.com).

bivelio_savings_layer-0.1.0/README.md

@@ -0,0 +1,134 @@
+# BiVelio Savings Layer for Python
+
+A thin client for the local **bvsala gateway**. It routes the official OpenAI
+and Anthropic Python SDKs through the gateway and hands you, for each request,
+the report the gateway recorded for your BiVelio dashboard: the provider's own
+token counts, the cost at the model's list price, and where the figure comes
+from (`cost.basis`).
+
+- **The gateway does the work.** It ships in the npm package
+  [`@bivelio/savings-layer`](https://www.npmjs.com/package/@bivelio/savings-layer),
+  holds your BiVelio license, forwards each request to your provider and
+  measures it with the provider's usage counter. This package prices nothing
+  itself, so its numbers are exactly the dashboard's.
+- **Fail-closed.** Without a running gateway and a live license, `wrap()`
+  raises. It never falls back to calling your provider directly.
+- **No dependencies.** Standard library only. It does not import the OpenAI or
+  Anthropic SDKs; you bring them.
+- **Your prompts never reach BiVelio.** The client only talks to the gateway on
+  `127.0.0.1`, ignoring any HTTP proxy settings, and the gateway forwards your
+  requests to your provider. What it sends to BiVelio is per-request usage
+  (token counts, cost, the model id and opaque ids), never your content: the
+  LICENSE, section 5, lists every field.
+
+This package measures. The saving levers of the TypeScript SDK do not run in
+Python; the gateway's own levers apply to Anthropic `/v1/messages` traffic with
+a PRO license.
+
+## Requirements
+
+- Python 3.10 or newer.
+- Node.js 20 or newer, for the gateway, and a BiVelio license with a service key
+  (`BIVELIO_SERVICE_KEY`): the gateway does not start without them.
+
+## Install
+
+```bash
+pip install bivelio-savings-layer
+```
+
+The package is `bivelio-savings-layer` on PyPI and `bvsala` in your code
+(`import bvsala`). From a checkout of the repository, to try unreleased changes:
+
+```bash
+pip install ./packages/python
+```
+
+## Start a gateway
+
+One gateway per provider:
+
+```bash
+export BIVELIO_SERVICE_KEY=…
+npx -p @bivelio/savings-layer bvsala gateway                                 # Anthropic, on 8402
+npx -p @bivelio/savings-layer bvsala gateway --upstream openai --port 8403   # OpenAI, on 8403
+python -m bvsala --url http://127.0.0.1:8403 status                          # version, upstream, license
+```
+
+## Use it
+
+```python
+import bvsala
+from openai import OpenAI
+
+gw = bvsala.Gateway("http://127.0.0.1:8403")
+client = gw.wrap(OpenAI())          # a copy that goes through the gateway; OpenAI() is untouched
+
+resp = client.chat.completions.create(
+    model="gpt-4o-mini", messages=[{"role": "user", "content": "Hi"}],
+)
+report = gw.report(resp)
+print(report.summary())             # gpt-4o-mini · measured · $0.000024 (in 100, cached 40, out 20)
+print(report.cost.actual, report.cost.basis, report.tokens.actual_output)
+```
+
+Streaming works the same way. For OpenAI Chat Completions, ask for usage in the
+request, or the provider sends no counter and the report says so:
+
+```python
+stream = client.chat.completions.create(
+    model="gpt-4o-mini", messages=[{"role": "user", "content": "Hi"}],
+    stream=True, stream_options={"include_usage": True},
+)
+for chunk in stream:
+    if chunk.choices:
+        print(chunk.choices[0].delta.content or "", end="")
+print(gw.report(stream).summary())
+```
+
+Anthropic:
+
+```python
+from anthropic import Anthropic
+
+gw = bvsala.Gateway()                # $BVSALA_GATEWAY_URL or http://127.0.0.1:8402
+claude = gw.wrap(Anthropic())
+msg = claude.messages.create(model="claude-haiku-4-5", max_tokens=256,
+                             messages=[{"role": "user", "content": "Hi"}])
+print(gw.report(msg).summary())
+```
+
+`gw.report()` accepts a response, a stream you have read, any chunk or event of
+it, a raw response from `with_raw_response`, or an id string. It also reads a
+LiteLLM response sent with `extra_headers=bvsala.REPORT_HEADERS`, from the
+provider headers LiteLLM keeps in `_hidden_params` (checked against LiteLLM's
+source, not yet end to end).
+
+`gw.report()` waits up to `wait` seconds (5 by default) for a request still in
+flight; after that the report comes back with `status == "pending"`. In async
+code use `await gw.areport(resp)`; `wrap()` also takes `AsyncOpenAI`,
+`AzureOpenAI` and `AsyncAnthropic`.
+
+`gw.totals()` adds up the reports this process fetched. Savings stay split by
+basis (`measured`, `reference`, `estimated`), never added into one figure.
+
+### Any other client
+
+The gateway side works with any HTTP client: send `x-bvsala-report: 1`, read
+the `x-bvsala-request-id` response header, then
+`GET /_bvsala/v1/reports/<id>` on the gateway. `bvsala.REPORT_HEADERS` is that
+header as a dict, for `extra_headers=` or `default_headers=`.
+
+## Errors
+
+| Exception | When |
+|---|---|
+| `GatewayUnavailable` | nothing answers at the URL, or it is not a bvsala gateway with local reports (0.4.26 or later is needed) |
+| `LicenseInactive` | the gateway's license does not serve new requests; `.state` says why |
+| `GatewayMismatch` | the client points at a different provider than the one the gateway forwards to |
+| `ReportNotFound` | the gateway holds no report for that id (only requests sent with `x-bvsala-report: 1` have one, kept for at most an hour) |
+
+## License
+
+Commercial software, © 2026 BiVelio Inc. Free to install, paid to run: see
+[LICENSE](./LICENSE) and [savings.bivelio.com](https://savings.bivelio.com).

bivelio_savings_layer-0.1.0/pyproject.toml

@@ -0,0 +1,60 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "bivelio-savings-layer"
+# La versión vive en UN sitio, src/bvsala/__init__.py (`__version__`), y hatch la
+# lee de ahí: la que devuelve `bvsala.__version__` es la que sube a PyPI.
+# Política: versión PROPIA, no la del paquete de npm (docs/PUBLICAR-PYPI.md). La
+# etiqueta de la Release es `py-v<versión>` y publish-pypi.yml exige que coincida.
+dynamic = ["version"]
+description = "Python client for the BiVelio Savings Layer gateway: route the official OpenAI and Anthropic SDKs through your local bvsala gateway and get each request's report, measured with your provider's own usage counter."
+readme = "README.md"
+requires-python = ">=3.10"
+# Software comercial: la LICENSE es la misma que la del paquete de npm, byte a
+# byte (test/python-cliente.test.ts lo comprueba).
+license = "LicenseRef-BiVelio-Commercial"
+license-files = ["LICENSE"]
+authors = [{ name = "BiVelio Inc.", email = "support@bivelio.com" }]
+keywords = ["llm", "cost-optimization", "llm-costs", "token-accounting", "openai", "anthropic"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+  "Typing :: Typed",
+]
+# Sin clasificador «License :: …»: con `license` como expresión SPDX (PEP 639)
+# están prohibidos, y PyPI rechaza la subida si van los dos.
+# Sin dependencias: solo la biblioteca estándar. Los SDK de OpenAI y Anthropic
+# los trae el usuario; este paquete no los importa.
+dependencies = []
+
+# Sin «Repository»: el repositorio es privado y el enlace daría un 404 en PyPI.
+[project.urls]
+Homepage = "https://savings.bivelio.com"
+Pricing = "https://savings.bivelio.com/pricing"
+Privacy = "https://savings.bivelio.com/privacy"
+"Gateway (npm)" = "https://www.npmjs.com/package/@bivelio/savings-layer"
+
+[tool.hatch.version]
+path = "src/bvsala/__init__.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/bvsala"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/bvsala", "tests", "README.md", "LICENSE", "pyproject.toml"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+addopts = "-p no:cacheprovider"

bivelio_savings_layer-0.1.0/src/bvsala/__init__.py

@@ -0,0 +1,46 @@
+"""BiVelio Savings Layer for Python — a thin client for the local ``bvsala`` gateway.
+
+The gateway (``bvsala gateway``, in the npm package ``@bivelio/savings-layer``)
+holds the BiVelio license, forwards your requests to the provider and measures
+each one with the provider's own usage counter. This package routes the
+official OpenAI and Anthropic SDKs through it and hands you, per request, the
+report the gateway recorded for your dashboard::
+
+    import bvsala
+    from openai import OpenAI
+
+    gw = bvsala.Gateway("http://127.0.0.1:8403")  # bvsala gateway --upstream openai --port 8403
+    client = gw.wrap(OpenAI())
+    resp = client.chat.completions.create(model="gpt-4o-mini", messages=[{"role": "user", "content": "Hi"}])
+    print(gw.report(resp).summary())
+
+Commercial software, © 2026 BiVelio Inc. See LICENSE.
+"""
+
+from ._errors import BvsalaError, GatewayMismatch, GatewayUnavailable, LicenseInactive, ReportNotFound
+from ._gateway import DEFAULT_URL, ENV_URL, REPORT_HEADER, REPORT_HEADERS, Gateway
+from ._keys import REQUEST_ID_HEADER
+from ._report import Calls, Cost, GatewayStatus, Report, Tokens, Totals
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "BvsalaError",
+    "Calls",
+    "Cost",
+    "DEFAULT_URL",
+    "ENV_URL",
+    "Gateway",
+    "GatewayMismatch",
+    "GatewayStatus",
+    "GatewayUnavailable",
+    "LicenseInactive",
+    "REPORT_HEADER",
+    "REPORT_HEADERS",
+    "REQUEST_ID_HEADER",
+    "Report",
+    "ReportNotFound",
+    "Tokens",
+    "Totals",
+    "__version__",
+]

bivelio_savings_layer-0.1.0/src/bvsala/__main__.py

@@ -0,0 +1,66 @@
+"""``python -m bvsala``: comprobar el gateway y leer un informe desde la terminal.
+
+Códigos de salida: 0 bien, 2 licencia sin servir, 3 gateway ausente o de otra
+versión, 4 informe no encontrado, 1 cualquier otro error.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from typing import List, Optional
+
+from ._errors import BvsalaError, GatewayUnavailable, LicenseInactive, ReportNotFound
+from ._gateway import Gateway
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    p = argparse.ArgumentParser(prog="python -m bvsala", description="Check a local bvsala gateway and read its per-request reports.")
+    p.add_argument("--url", help="gateway URL (default: $BVSALA_GATEWAY_URL or http://127.0.0.1:8402)")
+    sub = p.add_subparsers(dest="cmd", required=True)
+    sub.add_parser("status", help="print the gateway's version, upstream and license")
+    r = sub.add_parser("report", help="print the report of one request as JSON")
+    r.add_argument("id", help="the x-bvsala-request-id header, or the provider's response id")
+    r.add_argument("--wait", type=float, default=0.0, help="seconds to wait for a request still in flight")
+    a = p.parse_args(argv)
+
+    try:
+        gw = Gateway(a.url)
+        if a.cmd == "status":
+            st = gw.status()
+            print(f"bvsala gateway {st.version} at {gw.url}")
+            print(f"  upstream: {st.upstream}")
+            vence = f", expires {st.license_expires_at}" if st.license_expires_at else ""
+            print(f"  license:  {st.license_state} ({st.license_plan or 'unknown plan'}{vence})")
+            print(f"  metering: {'on' if st.metering else 'off (no BIVELIO_SERVICE_KEY)'}")
+            return 0 if st.serving else 2
+        informe = gw.report(a.id, wait=a.wait)
+        print(json.dumps(
+            {
+                "requestId": informe.request_id,
+                "responseId": informe.response_id,
+                "path": informe.path,
+                "status": informe.status,
+                "reason": informe.reason,
+                "report": informe.raw_report,
+            },
+            indent=2,
+        ))
+        return 0
+    except LicenseInactive as e:
+        print(f"license {e.state}: {e}", file=sys.stderr)
+        return 2
+    except GatewayUnavailable as e:
+        print(str(e), file=sys.stderr)
+        return 3
+    except ReportNotFound as e:
+        print(str(e), file=sys.stderr)
+        return 4
+    except (BvsalaError, ValueError) as e:
+        print(str(e), file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())