superlocalmemory 4.1.13 → 4.1.14

package/src/superlocalmemory/core/ram_lock.py

@@ -1,160 +0,0 @@
-# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
-# Licensed under AGPL-3.0-or-later - see LICENSE file
-# Part of SuperLocalMemory v3.4.22 — LLD-00 §7 + P0.5
-
-"""Process-wide RAM semaphore for heavyweight consolidation subsystems.
-
-LLD-00 §7: hnswlib index builds (LLD-12) and trigram full rebuilds
-(LLD-13) both spike RAM into the hundreds of MB. Running them
-concurrently in the same consolidation tick can blow past the I2 RAM
-ceiling on Light/Minimal profiles. This semaphore serialises them.
-
-Design notes:
-- One flock per process pair (exclusive, non-blocking with poll loop).
-- Fast-fail if psutil reports less than ``MIN_FREE_MB + required_mb``
-  available before we even try — better to defer than thrash.
-- Lock file lives at ``~/.superlocalmemory/ram_lock.sem`` by default,
-  tests may monkeypatch ``RAM_LOCK_PATH``.
-- Uses a standard-library advisory lock on POSIX and Windows.  The lock is
-  deliberately file-backed so independent daemon, CLI, and worker processes
-  share the same RAM reservation.
-"""
-
-from __future__ import annotations
-
-import os
-import time
-from contextlib import contextmanager
-from pathlib import Path
-from typing import Iterator
-
-import psutil
-
-try:  # POSIX advisory locks (macOS/Linux)
-    import fcntl as _fcntl
-except ImportError:  # Windows uses the stdlib byte-range equivalent below.
-    _fcntl = None
-
-# Public override retained for tests and embedders. ``None`` means resolve the
-# lock dynamically so a long-lived process can switch canonical namespaces
-# without retaining the first root it observed.
-RAM_LOCK_PATH: Path | None = None
-MIN_FREE_MB: int = 400
-
-
-def _ram_lock_path() -> Path:
-    if RAM_LOCK_PATH is not None:
-        return RAM_LOCK_PATH
-    from superlocalmemory.infra.data_root import state_path
-
-    return state_path("ram_lock.sem")
-
-
-def _acquire_lock(fd: int) -> None:
-    """Acquire one non-blocking cross-process lock for the semaphore."""
-    if _fcntl is not None:
-        _fcntl.flock(fd, _fcntl.LOCK_EX | _fcntl.LOCK_NB)
-        return
-
-    import msvcrt
-
-    # ``msvcrt.locking`` cannot reserve an empty file.  The marker byte is
-    # purely structural; the human-readable audit marker is written after the
-    # reservation is acquired.
-    if os.fstat(fd).st_size == 0:
-        os.write(fd, b"\0")
-    os.lseek(fd, 0, os.SEEK_SET)
-    try:
-        msvcrt.locking(fd, msvcrt.LK_NBLCK, 1)
-    except OSError as exc:
-        raise BlockingIOError("RAM reservation is already held") from exc
-
-
-def _release_lock(fd: int) -> None:
-    """Release a reservation acquired by :func:`_acquire_lock`."""
-    if _fcntl is not None:
-        _fcntl.flock(fd, _fcntl.LOCK_UN)
-        return
-
-    import msvcrt
-
-    os.lseek(fd, 0, os.SEEK_SET)
-    msvcrt.locking(fd, msvcrt.LK_UNLCK, 1)
-
-
-@contextmanager
-def ram_reservation(
-    name: str,
-    *,
-    timeout_s: float = 60.0,
-    required_mb: int = 200,
-) -> Iterator[None]:
-    """Process-wide RAM semaphore. Acquire before heavy subsystems.
-
-    Usage::
-
-        with ram_reservation('hnswlib', required_mb=200):
-            build_index(...)
-
-    Guarantees:
-
-    - Fast-fails if ``psutil.virtual_memory().available < (MIN_FREE_MB +
-      required_mb) * 1024 * 1024``. No body execution in that case.
-    - Acquires the exclusive flock on ``RAM_LOCK_PATH`` with a polling
-      wait. Raises ``RuntimeError`` after ``timeout_s``.
-    - Releases the lock on normal exit AND on exception propagation.
-    - Writes a short audit line ``<pid>:<name>\\n`` on acquire so
-      an operator can see which subsystem holds it.
-    """
-    if not isinstance(name, str) or not name:
-        raise ValueError("name must be a non-empty string")
-    if not isinstance(required_mb, int) or required_mb < 0:
-        raise ValueError(f"required_mb must be non-negative int, got {required_mb!r}")
-
-    vm = psutil.virtual_memory()
-    free_mb = vm.available / (1024 * 1024)
-    floor_mb = MIN_FREE_MB + required_mb
-    if free_mb < floor_mb:
-        raise RuntimeError(
-            f"ram_reservation({name}): free {free_mb:.0f}MB < required "
-            f"{floor_mb}MB"
-        )
-
-    lock_path = _ram_lock_path()
-    lock_path.parent.mkdir(parents=True, exist_ok=True)
-    # SEC-M6 — tighten the parent dir so the audit marker (``{pid}:{name}``)
-    # is not readable by other UIDs on shared hosts. Idempotent; POSIX-only.
-    try:
-        if os.name == "posix":
-            os.chmod(lock_path.parent, 0o700)
-    except OSError:  # pragma: no cover — perms race
-        pass
-    fd = os.open(str(lock_path), os.O_CREAT | os.O_RDWR, 0o600)
-    try:
-        deadline = time.time() + timeout_s
-        while True:
-            try:
-                _acquire_lock(fd)
-                break
-            except BlockingIOError:
-                if time.time() >= deadline:
-                    raise RuntimeError(
-                        f"ram_reservation({name}) timeout after {timeout_s:.1f}s"
-                    )
-                time.sleep(0.05)
-        try:
-            # Truncate + write a fresh audit marker.
-            os.ftruncate(fd, 0)
-            os.lseek(fd, 0, os.SEEK_SET)
-            os.write(fd, f"{os.getpid()}:{name}\n".encode("utf-8"))
-        except OSError:  # pragma: no cover — marker write is best-effort
-            pass
-        yield
-    finally:
-        try:
-            _release_lock(fd)
-        finally:
-            os.close(fd)
-
-
-__all__ = ("RAM_LOCK_PATH", "MIN_FREE_MB", "ram_reservation")

package/src/superlocalmemory/core/rate_limit.py

@@ -1,151 +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
-
-"""Layered token-bucket rate limiter.
-
-Part of Qualixar | Author: Varun Pratap Bhardwaj
-"""
-
-from __future__ import annotations
-
-import threading
-import time
-from dataclasses import dataclass, field
-
-from superlocalmemory.core.error_envelope import ErrorCode
-
-
-class RateLimitedError(Exception):
-    def __init__(
-        self,
-        layer: str,
-        retry_after_ms: int,
-        message: str | None = None,
-        **extras: object,
-    ) -> None:
-        self.layer = layer
-        self.retry_after_ms = retry_after_ms
-        self.code = ErrorCode.RATE_LIMITED
-        self.extras = extras
-        super().__init__(message or f"{layer} rate limit exceeded")
-
-
-class TokenBucket:
-    __slots__ = ("rate", "capacity", "tokens", "last_refill")
-
-    def __init__(self, rate_per_sec: float, capacity: float | None = None) -> None:
-        self.rate = float(rate_per_sec)
-        self.capacity = float(capacity) if capacity is not None else float(rate_per_sec)
-        self.tokens = self.capacity
-        self.last_refill = time.monotonic()
-
-    def _refill(self, now: float) -> None:
-        delta = now - self.last_refill
-        if delta > 0:
-            self.tokens = min(self.capacity, self.tokens + delta * self.rate)
-            self.last_refill = now
-
-    def can_consume(self, cost: float = 1.0) -> bool:
-        self._refill(time.monotonic())
-        return self.tokens >= cost
-
-    def try_consume(self, cost: float = 1.0) -> bool:
-        now = time.monotonic()
-        self._refill(now)
-        if self.tokens >= cost:
-            self.tokens -= cost
-            return True
-        return False
-
-    def consume(self, cost: float = 1.0) -> None:
-        self.tokens -= cost
-
-    def ms_to_refill(self, cost: float = 1.0) -> int:
-        self._refill(time.monotonic())
-        needed = max(0.0, cost - self.tokens)
-        if self.rate <= 0:
-            return 1_000_000
-        return int((needed / self.rate) * 1000) + 1
-
-
-@dataclass
-class _PidEntry:
-    bucket: TokenBucket
-    last_used: float = field(default_factory=time.monotonic)
-
-
-class LayeredRateLimiter:
-    def __init__(
-        self,
-        *,
-        global_rps: float = 100.0,
-        per_pid_rps: float = 30.0,
-        per_agent_rps: float = 10.0,
-        idle_ttl_s: float = 60.0,
-    ) -> None:
-        self._global = TokenBucket(global_rps)
-        self._per_pid_rps = per_pid_rps
-        self._per_agent_rps = per_agent_rps
-        self._idle_ttl_s = idle_ttl_s
-        self._per_pid: dict[int, _PidEntry] = {}
-        self._per_agent: dict[str, _PidEntry] = {}
-        self._lock = threading.RLock()
-
-    def _sweep(self, now: float) -> None:
-        cutoff = now - self._idle_ttl_s
-        for k in [p for p, e in self._per_pid.items() if e.last_used < cutoff]:
-            del self._per_pid[k]
-        for k in [a for a, e in self._per_agent.items() if e.last_used < cutoff]:
-            del self._per_agent[k]
-
-    def _get_pid(self, pid: int, now: float) -> TokenBucket:
-        entry = self._per_pid.get(pid)
-        if entry is None:
-            entry = _PidEntry(TokenBucket(self._per_pid_rps), now)
-            self._per_pid[pid] = entry
-        entry.last_used = now
-        return entry.bucket
-
-    def _get_agent(self, agent_id: str, now: float) -> TokenBucket:
-        entry = self._per_agent.get(agent_id)
-        if entry is None:
-            entry = _PidEntry(TokenBucket(self._per_agent_rps), now)
-            self._per_agent[agent_id] = entry
-        entry.last_used = now
-        return entry.bucket
-
-    def check_and_consume(self, *, pid: int, agent_id: str | None = None) -> None:
-        """Peek all layers; raise on any reject without touching others.
-
-        On admission, consume one token from each applicable bucket.
-        """
-        with self._lock:
-            now = time.monotonic()
-            self._sweep(now)
-            pid_bucket = self._get_pid(pid, now)
-            agent_bucket = self._get_agent(agent_id, now) if agent_id else None
-            if not self._global.can_consume():
-                raise RateLimitedError(
-                    "global", self._global.ms_to_refill(),
-                )
-            if not pid_bucket.can_consume():
-                raise RateLimitedError(
-                    "per-pid", pid_bucket.ms_to_refill(), pid=pid,
-                )
-            if agent_bucket is not None and not agent_bucket.can_consume():
-                raise RateLimitedError(
-                    "per-agent", agent_bucket.ms_to_refill(), agent=agent_id,
-                )
-            self._global.consume()
-            pid_bucket.consume()
-            if agent_bucket is not None:
-                agent_bucket.consume()
-
-    def per_pid_size(self) -> int:
-        with self._lock:
-            return len(self._per_pid)
-
-    def per_agent_size(self) -> int:
-        with self._lock:
-            return len(self._per_agent)

package/src/superlocalmemory/core/recall_gate.py

@@ -1,95 +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
-
-"""v3.4.32: Recall-in-flight counter used to give /search priority over the
-pending materializer.
-
-Every recall handler calls ``begin_recall()`` on entry and ``end_recall()``
-in a finally block. The pending-memory materializer thread polls
-``in_flight()`` and sleeps while any recall is active, so the shared
-embedder worker never serves a materialization ahead of a user-initiated
-recall.
-"""
-from __future__ import annotations
-
-import threading
-from contextlib import contextmanager
-from typing import Callable, Iterator
-
-_condition = threading.Condition(threading.Lock())
-_active = 0
-_work_context = threading.local()
-
-
-def begin_recall() -> None:
-    global _active
-    with _condition:
-        _active += 1
-
-
-def end_recall() -> None:
-    global _active
-    with _condition:
-        _active = max(0, _active - 1)
-        if _active == 0:
-            _condition.notify_all()
-
-
-def in_flight() -> int:
-    with _condition:
-        return _active
-
-
-@contextmanager
-def background_work(
-    *,
-    preempt_requested: Callable[[], bool] | None = None,
-) -> Iterator[None]:
-    """Mark best-effort work that must yield shared inference to recall.
-
-    The marker is thread-local because materialization, health probes, and
-    interactive handlers all share one resident engine and one embedder.
-    Nested callers restore the previous marker on exit.  A daemon-owned
-    materializer may also provide a preemption callback for a profile/runtime
-    reconfigure.  Inference clients use that callback to cut a bounded
-    background request short instead of holding the transition drain lease.
-    """
-    previous = bool(getattr(_work_context, "background", False))
-    previous_preempt = getattr(_work_context, "preempt_requested", None)
-    _work_context.background = True
-    _work_context.preempt_requested = (
-        preempt_requested if preempt_requested is not None else previous_preempt
-    )
-    try:
-        yield
-    finally:
-        _work_context.background = previous
-        _work_context.preempt_requested = previous_preempt
-
-
-def is_background_work() -> bool:
-    """Return whether the current thread is running best-effort work."""
-    return bool(getattr(_work_context, "background", False))
-
-
-def background_preempt_requested() -> bool:
-    """Return whether daemon-owned background work must release its lease."""
-    callback = getattr(_work_context, "preempt_requested", None)
-    if not callable(callback):
-        return False
-    try:
-        return bool(callback())
-    except Exception:
-        # A status read is advisory.  It must not crash a materializer or turn
-        # a valid recall into an ingestion failure.
-        return False
-
-
-def wait_for_foreground_idle() -> None:
-    """Block background inference while an interactive recall is active."""
-    if not is_background_work():
-        return
-    with _condition:
-        while _active > 0:
-            _condition.wait(timeout=0.1)