superlocalmemory 3.5.7 → 3.6.0

package/src/superlocalmemory/optimize/metrics/estimator.py

@@ -0,0 +1,90 @@
+# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
+# Licensed under AGPL-3.0-or-later - see LICENSE file
+# Part of SuperLocalMemory V3 | https://qualixar.com | https://varunpratap.com
+#
+# ATTRIBUTION: PricingRegistry + stale-detection pattern adapted from:
+#   headroom/pricing/registry.py (Apache-2.0)
+
+"""Savings estimator — converts MetricsSnapshot to dollar/rupee savings."""
+
+from __future__ import annotations
+
+import logging
+from datetime import date, timedelta
+from typing import Any
+
+from superlocalmemory.optimize.storage.db import MetricsSnapshot
+
+logger = logging.getLogger("superlocalmemory.optimize.metrics.estimator")
+
+# DATED: 2026-06-07 — prices verified from official pages on this date.
+BUILTIN_PRICING_TABLE: dict[str, dict[str, float]] = {
+    "anthropic": {"input_per_1m_usd": 3.00, "output_per_1m_usd": 15.00},
+    "openai":    {"input_per_1m_usd": 2.50, "output_per_1m_usd": 10.00},
+    "gemini":    {"input_per_1m_usd": 1.25, "output_per_1m_usd": 10.00},
+}
+
+_PRICING_STALE_DAYS: int = 90
+
+
+class SavingsEstimator:
+    """Converts MetricsSnapshot to dollar/rupee savings. Daemon-scoped singleton.
+
+    Pricing (June 2026 — dated defaults, user-configurable):
+        anthropic: $3.00/M input tokens
+        openai:    $2.50/M input tokens
+        gemini:    $1.25/M input tokens
+
+    CRITICAL pricing rule (INTERFACE-CONTRACT §7):
+        Cache SKIP saves BOTH input+output tokens (whole call avoided).
+        Compression saves INPUT tokens ONLY (output tokens not compressed).
+        NEVER apply output-token pricing to compression savings.
+
+    INR conversion: 83.5 (hardcoded, configurable).
+    Stale detection: if pricing data is > 90 days old → include is_stale=True in output.
+    """
+
+    INR_RATE: float = 83.5
+    _PRICING_DATE: str = "2026-06-07"
+
+    def estimate(self, snap: MetricsSnapshot, provider: str = "anthropic") -> dict[str, Any]:
+        """Compute savings from a MetricsSnapshot.
+
+        Returns:
+            dict with keys: usd, inr, tokens_saved_total, cache_tokens,
+            compress_tokens, is_stale, pricing_date
+        """
+        provider_key = provider if provider in BUILTIN_PRICING_TABLE else "anthropic"
+        rates = BUILTIN_PRICING_TABLE[provider_key]
+        input_rate = rates["input_per_1m_usd"]
+        output_rate = rates["output_per_1m_usd"]
+
+        cache_tokens = snap.tokens_saved_input + snap.tokens_saved_output
+        compress_tokens = snap.tokens_saved_compress
+        tokens_saved_total = cache_tokens + compress_tokens
+
+        # Cache skip: input + output tokens saved (whole call avoided)
+        savings_cache_usd = (snap.tokens_saved_input / 1_000_000) * input_rate + (snap.tokens_saved_output / 1_000_000) * output_rate
+        # Compression: input tokens only
+        savings_compress_usd = (compress_tokens / 1_000_000) * input_rate
+        total_usd = savings_cache_usd + savings_compress_usd
+
+        is_stale = self._is_stale()
+
+        return {
+            "usd": round(total_usd, 6),
+            "inr": round(total_usd * self.INR_RATE, 4),
+            "tokens_saved_total": tokens_saved_total,
+            "cache_tokens": cache_tokens,
+            "compress_tokens": compress_tokens,
+            "is_stale": is_stale,
+            "pricing_date": self._PRICING_DATE,
+        }
+
+    def _is_stale(self) -> bool:
+        """Return True if pricing data is older than _PRICING_STALE_DAYS."""
+        try:
+            table_date = date.fromisoformat(self._PRICING_DATE)
+            return (date.today() - table_date) > timedelta(days=_PRICING_STALE_DAYS)
+        except ValueError:
+            return True

package/src/superlocalmemory/optimize/metrics/exporters.py

@@ -0,0 +1,77 @@
+# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
+# Licensed under AGPL-3.0-or-later - see LICENSE file
+# Part of SuperLocalMemory V3 | https://qualixar.com | https://varunpratap.com
+
+"""Optional Prometheus/OpenTelemetry export. Guarded by try/except — no hard dependency."""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+logger = logging.getLogger("superlocalmemory.optimize.metrics.exporters")
+
+
+def get_prometheus_exporter() -> Any | None:
+    """Return a Prometheus exporter if prometheus_client is installed, else None.
+
+    Prometheus port: 9091 (NOT 8765, NOT 8766).
+    """
+    try:
+        from prometheus_client import Counter, Gauge, start_http_server  # noqa: F401
+        return _PrometheusExporter()
+    except ImportError:
+        return None
+
+
+class _PrometheusExporter:
+    """Thin wrapper around prometheus_client for SLM Optimize metrics."""
+
+    def __init__(self) -> None:
+        from prometheus_client import Counter, Gauge, start_http_server
+
+        self._cache_hits = Counter(
+            "slm_cache_hits_total", "Total cache hits"
+        )
+        self._cache_misses = Counter(
+            "slm_cache_misses_total", "Total cache misses"
+        )
+        self._tokens_saved = Counter(
+            "slm_tokens_saved_total", "Total tokens saved (cache + compress)"
+        )
+        self._compress_runs = Counter(
+            "slm_compress_runs_total", "Total compression runs"
+        )
+        self._cache_size = Gauge(
+            "slm_cache_size_bytes", "Cache size in bytes"
+        )
+        self._started = False
+
+    def start(self, port: int = 9091) -> None:
+        """Start Prometheus HTTP server on the given port."""
+        if self._started:
+            return
+        try:
+            from prometheus_client import start_http_server
+            start_http_server(port)
+            self._started = True
+            logger.info("Prometheus exporter started on port %d", port)
+        except Exception as exc:
+            logger.warning("Failed to start Prometheus exporter: %s", exc)
+
+    def update(self, snapshot: dict[str, Any]) -> None:
+        """Update Prometheus gauges/counters from a metrics snapshot dict."""
+        if not self._started:
+            return
+        try:
+            self._cache_hits._value.set(snapshot.get("hits", 0))
+            self._cache_misses._value.set(snapshot.get("misses", 0))
+            self._tokens_saved._value.set(
+                snapshot.get("tokens_saved_input", 0)
+                + snapshot.get("tokens_saved_output", 0)
+                + snapshot.get("tokens_saved_compress", 0)
+            )
+            self._compress_runs._value.set(snapshot.get("compress_runs", 0))
+            self._cache_size.set(snapshot.get("cache_size_bytes", 0))
+        except Exception as exc:
+            logger.debug("Prometheus update failed: %s", exc)

package/src/superlocalmemory/optimize/metrics/persistence.py

@@ -0,0 +1,115 @@
+# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
+# Licensed under AGPL-3.0-or-later - see LICENSE file
+# Part of SuperLocalMemory V3 | https://qualixar.com | https://varunpratap.com
+
+"""Flush in-memory counters to llmcache.db. Load on startup to restore counters."""
+
+from __future__ import annotations
+
+import logging
+import threading
+import time
+from typing import TYPE_CHECKING
+
+from superlocalmemory.optimize.metrics.counters import MetricsCollector
+from superlocalmemory.optimize.storage.db import CacheDB, MetricsSnapshot
+
+if TYPE_CHECKING:
+    pass
+
+logger = logging.getLogger("superlocalmemory.optimize.metrics.persistence")
+
+_FLUSH_INTERVAL_SECONDS: float = 60.0
+
+
+class MetricsPersistence:
+    """Flush in-memory counters -> llmcache.db. Load on startup -> restore counters.
+
+    Table: llmcache_metrics (16 columns — INTERFACE-CONTRACT §6).
+    Single aggregate row (id=1). INSERT OR REPLACE pattern.
+    NEVER reads or writes memory.db.
+    """
+
+    def __init__(self) -> None:
+        self._thread: threading.Thread | None = None
+        self._stop_event = threading.Event()
+
+    def flush(self, collector: MetricsCollector, db: CacheDB) -> None:
+        """Flush current collector state to llmcache_metrics via CacheDB."""
+        try:
+            try:
+                cache_size_bytes = db.db_size_bytes()
+            except Exception:
+                cache_size_bytes = 0
+            try:
+                cache_entry_count = db.entry_count()
+            except Exception:
+                cache_entry_count = 0
+            snap = collector.snapshot(
+                cache_size_bytes=cache_size_bytes,
+                cache_entry_count=cache_entry_count,
+            )
+            db.metrics_flush(snap)
+        except Exception as exc:
+            logger.warning("MetricsPersistence.flush failed: %s", exc)
+
+    def load(self, collector: MetricsCollector, db: CacheDB) -> None:
+        """Load persisted counters from llmcache_metrics into the live collector.
+
+        Runs at daemon startup to restore counters after restart.
+        """
+        try:
+            snap = db.metrics_load()
+            if snap.hits > 0 or snap.misses > 0:
+                # Restore counters from persisted snapshot
+                with collector._data_lock:
+                    collector._hits = snap.hits
+                    collector._misses = snap.misses
+                    collector._calls_skipped = snap.calls_skipped
+                    collector._tokens_saved_input = snap.tokens_saved_input
+                    collector._tokens_saved_output = snap.tokens_saved_output
+                    collector._tokens_saved_compress = snap.tokens_saved_compress
+                    collector._evictions = snap.evictions
+                    collector._latency_overhead_ms_sum = snap.latency_overhead_ms_sum
+                    collector._latency_samples = snap.latency_samples
+                    collector._compress_runs = snap.compress_runs
+                    collector._compress_bytes_original = snap.compress_bytes_original
+                    collector._compress_bytes_after = snap.compress_bytes_after
+                    collector._cache_size_bytes = snap.cache_size_bytes
+                    collector._cache_entry_count = snap.cache_entry_count
+                logger.info(
+                    "MetricsPersistence: restored %d hits, %d misses from llmcache.db",
+                    snap.hits, snap.misses,
+                )
+        except Exception as exc:
+            logger.warning("MetricsPersistence.load failed: %s", exc)
+
+    def start_background_flush(
+        self, collector: MetricsCollector, db: CacheDB
+    ) -> None:
+        """Start a background thread that flushes every 60s."""
+        if self._thread is not None and self._thread.is_alive():
+            return
+        self._stop_event.clear()
+
+        def _loop() -> None:
+            while not self._stop_event.is_set():
+                if self._stop_event.wait(timeout=_FLUSH_INTERVAL_SECONDS):
+                    return
+                try:
+                    self.flush(collector, db)
+                except Exception as exc:
+                    logger.warning("MetricsPersistence background flush error: %s", exc)
+
+        self._thread = threading.Thread(
+            target=_loop, name="slm-metrics-flush", daemon=True,
+        )
+        self._thread.start()
+
+    def stop_background_flush(self) -> None:
+        """Signal the background flush thread to stop."""
+        self._stop_event.set()
+        t = self._thread
+        if t is not None:
+            t.join(timeout=5.0)
+        self._thread = None

package/src/superlocalmemory/optimize/proxy/__init__.py

@@ -0,0 +1,28 @@
+"""Public exports for the Optimize proxy package."""
+
+from __future__ import annotations
+
+from superlocalmemory.optimize.proxy.lifecycle import (
+    CachedResponse,
+    CompressHook,
+    CacheHook,
+    HookChain,
+    ProviderResponse,
+    ProxyRequest,
+    ensure_proxy_running,
+    proxy_port,
+)
+from superlocalmemory.optimize.proxy.server import ProxyApp, build_proxy_router
+
+__all__ = [
+    "ProxyApp",
+    "build_proxy_router",
+    "ProxyRequest",
+    "CachedResponse",
+    "ProviderResponse",
+    "CacheHook",
+    "CompressHook",
+    "HookChain",
+    "ensure_proxy_running",
+    "proxy_port",
+]

package/src/superlocalmemory/optimize/proxy/_helpers.py

@@ -0,0 +1,257 @@
+"""_helpers.py — Shared HTTP utilities used by all surface modules."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from typing import Any, AsyncIterator
+
+import httpx
+from fastapi.requests import Request
+from fastapi.responses import Response, StreamingResponse
+
+from superlocalmemory.optimize.proxy.lifecycle import (
+    CachedResponse,
+    HookChain,
+    ProviderResponse,
+    ProxyRequest,
+)
+
+_get_running_loop = asyncio.get_running_loop
+
+logger = logging.getLogger("slm.optimize.proxy.helpers")
+
+# SEC-M-02 (CWE-400): reject oversized bodies to prevent compression-bomb DoS.
+_MAX_REQUEST_BODY_BYTES = 10 * 1024 * 1024  # 10 MB
+
+
+# Test helper: in-test httpx mock transport. NOT used in production code.
+from typing import Callable as _Callable
+import httpx as _httpx
+
+
+class _MockTransport(_httpx.AsyncBaseTransport):
+    """Minimal in-test mock for httpx that records requests and returns canned responses.
+
+    Handler may be sync (returns Response) or async (returns coroutine).
+    """
+
+    def __init__(self, handler: _Callable) -> None:
+        self._handler = handler
+        self.requests: list = []
+
+    async def handle_async_request(self, request: _httpx.Request) -> _httpx.Response:
+        self.requests.append(request)
+        result = self._handler(request)
+        if hasattr(result, "__await__"):
+            return await result
+        return result
+
+_HOP_BY_HOP = frozenset([
+    "connection", "keep-alive", "proxy-authenticate", "proxy-authorization",
+    "te", "trailer", "transfer-encoding", "upgrade", "host",
+    "x-forwarded-for", "x-forwarded-host", "x-forwarded-proto",
+    "x-real-ip", "x-original-forwarded-for",
+])
+
+_ANTHROPIC_FORWARD_HEADERS = frozenset([
+    "x-api-key",
+    "anthropic-version",
+    "anthropic-beta",
+    "x-claude-code-session-id",
+    "x-claude-code-agent-id",
+    "x-claude-code-parent-agent-id",
+    "authorization",
+    "content-type",
+])
+
+_OPENAI_FORWARD_HEADERS = frozenset([
+    "authorization",
+    "content-type",
+    "openai-beta",
+    "openai-organization",
+])
+
+_GEMINI_NATIVE_FORWARD_HEADERS = frozenset([
+    "x-goog-api-key",
+    "content-type",
+])
+
+_GEMINI_OPENAI_COMPAT_FORWARD_HEADERS = frozenset([
+    "authorization",
+    "content-type",
+])
+
+_SENSITIVE_HEADER_KEYS = frozenset([
+    "authorization",
+    "x-api-key",
+    "x-goog-api-key",
+])
+_REDACTED = "[REDACTED]"
+
+
+def _redact_headers(headers: dict) -> dict:
+    return {
+        k: (_REDACTED if k.lower() in _SENSITIVE_HEADER_KEYS else v)
+        for k, v in headers.items()
+    }
+
+
+def _body_has_tools(body: dict) -> bool:
+    tools = body.get("tools")
+    return isinstance(tools, list) and len(tools) > 0
+
+
+def _build_forward_headers(request: Request, allowed: frozenset) -> dict:
+    result: dict = {}
+    for k, v in request.headers.items():
+        kl = k.lower()
+        if kl in _HOP_BY_HOP:
+            continue
+        if kl in allowed:
+            result[kl] = v
+    return result
+
+
+def _filter_response_headers(headers) -> dict:
+    if hasattr(headers, "items"):
+        items = headers.items()
+    else:
+        items = headers
+    return {k: v for k, v in items if k.lower() not in _HOP_BY_HOP}
+
+
+async def _fail_open_forward(proxy: Any, request: Request, upstream_url: str) -> Response:
+    if proxy.http_client is None:
+        logger.error(
+            "fail_open_forward: http_client is None — startup() was not called. "
+            "Check daemon lifespan wiring."
+        )
+        return Response(
+            content=b'{"type":"error","error":{"type":"api_error",'
+                    b'"message":"SLM proxy not started - lifespan wiring error"}}',
+            status_code=502,
+            media_type="application/json",
+        )
+    try:
+        body_bytes = await request.body()
+        fwd_headers = {
+            k: v for k, v in request.headers.items()
+            if k.lower() not in _HOP_BY_HOP
+        }
+        upstream_resp = await proxy.http_client.request(
+            method=request.method,
+            url=upstream_url,
+            headers=fwd_headers,
+            content=body_bytes,
+        )
+        return Response(
+            content=upstream_resp.content,
+            status_code=upstream_resp.status_code,
+            headers=_filter_response_headers(dict(upstream_resp.headers)),
+        )
+    except Exception as exc:
+        logger.error("fail_open_forward failed upstream=%s exc=%r", upstream_url, exc)
+        return Response(
+            content=b'{"type":"error","error":{"type":"api_error",'
+                    b'"message":"SLM proxy unreachable - check upstream"}}',
+            status_code=502,
+            media_type="application/json",
+        )
+
+
+async def _stream_forward(
+    proxy: Any,
+    request_id: str,
+    fwd_headers: dict,
+    body_bytes: bytes,
+    upstream_url: str,
+) -> Response | StreamingResponse:
+    if proxy.http_client is None:
+        logger.error(
+            "[%s] _stream_forward: http_client is None - startup() was not called. "
+            "Check daemon lifespan wiring.",
+            request_id,
+        )
+        return Response(
+            content=b'{"type":"error","error":{"type":"api_error",'
+                    b'"message":"SLM proxy not started - lifespan wiring error"}}',
+            status_code=502,
+            media_type="application/json",
+        )
+
+    async def _generate() -> AsyncIterator[bytes]:
+        try:
+            async with proxy.http_client.stream(
+                "POST", upstream_url, content=body_bytes, headers=fwd_headers,
+            ) as upstream_resp:
+                async for chunk in upstream_resp.aiter_bytes():
+                    if chunk:
+                        yield chunk
+        except httpx.RemoteProtocolError as exc:
+            logger.warning("[%s] upstream stream closed early: %r", request_id, exc)
+            yield (
+                b'event: error\ndata: {"type":"error","error":{'
+                b'"type":"api_error","message":"upstream stream closed"}}\n\n'
+            )
+        except Exception as exc:
+            logger.error("[%s] stream forward error: %r", request_id, exc)
+            yield (
+                b'event: error\ndata: {"type":"error","error":{'
+                b'"type":"api_error","message":"SLM proxy stream error"}}\n\n'
+            )
+
+    return StreamingResponse(
+        _generate(),
+        media_type="text/event-stream",
+        headers={
+            "Cache-Control": "no-cache",
+            "Connection": "keep-alive",
+            "X-Accel-Buffering": "no",
+        },
+    )
+
+
+async def _safe_cache_check(hooks: HookChain, ctx: ProxyRequest) -> CachedResponse:
+    try:
+        result = hooks.cache.check(ctx)
+        return result if result is not None else CachedResponse(
+            hit=False, data=None, cache_key="", ttl_seconds=0
+        )
+    except Exception as exc:
+        logger.warning("cache.check failed (fail-open): %s", exc)
+        return CachedResponse(hit=False, data=None, cache_key="", ttl_seconds=0)
+
+
+async def _safe_cache_store(
+    hooks: HookChain,
+    ctx: ProxyRequest,
+    resp: ProviderResponse,
+) -> None:
+    try:
+        hooks.cache.store(ctx, resp)
+    except Exception as exc:
+        logger.warning("cache.store failed (fail-open): %s", exc)
+
+
+async def _safe_cache_hit_callbacks(
+    hooks: HookChain,
+    ctx: ProxyRequest,
+    response_bytes: bytes,
+    tokens_saved: int,
+) -> None:
+    try:
+        hooks.cache.on_hit(ctx, response_bytes, tokens_saved)
+    except Exception as exc:
+        logger.warning("cache.on_hit failed (fail-open): %s", exc)
+
+
+async def _safe_compress(hooks: HookChain, ctx: ProxyRequest) -> ProxyRequest:
+    try:
+        result: ProxyRequest = hooks.compress.compress(ctx)
+    except Exception as exc:
+        logger.warning("compress.compress failed (fail-open): %s", exc)
+        return ctx
+    # on_compress is fired internally by CompressRouter.compress() with
+    # actual token counts — no duplicate fire here.
+    return result