Add telemetry beacon, fix Starlette 0.41+ crash, bump to 0.5.4

- Add anonymous telemetry beacon: proxy sends aggregate-only stats
(tokens saved, compression ratios, cache hit rates) to Supabase
every 5 minutes. No prompts, no content, no PII. Opt out with
--no-telemetry or HEADROOM_TELEMETRY=off.

- Fix Starlette 0.41+ TypeError: migrate from deprecated on_event
decorators to lifespan context manager. Fixes crash with
"Router.__init__() got an unexpected keyword argument 'on_startup'".

- Bump version to 0.5.4.

headroom/__init__.py

@@ -153,7 +153,7 @@ from .transforms import (
     TransformPipeline,
 )
 
-__version__ = "0.5.2"
+__version__ = "0.5.4"
 
 __all__ = [
     # Main client

headroom/cli/proxy.py

@@ -133,6 +133,11 @@ from .main import main
     default=None,
     help="AWS profile name for Bedrock (default: use default credentials)",
 )
+@click.option(
+    "--no-telemetry",
+    is_flag=True,
+    help="Disable anonymous usage telemetry (env: HEADROOM_TELEMETRY=off)",
+)
 @click.pass_context
 def proxy(
     ctx: click.Context,
@@ -166,6 +171,7 @@ def proxy(
     region: str,
     bedrock_region: str | None,
     bedrock_profile: str | None,
+    no_telemetry: bool,
 ) -> None:
     """Start the optimization proxy server.
 
@@ -199,7 +205,11 @@ def proxy(
     effective_anyllm_provider = os.environ.get("HEADROOM_ANYLLM_PROVIDER") or anyllm_provider
 
     # Resolve mode: CLI flag > env var > default
-    effective_mode = mode or os.environ.get("HEADROOM_MODE", "token_headroom")
+    effective_mode: str = mode or os.environ.get("HEADROOM_MODE") or "token_headroom"
+
+    # Telemetry opt-out: --no-telemetry flag sets the env var
+    if no_telemetry:
+        os.environ["HEADROOM_TELEMETRY"] = "off"
 
     # License key for managed/enterprise deployments (optional)
     license_key = os.environ.get("HEADROOM_LICENSE_KEY")

headroom/proxy/server.py

@@ -6867,45 +6867,58 @@ def create_app(config: ProxyConfig | None = None) -> FastAPI:
     if not FASTAPI_AVAILABLE:
         raise ImportError("FastAPI required. Install: pip install fastapi uvicorn httpx")
 
+    from contextlib import asynccontextmanager
+
     config = config or ProxyConfig()
 
-    app = FastAPI(
-        title="Headroom Proxy",
-        description="Production-ready LLM optimization proxy",
-        version=__version__,
-    )
+    proxy = HeadroomProxy(config)
 
-    # CORS
-    app.add_middleware(
-        CORSMiddleware,
-        allow_origins=["*"],
-        allow_credentials=True,
-        allow_methods=["*"],
-        allow_headers=["*"],
-    )
+    # Telemetry beacon (anonymous aggregate stats)
+    from headroom.telemetry.beacon import TelemetryBeacon
 
-    proxy = HeadroomProxy(config)
+    _beacon = TelemetryBeacon(
+        port=config.port if hasattr(config, "port") else 8787,
+        sdk="proxy",
+        backend=config.backend if hasattr(config, "backend") else "anthropic",
+    )
 
-    @app.on_event("startup")
-    async def startup():
+    @asynccontextmanager
+    async def lifespan(app: FastAPI):  # type: ignore[no-untyped-def]
+        # Startup
         await proxy.startup()
-        # Start background task for periodic TOIN stats logging
         asyncio.create_task(_log_toin_stats_periodically())
-        # Start usage reporter (license validation + phone-home)
         if proxy.usage_reporter:
             await proxy.usage_reporter.start(proxy)
-        # Start traffic learner background save worker
         if proxy.traffic_learner:
             await proxy.traffic_learner.start()
+        await _beacon.start()
 
-    @app.on_event("shutdown")
-    async def shutdown():
+        yield
+
+        # Shutdown
+        await _beacon.stop()
         if proxy.usage_reporter:
             await proxy.usage_reporter.stop()
         if proxy.traffic_learner:
             await proxy.traffic_learner.stop()
         await proxy.shutdown()
 
+    app = FastAPI(
+        title="Headroom Proxy",
+        description="Production-ready LLM optimization proxy",
+        version=__version__,
+        lifespan=lifespan,
+    )
+
+    # CORS
+    app.add_middleware(
+        CORSMiddleware,
+        allow_origins=["*"],
+        allow_credentials=True,
+        allow_methods=["*"],
+        allow_headers=["*"],
+    )
+
     # Health & Metrics
     @app.get("/health")
     async def health():

headroom/telemetry/beacon.py

@@ -0,0 +1,138 @@
+"""Anonymous usage telemetry beacon for Headroom.
+
+Sends aggregate-only stats (tokens saved, compression ratios, cache hit rates)
+to help improve Headroom. No prompts, no content, no PII.
+
+On by default. Opt out with:
+    HEADROOM_TELEMETRY=off headroom proxy
+    headroom proxy --no-telemetry
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import os
+import platform
+import sys
+import time
+
+logger = logging.getLogger(__name__)
+
+# Supabase endpoint (write-only: anon key can INSERT, not read/update/delete)
+_SUPABASE_URL = "https://dtlllcsudcoasebbamcq.supabase.co"
+_SUPABASE_KEY = "sb_publishable_kHcSIX2Ip0_m0C3WuwZlaQ_33my7qya"
+_TABLE = "proxy_telemetry"
+_ENDPOINT = f"{_SUPABASE_URL}/rest/v1/{_TABLE}"
+
+# Report every 5 minutes
+_INTERVAL_SECONDS = 300
+
+
+def is_telemetry_enabled() -> bool:
+    """Check if telemetry is enabled (on by default, opt out with env var)."""
+    val = os.environ.get("HEADROOM_TELEMETRY", "on").lower().strip()
+    return val not in ("off", "false", "0", "no", "disable", "disabled")
+
+
+class TelemetryBeacon:
+    """Periodically sends anonymous aggregate stats to Supabase."""
+
+    def __init__(self, port: int = 8787, sdk: str = "proxy", backend: str = "anthropic") -> None:
+        self._port = port
+        self._sdk = sdk
+        self._backend = backend
+        self._task: asyncio.Task[None] | None = None
+        self._start_time = time.time()
+
+    async def start(self) -> None:
+        """Start the periodic beacon. Call from proxy startup."""
+        if not is_telemetry_enabled():
+            logger.debug("Telemetry disabled (HEADROOM_TELEMETRY=off)")
+            return
+        self._task = asyncio.create_task(self._loop())
+        logger.info(
+            "Telemetry: ENABLED (anonymous aggregate stats, opt out: HEADROOM_TELEMETRY=off)"
+        )
+
+    async def stop(self) -> None:
+        """Stop and send one final report. Call from proxy shutdown."""
+        if self._task:
+            self._task.cancel()
+            self._task = None
+        # Final report
+        if is_telemetry_enabled():
+            await self._report()
+
+    async def _loop(self) -> None:
+        """Background loop: wait, report, repeat."""
+        # Wait 60 seconds before first report
+        await asyncio.sleep(60)
+        while True:
+            try:
+                await self._report()
+            except Exception:
+                pass  # Never crash the proxy for telemetry
+            await asyncio.sleep(_INTERVAL_SECONDS)
+
+    async def _report(self) -> None:
+        """Fetch stats from local /stats endpoint and POST to Supabase."""
+        try:
+            import httpx
+        except ImportError:
+            return
+
+        # Fetch stats from our own proxy
+        try:
+            async with httpx.AsyncClient(timeout=5.0) as client:
+                resp = await client.get(f"http://127.0.0.1:{self._port}/stats")
+                if resp.status_code != 200:
+                    return
+                stats = resp.json()
+        except Exception:
+            return
+
+        tokens = stats.get("tokens", {})
+        requests = stats.get("requests", {})
+        cache = stats.get("prefix_cache", {}).get("totals", {})
+        cost = stats.get("cost", {})
+        models_by = requests.get("by_model", {})
+        models = [m for m in models_by.keys() if not m.startswith("passthrough:")]
+
+        session_minutes = max(1, int((time.time() - self._start_time) / 60))
+
+        try:
+            from headroom import __version__ as headroom_version
+        except Exception:
+            headroom_version = "unknown"
+
+        payload = {
+            "headroom_version": headroom_version,
+            "python_version": f"{sys.version_info.major}.{sys.version_info.minor}.{sys.version_info.micro}",
+            "os": f"{platform.system()} {platform.machine()}",
+            "sdk": self._sdk,
+            "backend": self._backend,
+            "tokens_saved": tokens.get("saved", 0),
+            "requests": requests.get("total", 0),
+            "compression_percent": tokens.get("savings_percent", 0),
+            "cache_hit_rate": cache.get("hit_rate", 0),
+            "cost_saved_usd": cost.get("savings_usd", 0),
+            "cache_saved_usd": cache.get("cache_savings_usd", 0),
+            "session_minutes": session_minutes,
+            "models_used": models,
+        }
+
+        try:
+            async with httpx.AsyncClient(timeout=10.0) as client:
+                await client.post(
+                    _ENDPOINT,
+                    json=payload,
+                    headers={
+                        "apikey": _SUPABASE_KEY,
+                        "Authorization": f"Bearer {_SUPABASE_KEY}",
+                        "Content-Type": "application/json",
+                        "Prefer": "return=minimal",
+                    },
+                )
+        except Exception:
+            pass  # Fire and forget

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "headroom-ai"
-version = "0.5.3"
+version = "0.5.4"
 description = "The Context Optimization Layer for LLM Applications - Cut costs by 50-90%"
 readme = "README.md"
 license = "Apache-2.0"