superlocalmemory 3.8.13 → 4.0.0

package/src/superlocalmemory/attribution/mathematical_dna.py

@@ -1,235 +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
-
-"""Self-enforcing inter-layer parameter constraints.
-
-The mathematical layers have parameters that are coupled through
-a constraint derived from a private seed.  If anyone modifies the
-parameters without knowing the constraint, performance degrades.
-
-Constraint: alpha * kappa = C * beta
-Where:
-    alpha = metric scaling parameter
-    kappa  = curvature parameter
-    beta   = inverse temperature
-    C      = derived from private HMAC key
-
-If the constraint is violated:
-    - Similarity calibration drifts
-    - Hierarchical distance fidelity drops
-    - Energy landscape flattens
-    - Overall retrieval quality drops 15-20%
-
-Part of Qualixar | Author: Varun Pratap Bhardwaj
-License: AGPL-3.0-or-later
-"""
-
-from __future__ import annotations
-
-import hashlib
-import hmac
-import os
-
-import numpy as np
-
-# Hopfield inverse temperature (legacy constant, kept for DNA compatibility)
-HOPFIELD_INVERSE_TEMP = 4.0
-
-# Default seed — production should use env var SLM_DNA_SEED
-_DNA_SEED = "qualixar-slm-alpha-dna-v1"
-
-
-class MathematicalDNA:
-    """Self-enforcing parameter constraint system.
-
-    Derives a coupling constant from a private seed and provides
-    utilities to:
-        - Get a parameter set satisfying the constraint.
-        - Verify whether arbitrary parameters satisfy it.
-        - Compute an integrity score (1.0 = perfect).
-        - Embed / detect computation fingerprints at the precision level.
-
-    Args:
-        seed: Override the DNA seed.  If ``None``, falls back to
-              ``SLM_DNA_SEED`` env var, then the built-in default.
-    """
-
-    def __init__(self, seed: str | None = None) -> None:
-        self._seed = seed or os.environ.get("SLM_DNA_SEED", _DNA_SEED)
-        self._constraint_C = self._derive_constraint()
-
-    # ── Constraint derivation ─────────────────────────────────────
-
-    def _derive_constraint(self) -> float:
-        """Derive the inter-layer coupling constant from seed.
-
-        Uses HMAC-SHA256 to produce a deterministic float in [0.5, 2.0].
-
-        Returns:
-            Coupling constant C.
-        """
-        h = hmac.new(
-            self._seed.encode("utf-8"),
-            b"layer-coupling",
-            hashlib.sha256,
-        )
-        hash_int = int(h.hexdigest()[:8], 16)
-        return 0.5 + (hash_int / 0xFFFFFFFF) * 1.5
-
-    # ── Parameter generation ──────────────────────────────────────
-
-    def get_coupled_parameters(self) -> dict[str, float | bool]:
-        """Get a parameter set satisfying the constraint.
-
-        Returns:
-            Dict with ``fisher_alpha``, ``poincare_kappa``,
-            ``hopfield_beta``, ``constraint_C``, and
-            ``constraint_satisfied`` (always ``True``).
-        """
-        beta = HOPFIELD_INVERSE_TEMP
-        target_product = self._constraint_C * beta
-
-        kappa = abs(self._constraint_C)
-        alpha = target_product / kappa if kappa > 1e-10 else 1.0
-
-        return {
-            "fisher_alpha": float(alpha),
-            "poincare_kappa": float(kappa),
-            "hopfield_beta": float(beta),
-            "constraint_C": float(self._constraint_C),
-            "constraint_satisfied": True,
-        }
-
-    # ── Constraint verification ───────────────────────────────────
-
-    def verify_constraint(
-        self,
-        alpha: float,
-        kappa: float,
-        beta: float,
-        tolerance: float = 0.01,
-    ) -> bool:
-        """Check if parameters satisfy alpha * kappa ≈ C * beta.
-
-        Args:
-            alpha: Metric scaling parameter.
-            kappa: Curvature parameter.
-            beta: Inverse temperature.
-            tolerance: Relative tolerance for the check.
-
-        Returns:
-            ``True`` if the constraint is satisfied.
-        """
-        lhs = alpha * kappa
-        rhs = self._constraint_C * beta
-        denom = max(abs(rhs), 1e-10)
-        return abs(lhs - rhs) / denom < tolerance
-
-    def compute_integrity_score(
-        self,
-        alpha: float,
-        kappa: float,
-        beta: float,
-    ) -> float:
-        """Compute integrity score in [0, 1].  1.0 = perfect.
-
-        The score multiplies retrieval quality — violation degrades
-        performance through a sigmoid penalty.
-
-        Args:
-            alpha: Metric scaling parameter.
-            kappa: Curvature parameter.
-            beta: Inverse temperature.
-
-        Returns:
-            Integrity score in [0.0, 1.0].
-        """
-        lhs = alpha * kappa
-        rhs = self._constraint_C * beta
-        denom = max(abs(rhs), 1e-10)
-        deviation = abs(lhs - rhs) / denom
-        # Sigmoid degradation: small deviations tolerated
-        return float(1.0 / (1.0 + 10.0 * deviation ** 2))
-
-    # ── Fingerprinting ────────────────────────────────────────────
-
-    def embed_fingerprint(self, value: float, memory_id: int) -> float:
-        """Embed a computation fingerprint at the precision level.
-
-        Modifies the 12th decimal place to encode a signature.
-        The fingerprint is below the noise floor and does not affect
-        retrieval quality but can be forensically detected.
-
-        Args:
-            value: Original floating point value.
-            memory_id: Unique memory identifier for per-memory signing.
-
-        Returns:
-            Value with embedded fingerprint.
-        """
-        sig = hmac.new(
-            self._seed.encode("utf-8"),
-            f"fingerprint:{memory_id}".encode("utf-8"),
-            hashlib.sha256,
-        ).hexdigest()
-        # 8-digit fingerprint from hash, mapped to [0, 1)
-        fp = int(sig[:8], 16) / 0xFFFFFFFF
-        scale = 1e-10
-        return value + fp * scale
-
-    def detect_fingerprint(
-        self,
-        value: float,
-        memory_id: int,
-        original: float,
-    ) -> bool:
-        """Check if a value carries our fingerprint.
-
-        Args:
-            value: The potentially fingerprinted value.
-            memory_id: Memory ID used during embedding.
-            original: The original pre-fingerprint value.
-
-        Returns:
-            ``True`` if the fingerprint is detected.
-        """
-        expected = self.embed_fingerprint(original, memory_id)
-        return abs(value - expected) < 1e-14
-
-    def generate_dna_hash(self, memory_id: int) -> str:
-        """Generate a unique DNA hash for a memory.
-
-        This hash can be stored alongside the memory for provenance.
-
-        Args:
-            memory_id: Memory identifier.
-
-        Returns:
-            Hex digest string (64 chars).
-        """
-        return hmac.new(
-            self._seed.encode("utf-8"),
-            f"dna:{memory_id}".encode("utf-8"),
-            hashlib.sha256,
-        ).hexdigest()
-
-    def verify_dna_hash(self, memory_id: int, dna_hash: str) -> bool:
-        """Verify that a DNA hash matches the expected value.
-
-        Args:
-            memory_id: Memory identifier.
-            dna_hash: Hash to verify.
-
-        Returns:
-            ``True`` if the hash is valid.
-        """
-        expected = self.generate_dna_hash(memory_id)
-        return hmac.compare_digest(expected, dna_hash)
-
-    # ── Properties ────────────────────────────────────────────────
-
-    @property
-    def constraint_C(self) -> float:
-        """The derived coupling constant."""
-        return self._constraint_C

package/src/superlocalmemory/cli/post_install.py

@@ -1,114 +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
-
-"""Post-install script for npm package.
-
-Runs after `npm install -g superlocalmemory`. Detects V2 installations,
-prompts for migration, and runs the setup wizard for new users.
-"""
-
-from __future__ import annotations
-
-import sys
-from pathlib import Path
-
-
-def run_post_install():
-    """Main post-install entry point."""
-    print()
-    print("SuperLocalMemory V3")
-    print("=" * 30)
-    print()
-
-    # Upgrade banner — fires when a prior-version user runs
-    # ``npm install -g superlocalmemory@latest``. Silent on fresh
-    # installs (setup wizard handles welcome).
-    try:
-        from superlocalmemory import __version__ as _slm_ver
-        from superlocalmemory.cli.version_banner import (
-            check_and_emit_upgrade_banner,
-        )
-        if check_and_emit_upgrade_banner(_slm_ver):
-            # Upgrade detected — the banner already covered it;
-            # skip the V2 path + fresh-install copy and return.
-            return
-    except Exception:
-        pass
-
-    # Step 1: Check for V2 installation
-    from superlocalmemory.storage.v2_migrator import V2Migrator
-
-    migrator = V2Migrator()
-
-    if migrator.detect_v2() and not migrator.is_already_migrated():
-        _handle_v2_upgrade(migrator)
-    else:
-        _handle_fresh_install()
-
-
-def _handle_v2_upgrade(migrator):
-    """Handle upgrade from V2."""
-    stats = migrator.get_v2_stats()
-
-    print("Existing V2 installation detected!")
-    print(f"  Database: {stats.get('db_path', '~/.superlocalmemory/memory.db')}")
-    print(f"  Memories: {stats.get('memory_count', 'unknown')}")
-    print(f"  Profiles: {stats.get('profile_count', 1)}")
-    print()
-    print("V3 requires a one-time migration to upgrade your database.")
-    print("Your data will be preserved. A backup is created automatically.")
-    print("You can rollback anytime within 30 days.")
-    print()
-
-    choice = input("Run migration now? [Y/n]: ").strip().lower()
-
-    if choice in ("", "y", "yes"):
-        print()
-        print("Migrating...")
-        result = migrator.migrate()
-
-        if result.get("success"):
-            print()
-            for step in result.get("steps", []):
-                print(f"  [ok] {step}")
-            print()
-            print("Migration complete!")
-            print(f"  V3 database: {result.get('v3_db', '')}")
-            print(f"  Backup: {result.get('backup_db', '')}")
-            print()
-            # Run setup wizard after migration
-            _run_setup()
-        else:
-            print(f"Migration failed: {result.get('error', 'unknown')}")
-            print("Your V2 data is untouched. Run `slm migrate` to try again.")
-            sys.exit(1)
-    else:
-        print()
-        print("Migration skipped. Run `slm migrate` when ready.")
-        print("Note: V3 features are unavailable until you migrate.")
-
-
-def _handle_fresh_install():
-    """Handle fresh install (no V2 detected)."""
-    from superlocalmemory.storage.v2_migrator import V2Migrator
-
-    migrator = V2Migrator()
-
-    if migrator.is_already_migrated():
-        print("V3 already configured. Run `slm setup` to reconfigure.")
-        return
-
-    print("Welcome! Let's set up SuperLocalMemory V3.")
-    _run_setup()
-
-
-def _run_setup():
-    """Run the interactive setup wizard."""
-    from superlocalmemory.cli.setup_wizard import run_wizard
-
-    run_wizard()
-
-
-if __name__ == "__main__":
-    run_post_install()

package/src/superlocalmemory/core/clock_monitor.py

@@ -1,45 +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
-
-"""Wall-clock jump detector.
-
-Part of Qualixar | Author: Varun Pratap Bhardwaj
-"""
-
-from __future__ import annotations
-
-from typing import Literal, Optional
-
-Event = Literal["forward", "backward"]
-
-
-class ClockJumpDetector:
-    """Detects NTP-style jumps by comparing wall-clock and monotonic deltas."""
-
-    def __init__(self, threshold_s: float = 1.0) -> None:
-        self._threshold = threshold_s
-        self._last_wall: Optional[float] = None
-        self._last_mono: Optional[float] = None
-        self.last_drift_s: float = 0.0
-        self.last_event: Optional[Event] = None
-
-    def tick(self, wall: float, monotonic: float) -> Optional[Event]:
-        if self._last_wall is None or self._last_mono is None:
-            self._last_wall = wall
-            self._last_mono = monotonic
-            return None
-        dw = wall - self._last_wall
-        dm = monotonic - self._last_mono
-        drift = dw - dm
-        self._last_wall = wall
-        self._last_mono = monotonic
-        self.last_drift_s = drift
-        if abs(drift) < self._threshold:
-            self.last_event = None
-            return None
-        self.last_event = "forward" if drift > 0 else "backward"
-        return self.last_event
-
-    def drift_magnitude_s(self) -> float:
-        return abs(self.last_drift_s)

package/src/superlocalmemory/core/db_pool.py

@@ -1,80 +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
-
-"""Simple bounded SQLite connection pool.
-
-Part of Qualixar | Author: Varun Pratap Bhardwaj
-"""
-
-from __future__ import annotations
-
-import sqlite3
-import threading
-from contextlib import contextmanager
-from queue import Empty, Queue
-from typing import Callable, Iterator
-
-
-class ConnectionPool:
-    """Bounded pool of SQLite connections created on-demand."""
-
-    def __init__(
-        self,
-        opener: Callable[[], sqlite3.Connection],
-        size: int = 8,
-    ) -> None:
-        if size < 1:
-            raise ValueError("size must be >= 1")
-        self._opener = opener
-        self._size = size
-        self._available: Queue[sqlite3.Connection] = Queue(maxsize=size)
-        self._created = 0
-        self._lock = threading.Lock()
-        self._closed = False
-        self._all: list[sqlite3.Connection] = []
-
-    def _get_or_create(self, timeout: float | None) -> sqlite3.Connection:
-        try:
-            return self._available.get_nowait()
-        except Empty:
-            pass
-        with self._lock:
-            if self._closed:
-                raise RuntimeError("pool is closed")
-            if self._created < self._size:
-                conn = self._opener()
-                self._all.append(conn)
-                self._created += 1
-                return conn
-        # Pool saturated — block for a returned connection
-        try:
-            return self._available.get(timeout=timeout)
-        except Empty as exc:
-            raise TimeoutError("timed out acquiring DB connection") from exc
-
-    @contextmanager
-    def acquire(self, timeout: float | None = 30.0) -> Iterator[sqlite3.Connection]:
-        if self._closed:
-            raise RuntimeError("pool is closed")
-        conn = self._get_or_create(timeout)
-        try:
-            yield conn
-        finally:
-            if not self._closed:
-                self._available.put(conn)
-
-    def close(self) -> None:
-        with self._lock:
-            if self._closed:
-                return
-            self._closed = True
-        for conn in self._all:
-            try:
-                conn.close()
-            except Exception:
-                pass
-        self._all.clear()
-
-    def size(self) -> int:
-        return self._size

package/src/superlocalmemory/core/error_catalog.py

@@ -1,113 +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
-
-"""User-facing strings for queue error codes."""
-
-from __future__ import annotations
-
-from typing import TypedDict
-
-from superlocalmemory.core.error_envelope import ErrorCode
-
-
-class ErrorEntry(TypedDict):
-    code: str
-    title: str
-    cli_message: str
-    recovery: list[str]
-    exit_code: int
-
-
-CATALOG: dict[str, ErrorEntry] = {
-    ErrorCode.RATE_LIMITED.value: {
-        "code": "RATE_LIMITED",
-        "title": "Rate limited",
-        "cli_message": "Too many recalls in the last second.",
-        "recovery": [
-            "Wait a moment and try again.",
-            "For batch work, export SLM_RATE_LIMIT_PER_AGENT=50 and restart the daemon.",
-        ],
-        "exit_code": 3,
-    },
-    ErrorCode.QUEUE_FULL.value: {
-        "code": "QUEUE_FULL",
-        "title": "Queue is full",
-        "cli_message": "The request queue cannot accept more work right now.",
-        "recovery": [
-            "Retry with backoff.",
-            "Run: slm queue status",
-        ],
-        "exit_code": 5,
-    },
-    ErrorCode.TIMEOUT.value: {
-        "code": "TIMEOUT",
-        "title": "Timed out",
-        "cli_message": "The recall did not finish in the allotted time.",
-        "recovery": [
-            "Retry.",
-            "Run: slm doctor",
-        ],
-        "exit_code": 2,
-    },
-    ErrorCode.CANCELLED.value: {
-        "code": "CANCELLED",
-        "title": "Cancelled",
-        "cli_message": "The request was cancelled before it completed.",
-        "recovery": ["Re-issue the request if needed."],
-        "exit_code": 6,
-    },
-    ErrorCode.DEAD_LETTER.value: {
-        "code": "DEAD_LETTER",
-        "title": "Request failed after retries",
-        "cli_message": (
-            "The request could not complete after the maximum number of "
-            "attempts. Your query is preserved in the dead-letter queue."
-        ),
-        "recovery": [
-            "Inspect: slm queue dlq",
-            "Run: slm doctor",
-        ],
-        "exit_code": 4,
-    },
-    ErrorCode.DAEMON_DOWN.value: {
-        "code": "DAEMON_DOWN",
-        "title": "Daemon unreachable",
-        "cli_message": "Cannot reach the SLM daemon.",
-        "recovery": [
-            "Start the daemon: slm daemon start",
-            "Check status: slm daemon status",
-        ],
-        "exit_code": 7,
-    },
-    ErrorCode.INTERNAL.value: {
-        "code": "INTERNAL",
-        "title": "Internal error",
-        "cli_message": "An unexpected internal error occurred.",
-        "recovery": [
-            "Run: slm doctor",
-            "If the issue persists, file an issue with the log excerpt.",
-        ],
-        "exit_code": 8,
-    },
-}
-
-
-def lookup(code: str | ErrorCode) -> ErrorEntry:
-    key = code.value if isinstance(code, ErrorCode) else code
-    if key not in CATALOG:
-        return CATALOG[ErrorCode.INTERNAL.value]
-    return CATALOG[key]
-
-
-def format_cli(code: str | ErrorCode, detail: str | None = None) -> str:
-    entry = lookup(code)
-    lines = [f"\u2717 {entry['title']}"]
-    lines.append(f"  {entry['cli_message']}")
-    if detail:
-        lines.append(f"  Detail: {detail}")
-    if entry["recovery"]:
-        lines.append("  Try:")
-        for step in entry["recovery"]:
-            lines.append(f"    - {step}")
-    return "\n".join(lines)

package/src/superlocalmemory/core/loop_watchdog.py

@@ -1,56 +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
-
-"""Tick-based watchdog that fires once when a cooperative loop goes silent.
-
-Part of Qualixar | Author: Varun Pratap Bhardwaj
-"""
-
-from __future__ import annotations
-
-import threading
-import time
-from typing import Callable, Optional
-
-
-class LoopWatchdog:
-    def __init__(
-        self,
-        stale_threshold_s: float,
-        on_stale: Optional[Callable[[float], None]] = None,
-    ) -> None:
-        self._threshold = stale_threshold_s
-        self._on_stale = on_stale
-        self._last_tick = time.monotonic()
-        self._fired = False
-        self._lock = threading.Lock()
-
-    def tick(self) -> None:
-        with self._lock:
-            self._last_tick = time.monotonic()
-            self._fired = False
-
-    def age_s(self) -> float:
-        with self._lock:
-            return time.monotonic() - self._last_tick
-
-    def is_stale(self) -> bool:
-        return self.age_s() >= self._threshold
-
-    def check(self) -> bool:
-        """Fire callback once if stale; return True if just fired."""
-        with self._lock:
-            age = time.monotonic() - self._last_tick
-            if age < self._threshold or self._fired:
-                return False
-            self._fired = True
-            cb = self._on_stale
-        if cb is not None:
-            cb(age)
-        return True
-
-    def run_forever(self, stop: threading.Event, interval_s: float = 1.0) -> None:
-        while not stop.is_set():
-            self.check()
-            stop.wait(timeout=interval_s)