superlocalmemory 4.1.13 → 4.1.14

package/src/superlocalmemory/learning/propensity.py

@@ -1,131 +0,0 @@
-# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
-# Licensed under AGPL-3.0-or-later - see LICENSE file
-
-"""Inverse-propensity weighting, so the bandit cannot confirm itself.
-
-THE BIAS
---------
-The bandit decides what is shown, and engagement is then measured on what was
-shown. Feed that back raw and the loop is circular: an arm ranked first is seen
-more, so it is engaged with more, so it is ranked first more. The arm that wins
-is the one that was already winning, and the posterior records popularity it
-manufactured rather than usefulness it discovered.
-
-That is the self-referential signal in its exact form — a measurement taken
-through the mechanism it is meant to evaluate cannot see that mechanism fail.
-
-THE CORRECTION
---------------
-Weight each observation by the inverse of the probability the policy had of
-showing that arm. An arm the policy was unlikely to show, that was engaged with
-anyway, is strong evidence; an arm the policy shows almost always is weak
-evidence whatever happens to it. This is the standard IPS estimator from
-counterfactual learning-to-rank, and it makes the update unbiased with respect
-to the policy's own choices.
-
-Under Thompson sampling the propensity is not a stored number: an arm is shown
-when its posterior draw beats every competitor's, so the probability is
-``P(theta_i > theta_j for all j != i)`` with each ``theta ~ Beta(alpha, beta)``.
-There is no closed form for more than two arms, so it is estimated by sampling.
-
-WHEN THE COMPETITORS ARE UNKNOWN
---------------------------------
-Return a weight of exactly 1.0 — no correction. A wrong correction is worse
-than none: it would silently scale evidence by a number with no meaning, and
-unlike an absent correction nothing downstream could tell. Abstaining from a
-correction is visible in ``PropensityEstimate.corrected``.
-"""
-
-from __future__ import annotations
-
-import random
-from dataclasses import dataclass
-
-__all__ = ["PropensityEstimate", "estimate_propensity", "ips_weight", "MAX_WEIGHT"]
-
-#: Ceiling on the weight a single observation may carry. IPS has unbounded
-#: variance as propensity approaches zero: one rare event with p = 0.001 would
-#: otherwise move a posterior by 1000 plays' worth. Clipping trades a little
-#: bias for a variance that does not destroy the estimate — the standard
-#: bias-variance trade in clipped IPS.
-MAX_WEIGHT = 10.0
-
-#: Propensities below this are treated as this value before inversion.
-_MIN_PROPENSITY = 1.0 / MAX_WEIGHT
-
-#: Monte Carlo draws. 2000 puts the standard error of a mid-range propensity
-#: near 0.01, which is finer than the weight clipping can express.
-_DRAWS = 2000
-
-
-@dataclass(frozen=True)
-class PropensityEstimate:
-    """A propensity and whether it was actually derived from anything."""
-
-    propensity: float
-    weight: float
-    corrected: bool
-    competitors: int = 0
-
-
-def estimate_propensity(
-    arm: tuple[float, float],
-    competitors: list[tuple[float, float]],
-    *,
-    draws: int = _DRAWS,
-    rng: random.Random | None = None,
-) -> float:
-    """P(this arm's Thompson draw is the largest), by Monte Carlo.
-
-    ``arm`` and each competitor are ``(alpha, beta)`` posteriors.  With no
-    competitors the arm is shown whenever it is considered, so the propensity
-    is 1.0 and the correction is a no-op.
-    """
-    if not competitors:
-        return 1.0
-    # Fixed seed by default: the same play settled twice must produce the
-    # same weight, or a retry would move a posterior differently than the
-    # first attempt did.
-    generator = rng or random.Random(20260824)
-    alpha, beta = _sane(arm)
-    others = [_sane(c) for c in competitors]
-
-    wins = 0
-    for _ in range(max(1, int(draws))):
-        mine = generator.betavariate(alpha, beta)
-        if all(mine > generator.betavariate(a, b) for a, b in others):
-            wins += 1
-    return wins / max(1, int(draws))
-
-
-def _sane(posterior: tuple[float, float]) -> tuple[float, float]:
-    """Beta requires strictly positive parameters; a stored 0 would raise."""
-    alpha, beta = posterior
-    return (max(float(alpha), 1e-6), max(float(beta), 1e-6))
-
-
-def ips_weight(
-    arm: tuple[float, float] | None,
-    competitors: list[tuple[float, float]] | None,
-    *,
-    draws: int = _DRAWS,
-    rng: random.Random | None = None,
-) -> PropensityEstimate:
-    """Clipped inverse-propensity weight for one observation.
-
-    Returns ``corrected=False`` and ``weight=1.0`` when there is nothing to
-    correct against, so a caller can tell an uncorrected update from a
-    corrected one that happened to land on 1.0.
-    """
-    if arm is None or not competitors:
-        return PropensityEstimate(propensity=1.0, weight=1.0, corrected=False)
-
-    propensity = estimate_propensity(arm, competitors, draws=draws, rng=rng)
-    clipped = max(propensity, _MIN_PROPENSITY)
-    weight = min(1.0 / clipped, MAX_WEIGHT)
-    return PropensityEstimate(
-        propensity=propensity,
-        weight=weight,
-        corrected=True,
-        competitors=len(competitors),
-    )

package/src/superlocalmemory/learning/ranker.py

@@ -1,300 +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
-
-"""3-phase adaptive ranker — from heuristic to ML.
-
-
-Phase 1: cross-encoder score only (cold start)
-Phase 2: heuristic boosts (some data)
-Phase 3: LightGBM **lambdarank** Booster (native, not LGBMRanker sklearn
-         wrapper) scoring on numpy feature matrices.
-
-Transitions are automatic based on accumulated training data. Feature-name
-drift is handled per LLD-02 §4.5 (``drift_mode``):
-    - ``aligned`` — score normally.
-    - ``subset``  — pad missing features with 0.0 in FEATURE_NAMES order.
-    - ``unknown`` — refuse to score; fall back to pre-model order.
-"""
-
-from __future__ import annotations
-
-import logging
-import math
-from typing import Any
-
-from superlocalmemory.learning.features import (
-    FEATURE_DIM,
-    FEATURE_NAMES,
-    FeatureExtractor,
-    FeatureVector,
-)
-
-logger = logging.getLogger(__name__)
-
-# Phase thresholds
-PHASE_2_THRESHOLD = 50   # signals needed to enter Phase 2
-PHASE_3_THRESHOLD = 200  # signals needed to enter Phase 3
-
-
-class AdaptiveRanker:
-    """3-phase adaptive re-ranker for V3 retrieval results."""
-
-    def __init__(
-        self,
-        signal_count: int = 0,
-        model_state: bytes | None = None,
-        *,
-        active_model: Any = None,
-    ) -> None:
-        """Build a ranker.
-
-        ``active_model`` (``model_cache.ActiveModel``) is preferred when
-        available — it carries verified booster + feature_names. The legacy
-        ``model_state`` bytes path remains for backward compatibility with
-        3.4.20 callers; it does NOT perform SHA-256 verification and should
-        not be used by the 3.4.22 recall path.
-        """
-        self._signal_count = signal_count
-        self._active = active_model
-        # Back-compat: only fill in from raw bytes when no active_model given.
-        if active_model is None and model_state:
-            self._load_legacy_bytes(model_state)
-
-    # --- public properties ---------------------------------------------
-
-    @property
-    def phase(self) -> int:
-        if self._signal_count >= PHASE_3_THRESHOLD and self._active is not None:
-            return 3
-        if self._signal_count >= PHASE_2_THRESHOLD:
-            return 2
-        return 1
-
-    @property
-    def signal_count(self) -> int:
-        return self._signal_count
-
-    @signal_count.setter
-    def signal_count(self, value: int) -> None:
-        self._signal_count = value
-
-    @property
-    def active_model(self) -> Any:
-        return self._active
-
-    # --- re-rank entry points ------------------------------------------
-
-    def rerank(self, results: list[dict], query_context: dict) -> list[dict]:
-        """Re-rank retrieval results based on current phase."""
-        if not results:
-            return results
-
-        if self.phase == 3:
-            return self._rerank_ml(results, query_context)
-        if self.phase == 2:
-            return self._rerank_heuristic(results, query_context)
-        return self._rerank_baseline(results)
-
-    def rank(self, candidates: list, query_context: dict) -> list:
-        """LLD-02 §4.5 native inference path.
-
-        Accepts an iterable of objects that implement ``to_result_dict()``
-        (the signal-pipeline candidates) AND plain dicts (legacy).
-        """
-        if self._active is None or not candidates:
-            return list(candidates)
-
-        # Build result dicts in a uniform shape.
-        result_dicts: list[dict] = []
-        for c in candidates:
-            if hasattr(c, "to_result_dict"):
-                result_dicts.append(c.to_result_dict())
-            elif isinstance(c, dict):
-                result_dicts.append(c)
-            else:
-                # Unknown candidate type — return original order.
-                return list(candidates)
-
-        from superlocalmemory.learning.model_cache import drift_mode
-
-        mode = drift_mode(self._active)
-        if mode == "unknown":
-            logger.info(
-                "ranker.rank: feature-name drift unknown; "
-                "falling back to pre-model order",
-            )
-            return list(candidates)
-
-        # Order matrix by CURRENT FEATURE_NAMES; if subset, missing names
-        # pad with 0.0 (FeatureExtractor already does this via .get(name, 0)).
-        try:
-            import numpy as np
-        except ImportError:  # pragma: no cover — numpy is required dep
-            return list(candidates)
-
-        try:
-            rows = []
-            for rd in result_dicts:
-                fv = FeatureExtractor.extract(rd, query_context)
-                rows.append(fv.to_list())
-            X = np.asarray(rows, dtype=np.float32)
-            scores = self._active.booster.predict(X)
-        except Exception as exc:  # pragma: no cover — booster.predict path
-            logger.warning("ranker.rank: booster.predict failed: %s", exc)
-            return list(candidates)
-
-        order = np.argsort(-scores, kind="stable")
-        return [candidates[int(i)] for i in order]
-
-    # --- phase implementations -----------------------------------------
-
-    def _rerank_baseline(self, results: list[dict]) -> list[dict]:
-        return sorted(
-            results,
-            key=lambda r: r.get("cross_encoder_score", r.get("score", 0)),
-            reverse=True,
-        )
-
-    def _rerank_heuristic(
-        self, results: list[dict], query_context: dict,
-    ) -> list[dict]:
-        scored: list[dict] = []
-        for r in results:
-            base = r.get("cross_encoder_score", r.get("score", 0))
-            age_days = r.get("fact", {}).get("age_days", 30)
-            access_count = r.get("fact", {}).get("access_count", 0)
-            recency_boost = 0.1 * math.exp(-age_days / 30)
-            access_boost = 0.05 * min(access_count / 10, 1.0)
-            trust_boost = 0.1 * (r.get("trust_score", 0.5) - 0.5)
-            final = base + recency_boost + access_boost + trust_boost
-            scored.append({**r, "_adaptive_score": final})
-        return sorted(scored, key=lambda r: r["_adaptive_score"], reverse=True)
-
-    def _rerank_ml(
-        self, results: list[dict], query_context: dict,
-    ) -> list[dict]:
-        """Phase 3 prediction via native Booster."""
-        if self._active is None:  # pragma: no cover — guarded by phase()
-            return self._rerank_heuristic(results, query_context)
-
-        from superlocalmemory.learning.model_cache import drift_mode
-
-        mode = drift_mode(self._active)
-        if mode == "unknown":
-            logger.info(
-                "ranker._rerank_ml: unknown drift → heuristic fallback",
-            )
-            return self._rerank_heuristic(results, query_context)
-
-        try:
-            import numpy as np
-        except ImportError:  # pragma: no cover
-            return self._rerank_heuristic(results, query_context)
-
-        try:
-            feature_vectors = FeatureExtractor.extract_batch(
-                results, query_context,
-            )
-            X = np.asarray(
-                [fv.to_list() for fv in feature_vectors],
-                dtype=np.float32,
-            )
-            scores = self._active.booster.predict(X)
-        except Exception as exc:  # pragma: no cover — booster.predict path
-            logger.warning("_rerank_ml failed: %s", exc)
-            return self._rerank_heuristic(results, query_context)
-
-        order = np.argsort(-scores, kind="stable")
-        return [
-            {**results[int(i)], "_adaptive_score": float(scores[int(i)])}
-            for i in order
-        ]
-
-    # --- legacy load path (back-compat) --------------------------------
-
-    def _load_legacy_bytes(self, state: bytes) -> None:
-        """Best-effort load from raw bytes — NO SHA-256 verify.
-
-        Kept for 3.4.20 callers. The 3.4.22 recall path uses
-        ``model_cache.load_active`` which enforces verification.
-        """
-        try:
-            import lightgbm as lgb  # noqa: PLC0415
-
-            booster = lgb.Booster(model_str=state.decode("utf-8"))
-        except Exception as exc:
-            logger.warning("Legacy model load failed: %s", exc)
-            self._active = None
-            return
-
-        from superlocalmemory.learning.model_cache import ActiveModel
-
-        self._active = ActiveModel(
-            profile_id="legacy",
-            booster=booster,
-            feature_names=tuple(FEATURE_NAMES),
-            trained_at="",
-            sha256="",
-        )
-
-    # --- legacy train() shim (3.4.20 API) ------------------------------
-
-    def train(self, training_data: list) -> bool:
-        """Deprecated — v3.4.22 training lives in ``consolidation_worker``.
-
-        Kept as a guard for 3.4.20 callers: returns False when
-        training_data is below the Phase-3 threshold, True after a best-
-        effort native booster fit on the legacy feature dict shape
-        (never persists to disk). Production training must go through
-        ``consolidation_worker._retrain_ranker`` which uses real features
-        + ``lambdarank`` + group + integrity persistence.
-        """
-        if not training_data or len(training_data) < PHASE_3_THRESHOLD:
-            return False
-        # Best-effort legacy path — does NOT persist, does NOT promote.
-        try:
-            import lightgbm as lgb  # noqa: PLC0415
-            import numpy as np
-        except ImportError:
-            return False
-        X = np.asarray(
-            [[float((d.get("features") or {}).get(n, 0.0))
-              for n in FEATURE_NAMES]
-             for d in training_data],
-            dtype=np.float32,
-        )
-        y = np.asarray(
-            [float(d.get("label", 0.0)) for d in training_data],
-            dtype=np.float32,
-        )
-        ds = lgb.Dataset(X, label=y, feature_name=list(FEATURE_NAMES),
-                         free_raw_data=False)
-        try:
-            booster = lgb.train(
-                {"objective": "regression", "metric": "rmse",
-                 "verbosity": -1, "min_data_in_leaf": 1},
-                ds, num_boost_round=10,
-            )
-        except Exception:  # pragma: no cover — defensive
-            return False
-        from superlocalmemory.learning.model_cache import ActiveModel
-
-        self._active = ActiveModel(
-            profile_id="legacy",
-            booster=booster,
-            feature_names=tuple(FEATURE_NAMES),
-            trained_at="",
-            sha256="",
-        )
-        return True
-
-    # --- legacy serialiser (used by external code in 3.4.20) -----------
-
-    def get_model_state(self) -> bytes | None:
-        if self._active is None:
-            return None
-        try:
-            return self._active.booster.model_to_string().encode("utf-8")
-        except Exception:  # pragma: no cover — defensive
-            return None

package/src/superlocalmemory/learning/ranker_common.py

@@ -1,163 +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 — F4.A Stage-8 H-01 fix
-
-"""Ranker retraining helpers shared by legacy + online paths.
-
-These functions predate the LLD-10 online retrain wiring and remain
-identical in behaviour; they are factored out so both
-``ranker_retrain_legacy.py`` and ``ranker_retrain_online.py`` can call
-them without importing from each other.
-
-Contract refs:
-  - LLD-02 §4.6 — lambdarank retraining groups + shadow gate.
-  - LLD-10 §3.2 — in-sample NDCG gate before persisting a candidate.
-  - Stage 8 H-01 (architect) — file split.
-"""
-
-from __future__ import annotations
-
-import logging
-
-logger = logging.getLogger(__name__)
-
-__all__ = (
-    "_build_training_matrix",
-    "_shadow_test_improved",
-    "_compute_eval_metrics",
-)
-
-
-def _build_training_matrix(rows: list[dict], feature_names):
-    """Group rows by ``query_id``, preserve order by ``position``.
-
-    Returns ``(X, y_int, group_counts)``. ``group_counts`` is ``None``
-    when no groups are discoverable (empty input).
-    """
-    import numpy as np
-    from superlocalmemory.learning.labeler import label_for_row
-
-    grouped: dict[str, list[dict]] = {}
-    for row in rows:
-        qid = row.get("query_id") or ""
-        grouped.setdefault(qid, []).append(row)
-    if not grouped:
-        return np.zeros((0, len(feature_names)), dtype=np.float32), [], None
-
-    xs: list[list[float]] = []
-    ys: list[int] = []
-    group_counts: list[int] = []
-    for qid, group_rows in grouped.items():
-        # Sort by position ascending; missing positions land at the end.
-        group_rows = sorted(
-            group_rows,
-            key=lambda r: (
-                r.get("position") if r.get("position") is not None else 10**9
-            ),
-        )
-        for r in group_rows:
-            feats = r.get("features") or {}
-            xs.append([float(feats.get(n, 0.0)) for n in feature_names])
-            ys.append(label_for_row(r))
-        group_counts.append(len(group_rows))
-
-    X = np.asarray(xs, dtype=np.float32)
-    y = np.asarray(ys, dtype=np.int32)
-    return X, y, group_counts
-
-
-def _shadow_test_improved(prior_row, booster_new, rows, feature_names) -> bool:
-    """Return True iff new booster beats prior on NDCG@10 with p<0.05.
-
-    Lightweight paired t-test across per-query NDCG@10 scores.
-    ``prior_row`` is the dict returned by ``load_active_model`` — it
-    may be unusable (missing state_bytes / unparseable); in that case
-    we promote.
-    """
-    try:
-        import numpy as np
-        import lightgbm as lgb
-    except ImportError:  # pragma: no cover
-        return True
-
-    try:
-        prior_booster = lgb.Booster(
-            model_str=bytes(prior_row["state_bytes"]).decode("utf-8"),
-        )
-    except Exception:
-        return True  # prior unusable → promote new.
-
-    X, y, groups = _build_training_matrix(rows, feature_names)
-    if groups is None or not groups:
-        return True
-
-    offsets = [0]
-    for g in groups:
-        offsets.append(offsets[-1] + g)
-
-    def _ndcg_at_k(scores, labels, k=10):
-        order = np.argsort(-scores)
-        gains_map = [0, 1, 3, 7, 15]
-        dcg = 0.0
-        for i, idx in enumerate(order[:k]):
-            l = int(labels[idx])
-            if 0 <= l < len(gains_map):
-                dcg += gains_map[l] / np.log2(i + 2)
-        ideal = sorted(labels.tolist(), reverse=True)[:k]
-        idcg = sum(
-            (gains_map[int(l)] if 0 <= int(l) < len(gains_map) else 0)
-            / np.log2(i + 2)
-            for i, l in enumerate(ideal)
-        )
-        return dcg / idcg if idcg > 0 else 0.0
-
-    old_ndcgs: list[float] = []
-    new_ndcgs: list[float] = []
-    for i in range(len(groups)):
-        lo, hi = offsets[i], offsets[i + 1]
-        if hi - lo < 2:
-            continue
-        Xg, yg = X[lo:hi], y[lo:hi]
-        try:
-            s_old = prior_booster.predict(Xg)
-            s_new = booster_new.predict(Xg)
-        except Exception:
-            return False
-        old_ndcgs.append(_ndcg_at_k(s_old, yg))
-        new_ndcgs.append(_ndcg_at_k(s_new, yg))
-
-    if not old_ndcgs:
-        return True
-    old_arr = np.asarray(old_ndcgs)
-    new_arr = np.asarray(new_ndcgs)
-    delta = float(np.mean(new_arr - old_arr))
-    if delta < 0.02:
-        return False
-
-    # Paired t-test — small-sample safe.
-    diff = new_arr - old_arr
-    n = len(diff)
-    if n < 2:
-        return True
-    mean = float(np.mean(diff))
-    std = float(np.std(diff, ddof=1))
-    if std == 0.0:
-        return mean > 0
-    t_stat = mean / (std / np.sqrt(n))
-    # Rough threshold: t > 2.0 (~p<0.05 for n ≥ 10 two-tailed).
-    return t_stat > 2.0
-
-
-def _compute_eval_metrics(booster, rows, feature_names) -> dict:
-    """Lightweight training metrics snapshot."""
-    try:
-        import numpy as np
-        X, y, groups = _build_training_matrix(rows, feature_names)
-        preds = booster.predict(X) if X.size else np.zeros(0)
-        return {
-            "n_rows": int(X.shape[0]),
-            "n_groups": int(len(groups or [])),
-            "mean_score": float(np.mean(preds)) if preds.size else 0.0,
-        }
-    except Exception:  # pragma: no cover
-        return {}