superlocalmemory 4.1.13 → 4.1.14

package/src/superlocalmemory/learning/reward_archive.py

@@ -1,223 +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-18/H-06 fix
-
-"""Reward-gated Ebbinghaus archive.
-
-Flags Ebbinghaus-cold facts as archived *only* when they show no
-positive reward in the last 60 days AND are not marked important
-(LLD-12 §4). Writes a payload-preserving row to ``memory_archive`` and
-updates ``atomic_facts.archive_status='archived'``.
-
-**Never issues DELETE FROM atomic_facts** (SOUL directive, LLD-12 §1 —
-memory is sacred across v3.4.22 with 18 000 live users).
-
-JSON1 join helper (``iter_outcomes_for_fact``) replaces the former
-``fact_ids_json LIKE '%"<fid>"%'`` pattern so that overlapping fact_id
-prefixes no longer collide (H-06).
-
-Contract refs:
-  - LLD-12 §4 — reward-gated archive criteria.
-  - Stage 8 H-18 — split from monolithic hnsw_dedup.py.
-  - Stage 8 H-06 — JSON1 replaces fragile LIKE.
-"""
-
-from __future__ import annotations
-
-import json
-import logging
-import sqlite3
-import uuid
-from datetime import datetime, timezone
-from pathlib import Path
-
-from superlocalmemory.learning.fact_outcome_joins import (
-    has_recent_positive_reward,
-)
-from superlocalmemory.storage.embedding_codec import decode_embedding
-from superlocalmemory.storage.write_lock import get_write_lock
-
-logger = logging.getLogger(__name__)
-
-
-REWARD_WINDOW_DAYS: int = 60
-ARCHIVE_REWARD_THRESHOLD: float = 0.3
-
-# SEC-L3 — soft cap on ``memory_archive.payload_json`` length. The DDL
-# in M011 is ``TEXT NOT NULL`` with no column cap (SQLite has no native
-# column-length limit), so a runaway fact could write multi-MB blobs
-# and blow past the MASTER-PLAN §2 I4 disk budget. Enforced on the
-# write path; oversize payloads are truncated with a breadcrumb in the
-# ``reason`` column so an operator can still retrieve the original
-# fact via ``atomic_facts`` (archive does not DELETE).
-PAYLOAD_JSON_MAX_BYTES: int = 262_144
-
-
-__all__ = (
-    "run_reward_gated_archive",
-    "REWARD_WINDOW_DAYS",
-    "ARCHIVE_REWARD_THRESHOLD",
-    "PAYLOAD_JSON_MAX_BYTES",
-)
-
-
-def _iso_now() -> str:
-    return datetime.now(timezone.utc).isoformat()
-
-
-def run_reward_gated_archive(
-    memory_db_path: str | Path,
-    profile_id: str,
-    *,
-    candidate_fact_ids: list[str],
-) -> list[str]:
-    """Archive candidate facts that have no positive reward in 60 days and
-    are not flagged important. Returns the list of fact_ids archived.
-
-    LLD-12 §1 hard invariant: this function NEVER issues
-    ``DELETE FROM atomic_facts``. It UPDATEs archive_status + writes a
-    payload snapshot to ``memory_archive``.
-    """
-    if not candidate_fact_ids:
-        return []
-
-    archived: list[str] = []
-
-    # READ phase — no write lock needed (WAL allows concurrent reads).
-    # H-12/H-P-02: compute the archivable set BEFORE acquiring the writer
-    # lock so that the lock is held only for the bulk INSERT/UPDATE pass.
-    conn_r = sqlite3.connect(str(memory_db_path), timeout=10.0)
-    conn_r.row_factory = sqlite3.Row
-    conn_r.execute("PRAGMA busy_timeout=2000")
-    try:
-        placeholders = ",".join("?" for _ in candidate_fact_ids)
-        rows = conn_r.execute(
-            f"SELECT fact_id, content, canonical_entities_json, importance, "
-            f"       confidence, embedding, created_at "
-            f"FROM atomic_facts "
-            f"WHERE profile_id = ? AND fact_id IN ({placeholders}) "
-            f"  AND (archive_status IS NULL OR archive_status = 'live')",
-            (profile_id, *candidate_fact_ids),
-        ).fetchall()
-
-        to_archive: list[dict] = []
-        for row in rows:
-            fid = row["fact_id"]
-            # 1. Important flag skip (LLD-12 §4 criterion 3).
-            if float(row["importance"] or 0.0) >= 1.0:
-                continue
-            # 2. Recent positive reward skip (criterion 2).
-            #    H-06 fix — JSON1 equality join via helper.
-            if has_recent_positive_reward(
-                conn_r, profile_id, fid,
-                min_reward=ARCHIVE_REWARD_THRESHOLD,
-                window_days=REWARD_WINDOW_DAYS,
-            ):
-                continue
-            # Decode the embedding to list[float] so json.dumps(payload)
-            # succeeds regardless of whether the row is TEXT or BLOB.
-            # ValueError (corrupt buffer) propagates — a silent None here
-            # would archive a fact with a missing embedding, which loses data.
-            to_archive.append({
-                "fid": fid,
-                "content": row["content"],
-                "canonical_entities_json": row["canonical_entities_json"],
-                "importance": row["importance"],
-                "confidence": row["confidence"],
-                "embedding": decode_embedding(row["embedding"], fact_id=fid),
-                "created_at": row["created_at"],
-            })
-    finally:
-        conn_r.close()
-
-    if not to_archive:
-        return []
-
-    # WRITE phase — acquire the process-level write lock BEFORE opening the
-    # write connection.  This serialises BEGIN IMMEDIATE → commit with all
-    # other in-process writers (DatabaseManager, VectorStore, adapter sync,
-    # memory_merge, reward_boost), eliminating SQLITE_BUSY races at the WAL
-    # layer.
-    with get_write_lock(memory_db_path):
-        conn = sqlite3.connect(str(memory_db_path), timeout=10.0)
-        conn.row_factory = sqlite3.Row
-        conn.execute("PRAGMA busy_timeout=2000")
-        try:
-            conn.execute("BEGIN IMMEDIATE")
-            # S9-SKEP-07: re-verify reward under RESERVED lock. Between the
-            # read-only reward scan above and this BEGIN IMMEDIATE another
-            # writer may have inserted a positive reward row. With the writer
-            # lock held we know no further inserts are landing; one last
-            # check per entry catches everything that raced in.
-            verified: list[dict] = []
-            for entry in to_archive:
-                if has_recent_positive_reward(
-                    conn, profile_id, entry["fid"],
-                    min_reward=ARCHIVE_REWARD_THRESHOLD,
-                    window_days=REWARD_WINDOW_DAYS,
-                ):
-                    continue
-                verified.append(entry)
-            to_archive = verified
-            if not to_archive:
-                conn.execute("COMMIT")
-                return []
-            for entry in to_archive:
-                fid = entry["fid"]
-                payload = {
-                    "fact_id": fid,
-                    "content": entry["content"],
-                    "canonical_entities_json": entry["canonical_entities_json"],
-                    "importance": entry["importance"],
-                    "confidence": entry["confidence"],
-                    "embedding": entry["embedding"],
-                    "created_at": entry["created_at"],
-                }
-                # SEC-L3 — cap payload_json at 256 KB. Oversize blobs are
-                # replaced with a minimal stub + ``truncated`` reason so the
-                # archive row stays within the I4 disk budget while still
-                # pointing back to the original ``fact_id`` in atomic_facts.
-                payload_str = json.dumps(payload)
-                reason = "reward_gated_ebbinghaus"
-                if len(payload_str.encode("utf-8")) > PAYLOAD_JSON_MAX_BYTES:
-                    payload_str = json.dumps({
-                        "fact_id": fid,
-                        "truncated": True,
-                        "original_bytes": len(payload_str.encode("utf-8")),
-                    })
-                    reason = "reward_gated_ebbinghaus_truncated"
-                    logger.warning(
-                        "memory_archive payload >%d bytes for fact_id=%s; "
-                        "truncated to stub", PAYLOAD_JSON_MAX_BYTES, fid,
-                    )
-                conn.execute(
-                    "INSERT INTO memory_archive "
-                    "(archive_id, fact_id, profile_id, payload_json, "
-                    " archived_at, reason) VALUES (?, ?, ?, ?, ?, ?)",
-                    (
-                        str(uuid.uuid4()),
-                        fid,
-                        profile_id,
-                        payload_str,
-                        _iso_now(),
-                        reason,
-                    ),
-                )
-                conn.execute(
-                    "UPDATE atomic_facts "
-                    "SET archive_status='archived', "
-                    "    archive_reason='reward_gated_ebbinghaus' "
-                    "WHERE fact_id=? "
-                    "  AND (archive_status IS NULL OR archive_status='live')",
-                    (fid,),
-                )
-                archived.append(fid)
-
-            conn.commit()
-        except sqlite3.Error as exc:
-            conn.rollback()
-            logger.warning("run_reward_gated_archive rollback: %s", exc)
-        finally:
-            conn.close()
-
-    return archived

package/src/superlocalmemory/learning/reward_boost.py

@@ -1,211 +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-06/H-18 fix
-
-"""Strong-memory boost + reward-aware fact selection.
-
-Nudges ``atomic_facts.retrieval_prior`` upward for facts with recurring
-high reward, capped at 0.5 (LLD-12 §5). Also exposes
-``select_high_reward_fact_ids`` for the soft-prompt generator.
-
-H-06 regression fix: outcome lookups now use the JSON1-backed
-``fact_outcome_joins`` helper instead of the fragile
-``fact_ids_json LIKE '%"<fid>"%'`` pattern that leaked substring matches
-across overlapping fact_id prefixes.
-"""
-
-from __future__ import annotations
-
-import logging
-import sqlite3
-from pathlib import Path
-
-from superlocalmemory.learning.fact_outcome_joins import (
-    aggregate_reward_for_fact,
-)
-from superlocalmemory.storage.write_lock import get_write_lock
-
-
-# H-12/H-P-01: single-pass JSON1 aggregation across ALL facts for a profile.
-# Returns ``{fact_id: (count, mean_reward)}`` for outcomes with reward NOT
-# NULL. Replaces the per-fact O(F) loop of ``aggregate_reward_for_fact``
-# with one GROUP BY scan — O(F+O) instead of O(F·O). JSON1 has been
-# mandatory since v3.4.22 (see ``fact_outcome_joins._json1_available``
-# contract in the module docstring); if it is missing at runtime the
-# caller falls back to the per-fact helper which retains its own
-# LIKE-based shim.
-
-
-# S9-W3 H-PERF-03: consolidation invokes ``apply_strong_memory_boost``
-# AND ``select_high_reward_fact_ids`` in the same cycle. Both call
-# ``_bulk_fact_reward_stats`` which is a full GROUP BY scan — at 100k
-# outcomes that's 1-3 s × 2 = 2-6 s wasted inside the 5-min cap. We
-# memoise the result with a short TTL so consecutive calls within the
-# same consolidation cycle share the stats. Key is (id(conn),
-# profile_id) so different conns / profiles get independent caches.
-# TTL expires quickly so live recall updates are reflected within one
-# cycle of the consolidation loop.
-_BULK_STATS_TTL_SEC: float = 30.0
-_bulk_stats_cache: dict[tuple[int, str], tuple[float, dict[str, tuple[int, float]]]] = {}
-
-
-# S9-W3 M-PERF-07: module-level MISS constant so ``stats.get(fid, _MISS)``
-# does not allocate a fresh ``(0, 0.0)`` tuple per call. At 100k facts
-# that saved ~2 MB of short-lived garbage per consolidation cycle.
-_MISS: tuple[int, float] = (0, 0.0)
-
-
-def _bulk_fact_reward_stats(
-    conn: sqlite3.Connection, profile_id: str,
-) -> dict[str, tuple[int, float]]:
-    import time as _time
-    now = _time.monotonic()
-    key = (id(conn), profile_id)
-    cached = _bulk_stats_cache.get(key)
-    if cached is not None:
-        ts, result = cached
-        if now - ts < _BULK_STATS_TTL_SEC:
-            return result
-    try:
-        rows = conn.execute(
-            "SELECT j.value AS fact_id, "
-            "       COUNT(*) AS c, "
-            "       AVG(reward) AS m "
-            "FROM action_outcomes a, json_each(a.fact_ids_json) j "
-            "WHERE a.profile_id = ? AND a.reward IS NOT NULL "
-            "GROUP BY j.value",
-            (profile_id,),
-        ).fetchall()
-    except sqlite3.OperationalError:
-        # JSON1 missing — signal to caller to fall back. Do NOT cache
-        # this (empty) result: a subsequent call on the same conn may
-        # fall through to the per-fact loop intentionally.
-        return {}
-    out: dict[str, tuple[int, float]] = {}
-    for fid, c, m in rows:
-        if fid is None:
-            continue
-        out[str(fid)] = (int(c or 0), float(m or 0.0))
-    _bulk_stats_cache[key] = (now, out)
-    # Prune the cache if it grows beyond 64 entries (multi-profile envs).
-    if len(_bulk_stats_cache) > 64:
-        stale = [k for k, (t, _) in _bulk_stats_cache.items()
-                 if now - t >= _BULK_STATS_TTL_SEC]
-        for k in stale:
-            _bulk_stats_cache.pop(k, None)
-    return out
-
-logger = logging.getLogger(__name__)
-
-
-STRONG_BOOST_INCREMENT: float = 0.1
-STRONG_BOOST_CAP: float = 0.5
-STRONG_BOOST_MIN_OUTCOMES: int = 3
-STRONG_BOOST_MIN_MEAN: float = 0.7
-
-
-__all__ = (
-    "apply_strong_memory_boost",
-    "select_high_reward_fact_ids",
-    "STRONG_BOOST_INCREMENT",
-    "STRONG_BOOST_CAP",
-    "STRONG_BOOST_MIN_OUTCOMES",
-    "STRONG_BOOST_MIN_MEAN",
-)
-
-
-def apply_strong_memory_boost(
-    memory_db_path: str | Path, profile_id: str,
-) -> int:
-    """Nudge retrieval_prior up for high-reward facts, capped at 0.5.
-
-    Eligibility: ≥ MIN_OUTCOMES outcomes with mean reward > MIN_MEAN.
-    Effect: retrieval_prior = MIN(retrieval_prior + INCREMENT, CAP).
-
-    Returns number of rows boosted.
-    """
-    # READ phase — no write lock needed (WAL allows concurrent reads).
-    conn_r = sqlite3.connect(str(memory_db_path), timeout=10.0)
-    try:
-        rows = conn_r.execute(
-            "SELECT fact_id FROM atomic_facts WHERE profile_id=? "
-            "  AND (archive_status IS NULL OR archive_status='live')",
-            (profile_id,),
-        ).fetchall()
-        if not rows:
-            conn_r.close()
-            return 0
-        # H-12/H-P-01: single JSON1 GROUP BY replaces the per-fact loop.
-        stats = _bulk_fact_reward_stats(conn_r, profile_id)
-    finally:
-        conn_r.close()
-
-    # WRITE phase — acquire the process-level write lock BEFORE opening the
-    # write connection.  This serialises BEGIN IMMEDIATE → commit with all
-    # other in-process writers (DatabaseManager, VectorStore, adapter sync),
-    # eliminating SQLITE_BUSY races at the SQLite WAL layer.
-    boosted = 0
-    with get_write_lock(memory_db_path):
-        conn = sqlite3.connect(str(memory_db_path), timeout=10.0)
-        conn.execute("PRAGMA busy_timeout=2000")
-        try:
-            conn.execute("BEGIN IMMEDIATE")
-            for (fid,) in rows:
-                if stats:
-                    count, mean = stats.get(fid, _MISS)
-                else:
-                    count, mean = aggregate_reward_for_fact(conn, profile_id, fid)
-                if count < STRONG_BOOST_MIN_OUTCOMES:
-                    continue
-                if mean <= STRONG_BOOST_MIN_MEAN:
-                    continue
-                conn.execute(
-                    "UPDATE atomic_facts "
-                    "SET retrieval_prior = MIN(COALESCE(retrieval_prior, 0) + ?, ?) "
-                    "WHERE fact_id=?",
-                    (STRONG_BOOST_INCREMENT, STRONG_BOOST_CAP, fid),
-                )
-                boosted += 1
-            conn.commit()
-        except sqlite3.Error as exc:
-            conn.rollback()
-            logger.warning("apply_strong_memory_boost rollback: %s", exc)
-        finally:
-            conn.close()
-    return boosted
-
-
-def select_high_reward_fact_ids(
-    memory_db_path: str | Path,
-    profile_id: str,
-    *,
-    min_reward: float = 0.6,
-    min_outcomes: int = 1,
-) -> list[str]:
-    """Return fact_ids whose mean outcome reward ≥ ``min_reward``.
-
-    Used by ``soft_prompt_generator`` to mine only high-reward facts
-    (LLD-12 §6). JSON1-backed — no substring false positives.
-    """
-    conn = sqlite3.connect(str(memory_db_path), timeout=10.0)
-    try:
-        fact_rows = conn.execute(
-            "SELECT fact_id FROM atomic_facts WHERE profile_id=? "
-            "  AND (archive_status IS NULL OR archive_status='live')",
-            (profile_id,),
-        ).fetchall()
-        # H-12/H-P-01: bulk aggregate replaces per-fact loop.
-        stats = _bulk_fact_reward_stats(conn, profile_id)
-        out: list[str] = []
-        for (fid,) in fact_rows:
-            if stats:
-                count, mean = stats.get(fid, _MISS)
-            else:
-                count, mean = aggregate_reward_for_fact(conn, profile_id, fid)
-            if count < min_outcomes:
-                continue
-            if mean >= min_reward:
-                out.append(fid)
-        return out
-    finally:
-        conn.close()