bioma-framework 1.0.0__py3-none-any.whl

bioma/__init__.py

@@ -0,0 +1,26 @@
+"""
+B.I.O.M.A. — a lean efficiency & resilience micro-kernel for LLM infrastructure.
+
+Two proven primitives, exposed from the Rust kernel (`bioma_micro`) plus a
+resilient OpenRouter abstraction and a drop-in gateway:
+
+  * `kernel.HormonalBus`       — lock-free in-memory signal injection (~2M sig/s, ~5μs)
+  * `kernel.dehydrate` / `kernel.ContextApoptosis` — autonomous context apoptosis
+  * `LeanOpenRouterClient`     — resilient async dispatch with kernel-side apoptosis
+  * `bioma.gateway`            — OpenAI/Anthropic drop-in gateway (`pip install bioma[gateway]`)
+
+The optional integrations (`LeanOpenRouterClient` needs `openai`) are imported
+lazily, so `import bioma` stays light for kernel-only use.
+"""
+import bioma_micro as kernel  # the compiled Rust micro-kernel
+
+__all__ = ["kernel", "LeanOpenRouterClient", "Dispatch"]
+__version__ = "1.0.0"
+
+
+def __getattr__(name: str):
+    # PEP 562 lazy import — pull the openai-backed client only when actually used
+    if name in ("LeanOpenRouterClient", "Dispatch"):
+        from bioma.openrouter_client import Dispatch, LeanOpenRouterClient
+        return {"LeanOpenRouterClient": LeanOpenRouterClient, "Dispatch": Dispatch}[name]
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

bioma/esg.py

@@ -0,0 +1,99 @@
+"""
+`bioma/esg.py` — the official Frugal-AI KPI of the project: **energy per token**.
+
+Converts MEASURED token savings (the kernel's per-dispatch audit) into energy
+(Wh) and emissions (gCO2e) estimates using DECLARED literature coefficients.
+The tokens are ground truth; the conversion is an estimate — every function
+returns (low, mid, high) bounds and never a single unqualified number.
+
+Coefficients (declared, replace with your own measurements when available):
+
+* Datacenter LLM inference energy: **0.5–1.3 kWh per million tokens**
+  (mid 0.9). Range adopted from the public literature — consistent with
+  Epoch AI's ~0.3 Wh per GPT-4o query (~500-token answer) and 2024–2025
+  meta-analyses of production frontier-model inference. Our own CPU-laptop
+  measurement (reports/BIOMA_ENERGY_LOCAL.md: 0.754 Wh / 7,481 tok ≈
+  0.10 kWh/M tok, MARGINAL — idle and PUE excluded, 1B-parameter model,
+  prefill-heavy) sits below that range, as expected for a tiny model
+  measured marginally; the literature range targets production-scale
+  frontier inference. The KPI's reduction % is coefficient-independent.
+* Grid carbon intensity presets (gCO2e/kWh): world ≈ 445 (IEA 2024),
+  EU ≈ 230 (EEA), US ≈ 385 (EPA eGRID), BR ≈ 100 (hydro-heavy, EPE/ONS).
+* Prompt-caching adjustment: cached prefill tokens are not free — they are
+  billed/computed at a fraction of full price. `cache_adjust` shrinks the
+  claimed saving accordingly: saving × ((1−hit) + hit·cache_cost).
+
+Usage:
+    from bioma.esg import estimate_saving, DEFAULTS
+    est = estimate_saving(tokens_saved=45_868)          # one 16-round session
+    est["wh"]      # (low, mid, high) Wh saved
+    est["gco2e"]   # (low, mid, high) gCO2e saved, world grid
+"""
+from __future__ import annotations
+
+from typing import TypedDict
+
+# kWh per MILLION tokens — declared literature range (see module docstring).
+KWH_PER_MTOK = {"low": 0.5, "mid": 0.9, "high": 1.3}
+
+# gCO2e per kWh — grid presets (replace with your grid's factor).
+GRID_GCO2_PER_KWH = {"world": 445.0, "eu": 230.0, "us": 385.0, "br": 100.0}
+
+DEFAULTS = {"grid": "world", "cache_hit": 0.0, "cache_cost": 0.10}
+
+
+class Estimate(TypedDict):
+    tokens_saved: int
+    cache_multiplier: float
+    wh: tuple[float, float, float]
+    gco2e: tuple[float, float, float]
+    grid: str
+    kwh_per_mtok: dict
+
+
+def cache_multiplier(cache_hit: float, cache_cost: float = 0.10) -> float:
+    """Fraction of the nominal saving that survives an honest caching baseline.
+
+    If `cache_hit` of the resent context would have been a cache hit anyway
+    (costing `cache_cost` of a full prefill), the counterfactual baseline is
+    cheaper and the claimable saving shrinks: (1−hit) + hit·cost."""
+    hit = min(max(cache_hit, 0.0), 1.0)
+    cost = min(max(cache_cost, 0.0), 1.0)
+    return (1.0 - hit) + hit * cost
+
+
+def wh_from_tokens(tokens: float) -> tuple[float, float, float]:
+    """Energy (Wh) for `tokens` at the declared low/mid/high coefficients."""
+    return tuple(tokens / 1e6 * KWH_PER_MTOK[k] * 1000.0 for k in ("low", "mid", "high"))  # type: ignore[return-value]
+
+
+def estimate_saving(tokens_saved: int, *, grid: str = "world",
+                    cache_hit: float = 0.0, cache_cost: float = 0.10) -> Estimate:
+    """Convert measured tokens saved into bounded Wh / gCO2e estimates."""
+    if grid not in GRID_GCO2_PER_KWH:
+        raise ValueError(f"unknown grid preset {grid!r}; options: {sorted(GRID_GCO2_PER_KWH)}")
+    mult = cache_multiplier(cache_hit, cache_cost)
+    wh = tuple(v * mult for v in wh_from_tokens(tokens_saved))
+    g = GRID_GCO2_PER_KWH[grid]
+    return Estimate(
+        tokens_saved=tokens_saved,
+        cache_multiplier=round(mult, 4),
+        wh=wh,  # type: ignore[typeddict-item]
+        gco2e=tuple(v / 1000.0 * g for v in wh),  # type: ignore[typeddict-item]
+        grid=grid,
+        kwh_per_mtok=dict(KWH_PER_MTOK),
+    )
+
+
+def kpi_energy_per_token(tokens_before: int, tokens_after: int) -> dict:
+    """The project KPI: energy per dispatch, before vs after apoptosis.
+
+    Returns Wh (low, mid, high) for both sides plus the reduction fraction —
+    which is exact (independent of the coefficient, since it cancels out)."""
+    if tokens_before <= 0:
+        raise ValueError("tokens_before must be positive")
+    return {
+        "wh_before": wh_from_tokens(tokens_before),
+        "wh_after": wh_from_tokens(tokens_after),
+        "reduction": 1.0 - tokens_after / tokens_before,
+    }

bioma/esg_report.py

@@ -0,0 +1,123 @@
+"""
+`bioma/esg_report.py` — the design-partner instrument: turn a deployment's REAL
+gateway audit log into a per-deployment ESG + cost case report.
+
+The gateway writes one JSONL line per request (`tokens_before`, `tokens_after`,
+`reduction`, kernel μs). This reads that ground-truth log and reports, for the
+deployment: tokens avoided, and — via the declared literature coefficients in
+`bioma.esg` — bounded Wh / gCO2e / USD avoided. Every input is measured on the
+partner's own traffic; only the energy conversion is an estimate (with bounds).
+
+A partner runs their real workload through the gateway, then:
+
+    python -m bioma.esg_report bioma_gateway_audit.jsonl --grid eu --price-in 2.0
+
+No third-party data is invented here — the report is empty until a real log exists.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+
+from bioma.esg import GRID_GCO2_PER_KWH, KWH_PER_MTOK, estimate_saving
+
+
+def read_audit(path: str) -> list[dict]:
+    rows = []
+    with open(path, encoding="utf-8") as f:
+        for line in f:
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                rows.append(json.loads(line))
+            except json.JSONDecodeError:
+                continue
+    return rows
+
+
+def build_report(rows: list[dict], *, grid: str = "world",
+                 price_in_per_mtok: float | None = None,
+                 cache_hit: float = 0.0) -> dict:
+    n = len(rows)
+    before = sum(int(r.get("tokens_before", 0)) for r in rows)
+    after = sum(int(r.get("tokens_after", 0)) for r in rows)
+    saved = before - after
+    est = estimate_saving(saved, grid=grid, cache_hit=cache_hit) if saved > 0 else None
+    usd = None
+    if price_in_per_mtok is not None and saved > 0:
+        usd = saved / 1e6 * price_in_per_mtok
+    return {
+        "requests": n,
+        "tokens_before": before, "tokens_after": after, "tokens_saved": saved,
+        "reduction": (1 - after / before) if before else 0.0,
+        "grid": grid,
+        "wh_avoided": est["wh"] if est else (0.0, 0.0, 0.0),
+        "gco2e_avoided": est["gco2e"] if est else (0.0, 0.0, 0.0),
+        "usd_avoided": usd,
+    }
+
+
+def render_md(rep: dict, coeff_note: str) -> str:
+    wl, wm, wh = rep["wh_avoided"]
+    gl, gm, gh = rep["gco2e_avoided"]
+    L = [
+        "# Relatório ESG de deployment — B.I.O.M.A. (dados do seu tráfego real)",
+        "",
+        f"> Gerado de {rep['requests']:,} requests do audit do gateway. Tokens = medidos "
+        "no seu tráfego; Wh/gCO2e = estimativa com coeficientes declarados "
+        f"({coeff_note}); limites baixo/central/alto.",
+        "",
+        "| Métrica | Valor |",
+        "| :--- | ---: |",
+        f"| Requests medidos | {rep['requests']:,} |",
+        f"| Tokens de entrada | {rep['tokens_before']:,} → {rep['tokens_after']:,} |",
+        f"| **Tokens evitados** | **{rep['tokens_saved']:,}** (−{rep['reduction']*100:.1f}%) |",
+        f"| Energia evitada (grid {rep['grid']}) | {wl:,.1f} / **{wm:,.1f}** / {wh:,.1f} Wh |",
+        f"| Emissões evitadas | {gl:,.1f} / **{gm:,.1f}** / {gh:,.1f} gCO2e |",
+    ]
+    if rep["usd_avoided"] is not None:
+        L.append(f"| Custo de entrada evitado | **${rep['usd_avoided']:,.4f}** |")
+    L += ["",
+          "Escopo: redução auditável POR DEPLOYMENT (não global). A energia herda a "
+          "incerteza declarada do coeficiente; substitua pelo fator do seu grid/provedor.",
+          ""]
+    return "\n".join(L)
+
+
+def _main(argv: list[str] | None = None) -> int:
+    try:
+        sys.stdout.reconfigure(encoding="utf-8", errors="replace")
+    except Exception:
+        pass
+    ap = argparse.ArgumentParser(description="ESG deployment report from a gateway audit log.")
+    ap.add_argument("audit", help="path to bioma_gateway_audit.jsonl")
+    ap.add_argument("--grid", default="world", choices=sorted(GRID_GCO2_PER_KWH))
+    ap.add_argument("--price-in", type=float, default=None,
+                    help="input price $/M tokens for your model (optional → $ avoided)")
+    ap.add_argument("--cache-hit", type=float, default=0.0)
+    ap.add_argument("--out", default=None, help="write the markdown report here")
+    args = ap.parse_args(argv)
+    if not os.path.exists(args.audit):
+        print(f"audit log não encontrado: {args.audit} — rode seu tráfego pelo gateway primeiro.")
+        return 2
+    rows = read_audit(args.audit)
+    if not rows:
+        print("audit vazio — nenhum request medido ainda.")
+        return 2
+    rep = build_report(rows, grid=args.grid, price_in_per_mtok=args.price_in,
+                       cache_hit=args.cache_hit)
+    coeff = f"{KWH_PER_MTOK['low']}–{KWH_PER_MTOK['high']} kWh/Mtok, grid {args.grid}"
+    md = render_md(rep, coeff)
+    print(md)
+    if args.out:
+        with open(args.out, "w", encoding="utf-8") as f:
+            f.write(md)
+        print(f"📄 {args.out}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(_main())

bioma/firewall_client.py

@@ -0,0 +1,223 @@
+"""
+`bioma/firewall_client.py` — the Cognitive Firewall: a local, provider-agnostic
+defensive shim you drop in front of ANY LLM call (Anthropic, Google, OpenAI, …).
+
+It is NOT a magic injection blocker. It is a stack of *real, measurable* controls:
+
+  1. **Secret redaction** — vault values are scrubbed from the outbound payload AND
+     the model response. An injection cannot exfiltrate a secret the model never got.
+  2. **Saturation detection + apoptosis** — cognitive-DDoS / floods are detected
+     (`saturation_scan`) → RED ALERT (`0x0F`) → dehydrated by apoptosis before dispatch.
+  3. **Timeout guard** — dispatch is bounded, so a loop/hang cannot stall the pipeline.
+  4. **Exponential backoff** — 429/5xx absorbed (built-in OpenRouter path).
+
+Two ways to use it — 100% local, no hosted service:
+
+    fw = CognitiveFirewall(vault={"db": DB_PW})
+
+    # (a) PURE artifact — harden the payload, then call YOUR provider yourself:
+    h = fw.shield(history, "fix the bug")
+    #   → send h.prompt / h.system to anthropic / google-genai / openai directly
+    #   → h.telemetry has saturation, red_alert, apoptosis reduction, μs latency
+
+    # (b) Bring-your-own dispatcher (any async provider):
+    s = await fw.harden(history, "fix the bug", dispatch_fn=my_anthropic_call)
+
+    # (c) Convenience: built-in OpenRouter dispatch (needs OPENROUTER_API_KEY).
+    s = await fw.harden(history, "fix the bug", model="openai/gpt-4o")
+"""
+from __future__ import annotations
+
+import asyncio
+import os
+import random
+from dataclasses import dataclass
+from typing import Awaitable, Callable, Optional
+
+import bioma_micro as _kernel
+
+RED_ALERT = 0x0F  # invasion bit-flag broadcast on the hormonal bus
+OPENROUTER_BASE_URL = "https://openrouter.ai/api/v1"
+
+_ROLE_SIGNAL = {"system": _kernel.SYSTEM, "user": _kernel.USER, "assistant": _kernel.ASSISTANT,
+                "tool": _kernel.TOOL, "fact": _kernel.FACT}
+
+# A bring-your-own dispatcher: takes the hardened (prompt, system) and returns text.
+Dispatcher = Callable[[str, Optional[str]], Awaitable[str]]
+
+
+@dataclass
+class Hardened:
+    """The pure output of `shield()`: a clean payload ready for ANY provider."""
+    prompt: str                   # dehydrated + redacted user payload
+    system: Optional[str]         # redacted system prompt
+    saturation: float
+    red_alert: bool
+    secrets_redacted: int
+    outbound_clean: bool          # no vault secret survived into the outbound
+    apoptosis_reduction: float
+    tokens_before: int
+    tokens_after: int
+    kernel_latency_us: float
+
+    @property
+    def telemetry(self) -> dict:
+        return {"saturation": self.saturation, "red_alert": self.red_alert,
+                "secrets_redacted": self.secrets_redacted, "outbound_clean": self.outbound_clean,
+                "apoptosis_reduction": self.apoptosis_reduction, "tokens_before": self.tokens_before,
+                "tokens_after": self.tokens_after, "kernel_latency_us": self.kernel_latency_us}
+
+
+@dataclass
+class Shield:
+    """The outcome of one hardened *dispatch* + full defensive telemetry."""
+    answer: str
+    model: str
+    saturation: float
+    red_alert: bool
+    secrets_redacted: int
+    outbound_clean: bool
+    apoptosis_reduction: float
+    tokens_before: int
+    tokens_after: int
+    kernel_latency_us: float
+    dispatched: bool
+    timed_out: bool
+    error: Optional[str] = None
+
+
+class CognitiveFirewall:
+    """Local, provider-agnostic defensive shim. Thread-safe: kernel calls are pure."""
+
+    def __init__(self, api_key: Optional[str] = None, *, vault: Optional[dict] = None,
+                 saturation_threshold: float = 0.85, dispatch_timeout: float = 20.0,
+                 max_retries: int = 5, base_delay: float = 1.0, max_delay: float = 30.0,
+                 half_life: float = 6.0, safe_threshold: float = 0.35,
+                 referer: str = "https://bioma.ai", title: str = "B.I.O.M.A. Cognitive Firewall"):
+        self._vault = dict(vault or {})
+        self._secrets = [str(v) for v in self._vault.values() if v]
+        self.saturation_threshold = saturation_threshold
+        self.dispatch_timeout = dispatch_timeout
+        self.max_retries = max_retries
+        self.base_delay = base_delay
+        self.max_delay = max_delay
+        self.half_life = half_life
+        self.safe_threshold = safe_threshold
+        self._bus = _kernel.HormonalBus(32)
+        key = api_key or os.environ.get("OPENROUTER_API_KEY")
+        self.online = bool(key and key.startswith("sk-or"))
+        if self.online:
+            from openai import AsyncOpenAI
+            self._client = AsyncOpenAI(base_url=OPENROUTER_BASE_URL, api_key=key,
+                                       default_headers={"HTTP-Referer": referer, "X-Title": title})
+        else:
+            self._client = None
+
+    # ----- primitives ------------------------------------------------------ #
+    def _redact(self, text: str) -> tuple[str, int]:
+        hits = 0
+        for sv in self._secrets:
+            if sv and sv in text:
+                hits += text.count(sv)
+                text = text.replace(sv, "[REDACTED]")
+        return text, hits
+
+    def _leaks(self, text: str) -> bool:
+        return any(sv in text for sv in self._secrets if sv)
+
+    def scan(self, text: str) -> float:
+        """Cognitive-DDoS saturation score (0..1)."""
+        return _kernel.saturation_scan(text)
+
+    def alert_level(self) -> float:
+        return self._bus.sense(RED_ALERT)
+
+    # ----- the PURE hardening primitive (provider-agnostic) ---------------- #
+    def shield(self, history: list[dict], query: str, system: Optional[str] = None) -> Hardened:
+        """Harden a payload — scan → RED ALERT → apoptosis → secret redaction — and
+        return the clean prompt/system + telemetry. No network, no provider. Send the
+        result to Anthropic / Google / OpenAI (or anything) yourself."""
+        payload = "\n".join(str(m.get("content", "")) for m in history) + "\n" + query
+        saturation = _kernel.saturation_scan(payload)
+        red = saturation >= self.saturation_threshold
+        if red:
+            self._bus.secrete(RED_ALERT, min(1.0, saturation))
+
+        msgs = [(str(m.get("content", "")), _ROLE_SIGNAL.get(m.get("role", "user"), _kernel.USER))
+                for m in history]
+        audit = _kernel.dehydrate(msgs, half_life=self.half_life, safe_threshold=self.safe_threshold)
+        dehydrated = "\n".join(audit["kept"])
+
+        clean_ctx, h1 = self._redact(dehydrated)
+        clean_query, h2 = self._redact(query)
+        clean_system, h3 = self._redact(system) if system else ("", 0)
+        prompt = f"Context:\n{clean_ctx}\n\nRequest:\n{clean_query}" if clean_ctx else clean_query
+        outbound_clean = not (self._leaks(prompt) or self._leaks(clean_system))
+        return Hardened(prompt=prompt, system=(clean_system or None), saturation=round(saturation, 4),
+                        red_alert=red, secrets_redacted=h1 + h2 + h3, outbound_clean=outbound_clean,
+                        apoptosis_reduction=float(audit["reduction"]), tokens_before=int(audit["tokens_before"]),
+                        tokens_after=int(audit["tokens_after"]), kernel_latency_us=float(audit["kernel_latency_us"]))
+
+    # ----- hardened dispatch (built-in OpenRouter OR your own provider) ---- #
+    async def harden(self, history: list[dict], query: str, *, model: str = "openai/gpt-4o",
+                     system: Optional[str] = None, max_tokens: int = 256,
+                     timeout: Optional[float] = None,
+                     dispatch_fn: Optional[Dispatcher] = None) -> Shield:
+        hp = self.shield(history, query, system)
+        base = dict(saturation=hp.saturation, red_alert=hp.red_alert, secrets_redacted=hp.secrets_redacted,
+                    outbound_clean=hp.outbound_clean, apoptosis_reduction=hp.apoptosis_reduction,
+                    tokens_before=hp.tokens_before, tokens_after=hp.tokens_after,
+                    kernel_latency_us=hp.kernel_latency_us)
+        bound = timeout if timeout is not None else self.dispatch_timeout
+
+        # No dispatcher available → hardening ran, dispatch skipped.
+        if dispatch_fn is None and not self.online:
+            return Shield(answer="", model=model, dispatched=False, timed_out=False,
+                          error="offline (no key, no dispatch_fn) — defenses ran; dispatch skipped", **base)
+
+        try:
+            if dispatch_fn is not None:  # bring-your-own provider (Anthropic/Google/OpenAI)
+                text = await asyncio.wait_for(dispatch_fn(hp.prompt, hp.system), timeout=bound)
+                err = None
+                model = "custom"
+            else:                        # built-in OpenRouter convenience
+                messages = ([{"role": "system", "content": hp.system}] if hp.system else []) + \
+                           [{"role": "user", "content": hp.prompt}]
+                text, err = await asyncio.wait_for(self._dispatch(model, messages, max_tokens), timeout=bound)
+        except asyncio.TimeoutError:
+            return Shield(answer="", model=model, dispatched=False, timed_out=True,
+                          error=f"dispatch exceeded {bound}s — contained by timeout guard", **base)
+
+        safe_answer, resp_hits = self._redact(text or "")
+        base["secrets_redacted"] += resp_hits
+        base["outbound_clean"] = base["outbound_clean"] and not self._leaks(safe_answer)
+        return Shield(answer=safe_answer, model=model, dispatched=(err is None),
+                      timed_out=False, error=err, **base)
+
+    async def _dispatch(self, model: str, messages: list, max_tokens: int) -> tuple[str, Optional[str]]:
+        from openai import (APIConnectionError, APIStatusError, APITimeoutError, RateLimitError)
+        delay, last = self.base_delay, "unknown"
+        for attempt in range(self.max_retries + 1):
+            try:
+                resp = await self._client.chat.completions.create(
+                    model=model, messages=messages, max_tokens=max_tokens,
+                    temperature=0.2, extra_body={"usage": {"include": True}})
+                return resp.choices[0].message.content or "", None
+            except RateLimitError as exc:
+                last = f"429 {exc}"
+            except APIStatusError as exc:
+                code = getattr(exc, "status_code", 0)
+                if 500 <= code < 600:
+                    last = f"{code} {exc}"
+                else:
+                    return "", f"{code}: {exc}"
+            except (APIConnectionError, APITimeoutError) as exc:
+                last = f"conn {exc}"
+            if attempt < self.max_retries:
+                await asyncio.sleep(min(self.max_delay, delay) + random.uniform(0, 0.3 * delay))
+                delay *= 2
+        return "", f"exhausted retries: {last}"
+
+    async def close(self) -> None:
+        if self._client is not None:
+            await self._client.close()