frutebox-node 0.1.0__py3-none-any.whl

frutebox/economics.py

@@ -0,0 +1,270 @@
+"""The reward engine — "mining, but for LLM inference".
+
+Every settled request splits into four parts:
+
+    base_cost         reimburses the provider's energy + basic maintenance
+    provider_margin   the provider's small guaranteed profit
+    platform_fee      the platform operator's (our) small fee
+    bonus             a DECAYING bootstrap emission, like a Bitcoin block reward
+
+The user only ever pays ``base_cost + provider_margin + platform_fee`` — which
+is cheap and roughly flat. The ``bonus`` is paid to the provider *on top*, out
+of a treasury/emission pool, and it halves every ``halving_epochs`` epochs. So
+early contributors earn a lot, and over time earnings settle toward pure
+cost-plus. That is what lets a company fund more hardware early, then coast on
+sustainable margins later.
+"""
+from __future__ import annotations
+
+import json
+import os
+import time
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Dict, List, Optional
+
+from .config import Config
+from .envvars import env as envvar
+
+#: Seeded per-region rates. Flat hourly values until real tariff data is loaded — see the file
+#: itself for why a plausible-looking invented curve would be worse than an honest flat number.
+_RATES_FILE = Path(envvar("RATES_FILE", str(Path(__file__).resolve().parent.parent / "data" / "electricity_rates.json")))
+
+_RATES_CACHE: Dict[str, dict] = {}
+
+
+def _seed_rates() -> Dict[str, dict]:
+    global _RATES_CACHE
+    if _RATES_CACHE:
+        return _RATES_CACHE
+    try:
+        _RATES_CACHE = (json.loads(_RATES_FILE.read_text()) or {}).get("regions") or {}
+    except Exception:
+        # Never let a missing data file stop settlement — the defaults below are the same
+        # numbers the seed file carries.
+        _RATES_CACHE = {}
+    return _RATES_CACHE
+
+
+#: Used only when the seed file is unreadable AND the region is unknown.
+_DEFAULT_RATE = {"per_gb_eur": 0.01, "per_kwh_by_hour": [0.20] * 24}
+
+
+def rates_for(region: str) -> dict:
+    """Bandwidth + hourly electricity rates for a region.
+
+    Prefers live/admin-edited rates cached from the web app (`gpuprices.region_rates()`), then
+    the seeded file, then a flat default. Falls back region -> "default" so an unrecognised
+    region still prices rather than raising mid-settlement.
+    """
+    key = (region or "default").strip().lower()
+    try:                                     # local import: gpuprices imports config, not us
+        from . import gpuprices
+        live = gpuprices.region_rates() or {}
+    except Exception:
+        live = {}
+    for src in (live, _seed_rates()):
+        row = src.get(key) or src.get("default")
+        if isinstance(row, dict) and row.get("per_kwh_by_hour"):
+            return row
+    return _DEFAULT_RATE
+
+
+@dataclass(frozen=True)
+class JobMeter:
+    """What one served request actually consumed (file 01-D).
+
+    Settlement used to price on `(tokens, cost_per_1k)`, which is not what serving costs
+    anyone: an operator pays for **bandwidth** and **electricity**. Tokens break in both
+    directions — a long cheap generation overpays the node, a short prompt against a huge
+    context underpays it — and no token price can express that electricity costs more at 19:00
+    than at 03:00.
+
+    `executor_class` decides who, if anyone, gets paid:
+      * ``account_node``  a community operator's machine  -> internet + electricity + reward
+      * ``backup_infra``  rented capacity we pay a vendor -> **nothing** here; the vendor bill
+                          is recorded as vendor spend, and the user price is the rented cost
+                          plus the thin rented margin
+      * ``owned``         our own hardware                -> no payout, cost side only
+      * ``local``         the user's own device           -> settlement is never called at all
+    """
+    bytes_in: int
+    bytes_out: int
+    t_dispatch: float
+    t_response: float
+    region: str = "default"
+    executor_class: str = "account_node"
+    #: 0 => not benchmarked; the tier wattage declaration is used instead.
+    node_power_w: float = 0.0
+    tier: str = "B"
+    #: §8A headroom input: what this job would have cost on the cheapest alternative, in EUR.
+    cheapest_alternative_eur: float = 0.0
+    tokens: int = 0
+
+    @property
+    def seconds(self) -> float:
+        # A clock that went backwards must not pay someone for negative time.
+        return max(0.0, float(self.t_response) - float(self.t_dispatch))
+
+
+EXECUTOR_CLASSES = ("account_node", "backup_infra", "owned", "local")
+
+
+class Economics:
+    def __init__(self, cfg: Config, genesis: Optional[float] = None):
+        self.cfg = cfg
+        # genesis is injected (not time.time() in a default arg) so tests /
+        # resumes are deterministic.
+        self.genesis = genesis if genesis is not None else time.time()
+        self.totals: Dict[str, float] = {
+            "user_revenue": 0.0,
+            "provider_payout": 0.0,
+            "platform_fee": 0.0,
+            "bonus_emitted": 0.0,
+            "requests": 0,
+            "tokens": 0,
+        }
+
+    # --- epoch / reward schedule -----------------------------------------
+    def current_epoch(self) -> int:
+        return int((time.time() - self.genesis) // self.cfg.epoch_seconds)
+
+    def seconds_into_epoch(self) -> float:
+        return (time.time() - self.genesis) % self.cfg.epoch_seconds
+
+    def reward_multiplier(self, epoch: Optional[int] = None) -> float:
+        """Bonus multiple of base cost at a given epoch (halving schedule)."""
+        if epoch is None:
+            epoch = self.current_epoch()
+        halvings = epoch // self.cfg.halving_epochs
+        return self.cfg.initial_bonus_rate * (0.5 ** halvings)
+
+    # --- settlement -------------------------------------------------------
+    def _tier_watts(self, tier: str) -> float:
+        return {
+            "C": self.cfg.tier_watts_c, "B": self.cfg.tier_watts_b,
+            "A": self.cfg.tier_watts_a, "S": self.cfg.tier_watts_s,
+        }.get((tier or "B").upper(), self.cfg.tier_watts_b)
+
+    def settle(self, job, cost_per_1k: Optional[float] = None) -> Dict[str, float]:
+        """Price one served request on bytes + time-of-use electricity + headroom reward.
+
+        Accepts a `JobMeter` (the real path). The legacy `(tokens, cost_per_1k)` signature
+        still works as a thin compat shim so callers not yet migrated keep settling instead of
+        crashing — it estimates 4 bytes/token, which is an estimate and is flagged as one on
+        the result (`estimated: True`).
+        """
+        if not isinstance(job, JobMeter):
+            tokens = int(job or 0)
+            rate = self.cfg.default_cost_per_1k if cost_per_1k is None else float(cost_per_1k)
+            # 4 bytes/token is the rough average for UTF-8 English; good enough to keep an
+            # unmigrated caller settling, never good enough to call measured.
+            approx = tokens * 4
+            job = JobMeter(bytes_in=approx // 2, bytes_out=approx - approx // 2,
+                           t_dispatch=0.0, t_response=0.0, tokens=tokens,
+                           cheapest_alternative_eur=(tokens / 1000.0) * rate)
+            return self._settle_meter(job, estimated=True)
+        return self._settle_meter(job, estimated=False)
+
+    def _settle_meter(self, job: JobMeter, *, estimated: bool) -> Dict[str, float]:
+        if job.executor_class == "local":
+            # On-device inference costs the network nothing and pays nobody. Reaching here
+            # means a local job was routed through network settlement, which would invent
+            # both a cost and a payout out of nothing — fail loudly instead.
+            raise ValueError("settle() must never be called for a local (on-device) job")
+        if job.executor_class not in EXECUTOR_CLASSES:
+            raise ValueError(f"unknown executor_class {job.executor_class!r}")
+
+        rates = rates_for(job.region)
+        per_gb = float(rates.get("per_gb_eur", _DEFAULT_RATE["per_gb_eur"]))
+        hourly = rates.get("per_kwh_by_hour") or _DEFAULT_RATE["per_kwh_by_hour"]
+
+        # Internet: what moved on the wire, both directions.
+        internet = (max(0, job.bytes_in) + max(0, job.bytes_out)) * per_gb / 1e9
+
+        # Electricity: seconds held x watts drawn x the tariff AT THE HOUR THE JOB STARTED.
+        hour = 0
+        if job.t_dispatch:
+            hour = datetime.fromtimestamp(job.t_dispatch, tz=timezone.utc).hour
+        per_kwh = float(hourly[hour % len(hourly)])
+        watts = job.node_power_w if job.node_power_w > 0 else self._tier_watts(job.tier)
+        electricity = (job.seconds / 3600.0) * (watts / 1000.0) * per_kwh
+
+        cost = internet + electricity
+        platform = cost * self.cfg.platform_rate
+
+        # Reward = §8A headroom: what we saved versus the cheapest alternative, after the
+        # operator's real costs and our fee. Never negative, and capped so a mispriced
+        # alternative cannot drain the treasury on a single job.
+        headroom = float(job.cheapest_alternative_eur) - cost - platform
+        reward = max(self.cfg.reward_floor_eur, min(max(0.0, headroom), self.cfg.reward_cap_eur))
+
+        if job.executor_class == "account_node":
+            payout = internet + electricity + reward
+        else:
+            # backup_infra: the vendor is paid on their own invoice, recorded as vendor spend.
+            # owned: our own hardware; the cost is ours and there is no counterparty to pay.
+            payout = 0.0
+            reward = 0.0
+
+        user_price = cost + platform + reward
+
+        return {
+            "tokens": job.tokens,
+            "executor_class": job.executor_class,
+            "region": (job.region or "default"),
+            "seconds": round(job.seconds, 4),
+            "watts": round(watts, 2),
+            "power_measured": job.node_power_w > 0,
+            "per_kwh_eur": round(per_kwh, 5),
+            "per_gb_eur": per_gb,
+            "internet_cost": round(internet, 8),
+            "electricity_cost": round(electricity, 8),
+            "base_cost": round(cost, 8),
+            "platform_fee": round(platform, 8),
+            "reward": round(reward, 8),
+            "user_price": round(user_price, 8),
+            "provider_payout": round(payout, 8),
+            "estimated": estimated,
+            "epoch": self.current_epoch(),
+            # Kept so existing dashboards/records that read these keys keep working. The
+            # halving bonus is now expressed through the reward headroom, not a multiple of a
+            # synthetic base cost.
+            "provider_margin": 0.0,
+            "bonus": round(reward, 8),
+            "multiplier": round(self.reward_multiplier(), 4),
+        }
+
+    def record(self, s: Dict[str, float]) -> None:
+        self.totals["user_revenue"] += s["user_price"]
+        self.totals["provider_payout"] += s.get("provider_payout", 0.0)
+        self.totals["platform_fee"] += s["platform_fee"]
+        self.totals["bonus_emitted"] += s.get("bonus", 0.0)
+        self.totals["requests"] += 1
+        self.totals["tokens"] += s.get("tokens", 0)
+
+    # --- dashboard snapshot ----------------------------------------------
+    def curve(self) -> List[Dict[str, float]]:
+        n = self.cfg.halving_epochs * self.cfg.curve_epochs
+        return [
+            {"epoch": e, "multiplier": round(self.reward_multiplier(e), 4)}
+            for e in range(0, n + 1)
+        ]
+
+    def snapshot(self) -> Dict:
+        return {
+            "epoch": self.current_epoch(),
+            "seconds_into_epoch": round(self.seconds_into_epoch(), 1),
+            "epoch_seconds": self.cfg.epoch_seconds,
+            "halving_epochs": self.cfg.halving_epochs,
+            "multiplier": round(self.reward_multiplier(), 4),
+            "rates": {
+                "margin": self.cfg.margin_rate,
+                "platform": self.cfg.platform_rate,
+                "initial_bonus": self.cfg.initial_bonus_rate,
+            },
+            "totals": {k: round(v, 4) if isinstance(v, float) else v
+                       for k, v in self.totals.items()},
+            "curve": self.curve(),
+        }