superlocalmemory 4.0.4 → 4.0.6

package/src/superlocalmemory/summaries/base.py

@@ -0,0 +1,108 @@
+# 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
+
+"""Base types for the #113 bounded summary layer."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class SummaryResult:
+    """A bounded, profile-scoped, traceable summary of user memories.
+
+    Maintainer's binding constraint (issue #113 reply):
+        "views must be customizable, profile-scoped, privacy-aware, and
+         traceable back to the underlying memories rather than becoming
+         opaque generic summaries"
+
+    This dataclass enforces three of those four constraints structurally:
+
+    Traceability
+        ``source_fact_ids`` carries the atomic_facts.fact_id for every fact
+        that contributed to this summary.  A user can always drill back to
+        the raw memories.
+
+    Profile scope
+        ``profile_id`` is mandatory; callers must never mix profiles.
+
+    Honesty / non-opaqueness
+        ``coverage`` must be set to an accurate value.  See the constants
+        below.  A summary over 3.9% of facts that presents itself as "your
+        session" is precisely the opaque generic summary the maintainer said
+        to avoid.
+
+    Generated-by
+        ``generated_by`` records whether the content is extractive
+        (deterministic, always available, Mode A default) or came from an
+        LLM (Mode B Ollama / Mode C cloud).
+
+    Attributes:
+        kind:            "session" | "daily" | "project"
+        profile_id:      Owning profile — never expose across profiles.
+        content:         Human-readable summary text.
+        source_fact_ids: IDs of the atomic_facts that contributed.
+                         Empty only when the underlying data does not exist.
+        coverage:        One of the COVERAGE_* constants below.
+        generated_by:    One of the GENERATED_BY_* constants below.
+        metadata:        Extra context: date, project_path, session_id, etc.
+    """
+
+    kind: str
+    profile_id: str
+    content: str
+    source_fact_ids: list[str]
+    coverage: str
+    generated_by: str
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+# ── coverage constants ──────────────────────────────────────────────────────
+#
+# Use these strings; the acceptance gate checks for their presence
+# and the values must be human-interpretable without this file.
+
+COVERAGE_FULL = "full"
+"""All relevant data was available and contributed to the summary."""
+
+COVERAGE_PARTIAL = "partial"
+"""Some data was available.  Session summaries are always at most partial
+because only ~3.9% of facts carry a session_id on a real store."""
+
+COVERAGE_INSUFFICIENT = "insufficient"
+"""Too few facts to produce a meaningful summary (below MIN_FACTS threshold)."""
+
+COVERAGE_NO_SESSION = "no_session"
+"""Session ID not found, or the session has no associated facts."""
+
+COVERAGE_UNAVAILABLE = "unavailable"
+"""Required data does not exist or a query error prevented access."""
+
+
+# ── generated_by constants ──────────────────────────────────────────────────
+#
+# extractive is the deterministic fallback, ALWAYS available.
+# Mode A users never get anything else.  Mode B/C users fall back when
+# Ollama or the cloud is down — silence is not an option.
+
+GENERATED_BY_EXTRACTIVE = "extractive"
+"""Deterministic extractive summary — no LLM.  Always available."""
+
+GENERATED_BY_LLM_B = "llm_b"
+"""Ollama local LLM (Mode B).  Falls back to extractive if unavailable."""
+
+GENERATED_BY_LLM_C = "llm_c"
+"""Cloud LLM (Mode C).  Falls back via llm_b to extractive."""
+
+
+def get_mode_str(config: object | None) -> str:
+    """Extract the operating mode string ('a', 'b', or 'c') from a config."""
+    if config is None:
+        return "a"
+    m = getattr(config, "mode", None)
+    if m is None:
+        return "a"
+    return getattr(m, "value", str(m)).lower()

package/src/superlocalmemory/summaries/daily_reflection.py

@@ -0,0 +1,293 @@
+# 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
+
+"""Daily Reflection — issue #113 bounded summary.
+
+Produces a human-readable summary of all facts recorded on a specific date,
+grouped by time of day and sorted by importance.
+
+MEASURED DATA REALITY
+---------------------
+On a real 3,294-fact store there are 48 distinct active days.
+Per-day volumes range from 4 to 454 facts.  Daily reflections are
+structurally viable for this store.
+
+DETERMINISTIC FALLBACK
+-----------------------
+The extractive path groups facts by topic entities and summarises the top-N
+by importance.  It never calls an LLM and never fails to return a result.
+Mode B/C enrichment is attempted when configured, but falls back to extractive
+on any failure — silence is not acceptable.
+
+HOT PATH EXCLUSION
+-------------------
+This module must NEVER be imported from core/recall_pipeline.py or
+core/store_pipeline.py.
+"""
+
+from __future__ import annotations
+
+import logging
+import sqlite3
+from datetime import date
+from pathlib import Path
+
+from .base import (
+    COVERAGE_FULL,
+    COVERAGE_INSUFFICIENT,
+    COVERAGE_UNAVAILABLE,
+    GENERATED_BY_EXTRACTIVE,
+    GENERATED_BY_LLM_B,
+    GENERATED_BY_LLM_C,
+    SummaryResult,
+    get_mode_str,
+)
+
+logger = logging.getLogger("superlocalmemory.summaries.daily")
+
+_MIN_FACTS = 2          # Below this threshold, coverage=insufficient
+_BODY_FACTS = 10        # Top-N facts shown in extractive summary
+_MAX_FACT_CHARS = 300   # Per-fact character cap in the body
+
+
+def generate_daily_reflection(
+    db_path: str | Path,
+    target_date: str | date,
+    profile_id: str = "default",
+    config: object | None = None,
+) -> SummaryResult:
+    """Generate a Daily Reflection for a specific date.
+
+    Args:
+        db_path:     Path to memory.db.
+        target_date: The date to reflect on.  Accepts ``date`` objects or
+                     ISO-format strings ("2026-08-17").
+        profile_id:  Profile scope — never mix profiles.
+        config:      Optional SLMConfig for LLM enrichment.  None = Mode A
+                     (extractive, always deterministic).
+
+    Returns:
+        SummaryResult with source_fact_ids for every contributing fact.
+        Never returns None.
+    """
+    db_path = Path(db_path)
+    date_str = target_date.isoformat() if isinstance(target_date, date) else str(target_date)
+
+    # ── 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,
+                       canonical_entities_json, lifecycle
+                FROM   atomic_facts
+                WHERE  profile_id = ?
+                  AND  DATE(created_at) = ?
+                  AND  lifecycle != 'archived'
+                ORDER  BY importance DESC, created_at ASC
+                """,
+                (profile_id, date_str),
+            ).fetchall()
+        finally:
+            conn.close()
+    except Exception as exc:
+        logger.warning("daily reflection query failed for %s: %s", date_str, exc)
+        return SummaryResult(
+            kind="daily",
+            profile_id=profile_id,
+            content=f"Daily reflection for {date_str} is unavailable: data access error.",
+            source_fact_ids=[],
+            coverage=COVERAGE_UNAVAILABLE,
+            generated_by=GENERATED_BY_EXTRACTIVE,
+            metadata={"date": date_str, "error": str(exc)},
+        )
+
+    # ── coverage decision ─────────────────────────────────────────────────────
+    if not rows:
+        return SummaryResult(
+            kind="daily",
+            profile_id=profile_id,
+            content=f"No facts recorded on {date_str}.",
+            source_fact_ids=[],
+            coverage=COVERAGE_INSUFFICIENT,
+            generated_by=GENERATED_BY_EXTRACTIVE,
+            metadata={"date": date_str, "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:
+        coverage = COVERAGE_FULL
+
+    # ── extractive summary (deterministic, always available) ──────────────────
+    extractive_content = _build_extractive_content(date_str, 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(date_str, facts, config, mode)
+        if llm_content:
+            return SummaryResult(
+                kind="daily",
+                profile_id=profile_id,
+                content=llm_content,
+                source_fact_ids=source_fact_ids,
+                coverage=coverage,
+                generated_by=llm_mode,
+                metadata={"date": date_str, "fact_count": fact_count},
+            )
+
+    return SummaryResult(
+        kind="daily",
+        profile_id=profile_id,
+        content=extractive_content,
+        source_fact_ids=source_fact_ids,
+        coverage=coverage,
+        generated_by=GENERATED_BY_EXTRACTIVE,
+        metadata={"date": date_str, "fact_count": fact_count},
+    )
+
+
+# ── helpers ──────────────────────────────────────────────────────────────────
+
+def _build_extractive_content(
+    date_str: str,
+    facts: list[dict],
+    fact_count: int,
+) -> str:
+    """Build a deterministic extractive daily reflection."""
+    import json
+
+    lines = [
+        f"Daily reflection: {date_str}",
+        f"Total facts recorded: {fact_count}",
+        "",
+        "Highlights:",
+    ]
+    for f in facts[:_BODY_FACTS]:
+        content = f.get("content", "")
+        if len(content) > _MAX_FACT_CHARS:
+            content = content[:_MAX_FACT_CHARS - 3] + "..."
+        lines.append(f"  - {content}")
+    if fact_count > _BODY_FACTS:
+        lines.append(f"  ... and {fact_count - _BODY_FACTS} additional facts.")
+
+    # Entity summary: which entities appeared most
+    entity_counts: dict[str, int] = {}
+    for f in facts:
+        raw = f.get("canonical_entities_json") or "[]"
+        try:
+            entities = json.loads(raw)
+        except (ValueError, TypeError):
+            entities = []
+        for e in entities:
+            entity_counts[e] = entity_counts.get(e, 0) + 1
+
+    if entity_counts:
+        top_entities = sorted(entity_counts.items(), key=lambda x: x[1], reverse=True)[:5]
+        entity_str = ", ".join(f"{e} ({c})" for e, c in top_entities)
+        lines.append("")
+        lines.append(f"Active entities: {entity_str}")
+
+    return "\n".join(lines)
+
+
+def _try_llm(
+    date_str: str,
+    facts: list[dict],
+    config: object | None,
+    mode: str,
+) -> tuple[str | None, str]:
+    """Attempt LLM-based daily reflection.  Returns (content, generated_by)."""
+    prompt = (
+        f"Write a concise daily reflection for {date_str} based on these facts. "
+        f"Focus on main themes and accomplishments in 3-5 sentences."
+    )
+    if mode == "c":
+        result = _call_cloud_llm(prompt, facts, config)
+        if result:
+            return result, GENERATED_BY_LLM_C
+    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 (extractive fallback)."""
+    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[:15])
+        full_prompt = f"{prompt}\n\nFacts from {len(facts)} recorded:\n{fact_texts}"
+        payload = json.dumps({
+            "model": model,
+            "prompt": full_prompt,
+            "stream": False,
+            "options": {"num_predict": 300},
+        }).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 = data.get("response", "").strip()
+        return text if text and len(text) > 20 else None
+    except Exception as exc:
+        logger.debug("Ollama daily reflection 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[:15])
+        full_prompt = f"{prompt}\n\nFacts:\n{fact_texts}"
+        text = llm.generate(
+            prompt=full_prompt,
+            system="You are a concise personal memory summariser.",
+            max_tokens=300,
+            temperature=0.1,
+        )
+        return text.strip() if text and len(text.strip()) > 20 else None
+    except Exception as exc:
+        logger.debug("Cloud LLM daily reflection failed: %s", exc)
+        return None