superlocalmemory 3.8.11 → 3.8.12

package/src/superlocalmemory/cli/setup_wizard.py

@@ -274,6 +274,35 @@ def _embedding_is_remote(config: Any) -> bool:
     return provider in ("openai", "openai-compatible", "remote") or bool(endpoint)
 
 
+def _reranker_is_remote(config: Any) -> bool:
+    """True when reranking runs against a remote endpoint (v3.8.12, #105).
+
+    In that case the local ~130MB English cross-encoder download is pointless
+    — and worse, misleading, since it is not the model that will score recall.
+    Unlike embeddings, the endpoint alone is NOT sufficient: a stray endpoint
+    against a local backend is a misconfiguration the engine reports, not a
+    remote setup.
+    """
+    rt = getattr(config, "retrieval", None)
+    if rt is None:
+        return False
+    backend = (getattr(rt, "cross_encoder_backend", "") or "").strip().lower()
+    endpoint = getattr(rt, "cross_encoder_endpoint", "") or ""
+    return backend in ("openai", "remote") and bool(endpoint)
+
+
+# Remote-reranker keys the wizard never asks about. ``retrieval`` is otherwise
+# a mode-owned block that the wizard resets from the template, which would
+# silently delete a working remote endpoint on every re-run (#105).
+_USER_OWNED_RETRIEVAL_KEYS = (
+    "cross_encoder_backend",
+    "cross_encoder_endpoint",
+    "cross_encoder_api_key",
+    "cross_encoder_model",
+    "cross_encoder_timeout_seconds",
+)
+
+
 def _build_wizard_config(mode):
     """Apply mode-owned presets without erasing existing user-owned blocks."""
     from superlocalmemory.core.config import SLMConfig
@@ -285,7 +314,14 @@ def _build_wizard_config(mode):
     existing = SLMConfig.load()
     existing.mode = mode
     existing.llm = template.llm
+    preserved = {
+        key: getattr(existing.retrieval, key)
+        for key in _USER_OWNED_RETRIEVAL_KEYS
+        if hasattr(existing.retrieval, key)
+    }
     existing.retrieval = template.retrieval
+    for key, value in preserved.items():
+        setattr(existing.retrieval, key, value)
     existing.math = template.math
     existing.channel_weights = template.channel_weights
     return existing
@@ -566,7 +602,15 @@ def run_wizard(auto: bool = False) -> None:
     print()
     print("─── Step 4b/10: Download Reranker Model ───")
 
-    if not st_ok:
+    if _reranker_is_remote(config):
+        # v3.8.12 (#105): a remote /v1/rerank endpoint scores the results, so
+        # the local English cross-encoder would be dead weight on disk.
+        rt = config.retrieval
+        print("  ✓ Skipped — remote rerank endpoint configured")
+        print(f"    backend={getattr(rt, 'cross_encoder_backend', '?')}, "
+              f"model={getattr(rt, 'cross_encoder_model', '?')}")
+        print("    No local reranker model needed.")
+    elif not st_ok:
         print("  ⚠ Skipped (sentence-transformers not installed)")
     else:
         _download_reranker(_RERANKER_MODEL)

package/src/superlocalmemory/core/component_registry.py

@@ -164,6 +164,20 @@ def _embedding_is_remote(config: Any) -> bool:
         return False
 
 
+def _reranker_is_remote(config: Any) -> bool:
+    """True when reranking is served by a remote endpoint (v3.8.12, #105).
+
+    Same shape as ``_embedding_is_remote``: conservative False on any
+    import/attribute error so a local reranker is still probed.
+    """
+    try:
+        from superlocalmemory.cli.setup_wizard import _reranker_is_remote as _r
+
+        return bool(_r(config))
+    except Exception:
+        return False
+
+
 # --------------------------------------------------------------------------
 # Individual probes — each returns a Component (never raises)
 # --------------------------------------------------------------------------
@@ -259,6 +273,17 @@ def probe_reranker_model(config: Any = None) -> Component:
             if config is not None else True
     except Exception:
         enabled = True
+    if enabled and config is not None and _reranker_is_remote(config):
+        # v3.8.12 (#105): a remote /v1/rerank endpoint supplies the scores, so
+        # the local 130MB English cross-encoder is neither downloaded nor used.
+        # Reporting it MISSING would push the operator to "fix" a component the
+        # configured runtime never touches.
+        return Component(
+            key="reranker_model", label="Reranker model",
+            category=CATEGORY_RECOMMENDED, status=STATUS_OK,
+            detail="remote rerank endpoint (no local model required)",
+            last_checked=time.time(),
+        )
     comp = _probe_hf_model(
         "reranker_model", "Reranker model", _RERANKER_MODEL,
         category=CATEGORY_RECOMMENDED if enabled else CATEGORY_OPTIONAL,

package/src/superlocalmemory/core/config.py

@@ -267,7 +267,41 @@ class RetrievalConfig:
     # relevant facts before reranking. See bench-v342-locomo.md.
     use_cross_encoder: bool = True
     cross_encoder_model: str = "cross-encoder/ms-marco-MiniLM-L-12-v2"
-    cross_encoder_backend: str = ""  # "" = PyTorch (~500MB stable), "onnx" = ONNX (leaks on ARM64 CoreML)
+    # "" = PyTorch (~500MB stable), "onnx" = ONNX (leaks on ARM64 CoreML),
+    # "openai"/"remote" = v3.8.12 (issue #105) OpenAI-compatible /v1/rerank
+    # endpoint (llama-server, TEI, Infinity, vLLM, Cohere-shaped services).
+    cross_encoder_backend: str = ""
+
+    # v3.8.12 (issue #105): remote reranker endpoint. The bundled default
+    # cross-encoder (ms-marco-MiniLM-L-12-v2) is ENGLISH-ONLY, so non-English
+    # deployments scored their own language with a model that cannot read it.
+    # Pointing this at a multilingual reranker (bge-reranker-v2-m3, a Qwen
+    # reranker, …) is the same escape hatch remote embeddings got in v3.4.24.
+    #
+    # This key was accepted-and-ignored before 3.8.12 (issue #103): it was not
+    # a dataclass field, so ``SLMConfig.load`` filtered it out without a word.
+    # It is now read, validated, and — when it disagrees with the backend —
+    # reported as a loud configuration error instead of nothing at all.
+    cross_encoder_endpoint: str = ""
+    # Optional bearer token. Prefer the SLM_CROSS_ENCODER_API_KEY environment
+    # variable — it takes precedence and keeps the secret out of config.json.
+    cross_encoder_api_key: str = ""
+    # Per-request read budget for the remote reranker. Recall is interactive,
+    # so this stays tight: a slow reranker degrades to fusion scores rather
+    # than holding the recall open.
+    cross_encoder_timeout_seconds: float = 15.0
+
+    @property
+    def is_remote_cross_encoder(self) -> bool:
+        """True when reranking is served by a remote HTTP endpoint."""
+        from superlocalmemory.retrieval.remote_reranker import (
+            is_remote_cross_encoder_backend,
+        )
+
+        return (
+            is_remote_cross_encoder_backend(self.cross_encoder_backend)
+            and bool(self.cross_encoder_endpoint)
+        )
 
     # Agentic (Mode C only)
     agentic_max_rounds: int = 3

package/src/superlocalmemory/core/engine_wiring.py

@@ -22,8 +22,88 @@ if TYPE_CHECKING:
 logger = logging.getLogger(__name__)
 
 
+def init_reranker(retrieval_config: Any) -> Any:
+    """Build the reranker the config asks for — remote endpoint or local worker.
+
+    v3.8.12 (issue #105). The remote branch is decided HERE, in the parent
+    process, before any subprocess exists. Spawning a worker whose only job
+    would be to forward an HTTP POST costs a fork, a machine-wide PID
+    singleton, and a warmup handshake for nothing — and issue #103 showed that
+    singleton blocking a reranker that was never local in the first place.
+
+    Misconfiguration is reported, never absorbed:
+      * remote backend with no/invalid endpoint -> reranking is DISABLED with
+        an error naming the fix. Quietly loading the English local model
+        instead would recreate the exact silent degradation #105 is about.
+      * endpoint set against a LOCAL backend -> error naming both keys, then
+        the local reranker runs as the backend actually requested. Before
+        3.8.12 this combination was dropped in silence (issue #103).
+
+    Returns the reranker, or None when reranking must stay off.
+    """
+    from superlocalmemory.retrieval.remote_reranker import (
+        RemoteReranker,
+        RemoteRerankerConfigError,
+        is_remote_cross_encoder_backend,
+        validate_remote_reranker_config,
+    )
+    from superlocalmemory.retrieval.reranker import CrossEncoderReranker
+
+    backend = getattr(retrieval_config, "cross_encoder_backend", "") or ""
+    endpoint = getattr(retrieval_config, "cross_encoder_endpoint", "") or ""
+    model = getattr(
+        retrieval_config, "cross_encoder_model",
+        "cross-encoder/ms-marco-MiniLM-L-12-v2",
+    )
+    remote_requested = is_remote_cross_encoder_backend(backend)
+
+    error = validate_remote_reranker_config(backend, endpoint)
+    if error and remote_requested:
+        logger.error(
+            "Remote reranker not started — %s Reranking is DISABLED; recall "
+            "returns fusion-ranked results.", error,
+        )
+        return None
+    if error:
+        logger.error(
+            "Reranker configuration conflict — %s Continuing with the local "
+            "cross-encoder as configured.", error,
+        )
+    elif remote_requested:
+        try:
+            return RemoteReranker(
+                model,
+                endpoint,
+                api_key=getattr(retrieval_config, "cross_encoder_api_key", ""),
+                backend=backend,
+                timeout_seconds=getattr(
+                    retrieval_config, "cross_encoder_timeout_seconds", 15.0,
+                ),
+            )
+        except RemoteRerankerConfigError as exc:
+            logger.error(
+                "Remote reranker not started — %s Reranking is DISABLED.", exc,
+            )
+            return None
+
+    return CrossEncoderReranker(model, backend=backend)
+
+
 def _log_reranker_warmup_status(reranker: Any) -> None:
     """Record non-blocking reranker warmup state without alarming first-run users."""
+    from superlocalmemory.retrieval.remote_reranker import RemoteReranker
+
+    # isinstance, not a duck-typed attribute probe: MagicMock fabricates any
+    # attribute on demand, so ``getattr(reranker, "is_remote", False)`` would
+    # route every mocked reranker in the suite down the remote branch. Same
+    # hazard RetrievalEngine guards against when it checks the TYPE for
+    # ``rerank_with_status``.
+    if isinstance(reranker, RemoteReranker):
+        # The remote reranker logs its own probe outcome (endpoint, model, and
+        # the precise transport error). A second generic line about a local
+        # worker singleton would be noise at best and misleading at worst.
+        reranker.warmup_sync()
+        return
     ready = reranker.warmup_sync(timeout=180)
     if ready:
         logger.info("Cross-encoder reranker warm and ready")
@@ -508,7 +588,6 @@ def init_retrieval(
     from superlocalmemory.retrieval.bm25_channel import BM25Channel
     from superlocalmemory.retrieval.entity_channel import EntityGraphChannel
     from superlocalmemory.retrieval.temporal_channel import TemporalChannel
-    from superlocalmemory.retrieval.reranker import CrossEncoderReranker
     from superlocalmemory.retrieval.profile_channel import ProfileChannel
     from superlocalmemory.retrieval.bridge_discovery import BridgeDiscovery
 
@@ -541,10 +620,7 @@ def init_retrieval(
 
     reranker = None
     if config.retrieval.use_cross_encoder:
-        reranker = CrossEncoderReranker(
-            config.retrieval.cross_encoder_model,
-            backend=config.retrieval.cross_encoder_backend,
-        )
+        reranker = init_reranker(config.retrieval)
 
     profile_ch = ProfileChannel(db)
     bridge = BridgeDiscovery(db)

package/src/superlocalmemory/core/recall_pipeline.py

@@ -283,7 +283,14 @@ class _ReadOnlyLearningView:
             connection.close()
 
     def count_feedback(self, profile_id: str) -> int:
-        """Count legacy feedback without running schema initialization."""
+        """Count legacy feedback without running schema initialization.
+
+        Reports the raw ``learning_feedback`` table, which the dashboard
+        surfaces as ``legacy_feedback_rows`` alongside a pending-migration
+        card. Do NOT gate a ranking phase on this — use ``count_signals``,
+        which is the counter every other surface resolves its phase from
+        (issue #106).
+        """
         connection = self._connection()
         try:
             row = connection.execute(
@@ -408,17 +415,31 @@ def apply_adaptive_ranking(
     if not learning_db.exists():
         return response
 
+    # issue #106: count the CANONICAL store, not the legacy one. The
+    # dashboard's Living Brain panel and ranker-phase card both resolve their
+    # phase from ``learning_signals``; this gate read ``learning_feedback``,
+    # so the phase a user was shown and the phase that actually ranked their
+    # results were computed from different tables and could disagree without
+    # limit. ``learning_feedback`` rows reach this counter through
+    # ``legacy_migration``, which copies them forward.
     try:
-        signal_count = _ReadOnlyLearningView(learning_db).count_feedback(pid)
+        signal_count = _ReadOnlyLearningView(learning_db).count_signals(pid)
     except sqlite3.Error:
         # A pre-learning database may not have this optional table yet.
         # Recall remains a query and cannot create it on demand.
         return response
 
-    if signal_count < 50:
+    from superlocalmemory.learning.ranker import (
+        PHASE_2_THRESHOLD,
+        AdaptiveRanker,
+    )
+
+    # Thresholds come from ``learning.ranker`` — the same constants the
+    # dashboard gates on. Duplicating the literals here is how the two
+    # surfaces drifted apart in the first place.
+    if signal_count < PHASE_2_THRESHOLD:
         return response  # Phase 1: no change
 
-    from superlocalmemory.learning.ranker import AdaptiveRanker
     ranker = AdaptiveRanker(signal_count=signal_count)
 
     from datetime import UTC

package/src/superlocalmemory/core/reranker_worker.py

@@ -230,6 +230,11 @@ def _worker_main() -> None:
 
 
 _KNOWN_BACKENDS = ("onnx", "", "pytorch", "torch")
+# Backends this worker can never serve — they are handled over HTTP by
+# superlocalmemory.retrieval.remote_reranker in the parent process (#105).
+# Duplicated as a literal on purpose: this module runs as a bare subprocess
+# and must not import the retrieval package (or, transitively, httpx).
+_REMOTE_BACKENDS = ("openai", "remote")
 
 
 def _load_model(
@@ -253,12 +258,26 @@ def _load_model(
     # the PyTorch tier and fail there with a confusing model-load error. A
     # user who set backend="openai" expecting a remote reranker got five
     # silent failures and no hint that the value meant nothing. Name it.
+    #
+    # v3.8.12 (issue #105): remote reranking now EXISTS, but it is served in
+    # the parent process — this worker holds torch/ONNX and cannot forward an
+    # HTTP request. Reaching here with a remote backend means the parent
+    # routed wrong (or a caller drove the worker directly), so the message
+    # points at the config keys that select the remote path.
+    if backend in _REMOTE_BACKENDS:
+        return None, "", "", (
+            f"unknown backend {backend!r} for the LOCAL reranker worker. "
+            f"{backend!r} selects the remote reranker, which runs in the "
+            f"parent process — set retrieval.cross_encoder_endpoint (e.g. "
+            f"\"http://127.0.0.1:8041/v1/rerank\") so SuperLocalMemory routes "
+            f"reranking over HTTP instead of spawning this worker."
+        )
     if backend not in _KNOWN_BACKENDS:
         return None, "", "", (
-            f"unknown backend {backend!r}; supported values are "
-            f"'onnx' or '' (PyTorch). SuperLocalMemory has no remote/"
-            f"OpenAI-compatible reranker backend — the cross-encoder always "
-            f"runs locally, so 'cross_encoder_endpoint' has no effect."
+            f"unknown backend {backend!r}; supported values are 'onnx' or ''"
+            f" (PyTorch) for local reranking, or 'openai'/'remote' with "
+            f"retrieval.cross_encoder_endpoint set for a remote "
+            f"OpenAI-compatible /v1/rerank endpoint."
         )
 
     tier_errors: list[str] = []

package/src/superlocalmemory/infra/daemon_identity.py

@@ -26,6 +26,7 @@ from pathlib import Path
 from typing import Any, Mapping
 
 from superlocalmemory.infra.data_root import canonical_data_root
+from superlocalmemory.infra.process_identity import process_start_token_for
 
 DAEMON_DESCRIPTOR_SCHEMA = 1
 DAEMON_PROTOCOL = 1
@@ -88,6 +89,11 @@ class DaemonDescriptor:
     state: str
     version: str
     started_at: float
+    # Clock-independent process identity. Optional and defaulted so a
+    # descriptor written by an older release still parses; platforms without a
+    # boot-relative start time (Windows) legitimately store None and fall back
+    # to the creation-time comparison. See infra/process_identity.py.
+    process_start_token: str | None = None
 
     def public_health_fields(self) -> dict[str, Any]:
         """Identity fields safe to expose on the loopback health endpoint."""
@@ -112,6 +118,7 @@ def build_descriptor(
     version: str,
     pid: int | None = None,
     process_create_time: float | None = None,
+    process_start_token: str | None = None,
     instance_id: str | None = None,
     capability: str | None = None,
     state: str = "starting",
@@ -141,6 +148,11 @@ def build_descriptor(
         state=state,
         version=version,
         started_at=float(started_at if started_at is not None else time.time()),
+        process_start_token=(
+            process_start_token
+            if process_start_token is not None
+            else process_start_token_for(actual_pid)
+        ),
     )
 
 
@@ -238,6 +250,10 @@ def read_descriptor(
         return None
     if not (1 <= descriptor.port <= 65535) or descriptor.pid <= 0:
         return None
+    if descriptor.process_start_token is not None and not isinstance(
+        descriptor.process_start_token, str
+    ):
+        return None
     return descriptor
 
 

package/src/superlocalmemory/infra/process_identity.py

@@ -0,0 +1,180 @@
+# 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
+
+"""Clock-independent identity for one running local process.
+
+Why this module exists
+----------------------
+A process's *wall-clock* creation time is not a stable identifier on every
+platform.  On Linux -- and therefore inside WSL2 -- psutil derives it as::
+
+    create_time = /proc/<pid>/stat:starttime / CLOCK_TICKS + /proc/stat:btime
+
+``starttime`` is boot-relative and never changes for the life of the process.
+``btime`` is the kernel's *estimate* of the boot instant, recomputed from the
+current wall clock, so any clock step moves ``btime`` and moves every process's
+computed ``create_time`` with it -- retroactively.  WSL2 periodically
+resynchronises its VM clock against the Windows host, so a ``create_time``
+recorded when the daemon started stops matching the ``create_time`` computed
+for that very same process minutes later.  Issue #104 measured a ~35 second
+divergence after roughly four minutes of uptime.
+
+Any *constant* tolerance on that comparison is a delay, not a fix: the
+divergence is unbounded and keeps growing.  The correct identifier is one the
+wall clock cannot move at all, which is what this module produces.
+
+What a start token is
+---------------------
+``process_start_token_for(pid)`` returns an opaque string identifying one
+process *instance*, derived without reference to wall-clock time, or ``None``
+when the platform cannot supply one.  Tokens are only comparable when they use
+the same scheme, so :func:`compare_start_tokens` is deliberately tri-state --
+callers fall back to a weaker signal instead of guessing.
+
+Schemes
+-------
+``lx1``
+    Linux/WSL2: ``lx1:<boot_id>:<starttime_ticks>``.  Both halves come straight
+    from procfs and are an opaque UUID and an integer tick count rather than
+    timestamps, so a clock adjustment cannot rewrite either.  ``boot_id``
+    differs across reboots, so a post-reboot PID collision can never look like
+    a match.
+``mn1``
+    Platforms where psutil exposes a monotonic creation time (macOS, NetBSD,
+    and Linux if procfs is unreadable): ``mn1:<value>``.  psutil builds its own
+    PID-reuse identity from exactly this value for exactly this reason.
+
+Windows has no monotonic variant, and needs none: its creation time comes from
+``GetProcessTimes``, a kernel timestamp that a clock adjustment does not
+rewrite.  ``process_start_token_for`` returns ``None`` there and the caller's
+creation-time comparison stays correct.
+"""
+
+from __future__ import annotations
+
+import logging
+import sys
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+LINUX_SCHEME = "lx1"
+MONOTONIC_SCHEME = "mn1"
+
+_PROCFS = Path("/proc")
+# "man proc" numbers /proc/<pid>/stat fields from 1 and starttime is field 22.
+# The comm field can contain spaces and parentheses, so parsing starts after
+# the last ')', which drops fields 1 and 2 -- hence 22 - 3 == 19.
+_STARTTIME_INDEX = 19
+
+
+def _boot_id() -> str | None:
+    """Return this boot's opaque kernel identifier, or None when unavailable.
+
+    Deliberately strict: without a boot id, two processes from different boots
+    could share a PID *and* a tick count, so the token would be unsound. A
+    missing boot id therefore means "no token" rather than a weaker token.
+    """
+    try:
+        value = (_PROCFS / "sys" / "kernel" / "random" / "boot_id").read_text(
+            encoding="utf-8",
+        ).strip()
+    except OSError:
+        return None
+    return value or None
+
+
+def _linux_start_ticks(pid: int) -> int | None:
+    """Return boot-relative start ticks for a PID from procfs, or None."""
+    try:
+        data = (_PROCFS / str(pid) / "stat").read_bytes()
+    except OSError:
+        return None
+    closing = data.rfind(b")")
+    if closing < 0:
+        return None
+    fields = data[closing + 2:].split()
+    if len(fields) <= _STARTTIME_INDEX:
+        return None
+    try:
+        return int(fields[_STARTTIME_INDEX])
+    except ValueError:
+        return None
+
+
+def _linux_start_token(pid: int) -> str | None:
+    boot_id = _boot_id()
+    if boot_id is None:
+        return None
+    ticks = _linux_start_ticks(pid)
+    if ticks is None:
+        return None
+    return f"{LINUX_SCHEME}:{boot_id}:{ticks}"
+
+
+def _monotonic_start_token(pid: int) -> str | None:
+    """Return psutil's monotonic creation time as a token, or None.
+
+    ``Process._proc.create_time(monotonic=True)`` is the same private accessor
+    psutil uses internally to build ``Process._ident``.  It is guarded on every
+    axis -- missing psutil, missing attribute, platforms whose implementation
+    takes no ``monotonic`` keyword (Windows) -- and degrades to ``None``.
+    """
+    try:
+        import psutil
+
+        platform_process = getattr(psutil.Process(pid), "_proc", None)
+    except Exception:  # noqa: BLE001 - identity probing must never raise
+        return None
+    create_time = getattr(platform_process, "create_time", None)
+    if create_time is None:
+        return None
+    try:
+        raw = create_time(monotonic=True)
+    except TypeError:
+        # No monotonic variant on this platform (Windows).
+        return None
+    except Exception:  # noqa: BLE001
+        return None
+    try:
+        return f"{MONOTONIC_SCHEME}:{float(raw)!r}"
+    except (TypeError, ValueError):
+        return None
+
+
+def process_start_token_for(pid: int) -> str | None:
+    """Return a clock-independent identity token for ``pid``, or None.
+
+    ``None`` is a normal answer, not an error: it means "this platform cannot
+    prove process identity without the wall clock", and the caller should fall
+    back to comparing creation times.
+    """
+    try:
+        pid = int(pid)
+    except (TypeError, ValueError):
+        return None
+    if pid <= 0:
+        return None
+    if sys.platform.startswith("linux"):
+        token = _linux_start_token(pid)
+        if token is not None:
+            return token
+    return _monotonic_start_token(pid)
+
+
+def compare_start_tokens(recorded: str | None, observed: str | None) -> bool | None:
+    """Tri-state comparison of two start tokens.
+
+    ``True``  -- same scheme, identical value: proven the same process instance.
+    ``False`` -- same scheme, different value: proven a different instance.
+    ``None``  -- not comparable (either side missing, or different schemes);
+                 the caller must fall back rather than assume either way.
+    """
+    if not recorded or not observed:
+        return None
+    if not isinstance(recorded, str) or not isinstance(observed, str):
+        return None
+    if recorded.split(":", 1)[0] != observed.split(":", 1)[0]:
+        return None
+    return recorded == observed