superlocalmemory 2.8.5 → 3.0.0

package/src/superlocalmemory/learning/features.py

@@ -0,0 +1,138 @@
+# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
+# Licensed under the MIT License - see LICENSE file
+# Part of SuperLocalMemory V3 | https://qualixar.com | https://varunpratap.com
+
+"""V3-native feature extractor for adaptive ranking.
+
+Extracts features from retrieval results for LightGBM training.
+Features are grouped by source: channel scores, fusion, reranker,
+math layers, query analysis, memory metadata, user history.
+
+Each feature vector has a fixed dimension (FEATURE_DIM).
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass, field
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+# Feature dimension — total number of features extracted
+FEATURE_DIM = 20
+
+
+@dataclass(frozen=True)
+class FeatureVector:
+    """Immutable feature vector for one retrieval result."""
+    fact_id: str
+    query_id: str
+    features: dict[str, float]
+    label: float | None = None  # None = unlabeled (inference), float = labeled (training)
+
+    def to_list(self) -> list[float]:
+        """Convert to ordered list for LightGBM input."""
+        return [self.features.get(name, 0.0) for name in FEATURE_NAMES]
+
+
+# Ordered feature names — must match FEATURE_DIM
+FEATURE_NAMES: list[str] = [
+    # Channel scores (4)
+    "semantic_score",
+    "bm25_score",
+    "entity_score",
+    "temporal_score",
+    # Fusion (2)
+    "rrf_rank",
+    "rrf_score",
+    # Reranker (1)
+    "cross_encoder_score",
+    # Math layers (3)
+    "fisher_distance",
+    "fisher_confidence",
+    "sheaf_consistent",
+    # Query features (4)
+    "query_type_sh",  # one-hot: single-hop
+    "query_type_mh",  # one-hot: multi-hop
+    "query_type_temp",  # one-hot: temporal
+    "query_type_od",  # one-hot: open-domain
+    # Memory metadata (4)
+    "fact_age_days",
+    "access_count",
+    "fact_trust_score",
+    "fact_confidence",
+    # User/profile (2)
+    "profile_recall_count",
+    "topic_affinity",
+]
+
+assert len(FEATURE_NAMES) == FEATURE_DIM
+
+
+class FeatureExtractor:
+    """Extract features from V3 retrieval results for LightGBM ranking."""
+
+    @staticmethod
+    def extract(result: dict[str, Any], query_context: dict[str, Any]) -> FeatureVector:
+        """Extract features from a single retrieval result.
+
+        Args:
+            result: dict with keys from RetrievalResult (score, channel_scores,
+                    fact metadata, etc.)
+            query_context: dict with query_type, query_length, profile stats, etc.
+
+        Returns:
+            FeatureVector with FEATURE_DIM features.
+        """
+        channel = result.get("channel_scores", {})
+        fact = result.get("fact", {})
+
+        features = {
+            # Channel scores
+            "semantic_score": channel.get("semantic", 0.0),
+            "bm25_score": channel.get("bm25", 0.0),
+            "entity_score": channel.get("entity_graph", 0.0),
+            "temporal_score": channel.get("temporal", 0.0),
+            # Fusion
+            "rrf_rank": result.get("rrf_rank", 0.0),
+            "rrf_score": result.get("rrf_score", 0.0),
+            # Reranker
+            "cross_encoder_score": result.get("cross_encoder_score", 0.0),
+            # Math
+            "fisher_distance": result.get("fisher_distance", 0.0),
+            "fisher_confidence": result.get("fisher_confidence", 0.0),
+            "sheaf_consistent": 1.0 if result.get("sheaf_consistent", True) else 0.0,
+            # Query (one-hot)
+            "query_type_sh": 1.0 if query_context.get("query_type") == "single_hop" else 0.0,
+            "query_type_mh": 1.0 if query_context.get("query_type") == "multi_hop" else 0.0,
+            "query_type_temp": 1.0 if query_context.get("query_type") == "temporal" else 0.0,
+            "query_type_od": 1.0 if query_context.get("query_type") == "open_domain" else 0.0,
+            # Memory metadata
+            "fact_age_days": _safe_float(fact.get("age_days", 0)),
+            "access_count": _safe_float(fact.get("access_count", 0)),
+            "fact_trust_score": _safe_float(result.get("trust_score", 0.5)),
+            "fact_confidence": _safe_float(fact.get("confidence", 0.7)),
+            # User/profile
+            "profile_recall_count": _safe_float(query_context.get("profile_recall_count", 0)),
+            "topic_affinity": _safe_float(query_context.get("topic_affinity", 0.0)),
+        }
+
+        return FeatureVector(
+            fact_id=result.get("fact_id", ""),
+            query_id=query_context.get("query_id", ""),
+            features=features,
+        )
+
+    @staticmethod
+    def extract_batch(results: list[dict], query_context: dict) -> list[FeatureVector]:
+        """Extract features from a batch of retrieval results."""
+        return [FeatureExtractor.extract(r, query_context) for r in results]
+
+
+def _safe_float(value: Any) -> float:
+    """Convert to float safely, defaulting to 0.0."""
+    try:
+        return float(value)
+    except (TypeError, ValueError):
+        return 0.0

package/src/superlocalmemory/learning/feedback.py

@@ -0,0 +1,316 @@
+#!/usr/bin/env python3
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 Qualixar / SuperLocalMemory (superlocalmemory.com)
+# Part of Qualixar | Author: Varun Pratap Bhardwaj (qualixar.com | varunpratap.com)
+"""
+FeedbackCollector -- Multi-signal feedback collection for V3 learning.
+
+Collects implicit and explicit relevance signals:
+    - Implicit: recall_hit (fact returned), recall_miss (fact not in results)
+    - Explicit: user_positive, user_negative, user_correction
+    - Derived: access_pattern (frequent recall = positive signal)
+
+Privacy:
+    - Full query text is NEVER stored.
+    - Queries are hashed to SHA-256[:16] for grouping.
+
+Storage:
+    Uses direct sqlite3 with a self-contained ``learning_feedback`` table.
+    NOT coupled to V3 DatabaseManager -- this is a standalone data collector.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import logging
+import sqlite3
+import threading
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+logger = logging.getLogger("superlocalmemory.learning.feedback")
+
+# Signal type -> numeric value for downstream consumers
+SIGNAL_VALUES: Dict[str, float] = {
+    "recall_hit": 0.7,
+    "recall_miss": 0.0,
+    "user_positive": 1.0,
+    "user_negative": 0.0,
+    "user_correction": 0.2,
+    "access_pattern": 0.6,
+}
+
+_CREATE_TABLE = """
+CREATE TABLE IF NOT EXISTS learning_feedback (
+    id           INTEGER PRIMARY KEY AUTOINCREMENT,
+    profile_id   TEXT    NOT NULL,
+    fact_id      TEXT    NOT NULL,
+    signal_type  TEXT    NOT NULL,
+    signal_value REAL    NOT NULL,
+    query_hash   TEXT,
+    created_at   TEXT    NOT NULL,
+    metadata     TEXT
+)
+"""
+
+_CREATE_INDEX = """
+CREATE INDEX IF NOT EXISTS idx_feedback_profile
+    ON learning_feedback (profile_id, created_at DESC)
+"""
+
+
+def _utcnow_iso() -> str:
+    """Return current UTC time as ISO-8601 string."""
+    return datetime.now(timezone.utc).isoformat()
+
+
+def _hash_query(query: str) -> str:
+    """Privacy-preserving SHA-256[:16] query hash."""
+    return hashlib.sha256(query.encode("utf-8")).hexdigest()[:16]
+
+
+class FeedbackCollector:
+    """
+    Collects multi-signal relevance feedback for the V3 learning system.
+
+    Each instance owns a sqlite3 database at *db_path*.  All writes are
+    serialised through a threading lock for safety.
+
+    Args:
+        db_path: Path to the sqlite3 database file.
+    """
+
+    def __init__(self, db_path: Path) -> None:
+        self._db_path = Path(db_path)
+        self._lock = threading.Lock()
+        self._ensure_schema()
+
+    # ------------------------------------------------------------------
+    # Schema
+    # ------------------------------------------------------------------
+
+    def _ensure_schema(self) -> None:
+        """Create tables/indexes if they do not exist."""
+        conn = self._connect()
+        try:
+            conn.execute(_CREATE_TABLE)
+            conn.execute(_CREATE_INDEX)
+            conn.commit()
+        finally:
+            conn.close()
+
+    def _connect(self) -> sqlite3.Connection:
+        """Open a connection with WAL mode and busy timeout."""
+        conn = sqlite3.connect(str(self._db_path), timeout=10)
+        conn.execute("PRAGMA journal_mode=WAL")
+        conn.execute("PRAGMA busy_timeout=5000")
+        conn.row_factory = sqlite3.Row
+        return conn
+
+    # ------------------------------------------------------------------
+    # Public API: record implicit feedback
+    # ------------------------------------------------------------------
+
+    def record_implicit(
+        self,
+        profile_id: str,
+        query: str,
+        fact_ids_returned: List[str],
+        fact_ids_available: List[str],
+    ) -> int:
+        """
+        Record implicit feedback from a recall operation.
+
+        Facts in *fact_ids_returned* get a ``recall_hit`` signal.
+        Facts in *fact_ids_available* but NOT in *fact_ids_returned* get
+        a ``recall_miss`` signal.
+
+        Args:
+            profile_id:        Profile that performed the recall.
+            query:             The recall query (hashed, never stored raw).
+            fact_ids_returned: Fact IDs that appeared in results.
+            fact_ids_available: All candidate fact IDs for this query.
+
+        Returns:
+            Number of feedback records created.
+        """
+        if not profile_id or not query:
+            return 0
+
+        qhash = _hash_query(query)
+        returned_set = set(fact_ids_returned)
+        now = _utcnow_iso()
+        records: list[tuple] = []
+
+        for fid in returned_set:
+            records.append((
+                profile_id, fid, "recall_hit",
+                SIGNAL_VALUES["recall_hit"], qhash, now, None,
+            ))
+
+        for fid in fact_ids_available:
+            if fid not in returned_set:
+                records.append((
+                    profile_id, fid, "recall_miss",
+                    SIGNAL_VALUES["recall_miss"], qhash, now, None,
+                ))
+
+        if not records:
+            return 0
+
+        with self._lock:
+            conn = self._connect()
+            try:
+                conn.executemany(
+                    "INSERT INTO learning_feedback "
+                    "(profile_id, fact_id, signal_type, signal_value, "
+                    "query_hash, created_at, metadata) "
+                    "VALUES (?, ?, ?, ?, ?, ?, ?)",
+                    records,
+                )
+                conn.commit()
+                return len(records)
+            finally:
+                conn.close()
+
+    # ------------------------------------------------------------------
+    # Public API: record explicit feedback
+    # ------------------------------------------------------------------
+
+    def record_explicit(
+        self,
+        profile_id: str,
+        fact_id: str,
+        signal_type: str,
+        value: float,
+    ) -> Optional[int]:
+        """
+        Record explicit user feedback on a specific fact.
+
+        Args:
+            profile_id:  Profile providing feedback.
+            fact_id:     The fact being rated.
+            signal_type: One of ``user_positive``, ``user_negative``,
+                         ``user_correction``, or any custom type.
+            value:       Numeric signal value (0.0 to 1.0).
+
+        Returns:
+            Row ID of the inserted record, or None on error.
+        """
+        if not profile_id or not fact_id:
+            return None
+
+        clamped = max(0.0, min(1.0, float(value)))
+        now = _utcnow_iso()
+
+        with self._lock:
+            conn = self._connect()
+            try:
+                cursor = conn.execute(
+                    "INSERT INTO learning_feedback "
+                    "(profile_id, fact_id, signal_type, signal_value, "
+                    "query_hash, created_at, metadata) "
+                    "VALUES (?, ?, ?, ?, ?, ?, ?)",
+                    (profile_id, fact_id, signal_type, clamped, None, now, None),
+                )
+                conn.commit()
+                return cursor.lastrowid
+            finally:
+                conn.close()
+
+    # ------------------------------------------------------------------
+    # Public API: read feedback
+    # ------------------------------------------------------------------
+
+    def get_feedback(
+        self,
+        profile_id: str,
+        limit: int = 100,
+    ) -> List[Dict[str, Any]]:
+        """
+        Retrieve recent feedback records for a profile.
+
+        Args:
+            profile_id: Profile to query.
+            limit:      Maximum records to return.
+
+        Returns:
+            List of dicts with keys: id, fact_id, signal_type,
+            signal_value, query_hash, created_at.
+        """
+        conn = self._connect()
+        try:
+            rows = conn.execute(
+                "SELECT id, fact_id, signal_type, signal_value, "
+                "query_hash, created_at "
+                "FROM learning_feedback "
+                "WHERE profile_id = ? "
+                "ORDER BY created_at DESC LIMIT ?",
+                (profile_id, limit),
+            ).fetchall()
+            return [dict(r) for r in rows]
+        finally:
+            conn.close()
+
+    def get_feedback_count(self, profile_id: str) -> int:
+        """
+        Return the total number of feedback records for a profile.
+
+        Args:
+            profile_id: Profile to query.
+
+        Returns:
+            Integer count of feedback records.
+        """
+        conn = self._connect()
+        try:
+            row = conn.execute(
+                "SELECT COUNT(*) FROM learning_feedback WHERE profile_id = ?",
+                (profile_id,),
+            ).fetchone()
+            return row[0] if row else 0
+        finally:
+            conn.close()
+
+    # ------------------------------------------------------------------
+    # Public API: summary
+    # ------------------------------------------------------------------
+
+    def get_summary(self, profile_id: str) -> Dict[str, Any]:
+        """
+        Return summary statistics for a profile's feedback.
+
+        Returns:
+            Dict with total, by_type counts, and latest timestamp.
+        """
+        conn = self._connect()
+        try:
+            total_row = conn.execute(
+                "SELECT COUNT(*) FROM learning_feedback WHERE profile_id = ?",
+                (profile_id,),
+            ).fetchone()
+            total = total_row[0] if total_row else 0
+
+            type_rows = conn.execute(
+                "SELECT signal_type, COUNT(*) AS cnt "
+                "FROM learning_feedback WHERE profile_id = ? "
+                "GROUP BY signal_type",
+                (profile_id,),
+            ).fetchall()
+            by_type = {r["signal_type"]: r["cnt"] for r in type_rows}
+
+            latest_row = conn.execute(
+                "SELECT MAX(created_at) FROM learning_feedback "
+                "WHERE profile_id = ?",
+                (profile_id,),
+            ).fetchone()
+            latest = latest_row[0] if latest_row else None
+
+            return {
+                "total": total,
+                "by_type": by_type,
+                "latest": latest,
+            }
+        finally:
+            conn.close()

package/src/superlocalmemory/learning/outcomes.py

@@ -0,0 +1,255 @@
+# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
+# Licensed under the MIT License - see LICENSE file
+# Part of SuperLocalMemory V3 | https://qualixar.com | https://varunpratap.com
+
+"""SuperLocalMemory V3 — Outcome Tracking & Inference.
+
+Records what happens AFTER memories are recalled: success, failure,
+or partial outcomes. Also provides signal-based outcome inference
+for implicit feedback loops.
+
+Uses the ``action_outcomes`` table from the V3 schema and returns
+``ActionOutcome`` dataclass instances for type safety.
+
+The feedback loop:
+  recall() -> user action -> record_outcome() -> learning engine
+
+Part of Qualixar | Author: Varun Pratap Bhardwaj
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from typing import Any
+
+from superlocalmemory.storage.models import ActionOutcome
+
+logger = logging.getLogger(__name__)
+
+# Valid outcome labels
+VALID_OUTCOMES = frozenset({"success", "failure", "partial"})
+
+# Inference signal weights
+_SIGNAL_WEIGHTS: dict[str, tuple[str, float]] = {
+    "used_immediately": ("success", 0.9),
+    "mcp_used_high": ("success", 0.8),
+    "cross_tool_access": ("success", 0.7),
+    "no_requery_10m": ("success", 0.6),
+    "partial_use": ("partial", 0.5),
+    "requery_different_terms": ("failure", 0.3),
+    "rapid_fire_queries": ("failure", 0.2),
+    "deleted_after_recall": ("failure", 0.1),
+    "ignored": ("failure", 0.4),
+}
+
+
+class OutcomeTracker:
+    """Track retrieval outcomes and feed into learning.
+
+    Accepts a ``DatabaseManager`` and operates on the ``action_outcomes``
+    table created by the V3 schema.  Returns ``ActionOutcome`` dataclasses.
+    """
+
+    def __init__(self, db) -> None:
+        self._db = db
+
+    # ------------------------------------------------------------------
+    # Public API — Recording
+    # ------------------------------------------------------------------
+
+    def record_outcome(
+        self,
+        query: str,
+        fact_ids: list[str],
+        outcome: str,
+        profile_id: str,
+        context: dict[str, Any] | None = None,
+    ) -> ActionOutcome:
+        """Record an outcome against one or more facts.
+
+        Args:
+            query: The recall query that produced these facts.
+            fact_ids: List of fact IDs involved in the outcome.
+            outcome: One of "success", "failure", "partial".
+            profile_id: Profile scope.
+            context: Arbitrary metadata dict.
+
+        Returns:
+            The persisted ActionOutcome.
+        """
+        if outcome not in VALID_OUTCOMES:
+            logger.warning(
+                "Invalid outcome '%s'. Must be one of %s", outcome, VALID_OUTCOMES
+            )
+            outcome = "partial"
+
+        ao = ActionOutcome(
+            profile_id=profile_id,
+            query=query,
+            fact_ids=list(fact_ids),
+            outcome=outcome,
+            context=dict(context) if context else {},
+        )
+
+        self._db.execute(
+            "INSERT OR REPLACE INTO action_outcomes "
+            "(outcome_id, profile_id, query, fact_ids_json, outcome, "
+            " context_json, timestamp) "
+            "VALUES (?, ?, ?, ?, ?, ?, ?)",
+            (
+                ao.outcome_id,
+                ao.profile_id,
+                ao.query,
+                json.dumps(ao.fact_ids),
+                ao.outcome,
+                json.dumps(ao.context),
+                ao.timestamp,
+            ),
+        )
+        return ao
+
+    # ------------------------------------------------------------------
+    # Public API — Querying
+    # ------------------------------------------------------------------
+
+    def get_outcomes(
+        self,
+        profile_id: str,
+        limit: int = 50,
+        outcome_filter: str | None = None,
+    ) -> list[ActionOutcome]:
+        """Get recent outcomes for a profile.
+
+        Returns:
+            List of ``ActionOutcome`` objects, newest first.
+        """
+        sql = "SELECT * FROM action_outcomes WHERE profile_id = ?"
+        params: list[Any] = [profile_id]
+
+        if outcome_filter and outcome_filter in VALID_OUTCOMES:
+            sql += " AND outcome = ?"
+            params.append(outcome_filter)
+
+        sql += " ORDER BY timestamp DESC LIMIT ?"
+        params.append(limit)
+
+        rows = self._db.execute(sql, tuple(params))
+        return [self._row_to_outcome(r) for r in rows]
+
+    def get_success_rate(self, profile_id: str) -> float:
+        """Overall success rate.  ``success`` = 1.0, ``partial`` = 0.5."""
+        rows = self._db.execute(
+            "SELECT outcome, COUNT(*) AS cnt FROM action_outcomes "
+            "WHERE profile_id = ? GROUP BY outcome",
+            (profile_id,),
+        )
+        if not rows:
+            return 0.0
+
+        counts = {dict(r)["outcome"]: dict(r)["cnt"] for r in rows}
+        total = sum(counts.values())
+        if total == 0:
+            return 0.0
+
+        success = counts.get("success", 0)
+        partial = counts.get("partial", 0) * 0.5
+        return round((success + partial) / total, 4)
+
+    def get_fact_success_rate(self, fact_id: str, profile_id: str) -> float:
+        """How often a specific fact led to successful outcomes.
+
+        Returns 0.5 (neutral) if no relevant data exists.
+        """
+        outcomes = self.get_outcomes(profile_id, limit=500)
+        relevant = [o for o in outcomes if fact_id in o.fact_ids]
+
+        if not relevant:
+            return 0.5
+
+        successes = sum(1 for o in relevant if o.outcome == "success")
+        return round(successes / len(relevant), 4)
+
+    # ------------------------------------------------------------------
+    # Public API — Inference
+    # ------------------------------------------------------------------
+
+    def infer_outcome(
+        self,
+        profile_id: str,
+        fact_ids: list[str],
+        signals: dict[str, Any],
+    ) -> str:
+        """Infer outcome from behavioral signals and auto-record it."""
+        success_score = 0.0
+        failure_score = 0.0
+        matched_signals: list[str] = []
+
+        for signal_name, value in signals.items():
+            if not value:
+                continue
+            if signal_name in _SIGNAL_WEIGHTS:
+                outcome_label, weight = _SIGNAL_WEIGHTS[signal_name]
+                matched_signals.append(signal_name)
+                if outcome_label == "success":
+                    success_score += weight
+                elif outcome_label == "failure":
+                    failure_score += weight
+                else:
+                    success_score += weight * 0.5
+                    failure_score += weight * 0.5
+
+        if success_score > failure_score:
+            inferred = "success"
+        elif failure_score > success_score:
+            inferred = "failure"
+        else:
+            inferred = "partial"
+
+        self.record_outcome(
+            query="[inferred]",
+            fact_ids=fact_ids,
+            outcome=inferred,
+            profile_id=profile_id,
+            context={
+                "signals": matched_signals,
+                "success_score": round(success_score, 3),
+                "failure_score": round(failure_score, 3),
+            },
+        )
+        return inferred
+
+    # ------------------------------------------------------------------
+    # Public API — Maintenance
+    # ------------------------------------------------------------------
+
+    def delete_outcomes(self, profile_id: str) -> int:
+        """Delete all outcomes for a profile. Returns count deleted."""
+        rows = self._db.execute(
+            "SELECT COUNT(*) AS c FROM action_outcomes WHERE profile_id = ?",
+            (profile_id,),
+        )
+        count = int(dict(rows[0])["c"]) if rows else 0
+        self._db.execute(
+            "DELETE FROM action_outcomes WHERE profile_id = ?",
+            (profile_id,),
+        )
+        return count
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def _row_to_outcome(row) -> ActionOutcome:
+        """Convert a DB row to ActionOutcome."""
+        d = dict(row)
+        return ActionOutcome(
+            outcome_id=d["outcome_id"],
+            profile_id=d["profile_id"],
+            query=d.get("query", ""),
+            fact_ids=json.loads(d.get("fact_ids_json", "[]")),
+            outcome=d.get("outcome", ""),
+            context=json.loads(d.get("context_json", "{}")),
+            timestamp=d.get("timestamp", ""),
+        )