superlocalmemory 4.1.13 → 4.1.14

package/src/superlocalmemory/summaries/session_summary.py

@@ -1,311 +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
-
-"""Session Summary — issue #113 bounded summary.
-
-CRITICAL DATA HONESTY NOTE
----------------------------
-On a real 3,294-fact store, only 127 facts (3.9%) carry a session_id.
-A Session Summary that presents itself as "everything you did this session"
-while silently covering 4% of the facts is overclaiming — the same defect
-removed from brain/truth.py.
-
-Coverage is ALWAYS disclosed.  If the session has too few facts to summarise
-meaningfully we say so; we never silently return partial data as complete.
-
-DETERMINISTIC FALLBACK IS MANDATORY
--------------------------------------
-Mode A users have no LLM at all.  Mode B/C users lose theirs whenever Ollama
-or the network is down.  Every call to generate_session_summary() MUST return
-a SummaryResult.  It may say the data is insufficient; it may never return
-None or an empty result.  The extractive fallback path is always active.
-
-HOT PATH EXCLUSION
--------------------
-This module must NEVER be imported from core/recall_pipeline.py or
-core/store_pipeline.py.  Summary generation performs multi-table reads and
-optional LLM calls.  It belongs in background maintenance or on explicit
-user request only.
-"""
-
-from __future__ import annotations
-
-import logging
-import sqlite3
-from datetime import date, timezone
-from pathlib import Path
-
-from .base import (
-    clean_llm_summary,
-    format_highlight,
-    SUMMARY_SYSTEM_PROMPT,
-    COVERAGE_FULL,
-    COVERAGE_INSUFFICIENT,
-    COVERAGE_NO_SESSION,
-    COVERAGE_PARTIAL,
-    COVERAGE_UNAVAILABLE,
-    GENERATED_BY_EXTRACTIVE,
-    GENERATED_BY_LLM_B,
-    GENERATED_BY_LLM_C,
-    SummaryResult,
-    get_mode_str,
-)
-
-logger = logging.getLogger("superlocalmemory.summaries.session")
-
-# Minimum number of session facts to attempt a meaningful summary.
-# Below this threshold we return coverage=insufficient and a stub.
-_MIN_FACTS = 3
-
-# Maximum facts to include in the content body (extractive mode).
-_BODY_FACTS = 7
-
-# Maximum character length for a single fact in the body.
-_MAX_FACT_CHARS = 250
-
-
-def generate_session_summary(
-    db_path: str | Path,
-    session_id: str,
-    profile_id: str = "default",
-    config: object | None = None,
-) -> SummaryResult:
-    """Generate a Session Summary for a specific session.
-
-    COVERAGE DISCLOSURE: session data is sparse on real stores (~3.9% of
-    facts carry a session_id).  The returned SummaryResult.coverage is always
-    set to an accurate value — never "full" unless the session is truly
-    complete.
-
-    Args:
-        db_path:    Path to memory.db.
-        session_id: The session identifier (atomic_facts.session_id).
-        profile_id: Profile scope — never mix profiles.
-        config:     Optional SLMConfig for LLM mode (B/C).  None = Mode A
-                    (extractive only, always deterministic).
-
-    Returns:
-        SummaryResult with source_fact_ids for every contributing fact.
-        Never returns None.
-
-    Note:
-        This function is NOT on the hot path.  It belongs in background
-        maintenance or on explicit user request, never inside recall or store.
-    """
-    db_path = Path(db_path)
-
-    # ── query ────────────────────────────────────────────────────────────────
-    try:
-        conn = sqlite3.connect(str(db_path), timeout=5.0)
-        conn.row_factory = sqlite3.Row
-        conn.execute("PRAGMA query_only=ON")
-        try:
-            rows = conn.execute(
-                """
-                SELECT fact_id, content, created_at, importance, lifecycle
-                FROM   atomic_facts
-                WHERE  profile_id  = ?
-                  AND  session_id  = ?
-                  AND  lifecycle  != 'archived'
-                ORDER  BY importance DESC, created_at ASC
-                """,
-                (profile_id, session_id),
-            ).fetchall()
-        finally:
-            conn.close()
-    except Exception as exc:
-        logger.warning("session summary query failed for %s: %s", session_id, exc)
-        return SummaryResult(
-            kind="session",
-            profile_id=profile_id,
-            content=(
-                f"Session summary for '{session_id}' is unavailable: "
-                f"data access error."
-            ),
-            source_fact_ids=[],
-            coverage=COVERAGE_UNAVAILABLE,
-            generated_by=GENERATED_BY_EXTRACTIVE,
-            metadata={"session_id": session_id, "error": str(exc)},
-        )
-
-    # ── coverage decision ─────────────────────────────────────────────────────
-    if not rows:
-        return SummaryResult(
-            kind="session",
-            profile_id=profile_id,
-            content=(
-                f"No facts found for session '{session_id}'.  "
-                f"Note: only a small fraction of facts carry a session_id "
-                f"on the current store — coverage is inherently partial."
-            ),
-            source_fact_ids=[],
-            coverage=COVERAGE_NO_SESSION,
-            generated_by=GENERATED_BY_EXTRACTIVE,
-            metadata={"session_id": session_id, "fact_count": 0},
-        )
-
-    facts = [dict(r) for r in rows]
-    source_fact_ids = [f["fact_id"] for f in facts]
-    fact_count = len(facts)
-
-    if fact_count < _MIN_FACTS:
-        coverage = COVERAGE_INSUFFICIENT
-    else:
-        # Session summaries are structurally partial: they cover only the facts
-        # that happened to carry a session_id.  On a real store that is ~3.9%
-        # of the corpus.  Reporting "full" would be dishonest.
-        coverage = COVERAGE_PARTIAL
-
-    # ── extractive summary (deterministic, always available) ──────────────────
-    extractive_content = _build_extractive_content(session_id, facts, fact_count)
-
-    # ── LLM enrichment (optional) ─────────────────────────────────────────────
-    mode = get_mode_str(config)
-    if fact_count >= _MIN_FACTS and mode in ("b", "c"):
-        llm_content, llm_mode = _try_llm(
-            f"Summarise the key activities in session {session_id}",
-            facts,
-            config,
-            mode,
-        )
-        if llm_content:
-            return SummaryResult(
-                kind="session",
-                profile_id=profile_id,
-                content=llm_content,
-                source_fact_ids=source_fact_ids,
-                coverage=coverage,
-                generated_by=llm_mode,
-                metadata={"session_id": session_id, "fact_count": fact_count},
-            )
-
-    return SummaryResult(
-        kind="session",
-        profile_id=profile_id,
-        content=extractive_content,
-        source_fact_ids=source_fact_ids,
-        coverage=coverage,
-        generated_by=GENERATED_BY_EXTRACTIVE,
-        metadata={"session_id": session_id, "fact_count": fact_count},
-    )
-
-
-# ── helpers ──────────────────────────────────────────────────────────────────
-
-def _build_extractive_content(
-    session_id: str,
-    facts: list[dict],
-    fact_count: int,
-) -> str:
-    """Build a deterministic extractive summary from session facts.
-
-    Coverage is disclosed in the header.  Top facts by importance are listed.
-    This is the fallback path — it must never fail or return an empty string.
-    """
-    lines = [
-        f"Session: {session_id}",
-        f"Facts recorded: {fact_count}",
-        f"Coverage: partial (session facts are a subset of the full store)",
-        "",
-        "Top recorded facts:",
-    ]
-    for f in facts[:_BODY_FACTS]:
-        content = f.get("content", "")
-        content = format_highlight(content)
-        lines.append(f"  - {content}")
-    if fact_count > _BODY_FACTS:
-        lines.append(f"  ... and {fact_count - _BODY_FACTS} more facts.")
-    return "\n".join(lines)
-
-
-def _try_llm(
-    prompt: str,
-    facts: list[dict],
-    config: object | None,
-    mode: str,
-) -> tuple[str | None, str]:
-    """Attempt LLM summarisation.  Returns (content, generated_by) or (None, extractive)."""
-    if mode == "c":
-        result = _call_cloud_llm(prompt, facts, config)
-        if result:
-            return result, GENERATED_BY_LLM_C
-        # fall through to Mode B
-    if mode in ("b", "c"):
-        result = _call_ollama(prompt, facts, config)
-        if result:
-            return result, GENERATED_BY_LLM_B
-    return None, GENERATED_BY_EXTRACTIVE
-
-
-def _call_ollama(
-    prompt: str,
-    facts: list[dict],
-    config: object | None,
-) -> str | None:
-    """Mode B: call Ollama.  Returns None on any failure."""
-    try:
-        import json
-        import urllib.request
-
-        api_base = "http://localhost:11434"
-        model = "llama3.2"
-        timeout = 30
-        if config and hasattr(config, "llm"):
-            api_base = getattr(config.llm, "api_base", api_base) or api_base
-            model = getattr(config.llm, "model", model) or model
-            timeout = (
-                getattr(config.llm, "timeout_seconds", None)
-                or getattr(config.llm, "timeout", None)
-                or timeout
-            )
-
-        fact_texts = "\n".join(f"- {f['content']}" for f in facts[:10])
-        full_prompt = f"{prompt}\n\nFacts:\n{fact_texts}\n\nRespond in 2-4 sentences."
-        payload = json.dumps({
-            "model": model,
-            "prompt": full_prompt,
-            "system": SUMMARY_SYSTEM_PROMPT,
-            "stream": False,
-            "options": {"num_predict": 200},
-        }).encode()
-        req = urllib.request.Request(
-            f"{api_base}/api/generate",
-            data=payload,
-            headers={"Content-Type": "application/json"},
-        )
-        resp = urllib.request.urlopen(req, timeout=timeout)
-        data = json.loads(resp.read().decode())
-        text = clean_llm_summary(data.get("response", ""))
-        return text if text and len(text) > 20 else None
-    except Exception as exc:
-        logger.debug("Ollama session summary failed: %s", exc)
-        return None
-
-
-def _call_cloud_llm(
-    prompt: str,
-    facts: list[dict],
-    config: object | None,
-) -> str | None:
-    """Mode C: call the configured cloud LLM.  Returns None on any failure."""
-    if not config or not hasattr(config, "llm"):
-        return None
-    try:
-        from superlocalmemory.llm.backbone import LLMBackbone
-        llm = LLMBackbone(config.llm)
-        if not llm.is_available():
-            return None
-        fact_texts = "\n".join(f"- {f['content']}" for f in facts[:10])
-        full_prompt = f"{prompt}\n\nFacts:\n{fact_texts}\n\nRespond in 2-4 sentences."
-        text = llm.generate(
-            prompt=full_prompt,
-            system=SUMMARY_SYSTEM_PROMPT,
-            max_tokens=200,
-            temperature=0.1,
-        )
-        cleaned = clean_llm_summary(text or "")
-        return cleaned if len(cleaned) > 20 else None
-    except Exception as exc:
-        logger.debug("Cloud LLM session summary failed: %s", exc)
-        return None

package/src/superlocalmemory/trust/gate.py

@@ -1,171 +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
-
-"""SuperLocalMemory V3 — Trust Gate (Pre-Operation Checks).
-
-Enforces minimum trust thresholds before allowing write/delete operations.
-Read operations always pass but are logged for audit purposes.
-
-Part of Qualixar | Author: Varun Pratap Bhardwaj
-"""
-
-from __future__ import annotations
-
-import logging
-import os
-from typing import TYPE_CHECKING
-
-if TYPE_CHECKING:
-    from superlocalmemory.trust.scorer import TrustScorer
-
-logger = logging.getLogger(__name__)
-
-
-def _env_threshold(name: str, default: float) -> float:
-    """Read a [0,1] threshold from the environment, falling back on parse/range error."""
-    try:
-        value = float(os.environ.get(name, ""))
-    except (TypeError, ValueError):
-        return default
-    return value if 0.0 <= value <= 1.0 else default
-
-
-# M-02/M-03 (3.7.9): thresholds are operator-tunable so multi-agent deployments
-# can tighten the write gate and opt into a read gate. Defaults are unchanged —
-# the audit's "raise write_threshold to 0.7" would block every new agent (a new
-# agent scores 0.5, Beta(1,1)); loopback callers bypass the gate entirely, so
-# this only affects remote credentialed agents. Read gate is OFF by default.
-_DEFAULT_WRITE_THRESHOLD = _env_threshold("SLM_TRUST_WRITE_THRESHOLD", 0.3)
-_DEFAULT_DELETE_THRESHOLD = _env_threshold("SLM_TRUST_DELETE_THRESHOLD", 0.5)
-_DEFAULT_READ_THRESHOLD = _env_threshold("SLM_TRUST_READ_THRESHOLD", 0.1)
-_READ_GATE_ENABLED = os.environ.get("SLM_TRUST_READ_GATE") == "1"
-
-
-class TrustError(PermissionError):
-    """Raised when an agent fails a trust check.
-
-    Attributes:
-        agent_id: The agent that failed the check.
-        trust_score: The agent's current trust score.
-        threshold: The minimum required trust score.
-        operation: The operation that was attempted.
-    """
-
-    def __init__(
-        self,
-        agent_id: str,
-        trust_score: float,
-        threshold: float,
-        operation: str,
-    ) -> None:
-        self.agent_id = agent_id
-        self.trust_score = trust_score
-        self.threshold = threshold
-        self.operation = operation
-        super().__init__(
-            f"Agent '{agent_id}' trust {trust_score:.3f} below "
-            f"{operation} threshold {threshold:.3f}"
-        )
-
-
-class TrustGate:
-    """Pre-operation trust checks.
-
-    Operations are gated by minimum trust thresholds:
-    - write: agent must have trust >= write_threshold (default 0.3)
-    - delete: agent must have trust >= delete_threshold (default 0.5)
-    - read: always passes (logged for audit trail)
-
-    Raises TrustError if the agent's trust is too low.
-    """
-
-    def __init__(
-        self,
-        scorer: TrustScorer,
-        write_threshold: float = _DEFAULT_WRITE_THRESHOLD,
-        delete_threshold: float = _DEFAULT_DELETE_THRESHOLD,
-        read_threshold: float = _DEFAULT_READ_THRESHOLD,
-        read_gate_enabled: bool = _READ_GATE_ENABLED,
-    ) -> None:
-        if write_threshold < 0 or write_threshold > 1:
-            raise ValueError("write_threshold must be in [0, 1]")
-        if delete_threshold < 0 or delete_threshold > 1:
-            raise ValueError("delete_threshold must be in [0, 1]")
-        if read_threshold < 0 or read_threshold > 1:
-            raise ValueError("read_threshold must be in [0, 1]")
-
-        self._scorer = scorer
-        self._write_threshold = write_threshold
-        self._delete_threshold = delete_threshold
-        self._read_threshold = read_threshold
-        self._read_gate_enabled = read_gate_enabled
-
-    @property
-    def write_threshold(self) -> float:
-        return self._write_threshold
-
-    @property
-    def delete_threshold(self) -> float:
-        return self._delete_threshold
-
-    def check_write(self, agent_id: str, profile_id: str) -> None:
-        """Check if agent is trusted enough to write.
-
-        Raises:
-            TrustError: If agent trust is below write_threshold.
-        """
-        score = self._scorer.get_agent_trust(agent_id, profile_id)
-        logger.debug(
-            "trust gate write: agent=%s trust=%.3f threshold=%.3f",
-            agent_id, score, self._write_threshold,
-        )
-        if score < self._write_threshold:
-            raise TrustError(
-                agent_id, score, self._write_threshold, "write"
-            )
-
-    def check_delete(self, agent_id: str, profile_id: str) -> None:
-        """Check if agent is trusted enough to delete.
-
-        Delete requires higher trust than write because it is destructive.
-
-        Raises:
-            TrustError: If agent trust is below delete_threshold.
-        """
-        score = self._scorer.get_agent_trust(agent_id, profile_id)
-        logger.debug(
-            "trust gate delete: agent=%s trust=%.3f threshold=%.3f",
-            agent_id, score, self._delete_threshold,
-        )
-        if score < self._delete_threshold:
-            raise TrustError(
-                agent_id, score, self._delete_threshold, "delete"
-            )
-
-    @property
-    def read_threshold(self) -> float:
-        return self._read_threshold
-
-    @property
-    def read_gate_enabled(self) -> bool:
-        return self._read_gate_enabled
-
-    def check_read(self, agent_id: str, profile_id: str) -> None:
-        """Read check. Passes by default; logged for the audit trail.
-
-        M-03 (3.7.9): reads are unblocked by default because denying read access
-        could break agent functionality. Operators who need to stop a
-        compromised agent from exfiltrating the store can set
-        ``SLM_TRUST_READ_GATE=1`` (optionally with ``SLM_TRUST_READ_THRESHOLD``)
-        to enforce a minimum trust for reads too.
-        """
-        score = self._scorer.get_agent_trust(agent_id, profile_id)
-        logger.debug(
-            "trust gate read: agent=%s trust=%.3f gate=%s",
-            agent_id, score, self._read_gate_enabled,
-        )
-        if self._read_gate_enabled and score < self._read_threshold:
-            raise TrustError(
-                agent_id, score, self._read_threshold, "read"
-            )

package/src/superlocalmemory/trust/provenance.py

@@ -1,124 +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
-
-"""SuperLocalMemory V3 — Provenance Tracking.
-
-Records who/what created each memory and how.
-V1 had provenance as WRITE-ONLY (stored but never read).
-Innovation wires reads into trust scoring and compliance audit.
-
-Part of Qualixar | Author: Varun Pratap Bhardwaj
-"""
-
-from __future__ import annotations
-
-import logging
-from datetime import UTC, datetime
-
-from superlocalmemory.storage.models import ProvenanceRecord
-
-logger = logging.getLogger(__name__)
-
-
-class ProvenanceTracker:
-    """Track provenance of all stored facts.
-
-    Every fact gets a provenance record at creation time.
-    Provenance feeds into:
-    - Trust scoring (sources with high-quality provenance get trust boost)
-    - Compliance audit (GDPR right-to-know: who stored what data?)
-    - Debugging (which extraction pipeline created this fact?)
-    """
-
-    def __init__(self, db) -> None:
-        self._db = db
-
-    def record(
-        self,
-        fact_id: str,
-        profile_id: str,
-        source_type: str,
-        source_id: str = "",
-        created_by: str = "",
-    ) -> ProvenanceRecord:
-        """Record provenance for a newly stored fact.
-
-        Args:
-            fact_id: The fact being tracked.
-            profile_id: Active profile.
-            source_type: "conversation", "import", "consolidation", "migration".
-            source_id: Session ID, import batch ID, etc.
-            created_by: Agent ID or user identifier.
-        """
-        record = ProvenanceRecord(
-            profile_id=profile_id,
-            fact_id=fact_id,
-            source_type=source_type,
-            source_id=source_id,
-            created_by=created_by,
-            timestamp=datetime.now(UTC).isoformat(),
-        )
-        self._db.execute(
-            "INSERT INTO provenance "
-            "(provenance_id, profile_id, fact_id, source_type, source_id, "
-            "created_by, timestamp) VALUES (?,?,?,?,?,?,?)",
-            (record.provenance_id, record.profile_id, record.fact_id,
-             record.source_type, record.source_id, record.created_by,
-             record.timestamp),
-        )
-        return record
-
-    def get_provenance(self, fact_id: str, profile_id: str) -> ProvenanceRecord | None:
-        """Get provenance for a specific fact."""
-        rows = self._db.execute(
-            "SELECT * FROM provenance WHERE fact_id = ? AND profile_id = ?",
-            (fact_id, profile_id),
-        )
-        if not rows:
-            return None
-        d = dict(rows[0])
-        return ProvenanceRecord(
-            provenance_id=d["provenance_id"],
-            profile_id=d["profile_id"],
-            fact_id=d["fact_id"],
-            source_type=d["source_type"],
-            source_id=d.get("source_id", ""),
-            created_by=d.get("created_by", ""),
-            timestamp=d["timestamp"],
-        )
-
-    def get_facts_by_source(
-        self, source_type: str, profile_id: str, limit: int = 100
-    ) -> list[ProvenanceRecord]:
-        """Get all facts from a specific source type."""
-        rows = self._db.execute(
-            "SELECT * FROM provenance WHERE source_type = ? AND profile_id = ? "
-            "ORDER BY timestamp DESC LIMIT ?",
-            (source_type, profile_id, limit),
-        )
-        return [self._row_to_record(r) for r in rows]
-
-    def get_provenance_for_profile(
-        self, profile_id: str, limit: int = 100
-    ) -> list[ProvenanceRecord]:
-        """Get all provenance records for a profile (compliance audit)."""
-        rows = self._db.execute(
-            "SELECT * FROM provenance WHERE profile_id = ? "
-            "ORDER BY timestamp DESC LIMIT ?",
-            (profile_id, limit),
-        )
-        return [self._row_to_record(r) for r in rows]
-
-    @staticmethod
-    def _row_to_record(row) -> ProvenanceRecord:
-        d = dict(row)
-        return ProvenanceRecord(
-            provenance_id=d["provenance_id"],
-            profile_id=d["profile_id"],
-            fact_id=d["fact_id"],
-            source_type=d["source_type"],
-            source_id=d.get("source_id", ""),
-            created_by=d.get("created_by", ""),
-            timestamp=d["timestamp"],
-        )