memwal 0.2.2.dev5__tar.gz → 0.2.3__tar.gz

{memwal-0.2.2.dev5 → memwal-0.2.3}/CHANGELOG.md

@@ -1,5 +1,12 @@
 # memwal
 
+## 0.2.3
+
+### Added
+
+- `RecallResult` gains `degraded: bool = False`, set to `True` whenever one or more vector matches were dropped, and `recall()` returns the degraded result (`results=[]`, `degraded=True`, `dropped_count`) by default when all matches fail to download or decrypt. (#1036, #1070)
+- `recall()` and `RecallParams` accept `on_dropped: str = "ignore"` (`"ignore"` or `"throw"`) across `MemWal`, `MemWalSync`, `MemWalMock`, and `MemWalMockSync`. Passing `on_dropped="throw"` raises `MemWalRecallAllDropped` (`code = "RECALL_ALL_DROPPED"`, exposing `total`, `dropped_count`, and `namespace`) when all vector search matches are dropped during Walrus blob download or SEAL decryption. (#1036, #1070)
+
 ## 0.2.2
 
 Unreleased.

{memwal-0.2.2.dev5 → memwal-0.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: memwal
-Version: 0.2.2.dev5
+Version: 0.2.3
 Summary: Python SDK for Walrus Memory — Privacy-first AI memory with Ed25519 signing
 Project-URL: Homepage, https://memory.walrus.xyz
 Project-URL: Documentation, https://memory.walrus.xyz

{memwal-0.2.2.dev5 → memwal-0.2.3}/memwal/__init__.py

@@ -29,6 +29,7 @@ from .client import (
     MemWalError,
     MemWalJsonBodyError,
     MemWalRateLimited,
+    MemWalRecallAllDropped,
     MemWalRememberJobFailed,
     MemWalRememberJobNotFound,
     MemWalRememberJobTimeout,
@@ -87,6 +88,7 @@ __all__ = [
     "MemWalClockDriftError",
     "MemWalJsonBodyError",
     "MemWalRateLimited",
+    "MemWalRecallAllDropped",
     "MemWalRememberJobFailed",
     "MemWalRememberJobNotFound",
     "MemWalRememberJobTimeout",
@@ -132,4 +134,4 @@ __all__ = [
     "RecallManualResult",
 ]
 
-__version__ = "0.2.2.dev5"
+__version__ = "0.2.3"

{memwal-0.2.2.dev5 → memwal-0.2.3}/memwal/client.py

@@ -453,6 +453,15 @@ def _check_limit(limit: Any) -> None:
         raise ValueError(f"limit must be a positive integer, got {limit!r}")
 
 
+def _check_on_dropped(on_dropped: Any) -> str:
+    """Validate the recall all-dropped handling policy before signing."""
+    if on_dropped not in ("throw", "ignore"):
+        raise ValueError(
+            f"on_dropped must be 'throw' or 'ignore', got {on_dropped!r}"
+        )
+    return str(on_dropped)
+
+
 def _check_vector(vector: Any) -> None:
     """Reject a vector that is not a non-empty list of finite numbers (#1218).
 
@@ -1175,6 +1184,7 @@ class MemWal:
         limit: int = 10,
         namespace: Optional[str] = None,
         max_distance: Optional[float] = None,
+        on_dropped: str = "ignore",
     ) -> RecallResult:
         """Recall memories similar to a query.
 
@@ -1200,6 +1210,11 @@ class MemWal:
             max_distance: Optional client-side relevance threshold. Memories
                 with ``distance >= max_distance`` are dropped. Ignored when
                 ``query`` is a :class:`RecallParams`.
+            on_dropped: Policy when every matched memory failed download or
+                decrypt (``"ignore"`` by default returns the degraded
+                :class:`RecallResult` with ``degraded=True`` and
+                ``dropped_count``; ``"throw"`` raises
+                :class:`MemWalRecallAllDropped`).
 
         Returns:
             :class:`RecallResult` with decrypted text results.
@@ -1214,15 +1229,18 @@ class MemWal:
             max_distance = params.max_distance
             scoring_weights = params.scoring_weights
             sort = params.sort
+            on_dropped = params.on_dropped
         else:
             query_text = query
         _reject_blank_text(query_text, "query cannot be empty")
         _check_limit(limit)
         validate_max_distance(max_distance)
+        policy = _check_on_dropped(on_dropped)
+        resolved_namespace = self._resolve_namespace(namespace)
         body = {
             "query": query_text,
             "limit": limit,
-            "namespace": self._resolve_namespace(namespace),
+            "namespace": resolved_namespace,
         }
         if scoring_weights is not None:
             body["scoring_weights"] = scoring_weights.to_wire()
@@ -1241,16 +1259,34 @@ class MemWal:
         ]
         raw_dropped = data.get("dropped_count") or 0
         try:
-            dropped = int(raw_dropped)
+            dropped = max(0, int(raw_dropped))
         except (TypeError, ValueError):
             dropped = 0
-        total_count = data.get("total", len(memories))
+        degraded = bool(data.get("degraded")) or dropped > 0
+        raw_total = data.get("total", len(memories))
+        try:
+            total_count = int(raw_total)
+        except (TypeError, ValueError):
+            total_count = len(memories)
+
+        if len(memories) == 0 and degraded:
+            effective_dropped = dropped if dropped > 0 else max(1, total_count)
+            effective_total = max(total_count, effective_dropped)
+            if policy == "throw":
+                raise MemWalRecallAllDropped(
+                    dropped_count=effective_dropped,
+                    total=effective_total,
+                    namespace=resolved_namespace,
+                )
+            dropped = effective_dropped
+
         if max_distance is not None:
             memories = [m for m in memories if m.distance < max_distance]
         return RecallResult(
             results=memories,
             total=total_count,
             dropped_count=dropped,
+            degraded=degraded,
         )
 
     async def forget(self, namespace: Optional[str] = None) -> ForgetResult:
@@ -2311,6 +2347,27 @@ class MemWalRememberJobTimeout(MemWalError):
         self.last_refusal = last_refusal
 
 
+class MemWalRecallAllDropped(MemWalError):
+    """Raised by :meth:`MemWal.recall` when ``on_dropped="throw"`` is set and
+    every matched memory failed to download or decrypt (``results == []`` and
+    ``dropped_count > 0``).
+
+    By default (``on_dropped="ignore"``), :meth:`MemWal.recall` returns the
+    degraded :class:`RecallResult` without raising.
+    """
+
+    def __init__(self, dropped_count: int, total: int, namespace: str) -> None:
+        noun = "match" if total == 1 else "matches"
+        super().__init__(
+            f'MemWal recall matched {total} {noun} in namespace "{namespace}", '
+            f"but all {dropped_count} failed to download or decrypt"
+        )
+        self.code = "RECALL_ALL_DROPPED"
+        self.dropped_count = dropped_count
+        self.total = total
+        self.namespace = namespace
+
+
 async def _discard_http_client(memwal: MemWal) -> None:
     """Close the cached httpx client, and drop it either way.
 
@@ -2502,10 +2559,19 @@ class MemWalSync:
         limit: int = 10,
         namespace: Optional[str] = None,
         max_distance: Optional[float] = None,
+        on_dropped: str = "ignore",
     ) -> RecallResult:
         """Synchronous version of :meth:`MemWal.recall` (accepts
         :class:`RecallParams` for the recommended object-style call)."""
-        return self._run(self._inner.recall(query, limit, namespace, max_distance))
+        return self._run(
+            self._inner.recall(
+                query,
+                limit,
+                namespace,
+                max_distance,
+                on_dropped=on_dropped,
+            )
+        )
 
     def forget(self, namespace: Optional[str] = None) -> ForgetResult:
         """Synchronous version of :meth:`MemWal.forget`."""

{memwal-0.2.2.dev5 → memwal-0.2.3}/memwal/middleware.py

@@ -659,7 +659,9 @@ def with_memwal_langchain(
             return messages
 
         try:
-            recall_result = await memwal.recall(user_text, max_memories, namespace)
+            recall_result = await memwal.recall(
+                user_text, max_memories, namespace, on_dropped="throw"
+            )
             relevant = [
                 m for m in recall_result.results
                 if (1 - m.distance) >= min_relevance
@@ -837,7 +839,9 @@ def _wrap_async_openai(
             user_text = _find_last_user_message(messages)
             if user_text:
                 try:
-                    recall_result = await memwal.recall(user_text, max_memories, namespace)
+                    recall_result = await memwal.recall(
+                        user_text, max_memories, namespace, on_dropped="throw"
+                    )
                     relevant = [
                         m for m in recall_result.results
                         if (1 - m.distance) >= min_relevance
@@ -915,7 +919,9 @@ def _wrap_sync_openai(
             if user_text:
                 try:
                     recall_result = _run_memwal(
-                        lambda: memwal.recall(user_text, max_memories, namespace)
+                        lambda: memwal.recall(
+                            user_text, max_memories, namespace, on_dropped="throw"
+                        )
                     )
                     relevant = [
                         m for m in recall_result.results

{memwal-0.2.2.dev5 → memwal-0.2.3}/memwal/mock.py

@@ -267,6 +267,7 @@ class MemWalMock:
         limit: int = 10,
         namespace: Optional[str] = None,
         max_distance: Optional[float] = None,
+        on_dropped: str = "ignore",
     ) -> RecallResult:
         """Token-overlap recall over the in-memory store.
 
@@ -281,6 +282,7 @@ class MemWalMock:
             namespace = query.namespace
             max_distance = query.max_distance
             sort = query.sort
+            on_dropped = query.on_dropped
             query_text = query.query
         else:
             sort = None
@@ -288,6 +290,10 @@ class MemWalMock:
         _validate_text(query_text, "query")
         _check_limit(limit)
         validate_max_distance(max_distance)
+        if on_dropped not in ("throw", "ignore"):
+            raise ValueError(
+                f"on_dropped must be 'throw' or 'ignore', got {on_dropped!r}"
+            )
         if sort not in (None, "relevance", "recent"):
             raise ValueError("sort must be 'relevance' or 'recent'")
         resolved_namespace = self._namespace if namespace is None else namespace
@@ -670,9 +676,16 @@ class MemWalMockSync:
         limit: int = 10,
         namespace: Optional[str] = None,
         max_distance: Optional[float] = None,
+        on_dropped: str = "ignore",
     ) -> RecallResult:
         return self._run(
-            self._inner.recall(query, limit, namespace, max_distance)
+            self._inner.recall(
+                query,
+                limit,
+                namespace,
+                max_distance,
+                on_dropped=on_dropped,
+            )
         )
 
     def analyze(

{memwal-0.2.2.dev5 → memwal-0.2.3}/memwal/types.py

@@ -121,6 +121,7 @@ class RecallParams:
     max_distance: Optional[float] = None
     scoring_weights: Optional["ScoringWeights"] = None
     sort: Optional[str] = None
+    on_dropped: str = "ignore"
 
 
 @dataclass
@@ -132,6 +133,8 @@ class RecallResult:
     # Matches omitted because download or decrypt failed. 0 also means the
     # relayer omitted the field (older servers).
     dropped_count: int = 0
+    # True whenever one or more matched blobs were dropped (dropped_count > 0).
+    degraded: bool = False
 
 
 @dataclass

{memwal-0.2.2.dev5 → memwal-0.2.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "memwal"
-version = "0.2.2.dev5"
+version = "0.2.3"
 description = "Python SDK for Walrus Memory — Privacy-first AI memory with Ed25519 signing"
 readme = "README.md"
 license = "MIT"

{memwal-0.2.2.dev5 → memwal-0.2.3}/tests/test_client.py

@@ -25,6 +25,7 @@ from memwal.client import (
     MemWalCompatibilityError,
     MemWalError,
     MemWalRateLimited,
+    MemWalRecallAllDropped,
     MemWalRememberJobNotFound,
     MemWalRememberJobTimeout,
     MemWalSync,
@@ -830,7 +831,9 @@ class TestRecall:
         assert result.results[1].blob_id == "b2"
 
     @respx.mock
-    async def test_recall_surfaces_dropped_count(self, memwal_client: MemWal) -> None:
+    async def test_recall_returns_degraded_result_by_default_and_raises_on_throw(
+        self, memwal_client: MemWal
+    ) -> None:
         mock_seal_session_prereqs()
         respx.post(f"{_TEST_SERVER}/api/recall").mock(
             return_value=httpx.Response(
@@ -838,9 +841,80 @@ class TestRecall:
                 json={"results": [], "total": 0, "dropped_count": 3},
             )
         )
-        result = await memwal_client.recall("coffee")
-        assert result.results == []
-        assert result.dropped_count == 3
+        omitted = await memwal_client.recall("coffee")
+        assert omitted.results == []
+        assert omitted.dropped_count == 3
+        assert omitted.total == 0
+        assert omitted.degraded is True
+
+        omitted_params = await memwal_client.recall(RecallParams(query="coffee"))
+        assert omitted_params.results == []
+        assert omitted_params.dropped_count == 3
+        assert omitted_params.total == 0
+        assert omitted_params.degraded is True
+
+        explicit_ignore = await memwal_client.recall(
+            RecallParams(query="coffee", on_dropped="ignore")
+        )
+        assert explicit_ignore.results == []
+        assert explicit_ignore.dropped_count == 3
+        assert explicit_ignore.total == 0
+        assert explicit_ignore.degraded is True
+
+        with pytest.raises(MemWalRecallAllDropped) as exc_info:
+            await memwal_client.recall("coffee", on_dropped="throw")
+        assert exc_info.value.code == "RECALL_ALL_DROPPED"
+        assert exc_info.value.dropped_count == 3
+        assert exc_info.value.total == 3
+        assert exc_info.value.namespace == "default"
+
+        with pytest.raises(MemWalRecallAllDropped) as params_exc:
+            await memwal_client.recall(
+                RecallParams(query="coffee", namespace="profile", on_dropped="throw")
+            )
+        assert params_exc.value.code == "RECALL_ALL_DROPPED"
+        assert params_exc.value.dropped_count == 3
+        assert params_exc.value.total == 3
+        assert params_exc.value.namespace == "profile"
+
+        sync_client = MemWalSync(memwal_client)
+        sync_default = sync_client.recall("coffee")
+        assert sync_default.results == []
+        assert sync_default.dropped_count == 3
+        assert sync_default.total == 0
+        assert sync_default.degraded is True
+
+        with pytest.raises(MemWalRecallAllDropped):
+            sync_client.recall("coffee", on_dropped="throw")
+
+        with pytest.raises(ValueError, match="on_dropped"):
+            await memwal_client.recall("coffee", on_dropped="warn")
+
+    @respx.mock
+    async def test_recall_preserves_dropped_count_with_max_distance(
+        self, memwal_client: MemWal
+    ) -> None:
+        mock_seal_session_prereqs()
+        respx.post(f"{_TEST_SERVER}/api/recall").mock(
+            return_value=httpx.Response(
+                200,
+                json={
+                    "results": [
+                        {"blob_id": "b1", "text": "near hit", "distance": 0.1},
+                        {"blob_id": "b2", "text": "far hit", "distance": 0.9},
+                    ],
+                    "total": 2,
+                    "dropped_count": 25,
+                },
+            )
+        )
+        result = await memwal_client.recall(
+            RecallParams(query="coffee", max_distance=0.5)
+        )
+        assert [m.blob_id for m in result.results] == ["b1"]
+        assert result.total == 2
+        assert result.dropped_count == 25
+        assert result.degraded is True
 
     @respx.mock
     async def test_recall_preserves_score_and_created_at(

{memwal-0.2.2.dev5 → memwal-0.2.3}/tests/test_mock.py

@@ -8,6 +8,7 @@ import re
 import pytest
 
 from memwal import (
+    MemWal,
     MemWalMock,
     MemWalMockSeed,
     MemWalMockSync,
@@ -202,6 +203,7 @@ def test_sync_mock_polling_and_analyze_signatures_match_production():
         "remember_and_wait",
         "wait_for_remember_jobs",
         "remember_bulk_and_wait",
+        "recall",
         "analyze",
         "analyze_and_wait",
         "forget_namespace",
@@ -217,6 +219,20 @@ def test_sync_mock_polling_and_analyze_signatures_match_production():
         assert parameter_contract(getattr(MemWalMockSync, method_name)) == parameter_contract(
             getattr(MemWalSync, method_name)
         )
+    assert parameter_contract(MemWalMock.recall) == parameter_contract(MemWal.recall)
+    assert inspect.signature(MemWalMock.recall).parameters["on_dropped"].default == "ignore"
+    assert RecallParams(query="x").on_dropped == "ignore"
+
+    async_mock = MemWalMock.create(
+        namespace="sync",
+        initial_memories=[MemWalMockSeed(text="coffee preference", namespace="sync")],
+    )
+    sync_mock = MemWalMockSync(async_mock)
+    assert sync_mock.recall("coffee").total == 1
+    assert sync_mock.recall("coffee", on_dropped="ignore").total == 1
+    assert sync_mock.recall("coffee", on_dropped="throw").total == 1
+    with pytest.raises(ValueError, match="on_dropped"):
+        sync_mock.recall("coffee", on_dropped="warn")
 
 
 @pytest.mark.asyncio