superlocalmemory 3.4.19 → 3.4.21

package/src/superlocalmemory/learning/ensemble.py

@@ -0,0 +1,300 @@
+# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
+# Licensed under AGPL-3.0-or-later - see LICENSE file
+# Part of SuperLocalMemory v3.4.21 — LLD-03 §5.4
+
+"""Bandit / LightGBM ensemble blender.
+
+LLD reference: ``.backup/active-brain/lld/LLD-03-contextual-bandit-and-ensemble.md``
+Section 5.4.
+
+D8 blend policy (``choose_ensemble``):
+  - 0..199 signals OR model is None → ``EnsembleWeights(1.0, 0.0)`` (bandit-only).
+  - 200..499 signals + model         → ``EnsembleWeights(0.4, 0.6)`` (warm blend).
+  - 500+ signals + model             → ``EnsembleWeights(0.2, 0.8)`` (mature).
+
+Hard rules:
+  - E1: ``bandit + lgbm == 1.0`` — asserted at construction.
+  - E2: ``booster.predict`` called exactly ONCE per rerank (batched).
+  - E3: no predict call when ``lgbm_weight == 0.0`` or ``model is None``.
+  - E4: both score streams normalised to [0, 1] before blending.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from dataclasses import dataclass
+from typing import Any, Sequence
+
+logger = logging.getLogger(__name__)
+
+
+# Thresholds come from env for ops-time override; defaults match LLD-03 §10.
+_MIN_SIGNALS = int(os.environ.get("SLM_ENSEMBLE_LGBM_MIN_SIGNALS", "200"))
+_DOMINANT_SIGNALS = int(
+    os.environ.get("SLM_ENSEMBLE_DOMINANT_MIN_SIGNALS", "500")
+)
+
+
+def _parse_blend(value: str, fallback: tuple[float, float]) -> tuple[float, float]:
+    """Parse 'bandit:lgbm' env var into a (bandit, lgbm) tuple."""
+    try:
+        a_s, b_s = value.split(":", 1)
+        a, b = float(a_s), float(b_s)
+        if abs((a + b) - 1.0) > 1e-6:
+            return fallback
+        return (a, b)
+    except (ValueError, AttributeError):
+        return fallback
+
+
+_WARM = _parse_blend(
+    os.environ.get("SLM_ENSEMBLE_BLEND_WARM", "0.4:0.6"), (0.4, 0.6),
+)
+_MATURE = _parse_blend(
+    os.environ.get("SLM_ENSEMBLE_BLEND_MATURE", "0.2:0.8"), (0.2, 0.8),
+)
+
+
+# ---------------------------------------------------------------------------
+# EnsembleWeights
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True, slots=True)
+class EnsembleWeights:
+    """Blend weights for the bandit/LGBM ensemble.
+
+    E1: ``bandit + lgbm`` must equal 1.0 (±1e-6 float tolerance).
+    """
+
+    bandit: float
+    lgbm: float
+
+    def __post_init__(self) -> None:
+        total = self.bandit + self.lgbm
+        if abs(total - 1.0) > 1e-6:
+            raise AssertionError(
+                f"EnsembleWeights must sum to 1.0, got {total}"
+            )
+        if self.bandit < 0.0 or self.lgbm < 0.0:
+            raise AssertionError(
+                f"EnsembleWeights must be non-negative, got "
+                f"bandit={self.bandit}, lgbm={self.lgbm}"
+            )
+
+
+def choose_ensemble(
+    signal_count: int,
+    model: Any | None,
+) -> EnsembleWeights:
+    """Select bandit/LGBM blend per D8.
+
+    ``model`` is typed ``Any`` to avoid importing ``ActiveModel`` at module
+    load; in practice it's an ``ActiveModel | None``. Only ``model is None``
+    is checked.
+    """
+    try:
+        count = int(signal_count)
+    except (TypeError, ValueError):
+        count = 0
+    if model is None or count < _MIN_SIGNALS:
+        return EnsembleWeights(1.0, 0.0)
+    if count < _DOMINANT_SIGNALS:
+        return EnsembleWeights(_WARM[0], _WARM[1])
+    return EnsembleWeights(_MATURE[0], _MATURE[1])
+
+
+# ---------------------------------------------------------------------------
+# Scoring helpers
+# ---------------------------------------------------------------------------
+
+
+def _softmax_unit(scores: Sequence[float]) -> list[float]:
+    """Normalise a score stream to [0, 1] via softmax, numerically stable.
+
+    Preserves ordering. Returns uniform 1/N when all scores are identical.
+    """
+    if not scores:
+        return []
+    xs = list(scores)
+    n = len(xs)
+    m = max(xs)
+    # Subtract max for numerical stability before exp.
+    exps = []
+    for v in xs:
+        try:
+            exps.append(pow(2.718281828459045, v - m))
+        except OverflowError:  # pragma: no cover — m subtraction avoids this
+            exps.append(0.0)
+    total = sum(exps)
+    if total <= 0.0:  # pragma: no cover — defensive
+        return [1.0 / n] * n
+    return [e / total for e in exps]
+
+
+def _apply_weights_score(candidate: Any, weights: dict[str, float]) -> float:
+    """Compute a scalar bandit score for a candidate under the arm weights.
+
+    Input shape: candidate has either ``.channel_scores`` attr OR ``score``.
+    For v3.4.21 the bandit-only path simply uses the already-weighted ordering
+    from ``apply_channel_weights``; this helper only matters when we blend.
+    """
+    # Prefer pre-weighted score on the object.
+    score = getattr(candidate, "score", None)
+    if score is None and isinstance(candidate, dict):
+        score = candidate.get("score")
+    if score is None:
+        # Fallback: sum channel contributions × weights.
+        cs = getattr(candidate, "channel_scores", None)
+        if cs is None and isinstance(candidate, dict):
+            cs = candidate.get("channel_scores", {}) or {}
+        cs = cs or {}
+        score = sum(
+            float(cs.get(name, 0.0)) * float(weights.get(name, 1.0))
+            for name in ("semantic", "bm25", "entity_graph", "temporal")
+        )
+        ce = None
+        if hasattr(candidate, "cross_encoder_score"):
+            ce = getattr(candidate, "cross_encoder_score", None)
+        elif isinstance(candidate, dict):
+            ce = candidate.get("cross_encoder_score")
+        if ce is not None:
+            score += float(ce) * float(
+                weights.get("cross_encoder_bias", 1.0)
+            )
+    try:
+        return float(score)
+    except (TypeError, ValueError):
+        return 0.0
+
+
+# ---------------------------------------------------------------------------
+# ensemble_rerank
+# ---------------------------------------------------------------------------
+
+
+def ensemble_rerank(
+    candidates: list[Any],
+    bandit_choice: Any,
+    model: Any | None,
+    weights: EnsembleWeights,
+    query_context: dict[str, Any],
+) -> list[Any]:
+    """Blend bandit + LGBM scores and reorder candidates.
+
+    E2: ``booster.predict`` called at most ONCE, via a single batched input.
+    E3: short-circuits when ``weights.lgbm == 0.0`` or ``model is None``.
+    E4: softmax-unit normalisation per stream before blending.
+
+    Never raises. On error (import / predict), returns input unchanged.
+    """
+    if not candidates:
+        return candidates
+
+    # E3: short-circuit.
+    if weights.lgbm == 0.0 or model is None:
+        return list(candidates)
+
+    try:
+        import numpy as np  # noqa: PLC0415 — optional heavy dep
+    except ImportError:  # pragma: no cover — optional
+        logger.debug("ensemble_rerank: numpy unavailable; bandit-only path")
+        return list(candidates)
+
+    # Lazy import so the unit tests don't require lightgbm at import time.
+    try:
+        from superlocalmemory.learning.features import FeatureExtractor
+    except ImportError:  # pragma: no cover — defensive
+        return list(candidates)
+
+    # Build batch feature matrix ONCE. PERF-v2-02: also stash a
+    # ``{fact_id: features_json}`` dict on ``query_context`` under the
+    # reserved key ``_precomputed_features_json`` so the downstream
+    # signal_worker (which would otherwise call ``FeatureExtractor.extract``
+    # again when recording signals) can reuse this work. No schema change;
+    # purely a caller-opt-in cache the signal writer probes.
+    try:
+        import json as _json  # noqa: PLC0415 — local import keeps hot-path clean
+
+        rows = []
+        feats_cache: dict[str, str] = {}
+        for c in candidates:
+            result = _candidate_to_result(c)
+            fv = FeatureExtractor.extract(result, query_context)
+            rows.append(fv.to_list())
+            fid = getattr(c, "fact_id", None) or result.get("fact_id", "")
+            if fid:
+                feats_cache[fid] = _json.dumps(
+                    fv.features, separators=(",", ":"),
+                )
+        X = np.asarray(rows, dtype=np.float32)
+        if isinstance(query_context, dict) and feats_cache:
+            # Merge into caller's dict; do not clobber a pre-existing cache.
+            existing = query_context.get("_precomputed_features_json") or {}
+            if isinstance(existing, dict):
+                merged = {**existing, **feats_cache}
+                query_context["_precomputed_features_json"] = merged
+    except Exception as exc:
+        logger.debug("ensemble_rerank: feature build failed: %s", exc)
+        return list(candidates)
+
+    # E2: single batched predict call.
+    booster = getattr(model, "booster", None)
+    if booster is None or not hasattr(booster, "predict"):
+        return list(candidates)
+    try:
+        lgbm_scores = booster.predict(X)
+    except Exception as exc:
+        logger.warning("ensemble_rerank: predict failed: %s", exc)
+        return list(candidates)
+    try:
+        lgbm_scores = list(map(float, lgbm_scores))
+    except (TypeError, ValueError):  # pragma: no cover — defensive
+        return list(candidates)
+
+    arm_weights = (
+        bandit_choice.weights if hasattr(bandit_choice, "weights") else {}
+    )
+    bandit_scores = [
+        _apply_weights_score(c, arm_weights) for c in candidates
+    ]
+
+    # E4: normalise each stream to [0, 1] via softmax before blending.
+    n_lgbm = _softmax_unit(lgbm_scores)
+    n_bandit = _softmax_unit(bandit_scores)
+
+    blended = [
+        weights.bandit * b + weights.lgbm * l
+        for b, l in zip(n_bandit, n_lgbm)
+    ]
+
+    # Stable-sort descending so equal scores preserve original order.
+    indexed = list(enumerate(candidates))
+    indexed.sort(key=lambda pair: -blended[pair[0]])
+    return [c for _, c in indexed]
+
+
+def _candidate_to_result(c: Any) -> dict[str, Any]:
+    """Coerce a candidate (dict / dataclass / ORM row) to a feature result."""
+    if isinstance(c, dict):
+        return c
+    if hasattr(c, "to_result_dict") and callable(c.to_result_dict):
+        try:
+            return c.to_result_dict()
+        except Exception:  # pragma: no cover — defensive
+            pass
+    # Last resort: assemble from common attributes.
+    return {
+        "fact_id": getattr(c, "fact_id", ""),
+        "score": getattr(c, "score", 0.0),
+        "channel_scores": getattr(c, "channel_scores", {}) or {},
+        "cross_encoder_score": getattr(c, "cross_encoder_score", None),
+    }
+
+
+__all__ = (
+    "EnsembleWeights",
+    "choose_ensemble",
+    "ensemble_rerank",
+)

package/src/superlocalmemory/learning/fact_outcome_joins.py

@@ -0,0 +1,207 @@
+# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
+# Licensed under AGPL-3.0-or-later - see LICENSE file
+# Part of SuperLocalMemory v3.4.21 — F4.A Stage-8 H-03/H-06 fix
+
+"""Parameterised JSON1-backed join helpers for ``action_outcomes``.
+
+Replaces the fragile ``fact_ids_json LIKE '%"<fid>"%'`` pattern that five
+call sites depended on. Substring matching on serialised JSON leaks
+false positives across overlapping fact_id prefixes — see Stage-8
+skeptic-H06 for the exact failure mode.
+
+This module centralises the correct lookup:
+
+    SELECT outcome_id, ... FROM action_outcomes
+    WHERE profile_id = ?
+      AND EXISTS (
+          SELECT 1 FROM json_each(fact_ids_json) WHERE value = ?
+      )
+
+SQLite ships JSON1 enabled by default since 3.38 (February 2022) and the
+minimum Python supported by SLM is 3.9 — which ships SQLite ≥ 3.31. We
+defensively fall back to a ``LIKE`` probe only when JSON1 is missing at
+runtime, with a one-off warning.
+
+Callers:
+  - ``learning/hnsw_dedup.py`` — ``apply_strong_memory_boost``,
+    ``select_high_reward_fact_ids``, ``run_reward_gated_archive``.
+  - ``learning/forgetting_scheduler.py`` — ``_has_recent_positive_reward``.
+
+Contract refs:
+  - Stage 8 H-03 (architect-H3) + H-06 (skeptic-H06).
+  - LLD-12 §5 — reward-gated archive.
+"""
+
+from __future__ import annotations
+
+import logging
+import sqlite3
+from typing import Iterable
+
+logger = logging.getLogger(__name__)
+
+__all__ = (
+    "iter_outcomes_for_fact",
+    "has_recent_positive_reward",
+    "aggregate_reward_for_fact",
+)
+
+
+# Columns returned — mirror what the legacy LIKE callers read.
+# NB: callers that need extra columns can pass ``columns=``.
+_DEFAULT_COLUMNS = "outcome_id, profile_id, fact_ids_json, reward, settled_at"
+
+
+def _json1_available(conn: sqlite3.Connection) -> bool:
+    """Return True iff SQLite ``json_each`` is usable on ``conn``.
+
+    Result is intentionally not cached across connections — JSON1 is a
+    compile-time flag and runtime-swapping SQLite libraries is a rare
+    edge case but we stay defensive.
+    """
+    try:
+        conn.execute("SELECT value FROM json_each('[\"x\"]') LIMIT 1").fetchall()
+        return True
+    except sqlite3.OperationalError:
+        return False
+
+
+def iter_outcomes_for_fact(
+    conn: sqlite3.Connection,
+    profile_id: str,
+    fact_id: str,
+    *,
+    columns: str = _DEFAULT_COLUMNS,
+    extra_where: str = "",
+    extra_params: tuple = (),
+) -> Iterable[tuple]:
+    """Yield action_outcomes rows whose fact_ids_json contains ``fact_id``.
+
+    Scoped strictly to ``profile_id``; SQL parameters are always bound,
+    never string-interpolated. Returns a materialised list so the caller
+    can close the connection immediately.
+
+    Args:
+        conn: SQLite connection pointing at the database holding the
+            ``action_outcomes`` table (usually ``memory.db``).
+        profile_id: Profile scope.
+        fact_id: Exact fact_id to find.
+        columns: Comma-separated column list projected into the
+            SELECT. Defaults to (outcome_id, profile_id, fact_ids_json,
+            reward, settled_at).
+        extra_where: Optional extra predicate — must start with 'AND'
+            and use '?' placeholders. E.g.
+            ``"AND reward IS NOT NULL AND reward > ?"``.
+        extra_params: Bound parameters for ``extra_where``.
+
+    Returns:
+        List of sqlite3.Row-compatible tuples (or sqlite3.Row objects if
+        the caller set ``conn.row_factory = sqlite3.Row``).
+    """
+    if not profile_id or not fact_id:
+        return []
+
+    if _json1_available(conn):
+        sql = (
+            f"SELECT {columns} FROM action_outcomes "
+            f"WHERE profile_id = ? "
+            f"  AND EXISTS ("
+            f"    SELECT 1 FROM json_each(fact_ids_json) WHERE value = ?"
+            f"  ) "
+            f"{extra_where}"
+        )
+        params = (profile_id, fact_id, *extra_params)
+    else:
+        # Fallback: prefix-LIKE. Accurate ONLY for simple ids.
+        # Logged once per process to flag that JSON1 is missing.
+        _warn_fallback_once()
+        sql = (
+            f"SELECT {columns} FROM action_outcomes "
+            f"WHERE profile_id = ? AND fact_ids_json LIKE ? "
+            f"{extra_where}"
+        )
+        params = (profile_id, f'%"{fact_id}"%', *extra_params)
+
+    cursor = conn.execute(sql, params)
+    return cursor.fetchall()
+
+
+def has_recent_positive_reward(
+    conn: sqlite3.Connection,
+    profile_id: str,
+    fact_id: str,
+    *,
+    min_reward: float = 0.3,
+    window_days: int = 60,
+) -> bool:
+    """True if ``fact_id`` has any outcome with reward > ``min_reward``
+    settled in the last ``window_days`` days.
+    """
+    extra = (
+        "AND reward IS NOT NULL AND reward > ? "
+        f"AND COALESCE(settled_at, '') >= datetime('now', '-{int(window_days)} days') "
+        "LIMIT 1"
+    )
+    rows = iter_outcomes_for_fact(
+        conn, profile_id, fact_id,
+        columns="1",
+        extra_where=extra,
+        extra_params=(float(min_reward),),
+    )
+    return bool(rows)
+
+
+def aggregate_reward_for_fact(
+    conn: sqlite3.Connection,
+    profile_id: str,
+    fact_id: str,
+) -> tuple[int, float]:
+    """Return ``(count, mean_reward)`` for a single fact_id.
+
+    Count is the number of outcomes with reward IS NOT NULL; mean is
+    ``AVG(reward)`` across that same subset. Returns ``(0, 0.0)`` when
+    the fact has no outcomes.
+    """
+    if not profile_id or not fact_id:
+        return 0, 0.0
+
+    if _json1_available(conn):
+        sql = (
+            "SELECT COUNT(*), AVG(reward) FROM action_outcomes "
+            "WHERE profile_id = ? "
+            "  AND reward IS NOT NULL "
+            "  AND EXISTS ("
+            "    SELECT 1 FROM json_each(fact_ids_json) WHERE value = ?"
+            "  )"
+        )
+        row = conn.execute(sql, (profile_id, fact_id)).fetchone()
+    else:
+        _warn_fallback_once()
+        sql = (
+            "SELECT COUNT(*), AVG(reward) FROM action_outcomes "
+            "WHERE profile_id = ? "
+            "  AND reward IS NOT NULL "
+            "  AND fact_ids_json LIKE ?"
+        )
+        row = conn.execute(sql, (profile_id, f'%"{fact_id}"%')).fetchone()
+
+    if row is None:
+        return 0, 0.0
+    count, mean = row
+    return int(count or 0), float(mean or 0.0)
+
+
+_FALLBACK_WARNED = False
+
+
+def _warn_fallback_once() -> None:
+    """Log the JSON1-missing fallback exactly once per process."""
+    global _FALLBACK_WARNED
+    if _FALLBACK_WARNED:
+        return
+    _FALLBACK_WARNED = True
+    logger.warning(
+        "fact_outcome_joins: SQLite JSON1 unavailable — falling back to "
+        "prefix-LIKE. Expect substring false positives on overlapping "
+        "fact_id prefixes. Upgrade SQLite to ≥3.38 for correct matches.",
+    )

package/src/superlocalmemory/learning/forgetting_scheduler.py

@@ -306,10 +306,65 @@ class ForgettingScheduler:
     def _soft_delete_with_audit(self, fact_id: str, profile_id: str) -> None:
         """Soft-delete a forgotten fact with compliance audit trail.
 
+        v3.4.21 (LLD-12 §4): reward-gated. If the fact has any positive
+        reward (>0.3) in the last 60 days, it is considered "still
+        useful" and kept live — consolidation will retry next cycle.
+
         HR-04: Never physically deletes.
         """
+        if self._has_recent_positive_reward(fact_id, profile_id):
+            logger.debug(
+                "forgetting_scheduler: fact_id=%s kept live (recent reward)",
+                fact_id,
+            )
+            return
         logger.info(
             "Soft-deleting forgotten fact: fact_id=%s, profile_id=%s",
             fact_id, profile_id,
         )
         self._db.soft_delete_fact(fact_id, profile_id)
+
+    def _has_recent_positive_reward(
+        self, fact_id: str, profile_id: str,
+    ) -> bool:
+        """True if fact has an outcome_reward > 0.3 in the last 60 days.
+
+        v3.4.21 (Stage 8 H-06): routes through the JSON1-backed
+        ``fact_outcome_joins.has_recent_positive_reward`` helper —
+        eliminates the substring-LIKE false-positive class.
+
+        Resilient to schema drift: if ``action_outcomes`` or its columns
+        are unavailable we return False (no gating), preserving legacy
+        behaviour.
+        """
+        try:
+            # ``DatabaseManager`` is the owner of a persistent sqlite
+            # connection; the JSON1 helper needs a raw connection. We
+            # fall through to the legacy execute-path if the DB wrapper
+            # does not expose a ``.conn`` handle.
+            raw_conn = getattr(self._db, "conn", None) or getattr(
+                self._db, "_conn", None,
+            )
+            if raw_conn is not None:
+                from superlocalmemory.learning.fact_outcome_joins import (
+                    has_recent_positive_reward,
+                )
+                return has_recent_positive_reward(
+                    raw_conn, profile_id, fact_id,
+                    min_reward=0.3, window_days=60,
+                )
+            # Fallback: use the DB wrapper with JSON1 SQL inline.
+            rows = self._db.execute(
+                "SELECT 1 FROM action_outcomes "
+                "WHERE profile_id = ? "
+                "  AND reward IS NOT NULL AND reward > 0.3 "
+                "  AND EXISTS ("
+                "    SELECT 1 FROM json_each(fact_ids_json) WHERE value = ?"
+                "  ) "
+                "  AND COALESCE(settled_at, '') >= datetime('now', '-60 days') "
+                "LIMIT 1",
+                (profile_id, fact_id),
+            )
+            return bool(rows)
+        except Exception:
+            return False

package/src/superlocalmemory/learning/hnsw_dedup.py

@@ -0,0 +1,69 @@
+# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
+# Licensed under AGPL-3.0-or-later - see LICENSE file
+# Part of SuperLocalMemory v3.4.21 — F4.A Stage-8 H-03/H-17/H-18 shim
+
+"""HNSW dedup + reward-gated archive + strong-memory boost — shim.
+
+As of v3.4.21 (Stage 8 H-03/H-17/H-18 fixes), the 535-LOC god-module
+was split into three cohesive files:
+
+  - ``dedup_hnsw.py``     — :class:`HnswDeduplicator` + fallback counter.
+  - ``reward_archive.py`` — :func:`run_reward_gated_archive`.
+  - ``reward_boost.py``   — :func:`apply_strong_memory_boost`,
+                            :func:`select_high_reward_fact_ids`.
+
+Outcome lookups that used to issue ``fact_ids_json LIKE`` now go
+through :mod:`superlocalmemory.learning.fact_outcome_joins` which wraps
+SQLite JSON1 so overlapping fact_id prefixes cannot collide (H-06).
+
+This shim re-exports the original surface so that existing imports
+continue to work unchanged.
+"""
+
+from __future__ import annotations
+
+import logging
+
+from superlocalmemory.core.ram_lock import ram_reservation  # noqa: F401
+
+from superlocalmemory.learning.dedup_hnsw import (  # noqa: F401
+    HnswDeduplicator,
+    get_hnsw_degraded_count,
+    reset_hnsw_degraded_count,
+    _cosine,
+    _jaccard,
+    _parse_embedding,
+    _pick_canonical,
+)
+from superlocalmemory.learning.reward_archive import (  # noqa: F401
+    ARCHIVE_REWARD_THRESHOLD,
+    REWARD_WINDOW_DAYS,
+    run_reward_gated_archive,
+)
+from superlocalmemory.learning.reward_boost import (  # noqa: F401
+    STRONG_BOOST_CAP,
+    STRONG_BOOST_INCREMENT,
+    STRONG_BOOST_MIN_MEAN,
+    STRONG_BOOST_MIN_OUTCOMES,
+    apply_strong_memory_boost,
+    select_high_reward_fact_ids,
+)
+
+logger = logging.getLogger(__name__)
+
+
+__all__ = (
+    "HnswDeduplicator",
+    "run_reward_gated_archive",
+    "apply_strong_memory_boost",
+    "select_high_reward_fact_ids",
+    "get_hnsw_degraded_count",
+    "reset_hnsw_degraded_count",
+    "REWARD_WINDOW_DAYS",
+    "ARCHIVE_REWARD_THRESHOLD",
+    "STRONG_BOOST_INCREMENT",
+    "STRONG_BOOST_CAP",
+    "STRONG_BOOST_MIN_OUTCOMES",
+    "STRONG_BOOST_MIN_MEAN",
+    "ram_reservation",
+)