superlocalmemory 4.1.13 → 4.1.14

package/src/superlocalmemory/retrieval/channel_registry.py

@@ -1,154 +0,0 @@
-# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
-# Licensed under AGPL-3.0-or-later - see LICENSE file
-# Part of SuperLocalMemory V3
-
-"""SuperLocalMemory V3.2 -- Channel Registry.
-
-Self-registration system for retrieval channels. Prevents merge
-conflicts when Phases 2/3/4 add new channels in parallel.
-
-Design: Registry Pattern + Protocol (structural subtyping).
-Each channel registers itself with a name and implements the
-RetrievalChannel protocol. The registry dispatches search()
-calls to all registered channels and collects results.
-
-Part of Qualixar | Author: Varun Pratap Bhardwaj
-"""
-
-from __future__ import annotations
-
-import logging
-from typing import Any, Callable, Protocol, runtime_checkable
-
-logger = logging.getLogger(__name__)
-
-
-@runtime_checkable
-class RetrievalChannel(Protocol):
-    """Protocol for retrieval channels.
-
-    Any object with a search() method matching this signature
-    is a valid channel. No inheritance required.
-    """
-
-    def search(
-        self,
-        query: Any,
-        profile_id: str,
-        top_k: int = 50,
-    ) -> list[tuple[str, float]]:
-        """Search for relevant facts. Returns [(fact_id, score)]."""
-        ...
-
-
-# Type alias for post-retrieval filter functions.
-# Filters operate on the FULL channel results dict, NOT per-channel.
-# Signature: (all_channel_results, profile_id, context) -> filtered_results
-FilterFn = Callable[
-    [dict[str, list[tuple[str, float]]], str, Any],
-    dict[str, list[tuple[str, float]]]
-]
-
-
-class ChannelRegistry:
-    """Registry for retrieval channels with self-registration.
-
-    Usage:
-        registry = ChannelRegistry()
-        registry.register_channel("semantic", semantic_ch, needs_embedding=True)
-        registry.register_channel("bm25", bm25_ch)
-        registry.register_filter(temporal_filter)
-        results = registry.run_all(query, "default", embedder=emb)
-
-    BACKWARD COMPATIBILITY:
-    - register_channel() defaults needs_embedding=False (existing channels unaffected)
-    - run_all() is a new method (no existing callers to break)
-    - Filters use dict-based signature for Phase 4 temporal filter compatibility
-    """
-
-    def __init__(self) -> None:
-        self._channels: dict[str, RetrievalChannel] = {}
-        self._filters: list[FilterFn] = []
-        self._embedding_channels: set[str] = set()
-
-    def register_channel(
-        self, name: str, channel: RetrievalChannel, needs_embedding: bool = False,
-    ) -> None:
-        """Register a retrieval channel by name.
-
-        Args:
-            name: Channel identifier (e.g., "semantic", "spreading_activation").
-            channel: Object implementing RetrievalChannel protocol.
-            needs_embedding: If True, raw query string is embedded into a vector
-                before passing to channel.search(). Required for channels that
-                expect vector input (semantic, spreading_activation).
-        """
-        self._channels[name] = channel
-        if needs_embedding:
-            self._embedding_channels.add(name)
-        logger.debug("Registered channel: %s (needs_embedding=%s)", name, needs_embedding)
-
-    def register_filter(self, fn: FilterFn) -> None:
-        """Register a post-retrieval filter function.
-
-        Filters run after all channels, before fusion. Used for
-        temporal validity filtering (Phase 4) and other concerns.
-
-        Filter signature: (channel_results_dict, profile_id, context) -> filtered_dict
-        """
-        self._filters.append(fn)
-        logger.debug("Registered filter: %s", getattr(fn, '__name__', str(fn)))
-
-    def run_all(
-        self,
-        query: str,
-        profile_id: str,
-        *,
-        embedder: Any | None = None,
-        disabled: set[str] | None = None,
-        top_k: int = 50,
-    ) -> dict[str, list[tuple[str, float]]]:
-        """Run all registered channels and return results.
-
-        Channels in `disabled` are skipped. Channels in _embedding_channels
-        receive embedder.embed(query) instead of raw query text.
-        Errors in channels are logged, not raised (Rule 19).
-
-        Returns dict of channel_name to [(fact_id, score)].
-        """
-        disabled = disabled or set()
-        out: dict[str, list[tuple[str, float]]] = {}
-
-        for name, channel in self._channels.items():
-            if name in disabled:
-                continue
-            try:
-                if name in self._embedding_channels and embedder is not None:
-                    q_emb = embedder.embed(query)
-                    results = channel.search(q_emb, profile_id, top_k)
-                else:
-                    results = channel.search(query, profile_id, top_k)
-                if results:
-                    out[name] = results
-            except Exception as exc:
-                logger.warning("Channel %s failed: %s", name, exc)
-
-        # Filters operate on the FULL results dict (not per-channel).
-        for fn in self._filters:
-            try:
-                out = fn(out, profile_id, None)
-            except Exception as exc:
-                logger.debug("Filter %s failed: %s",
-                            getattr(fn, '__name__', str(fn)), exc)
-
-        return out
-
-    @property
-    def channel_names(self) -> list[str]:
-        """List of registered channel names."""
-        return list(self._channels.keys())
-
-    @property
-    def channel_count(self) -> int:
-        """Number of registered channels."""
-        return len(self._channels)

package/src/superlocalmemory/retrieval/channel_status.py

@@ -1,117 +0,0 @@
-# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
-# Licensed under AGPL-3.0-or-later - see LICENSE file
-
-"""What happened to each retrieval channel on one recall.
-
-WHY THIS EXISTS
----------------
-A channel that crashes on every query and a channel that correctly found
-nothing produced the same observable result: absence. Both simply had no entry
-in the fused candidate map, and the only trace was a log line on a machine
-nobody is reading.
-
-That matters because the channels are not interchangeable. Lexical search
-finding nothing for a conceptual question is the system working. Lexical search
-raising on every question is an outage that looks, from the outside, like a
-store with nothing in it — the user sees weaker answers and has no way to tell
-which of the two they are getting.
-
-There is a third case the absence hid, and it is the worst of them: a channel
-that never ran. When the query embedding is unavailable, three of the five
-channels are never even dispatched. Nothing in the answer said so.
-
-WHY MORE THAN "ok / empty / error"
-----------------------------------
-Because the remedies differ, and a status whose remedy is ambiguous is a status
-nobody acts on. ``error`` is a bug to fix. ``timeout`` is a capacity or data-size
-problem. ``no_embedding`` means the embedding provider is down and several
-channels are silently offline together. ``disabled`` and ``not_configured`` are
-someone's deliberate choice and must not read as faults — which is the point:
-without naming them, an operator reading a list of missing channels cannot tell
-their own configuration apart from a failure.
-
-STRINGS, NOT AN ENUM
---------------------
-This crosses the MCP and HTTP surfaces, where it is JSON either way. A str-valued
-constant serialises without a custom encoder and compares equal to what a client
-sends back.
-"""
-
-from __future__ import annotations
-
-from typing import Literal
-
-__all__ = [
-    "ALL_STATUSES",
-    "CHANNEL_NAMES",
-    "ChannelStatus",
-    "DISABLED",
-    "EMPTY",
-    "ERROR",
-    "NOT_CONFIGURED",
-    "NO_CANDIDATES",
-    "NO_EMBEDDING",
-    "OK",
-    "TIMEOUT",
-    "is_fault",
-]
-
-ChannelStatus = Literal[
-    "ok",
-    "empty",
-    "error",
-    "timeout",
-    "disabled",
-    "not_configured",
-    "no_embedding",
-    "no_candidates",
-]
-
-#: Ran and contributed candidates.
-OK: ChannelStatus = "ok"
-#: Ran, contributed nothing. A legitimate answer, not a fault.
-EMPTY: ChannelStatus = "empty"
-#: Raised. This answer is missing whatever this channel alone could see.
-ERROR: ChannelStatus = "error"
-#: Abandoned at the hang guard. The answer is incomplete, not merely late.
-TIMEOUT: ChannelStatus = "timeout"
-#: Excluded by configuration or by a per-recall ablation flag.
-DISABLED: ChannelStatus = "disabled"
-#: No such channel on this engine — not built, or its dependency is absent.
-NOT_CONFIGURED: ChannelStatus = "not_configured"
-#: Needed the query embedding, which was unavailable. Several channels fail
-#: together this way, and none of them individually did anything wrong.
-NO_EMBEDDING: ChannelStatus = "no_embedding"
-#: Had nothing to work on. Distinct from ``empty``, which claims a search
-#: happened: a channel that re-scores other channels' candidates never searched
-#: at all when there were none, and if the reason there were none is that the
-#: others failed, calling this "found nothing" hides the actual fault.
-NO_CANDIDATES: ChannelStatus = "no_candidates"
-
-ALL_STATUSES: frozenset[str] = frozenset({
-    OK, EMPTY, ERROR, TIMEOUT, DISABLED, NOT_CONFIGURED, NO_EMBEDDING,
-    NO_CANDIDATES,
-})
-
-#: Every channel a recall can report on, so a caller can tell "this channel had
-#: no status recorded" (a gap in the reporting) from "this channel reported that
-#: it did nothing" (an answer). A missing key is a bug; ``empty`` is not.
-CHANNEL_NAMES: tuple[str, ...] = (
-    "semantic",
-    "bm25",
-    "temporal",
-    "hopfield",
-    "spreading_activation",
-    "entity_graph",
-    "profile",
-)
-
-#: Statuses that mean the answer is worse than it should have been. ``empty``,
-#: ``disabled`` and ``not_configured`` are deliberately absent: the first is a
-#: valid finding and the other two are somebody's decision.
-_FAULTS: frozenset[str] = frozenset({ERROR, TIMEOUT, NO_EMBEDDING})
-
-
-def is_fault(status: str | None) -> bool:
-    """Whether this status means the answer was degraded."""
-    return (status or "") in _FAULTS