superlocalmemory 4.1.13 → 4.1.15

package/src/superlocalmemory/learning/model_rollback.py

@@ -1,281 +0,0 @@
-# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
-# Licensed under AGPL-3.0-or-later - see LICENSE file
-# Part of SuperLocalMemory v3.4.22 — Track A.3 (LLD-10 §5)
-
-"""Post-promotion watch + auto-rollback (LLD-10 §5).
-
-After promotion flips ``is_active`` to the new row, the next 200
-recalls are measured against the pre-promotion baseline. If mean
-NDCG@10 drops by ≥ REGRESSION_THRESHOLD (2%), auto-rollback fires:
-
-* Current active → ``is_rollback=1``, ``is_active=0``,
-  ``rollback_reason=<reason>``.
-* Former ``is_previous`` → ``is_active=1``, ``is_previous=0``.
-* ``metadata_json.retrain_disabled_until`` set to now+24h; counter
-  reset to 0.
-
-All three flag flips happen inside one ``BEGIN IMMEDIATE`` transaction.
-The partial unique indexes ``idx_model_active_one`` and
-``idx_model_candidate_one`` (M009) enforce single-active and
-single-candidate per profile.
-
-Failure-mode handling (LLD-10 §5.4 "missing is_previous"):
-   If the is_previous row is absent, we do NOT demote the current
-   active — that would leave the profile with no active model.
-   Instead we log an error, set ``metadata_json.safe_mode=1`` on the
-   active row, and let AdaptiveRanker fall back to Phase-2 heuristic.
-"""
-
-from __future__ import annotations
-
-import json
-import logging
-import sqlite3
-from datetime import datetime, timedelta, timezone
-from typing import Final
-
-from superlocalmemory.learning.model_cache import invalidate as invalidate_model_cache
-
-logger = logging.getLogger(__name__)
-
-
-_WATCH_WINDOW: Final[int] = 200
-_REGRESSION_THRESHOLD: Final[float] = 0.02
-_RETRAIN_DISABLED_HOURS: Final[int] = 24
-
-#: Baseline floor below which the ratio ``(baseline - current) / baseline``
-#: is numerically meaningless (division explodes; a 1pp drop on a 0.5%
-#: baseline looks like 200% regression). Below this floor we switch to
-#: an ABSOLUTE-drop comparison against ``_REGRESSION_THRESHOLD``. Stage 8
-#: F4.B H-04 fix — previously baseline ≤ 0 silently disarmed the
-#: watchdog, which meant a freshly-promoted-but-broken model with a
-#: sparse-data baseline of 0 would never auto-rollback.
-_BASELINE_RATIO_FLOOR: Final[float] = 0.05
-
-
-def _iso_now() -> str:
-    return datetime.now(timezone.utc).isoformat()
-
-
-def _iso_in_hours(hours: int) -> str:
-    return (
-        datetime.now(timezone.utc) + timedelta(hours=hours)
-    ).isoformat()
-
-
-class ModelRollback:
-    """Watch post-promotion NDCG@10 and flip lineage on regression."""
-
-    WATCH_WINDOW: Final[int] = _WATCH_WINDOW
-    REGRESSION_THRESHOLD: Final[float] = _REGRESSION_THRESHOLD
-    RETRAIN_DISABLED_HOURS: Final[int] = _RETRAIN_DISABLED_HOURS
-
-    def __init__(
-        self,
-        *,
-        learning_db_path: str,
-        profile_id: str,
-        baseline_ndcg: float,
-    ) -> None:
-        self._db = str(learning_db_path)
-        self._profile_id = profile_id
-        self._baseline = float(baseline_ndcg)
-        self._observations: list[float] = []
-
-    # ------------------------------------------------------------------
-    # Observation ingestion
-    # ------------------------------------------------------------------
-
-    def record_post_promotion(
-        self, *, query_id: str, ndcg_at_10: float,
-    ) -> None:
-        """Record one post-promotion NDCG@10 sample (at most WATCH_WINDOW)."""
-        if len(self._observations) >= self.WATCH_WINDOW:
-            return
-        self._observations.append(float(ndcg_at_10))
-
-    def should_rollback(self) -> bool:
-        """Return True iff ≥ WATCH_WINDOW samples and regression detected.
-
-        Regression is detected by whichever of these is true:
-          * **Ratio path** (baseline ≥ ``_BASELINE_RATIO_FLOOR``, i.e. 0.05):
-            ``(baseline - current) / baseline ≥ REGRESSION_THRESHOLD``.
-            Existing v3.4.22 pre-fix semantics preserved at normal
-            baselines.
-          * **Absolute path** (baseline below the ratio floor — includes
-            zero and negative baselines which can happen on sparse data):
-            ``(baseline - current) ≥ REGRESSION_THRESHOLD`` in absolute
-            units. Stage 8 F4.B H-04 fix — a zero baseline is a valid
-            observation, not "no baseline".
-
-        Invariants:
-          * Watch window minimum is always enforced — we will NOT fire
-            before ``WATCH_WINDOW`` samples land.
-          * ``REGRESSION_THRESHOLD`` is the same 0.02 for both paths, so
-            the fix is not stricter for typical baselines.
-        """
-        if len(self._observations) < self.WATCH_WINDOW:
-            return False
-        current = sum(self._observations) / len(self._observations)
-        drop_abs = self._baseline - current
-        # S9-SKEP-10: smooth the ratio/absolute boundary.
-        #
-        # Before this fix there was a step discontinuity at
-        # ``baseline == _BASELINE_RATIO_FLOOR`` (0.05):
-        #   * baseline=0.049 → abs path fires at drop≥0.02
-        #   * baseline=0.050 → ratio path fires at drop≥0.001 (0.02*0.05)
-        # So a 0.001 baseline drift produced a 20× sensitivity change,
-        # and new-user profiles near 0.05 oscillated between "never
-        # rollback" and "rollback on any noise". We now linearly blend
-        # the two thresholds across a ±`_BLEND_BAND` neighbourhood
-        # around the floor, so the derivative of the threshold with
-        # respect to baseline stays bounded.
-        #
-        # Asymptotic equivalence:
-        #   baseline ≥ floor + band  → pure ratio (prior behaviour).
-        #   baseline ≤ floor - band  → pure absolute (prior behaviour).
-        _BLEND_BAND = 0.02
-        hi = _BASELINE_RATIO_FLOOR + _BLEND_BAND
-        lo = max(0.0, _BASELINE_RATIO_FLOOR - _BLEND_BAND)
-        # The "drop needed to fire" in each regime.
-        #   ratio regime: drop ≥ baseline * REGRESSION_THRESHOLD
-        #   abs regime:   drop ≥ REGRESSION_THRESHOLD
-        ratio_drop = self._baseline * self.REGRESSION_THRESHOLD
-        abs_drop = self.REGRESSION_THRESHOLD
-        if self._baseline >= hi:
-            needed = ratio_drop
-        elif self._baseline <= lo:
-            needed = abs_drop
-        else:
-            # Linear blend — at baseline=lo weight=0, at baseline=hi weight=1.
-            weight = (self._baseline - lo) / (hi - lo)
-            needed = weight * ratio_drop + (1.0 - weight) * abs_drop
-        return drop_abs >= needed
-
-    # ------------------------------------------------------------------
-    # Lineage flip
-    # ------------------------------------------------------------------
-
-    def execute_rollback(self, reason: str) -> bool:
-        """Flip lineage atomically — return True on success.
-
-        Transaction shape (all under one BEGIN IMMEDIATE):
-          1. Confirm an ``is_previous=1`` row exists for profile.
-             If missing → abort, set ``safe_mode`` on active, return False.
-          2. Current active row: set ``is_active=0, is_rollback=1,
-             rollback_reason=?``.
-          3. Previous row: set ``is_active=1, is_previous=0``.
-          4. Patch ``metadata_json`` on the new active with
-             ``retrain_disabled_until`` (+24h) and
-             ``last_rollback_at``, counter reset.
-        """
-        with sqlite3.connect(self._db, timeout=10) as conn:
-            conn.row_factory = sqlite3.Row
-            try:
-                conn.execute("BEGIN IMMEDIATE")
-                prev = conn.execute(
-                    "SELECT id FROM learning_model_state "
-                    "WHERE profile_id = ? AND is_previous = 1 LIMIT 1",
-                    (self._profile_id,),
-                ).fetchone()
-                if prev is None:
-                    conn.rollback()
-                    self._set_safe_mode(conn)
-                    logger.error(
-                        "rollback: missing is_previous row for profile=%s "
-                        "reason=%s — entering safe_mode",
-                        self._profile_id, reason,
-                    )
-                    return False
-
-                # Step 2 — demote current active (unset is_active FIRST so
-                # the partial unique index on is_active=1 never has two rows).
-                conn.execute(
-                    "UPDATE learning_model_state "
-                    "SET is_active = 0, is_rollback = 1, "
-                    "    rollback_reason = ? "
-                    "WHERE profile_id = ? AND is_active = 1",
-                    (reason, self._profile_id),
-                )
-
-                # Step 3 — promote previous to active.
-                conn.execute(
-                    "UPDATE learning_model_state "
-                    "SET is_active = 1, is_previous = 0 "
-                    "WHERE id = ?",
-                    (prev["id"],),
-                )
-
-                # Step 4 — patch metadata on the new active.
-                new_meta_row = conn.execute(
-                    "SELECT metadata_json FROM learning_model_state "
-                    "WHERE id = ?",
-                    (prev["id"],),
-                ).fetchone()
-                try:
-                    meta = json.loads(new_meta_row["metadata_json"] or "{}")
-                except (TypeError, ValueError):
-                    meta = {}
-                meta.update({
-                    "retrain_disabled_until": _iso_in_hours(
-                        self.RETRAIN_DISABLED_HOURS,
-                    ),
-                    "last_rollback_at": _iso_now(),
-                    "new_outcomes_since_last_retrain": 0,
-                })
-                conn.execute(
-                    "UPDATE learning_model_state "
-                    "SET metadata_json = ? WHERE id = ?",
-                    (json.dumps(meta), prev["id"]),
-                )
-                conn.commit()
-            except sqlite3.Error as exc:
-                conn.rollback()
-                logger.error(
-                    "rollback: sqlite error profile=%s reason=%s: %s",
-                    self._profile_id, reason, exc,
-                )
-                return False
-
-        invalidate_model_cache(self._profile_id)
-        logger.warning(
-            "AUTO-ROLLBACK profile=%s reason=%s observations=%d "
-            "baseline_ndcg=%.4f current_ndcg=%.4f",
-            self._profile_id, reason, len(self._observations),
-            self._baseline,
-            (sum(self._observations) / len(self._observations))
-            if self._observations else 0.0,
-        )
-        return True
-
-    # ------------------------------------------------------------------
-    # Safe-mode helper (is_previous missing)
-    # ------------------------------------------------------------------
-
-    def _set_safe_mode(self, conn: sqlite3.Connection) -> None:
-        try:
-            row = conn.execute(
-                "SELECT metadata_json FROM learning_model_state "
-                "WHERE profile_id = ? AND is_active = 1",
-                (self._profile_id,),
-            ).fetchone()
-            meta: dict
-            if row is None:
-                meta = {"safe_mode": 1}
-            else:
-                try:
-                    meta = json.loads(row["metadata_json"] or "{}")
-                except (TypeError, ValueError):
-                    meta = {}
-                meta["safe_mode"] = 1
-            conn.execute(
-                "UPDATE learning_model_state SET metadata_json = ? "
-                "WHERE profile_id = ? AND is_active = 1",
-                (json.dumps(meta), self._profile_id),
-            )
-            conn.commit()
-        except sqlite3.Error as exc:  # pragma: no cover — defensive
-            logger.debug("safe_mode set failed: %s", exc)
-
-
-__all__ = ("ModelRollback",)

package/src/superlocalmemory/learning/outcome_queue.py

@@ -1,306 +0,0 @@
-# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
-# Licensed under AGPL-3.0-or-later - see LICENSE file
-# Part of SuperLocalMemory v3.4.22 — Stage 9 DASH-02
-
-"""Background queue for producer-side engagement-reward recording.
-
-**Why this module exists.** Before v3.4.22, ``EngagementRewardModel.record_recall``
-had zero production callers. Every recall path (CLI, MCP, dashboard, daemon
-HTTP) returned results without ever creating a ``pending_outcomes`` row. The
-closed-loop learning pipeline therefore had no producer — its consumers
-(PostToolUse hook, Stop hook, finalize_outcome, action_outcomes, retrain,
-shadow, rollback) were all consuming an empty stream.
-
-This module wires the producer as a non-blocking enqueue + background drain.
-The I1 invariant is absolute — recall wall time must NOT regress. So we:
-
-1. ``enqueue_recall`` is ``queue.put_nowait`` — microseconds.
-2. A single daemon thread drains the queue and calls
-   ``EngagementRewardModel.record_recall`` (one SQLite INSERT per recall).
-3. Queue is bounded; a full queue drops the oldest entry and bumps a
-   counter. Signal quality is NEVER load-bearing on recall correctness.
-
-The worker lives for the daemon's lifetime and is stopped on shutdown
-by ``unified_daemon.py``'s lifespan hook.
-"""
-
-from __future__ import annotations
-
-
-from superlocalmemory.core.session_identity import is_conversation
-import logging
-import queue
-import threading
-from dataclasses import dataclass, field
-from pathlib import Path
-from typing import Optional
-
-logger = logging.getLogger(__name__)
-
-
-# ---------------------------------------------------------------------------
-# Public dataclass — the enqueue payload
-# ---------------------------------------------------------------------------
-
-@dataclass(frozen=True)
-class RecallEvent:
-    """One recall event awaiting pending_outcomes persistence.
-
-    Fields mirror ``EngagementRewardModel.record_recall`` arguments.
-    ``session_id`` is REQUIRED for hook-based signal matching; if the
-    caller can't produce one, pass a stable synthetic like
-    ``f"cli:{os.getpid()}"`` or ``"dashboard:<profile>"``.
-    """
-    session_id: str
-    profile_id: str
-    query: str
-    fact_ids: tuple[str, ...]
-    query_id: str = ""
-
-
-# ---------------------------------------------------------------------------
-# Module state — bounded queue + counters
-# ---------------------------------------------------------------------------
-
-#: S9-DASH-02: cap at 1000 pending recalls. At ~50 ms per row drain, even
-#: a full queue drains in 50 s. Bigger than realistic daemon burst (p99
-#: recalls/sec < 20). Fuller queue → drop oldest, bump counter.
-_MAX_QUEUE = 1000
-
-_queue: "queue.Queue[RecallEvent]" = queue.Queue(maxsize=_MAX_QUEUE)
-_worker_thread: Optional[threading.Thread] = None
-_stop_event = threading.Event()
-_counters: dict[str, int] = {
-    "recall_enqueued": 0,
-    "recall_dropped_queue_full": 0,
-    "recall_persisted": 0,
-    "recall_persist_failed": 0,
-    "recall_reaped": 0,
-}
-_counters_lock = threading.Lock()
-
-
-def _bump(name: str, n: int = 1) -> None:
-    with _counters_lock:
-        _counters[name] = _counters.get(name, 0) + n
-
-
-def get_counters() -> dict[str, int]:
-    """Snapshot of queue counters for dashboards / tests."""
-    with _counters_lock:
-        return dict(_counters)
-
-
-def queue_size() -> int:
-    """Current queue depth (approximate, no lock)."""
-    return _queue.qsize()
-
-
-# ---------------------------------------------------------------------------
-# Public API — called from the recall hot path
-# ---------------------------------------------------------------------------
-
-def enqueue_recall(event: RecallEvent) -> None:
-    """Non-blocking enqueue for later ``record_recall`` persistence.
-
-    Hot-path cost: one ``put_nowait`` — ~1 µs. Drops the event if the
-    queue is full; never raises. Signal quality is not load-bearing on
-    recall correctness (S9-DASH-02 contract).
-    """
-    if not isinstance(event, RecallEvent):
-        return
-    if not event.session_id or not event.profile_id:
-        # S9-DASH-02: session_id is mandatory — hooks key by it.
-        # If the caller can't name a session, we silently drop: this
-        # is a recall whose outcome cannot match to a signal anyway.
-        return
-    if not is_conversation(event.session_id, event.profile_id):
-        # Same reason, one step further. A front that invents an id names
-        # itself, not a caller: ``engine:<pid>`` is the daemon every client
-        # shares, ``cli:<pid>`` a process that exits before any follow-on
-        # action, ``http:<ms>`` a single request. No tool event can ever
-        # carry one, so the outcome is unmatchable the moment it is written.
-        # Recording it anyway is not free: a play that is never settled from
-        # evidence is eventually settled from nothing, and a neutral update
-        # tightens a Beta posterior around its prior instead of leaving it
-        # movable.
-        _bump("recall_dropped_synthetic_session")
-        return
-    try:
-        _queue.put_nowait(event)
-        _bump("recall_enqueued")
-    except queue.Full:
-        # Drop oldest-first so newer recalls always make it in.
-        try:
-            _queue.get_nowait()
-        except queue.Empty:
-            pass
-        try:
-            _queue.put_nowait(event)
-            _bump("recall_dropped_queue_full")
-        except queue.Full:  # pragma: no cover — defensive
-            _bump("recall_dropped_queue_full")
-
-
-# ---------------------------------------------------------------------------
-# Worker — persists to pending_outcomes
-# ---------------------------------------------------------------------------
-
-def _drain_once(memory_db_path: Path, max_batch: int = 50) -> int:
-    """Drain up to ``max_batch`` events, persisting each via
-    ``EngagementRewardModel.record_recall``. Returns count persisted.
-    """
-    from superlocalmemory.learning.reward import EngagementRewardModel
-
-    model = EngagementRewardModel(memory_db_path)
-    persisted = 0
-    try:
-        for _ in range(max_batch):
-            try:
-                event = _queue.get_nowait()
-            except queue.Empty:
-                break
-            try:
-                model.record_recall(
-                    profile_id=event.profile_id,
-                    session_id=event.session_id,
-                    recall_query_id=event.query_id or "",
-                    fact_ids=list(event.fact_ids),
-                    query_text=event.query,
-                )
-                _bump("recall_persisted")
-                persisted += 1
-            except Exception as exc:
-                _bump("recall_persist_failed")
-                logger.debug(
-                    "outcome_queue: record_recall failed: %s (session=%s)",
-                    exc, event.session_id,
-                )
-    finally:
-        try:
-            model.close()
-        except Exception:
-            pass
-    return persisted
-
-
-#: S9-DASH-02: reaper cadence — force-finalize pending_outcomes older
-#: than this so CLI/dashboard recalls (no Stop hook) still land in
-#: action_outcomes with a neutral reward. One hour keeps slow-moving
-#: interactive sessions alive while still draining abandoned recalls.
-_REAP_INTERVAL_S = 300.0  # check every 5 minutes
-_REAP_AGE_MS = 3_600_000  # 1 hour
-
-
-def _reap_stale(memory_db_path: Path) -> int:
-    """Force-finalize pending_outcomes older than ``_REAP_AGE_MS``.
-
-    Uses ``EngagementRewardModel.reap_stale`` which computes the label
-    from whatever signals accumulated (``0.5`` if none, which is the
-    intended neutral for CLI/dashboard recalls without hook coverage).
-    """
-    try:
-        from superlocalmemory.learning.reward import EngagementRewardModel
-        model = EngagementRewardModel(memory_db_path)
-        try:
-            return int(model.reap_stale(older_than_ms=_REAP_AGE_MS))
-        finally:
-            try:
-                model.close()
-            except Exception:
-                pass
-    except Exception as exc:  # pragma: no cover — defensive
-        logger.debug("reap_stale failed: %s", exc)
-        return 0
-
-
-def _worker_loop(memory_db_path: Path, interval_s: float) -> None:
-    logger.info(
-        "outcome_queue worker started (db=%s interval=%.2fs)",
-        memory_db_path, interval_s,
-    )
-    import time as _time
-    next_reap = _time.monotonic() + _REAP_INTERVAL_S
-    # Adaptive idle back-off: poll at interval_s under load, but relax the wait
-    # (doubling, capped) when the queue drains empty so an idle daemon stops
-    # contending on the shared SQLite file every 0.25s (issue #53). Snaps back
-    # to interval_s the instant there is work again.
-    _idle_cap = max(interval_s, 2.0)
-    cur_wait = interval_s
-    while not _stop_event.wait(cur_wait):
-        try:
-            drained = _drain_once(memory_db_path)
-        except Exception as exc:  # pragma: no cover — defensive
-            logger.warning("outcome_queue drain crashed: %s", exc)
-            drained = 0
-        cur_wait = interval_s if drained else min(cur_wait * 2.0, _idle_cap)
-        # Periodic reaper for CLI/dashboard outcomes that no Stop hook
-        # will ever finalize. Runs OFF the drain path so a busy queue
-        # doesn't starve the reaper.
-        now = _time.monotonic()
-        if now >= next_reap:
-            try:
-                reaped = _reap_stale(memory_db_path)
-                if reaped:
-                    logger.info(
-                        "outcome_queue reaper: finalized %d stale rows",
-                        reaped,
-                    )
-                _bump("recall_reaped", reaped)
-            except Exception:  # pragma: no cover
-                pass
-            next_reap = now + _REAP_INTERVAL_S
-    # Final drain on graceful shutdown.
-    try:
-        _drain_once(memory_db_path, max_batch=1000)
-    except Exception:
-        pass
-    logger.info("outcome_queue worker stopped")
-
-
-def start_worker(memory_db_path: Path, *, interval_s: float = 0.25) -> None:
-    """Start the drain thread (idempotent)."""
-    global _worker_thread
-    if _worker_thread is not None and _worker_thread.is_alive():
-        return
-    _stop_event.clear()
-    _worker_thread = threading.Thread(
-        target=_worker_loop,
-        args=(Path(memory_db_path), interval_s),
-        name="slm-outcome-queue",
-        daemon=True,
-    )
-    _worker_thread.start()
-
-
-def stop_worker(*, timeout_s: float = 2.0) -> int:
-    """Signal the worker to stop and wait up to ``timeout_s`` for flush."""
-    global _worker_thread
-    _stop_event.set()
-    if _worker_thread is not None and _worker_thread.is_alive():
-        _worker_thread.join(timeout=timeout_s)
-    remaining = _queue.qsize()
-    _worker_thread = None
-    return remaining
-
-
-# ---------------------------------------------------------------------------
-# Test helpers
-# ---------------------------------------------------------------------------
-
-def _reset_for_testing() -> None:
-    """TEST-ONLY: drain queue and zero counters. Never called in prod."""
-    global _worker_thread
-    _stop_event.set()
-    if _worker_thread is not None and _worker_thread.is_alive():
-        _worker_thread.join(timeout=1.0)
-    _worker_thread = None
-    while True:
-        try:
-            _queue.get_nowait()
-        except queue.Empty:
-            break
-    with _counters_lock:
-        for k in _counters:
-            _counters[k] = 0
-    _stop_event.clear()