superlocalmemory 3.4.25 → 3.4.30

package/src/superlocalmemory/core/engine_capabilities.py

@@ -0,0 +1,24 @@
+# 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
+
+"""MemoryEngine capability levels.
+
+LIGHT: SQLite + profile only. Suitable for clients that must stay small in
+memory (e.g. multi-IDE MCP processes) and route heavy work elsewhere.
+
+FULL: DB layer + embedder + retrieval engine + LLM. Matches the historical
+v3.4.25 engine surface exactly and remains the default for backward compat.
+"""
+from __future__ import annotations
+
+import enum
+
+
+class Capabilities(enum.Enum):
+    LIGHT = "light"
+    FULL = "full"
+
+
+class CapabilityError(RuntimeError):
+    """Raised when a LIGHT-mode engine is asked for a FULL-mode operation."""

package/src/superlocalmemory/core/engine_lock.py

@@ -0,0 +1,75 @@
+# 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
+
+"""Reader-writer lock used by the shared worker engine.
+
+Part of Qualixar | Author: Varun Pratap Bhardwaj
+"""
+
+from __future__ import annotations
+
+import threading
+from contextlib import contextmanager
+from typing import Iterator
+
+
+class EngineRWLock:
+    """Writer-priority reader-writer lock.
+
+    Usage:
+        lock = EngineRWLock()
+        with lock.read():
+            ...
+        with lock.write():
+            ...
+
+    Not reentrant.
+    """
+
+    __slots__ = ("_cond", "_readers", "_writers_waiting", "_writer_active")
+
+    def __init__(self) -> None:
+        self._cond = threading.Condition()
+        self._readers: int = 0
+        self._writers_waiting: int = 0
+        self._writer_active: bool = False
+
+    @contextmanager
+    def read(self) -> Iterator[None]:
+        with self._cond:
+            while self._writer_active or self._writers_waiting > 0:
+                self._cond.wait()
+            self._readers += 1
+        try:
+            yield
+        finally:
+            with self._cond:
+                self._readers -= 1
+                if self._readers == 0:
+                    self._cond.notify_all()
+
+    @contextmanager
+    def write(self) -> Iterator[None]:
+        with self._cond:
+            self._writers_waiting += 1
+            try:
+                while self._readers > 0 or self._writer_active:
+                    self._cond.wait()
+                self._writer_active = True
+            finally:
+                self._writers_waiting -= 1
+        try:
+            yield
+        finally:
+            with self._cond:
+                self._writer_active = False
+                self._cond.notify_all()
+
+    def stats(self) -> dict[str, int | bool]:
+        with self._cond:
+            return {
+                "readers": self._readers,
+                "writers_waiting": self._writers_waiting,
+                "writer_active": self._writer_active,
+            }

package/src/superlocalmemory/core/error_catalog.py

@@ -0,0 +1,113 @@
+# 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/error_envelope.py

@@ -0,0 +1,60 @@
+# 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
+
+"""Uniform error envelope for queue-backed callers.
+
+Part of Qualixar | Author: Varun Pratap Bhardwaj
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import Any
+
+
+class ErrorCode(str, Enum):
+    RATE_LIMITED = "RATE_LIMITED"
+    QUEUE_FULL = "QUEUE_FULL"
+    TIMEOUT = "TIMEOUT"
+    CANCELLED = "CANCELLED"
+    DEAD_LETTER = "DEAD_LETTER"
+    DAEMON_DOWN = "DAEMON_DOWN"
+    INTERNAL = "INTERNAL"
+
+
+_HTTP_STATUS: dict[ErrorCode, int] = {
+    ErrorCode.RATE_LIMITED: 429,
+    ErrorCode.QUEUE_FULL: 503,
+    ErrorCode.TIMEOUT: 504,
+    ErrorCode.DEAD_LETTER: 504,
+    ErrorCode.CANCELLED: 499,
+    ErrorCode.DAEMON_DOWN: 502,
+    ErrorCode.INTERNAL: 500,
+}
+
+
+def http_status_for(code: ErrorCode) -> int:
+    return _HTTP_STATUS[code]
+
+
+def make_error_envelope(
+    code: ErrorCode,
+    message: str,
+    *,
+    request_id: str | None = None,
+    retry_after_ms: int | None = None,
+    **extras: Any,
+) -> dict[str, Any]:
+    """Build a JSON-serialisable error envelope."""
+    env: dict[str, Any] = {
+        "ok": False,
+        "error_code": code.value,
+        "error": message,
+        "request_id": request_id,
+        "retry_after_ms": retry_after_ms,
+    }
+    for k, v in extras.items():
+        if k not in env:
+            env[k] = v
+    return env

package/src/superlocalmemory/core/file_lock.py

@@ -0,0 +1,92 @@
+# 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
+
+"""Cross-platform exclusive file lock via portalocker.
+
+Part of Qualixar | Author: Varun Pratap Bhardwaj
+"""
+
+from __future__ import annotations
+
+import os
+import threading
+from contextlib import contextmanager
+from pathlib import Path
+from typing import Iterator
+
+try:
+    import portalocker
+    _HAS_PORTALOCKER = True
+except ImportError:  # pragma: no cover
+    portalocker = None  # type: ignore[assignment]
+    _HAS_PORTALOCKER = False
+
+
+class LockHeldError(RuntimeError):
+    """Raised when the lock cannot be acquired (held by another holder)."""
+
+
+class _FallbackLock:
+    """Thread-local mutex used when portalocker is unavailable."""
+
+    def __init__(self) -> None:
+        self._lock = threading.Lock()
+
+    def acquire(self, timeout: float) -> bool:
+        return self._lock.acquire(timeout=timeout)
+
+    def release(self) -> None:
+        self._lock.release()
+
+
+_fallback_registry: dict[str, _FallbackLock] = {}
+_fallback_registry_lock = threading.Lock()
+
+# Track fds held by this process so a double-acquire in the same process
+# is rejected immediately (portalocker on POSIX is permissive on same fd).
+_held_in_process: set[str] = set()
+_held_lock = threading.Lock()
+
+
+@contextmanager
+def exclusive_lock(path: Path, timeout_s: float = 0.0) -> Iterator[int]:
+    """Acquire an exclusive file lock. Raises LockHeldError on contention."""
+    path_str = str(path)
+    with _held_lock:
+        if path_str in _held_in_process:
+            raise LockHeldError(f"{path} already locked by this process")
+        _held_in_process.add(path_str)
+
+    try:
+        if _HAS_PORTALOCKER:
+            fd = os.open(str(path), os.O_RDWR | os.O_CREAT, 0o600)
+            try:
+                try:
+                    portalocker.lock(
+                        fd, portalocker.LOCK_EX | portalocker.LOCK_NB,
+                    )
+                except portalocker.LockException as exc:
+                    os.close(fd)
+                    raise LockHeldError(f"{path} is locked") from exc
+                try:
+                    yield fd
+                finally:
+                    try:
+                        portalocker.unlock(fd)
+                    finally:
+                        os.close(fd)
+            except LockHeldError:
+                raise
+        else:  # pragma: no cover — fallback path
+            with _fallback_registry_lock:
+                lk = _fallback_registry.setdefault(path_str, _FallbackLock())
+            if not lk.acquire(timeout=timeout_s):
+                raise LockHeldError(f"{path} is locked (fallback)")
+            try:
+                yield -1
+            finally:
+                lk.release()
+    finally:
+        with _held_lock:
+            _held_in_process.discard(path_str)

package/src/superlocalmemory/core/loop_watchdog.py

@@ -0,0 +1,56 @@
+# 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)

package/src/superlocalmemory/core/priority_queue.py

@@ -0,0 +1,61 @@
+# 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
+
+"""Weighted fair scheduler for high/low job lanes.
+
+Part of Qualixar | Author: Varun Pratap Bhardwaj
+"""
+
+from __future__ import annotations
+
+import threading
+from typing import Literal
+
+Lane = Literal["high", "low"]
+
+
+class WFQScheduler:
+    """Deficit-round-robin-ish scheduler over two lanes.
+
+    Tracks served counts and picks the lane whose ratio is furthest
+    below its target share. Approximates the target ratio over any
+    rolling window without requiring a time source.
+    """
+
+    def __init__(self, high_weight: int = 70, low_weight: int = 30) -> None:
+        if high_weight <= 0 or low_weight <= 0:
+            raise ValueError("weights must be positive")
+        self.high_weight = high_weight
+        self.low_weight = low_weight
+        self._served = {"high": 0, "low": 0}
+        self._lock = threading.Lock()
+
+    def pick_lane(self, *, has_high: bool, has_low: bool) -> Lane | None:
+        if not has_high and not has_low:
+            return None
+        if has_high and not has_low:
+            return "high"
+        if has_low and not has_high:
+            return "low"
+        with self._lock:
+            total = self._served["high"] + self._served["low"]
+            if total == 0:
+                return "high"
+            total_weight = self.high_weight + self.low_weight
+            high_target = self.high_weight / total_weight
+            low_target = self.low_weight / total_weight
+            high_ratio = self._served["high"] / total
+            low_ratio = self._served["low"] / total
+            # Pick whichever lane is further below its target
+            high_deficit = high_target - high_ratio
+            low_deficit = low_target - low_ratio
+            return "high" if high_deficit >= low_deficit else "low"
+
+    def record_served(self, lane: Lane) -> None:
+        with self._lock:
+            self._served[lane] += 1
+
+    def snapshot(self) -> dict[str, int]:
+        with self._lock:
+            return dict(self._served)

package/src/superlocalmemory/core/queue_dispatcher.py

@@ -0,0 +1,73 @@
+# 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
+
+"""Queue-backed dispatcher coordinator.
+
+Part of Qualixar | Author: Varun Pratap Bhardwaj
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Any
+
+from superlocalmemory.core import rate_limit as rl
+from superlocalmemory.core import recall_queue as rq
+from superlocalmemory.core.engine_lock import EngineRWLock
+
+
+class QueueDispatcher:
+    """Coordinates rate-limit check, enqueue, and poll for callers."""
+
+    def __init__(
+        self,
+        *,
+        db_path: Path | str,
+        global_rps: float = 100.0,
+        per_pid_rps: float = 30.0,
+        per_agent_rps: float = 10.0,
+    ) -> None:
+        self.queue = rq.RecallQueue(db_path=db_path)
+        self.engine_lock = EngineRWLock()
+        self._rate = rl.LayeredRateLimiter(
+            global_rps=global_rps,
+            per_pid_rps=per_pid_rps,
+            per_agent_rps=per_agent_rps,
+        )
+        # Module handles kept for test introspection.
+        self.rl = rl
+        self.rq = rq
+
+    def _check_rate(self, *, pid: int, agent_id: str | None) -> None:
+        self._rate.check_and_consume(pid=pid, agent_id=agent_id)
+
+    def dispatch(
+        self,
+        *,
+        query: str,
+        limit_n: int,
+        mode: str,
+        agent_id: str,
+        session_id: str,
+        tenant_id: str = "",
+        namespace: str = "",
+        priority: str = "high",
+        stall_timeout_s: float = 25.0,
+        timeout_s: float = 30.0,
+    ) -> dict[str, Any]:
+        self._check_rate(pid=os.getpid(), agent_id=agent_id)
+        rid = self.queue.enqueue(
+            query=query, limit_n=limit_n, mode=mode,
+            agent_id=agent_id, session_id=session_id,
+            tenant_id=tenant_id, namespace=namespace,
+            priority=priority, stall_timeout_s=stall_timeout_s,
+        )
+        try:
+            return self.queue.poll_result(rid, timeout_s=timeout_s)
+        finally:
+            self.queue.unsubscribe(rid)
+
+    def close(self) -> None:
+        self.queue.close()