superlocalmemory 2.8.5 → 3.0.0

package/src/superlocalmemory/cli/setup_wizard.py

@@ -0,0 +1,129 @@
+# 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
+
+"""Interactive setup wizard for first-time configuration.
+
+Guides new users through mode selection and provider setup.
+
+Part of Qualixar | Author: Varun Pratap Bhardwaj
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+
+
+def run_wizard() -> None:
+    """Run the interactive setup wizard."""
+    print()
+    print("SuperLocalMemory V3 — First Time Setup")
+    print("=" * 40)
+    print()
+    print("Choose your operating mode:")
+    print()
+    print("  [A] Local Guardian (default)")
+    print("      Zero cloud. Zero LLM. Your data never leaves your machine.")
+    print("      EU AI Act compliant. Works immediately.")
+    print()
+    print("  [B] Smart Local")
+    print("      Local LLM via Ollama for answer synthesis.")
+    print("      Still private — nothing leaves your machine.")
+    print()
+    print("  [C] Full Power")
+    print("      Cloud LLM for best accuracy (~78% on LoCoMo).")
+    print("      Requires: API key from a supported provider.")
+    print()
+
+    choice = input("Select mode [A/B/C] (default: A): ").strip().lower() or "a"
+
+    if choice not in ("a", "b", "c"):
+        print(f"Invalid choice: {choice}. Using Mode A.")
+        choice = "a"
+
+    from superlocalmemory.core.config import SLMConfig
+    from superlocalmemory.storage.models import Mode
+
+    if choice == "a":
+        config = SLMConfig.for_mode(Mode.A)
+        config.save()
+        print()
+        print("Mode A configured. Zero cloud, zero LLM.")
+        print(f"Config saved to: {config.base_dir / 'config.json'}")
+
+    elif choice == "b":
+        config = SLMConfig.for_mode(Mode.B)
+        print()
+        print("Checking for Ollama...")
+        if shutil.which("ollama"):
+            print("  Ollama found!")
+        else:
+            print("  Ollama not found. Install it from https://ollama.ai")
+            print("  After installing, run: ollama pull llama3.2")
+        config.save()
+        print(f"Config saved to: {config.base_dir / 'config.json'}")
+
+    elif choice == "c":
+        config = SLMConfig.for_mode(Mode.C)
+        configure_provider(config)
+
+    print()
+    print("Ready! Your AI now remembers you.")
+    print()
+
+
+def configure_provider(config: object) -> None:
+    """Configure LLM provider for Mode C.
+
+    Args:
+        config: An SLMConfig instance (typed as object to avoid circular import
+                at module level; actual type checked at runtime).
+    """
+    from superlocalmemory.core.config import SLMConfig
+    from superlocalmemory.storage.models import Mode
+
+    presets = SLMConfig.provider_presets()
+
+    print()
+    print("Choose your LLM provider:")
+    print()
+    providers = list(presets.keys())
+    for i, name in enumerate(providers, 1):
+        preset = presets[name]
+        print(f"  [{i}] {name.capitalize()} — {preset['model']}")
+    print()
+
+    idx = input(f"Select provider [1-{len(providers)}]: ").strip()
+    try:
+        provider_name = providers[int(idx) - 1]
+    except (ValueError, IndexError):
+        print("Invalid choice. Using OpenAI.")
+        provider_name = "openai"
+
+    preset = presets[provider_name]
+
+    # Resolve API key from environment or prompt
+    env_key = preset.get("env_key", "")
+    api_key = ""
+    if env_key:
+        existing = os.environ.get(env_key, "")
+        if existing:
+            print(f"  Found {env_key} in environment.")
+            api_key = existing
+        else:
+            api_key = input(
+                f"  Enter your {provider_name.capitalize()} API key: ",
+            ).strip()
+
+    updated = SLMConfig.for_mode(
+        Mode.C,
+        llm_provider=provider_name,
+        llm_model=preset["model"],
+        llm_api_key=api_key,
+        llm_api_base=preset["base_url"],
+    )
+    updated.save()
+    print(f"  Provider: {provider_name}")
+    print(f"  Model: {preset['model']}")
+    print(f"Config saved to: {updated.base_dir / 'config.json'}")

package/src/superlocalmemory/compliance/abac.py

@@ -0,0 +1,204 @@
+# 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
+
+"""Attribute-Based Access Control for memory operations.
+
+Evaluates policies: (agent_id, profile_id, action) -> allow/deny.
+Default: allow all (open access). Policies restrict specific agents.
+
+Actions: "read", "write", "delete", "admin".
+Policies are stored in-memory (loaded from DB on init).
+Simple deny-list approach: if a deny policy matches, access is blocked.
+"""
+
+from __future__ import annotations
+
+import logging
+import sqlite3
+from typing import Any, Optional
+
+logger = logging.getLogger(__name__)
+
+# Valid ABAC actions
+VALID_ACTIONS = frozenset({"read", "write", "delete", "admin"})
+
+_POLICY_TABLE_SQL = """
+CREATE TABLE IF NOT EXISTS abac_policies (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    profile_id TEXT NOT NULL,
+    agent_id TEXT NOT NULL,
+    action TEXT NOT NULL,
+    deny INTEGER NOT NULL DEFAULT 1,
+    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+)
+"""
+
+
+class AccessDenied(PermissionError):
+    """Raised when ABAC denies an operation."""
+
+
+class ABACEngine:
+    """Attribute-Based Access Control for memory operations.
+
+    Evaluates policies: (agent_id, profile_id, action) -> allow/deny.
+    Default: allow all (open access). Deny policies restrict specific
+    agent+profile+action combinations.
+    """
+
+    def __init__(self, db: Optional[sqlite3.Connection] = None) -> None:
+        self._policies: list[dict[str, Any]] = []
+        self._db = db
+        if db is not None:
+            self._load_policies_from_db(db)
+
+    # ------------------------------------------------------------------
+    # Policy loading
+    # ------------------------------------------------------------------
+
+    def _load_policies_from_db(self, db: sqlite3.Connection) -> None:
+        """Load policies from the abac_policies table."""
+        try:
+            db.execute(_POLICY_TABLE_SQL)
+            db.commit()
+            rows = db.execute(
+                "SELECT profile_id, agent_id, action, deny "
+                "FROM abac_policies"
+            ).fetchall()
+            for row in rows:
+                self._policies.append({
+                    "profile_id": row[0],
+                    "agent_id": row[1],
+                    "action": row[2],
+                    "deny": bool(row[3]),
+                })
+            logger.info("Loaded %d ABAC policies from DB", len(self._policies))
+        except sqlite3.OperationalError as exc:
+            logger.warning("Failed to load ABAC policies: %s", exc)
+
+    # ------------------------------------------------------------------
+    # Policy management
+    # ------------------------------------------------------------------
+
+    def add_policy(
+        self,
+        profile_id: str,
+        agent_id: str,
+        action: str,
+        deny: bool = True,
+    ) -> None:
+        """Add an access control policy.
+
+        Args:
+            profile_id: Profile this policy applies to.
+            agent_id: Agent this policy applies to.
+            action: The action to control (read/write/delete/admin).
+            deny: If True, this is a deny policy. Default True.
+        """
+        if action not in VALID_ACTIONS:
+            raise ValueError(f"Invalid action '{action}'. Must be one of {VALID_ACTIONS}")
+        policy = {
+            "profile_id": profile_id,
+            "agent_id": agent_id,
+            "action": action,
+            "deny": deny,
+        }
+        self._policies.append(policy)
+        self._persist_policy(policy)
+
+    def remove_policy(
+        self,
+        profile_id: str,
+        agent_id: str,
+        action: str,
+    ) -> None:
+        """Remove a policy matching profile_id + agent_id + action."""
+        self._policies = [
+            p for p in self._policies
+            if not (
+                p["profile_id"] == profile_id
+                and p["agent_id"] == agent_id
+                and p["action"] == action
+            )
+        ]
+        if self._db is not None:
+            try:
+                self._db.execute(
+                    "DELETE FROM abac_policies WHERE profile_id = ? AND agent_id = ? AND action = ?",
+                    (profile_id, agent_id, action),
+                )
+                self._db.commit()
+            except sqlite3.OperationalError:
+                pass
+
+    def _persist_policy(self, policy: dict[str, Any]) -> None:
+        """Write a policy to DB so it survives restart."""
+        if self._db is None:
+            return
+        try:
+            self._db.execute(
+                "INSERT INTO abac_policies (profile_id, agent_id, action, deny) "
+                "VALUES (?, ?, ?, ?)",
+                (policy["profile_id"], policy["agent_id"], policy["action"], int(policy["deny"])),
+            )
+            self._db.commit()
+        except sqlite3.OperationalError as exc:
+            logger.warning("Failed to persist ABAC policy: %s", exc)
+
+    # ------------------------------------------------------------------
+    # Access evaluation
+    # ------------------------------------------------------------------
+
+    def check(self, agent_id: str, profile_id: str, action: str) -> bool:
+        """Evaluate access. Returns True if allowed, False if denied.
+
+        Default: allow if no deny policy matches the request.
+        Deny-first semantics: any matching deny policy blocks access.
+        """
+        for policy in self._policies:
+            if not policy.get("deny", True):
+                continue
+            if (
+                policy["agent_id"] == agent_id
+                and policy["profile_id"] == profile_id
+                and policy["action"] == action
+            ):
+                return False
+        return True
+
+    def check_or_raise(
+        self,
+        agent_id: str,
+        profile_id: str,
+        action: str,
+    ) -> None:
+        """Like check() but raises AccessDenied if denied."""
+        if not self.check(agent_id, profile_id, action):
+            raise AccessDenied(
+                f"Agent '{agent_id}' denied '{action}' "
+                f"on profile '{profile_id}'"
+            )
+
+    # ------------------------------------------------------------------
+    # Policy listing
+    # ------------------------------------------------------------------
+
+    def list_policies(
+        self,
+        profile_id: Optional[str] = None,
+    ) -> list[dict[str, Any]]:
+        """List all policies, optionally filtered by profile.
+
+        Args:
+            profile_id: If provided, only return policies for this profile.
+
+        Returns:
+            List of policy dicts with keys: profile_id, agent_id, action, deny.
+        """
+        if profile_id is None:
+            return [dict(p) for p in self._policies]
+        return [
+            dict(p) for p in self._policies
+            if p["profile_id"] == profile_id
+        ]

package/src/superlocalmemory/compliance/audit.py

@@ -0,0 +1,314 @@
+# 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
+
+"""Tamper-proof hash-chain audit log for compliance.
+
+Every operation is logged with a SHA-256 hash that includes the previous
+entry's hash, creating a chain. Tampering with any entry breaks the chain
+and is detectable via verify_integrity().
+
+The audit chain uses its OWN sqlite3 connection (not shared DB manager)
+for independence — audit must survive even if the main DB is corrupted.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import logging
+import sqlite3
+import threading
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Optional, Union
+
+logger = logging.getLogger(__name__)
+
+_GENESIS_HASH = "genesis"
+
+_SCHEMA = """
+CREATE TABLE IF NOT EXISTS audit_chain (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    timestamp TEXT NOT NULL,
+    operation TEXT NOT NULL,
+    agent_id TEXT DEFAULT '',
+    profile_id TEXT DEFAULT '',
+    content_hash TEXT DEFAULT '',
+    prev_hash TEXT DEFAULT '',
+    event_hash TEXT NOT NULL,
+    metadata TEXT DEFAULT '{}'
+);
+"""
+
+
+def _compute_hash(
+    prev_hash: str,
+    operation: str,
+    agent_id: str,
+    profile_id: str,
+    content_hash: str,
+    timestamp: str,
+) -> str:
+    """Compute SHA-256 hash for an audit entry.
+
+    The hash incorporates: prev_hash + operation + agent_id +
+    profile_id + content_hash + timestamp.
+    """
+    payload = (
+        f"{prev_hash}{operation}{agent_id}"
+        f"{profile_id}{content_hash}{timestamp}"
+    )
+    return hashlib.sha256(payload.encode("utf-8")).hexdigest()
+
+
+class AuditChain:
+    """Tamper-proof hash-chain audit log for compliance.
+
+    Every operation is logged with a hash that includes the previous hash,
+    creating a chain. Tampering with any entry breaks the chain.
+
+    Uses its own SQLite connection for independence from main DB.
+    """
+
+    def __init__(self, db_path: Optional[Union[str, Path]] = None) -> None:
+        self._db_path = str(db_path) if db_path else ":memory:"
+        self._is_memory = self._db_path == ":memory:"
+        self._lock = threading.Lock()
+        # For in-memory DBs, keep a persistent connection (each connect()
+        # to ":memory:" creates a separate empty database).
+        self._persistent_conn: Optional[sqlite3.Connection] = None
+        if self._is_memory:
+            self._persistent_conn = self._make_conn()
+        self._init_db()
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def _make_conn_from_path(path: str) -> sqlite3.Connection:
+        """Create a configured SQLite connection."""
+        conn = sqlite3.connect(path)
+        conn.execute("PRAGMA journal_mode=WAL")
+        conn.row_factory = sqlite3.Row
+        return conn
+
+    def _make_conn(self) -> sqlite3.Connection:
+        """Create a new configured connection to the audit database."""
+        return self._make_conn_from_path(self._db_path)
+
+    def _get_conn(self) -> sqlite3.Connection:
+        """Get a connection to the audit database.
+
+        For in-memory databases, returns the persistent connection.
+        For file databases, creates a new connection each time.
+        """
+        if self._is_memory and self._persistent_conn is not None:
+            return self._persistent_conn
+        return self._make_conn()
+
+    def _release_conn(self, conn: sqlite3.Connection) -> None:
+        """Release a connection. Only closes file-based connections."""
+        if not self._is_memory:
+            conn.close()
+
+    def _init_db(self) -> None:
+        """Initialize the audit_chain table."""
+        conn = self._get_conn()
+        try:
+            conn.executescript(_SCHEMA)
+            conn.commit()
+        finally:
+            self._release_conn(conn)
+
+    def _get_last_hash(self, conn: sqlite3.Connection) -> str:
+        """Get the hash of the most recent entry, or genesis."""
+        row = conn.execute(
+            "SELECT event_hash FROM audit_chain "
+            "ORDER BY id DESC LIMIT 1"
+        ).fetchone()
+        return row["event_hash"] if row else _GENESIS_HASH
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def log(
+        self,
+        operation: str,
+        agent_id: str = "",
+        profile_id: str = "",
+        content_hash: str = "",
+        metadata: Optional[dict[str, Any]] = None,
+    ) -> str:
+        """Log an audit event. Returns the event hash.
+
+        Args:
+            operation: Type of operation (store, recall, delete, etc.).
+            agent_id: ID of the agent performing the operation.
+            profile_id: ID of the profile being accessed.
+            content_hash: Hash of the content involved (optional).
+            metadata: Additional metadata dict (optional).
+
+        Returns:
+            The SHA-256 event hash for this entry.
+        """
+        ts = datetime.now(timezone.utc).isoformat()
+        metadata_str = json.dumps(metadata or {}, sort_keys=True)
+
+        with self._lock:
+            conn = self._get_conn()
+            try:
+                prev_hash = self._get_last_hash(conn)
+                event_hash = _compute_hash(
+                    prev_hash, operation, agent_id,
+                    profile_id, content_hash, ts,
+                )
+                conn.execute(
+                    "INSERT INTO audit_chain "
+                    "(timestamp, operation, agent_id, profile_id, "
+                    " content_hash, prev_hash, event_hash, metadata) "
+                    "VALUES (?, ?, ?, ?, ?, ?, ?, ?)",
+                    (
+                        ts, operation, agent_id, profile_id,
+                        content_hash, prev_hash, event_hash, metadata_str,
+                    ),
+                )
+                conn.commit()
+                return event_hash
+            finally:
+                self._release_conn(conn)
+
+    def query(
+        self,
+        profile_id: Optional[str] = None,
+        agent_id: Optional[str] = None,
+        operation: Optional[str] = None,
+        start_date: Optional[str] = None,
+        end_date: Optional[str] = None,
+        limit: int = 100,
+    ) -> list[dict[str, Any]]:
+        """Query audit events with filters.
+
+        Args:
+            profile_id: Filter by profile ID.
+            agent_id: Filter by agent ID.
+            operation: Filter by operation type.
+            start_date: ISO date string for range start.
+            end_date: ISO date string for range end.
+            limit: Maximum number of events to return.
+
+        Returns:
+            List of event dicts ordered by id descending.
+        """
+        clauses: list[str] = []
+        params: list[Any] = []
+
+        if profile_id is not None:
+            clauses.append("profile_id = ?")
+            params.append(profile_id)
+        if agent_id is not None:
+            clauses.append("agent_id = ?")
+            params.append(agent_id)
+        if operation is not None:
+            clauses.append("operation = ?")
+            params.append(operation)
+        if start_date is not None:
+            clauses.append("timestamp >= ?")
+            params.append(start_date)
+        if end_date is not None:
+            clauses.append("timestamp <= ?")
+            params.append(end_date)
+
+        where = f"WHERE {' AND '.join(clauses)}" if clauses else ""
+        sql = (
+            f"SELECT id, timestamp, operation, agent_id, profile_id, "
+            f"content_hash, prev_hash, event_hash, metadata "
+            f"FROM audit_chain {where} "
+            f"ORDER BY id DESC LIMIT ?"
+        )
+        params.append(limit)
+
+        with self._lock:
+            conn = self._get_conn()
+            try:
+                rows = conn.execute(sql, params).fetchall()
+                return [dict(r) for r in rows]
+            finally:
+                self._release_conn(conn)
+
+    def verify_integrity(self) -> bool:
+        """Verify the entire hash chain. Returns True if chain is intact.
+
+        Walks every entry in order, recomputes each hash, and verifies
+        it matches the stored hash. Any mismatch means tampering.
+        """
+        conn = self._get_conn()
+        try:
+            rows = conn.execute(
+                "SELECT id, timestamp, operation, agent_id, profile_id, "
+                "content_hash, prev_hash, event_hash "
+                "FROM audit_chain ORDER BY id"
+            ).fetchall()
+        finally:
+            self._release_conn(conn)
+
+        if not rows:
+            return True
+
+        expected_prev = _GENESIS_HASH
+        for row in rows:
+            row_dict = dict(row)
+
+            # Check the prev_hash link
+            if row_dict["prev_hash"] != expected_prev:
+                logger.warning(
+                    "Audit chain prev_hash mismatch at entry %d",
+                    row_dict["id"],
+                )
+                return False
+
+            # Recompute the entry hash
+            computed = _compute_hash(
+                row_dict["prev_hash"],
+                row_dict["operation"],
+                row_dict["agent_id"],
+                row_dict["profile_id"],
+                row_dict["content_hash"],
+                row_dict["timestamp"],
+            )
+            if computed != row_dict["event_hash"]:
+                logger.warning(
+                    "Audit chain event_hash mismatch at entry %d",
+                    row_dict["id"],
+                )
+                return False
+
+            expected_prev = row_dict["event_hash"]
+
+        return True
+
+    def get_stats(self) -> dict[str, int]:
+        """Get audit statistics (event counts by operation type).
+
+        Returns:
+            Dict mapping operation names to their counts, plus
+            a 'total' key with the chain length.
+        """
+        conn = self._get_conn()
+        try:
+            rows = conn.execute(
+                "SELECT operation, COUNT(*) AS cnt "
+                "FROM audit_chain GROUP BY operation"
+            ).fetchall()
+            stats: dict[str, int] = {}
+            total = 0
+            for row in rows:
+                count = row["cnt"]
+                stats[row["operation"]] = count
+                total += count
+            stats["total"] = total
+            return stats
+        finally:
+            self._release_conn(conn)