memwal 0.1.6.dev0__tar.gz → 0.1.6.dev2__tar.gz

{memwal-0.1.6.dev0 → memwal-0.1.6.dev2}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: memwal
-Version: 0.1.6.dev0
+Version: 0.1.6.dev2
 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
@@ -124,6 +124,23 @@ matches = client.recall(RecallParams(query="food allergies"))
 client.close()
 ```
 
+### Offline tests and CI
+
+`MemWalMock` and `MemWalMockSync` implement the common memory API in process. They require no credentials, relayer, chain, or paid storage and use deterministic token-overlap ranking.
+
+```python
+from memwal import MemWalMock, RecallParams
+
+async def test_memory_flow():
+    memwal = MemWalMock.create(namespace="test-user")
+    await memwal.remember_and_wait("The user prefers dark mode")
+
+    result = await memwal.recall(RecallParams(query="display preference"))
+    assert "dark mode" in result.results[0].text
+```
+
+The mock supports remember/job polling, bulk remember, recall, analyze, embed, ask, health, restore, `forget(blob_id)`, and `clear(namespace)`. For deterministic behavior, `analyze` stores its full input as one fact instead of invoking an LLM extractor. Its simple relevance score is for application tests, not production search-quality evaluation.
+
 ### Context Manager
 
 ```python

{memwal-0.1.6.dev0 → memwal-0.1.6.dev2}/README.md

@@ -85,6 +85,23 @@ matches = client.recall(RecallParams(query="food allergies"))
 client.close()
 ```
 
+### Offline tests and CI
+
+`MemWalMock` and `MemWalMockSync` implement the common memory API in process. They require no credentials, relayer, chain, or paid storage and use deterministic token-overlap ranking.
+
+```python
+from memwal import MemWalMock, RecallParams
+
+async def test_memory_flow():
+    memwal = MemWalMock.create(namespace="test-user")
+    await memwal.remember_and_wait("The user prefers dark mode")
+
+    result = await memwal.recall(RecallParams(query="display preference"))
+    assert "dark mode" in result.results[0].text
+```
+
+The mock supports remember/job polling, bulk remember, recall, analyze, embed, ask, health, restore, `forget(blob_id)`, and `clear(namespace)`. For deterministic behavior, `analyze` stores its full input as one fact instead of invoking an LLM extractor. Its simple relevance score is for application tests, not production search-quality evaluation.
+
 ### Context Manager
 
 ```python

{memwal-0.1.6.dev0 → memwal-0.1.6.dev2}/memwal/__init__.py

@@ -32,6 +32,7 @@ from .client import (
     MemWalSync,
 )
 from .middleware import with_memwal_langchain, with_memwal_openai
+from .mock import MemWalMock, MemWalMockSeed, MemWalMockSync
 from .types import (
     ENV_PRESETS,
     AnalyzedFact,
@@ -72,6 +73,9 @@ __all__ = [
     # Core client
     "MemWal",
     "MemWalSync",
+    "MemWalMock",
+    "MemWalMockSync",
+    "MemWalMockSeed",
     "MemWalError",
     "MemWalCompatibilityError",
     "MemWalRememberJobFailed",
@@ -116,4 +120,4 @@ __all__ = [
     "RecallManualResult",
 ]
 
-__version__ = "0.1.6.dev0"
+__version__ = "0.1.6.dev2"

{memwal-0.1.6.dev0 → memwal-0.1.6.dev2}/memwal/client.py

@@ -30,6 +30,7 @@ import base64
 import json
 import random
 import time
+import uuid
 from datetime import datetime, timezone
 from typing import Any, Dict, List, Optional, Sequence, Tuple, TypeVar, Union
 
@@ -223,6 +224,9 @@ class MemWal:
         self._session_build_task: Optional[asyncio.Task[str]] = None
         self._relayer_version_metadata: Optional[Dict[str, Any]] = None
         self._compatibility_lock: Optional[asyncio.Lock] = None
+        # Preserve a generated key across an ambiguous transport failure. A
+        # subsequent identical call then collapses onto the accepted paid job.
+        self._pending_remember_keys: Dict[str, str] = {}
 
     @classmethod
     def create(
@@ -281,7 +285,10 @@ class MemWal:
     # ============================================================
 
     async def remember(
-        self, text: str, namespace: Optional[str] = None
+        self,
+        text: str,
+        namespace: Optional[str] = None,
+        idempotency_key: Optional[str] = None,
     ) -> RememberAcceptedResult:
         """Submit a remember request and return as soon as the server accepts it.
 
@@ -299,12 +306,27 @@ class MemWal:
             :class:`RememberAcceptedResult` with ``job_id`` and initial
             status (``"pending"``).
         """
+        resolved_namespace = namespace or self._namespace
+        request_identity = f"{resolved_namespace}\0{text}"
+        generated_key = idempotency_key is None
+        resolved_key = idempotency_key or self._pending_remember_keys.get(request_identity)
+        if resolved_key is None:
+            resolved_key = str(uuid.uuid4())
+        if generated_key:
+            self._pending_remember_keys[request_identity] = resolved_key
+
         data = await self._signed_request(
             "POST",
             "/api/remember",
-            {"text": text, "namespace": namespace or self._namespace},
+            {
+                "text": text,
+                "namespace": resolved_namespace,
+                "idempotency_key": resolved_key,
+            },
             accepted_statuses=(200, 202),
         )
+        if generated_key:
+            self._pending_remember_keys.pop(request_identity, None)
         return RememberAcceptedResult(
             job_id=data["job_id"],
             status=data.get("status", "pending"),
@@ -312,9 +334,12 @@ class MemWal:
 
     # Alias for parity with TS SDK ``rememberAsync``.
     async def remember_async(
-        self, text: str, namespace: Optional[str] = None
+        self,
+        text: str,
+        namespace: Optional[str] = None,
+        idempotency_key: Optional[str] = None,
     ) -> RememberAcceptedResult:
-        return await self.remember(text, namespace)
+        return await self.remember(text, namespace, idempotency_key)
 
     async def wait_for_remember_job(
         self,
@@ -380,6 +405,7 @@ class MemWal:
         namespace: Optional[str] = None,
         poll_interval_ms: int = 1500,
         timeout_ms: int = 60_000,
+        idempotency_key: Optional[str] = None,
     ) -> RememberResult:
         """Submit a remember and wait for the background worker to finish.
 
@@ -388,12 +414,24 @@ class MemWal:
         ``failed``). Mirrors TS ``rememberAndWait``.
         """
 
-        accepted = await self.remember(text, namespace)
-        return await self.wait_for_remember_job(
+        resolved_namespace = namespace or self._namespace
+        request_identity = f"{resolved_namespace}\0{text}"
+        generated_key = idempotency_key is None
+        resolved_key = idempotency_key or self._pending_remember_keys.get(request_identity)
+        if resolved_key is None:
+            resolved_key = str(uuid.uuid4())
+        if generated_key:
+            self._pending_remember_keys[request_identity] = resolved_key
+
+        accepted = await self.remember(text, resolved_namespace, resolved_key)
+        result = await self.wait_for_remember_job(
             accepted.job_id,
             poll_interval_ms=poll_interval_ms,
             timeout_ms=timeout_ms,
         )
+        if generated_key:
+            self._pending_remember_keys.pop(request_identity, None)
+        return result
 
     # ============================================================
     # Bulk remember (ENG-1408)
@@ -1285,16 +1323,22 @@ class MemWalSync:
             return asyncio.run(coro)
 
     def remember(
-        self, text: str, namespace: Optional[str] = None
+        self,
+        text: str,
+        namespace: Optional[str] = None,
+        idempotency_key: Optional[str] = None,
     ) -> RememberAcceptedResult:
         """Synchronous version of :meth:`MemWal.remember` (async accept)."""
-        return self._run(self._inner.remember(text, namespace))
+        return self._run(self._inner.remember(text, namespace, idempotency_key))
 
     # Alias for parity with TS SDK ``rememberAsync``.
     def remember_async(
-        self, text: str, namespace: Optional[str] = None
+        self,
+        text: str,
+        namespace: Optional[str] = None,
+        idempotency_key: Optional[str] = None,
     ) -> RememberAcceptedResult:
-        return self._run(self._inner.remember_async(text, namespace))
+        return self._run(self._inner.remember_async(text, namespace, idempotency_key))
 
     def wait_for_remember_job(
         self,
@@ -1317,6 +1361,7 @@ class MemWalSync:
         namespace: Optional[str] = None,
         poll_interval_ms: int = 1500,
         timeout_ms: int = 60_000,
+        idempotency_key: Optional[str] = None,
     ) -> RememberResult:
         """Synchronous version of :meth:`MemWal.remember_and_wait`."""
         return self._run(
@@ -1325,6 +1370,7 @@ class MemWalSync:
                 namespace,
                 poll_interval_ms=poll_interval_ms,
                 timeout_ms=timeout_ms,
+                idempotency_key=idempotency_key,
             )
         )
 

memwal-0.1.6.dev2/memwal/mock.py

@@ -0,0 +1,585 @@
+"""Deterministic, dependency-free in-memory Walrus Memory client for tests."""
+
+from __future__ import annotations
+
+import asyncio
+import math
+import re
+import unicodedata
+from dataclasses import dataclass
+from datetime import datetime
+from typing import Any, Dict, List, Optional, Sequence, Union
+
+from .types import (
+    AnalyzedFact,
+    AnalyzeResult,
+    AnalyzeWaitResult,
+    AskMemory,
+    AskResult,
+    EmbedResult,
+    HealthResult,
+    RecallMemory,
+    RecallParams,
+    RecallResult,
+    RememberAcceptedResult,
+    RememberBulkAcceptedResult,
+    RememberBulkItem,
+    RememberBulkItemResult,
+    RememberBulkOptions,
+    RememberBulkResult,
+    RememberBulkStatusItem,
+    RememberBulkStatusResult,
+    RememberJobStatus,
+    RememberResult,
+    RestoreResult,
+)
+
+
+@dataclass
+class MemWalMockSeed:
+    """One optional memory loaded when a mock is created."""
+
+    text: str
+    namespace: Optional[str] = None
+    blob_id: Optional[str] = None
+
+
+@dataclass
+class _Memory:
+    id: str
+    job_id: str
+    blob_id: str
+    text: str
+    namespace: str
+    sequence: int
+
+
+def _tokens(text: str) -> set[str]:
+    normalized = unicodedata.normalize("NFKC", text).casefold()
+    return set(re.findall(r"[^\W_]+", normalized, flags=re.UNICODE))
+
+
+def _distance(query_tokens: set[str], text: str) -> float:
+    if not query_tokens:
+        return 1.0
+    matches = len(query_tokens.intersection(_tokens(text)))
+    return 1.0 - matches / len(query_tokens)
+
+
+def _validate_text(text: str, field: str = "text") -> None:
+    if not isinstance(text, str) or not text.strip():
+        raise ValueError(f"{field} cannot be empty")
+
+
+class MemWalMock:
+    """In-memory implementation of the common async :class:`MemWal` API.
+
+    The mock never creates an HTTP client or contacts Sui/Walrus. Recall uses
+    deterministic token-overlap distance; it is intentionally simple and is
+    designed for application tests, not relevance benchmarking.
+    """
+
+    def __init__(
+        self,
+        namespace: str = "default",
+        owner: str = "mock-owner",
+        initial_memories: Optional[Sequence[MemWalMockSeed]] = None,
+    ) -> None:
+        if not namespace:
+            raise ValueError("namespace cannot be empty")
+        self._namespace = namespace
+        self._owner = owner
+        self._memories: List[_Memory] = []
+        self._jobs: Dict[str, _Memory] = {}
+        self._sequence = 0
+        for seed in initial_memories or []:
+            self._store(seed.text, seed.namespace, seed.blob_id)
+
+    @classmethod
+    def create(
+        cls,
+        namespace: str = "default",
+        owner: str = "mock-owner",
+        initial_memories: Optional[Sequence[MemWalMockSeed]] = None,
+    ) -> "MemWalMock":
+        return cls(namespace, owner, initial_memories)
+
+    async def close(self) -> None:
+        """No-op for API parity with :class:`MemWal`."""
+
+    async def __aenter__(self) -> "MemWalMock":
+        return self
+
+    async def __aexit__(self, *exc: Any) -> None:
+        await self.close()
+
+    async def remember(
+        self, text: str, namespace: Optional[str] = None
+    ) -> RememberAcceptedResult:
+        memory = self._store(text, namespace)
+        return RememberAcceptedResult(job_id=memory.job_id, status="done")
+
+    async def remember_async(
+        self, text: str, namespace: Optional[str] = None
+    ) -> RememberAcceptedResult:
+        return await self.remember(text, namespace)
+
+    async def wait_for_remember_job(
+        self,
+        job_id: str,
+        poll_interval_ms: int = 1500,
+        timeout_ms: int = 60_000,
+    ) -> RememberResult:
+        del poll_interval_ms, timeout_ms
+        memory = self._jobs.get(job_id)
+        if memory is None:
+            raise KeyError(f"Remember job not found: {job_id}")
+        return self._remember_result(memory)
+
+    async def remember_and_wait(
+        self,
+        text: str,
+        namespace: Optional[str] = None,
+        poll_interval_ms: int = 1500,
+        timeout_ms: int = 60_000,
+    ) -> RememberResult:
+        accepted = await self.remember(text, namespace)
+        return await self.wait_for_remember_job(
+            accepted.job_id, poll_interval_ms, timeout_ms
+        )
+
+    async def get_remember_status(self, job_id: str) -> RememberJobStatus:
+        memory = self._jobs.get(job_id)
+        if memory is None:
+            return RememberJobStatus(job_id=job_id, status="not_found")
+        return RememberJobStatus(
+            job_id=job_id,
+            status="done",
+            owner=self._owner,
+            namespace=memory.namespace,
+            blob_id=memory.blob_id,
+        )
+
+    async def remember_bulk_async(
+        self, items: Sequence[RememberBulkItem]
+    ) -> RememberBulkAcceptedResult:
+        job_ids = [self._store(item.text, item.namespace).job_id for item in items]
+        return RememberBulkAcceptedResult(
+            job_ids=job_ids, total=len(job_ids), status="done"
+        )
+
+    async def remember_bulk(
+        self, items: Sequence[RememberBulkItem]
+    ) -> RememberBulkAcceptedResult:
+        return await self.remember_bulk_async(items)
+
+    async def get_remember_bulk_status(
+        self, job_ids: Sequence[str]
+    ) -> RememberBulkStatusResult:
+        results = []
+        for job_id in job_ids:
+            memory = self._jobs.get(job_id)
+            results.append(
+                RememberBulkStatusItem(
+                    job_id=job_id,
+                    status="done" if memory else "not_found",
+                    blob_id=memory.blob_id if memory else None,
+                )
+            )
+        return RememberBulkStatusResult(results=results)
+
+    async def wait_for_remember_jobs(
+        self,
+        job_ids: Sequence[str],
+        opts: Optional[RememberBulkOptions] = None,
+    ) -> RememberBulkResult:
+        del opts
+        results: List[RememberBulkItemResult] = []
+        for job_id in job_ids:
+            memory = self._jobs.get(job_id)
+            results.append(
+                RememberBulkItemResult(
+                    id=job_id,
+                    blob_id=memory.blob_id if memory else "",
+                    status="done" if memory else "failed",
+                    error=None if memory else "Remember job not found",
+                )
+            )
+        succeeded = sum(result.status == "done" for result in results)
+        return RememberBulkResult(
+            results=results,
+            total=len(results),
+            succeeded=succeeded,
+            failed=len(results) - succeeded,
+            timed_out=0,
+        )
+
+    async def remember_bulk_and_wait(
+        self,
+        items: Sequence[RememberBulkItem],
+        opts: Optional[RememberBulkOptions] = None,
+    ) -> RememberBulkResult:
+        accepted = await self.remember_bulk_async(items)
+        return await self.wait_for_remember_jobs(accepted.job_ids, opts)
+
+    async def recall(
+        self,
+        query: Union[str, RecallParams],
+        limit: int = 10,
+        namespace: Optional[str] = None,
+        max_distance: Optional[float] = None,
+    ) -> RecallResult:
+        if isinstance(query, RecallParams):
+            limit = query.limit
+            namespace = query.namespace
+            max_distance = query.max_distance
+            query_text = query.query
+        else:
+            query_text = query
+        _validate_text(query_text, "query")
+        if not isinstance(limit, int) or limit < 0:
+            raise ValueError("limit must be a non-negative integer")
+        resolved_namespace = namespace or self._namespace
+        query_tokens = _tokens(query_text)
+        ranked = [
+            (memory, _distance(query_tokens, memory.text))
+            for memory in self._memories
+            if memory.namespace == resolved_namespace
+        ]
+        if max_distance is not None:
+            ranked = [item for item in ranked if item[1] < max_distance]
+        ranked.sort(key=lambda item: (item[1], item[0].sequence))
+        results = [
+            RecallMemory(blob_id=memory.blob_id, text=memory.text, distance=score)
+            for memory, score in ranked[:limit]
+        ]
+        return RecallResult(results=results, total=len(results))
+
+    async def analyze(
+        self,
+        text: str,
+        namespace: Optional[str] = None,
+        occurred_at: Optional[Union[str, datetime]] = None,
+    ) -> AnalyzeResult:
+        del occurred_at
+        memory = self._store(text, namespace)
+        return AnalyzeResult(
+            facts=[
+                AnalyzedFact(
+                    text=text, id=memory.id, blob_id=memory.blob_id
+                )
+            ],
+            fact_count=1,
+            job_ids=[memory.job_id],
+            status="done",
+            owner=self._owner,
+        )
+
+    async def analyze_and_wait(
+        self,
+        text: str,
+        namespace: Optional[str] = None,
+        opts: Optional[RememberBulkOptions] = None,
+        occurred_at: Optional[Union[str, datetime]] = None,
+    ) -> AnalyzeWaitResult:
+        analyzed = await self.analyze(text, namespace, occurred_at=occurred_at)
+        settled = await self.wait_for_remember_jobs(analyzed.job_ids, opts)
+        return AnalyzeWaitResult(
+            results=settled.results,
+            total=settled.total,
+            succeeded=settled.succeeded,
+            failed=settled.failed,
+            timed_out=settled.timed_out,
+            facts=analyzed.facts,
+            owner=self._owner,
+        )
+
+    async def embed(self, text: str) -> EmbedResult:
+        _validate_text(text)
+        vector = [0.0] * 16
+        for token in _tokens(text):
+            value = 2166136261
+            for char in token:
+                value ^= ord(char)
+                value = (value * 16777619) & 0xFFFFFFFF
+            vector[value % len(vector)] += 1.0
+        magnitude = math.sqrt(sum(value * value for value in vector)) or 1.0
+        return EmbedResult(vector=[value / magnitude for value in vector])
+
+    async def ask(
+        self, question: str, limit: int = 5, namespace: Optional[str] = None
+    ) -> AskResult:
+        recalled = await self.recall(question, limit, namespace)
+        memories = [
+            AskMemory(
+                blob_id=memory.blob_id,
+                text=memory.text,
+                distance=memory.distance,
+            )
+            for memory in recalled.results
+        ]
+        return AskResult(
+            answer="\n".join(memory.text for memory in memories),
+            memories_used=len(memories),
+            memories=memories,
+        )
+
+    async def restore(self, namespace: str, limit: int = 10) -> RestoreResult:
+        del limit
+        return RestoreResult(
+            restored=0,
+            skipped=0,
+            total=0,
+            namespace=namespace,
+            owner=self._owner,
+            truncated=False,
+        )
+
+    async def health(self) -> HealthResult:
+        return HealthResult(
+            status="ok",
+            version="memwal-mock",
+            relayer_version="memwal-mock",
+            api_version="1.0.0",
+            min_supported_sdk={"typescript": "0.0.0", "python": "0.0.0", "mcp": "0.0.0"},
+            feature_flags={"offlineMock": True},
+            deprecations=[],
+            build={},
+        )
+
+    async def compatibility(self) -> Dict[str, Any]:
+        return {
+            "relayerVersion": "memwal-mock",
+            "apiVersion": "1.0.0",
+            "minSupportedSdk": {
+                "typescript": "0.0.0",
+                "python": "0.0.0",
+                "mcp": "0.0.0",
+            },
+            "featureFlags": {"offlineMock": True},
+            "deprecations": [],
+            "build": {},
+        }
+
+    def forget(self, blob_id: str) -> bool:
+        for index, memory in enumerate(self._memories):
+            if memory.blob_id == blob_id:
+                self._memories.pop(index)
+                self._jobs.pop(memory.job_id, None)
+                return True
+        return False
+
+    def clear(self, namespace: Optional[str] = None) -> int:
+        removed = [
+            memory
+            for memory in self._memories
+            if namespace is None or memory.namespace == namespace
+        ]
+        self._memories = [
+            memory
+            for memory in self._memories
+            if namespace is not None and memory.namespace != namespace
+        ]
+        for memory in removed:
+            self._jobs.pop(memory.job_id, None)
+        return len(removed)
+
+    def _store(
+        self,
+        text: str,
+        namespace: Optional[str] = None,
+        blob_id: Optional[str] = None,
+    ) -> _Memory:
+        _validate_text(text)
+        resolved_namespace = namespace or self._namespace
+        if not resolved_namespace:
+            raise ValueError("namespace cannot be empty")
+        self._sequence += 1
+        suffix = f"{self._sequence:06d}"
+        memory = _Memory(
+            id=f"mock-job-{suffix}",
+            job_id=f"mock-job-{suffix}",
+            blob_id=blob_id or f"mock-blob-{suffix}",
+            text=text,
+            namespace=resolved_namespace,
+            sequence=self._sequence,
+        )
+        self._memories.append(memory)
+        self._jobs[memory.job_id] = memory
+        return memory
+
+    def _remember_result(self, memory: _Memory) -> RememberResult:
+        return RememberResult(
+            id=memory.id,
+            blob_id=memory.blob_id,
+            owner=self._owner,
+            namespace=memory.namespace,
+        )
+
+
+class MemWalMockSync:
+    """Synchronous wrapper around :class:`MemWalMock` for non-async tests."""
+
+    def __init__(self, inner: MemWalMock) -> None:
+        self._inner = inner
+
+    @classmethod
+    def create(
+        cls,
+        namespace: str = "default",
+        owner: str = "mock-owner",
+        initial_memories: Optional[Sequence[MemWalMockSeed]] = None,
+    ) -> "MemWalMockSync":
+        return cls(MemWalMock.create(namespace, owner, initial_memories))
+
+    @staticmethod
+    def _run(coro: Any) -> Any:
+        try:
+            loop = asyncio.get_running_loop()
+        except RuntimeError:
+            loop = None
+
+        if loop is not None and loop.is_running():
+            # Match MemWalSync in notebooks and other hosts with a live loop:
+            # execute the coroutine on a fresh event loop in a worker thread.
+            import concurrent.futures
+
+            with concurrent.futures.ThreadPoolExecutor(max_workers=1) as pool:
+                return pool.submit(asyncio.run, coro).result()
+        return asyncio.run(coro)
+
+    def remember(self, text: str, namespace: Optional[str] = None) -> RememberAcceptedResult:
+        return self._run(self._inner.remember(text, namespace))
+
+    def remember_async(
+        self, text: str, namespace: Optional[str] = None
+    ) -> RememberAcceptedResult:
+        return self.remember(text, namespace)
+
+    def wait_for_remember_job(
+        self,
+        job_id: str,
+        poll_interval_ms: int = 1500,
+        timeout_ms: int = 60_000,
+    ) -> RememberResult:
+        return self._run(
+            self._inner.wait_for_remember_job(
+                job_id,
+                poll_interval_ms=poll_interval_ms,
+                timeout_ms=timeout_ms,
+            )
+        )
+
+    def get_remember_status(self, job_id: str) -> RememberJobStatus:
+        return self._run(self._inner.get_remember_status(job_id))
+
+    def remember_and_wait(
+        self,
+        text: str,
+        namespace: Optional[str] = None,
+        poll_interval_ms: int = 1500,
+        timeout_ms: int = 60_000,
+    ) -> RememberResult:
+        return self._run(
+            self._inner.remember_and_wait(
+                text,
+                namespace,
+                poll_interval_ms=poll_interval_ms,
+                timeout_ms=timeout_ms,
+            )
+        )
+
+    def remember_bulk_async(
+        self, items: Sequence[RememberBulkItem]
+    ) -> RememberBulkAcceptedResult:
+        return self._run(self._inner.remember_bulk_async(items))
+
+    def remember_bulk(
+        self, items: Sequence[RememberBulkItem]
+    ) -> RememberBulkAcceptedResult:
+        return self.remember_bulk_async(items)
+
+    def get_remember_bulk_status(
+        self, job_ids: Sequence[str]
+    ) -> RememberBulkStatusResult:
+        return self._run(self._inner.get_remember_bulk_status(job_ids))
+
+    def wait_for_remember_jobs(
+        self,
+        job_ids: Sequence[str],
+        opts: Optional[RememberBulkOptions] = None,
+    ) -> RememberBulkResult:
+        return self._run(self._inner.wait_for_remember_jobs(job_ids, opts))
+
+    def remember_bulk_and_wait(
+        self,
+        items: Sequence[RememberBulkItem],
+        opts: Optional[RememberBulkOptions] = None,
+    ) -> RememberBulkResult:
+        return self._run(self._inner.remember_bulk_and_wait(items, opts))
+
+    def recall(
+        self,
+        query: Union[str, RecallParams],
+        limit: int = 10,
+        namespace: Optional[str] = None,
+        max_distance: Optional[float] = None,
+    ) -> RecallResult:
+        return self._run(
+            self._inner.recall(query, limit, namespace, max_distance)
+        )
+
+    def analyze(
+        self,
+        text: str,
+        namespace: Optional[str] = None,
+        occurred_at: Optional[Union[str, datetime]] = None,
+    ) -> AnalyzeResult:
+        return self._run(
+            self._inner.analyze(text, namespace, occurred_at=occurred_at)
+        )
+
+    def analyze_and_wait(
+        self,
+        text: str,
+        namespace: Optional[str] = None,
+        opts: Optional[RememberBulkOptions] = None,
+        occurred_at: Optional[Union[str, datetime]] = None,
+    ) -> AnalyzeWaitResult:
+        return self._run(
+            self._inner.analyze_and_wait(
+                text, namespace, opts, occurred_at=occurred_at
+            )
+        )
+
+    def embed(self, text: str) -> EmbedResult:
+        return self._run(self._inner.embed(text))
+
+    def ask(
+        self, question: str, limit: int = 5, namespace: Optional[str] = None
+    ) -> AskResult:
+        return self._run(self._inner.ask(question, limit, namespace))
+
+    def restore(self, namespace: str, limit: int = 10) -> RestoreResult:
+        return self._run(self._inner.restore(namespace, limit))
+
+    def health(self) -> HealthResult:
+        return self._run(self._inner.health())
+
+    def compatibility(self) -> Dict[str, Any]:
+        return self._run(self._inner.compatibility())
+
+    def forget(self, blob_id: str) -> bool:
+        return self._inner.forget(blob_id)
+
+    def clear(self, namespace: Optional[str] = None) -> int:
+        return self._inner.clear(namespace)
+
+    def close(self) -> None:
+        self._run(self._inner.close())
+
+    def __enter__(self) -> "MemWalMockSync":
+        return self
+
+    def __exit__(self, *exc: Any) -> None:
+        self.close()

{memwal-0.1.6.dev0 → memwal-0.1.6.dev2}/pyproject.toml

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

memwal-0.1.6.dev2/tests/test_mock.py

@@ -0,0 +1,162 @@
+"""Offline mock client regression tests."""
+
+import inspect
+
+import pytest
+
+from memwal import (
+    MemWalMock,
+    MemWalMockSeed,
+    MemWalMockSync,
+    MemWalSync,
+    RecallParams,
+    RememberBulkItem,
+    RememberBulkOptions,
+)
+
+
+@pytest.mark.asyncio
+async def test_mock_remember_and_recall_are_deterministic_and_offline(monkeypatch):
+    def reject_network(*args, **kwargs):
+        raise AssertionError("MemWalMock must not create a network client")
+
+    monkeypatch.setattr("httpx.AsyncClient", reject_network)
+    mock = MemWalMock.create(namespace="user-a", owner="test-owner")
+    coffee = await mock.remember_and_wait("I prefer coffee in the morning")
+    tea = await mock.remember_and_wait("I drink tea at night")
+
+    assert coffee.id == "mock-job-000001"
+    assert coffee.blob_id == "mock-blob-000001"
+    assert coffee.namespace == "user-a"
+    assert tea.blob_id == "mock-blob-000002"
+
+    recalled = await mock.recall(RecallParams(query="morning coffee", limit=2))
+    assert [memory.text for memory in recalled.results] == [
+        "I prefer coffee in the morning",
+        "I drink tea at night",
+    ]
+    assert recalled.results[0].distance == 0
+    assert recalled.results[1].distance == 1
+
+
+@pytest.mark.asyncio
+async def test_mock_isolates_namespaces_and_honors_max_distance():
+    mock = MemWalMock.create()
+    await mock.remember_and_wait("Alice likes ramen", "user-a")
+    await mock.remember_and_wait("Bob likes tacos", "user-b")
+
+    alice = await mock.recall(
+        RecallParams(query="likes", namespace="user-a", max_distance=0.5)
+    )
+    bob = await mock.recall("likes", namespace="user-b")
+    empty = await mock.recall("likes")
+
+    assert [memory.text for memory in alice.results] == ["Alice likes ramen"]
+    assert [memory.text for memory in bob.results] == ["Bob likes tacos"]
+    assert empty.total == 0
+
+
+@pytest.mark.asyncio
+async def test_mock_supports_jobs_bulk_analyze_forget_and_clear():
+    mock = MemWalMock.create()
+    accepted = await mock.remember("single fact")
+    status = await mock.get_remember_status(accepted.job_id)
+    assert status.status == "done"
+    assert status.blob_id == "mock-blob-000001"
+
+    bulk = await mock.remember_bulk_and_wait(
+        [
+            RememberBulkItem(text="bulk one", namespace="one"),
+            RememberBulkItem(text="bulk two", namespace="two"),
+        ]
+    )
+    assert bulk.succeeded == 2
+    assert bulk.failed == 0
+
+    analyzed = await mock.analyze_and_wait("durable analyzed fact", "analysis")
+    assert analyzed.facts[0].text == "durable analyzed fact"
+
+    assert mock.forget("mock-blob-000001") is True
+    assert mock.forget("missing") is False
+    assert mock.clear("one") == 1
+    assert (await mock.recall("bulk", namespace="one")).total == 0
+
+
+@pytest.mark.asyncio
+async def test_mock_seed_embed_health_and_compatibility():
+    first = MemWalMock.create(
+        initial_memories=[
+            MemWalMockSeed(text="seed memory", namespace="seed", blob_id="seed-blob")
+        ]
+    )
+    second = MemWalMock.create()
+
+    assert await first.embed("same text") == await second.embed("same text")
+    recalled = await first.recall("seed", namespace="seed")
+    assert recalled.results[0].blob_id == "seed-blob"
+    assert (await first.health()).status == "ok"
+    assert (await first.compatibility())["featureFlags"]["offlineMock"] is True
+
+
+def test_sync_mock_wraps_core_flows_and_accepts_production_options():
+    mock = MemWalMockSync.create(namespace="sync")
+    opts = RememberBulkOptions(poll_interval_ms=1, timeout_ms=10)
+
+    accepted = mock.remember("accepted memory")
+    stored = mock.wait_for_remember_job(
+        accepted.job_id, poll_interval_ms=1, timeout_ms=10
+    )
+    waited = mock.remember_and_wait(
+        "sync memory", poll_interval_ms=1, timeout_ms=10
+    )
+    bulk = mock.remember_bulk_and_wait(
+        [RememberBulkItem(text="bulk memory")], opts=opts
+    )
+    assert mock.wait_for_remember_jobs([accepted.job_id], opts=opts).succeeded == 1
+    analyzed = mock.analyze("analyzed memory", occurred_at="2024-01-01T00:00:00Z")
+    analyzed_wait = mock.analyze_and_wait(
+        "analyzed and waited",
+        opts=opts,
+        occurred_at="2024-01-01T00:00:00Z",
+    )
+    recalled = mock.recall("sync")
+
+    assert stored.blob_id == "mock-blob-000001"
+    assert waited.namespace == "sync"
+    assert bulk.succeeded == 1
+    assert analyzed.fact_count == 1
+    assert analyzed_wait.succeeded == 1
+    assert recalled.results[0].text == "sync memory"
+
+
+def test_sync_mock_polling_and_analyze_signatures_match_production():
+    methods = (
+        "wait_for_remember_job",
+        "remember_and_wait",
+        "wait_for_remember_jobs",
+        "remember_bulk_and_wait",
+        "analyze",
+        "analyze_and_wait",
+    )
+
+    def parameter_contract(method):
+        return [
+            (parameter.name, parameter.kind, parameter.default)
+            for parameter in inspect.signature(method).parameters.values()
+        ]
+
+    for method_name in methods:
+        assert parameter_contract(getattr(MemWalMockSync, method_name)) == parameter_contract(
+            getattr(MemWalSync, method_name)
+        )
+
+
+@pytest.mark.asyncio
+async def test_sync_mock_works_inside_an_existing_event_loop():
+    mock = MemWalMockSync.create(namespace="notebook")
+
+    stored = mock.remember_and_wait("called from a running loop")
+    recalled = mock.recall("running loop")
+
+    assert stored.namespace == "notebook"
+    assert recalled.results[0].text == "called from a running loop"