superlocalmemory 4.1.13 → 4.1.15

package/src/superlocalmemory/core/worker_pool.py

@@ -1,377 +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
-
-"""Recall worker pool — manages subprocess lifecycle for all callers.
-
-Single shared worker process handles requests from dashboard, MCP, CLI.
-Serializes concurrent requests via a threading lock (one at a time to
-avoid interleaved stdout). Worker auto-kills after idle timeout.
-
-Usage:
-    pool = WorkerPool.shared()
-    result = pool.recall("what is X?", limit=10)
-    result = pool.store("some content", metadata={})
-
-Part of Qualixar | Author: Varun Pratap Bhardwaj
-"""
-
-from __future__ import annotations
-
-import json
-import logging
-import os
-import subprocess
-import sys
-import threading
-import time
-
-logger = logging.getLogger(__name__)
-
-_IDLE_TIMEOUT = 120   # 2 min — kill worker after idle
-_REQUEST_TIMEOUT = 120  # 120 sec per request (V3.3.2: ONNX cold start can take 30-60s)
-_WARMUP_TIMEOUT = 180  # 3 min — first cold start: engine + ONNX export + models
-_WORKER_RECYCLE_AFTER = 1000  # Recycle worker after N requests (C++ fragmentation prevention)
-
-
-class WorkerPool:
-    """Manages a single recall_worker subprocess with idle auto-kill.
-
-    Thread-safe: concurrent callers are serialized via lock.
-    The worker subprocess holds all heavy memory (PyTorch, engine).
-    The calling process stays at ~60 MB.
-    """
-
-    _instance: WorkerPool | None = None
-    _instance_lock = threading.Lock()
-
-    def __init__(self) -> None:
-        self._lock = threading.Lock()
-        self._proc: subprocess.Popen | None = None
-        self._idle_timer: threading.Timer | None = None
-        self._last_used: float = 0.0
-        self._request_count: int = 0
-
-    @classmethod
-    def shared(cls) -> WorkerPool:
-        """Get or create the singleton worker pool."""
-        if cls._instance is None:
-            with cls._instance_lock:
-                if cls._instance is None:
-                    cls._instance = cls()
-        return cls._instance
-
-    # ------------------------------------------------------------------
-    # Public API
-    # ------------------------------------------------------------------
-
-    def recall(
-        self, query: str, limit: int = 10, session_id: str = "",
-        fast: bool = False,
-        include_global: bool | None = None,
-        include_shared: bool | None = None,
-        window: str | None = None,
-        as_of: str | None = None,
-        known_as_of: str | None = None,
-        valid_at: str | None = None,
-        include_unknown: bool = False,
-    ) -> dict:
-        """Run recall in worker subprocess. Returns result dict.
-
-        ``session_id`` threads through to ``engine.recall``, where it gives
-        the recall continuity with earlier turns of the same session. It does
-        NOT create an outcome row — this docstring claimed one for several
-        releases and none was ever written.
-
-        v3.6.15 multi-scope: ``include_global``/``include_shared`` are forwarded
-        to the worker (and on to ``engine.recall``). ``None`` is sent verbatim
-        so the worker-side engine resolves the configured default — shared
-        memory is opt-in.
-        """
-        msg: dict = {
-            "cmd": "recall", "query": query, "limit": limit,
-            "session_id": session_id or "",
-        }
-        if fast is not None:
-            msg["fast"] = bool(fast)
-        if include_global is not None:
-            msg["include_global"] = bool(include_global)
-        if include_shared is not None:
-            msg["include_shared"] = bool(include_shared)
-        if window:
-            msg["window"] = window
-        if as_of:
-            msg["as_of"] = as_of
-        if known_as_of:
-            msg["known_as_of"] = known_as_of
-        if valid_at:
-            msg["valid_at"] = valid_at
-        if include_unknown:
-            msg["include_unknown"] = True
-        return self._send(msg)
-
-    def store(self, content: str, metadata: dict | None = None) -> dict:
-        """Run store in worker subprocess. Returns result dict."""
-        return self._send({
-            "cmd": "store", "content": content,
-            "metadata": metadata or {},
-        })
-
-    def delete_memory(self, fact_id: str, agent_id: str = "system") -> dict:
-        """Delete by fact ID; ``agent_id`` is untrusted audit metadata."""
-        return self._send({
-            "cmd": "delete_memory",
-            "fact_id": fact_id,
-            "source_agent_id": agent_id,
-        })
-
-    def update_memory(self, fact_id: str, content: str, agent_id: str = "system") -> dict:
-        """Update content; ``agent_id`` is untrusted audit metadata."""
-        return self._send({
-            "cmd": "update_memory",
-            "fact_id": fact_id,
-            "content": content,
-            "source_agent_id": agent_id,
-        })
-
-    def get_memory_facts(self, memory_id: str) -> dict:
-        """Get original memory text + child atomic facts."""
-        return self._send({"cmd": "get_memory_facts", "memory_id": memory_id})
-
-    def summarize(self, texts: list[str]) -> dict:
-        """Generate summary from texts (heuristic in A, LLM in B/C)."""
-        return self._send({"cmd": "summarize", "texts": texts})
-
-    def synthesize(self, query: str, facts: list[dict]) -> dict:
-        """Generate synthesized answer from query + facts."""
-        return self._send({"cmd": "synthesize", "query": query, "facts": facts})
-
-    def status(self) -> dict:
-        """Get engine status from worker."""
-        return self._send({"cmd": "status"})
-
-    def shutdown(self) -> None:
-        """Gracefully kill the worker."""
-        with self._lock:
-            self._kill()
-
-    def warmup(self) -> None:
-        """Pre-spawn and warm up the worker in a background thread.
-
-        Spawns the recall_worker subprocess so that PyTorch, models, and
-        the engine are all loaded BEFORE the first user request. This
-        amortizes the 30s cold-start at dashboard/MCP startup time.
-
-        Call from startup events — non-blocking, runs in background.
-        """
-        def _do_warmup() -> None:
-            logger.info("Worker warmup starting (background)...")
-            try:
-                result = self._send_with_timeout(
-                    {"cmd": "warmup"}, timeout=_WARMUP_TIMEOUT,
-                )
-                if result.get("ok"):
-                    logger.info("Worker warmup complete (engine + models ready)")
-                else:
-                    logger.warning("Worker warmup returned: %s", result)
-            except Exception as exc:
-                logger.warning("Worker warmup failed: %s", exc)
-
-        t = threading.Thread(target=_do_warmup, daemon=True, name="worker-warmup")
-        t.start()
-
-    @property
-    def worker_pid(self) -> int | None:
-        """PID of the worker process, or None if not running."""
-        if self._proc and self._proc.poll() is None:
-            return self._proc.pid
-        return None
-
-    # ------------------------------------------------------------------
-    # Internals
-    # ------------------------------------------------------------------
-
-    def _send(self, request: dict) -> dict:
-        """Send request to worker and get response. Thread-safe.
-
-        Auto-retries once on worker death (idle timeout, crash).
-        """
-        resp = self._send_with_timeout(request, timeout=_REQUEST_TIMEOUT)
-        if not resp.get("ok") and "Worker" in resp.get("error", ""):
-            logger.info("Auto-restarting worker after failure, retrying request")
-            resp = self._send_with_timeout(request, timeout=_REQUEST_TIMEOUT)
-        return resp
-
-    def _send_with_timeout(self, request: dict, timeout: float) -> dict:
-        """Send request with configurable timeout. Thread-safe."""
-        with self._lock:
-            # Worker recycling: restart after N requests to prevent
-            # C++ allocator fragmentation over long-running sessions.
-            if self._request_count >= _WORKER_RECYCLE_AFTER and self._proc is not None:
-                logger.info("Recycling recall worker after %d requests", self._request_count)
-                self._kill()
-                self._request_count = 0
-
-            self._ensure_worker()
-            if self._proc is None:
-                return {"ok": False, "error": "Worker failed to start"}
-
-            req_line = json.dumps(request) + "\n"
-            try:
-                self._proc.stdin.write(req_line)
-                self._proc.stdin.flush()
-
-                # Read response with timeout using a thread.
-                # selectors/select do NOT work with pipes on Windows,
-                # so we use the same thread-based approach as EmbeddingService.
-                resp_line = self._readline_with_timeout(
-                    self._proc.stdout, timeout,
-                )
-
-                if not resp_line:
-                    logger.warning("Worker returned empty, restarting. Run 'slm doctor' to diagnose.")
-                    self._kill()
-                    return {"ok": False, "error": "Worker died"}
-
-                self._reset_idle_timer()
-                self._request_count += 1
-                return json.loads(resp_line)
-
-            except (BrokenPipeError, OSError, json.JSONDecodeError) as exc:
-                logger.warning("Worker communication failed: %s. Run 'slm doctor' to diagnose.", exc)
-                self._kill()
-                return {"ok": False, "error": str(exc)}
-
-    @staticmethod
-    def _readline_with_timeout(stream, timeout_seconds: float) -> str:
-        """Read one line from *stream* with a timeout.
-
-        Prefer a deadline-driven selector poll of the stream's file descriptor
-        (POSIX pipes). That path never spawns a helper thread, so a hung
-        worker cannot leak reader threads or pin the pipe FD across timeouts.
-        A thread fallback remains only for streams without a usable fileno
-        (unit-test mocks) and for Windows, where selectors cannot wait on
-        pipes.
-
-        Returns the line read, or ``""`` on timeout / error.
-        """
-        import selectors
-
-        timeout_seconds = max(0.0, float(timeout_seconds))
-        fd: int | None
-        try:
-            raw_fd = stream.fileno()
-            fd = raw_fd if isinstance(raw_fd, int) else None
-        except (AttributeError, OSError, ValueError, TypeError):
-            fd = None
-
-        # Windows select()/selectors only accept sockets, not subprocess pipes.
-        if fd is not None and sys.platform != "win32":
-            try:
-                with selectors.DefaultSelector() as sel:
-                    sel.register(fd, selectors.EVENT_READ)
-                    events = sel.select(timeout=timeout_seconds)
-                if not events:
-                    return ""
-                line = stream.readline()
-                return line if line else ""
-            except (OSError, ValueError):
-                return ""
-
-        result_container: list[str] = []
-        error_container: list[Exception] = []
-
-        def _read() -> None:
-            try:
-                result_container.append(stream.readline())
-            except Exception as exc:
-                error_container.append(exc)
-
-        reader = threading.Thread(target=_read, daemon=True)
-        reader.start()
-        reader.join(timeout=timeout_seconds)
-
-        if reader.is_alive():
-            return ""
-        if error_container:
-            raise error_container[0]
-        return result_container[0] if result_container else ""
-
-    def _ensure_worker(self) -> None:
-        """Spawn worker if not running."""
-        if self._proc is not None and self._proc.poll() is None:
-            return
-        self._proc = None
-        try:
-            env = {
-                **os.environ,
-                "CUDA_VISIBLE_DEVICES": "",
-                "PYTORCH_MPS_HIGH_WATERMARK_RATIO": "0.0",
-                "PYTORCH_MPS_MEM_LIMIT": "0",
-                "PYTORCH_ENABLE_MPS_FALLBACK": "1",
-                "TOKENIZERS_PARALLELISM": "false",
-                "TORCH_DEVICE": "cpu",
-            }
-            from superlocalmemory.core.platform_utils import popen_platform_kwargs
-            self._proc = subprocess.Popen(
-                [sys.executable, "-m", "superlocalmemory.core.recall_worker"],
-                stdin=subprocess.PIPE,
-                stdout=subprocess.PIPE,
-                stderr=subprocess.DEVNULL,
-                text=True,
-                bufsize=1,
-                env=env,
-                **popen_platform_kwargs(),
-            )
-            logger.info("Recall worker spawned (PID %d)", self._proc.pid)
-        except Exception as exc:
-            logger.error("Failed to spawn recall worker: %s. Run 'slm doctor' to diagnose. Python: %s", exc, sys.executable)
-            self._proc = None
-
-    def _kill(self) -> None:
-        """Terminate worker. ALL memory freed to OS."""
-        if self._idle_timer is not None:
-            self._idle_timer.cancel()
-            self._idle_timer = None
-        if self._proc is not None:
-            proc = self._proc
-            pid = proc.pid
-            try:
-                proc.stdin.write('{"cmd":"quit"}\n')
-                proc.stdin.flush()
-                proc.wait(timeout=3)
-            except Exception:
-                try:
-                    proc.kill()
-                    proc.wait(timeout=2)
-                except Exception:
-                    pass
-            # L-CONC-1: deterministically close the pipe fds rather than leaving
-            # them to GC. This releases the OS handles immediately and unblocks
-            # any orphaned _readline_with_timeout reader thread (its readline
-            # returns/raises on the closed pipe), so repeated request timeouts
-            # cannot accumulate reader threads or file descriptors. Cross-platform.
-            for stream in (proc.stdin, proc.stdout, proc.stderr):
-                try:
-                    if stream is not None:
-                        stream.close()
-                except Exception:
-                    pass
-            self._proc = None
-            logger.info("Recall worker killed (PID %s)", pid)
-
-    def _reset_idle_timer(self) -> None:
-        """Kill worker after 2 min of no requests."""
-        if self._idle_timer is not None:
-            self._idle_timer.cancel()
-        self._idle_timer = threading.Timer(_IDLE_TIMEOUT, self._idle_kill)
-        self._idle_timer.daemon = True
-        self._idle_timer.start()
-        self._last_used = time.time()
-
-    def _idle_kill(self) -> None:
-        """Called by idle timer — kill worker to free memory."""
-        with self._lock:
-            if self._proc is not None:
-                logger.info("Idle timeout — killing recall worker")
-                self._kill()

package/src/superlocalmemory/core/working_memory.py

@@ -1,288 +0,0 @@
-# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
-# Licensed under AGPL-3.0-or-later - see LICENSE file
-
-"""A small, per-session set of memories that biases the next recall.
-
-WHAT THIS IS FOR
-----------------
-Turn 5 of a conversation currently knows nothing about turns 1-4. Every recall
-starts from the query alone, so a memory the user was just discussing competes
-from scratch against every other memory in the store.
-
-``ContextCache`` does not fix this, because it does something different: on a
-hit it answers *instead of* searching, and on a miss it contributes nothing.
-This module biases a search that always runs in full. The distinction is the
-whole point — a cache replaces retrieval, a working set shapes it.
-
-The two are complementary and both stay: the cache short-circuits an exact
-repeat of a query before the daemon is reached, this biases the ranking of
-every query that does reach it.
-
-WHY SO SMALL
-------------
-Seven slots per session, evicting the least-activated when full. Human working
-memory is capacity-limited to a handful of items, and the limit is what makes it
-useful: an unbounded "everything recently seen" set would boost most of the
-store and therefore rank nothing.
-
-Seven is the constant this ships with. It is a starting point, not a derived
-optimum, and ``MAX_SLOTS`` is the single place to change it.
-
-ADMISSION IS BY RANK, NOT BY SCORE
-----------------------------------
-An earlier design admitted a memory when its fused score cleared 0.60. That
-threshold is unreachable, and measurably so: reciprocal-rank fusion of *n*
-channels caps the top score at ``n/(k+1)``, which is 0.31 at ``rrf_k=15`` and
-0.08 at ``rrf_k=60``. Nothing would ever have been admitted, the bias would
-never have fired, and the symptom would have been silence rather than an error.
-(The 0.60 that does exist in retrieval is the evidence floor's semantic cosine —
-a different quantity on a different scale.)
-
-So admission takes the memories that were actually *shown* at the top of an
-answer. Rank survives every rescaling the pipeline applies to scores; an
-absolute threshold does not.
-
-WHY A LOCK, AND NOT "THE GIL IS ENOUGH"
----------------------------------------
-``admit`` reads the slot list, decides an eviction, and writes it back. That is
-not atomic under the GIL — it spans many bytecodes, and the daemon serves
-recalls from a thread-pool executor, so two recalls in one session genuinely
-interleave. Without the lock, both can pass the capacity check and both append,
-leaving eight slots in a seven-slot set. A lock acquisition costs nanoseconds
-against a recall measured in hundreds of milliseconds.
-
-NEVER PERSISTED
----------------
-There is no table behind this and there must not be. It is ephemeral by
-definition; persisting it would create an unbounded write per recall for state
-whose entire value is that it is cheap.
-"""
-
-from __future__ import annotations
-
-import threading
-import time
-from dataclasses import dataclass
-
-__all__ = [
-    "MAX_SLOTS",
-    "WorkingMemory",
-    "discard",
-    "discard_profile",
-    "get_or_create",
-    "registry_size",
-]
-
-#: Slots per session. See "WHY SO SMALL" above.
-MAX_SLOTS = 7
-
-#: How many shown memories a single answer may offer for admission. Matches the
-#: prefix the settlement path records as "what this query showed", so the two
-#: notions of "what the user actually saw" cannot drift apart.
-ADMIT_TOP_N = 5
-
-#: A session untouched for this long is dropped. The daemon runs for weeks.
-SESSION_IDLE_EVICT_SECS = 86_400  # 24 h
-
-#: Hard ceiling on tracked sessions, evicting least-recently-touched first.
-#: Age alone does not bound anything inside the first 24 hours, and a burst of
-#: short-lived session ids is exactly the shape of an agent workload.
-MAX_SESSIONS = 512
-
-#: Activation halves roughly every hour of disuse.
-_RECENCY_HALFLIFE_SECS = 3_600.0
-
-
-@dataclass(frozen=True)
-class _Slot:
-    """One remembered memory. Frozen, so an update is a replacement.
-
-    Immutability is not decoration here: a reader holding this object while a
-    writer updates the same memory sees either the old slot or the new one,
-    never a half-applied mix of the two.
-    """
-
-    fact_id: str
-    hits: int
-    last_seen: float
-
-    def activation(self, now: float) -> float:
-        """How strongly this memory is currently held.
-
-        Repetition raises it, elapsed time lowers it. The decay is a smooth
-        reciprocal rather than a step, so eviction never depends on which side
-        of a boundary a timestamp happened to land.
-        """
-        age = max(0.0, now - self.last_seen)
-        return self.hits / (1.0 + age / _RECENCY_HALFLIFE_SECS)
-
-
-class WorkingMemory:
-    """The working set for one (profile, session) pair."""
-
-    __slots__ = ("_lock", "_slots", "_touched_at")
-
-    def __init__(self) -> None:
-        self._lock = threading.Lock()
-        self._slots: dict[str, _Slot] = {}
-        self._touched_at = time.monotonic()
-
-    # -- mutation ----------------------------------------------------------
-
-    def admit(self, fact_ids: list[str] | tuple[str, ...]) -> None:
-        """Offer the memories an answer just showed, best-ranked first.
-
-        Already-held memories are reinforced rather than duplicated, which is
-        what makes a memory referenced across several turns hard to evict.
-        """
-        if not fact_ids:
-            return
-        now = time.monotonic()
-        with self._lock:
-            self._touched_at = now
-            for fact_id in fact_ids[:ADMIT_TOP_N]:
-                if not fact_id:
-                    continue
-                existing = self._slots.get(fact_id)
-                self._slots[fact_id] = _Slot(
-                    fact_id=fact_id,
-                    hits=(existing.hits + 1) if existing else 1,
-                    last_seen=now,
-                )
-            self._evict_locked(now)
-
-    def touch(self, fact_id: str) -> None:
-        """Reinforce a memory something downstream actually used.
-
-        Stronger evidence than having been displayed, and it arrives later, so
-        it is a separate entry point rather than a flag on ``admit``. A memory
-        that is not held is not admitted by being touched: this reinforces
-        attention, it does not create it.
-        """
-        if not fact_id:
-            return
-        now = time.monotonic()
-        with self._lock:
-            self._touched_at = now
-            existing = self._slots.get(fact_id)
-            if existing is None:
-                return
-            self._slots[fact_id] = _Slot(
-                fact_id=fact_id, hits=existing.hits + 1, last_seen=now,
-            )
-
-    def _evict_locked(self, now: float) -> None:
-        """Drop the least-activated slots. Caller holds the lock."""
-        while len(self._slots) > MAX_SLOTS:
-            weakest = min(
-                self._slots.values(),
-                key=lambda s: (s.activation(now), s.last_seen, s.fact_id),
-            )
-            self._slots.pop(weakest.fact_id, None)
-
-    # -- reads -------------------------------------------------------------
-
-    def boost_set(self) -> frozenset[str]:
-        """The memories currently held. Read by the ranking bias."""
-        with self._lock:
-            return frozenset(self._slots)
-
-    def idle_secs(self, now: float | None = None) -> float:
-        with self._lock:
-            return max(0.0, (now or time.monotonic()) - self._touched_at)
-
-    def __len__(self) -> int:
-        with self._lock:
-            return len(self._slots)
-
-
-# ---------------------------------------------------------------------------
-# Registry
-#
-# Keyed by (profile_id, session_id), never by session_id alone. Two profiles in
-# one daemon can be handed the same session id, and a shared key would let one
-# profile's memories bias the other's answers. It also gives erasure something
-# to erase: ``discard_profile`` can find every set belonging to a profile.
-# ---------------------------------------------------------------------------
-
-_REGISTRY: dict[tuple[str, str], WorkingMemory] = {}
-_REGISTRY_LOCK = threading.Lock()
-
-
-def get_or_create(profile_id: str, session_id: str) -> WorkingMemory:
-    """The working set for this session, creating it on first use.
-
-    Both arguments are required and neither defaults. A default ``profile_id``
-    is how two profiles end up sharing one set.
-    """
-    key = (profile_id or "", session_id or "")
-    with _REGISTRY_LOCK:
-        _sweep_locked()
-        existing = _REGISTRY.get(key)
-        if existing is not None:
-            return existing
-        created = WorkingMemory()
-        _REGISTRY[key] = created
-        return created
-
-
-def peek(profile_id: str, session_id: str) -> WorkingMemory | None:
-    """The working set if one exists, without creating one.
-
-    Reading must not allocate: a bias that runs on every recall would otherwise
-    register an entry for every session id it ever sees, including those that
-    never admit anything.
-    """
-    with _REGISTRY_LOCK:
-        return _REGISTRY.get((profile_id or "", session_id or ""))
-
-
-def discard(profile_id: str, session_id: str) -> None:
-    """Forget one session. Called when a session closes."""
-    with _REGISTRY_LOCK:
-        _REGISTRY.pop((profile_id or "", session_id or ""), None)
-
-
-def discard_profile(profile_id: str) -> int:
-    """Forget every session belonging to a profile. Returns the count dropped.
-
-    Called from erasure. In-process state is still the erased subject's data:
-    leaving it behind would let a deleted profile's memories bias a later
-    session that reuses its session id, which is the residue defect this
-    project has already paid for once in a search index.
-    """
-    target = profile_id or ""
-    with _REGISTRY_LOCK:
-        doomed = [k for k in _REGISTRY if k[0] == target]
-        for key in doomed:
-            _REGISTRY.pop(key, None)
-        return len(doomed)
-
-
-def registry_size() -> int:
-    with _REGISTRY_LOCK:
-        return len(_REGISTRY)
-
-
-def _sweep_locked() -> None:
-    """Bound the registry by idle time and then by count. Caller holds the lock."""
-    now = time.monotonic()
-    stale = [
-        key for key, wm in _REGISTRY.items()
-        if wm.idle_secs(now) > SESSION_IDLE_EVICT_SECS
-    ]
-    for key in stale:
-        _REGISTRY.pop(key, None)
-    # Trim to one below the ceiling, because the caller is about to insert.
-    # Trimming to the ceiling itself leaves the registry one over after every
-    # insertion, which is a cap that is never actually enforced. Sweeping after
-    # the insert instead would make the new entry — idle for zero seconds, tied
-    # with every other new entry — a candidate for its own eviction.
-    headroom = MAX_SESSIONS - 1
-    if len(_REGISTRY) <= headroom:
-        return
-    by_age = sorted(
-        _REGISTRY.items(), key=lambda kv: (-kv[1].idle_secs(now), kv[0]),
-    )
-    for key, _wm in by_age[: len(_REGISTRY) - headroom]:
-        _REGISTRY.pop(key, None)