superlocalmemory 2.8.6 → 3.0.1

package/src/superlocalmemory/core/hooks.py

@@ -0,0 +1,65 @@
+# 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
+
+"""Engine lifecycle hooks -- pre/post operation dispatch.
+
+Pre-hooks are synchronous and can reject operations (raise exceptions).
+Post-hooks are fire-and-forget -- errors are logged, never propagated.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, Callable
+
+logger = logging.getLogger(__name__)
+
+
+class HookRegistry:
+    """Registry for engine lifecycle hooks.
+
+    Usage:
+        registry = HookRegistry()
+        registry.register_pre("store", abac_check)
+        registry.register_pre("store", trust_gate_check)
+        registry.register_post("store", audit_log)
+        registry.register_post("store", event_bus_publish)
+
+        # In engine.store():
+        registry.run_pre("store", context)   # raises if any pre-hook fails
+        # ... core operation ...
+        registry.run_post("store", context)  # never raises
+    """
+
+    def __init__(self) -> None:
+        self._pre: dict[str, list[Callable]] = {}
+        self._post: dict[str, list[Callable]] = {}
+
+    def register_pre(self, operation: str, hook: Callable[[dict[str, Any]], None]) -> None:
+        """Register a pre-operation hook. Hook receives context dict.
+        Hook can raise to reject the operation."""
+        self._pre.setdefault(operation, []).append(hook)
+
+    def register_post(self, operation: str, hook: Callable[[dict[str, Any]], None]) -> None:
+        """Register a post-operation hook. Hook receives context dict.
+        Errors are logged, never propagated."""
+        self._post.setdefault(operation, []).append(hook)
+
+    def run_pre(self, operation: str, context: dict[str, Any]) -> None:
+        """Run all pre-hooks for an operation. Raises on first failure."""
+        for hook in self._pre.get(operation, []):
+            hook(context)  # Let exceptions propagate -- this is intentional
+
+    def run_post(self, operation: str, context: dict[str, Any]) -> None:
+        """Run all post-hooks for an operation. Errors logged, never raised."""
+        for hook in self._post.get(operation, []):
+            try:
+                hook(context)
+            except Exception as exc:
+                logger.debug("Post-hook error (%s): %s", operation, exc)
+
+    def clear(self) -> None:
+        """Remove all hooks. Useful for testing."""
+        self._pre.clear()
+        self._post.clear()

package/src/superlocalmemory/core/maintenance.py

@@ -0,0 +1,172 @@
+# 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 — Background Math Maintenance.
+
+Periodic batch processing for mathematical layers:
+1. Langevin batch_step on all active facts (self-organization)
+2. Sheaf batch consistency check on recent facts
+3. Fisher adaptive temperature recalculation
+
+Frequency: every 6-24h or after 100 stores.
+~100 Langevin steps to stationarity.
+
+Part of Qualixar | Author: Varun Pratap Bhardwaj
+License: MIT
+"""
+from __future__ import annotations
+
+import logging
+from datetime import UTC, datetime, timedelta
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from superlocalmemory.core.config import SLMConfig
+    from superlocalmemory.storage.database import DatabaseManager
+
+logger = logging.getLogger(__name__)
+
+
+def run_maintenance(
+    db: DatabaseManager,
+    config: SLMConfig,
+    profile_id: str = "default",
+) -> dict[str, int]:
+    """Run background maintenance on mathematical layers.
+
+    Args:
+        db: Database manager.
+        config: Full SLM configuration.
+        profile_id: Scope to this profile.
+
+    Returns:
+        Dict of counts: langevin_updated, sheaf_checked, etc.
+    """
+    counts: dict[str, int] = {
+        "langevin_updated": 0,
+        "fisher_coupled": 0,
+        "sheaf_checked": 0,
+    }
+
+    facts = db.get_all_facts(profile_id)
+    if not facts:
+        return counts
+
+    # 1. Langevin batch step
+    if config.math.langevin_persist_positions:
+        try:
+            from superlocalmemory.math.langevin import LangevinDynamics
+
+            ld = LangevinDynamics(
+                dim=8,
+                dt=config.math.langevin_dt,
+                temperature=config.math.langevin_temperature,
+            )
+            fact_dicts = []
+            for f in facts:
+                if f.langevin_position is None:
+                    continue
+                created = datetime.fromisoformat(
+                    f.created_at.replace("Z", "+00:00")
+                ) if f.created_at else datetime.now(UTC)
+                age_days = max(
+                    0.0,
+                    (datetime.now(UTC) - created).total_seconds() / 86400.0,
+                )
+                fact_dicts.append({
+                    "fact_id": f.fact_id,
+                    "position": f.langevin_position,
+                    "access_count": f.access_count,
+                    "age_days": age_days,
+                    "importance": f.importance,
+                })
+
+            if fact_dicts:
+                results = ld.batch_step(fact_dicts)
+                for r in results:
+                    db.update_fact(r["fact_id"], {
+                        "langevin_position": r["position"],
+                        "lifecycle": r["lifecycle"],
+                    })
+                counts["langevin_updated"] = len(results)
+        except Exception as exc:
+            logger.warning("Langevin maintenance failed: %s", exc)
+
+    # 1b. Fisher-Langevin coupling: modulate temperature per-fact
+    # High Fisher confidence (low variance) -> low temperature -> memory stabilizes
+    # Low Fisher confidence (high variance) -> high temperature -> memory fades
+    if config.math.langevin_persist_positions and counts["langevin_updated"] > 0:
+        try:
+            from superlocalmemory.dynamics.fisher_langevin_coupling import (
+                FisherLangevinCoupling,
+            )
+
+            coupling = FisherLangevinCoupling(
+                base_temperature=config.math.langevin_temperature,
+            )
+            coupled_count = 0
+
+            for f in facts:
+                if f.langevin_position is None or f.fisher_variance is None:
+                    continue
+                eff_temp = coupling.get_effective_temperature(
+                    f.fisher_variance, f.access_count,
+                )
+                # Re-run Langevin step with Fisher-coupled temperature
+                # only if it differs meaningfully from the base temperature
+                if abs(eff_temp - config.math.langevin_temperature) > 0.01:
+                    from superlocalmemory.math.langevin import LangevinDynamics
+
+                    coupled_ld = LangevinDynamics(
+                        dim=8,
+                        dt=config.math.langevin_dt,
+                        temperature=eff_temp,
+                    )
+                    created = datetime.fromisoformat(
+                        f.created_at.replace("Z", "+00:00")
+                    ) if f.created_at else datetime.now(UTC)
+                    age_days = max(
+                        0.0,
+                        (datetime.now(UTC) - created).total_seconds() / 86400.0,
+                    )
+                    new_pos, weight = coupled_ld.step(
+                        position=f.langevin_position,
+                        access_count=f.access_count,
+                        age_days=age_days,
+                        importance=f.importance,
+                    )
+                    lifecycle = coupled_ld.get_lifecycle_state(weight).value
+                    db.update_fact(f.fact_id, {
+                        "langevin_position": new_pos,
+                        "lifecycle": lifecycle,
+                    })
+                    coupled_count += 1
+
+            counts["fisher_coupled"] = coupled_count
+        except Exception as exc:
+            logger.warning("Fisher-Langevin coupling failed: %s", exc)
+
+    # 2. Sheaf batch consistency on recent facts (last 24h)
+    if config.math.sheaf_at_encoding:
+        try:
+            from superlocalmemory.math.sheaf import SheafConsistencyChecker
+
+            checker = SheafConsistencyChecker(
+                db, config.math.sheaf_contradiction_threshold,
+            )
+            cutoff = (datetime.now(UTC) - timedelta(hours=24)).isoformat()
+            recent = [f for f in facts if f.created_at and f.created_at >= cutoff]
+            for f in recent:
+                if f.embedding and f.canonical_entities:
+                    checker.check_consistency(f, profile_id)
+                    counts["sheaf_checked"] += 1
+        except Exception as exc:
+            logger.warning("Sheaf maintenance failed: %s", exc)
+
+    logger.info(
+        "Maintenance complete: %d Langevin, %d Fisher-coupled, %d Sheaf",
+        counts["langevin_updated"], counts["fisher_coupled"],
+        counts["sheaf_checked"],
+    )
+    return counts

package/src/superlocalmemory/core/modes.py

@@ -0,0 +1,140 @@
+# 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 — Mode System.
+
+Three operating modes with clear capability boundaries.
+Mode A: EU AI Act FULL compliance (zero LLM).
+Mode B: EU AI Act FULL (local LLM only).
+Mode C: UNRESTRICTED — best models, full power, 90%+ target.
+
+Part of Qualixar | Author: Varun Pratap Bhardwaj
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from superlocalmemory.storage.models import Mode
+
+
+@dataclass(frozen=True)
+class ModeCapabilities:
+    """What each mode can and cannot do."""
+
+    mode: Mode
+
+    # Encoding capabilities
+    llm_fact_extraction: bool      # Can use LLM for fact extraction?
+    llm_entity_resolution: bool    # Can use LLM for entity disambiguation?
+    llm_type_classification: bool  # Can use LLM for fact type routing?
+    llm_importance_scoring: bool   # Can use LLM for importance assessment?
+
+    # Retrieval capabilities
+    agentic_retrieval: bool        # Can do multi-round LLM-guided retrieval?
+    llm_answer_generation: bool    # Can LLM generate answers from context?
+    cloud_reranker: bool           # Can use Cohere / cloud reranker?
+
+    # Embedding capabilities
+    cloud_embeddings: bool         # Can use cloud embedding API?
+    embedding_dimension: int       # Expected embedding dimension
+
+    # Compliance
+    eu_ai_act_compliant: bool      # Full EU AI Act compliance?
+    data_stays_local: bool         # Does ALL data stay on device?
+
+    # Description
+    description: str = ""
+
+
+# ---------------------------------------------------------------------------
+# Mode Definitions
+# ---------------------------------------------------------------------------
+
+MODE_A = ModeCapabilities(
+    mode=Mode.A,
+    llm_fact_extraction=False,
+    llm_entity_resolution=False,
+    llm_type_classification=False,
+    llm_importance_scoring=False,
+    agentic_retrieval=False,
+    llm_answer_generation=False,
+    cloud_reranker=False,
+    cloud_embeddings=False,
+    embedding_dimension=768,
+    eu_ai_act_compliant=True,
+    data_stays_local=True,
+    description=(
+        "Local Guardian — Zero LLM, zero cloud. "
+        "Uses nomic-embed-text-v1.5 encoder (768d, 8K context) for embeddings. "
+        "spaCy + rules for extraction. Cross-encoder for reranking. "
+        "Full EU AI Act compliance. Target: 65%+"
+    ),
+)
+
+MODE_B = ModeCapabilities(
+    mode=Mode.B,
+    llm_fact_extraction=True,
+    llm_entity_resolution=True,
+    llm_type_classification=True,
+    llm_importance_scoring=True,
+    agentic_retrieval=False,
+    llm_answer_generation=True,
+    cloud_reranker=False,
+    cloud_embeddings=False,
+    embedding_dimension=768,
+    eu_ai_act_compliant=True,
+    data_stays_local=True,
+    description=(
+        "Smart Local — Local Ollama LLM (Phi-3, Llama 3.2). "
+        "LLM-quality extraction and classification, fully local. "
+        "No cloud, no data export. EU AI Act compliant. Target: 75-80%"
+    ),
+)
+
+MODE_C = ModeCapabilities(
+    mode=Mode.C,
+    llm_fact_extraction=True,
+    llm_entity_resolution=True,
+    llm_type_classification=True,
+    llm_importance_scoring=True,
+    agentic_retrieval=True,
+    llm_answer_generation=True,
+    cloud_reranker=True,
+    cloud_embeddings=True,
+    embedding_dimension=3072,
+    eu_ai_act_compliant=False,
+    data_stays_local=False,
+    description=(
+        "FULL POWER — UNRESTRICTED. Best embeddings (text-embedding-3-large, 3072-dim). "
+        "Best LLMs (GPT-5.2, Claude Opus). Agentic multi-round retrieval. "
+        "Cohere reranker option. No EU restriction. Target: 90%+"
+    ),
+)
+
+
+def get_capabilities(mode: Mode) -> ModeCapabilities:
+    """Get capability matrix for a mode."""
+    _map = {Mode.A: MODE_A, Mode.B: MODE_B, Mode.C: MODE_C}
+    return _map[mode]
+
+
+def validate_mode_config(mode: Mode, *, has_ollama: bool = False, has_cloud_llm: bool = False) -> list[str]:
+    """Validate that required services are available for the chosen mode.
+
+    Returns list of warnings/errors. Empty list = all good.
+    """
+    issues: list[str] = []
+    caps = get_capabilities(mode)
+
+    if caps.llm_fact_extraction and mode == Mode.B and not has_ollama:
+        issues.append("Mode B requires Ollama but it is not available. Falling back to Mode A extraction.")
+
+    if caps.cloud_embeddings and not has_cloud_llm:
+        issues.append("Mode C cloud embeddings configured but no API endpoint provided.")
+
+    if caps.agentic_retrieval and not has_cloud_llm:
+        issues.append("Mode C agentic retrieval requires cloud LLM but none configured.")
+
+    return issues

package/src/superlocalmemory/core/profiles.py

@@ -0,0 +1,234 @@
+# 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 — Profile Management.
+
+First-class profile isolation. Every memory, fact, entity, and learning
+record is scoped by profile_id. Profiles are persisted in profiles.json
+with atomic writes and instant switching (config-only, zero data movement).
+
+Ported from V2.8 columnar profile isolation pattern.
+
+Part of Qualixar | Author: Varun Pratap Bhardwaj
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import re
+import tempfile
+import uuid
+from dataclasses import asdict
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Callable
+
+from superlocalmemory.core.config import DEFAULT_PROFILES_FILE
+from superlocalmemory.storage.models import Mode, Profile
+
+logger = logging.getLogger(__name__)
+
+_VALID_NAME_RE = re.compile(r"^[a-zA-Z0-9][a-zA-Z0-9_-]{0,49}$")
+_MAX_NAME_LEN = 50
+_RESERVED = "default"
+
+
+def _validate_name(name: str) -> None:
+    """Alphanumeric + dash + underscore, 1-50 chars, starts alphanumeric."""
+    if not name or len(name) > _MAX_NAME_LEN:
+        raise ValueError(f"Profile name must be 1-{_MAX_NAME_LEN} chars, got {len(name)}.")
+    if not _VALID_NAME_RE.match(name):
+        raise ValueError(
+            f"Invalid profile name '{name}'. "
+            "Must start with alphanumeric, then alphanumeric / dash / underscore."
+        )
+
+
+def _now() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+def _pid() -> str:
+    return uuid.uuid4().hex[:16]
+
+
+def _evolve(prof: Profile, **overrides: Any) -> Profile:
+    """Return a new Profile with selected fields replaced (frozen dataclass)."""
+    base = asdict(prof)
+    base.update(overrides)
+    base["mode"] = Mode(base["mode"]) if isinstance(base["mode"], str) else base["mode"]
+    return Profile(**base)
+
+
+class ProfileManager:
+    """Thread-safe profile manager with atomic JSON persistence.
+
+    Stores profile metadata in ``profiles.json`` inside *base_dir*.
+    Profiles are isolated at the DB column level (WHERE profile_id = ?).
+    Switching is instant — only the active pointer changes.
+    """
+
+    def __init__(self, base_dir: Path) -> None:
+        self._base_dir = base_dir
+        self._base_dir.mkdir(parents=True, exist_ok=True)
+        self._path = self._base_dir / DEFAULT_PROFILES_FILE
+        self._profiles: dict[str, Profile] = {}
+        self._active_name: str = _RESERVED
+        self._on_switch: Callable[[Profile], None] | None = None
+        self._load()
+
+    # -- Persistence (atomic write via tempfile + rename) ------------------
+
+    def _load(self) -> None:
+        """Load profiles.json or bootstrap with the default profile."""
+        if self._path.exists():
+            raw = json.loads(self._path.read_text(encoding="utf-8"))
+            self._active_name = raw.get("active", _RESERVED)
+            for entry in raw.get("profiles", []):
+                mode = Mode(entry["mode"]) if "mode" in entry else Mode.A
+                prof = Profile(
+                    profile_id=entry["profile_id"],
+                    name=entry["name"],
+                    description=entry.get("description", ""),
+                    personality=entry.get("personality", ""),
+                    mode=mode,
+                    created_at=entry.get("created_at", _now()),
+                    last_used=entry.get("last_used"),
+                    config=entry.get("config", {}),
+                )
+                self._profiles[prof.name] = prof
+        if _RESERVED not in self._profiles:
+            self._profiles[_RESERVED] = Profile(
+                profile_id=_pid(), name=_RESERVED,
+                description="Default memory profile", mode=Mode.A,
+                created_at=_now(),
+            )
+            self._save()
+
+    def _save(self) -> None:
+        """Atomic write: temp file in same dir, then rename."""
+        data = json.dumps(
+            {"active": self._active_name,
+             "profiles": [asdict(p) for p in self._profiles.values()]},
+            indent=2, ensure_ascii=False,
+        )
+        fd, tmp = tempfile.mkstemp(dir=str(self._base_dir), suffix=".tmp")
+        try:
+            Path(tmp).write_text(data, encoding="utf-8")
+            Path(tmp).replace(self._path)
+        finally:
+            try:
+                os.close(fd)
+            except OSError:
+                pass
+
+    # -- Event hook --------------------------------------------------------
+
+    @property
+    def on_profile_switch(self) -> Callable[[Profile], None] | None:
+        return self._on_switch
+
+    @on_profile_switch.setter
+    def on_profile_switch(self, cb: Callable[[Profile], None] | None) -> None:
+        self._on_switch = cb
+
+    # -- CRUD --------------------------------------------------------------
+
+    def create_profile(
+        self,
+        name: str,
+        description: str = "",
+        personality: str = "",
+        mode: Mode = Mode.A,
+        config: dict[str, Any] | None = None,
+    ) -> Profile:
+        """Create a new profile. Raises ValueError on duplicate or bad name."""
+        _validate_name(name)
+        if name in self._profiles:
+            raise ValueError(f"Profile '{name}' already exists.")
+        profile = Profile(
+            profile_id=_pid(), name=name, description=description,
+            personality=personality, mode=mode,
+            created_at=_now(), config=config or {},
+        )
+        self._profiles[name] = profile
+        self._save()
+        logger.info("Created profile '%s' (id=%s, mode=%s)", name, profile.profile_id, mode.value)
+        return profile
+
+    def get_profile(self, name: str) -> Profile | None:
+        """Return profile by name, or None if not found."""
+        return self._profiles.get(name)
+
+    def get_active_profile(self) -> Profile:
+        """Return the currently active profile."""
+        return self._profiles.get(self._active_name) or self._profiles[_RESERVED]
+
+    def switch_profile(self, name: str) -> Profile:
+        """Instant switch — config-only, zero data movement."""
+        if name not in self._profiles:
+            raise KeyError(f"Profile '{name}' does not exist.")
+        self._active_name = name
+        updated = _evolve(self._profiles[name], last_used=_now())
+        self._profiles[name] = updated
+        self._save()
+        logger.info("Switched to profile '%s'", name)
+        if self._on_switch is not None:
+            self._on_switch(updated)
+        return updated
+
+    def list_profiles(self) -> list[Profile]:
+        """All profiles sorted by name (default first)."""
+        profs = list(self._profiles.values())
+        profs.sort(key=lambda p: (p.name != _RESERVED, p.name))
+        return profs
+
+    def delete_profile(self, name: str) -> None:
+        """Delete a profile. Cannot delete 'default'. Data stays in DB."""
+        if name == _RESERVED:
+            raise ValueError("Cannot delete the default profile.")
+        if name not in self._profiles:
+            raise KeyError(f"Profile '{name}' does not exist.")
+        del self._profiles[name]
+        if self._active_name == name:
+            self._active_name = _RESERVED
+            logger.info("Active profile deleted — fell back to 'default'.")
+        self._save()
+        logger.info("Deleted profile '%s'. Associated data remains in DB.", name)
+
+    def rename_profile(self, old_name: str, new_name: str) -> None:
+        """Rename a profile. Cannot rename 'default'."""
+        if old_name == _RESERVED:
+            raise ValueError("Cannot rename the default profile.")
+        _validate_name(new_name)
+        if old_name not in self._profiles:
+            raise KeyError(f"Profile '{old_name}' does not exist.")
+        if new_name in self._profiles:
+            raise ValueError(f"Profile '{new_name}' already exists.")
+        old = self._profiles.pop(old_name)
+        self._profiles[new_name] = _evolve(old, name=new_name)
+        if self._active_name == old_name:
+            self._active_name = new_name
+        self._save()
+        logger.info("Renamed profile '%s' -> '%s'", old_name, new_name)
+
+    def update_profile(self, name: str, **kwargs: Any) -> Profile:
+        """Update mutable fields: description, personality, mode, config."""
+        if name not in self._profiles:
+            raise KeyError(f"Profile '{name}' does not exist.")
+        allowed = {"description", "personality", "mode", "config"}
+        overrides = {k: v for k, v in kwargs.items() if k in allowed}
+        updated = _evolve(self._profiles[name], **overrides)
+        self._profiles[name] = updated
+        self._save()
+        logger.info("Updated profile '%s'", name)
+        return updated
+
+    def export_profile(self, name: str) -> dict[str, Any]:
+        """Export profile metadata as a plain dict (for backup / migration)."""
+        if name not in self._profiles:
+            raise KeyError(f"Profile '{name}' does not exist.")
+        return asdict(self._profiles[name])