superlocalmemory 4.1.13 → 4.1.14

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

@@ -1,270 +0,0 @@
-"""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 atexit
-import json
-import logging
-import os
-import threading
-import weakref
-from pathlib import Path
-from typing import Any, Callable
-
-from superlocalmemory.infra.data_root import DynamicStatePath
-from superlocalmemory.optimize.config.defaults import DEFAULT_OPTIMIZE_CONFIG
-from superlocalmemory.optimize.config.schema import OptimizeConfig
-
-logger = logging.getLogger(__name__)
-
-_DEFAULT_CONFIG_PATH = DynamicStatePath("optimize.json")
-_POLL_INTERVAL_SECONDS: float = 2.0
-
-# ---- watchdog shutdown safety -------------------------------------------
-# Each started watchdog runs in a daemon thread. At interpreter shutdown CPython
-# kills daemon threads abruptly; on macOS, with the ``watchdog`` fsevents C
-# extension also loaded in-process, a daemon thread still executing while the
-# interpreter finalizes can race the teardown and SIGSEGV. We track every store
-# that has a live watchdog and stop+join them from an ``atexit`` hook — atexit
-# callbacks run BEFORE daemon threads are terminated, so no watchdog thread is
-# still alive when CPython finalizes.
-_active_stores: "weakref.WeakSet[ConfigStore]" = weakref.WeakSet()
-_registry_lock = threading.Lock()
-_atexit_registered = False
-
-
-def _register_active_store(store: "ConfigStore") -> None:
-    """Track a store with a running watchdog; install the atexit hook once."""
-    global _atexit_registered
-    with _registry_lock:
-        _active_stores.add(store)
-        if not _atexit_registered:
-            atexit.register(_stop_all_watchdogs)
-            _atexit_registered = True
-
-
-def _stop_all_watchdogs() -> None:
-    """Stop+join every registered watchdog. Idempotent; safe at interpreter exit.
-
-    Also invoked by the test harness at session finish (see tests/conftest.py)
-    so no leaked watchdog thread survives into interpreter finalization.
-    """
-    with _registry_lock:
-        stores = list(_active_stores)
-    for store in stores:
-        try:
-            store.stop_watchdog()
-        except Exception:
-            pass
-
-
-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 is not None 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.
-
-        Fires registered change callbacks immediately after a successful write
-        (outside the lock) so a UI/CLI save reaches the live proxy without
-        waiting for the 2s watchdog poll. The watchdog skips this write via
-        ``_saved_by_self`` so callbacks fire exactly once.
-        """
-        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
-            callbacks = list(self._change_callbacks)
-        # Fire callbacks OUTSIDE the lock — a callback may rebuild proxy hooks
-        # or call back into get(); keeping them off the lock avoids contention.
-        for cb in callbacks:
-            try:
-                cb(new_cfg)
-            except Exception as exc:
-                logger.warning("ConfigStore save callback error: %s", exc)
-
-    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()
-        # Register outside self._lock — _register_active_store takes the module
-        # registry lock, and the idempotent early-return above already covers a
-        # re-start (the store stays registered from the first start).
-        _register_active_store(self)
-
-    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
-        with _registry_lock:
-            _active_stores.discard(self)
-
-    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

@@ -1,8 +0,0 @@
-# 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

@@ -1,155 +0,0 @@
-# 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
-
-"""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(tokens_before, tokens_after):          compress ran (word-count proxy)
-        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._lossy_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, tokens_before: int, tokens_after: int, lossy: bool = False) -> None:
-        """Record a compression run. Arguments are word-count proxy estimates from _token_estimate().
-
-        M-03: consistent naming — these are token estimates, not byte counts.
-        Stored in compress_bytes_original/after fields for DB schema compat; unit is word-count.
-
-        ``lossy`` distinguishes a Layer-2 lossy (LLMLingua prose) run from a
-        lossless Layer-1/JSON-minify run; tracked in memory (not yet persisted).
-        """
-        with self._data_lock:
-            self._compress_runs += 1
-            if lossy:
-                self._lossy_compress_runs += 1
-            self._compress_bytes_original += max(0, tokens_before)
-            self._compress_bytes_after += max(0, tokens_after)
-            self._tokens_saved_compress += max(0, tokens_before - tokens_after)
-
-    def lossy_compress_runs(self) -> int:
-        """Session-scoped count of lossy (Layer-2) compression runs."""
-        with self._data_lock:
-            return self._lossy_compress_runs
-
-    def on_eviction(self) -> None:
-        """Record an eviction."""
-        with self._data_lock:
-            self._evictions += 1
-
-    def increment_skipped_temperature(self) -> None:
-        """C-04: record a cache skip due to non-zero temperature."""
-        with self._data_lock:
-            self._calls_skipped += 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._lossy_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()

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

@@ -1,87 +0,0 @@
-# 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
-
-"""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

@@ -1,77 +0,0 @@
-# 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)