bioma-framework 1.0.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (16) hide show
  1. bioma_framework-1.0.0/.gitignore +27 -0
  2. bioma_framework-1.0.0/LICENSE +114 -0
  3. bioma_framework-1.0.0/PKG-INFO +232 -0
  4. bioma_framework-1.0.0/README.md +187 -0
  5. bioma_framework-1.0.0/README.pt-BR.md +144 -0
  6. bioma_framework-1.0.0/bioma/__init__.py +26 -0
  7. bioma_framework-1.0.0/bioma/esg.py +99 -0
  8. bioma_framework-1.0.0/bioma/esg_report.py +123 -0
  9. bioma_framework-1.0.0/bioma/firewall_client.py +223 -0
  10. bioma_framework-1.0.0/bioma/gateway.py +431 -0
  11. bioma_framework-1.0.0/bioma/openrouter_client.py +159 -0
  12. bioma_framework-1.0.0/bioma/server.py +137 -0
  13. bioma_framework-1.0.0/bioma/vision.py +280 -0
  14. bioma_framework-1.0.0/bioma_micro/LICENSE +114 -0
  15. bioma_framework-1.0.0/bioma_micro/README.md +85 -0
  16. bioma_framework-1.0.0/pyproject.toml +47 -0
bioma_framework-1.0.0/.gitignore ADDED
@@ -0,0 +1,27 @@
1
+ # --- secrets (NEVER commit) ---
2
+ .env
3
+ .env.local
4
+ .env.*.local
5
+
6
+ # --- python ---
7
+ __pycache__/
8
+ *.py[cod]
9
+ *.egg-info/
10
+ .pytest_cache/
11
+ .hypothesis/
12
+ build/
13
+ dist/
14
+
15
+ # --- rust / maturin ---
16
+ target/
17
+ *.whl
18
+
19
+ # --- scratch ---
20
+ *.log
21
+ bioevents.jsonl
22
+ .env.bak
23
+
24
+ # gateway per-request audit log (runtime)
25
+ bioma_gateway_audit.jsonl
26
+ resultados/gateway_dropin_audit.jsonl
27
+ reference_pilot_audit.jsonl
bioma_framework-1.0.0/LICENSE ADDED
@@ -0,0 +1,114 @@
1
+ # Functional Source License, Version 1.1, MIT Future License
2
+
3
+ ## Abbreviation
4
+
5
+ FSL-1.1-MIT
6
+
7
+ ## Notice
8
+
9
+ Copyright 2026 Jonathas Cordeiro
10
+
11
+ ## Terms and Conditions
12
+
13
+ ### Licensor ("We")
14
+
15
+ The party offering the Software under these Terms and Conditions.
16
+
17
+ ### The Software
18
+
19
+ The "Software" is each version of the software that we make available under
20
+ these Terms and Conditions, as indicated by our inclusion of these Terms and
21
+ Conditions with the Software.
22
+
23
+ ### License Grant
24
+
25
+ Subject to your compliance with this License Grant and the Patents,
26
+ Redistribution and Trademark clauses below, we hereby grant you the right to
27
+ use, copy, modify, create derivative works, publicly perform, publicly display
28
+ and redistribute the Software for any Permitted Purpose identified below.
29
+
30
+ ### Permitted Purpose
31
+
32
+ A Permitted Purpose is any purpose other than a Competing Use. A Competing Use
33
+ means making the Software available to others in a commercial product or
34
+ service that:
35
+
36
+ 1. substitutes for the Software;
37
+
38
+ 2. substitutes for any other product or service we offer using the Software
39
+ that exists as of the date we make the Software available; or
40
+
41
+ 3. offers the same or substantially similar functionality as the Software.
42
+
43
+ Permitted Purposes specifically include using the Software:
44
+
45
+ 1. for your internal use and access;
46
+
47
+ 2. for non-commercial education;
48
+
49
+ 3. for non-commercial research; and
50
+
51
+ 4. in connection with professional services that you provide to a licensee
52
+ using the Software in accordance with these Terms and Conditions.
53
+
54
+ ### Patents
55
+
56
+ To the extent your use for a Permitted Purpose would necessarily infringe our
57
+ patents, the license grant above includes a license under our patents. If you
58
+ make a claim against any party that the Software infringes or contributes to
59
+ the infringement of any patent, then your patent license to the Software ends
60
+ immediately.
61
+
62
+ ### Redistribution
63
+
64
+ The Terms and Conditions apply to all copies, modifications and derivatives of
65
+ the Software.
66
+
67
+ If you redistribute any copies, modifications or derivatives of the Software,
68
+ you must include a copy of or a link to these Terms and Conditions and not
69
+ remove any copyright notices provided in or with the Software.
70
+
71
+ ### Disclaimer
72
+
73
+ THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTIES OF ANY KIND, INCLUDING
74
+ BUT NOT LIMITED TO WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
75
+ PURPOSE, TITLE OR NON-INFRINGEMENT.
76
+
77
+ IN NO EVENT WILL WE HAVE ANY LIABILITY TO YOU ARISING OUT OF OR RELATED TO THE
78
+ SOFTWARE, INCLUDING INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES,
79
+ EVEN IF WE HAVE BEEN INFORMED OF THEIR POSSIBILITY IN ADVANCE.
80
+
81
+ ### Trademarks
82
+
83
+ Except for displaying the License Details and identifying us as the origin of
84
+ the Software, you have no right under these Terms and Conditions to use our
85
+ trademarks, trade names, service marks or product names.
86
+
87
+ ## Grant of Future License
88
+
89
+ We hereby irrevocably grant you an additional license to use the Software under
90
+ the MIT License that is effective on the second anniversary of the date we make
91
+ the Software available. On or after that date, you may use the Software under
92
+ the MIT License, in which case the following will apply:
93
+
94
+ MIT License
95
+
96
+ Copyright 2026 Jonathas Cordeiro
97
+
98
+ Permission is hereby granted, free of charge, to any person obtaining a copy of
99
+ this software and associated documentation files (the "Software"), to deal in
100
+ the Software without restriction, including without limitation the rights to
101
+ use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
102
+ of the Software, and to permit persons to whom the Software is furnished to do
103
+ so, subject to the following conditions:
104
+
105
+ The above copyright notice and this permission notice shall be included in all
106
+ copies or substantial portions of the Software.
107
+
108
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
109
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
110
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
111
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
112
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
113
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
114
+ SOFTWARE.
bioma_framework-1.0.0/PKG-INFO ADDED
@@ -0,0 +1,232 @@
1
+ Metadata-Version: 2.4
2
+ Name: bioma-framework
3
+ Version: 1.0.0
4
+ Summary: Client-side Frugal-AI layer: context apoptosis that auditably cuts LLM inference cost per deployment.
5
+ Project-URL: Homepage, https://github.com/jonathascordeiro20/bioma-framework
6
+ Project-URL: Repository, https://github.com/jonathascordeiro20/bioma-framework
7
+ Author: B.I.O.M.A.
8
+ License: LicenseRef-FSL-1.1-MIT
9
+ License-File: LICENSE
10
+ Keywords: context,cost,frugal-ai,gateway,inference,llm,sustainability,tokens
11
+ Classifier: Intended Audience :: Developers
12
+ Classifier: Programming Language :: Python :: 3
13
+ Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
14
+ Requires-Python: >=3.9
15
+ Requires-Dist: bioma-micro>=1.0.0
16
+ Provides-Extra: all
17
+ Requires-Dist: anthropic>=0.40; extra == 'all'
18
+ Requires-Dist: fastapi>=0.110; extra == 'all'
19
+ Requires-Dist: httpx>=0.27; extra == 'all'
20
+ Requires-Dist: imagehash>=4.3; extra == 'all'
21
+ Requires-Dist: numpy>=1.24; extra == 'all'
22
+ Requires-Dist: openai>=1.0; extra == 'all'
23
+ Requires-Dist: opencv-python-headless>=4.9; extra == 'all'
24
+ Requires-Dist: pillow>=10; extra == 'all'
25
+ Requires-Dist: python-dotenv>=1.0; extra == 'all'
26
+ Requires-Dist: rapidocr-onnxruntime>=1.3; extra == 'all'
27
+ Requires-Dist: uvicorn[standard]>=0.29; extra == 'all'
28
+ Provides-Extra: anthropic
29
+ Requires-Dist: anthropic>=0.40; extra == 'anthropic'
30
+ Provides-Extra: client
31
+ Requires-Dist: openai>=1.0; extra == 'client'
32
+ Requires-Dist: python-dotenv>=1.0; extra == 'client'
33
+ Provides-Extra: gateway
34
+ Requires-Dist: fastapi>=0.110; extra == 'gateway'
35
+ Requires-Dist: httpx>=0.27; extra == 'gateway'
36
+ Requires-Dist: python-dotenv>=1.0; extra == 'gateway'
37
+ Requires-Dist: uvicorn[standard]>=0.29; extra == 'gateway'
38
+ Provides-Extra: vision
39
+ Requires-Dist: imagehash>=4.3; extra == 'vision'
40
+ Requires-Dist: numpy>=1.24; extra == 'vision'
41
+ Requires-Dist: opencv-python-headless>=4.9; extra == 'vision'
42
+ Requires-Dist: pillow>=10; extra == 'vision'
43
+ Requires-Dist: rapidocr-onnxruntime>=1.3; extra == 'vision'
44
+ Description-Content-Type: text/markdown
45
+
46
+ # B.I.O.M.A.
47
+
48
+ **🌐 English · [Português](README.pt-BR.md)**
49
+
50
+ [![CI](https://github.com/jonathascordeiro20/bioma-framework/actions/workflows/ci.yml/badge.svg)](https://github.com/jonathascordeiro20/bioma-framework/actions/workflows/ci.yml)
51
+ [![License: FSL-1.1-MIT](https://img.shields.io/badge/license-FSL--1.1--MIT-blue.svg)](LICENSE)
52
+ ![Built with Rust + Python](https://img.shields.io/badge/built%20with-Rust%20%2B%20Python-orange.svg)
53
+ ![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)
54
+ ![Tokens saved: up to 97%](https://img.shields.io/badge/tokens%20saved-up%20to%2097%25-success.svg)
55
+
56
+ **A local, provider-agnostic efficiency & security micro-kernel for LLM applications.**
57
+
58
+ <p align="center">
59
+ <img src="assets/bioma-concept-map.png" width="760"
60
+ alt="B.I.O.M.A. concept map: what it is, its three mechanisms (context apoptosis, cognitive firewall, hormonal bus), what it honestly generates, and why sovereignty depends on where the model runs.">
61
+ </p>
62
+
63
+ B.I.O.M.A. is a drop-in artifact — a lock-free Rust kernel (`bioma_micro`) plus a
64
+ thin Python layer — that you embed in *any* project or architecture that talks to an
65
+ LLM. It does not try to make the model "smarter". It makes the *processing* cheaper,
66
+ faster and safer, in-process, before your prompt ever leaves the machine:
67
+
68
+ - **Context apoptosis** — dehydrates wasted/stale context (−80% input tokens; up to
69
+ −97% on long sessions).
70
+ - **Cognitive firewall** — secret redaction, cognitive-DDoS/flood detection, and a
71
+ dispatch timeout guard.
72
+ - **Hormonal bus** — lock-free μs signalling substrate (~2M signals/s).
73
+
74
+ 100% local. Provider-agnostic: harden the payload here, then send it to **Anthropic,
75
+ Google, OpenAI** — or anything — with *your* SDK.
76
+
77
+ > **New here?** [`OVERVIEW.md`](OVERVIEW.md) explains what B.I.O.M.A. is, the pain it
78
+ > attacks, and the real benchmarks as proof. Step-by-step deployment (local & online
79
+ > providers) is in [`IMPLEMENTATION.md`](IMPLEMENTATION.md). Every claim is measured and
80
+ > audited in [`FINDINGS.md`](FINDINGS.md), including what we tested and **refuted** (multi-LLM
81
+ > "mitosis" does not improve quality — it is not part of the product).
82
+
83
+ ## Use it as a library (any provider)
84
+
85
+ ```python
86
+ from bioma.firewall_client import CognitiveFirewall
87
+
88
+ fw = CognitiveFirewall(vault={"db_password": DB_PW}) # secrets to protect
89
+
90
+ # (a) PURE artifact — harden, then call YOUR provider with YOUR SDK:
91
+ h = fw.shield(history, "refactor this function")
92
+ # h.prompt / h.system → clean, dehydrated, secret-free payload
93
+ # h.telemetry → saturation, red_alert, apoptosis_reduction, kernel_latency_us
94
+
95
+ import anthropic # or google.genai, or openai
96
+ msg = anthropic.Anthropic().messages.create(
97
+ model="claude-sonnet-5", max_tokens=1024,
98
+ system=h.system or "", messages=[{"role": "user", "content": h.prompt}])
99
+
100
+ # (b) Bring your own async dispatcher (Anthropic/Google/OpenAI), keep the guards:
101
+ shield = await fw.harden(history, "refactor", dispatch_fn=my_async_provider_call)
102
+ # → timeout guard + response-side secret redaction applied automatically
103
+ ```
104
+
105
+ The Rust kernel is usable directly too:
106
+
107
+ ```python
108
+ import bioma_micro as k
109
+ k.dehydrate([("system rules", k.SYSTEM), ("verbose log " * 200, k.TOOL)]) # → -80% tokens
110
+ k.saturation_scan(payload) # cognitive-DDoS score 0..1 (flood ≈ 1.0)
111
+ ```
112
+
113
+ ## Proven results (ground truth)
114
+
115
+ | Capability | Result | Source |
116
+ |---|---|---|
117
+ | Context apoptosis | **−80% input tokens** (up to −97% long sessions) | `tests/test_enxuto_efficiency.py` |
118
+ | Answer-quality preservation | **10/10 parity, 100% correct answers at −97% tokens** (5 online models, objective probes) | `tests/test_quality_preservation.py` · `reports/BIOMA_QUALITY_PRESERVATION.md` |
119
+ | Measured energy per dispatch | **2,714.7 J → 69.5 J (−97.4%)**, quality parity (local Llama 3.2 1B, battery fuel gauge, idle subtracted) | `tests/test_energy_local.py` · `reports/BIOMA_ENERGY_LOCAL.md` |
120
+ | Vision context apoptosis (agent screenshot loops) | **6/6 parity, 100% correct at −56% real tokens** (−77% at 24 steps; dehydrated payload is O(1) in session length) — 3 vision models, probes rendered into the pixels | `tests/test_vision_quality_preservation.py` · `reports/BIOMA_VISION_QUALITY.md` |
121
+ | Image distillation (keep-latest dedup + OCR + deterministic shape structure) | **100% answers at −74% tokens vs sending every image** — stale images become ~25–86-token text blocks; local VLM captions measured and rejected (label confabulation) | `tests/test_vision_distill.py` · `reports/BIOMA_VISION_DISTILL.md` |
122
+ | Dev-workload cost benchmark (7 agent models, real OpenRouter usage & prices) | **−57% to −86% median cost at quality parity** — 126 real executions, paired replicas, failures reported first-page (Fable 5×T1 arm-B empty 3/3) | `tests/benchmark_dev_openrouter.py` · `resultados/relatorio.md` · `resultados/SIMULACAO_MERCADO.md` |
123
+ | Drop-in gateway (OpenAI **and Anthropic** surfaces, cache-safe, tool-pair aware) | **−78% (OpenAI) / −33% (Anthropic) billed input tokens, answer intact** with only `base_url` changed — proven with both official SDKs on real models; Claude Code speaks the Anthropic surface | `bioma/gateway.py` · `tests/test_gateway.py` · `tests/prove_gateway_dropin.py` · `tests/prove_anthropic_surface.py` |
124
+ | Apoptosis × prompt caching (real Anthropic cache) | **−65% net cost after the cache discount** — the durable prefix hits the *same* cache in both arms; savings come from purging the never-cacheable middle | `tests/measure_cache_interaction.py` · `resultados/MEDICOES_GATEWAY.md` |
125
+ | Real Claude Code E2E (CLI through the gateway) | **solves real bug+feature tasks, pytest green** with only `ANTHROPIC_BASE_URL` changed; apoptosis is a **safe no-op** here (Claude Code self-manages context — nothing to purge), and the value shows on agents that don't (−84% measured) | `tests/e2e_claude_code.py` · `resultados/E2E_CLAUDE_CODE.md` |
126
+ | E2E real tool-calling agent (fixes a real bug to green pytest) | **−84% accumulated input tokens at task parity** on a long-running agent (−0% on a 3-turn task — apoptosis is a correct no-op with no dead weight) | `tests/e2e_agent_gateway.py` · `resultados/MEDICOES_GATEWAY.md` |
127
+ | Hormonal bus | **~2M signals/s @ ~5μs**, bounded under 10× load | archived bench (research repo) |
128
+ | Cognitive-DDoS mitigation | 15k-token flood → dehydrated pre-dispatch | `tests/test_sovereign_defense.py` |
129
+ | Secret redaction | vault values never reach the model | `reports/BIOMA_IMMUNITY_VERDICT.md` |
130
+ | Pixel secret redaction (closes our own declared gap) | **a real vision model transcribes an AWS/OpenAI key from the original screenshot but only `████` from the redacted one** — OCR + region masking, client-side | `tests/test_vision_secret_redaction.py` · `reports/BIOMA_PIXEL_SECRETS.md` |
131
+
132
+ ## Install
133
+
134
+ ```bash
135
+ pip install bioma # core: the Rust micro-kernel + Python API
136
+ pip install bioma[gateway] # + the drop-in OpenAI/Anthropic gateway
137
+ pip install bioma[all] # + client, anthropic, and the vision tier
138
+ ```
139
+
140
+ The core install ships the compiled Rust kernel (`bioma_micro`) as a binary
141
+ wheel — no Rust toolchain required. Extras (`gateway`, `client`, `anthropic`,
142
+ `vision`) are opt-in so the base stays light. Publishing is one tag away for
143
+ maintainers (`git tag v1.0.0 && git push --tags` → the `Release` workflow builds
144
+ multi-platform wheels and publishes to PyPI). Local dev from source is in
145
+ [Quickstart](#quickstart-local).
146
+
147
+ ## Drop-in gateway — apoptosis with zero code changes
148
+
149
+ Point any OpenAI-compatible **or Anthropic-compatible** client's `base_url` at
150
+ the gateway and every request gets context apoptosis transparently — no SDK
151
+ swap, no prompt rewrite:
152
+
153
+ ```bash
154
+ pip install fastapi "uvicorn[standard]" httpx
155
+ uvicorn bioma.gateway:app --port 8790
156
+ ```
157
+
158
+ ```python
159
+ # OpenAI clients:
160
+ from openai import OpenAI
161
+ client = OpenAI(base_url="http://localhost:8790/v1", api_key="...") # only change
162
+
163
+ # Anthropic clients (incl. Claude Code — set ANTHROPIC_BASE_URL):
164
+ from anthropic import Anthropic
165
+ client = Anthropic(base_url="http://localhost:8790", api_key="...") # only change
166
+ ```
167
+
168
+ Both surfaces proven with the official SDKs on real models:
169
+ - **OpenAI** (`tests/prove_gateway_dropin.py`): billed input **−78%** on Sonnet 5
170
+ / GLM-5.2 / Gemini 3.5 Flash, answer intact, streaming works.
171
+ - **Anthropic `/v1/messages`** (`tests/prove_anthropic_surface.py`): billed input
172
+ **−33%** on Sonnet 5 / Opus 4.8, answer intact, streaming works — the protocol
173
+ Claude Code speaks, so `ANTHROPIC_BASE_URL` → the gateway just works.
174
+
175
+ Design guarantees (each unit-tested in `tests/test_gateway.py`, 14 tests): the
176
+ current query is never filtered; the surviving `system`+`FACT` prefix stays
177
+ **byte-identical** across calls (prompt-cache-safe); tool-call/tool-result pairs
178
+ survive or purge as a unit (never orphaned) — on both the OpenAI `tool` role and
179
+ the Anthropic `tool_use`/`tool_result` block structure. Anthropic `system` is a
180
+ top-level field, forwarded untouched (never purged).
181
+
182
+ ## Frugal AI — the official KPI: energy per token
183
+
184
+ B.I.O.M.A. is a **client-side Frugal AI layer that auditably reduces the energy
185
+ cost of LLM inference per deployment**. The kernel's per-dispatch audit
186
+ (tokens before/after) *is* the KPI: the reduction percentage is exact and
187
+ coefficient-independent. A reproducible benchmark (`tests/test_esg_benchmark.py`
188
+ → `reports/BIOMA_ESG_BENCHMARK.md`) converts the measured token savings into
189
+ bounded Wh/gCO2e estimates using declared literature coefficients
190
+ (0.5–1.3 kWh/M tokens; grid presets; caching-adjusted counterfactual), with the
191
+ conversion helpers shipped in `bioma/esg.py`. This is a per-deployment claim —
192
+ not a global one; it scales with adoption and with your grid.
193
+
194
+ Turn your own real traffic into a case report: run your workload through the
195
+ gateway, then `python -m bioma.esg_report bioma_gateway_audit.jsonl --grid eu
196
+ --price-in <your $/M>` prints tokens / Wh / gCO2e / $ avoided from the measured
197
+ audit log — the design-partner instrument (`bioma/esg_report.py`). A ready-to-run
198
+ NVIDIA-GPU energy harness (`tests/measure_energy_gpu.py`) awaits datacenter
199
+ hardware; it fabricates no numbers without a GPU.
200
+
201
+ ## Quickstart (local)
202
+
203
+ ```bash
204
+ # Build & install the Rust micro-kernel (PyO3 extension)
205
+ python -m pip install maturin
206
+ cd bioma_micro && maturin build --release && \
207
+ pip install --force-reinstall target/wheels/bioma_micro-*.whl && cd ..
208
+
209
+ # Run the test suite (offline, deterministic)
210
+ pip install pytest fastapi "openai>=1"
211
+ python -m pytest tests/test_kernel.py tests/test_firewall.py tests/test_server.py -q
212
+ ```
213
+
214
+ Optional: a local FastAPI runner (`bioma.server`, `GET /health` + `POST /v1/dispatch`)
215
+ and a local container image (`deploy/Dockerfile.lean`) are included — no hosted
216
+ service required.
217
+
218
+ ## Layout
219
+
220
+ ```
221
+ bioma_micro/ Rust/PyO3 micro-kernel — hormonal bus + apoptosis + saturation_scan
222
+ bioma/ Python: CognitiveFirewall, LeanOpenRouterClient, local server
223
+ tests/ unit suite (kernel, firewall, server) + real end-to-end validations
224
+ FINDINGS.md ground-truth evaluation (proven / refuted), reproducible
225
+ reports/ immunity verdict (APT war-game)
226
+ ```
227
+
228
+ ## License
229
+
230
+ Fair-source under the **Functional Source License (FSL-1.1-MIT)** ([`LICENSE`](LICENSE)):
231
+ read it, run it, and build on it for any non-competing purpose. The only limit is repackaging
232
+ it as a competing product, and each release automatically becomes MIT two years after its date.
bioma_framework-1.0.0/README.md ADDED
@@ -0,0 +1,187 @@
1
+ # B.I.O.M.A.
2
+
3
+ **🌐 English · [Português](README.pt-BR.md)**
4
+
5
+ [![CI](https://github.com/jonathascordeiro20/bioma-framework/actions/workflows/ci.yml/badge.svg)](https://github.com/jonathascordeiro20/bioma-framework/actions/workflows/ci.yml)
6
+ [![License: FSL-1.1-MIT](https://img.shields.io/badge/license-FSL--1.1--MIT-blue.svg)](LICENSE)
7
+ ![Built with Rust + Python](https://img.shields.io/badge/built%20with-Rust%20%2B%20Python-orange.svg)
8
+ ![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)
9
+ ![Tokens saved: up to 97%](https://img.shields.io/badge/tokens%20saved-up%20to%2097%25-success.svg)
10
+
11
+ **A local, provider-agnostic efficiency & security micro-kernel for LLM applications.**
12
+
13
+ <p align="center">
14
+ <img src="assets/bioma-concept-map.png" width="760"
15
+ alt="B.I.O.M.A. concept map: what it is, its three mechanisms (context apoptosis, cognitive firewall, hormonal bus), what it honestly generates, and why sovereignty depends on where the model runs.">
16
+ </p>
17
+
18
+ B.I.O.M.A. is a drop-in artifact — a lock-free Rust kernel (`bioma_micro`) plus a
19
+ thin Python layer — that you embed in *any* project or architecture that talks to an
20
+ LLM. It does not try to make the model "smarter". It makes the *processing* cheaper,
21
+ faster and safer, in-process, before your prompt ever leaves the machine:
22
+
23
+ - **Context apoptosis** — dehydrates wasted/stale context (−80% input tokens; up to
24
+ −97% on long sessions).
25
+ - **Cognitive firewall** — secret redaction, cognitive-DDoS/flood detection, and a
26
+ dispatch timeout guard.
27
+ - **Hormonal bus** — lock-free μs signalling substrate (~2M signals/s).
28
+
29
+ 100% local. Provider-agnostic: harden the payload here, then send it to **Anthropic,
30
+ Google, OpenAI** — or anything — with *your* SDK.
31
+
32
+ > **New here?** [`OVERVIEW.md`](OVERVIEW.md) explains what B.I.O.M.A. is, the pain it
33
+ > attacks, and the real benchmarks as proof. Step-by-step deployment (local & online
34
+ > providers) is in [`IMPLEMENTATION.md`](IMPLEMENTATION.md). Every claim is measured and
35
+ > audited in [`FINDINGS.md`](FINDINGS.md), including what we tested and **refuted** (multi-LLM
36
+ > "mitosis" does not improve quality — it is not part of the product).
37
+
38
+ ## Use it as a library (any provider)
39
+
40
+ ```python
41
+ from bioma.firewall_client import CognitiveFirewall
42
+
43
+ fw = CognitiveFirewall(vault={"db_password": DB_PW}) # secrets to protect
44
+
45
+ # (a) PURE artifact — harden, then call YOUR provider with YOUR SDK:
46
+ h = fw.shield(history, "refactor this function")
47
+ # h.prompt / h.system → clean, dehydrated, secret-free payload
48
+ # h.telemetry → saturation, red_alert, apoptosis_reduction, kernel_latency_us
49
+
50
+ import anthropic # or google.genai, or openai
51
+ msg = anthropic.Anthropic().messages.create(
52
+ model="claude-sonnet-5", max_tokens=1024,
53
+ system=h.system or "", messages=[{"role": "user", "content": h.prompt}])
54
+
55
+ # (b) Bring your own async dispatcher (Anthropic/Google/OpenAI), keep the guards:
56
+ shield = await fw.harden(history, "refactor", dispatch_fn=my_async_provider_call)
57
+ # → timeout guard + response-side secret redaction applied automatically
58
+ ```
59
+
60
+ The Rust kernel is usable directly too:
61
+
62
+ ```python
63
+ import bioma_micro as k
64
+ k.dehydrate([("system rules", k.SYSTEM), ("verbose log " * 200, k.TOOL)]) # → -80% tokens
65
+ k.saturation_scan(payload) # cognitive-DDoS score 0..1 (flood ≈ 1.0)
66
+ ```
67
+
68
+ ## Proven results (ground truth)
69
+
70
+ | Capability | Result | Source |
71
+ |---|---|---|
72
+ | Context apoptosis | **−80% input tokens** (up to −97% long sessions) | `tests/test_enxuto_efficiency.py` |
73
+ | Answer-quality preservation | **10/10 parity, 100% correct answers at −97% tokens** (5 online models, objective probes) | `tests/test_quality_preservation.py` · `reports/BIOMA_QUALITY_PRESERVATION.md` |
74
+ | Measured energy per dispatch | **2,714.7 J → 69.5 J (−97.4%)**, quality parity (local Llama 3.2 1B, battery fuel gauge, idle subtracted) | `tests/test_energy_local.py` · `reports/BIOMA_ENERGY_LOCAL.md` |
75
+ | Vision context apoptosis (agent screenshot loops) | **6/6 parity, 100% correct at −56% real tokens** (−77% at 24 steps; dehydrated payload is O(1) in session length) — 3 vision models, probes rendered into the pixels | `tests/test_vision_quality_preservation.py` · `reports/BIOMA_VISION_QUALITY.md` |
76
+ | Image distillation (keep-latest dedup + OCR + deterministic shape structure) | **100% answers at −74% tokens vs sending every image** — stale images become ~25–86-token text blocks; local VLM captions measured and rejected (label confabulation) | `tests/test_vision_distill.py` · `reports/BIOMA_VISION_DISTILL.md` |
77
+ | Dev-workload cost benchmark (7 agent models, real OpenRouter usage & prices) | **−57% to −86% median cost at quality parity** — 126 real executions, paired replicas, failures reported first-page (Fable 5×T1 arm-B empty 3/3) | `tests/benchmark_dev_openrouter.py` · `resultados/relatorio.md` · `resultados/SIMULACAO_MERCADO.md` |
78
+ | Drop-in gateway (OpenAI **and Anthropic** surfaces, cache-safe, tool-pair aware) | **−78% (OpenAI) / −33% (Anthropic) billed input tokens, answer intact** with only `base_url` changed — proven with both official SDKs on real models; Claude Code speaks the Anthropic surface | `bioma/gateway.py` · `tests/test_gateway.py` · `tests/prove_gateway_dropin.py` · `tests/prove_anthropic_surface.py` |
79
+ | Apoptosis × prompt caching (real Anthropic cache) | **−65% net cost after the cache discount** — the durable prefix hits the *same* cache in both arms; savings come from purging the never-cacheable middle | `tests/measure_cache_interaction.py` · `resultados/MEDICOES_GATEWAY.md` |
80
+ | Real Claude Code E2E (CLI through the gateway) | **solves real bug+feature tasks, pytest green** with only `ANTHROPIC_BASE_URL` changed; apoptosis is a **safe no-op** here (Claude Code self-manages context — nothing to purge), and the value shows on agents that don't (−84% measured) | `tests/e2e_claude_code.py` · `resultados/E2E_CLAUDE_CODE.md` |
81
+ | E2E real tool-calling agent (fixes a real bug to green pytest) | **−84% accumulated input tokens at task parity** on a long-running agent (−0% on a 3-turn task — apoptosis is a correct no-op with no dead weight) | `tests/e2e_agent_gateway.py` · `resultados/MEDICOES_GATEWAY.md` |
82
+ | Hormonal bus | **~2M signals/s @ ~5μs**, bounded under 10× load | archived bench (research repo) |
83
+ | Cognitive-DDoS mitigation | 15k-token flood → dehydrated pre-dispatch | `tests/test_sovereign_defense.py` |
84
+ | Secret redaction | vault values never reach the model | `reports/BIOMA_IMMUNITY_VERDICT.md` |
85
+ | Pixel secret redaction (closes our own declared gap) | **a real vision model transcribes an AWS/OpenAI key from the original screenshot but only `████` from the redacted one** — OCR + region masking, client-side | `tests/test_vision_secret_redaction.py` · `reports/BIOMA_PIXEL_SECRETS.md` |
86
+
87
+ ## Install
88
+
89
+ ```bash
90
+ pip install bioma # core: the Rust micro-kernel + Python API
91
+ pip install bioma[gateway] # + the drop-in OpenAI/Anthropic gateway
92
+ pip install bioma[all] # + client, anthropic, and the vision tier
93
+ ```
94
+
95
+ The core install ships the compiled Rust kernel (`bioma_micro`) as a binary
96
+ wheel — no Rust toolchain required. Extras (`gateway`, `client`, `anthropic`,
97
+ `vision`) are opt-in so the base stays light. Publishing is one tag away for
98
+ maintainers (`git tag v1.0.0 && git push --tags` → the `Release` workflow builds
99
+ multi-platform wheels and publishes to PyPI). Local dev from source is in
100
+ [Quickstart](#quickstart-local).
101
+
102
+ ## Drop-in gateway — apoptosis with zero code changes
103
+
104
+ Point any OpenAI-compatible **or Anthropic-compatible** client's `base_url` at
105
+ the gateway and every request gets context apoptosis transparently — no SDK
106
+ swap, no prompt rewrite:
107
+
108
+ ```bash
109
+ pip install fastapi "uvicorn[standard]" httpx
110
+ uvicorn bioma.gateway:app --port 8790
111
+ ```
112
+
113
+ ```python
114
+ # OpenAI clients:
115
+ from openai import OpenAI
116
+ client = OpenAI(base_url="http://localhost:8790/v1", api_key="...") # only change
117
+
118
+ # Anthropic clients (incl. Claude Code — set ANTHROPIC_BASE_URL):
119
+ from anthropic import Anthropic
120
+ client = Anthropic(base_url="http://localhost:8790", api_key="...") # only change
121
+ ```
122
+
123
+ Both surfaces proven with the official SDKs on real models:
124
+ - **OpenAI** (`tests/prove_gateway_dropin.py`): billed input **−78%** on Sonnet 5
125
+ / GLM-5.2 / Gemini 3.5 Flash, answer intact, streaming works.
126
+ - **Anthropic `/v1/messages`** (`tests/prove_anthropic_surface.py`): billed input
127
+ **−33%** on Sonnet 5 / Opus 4.8, answer intact, streaming works — the protocol
128
+ Claude Code speaks, so `ANTHROPIC_BASE_URL` → the gateway just works.
129
+
130
+ Design guarantees (each unit-tested in `tests/test_gateway.py`, 14 tests): the
131
+ current query is never filtered; the surviving `system`+`FACT` prefix stays
132
+ **byte-identical** across calls (prompt-cache-safe); tool-call/tool-result pairs
133
+ survive or purge as a unit (never orphaned) — on both the OpenAI `tool` role and
134
+ the Anthropic `tool_use`/`tool_result` block structure. Anthropic `system` is a
135
+ top-level field, forwarded untouched (never purged).
136
+
137
+ ## Frugal AI — the official KPI: energy per token
138
+
139
+ B.I.O.M.A. is a **client-side Frugal AI layer that auditably reduces the energy
140
+ cost of LLM inference per deployment**. The kernel's per-dispatch audit
141
+ (tokens before/after) *is* the KPI: the reduction percentage is exact and
142
+ coefficient-independent. A reproducible benchmark (`tests/test_esg_benchmark.py`
143
+ → `reports/BIOMA_ESG_BENCHMARK.md`) converts the measured token savings into
144
+ bounded Wh/gCO2e estimates using declared literature coefficients
145
+ (0.5–1.3 kWh/M tokens; grid presets; caching-adjusted counterfactual), with the
146
+ conversion helpers shipped in `bioma/esg.py`. This is a per-deployment claim —
147
+ not a global one; it scales with adoption and with your grid.
148
+
149
+ Turn your own real traffic into a case report: run your workload through the
150
+ gateway, then `python -m bioma.esg_report bioma_gateway_audit.jsonl --grid eu
151
+ --price-in <your $/M>` prints tokens / Wh / gCO2e / $ avoided from the measured
152
+ audit log — the design-partner instrument (`bioma/esg_report.py`). A ready-to-run
153
+ NVIDIA-GPU energy harness (`tests/measure_energy_gpu.py`) awaits datacenter
154
+ hardware; it fabricates no numbers without a GPU.
155
+
156
+ ## Quickstart (local)
157
+
158
+ ```bash
159
+ # Build & install the Rust micro-kernel (PyO3 extension)
160
+ python -m pip install maturin
161
+ cd bioma_micro && maturin build --release && \
162
+ pip install --force-reinstall target/wheels/bioma_micro-*.whl && cd ..
163
+
164
+ # Run the test suite (offline, deterministic)
165
+ pip install pytest fastapi "openai>=1"
166
+ python -m pytest tests/test_kernel.py tests/test_firewall.py tests/test_server.py -q
167
+ ```
168
+
169
+ Optional: a local FastAPI runner (`bioma.server`, `GET /health` + `POST /v1/dispatch`)
170
+ and a local container image (`deploy/Dockerfile.lean`) are included — no hosted
171
+ service required.
172
+
173
+ ## Layout
174
+
175
+ ```
176
+ bioma_micro/ Rust/PyO3 micro-kernel — hormonal bus + apoptosis + saturation_scan
177
+ bioma/ Python: CognitiveFirewall, LeanOpenRouterClient, local server
178
+ tests/ unit suite (kernel, firewall, server) + real end-to-end validations
179
+ FINDINGS.md ground-truth evaluation (proven / refuted), reproducible
180
+ reports/ immunity verdict (APT war-game)
181
+ ```
182
+
183
+ ## License
184
+
185
+ Fair-source under the **Functional Source License (FSL-1.1-MIT)** ([`LICENSE`](LICENSE)):
186
+ read it, run it, and build on it for any non-competing purpose. The only limit is repackaging
187
+ it as a competing product, and each release automatically becomes MIT two years after its date.