superlocalmemory 3.5.8 → 3.6.0

package/src/superlocalmemory/optimize/config/defaults.py

@@ -0,0 +1,48 @@
+"""Default OptimizeConfig singleton — import-safe."""
+
+from __future__ import annotations
+
+from superlocalmemory.optimize.config.schema import (
+    OptimizeConfig, ProviderConfig, TTLConfig,
+)
+
+DEFAULT_OPTIMIZE_CONFIG = OptimizeConfig(
+    enabled=False,
+    proxy_enabled=False,
+    cache_enabled=True,
+    semantic_enabled=False,
+    semantic_return_threshold=0.98,
+    semantic_verify_lo=0.90,
+    semantic_error_target=0.02,
+    semantic_explore_rate=0.10,
+    semantic_constant_time=False,
+    semantic_centroid_defense=True,
+    semantic_multiturn_guard=True,
+    semantic_ann_top_k=5,
+    semantic_boundary_init=0.95,
+    semantic_boundary_floor=0.85,
+    semantic_pad_latency_ms=0.0,
+    semantic_centroid_min_similarity=0.85,
+    compress_enabled=True,
+    compress_mode="safe",
+    compress_code=True,
+    compress_json=True,
+    compress_prose=False,
+    compress_ccr=True,
+    compress_align=True,
+    compress_protect_recent=4,
+    compress_llmlingua_allow_download=False,
+    ttl_seconds=86400,
+    ttl=TTLConfig(),
+    providers={
+        "anthropic": ProviderConfig(enabled=True, base_url=""),
+        "openai": ProviderConfig(enabled=True, base_url=""),
+        "gemini": ProviderConfig(enabled=True, base_url=""),
+    },
+    pricing={},
+    active_model="claude-sonnet-4-6",
+    usd_to_inr_rate=83.5,
+    pricing_overrides={},
+    prometheus_port=9091,
+    config_version=1,
+)

package/src/superlocalmemory/optimize/config/schema.py

@@ -0,0 +1,255 @@
+"""Typed schema for optimize.json.
+
+All fields have a default — partial JSON is always valid (additive migration).
+No imports from optimize.storage (no circular dependency).
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass, field
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class TTLConfig:
+    """TTL settings for each cache tier, in seconds."""
+
+    exact_seconds: int = 86400
+    semantic_seconds: int = 3600
+    ccr_seconds: int = 604800
+    sweep_interval_seconds: int = 3600
+
+    def validate(self) -> None:
+        for fname in ("exact_seconds", "semantic_seconds", "ccr_seconds",
+                      "sweep_interval_seconds"):
+            v = getattr(self, fname)
+            if not isinstance(v, int) or v <= 0:
+                raise ValueError(
+                    f"TTLConfig.{fname} must be a positive integer, got {v!r}"
+                )
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> "TTLConfig":
+        known = {f for f in cls.__dataclass_fields__}
+        return cls(**{k: v for k, v in d.items() if k in known})
+
+
+@dataclass
+class ProviderConfig:
+    """Per-provider settings."""
+
+    enabled: bool = True
+    base_url: str = ""
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> "ProviderConfig":
+        return cls(
+            enabled=bool(d.get("enabled", True)),
+            base_url=str(d.get("base_url", "")),
+        )
+
+    def as_dict(self) -> dict[str, Any]:
+        return {"enabled": self.enabled, "base_url": self.base_url}
+
+
+@dataclass(frozen=True)
+class OptimizeConfig:
+    """Master typed schema for ~/.superlocalmemory/optimize.json.
+
+    INTERFACE-CONTRACT §2 CONFORMANCE — all fields frozen, no aliases.
+    """
+
+    # Master kill-switch
+    enabled: bool = False
+    proxy_enabled: bool = False
+
+    # Cache
+    cache_enabled: bool = True
+    semantic_enabled: bool = False
+    semantic_return_threshold: float = 0.98
+    semantic_verify_lo: float = 0.90
+    semantic_error_target: float = 0.02
+    semantic_explore_rate: float = 0.10
+    semantic_constant_time: bool = False
+    semantic_centroid_defense: bool = True
+    semantic_multiturn_guard: bool = True
+    semantic_ann_top_k: int = 5
+    semantic_boundary_init: float = 0.95
+    semantic_boundary_floor: float = 0.85
+    semantic_boundary_ceiling: float = 0.995
+    semantic_boundary_step: float = 0.01
+    semantic_max_turns_for_semantic: int = 6
+    semantic_context_window_turns: int = 3
+    semantic_centroid_distance_floor: float = 0.15
+    semantic_verifier_model: str = ""
+    semantic_pad_latency_ms: float = 0.0
+    semantic_centroid_min_similarity: float = 0.85
+
+    # Compress
+    compress_enabled: bool = True
+    compress_mode: str = "safe"
+    compress_code: bool = True
+    compress_json: bool = True
+    compress_prose: bool = False
+    compress_ccr: bool = True
+    compress_align: bool = True
+    compress_protect_recent: int = 4
+    compress_llmlingua_allow_download: bool = False
+
+    # TTL + providers + pricing
+    ttl_seconds: int = 86400
+    providers: dict = field(default_factory=dict)
+    pricing: dict = field(default_factory=dict)
+
+    # Metrics/savings
+    active_model: str | None = None
+    usd_to_inr_rate: float = 83.5
+    pricing_overrides: dict = field(default_factory=dict)
+
+    # Observability
+    prometheus_port: int = 9091
+
+    # TTL sub-config
+    ttl: "TTLConfig" = field(default_factory=lambda: TTLConfig())
+
+    # Config version
+    config_version: int = 1
+
+    def validate(self) -> None:
+        if self.compress_mode not in ("safe", "aggressive"):
+            raise ValueError(
+                f"compress_mode must be 'safe' or 'aggressive', "
+                f"got {self.compress_mode!r}"
+            )
+        if not (0.0 < self.semantic_return_threshold <= 1.0):
+            raise ValueError(
+                f"semantic_return_threshold must be in (0.0, 1.0], "
+                f"got {self.semantic_return_threshold!r}"
+            )
+        if not (0.0 < self.semantic_error_target < 1.0):
+            raise ValueError(
+                f"semantic_error_target must be in (0.0, 1.0), "
+                f"got {self.semantic_error_target!r}"
+            )
+        if self.semantic_pad_latency_ms > 100:
+            logger.warning(
+                "semantic_pad_latency_ms=%s may negate cache latency benefit",
+                self.semantic_pad_latency_ms,
+            )
+        if self.prometheus_port < 1024 or self.prometheus_port > 65535:
+            raise ValueError(
+                f"prometheus_port must be 1024-65535, got {self.prometheus_port!r}"
+            )
+        self.ttl.validate()
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> "OptimizeConfig":
+        ttl_raw = d.get("ttl", {})
+        ttl = TTLConfig.from_dict(ttl_raw) if isinstance(ttl_raw, dict) else TTLConfig()
+
+        providers_raw = d.get("providers", {})
+        providers: dict[str, ProviderConfig] = {}
+        if isinstance(providers_raw, dict):
+            for pname, pdata in providers_raw.items():
+                if isinstance(pdata, dict):
+                    providers[pname] = ProviderConfig.from_dict(pdata)
+
+        return cls(
+            enabled=bool(d.get("enabled", False)),
+            proxy_enabled=bool(d.get("proxy_enabled", False)),
+            cache_enabled=bool(d.get("cache_enabled", True)),
+            semantic_enabled=bool(d.get("semantic_enabled", False)),
+            semantic_return_threshold=float(d.get("semantic_return_threshold", 0.98)),
+            semantic_verify_lo=float(d.get("semantic_verify_lo", 0.90)),
+            semantic_error_target=float(d.get("semantic_error_target", 0.02)),
+            semantic_explore_rate=float(d.get("semantic_explore_rate", 0.10)),
+            semantic_constant_time=bool(d.get("semantic_constant_time", False)),
+            semantic_centroid_defense=bool(d.get("semantic_centroid_defense", True)),
+            semantic_multiturn_guard=bool(d.get("semantic_multiturn_guard", True)),
+            semantic_ann_top_k=int(d.get("semantic_ann_top_k", 5)),
+            semantic_boundary_init=float(d.get("semantic_boundary_init", 0.95)),
+            semantic_boundary_floor=float(d.get("semantic_boundary_floor", 0.85)),
+            semantic_boundary_ceiling=float(d.get("semantic_boundary_ceiling", 0.995)),
+            semantic_boundary_step=float(d.get("semantic_boundary_step", 0.01)),
+            semantic_max_turns_for_semantic=int(d.get("semantic_max_turns_for_semantic", 6)),
+            semantic_context_window_turns=int(d.get("semantic_context_window_turns", 3)),
+            semantic_centroid_distance_floor=float(d.get("semantic_centroid_distance_floor", 0.15)),
+            semantic_verifier_model=str(d.get("semantic_verifier_model", "")),
+            semantic_pad_latency_ms=float(d.get("semantic_pad_latency_ms", 0.0)),
+            semantic_centroid_min_similarity=float(
+                d.get("semantic_centroid_min_similarity", 0.85)
+            ),
+            compress_enabled=bool(d.get("compress_enabled", True)),
+            compress_mode=str(d.get("compress_mode", "safe")),
+            compress_code=bool(d.get("compress_code", True)),
+            compress_json=bool(d.get("compress_json", True)),
+            compress_prose=bool(d.get("compress_prose", False)),
+            compress_ccr=bool(d.get("compress_ccr", True)),
+            compress_align=bool(d.get("compress_align", True)),
+            compress_protect_recent=int(d.get("compress_protect_recent", 4)),
+            compress_llmlingua_allow_download=bool(
+                d.get("compress_llmlingua_allow_download", False)
+            ),
+            ttl_seconds=int(d.get("ttl_seconds", 86400)),
+            providers=providers,
+            pricing=dict(d.get("pricing", {})),
+            active_model=str(d.get("active_model", None)) if d.get("active_model") else None,
+            usd_to_inr_rate=float(d.get("usd_to_inr_rate", 83.5)),
+            pricing_overrides=dict(d.get("pricing_overrides", {})),
+            prometheus_port=int(d.get("prometheus_port", 9091)),
+            ttl=ttl,
+            config_version=int(d.get("config_version", 1)),
+        )
+
+    def as_dict(self) -> dict[str, Any]:
+        return {
+            "enabled": self.enabled,
+            "proxy_enabled": self.proxy_enabled,
+            "cache_enabled": self.cache_enabled,
+            "semantic_enabled": self.semantic_enabled,
+            "semantic_return_threshold": self.semantic_return_threshold,
+            "semantic_verify_lo": self.semantic_verify_lo,
+            "semantic_error_target": self.semantic_error_target,
+            "semantic_explore_rate": self.semantic_explore_rate,
+            "semantic_constant_time": self.semantic_constant_time,
+            "semantic_centroid_defense": self.semantic_centroid_defense,
+            "semantic_multiturn_guard": self.semantic_multiturn_guard,
+            "semantic_ann_top_k": self.semantic_ann_top_k,
+            "semantic_boundary_init": self.semantic_boundary_init,
+            "semantic_boundary_floor": self.semantic_boundary_floor,
+            "semantic_boundary_ceiling": self.semantic_boundary_ceiling,
+            "semantic_boundary_step": self.semantic_boundary_step,
+            "semantic_max_turns_for_semantic": self.semantic_max_turns_for_semantic,
+            "semantic_context_window_turns": self.semantic_context_window_turns,
+            "semantic_centroid_distance_floor": self.semantic_centroid_distance_floor,
+            "semantic_verifier_model": self.semantic_verifier_model,
+            "semantic_pad_latency_ms": self.semantic_pad_latency_ms,
+            "semantic_centroid_min_similarity": self.semantic_centroid_min_similarity,
+            "compress_enabled": self.compress_enabled,
+            "compress_mode": self.compress_mode,
+            "compress_code": self.compress_code,
+            "compress_json": self.compress_json,
+            "compress_prose": self.compress_prose,
+            "compress_ccr": self.compress_ccr,
+            "compress_align": self.compress_align,
+            "compress_protect_recent": self.compress_protect_recent,
+            "compress_llmlingua_allow_download": self.compress_llmlingua_allow_download,
+            "ttl_seconds": self.ttl_seconds,
+            "providers": {k: v.as_dict() for k, v in self.providers.items()},
+            "pricing": self.pricing,
+            "active_model": self.active_model,
+            "usd_to_inr_rate": self.usd_to_inr_rate,
+            "pricing_overrides": self.pricing_overrides,
+            "prometheus_port": self.prometheus_port,
+            "ttl": {
+                "exact_seconds": self.ttl.exact_seconds,
+                "semantic_seconds": self.ttl.semantic_seconds,
+                "ccr_seconds": self.ttl.ccr_seconds,
+                "sweep_interval_seconds": self.ttl.sweep_interval_seconds,
+            },
+            "config_version": self.config_version,
+        }
+

package/src/superlocalmemory/optimize/config/store.py

@@ -0,0 +1,209 @@
+"""ConfigStore — reads, writes, and hot-reloads optimize.json.
+
+SINGLE SOURCE OF TRUTH for the daemon, UI, CLI, and MCP tools.
+UI and CLI write via save(); daemon reads via get() which is always current.
+
+Hot-reload: a background watchdog thread polls optimize.json every 2 seconds.
+On mtime change, it parses and validates; if valid, atomically swaps the
+active config. If invalid, keeps the old config (fail-open).
+
+Thread safety: self._lock (threading.RLock) protects self._current_config
+and self._version. get() acquires a read-lock; save() acquires a write-lock.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import threading
+import time
+from pathlib import Path
+from typing import Any, Callable
+
+from superlocalmemory.optimize.config.schema import OptimizeConfig
+from superlocalmemory.optimize.config.defaults import DEFAULT_OPTIMIZE_CONFIG
+
+logger = logging.getLogger(__name__)
+
+_DEFAULT_CONFIG_PATH: Path = Path.home() / ".superlocalmemory" / "optimize.json"
+_POLL_INTERVAL_SECONDS: float = 2.0
+
+
+class ConfigStore:
+    """Manages optimize.json with hot-reload capability."""
+
+    def __init__(
+        self,
+        config_path: Path | None = None,
+        poll_interval: float = _POLL_INTERVAL_SECONDS,
+    ) -> None:
+        self._config_path = Path(config_path) if config_path else _DEFAULT_CONFIG_PATH
+        self._poll_interval_seconds = float(poll_interval)
+        self._lock = threading.RLock()
+        self._change_callbacks: list[Callable[[OptimizeConfig], None]] = []
+        self._stop_event = threading.Event()
+        self._watchdog_thread: threading.Thread | None = None
+
+        self._saved_by_self: bool = False
+        self._current_config: OptimizeConfig = DEFAULT_OPTIMIZE_CONFIG
+        self._last_mtime: float = 0.0
+        self._version: int = DEFAULT_OPTIMIZE_CONFIG.config_version
+
+        # Load initial state from disk if available.
+        try:
+            if self._config_path.exists():
+                self._current_config = self._load_from_disk()
+                try:
+                    self._last_mtime = self._config_path.stat().st_mtime
+                except OSError:
+                    self._last_mtime = 0.0
+                self._version = self._current_config.config_version
+        except (json.JSONDecodeError, ValueError, TypeError, OSError) as exc:
+            logger.warning(
+                "ConfigStore: failed to parse %s — using defaults: %s",
+                self._config_path, exc,
+            )
+
+    def get(self) -> OptimizeConfig:
+        """Return the current active config (thread-safe, no I/O).
+
+        INTERFACE-CONTRACT v2.2 §2 — canonical accessor.
+        """
+        with self._lock:
+            return self._current_config
+
+    def save(self, config: OptimizeConfig) -> None:
+        """Write config to optimize.json with version bump."""
+        config.validate()
+        with self._lock:
+            new_version = self._version + 1
+            new_cfg = OptimizeConfig.from_dict(
+                {**config.as_dict(), "config_version": new_version}
+            )
+            new_cfg.validate()
+            self._saved_by_self = True
+            try:
+                self._atomic_write(new_cfg.as_dict())
+                try:
+                    self._last_mtime = self._config_path.stat().st_mtime
+                except OSError:
+                    self._last_mtime = 0.0
+                self._current_config = new_cfg
+                self._version = new_version
+            finally:
+                self._saved_by_self = False
+
+    def start_watchdog(self) -> None:
+        """Start the background hot-reload watchdog thread.
+
+        Idempotent — safe to call multiple times.
+        """
+        with self._lock:
+            if self._watchdog_thread is not None and self._watchdog_thread.is_alive():
+                return
+            self._stop_event.clear()
+            self._watchdog_thread = threading.Thread(
+                target=self._watchdog_loop,
+                name="slm-optimize-config-watchdog",
+                daemon=True,
+            )
+            self._watchdog_thread.start()
+
+    def stop_watchdog(self) -> None:
+        """Signal the watchdog thread to stop and join it (timeout=5s)."""
+        self._stop_event.set()
+        t = self._watchdog_thread
+        if t is not None:
+            t.join(timeout=5.0)
+        with self._lock:
+            self._watchdog_thread = None
+
+    def version(self) -> int:
+        with self._lock:
+            return self._version
+
+    def register_change_callback(
+        self, callback: Callable[[OptimizeConfig], None]
+    ) -> None:
+        with self._lock:
+            self._change_callbacks.append(callback)
+
+    # ---- private ----
+
+    def _load_from_disk(self) -> OptimizeConfig:
+        raw = self._config_path.read_text(encoding="utf-8")
+        data = json.loads(raw)
+        if not isinstance(data, dict):
+            raise ValueError("optimize.json root must be an object")
+        return OptimizeConfig.from_dict(data)
+
+    def _atomic_write(self, data: dict[str, Any]) -> None:
+        self._config_path.parent.mkdir(parents=True, exist_ok=True)
+        tmp = self._config_path.with_suffix(self._config_path.suffix + ".tmp")
+        with open(tmp, "w", encoding="utf-8") as f:
+            json.dump(data, f, indent=2, sort_keys=True)
+            f.flush()
+            os.fsync(f.fileno())
+        os.replace(tmp, self._config_path)
+        try:
+            os.chmod(self._config_path, 0o600)
+        except OSError:
+            pass
+
+    def _watchdog_loop(self) -> None:
+        while not self._stop_event.is_set():
+            # Sleep with cancellation
+            if self._stop_event.wait(timeout=self._poll_interval_seconds):
+                return
+            try:
+                try:
+                    mtime = self._config_path.stat().st_mtime
+                except FileNotFoundError:
+                    continue
+                except OSError as exc:
+                    logger.warning("ConfigStore watchdog stat error: %s", exc)
+                    continue
+
+                with self._lock:
+                    if mtime == self._last_mtime:
+                        continue
+                    if self._saved_by_self:
+                        self._last_mtime = mtime
+                        self._saved_by_self = False
+                        continue
+
+                # Parse + validate OUTSIDE the lock to avoid contention.
+                try:
+                    new_config = self._load_from_disk()
+                except (json.JSONDecodeError, ValueError, TypeError, OSError) as exc:
+                    logger.warning(
+                        "ConfigStore hot-reload PARSE ERROR — keeping previous config: %s",
+                        exc,
+                    )
+                    continue
+
+                with self._lock:
+                    # Re-check after lock: another save may have completed.
+                    if mtime == self._last_mtime:
+                        continue
+                    self._current_config = new_config
+                    self._last_mtime = mtime
+                    self._version += 1
+                new_version = self._version
+
+                # Snapshot callbacks under lock, iterate outside.
+                with self._lock:
+                    callbacks = list(self._change_callbacks)
+                for cb in callbacks:
+                    try:
+                        cb(new_config)
+                    except Exception as exc:
+                        logger.warning("ConfigStore callback error: %s", exc)
+
+                logger.info(
+                    "ConfigStore hot-reloaded optimize.json (version %d)",
+                    new_version,
+                )
+            except Exception as exc:
+                logger.critical("ConfigStore watchdog thread crashed: %s", exc, exc_info=True)

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

@@ -0,0 +1,8 @@
+# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
+# Licensed under AGPL-3.0-or-later - see LICENSE file
+"""Metrics layer for SLM v3.6 Optimize module."""
+
+from superlocalmemory.optimize.metrics.counters import MetricsCollector, get_metrics
+from superlocalmemory.optimize.metrics.estimator import SavingsEstimator
+
+__all__ = ["MetricsCollector", "SavingsEstimator", "get_metrics"]

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

@@ -0,0 +1,138 @@
+# 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: CacheMetrics design pattern adapted from:
+#   omnicache_ai/core/metrics.py (MIT License)
+
+"""Thread-safe atomic counters for all SLM Optimize operations."""
+
+from __future__ import annotations
+
+import threading
+from typing import ClassVar
+
+from superlocalmemory.optimize.storage.db import MetricsSnapshot
+
+
+class MetricsCollector:
+    """Thread-safe atomic in-memory counters. Daemon-scoped singleton.
+
+    All increment methods acquire a threading.Lock. Each increment is
+    O(1) and must add < 1 µs of latency on the hot path.
+
+    Hook binding (from INTERFACE-CONTRACT §3):
+        on_hit(tokens_saved_input, tokens_saved_output):  cache hit
+        on_miss():                                         cache miss
+        on_compress(bytes_original, bytes_after):          compress ran
+        on_eviction():                                     entry expired/evicted
+    """
+
+    _instance: ClassVar[MetricsCollector | None] = None
+    _lock: ClassVar[threading.Lock] = threading.Lock()
+
+    def __init__(self) -> None:
+        self._data_lock = threading.Lock()
+        self._hits: int = 0
+        self._misses: int = 0
+        self._calls_skipped: int = 0
+        self._tokens_saved_input: int = 0
+        self._tokens_saved_output: int = 0
+        self._tokens_saved_compress: int = 0
+        self._evictions: int = 0
+        self._latency_overhead_ms_sum: float = 0.0
+        self._latency_samples: int = 0
+        self._compress_runs: int = 0
+        self._compress_bytes_original: int = 0
+        self._compress_bytes_after: int = 0
+        self._cache_size_bytes: int = 0
+        self._cache_entry_count: int = 0
+
+    @classmethod
+    def get_instance(cls) -> MetricsCollector:
+        """Return the process-global singleton. Thread-safe."""
+        if cls._instance is None:
+            with cls._lock:
+                if cls._instance is None:
+                    cls._instance = cls()
+        return cls._instance
+
+    def on_hit(self, tokens_saved_input: int = 0, tokens_saved_output: int = 0) -> None:
+        """Record a cache hit with tokens saved."""
+        with self._data_lock:
+            self._hits += 1
+            self._tokens_saved_input += max(0, tokens_saved_input)
+            self._tokens_saved_output += max(0, tokens_saved_output)
+
+    def on_miss(self) -> None:
+        """Record a cache miss."""
+        with self._data_lock:
+            self._misses += 1
+
+    def on_compress(self, bytes_original: int, bytes_after: int) -> None:
+        """Record a compression run with byte counts."""
+        with self._data_lock:
+            self._compress_runs += 1
+            self._compress_bytes_original += max(0, bytes_original)
+            self._compress_bytes_after += max(0, bytes_after)
+            saved_tokens = max(0, bytes_original - bytes_after)
+            self._tokens_saved_compress += saved_tokens
+
+    def on_eviction(self) -> None:
+        """Record an eviction."""
+        with self._data_lock:
+            self._evictions += 1
+
+    def record_latency(self, ms: float) -> None:
+        """Record latency overhead in milliseconds."""
+        if ms < 0:
+            return
+        with self._data_lock:
+            self._latency_overhead_ms_sum += ms
+            self._latency_samples += 1
+
+    def snapshot(self, cache_size_bytes: int | None = None, cache_entry_count: int | None = None) -> MetricsSnapshot:
+        """Return a consistent read of all counters as a MetricsSnapshot."""
+        with self._data_lock:
+            import time
+            return MetricsSnapshot(
+                id=1,
+                hits=self._hits,
+                misses=self._misses,
+                calls_skipped=self._calls_skipped,
+                tokens_saved_input=self._tokens_saved_input,
+                tokens_saved_output=self._tokens_saved_output,
+                tokens_saved_compress=self._tokens_saved_compress,
+                evictions=self._evictions,
+                latency_overhead_ms_sum=self._latency_overhead_ms_sum,
+                latency_samples=self._latency_samples,
+                compress_runs=self._compress_runs,
+                compress_bytes_original=self._compress_bytes_original,
+                compress_bytes_after=self._compress_bytes_after,
+                cache_size_bytes=cache_size_bytes if cache_size_bytes is not None else self._cache_size_bytes,
+                cache_entry_count=cache_entry_count if cache_entry_count is not None else self._cache_entry_count,
+                updated_at=time.time(),
+            )
+
+    def reset(self) -> None:
+        """Reset all counters. FOR TESTS ONLY."""
+        with self._data_lock:
+            self._hits = 0
+            self._misses = 0
+            self._calls_skipped = 0
+            self._tokens_saved_input = 0
+            self._tokens_saved_output = 0
+            self._tokens_saved_compress = 0
+            self._evictions = 0
+            self._latency_overhead_ms_sum = 0.0
+            self._latency_samples = 0
+            self._compress_runs = 0
+            self._compress_bytes_original = 0
+            self._compress_bytes_after = 0
+            self._cache_size_bytes = 0
+            self._cache_entry_count = 0
+
+
+def get_metrics() -> MetricsCollector:
+    """Return the process-global MetricsCollector singleton."""
+    return MetricsCollector.get_instance()