memwal 0.1.0.dev3__tar.gz → 0.1.1.dev0__tar.gz

{memwal-0.1.0.dev3 → memwal-0.1.1.dev0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: memwal
-Version: 0.1.0.dev3
+Version: 0.1.1.dev0
 Summary: Python SDK for MemWal — Privacy-first AI memory with Ed25519 signing
 Project-URL: Homepage, https://memwal.ai
 Project-URL: Documentation, https://docs.memwal.ai
@@ -227,10 +227,10 @@ Create a new async client.
 Every request is signed with Ed25519:
 
 ```
-message = f"{timestamp}.{method}.{path}.{sha256(body)}"
+message = f"{timestamp}.{method}.{path_and_query}.{body_sha256}.{nonce}.{account_id}"
 ```
 
-Headers sent: `x-public-key`, `x-signature`, `x-timestamp`, `x-delegate-key`, `x-account-id`.
+Signed requests send `x-public-key`, `x-signature`, `x-timestamp`, `x-nonce`, and `x-account-id`. Relayer-mode requests also send `x-seal-session`; manual-mode requests omit decrypt credentials.
 
 ## License
 

{memwal-0.1.0.dev3 → memwal-0.1.1.dev0}/README.md

@@ -188,10 +188,10 @@ Create a new async client.
 Every request is signed with Ed25519:
 
 ```
-message = f"{timestamp}.{method}.{path}.{sha256(body)}"
+message = f"{timestamp}.{method}.{path_and_query}.{body_sha256}.{nonce}.{account_id}"
 ```
 
-Headers sent: `x-public-key`, `x-signature`, `x-timestamp`, `x-delegate-key`, `x-account-id`.
+Signed requests send `x-public-key`, `x-signature`, `x-timestamp`, `x-nonce`, and `x-account-id`. Relayer-mode requests also send `x-seal-session`; manual-mode requests omit decrypt credentials.
 
 ## License
 

{memwal-0.1.0.dev3 → memwal-0.1.1.dev0}/memwal/__init__.py

@@ -24,6 +24,7 @@ Quick start::
 
 from .client import (
     MemWal,
+    MemWalCompatibilityError,
     MemWalError,
     MemWalRememberJobFailed,
     MemWalRememberJobNotFound,
@@ -70,6 +71,7 @@ __all__ = [
     "MemWal",
     "MemWalSync",
     "MemWalError",
+    "MemWalCompatibilityError",
     "MemWalRememberJobFailed",
     "MemWalRememberJobNotFound",
     "MemWalRememberJobTimeout",
@@ -110,4 +112,4 @@ __all__ = [
     "RecallManualResult",
 ]
 
-__version__ = "0.1.0.dev3"
+__version__ = "0.1.1.dev0"

{memwal-0.1.0.dev3 → memwal-0.1.1.dev0}/memwal/client.py

@@ -35,6 +35,7 @@ from typing import Any, Dict, List, Optional, Sequence, Tuple, TypeVar
 import httpx
 import nacl.signing
 
+from .compatibility import compatibility_error
 from .types import (
     AnalyzedFact,
     AnalyzeResult,
@@ -134,6 +135,8 @@ class MemWal:
         self._server_config: Optional[Dict[str, str]] = None
         self._session_cache: Optional[Tuple[str, int]] = None
         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
 
     @classmethod
     def create(
@@ -652,7 +655,22 @@ class MemWal:
         if response.status_code != 200:
             raise MemWalError(f"Health check failed: {response.status_code}")
         data = response.json()
-        return HealthResult(status=data["status"], version=data["version"])
+        return HealthResult(
+            status=data["status"],
+            version=data["version"],
+            relayer_version=data.get("relayerVersion"),
+            api_version=data.get("apiVersion"),
+            min_supported_sdk=data.get("minSupportedSdk"),
+            feature_flags=data.get("featureFlags"),
+            deprecations=data.get("deprecations"),
+            build=data.get("build"),
+            mode=data.get("mode"),
+        )
+
+    async def compatibility(self) -> Dict[str, Any]:
+        """Fetch and validate the relayer compatibility contract."""
+
+        return await self._ensure_compatible_relayer()
 
     # ============================================================
     # Manual API (user handles SEAL + embedding + Walrus)
@@ -727,6 +745,42 @@ class MemWal:
     # Internal: Signed HTTP Requests
     # ============================================================
 
+    async def _ensure_compatible_relayer(self) -> Dict[str, Any]:
+        if self._relayer_version_metadata is not None:
+            return self._relayer_version_metadata
+
+        if self._compatibility_lock is None:
+            self._compatibility_lock = asyncio.Lock()
+
+        async with self._compatibility_lock:
+            if self._relayer_version_metadata is not None:
+                return self._relayer_version_metadata
+
+            version_response = await self._http.get(f"{self._server_url}/version")
+            if version_response.status_code == 200:
+                metadata = version_response.json()
+            elif version_response.status_code in (404, 405):
+                health_response = await self._http.get(f"{self._server_url}/health")
+                if health_response.status_code != 200:
+                    raise MemWalError(
+                        "MemWal compatibility check failed: "
+                        f"GET /version returned {version_response.status_code}, "
+                        f"and GET /health returned {health_response.status_code}"
+                    )
+                metadata = health_response.json()
+            else:
+                raise MemWalError(
+                    "MemWal compatibility check failed: "
+                    f"GET /version returned {version_response.status_code}"
+                )
+
+            error = compatibility_error(metadata, self._server_url)
+            if error is not None:
+                raise MemWalCompatibilityError(error)
+
+            self._relayer_version_metadata = metadata
+            return metadata
+
     async def _fetch_server_config(self) -> Dict[str, str]:
         if self._server_config is not None:
             return self._server_config
@@ -842,7 +896,7 @@ class MemWal:
         """Make a signed request to the server.
 
         Signature format:
-            ``{timestamp}.{method}.{path}.{body_sha256}.{nonce}.{account_id}``
+            ``{timestamp}.{method}.{path_and_query}.{body_sha256}.{nonce}.{account_id}``
 
         For ``GET`` requests the canonical body string is the empty string,
         and no HTTP request body is sent. This keeps the signed payload hash
@@ -853,12 +907,15 @@ class MemWal:
             - ``x-public-key``: Ed25519 public key hex
             - ``x-signature``: Ed25519 signature hex
             - ``x-timestamp``: Unix seconds string
+            - ``x-nonce``: UUID v4 replay-protection nonce
             - ``x-seal-session``: Base64-encoded exported session envelope
             - ``x-account-id``: MemWalAccount object ID
             - ``Content-Type``: application/json
         """
         import uuid
 
+        await self._ensure_compatible_relayer()
+
         method_upper = method.upper()
         timestamp = str(int(time.time()))
         body_str = "" if method_upper == "GET" else json.dumps(body, separators=(",", ":"))
@@ -899,6 +956,12 @@ class MemWal:
 
         if response.status_code not in accepted_statuses:
             err_text = response.text
+            if response.status_code == 426:
+                raise MemWalCompatibilityError(
+                    "MemWal relayer rejected this SDK as unsupported "
+                    f"(HTTP 426 Upgrade Required). Relayer response: "
+                    f"{err_text[:300] or 'upgrade required'}"
+                )
             raise _HttpStatusError(
                 status=response.status_code,
                 body=err_text,
@@ -913,6 +976,12 @@ class MemWalError(Exception):
     pass
 
 
+class MemWalCompatibilityError(MemWalError):
+    """Raised when the SDK and relayer API contract are incompatible."""
+
+    pass
+
+
 class _HttpStatusError(MemWalError):
     """Internal: raised when an HTTP response status is not in ``accepted_statuses``.
 
@@ -1135,6 +1204,10 @@ class MemWalSync:
         """Synchronous version of :meth:`MemWal.health`."""
         return self._run(self._inner.health())
 
+    def compatibility(self) -> Dict[str, Any]:
+        """Synchronous version of :meth:`MemWal.compatibility`."""
+        return self._run(self._inner.compatibility())
+
     def remember_manual(self, opts: RememberManualOptions) -> RememberManualResult:
         """Synchronous version of :meth:`MemWal.remember_manual`."""
         return self._run(self._inner.remember_manual(opts))

memwal-0.1.1.dev0/memwal/compatibility.py

@@ -0,0 +1,72 @@
+"""Relayer/API compatibility checks for the Python SDK."""
+
+from __future__ import annotations
+
+import re
+from typing import Any, Dict, Optional, Tuple
+
+MEMWAL_PYTHON_COMPATIBILITY_VERSION = "0.1.0"
+SUPPORTED_RELAYER_API_MAJOR = 1
+
+
+def compatibility_error(metadata: Dict[str, Any], server_url: str) -> Optional[str]:
+    """Return an actionable error string when relayer metadata is unsupported."""
+
+    api_version = metadata.get("apiVersion")
+    relayer_version = metadata.get("relayerVersion")
+    min_supported = metadata.get("minSupportedSdk")
+
+    if not api_version or not relayer_version or not isinstance(min_supported, dict):
+        return (
+            f"MemWal relayer at {server_url} does not expose compatibility metadata. "
+            "Upgrade the relayer to a version that serves GET /version, or use an older SDK."
+        )
+
+    api_major = _semver_major(str(api_version))
+    if api_major is None:
+        return f'MemWal relayer at {server_url} returned invalid apiVersion "{api_version}".'
+
+    if api_major != SUPPORTED_RELAYER_API_MAJOR:
+        return (
+            "This MemWal Python SDK supports relayer API "
+            f"{SUPPORTED_RELAYER_API_MAJOR}.x, but {server_url} reports apiVersion "
+            f"{api_version}. Upgrade or downgrade the SDK/relayer pair."
+        )
+
+    min_python = min_supported.get("python")
+    if not isinstance(min_python, str):
+        return f"MemWal relayer at {server_url} did not report minSupportedSdk.python."
+    if _parse_semver(min_python) is None:
+        return (
+            f'MemWal relayer at {server_url} returned invalid '
+            f'minSupportedSdk.python "{min_python}".'
+        )
+
+    if _compare_semver(MEMWAL_PYTHON_COMPATIBILITY_VERSION, min_python) < 0:
+        return (
+            f"MemWal relayer at {server_url} requires Python SDK >= {min_python}, "
+            f"but this package supports the {MEMWAL_PYTHON_COMPATIBILITY_VERSION} "
+            "compatibility baseline. Upgrade memwal or use an older compatible relayer."
+        )
+
+    return None
+
+
+def _semver_major(version: str) -> Optional[int]:
+    parsed = _parse_semver(version)
+    return parsed[0] if parsed else None
+
+
+def _compare_semver(left: str, right: str) -> int:
+    left_parts = _parse_semver(left)
+    right_parts = _parse_semver(right)
+    if left_parts is None or right_parts is None:
+        raise ValueError(f"invalid semver comparison: {left} vs {right}")
+    return (left_parts > right_parts) - (left_parts < right_parts)
+
+
+def _parse_semver(version: str) -> Optional[Tuple[int, int, int]]:
+    match = re.match(r"^(\d+)\.(\d+)\.(\d+)(?:[-+].*)?$", version.strip())
+    if match is None:
+        return None
+    return int(match.group(1)), int(match.group(2)), int(match.group(3))

{memwal-0.1.0.dev3 → memwal-0.1.1.dev0}/memwal/types.py

@@ -9,7 +9,7 @@ the MemWal Rust server (TEE).
 from __future__ import annotations
 
 from dataclasses import dataclass
-from typing import List, Optional
+from typing import Any, Dict, List, Optional
 
 # ============================================================
 # Config
@@ -136,6 +136,13 @@ class HealthResult:
 
     status: str
     version: str
+    relayer_version: Optional[str] = None
+    api_version: Optional[str] = None
+    min_supported_sdk: Optional[Dict[str, str]] = None
+    feature_flags: Optional[Dict[str, bool]] = None
+    deprecations: Optional[List[Dict[str, Any]]] = None
+    build: Optional[Dict[str, Any]] = None
+    mode: Optional[str] = None
 
 
 @dataclass

{memwal-0.1.0.dev3 → memwal-0.1.1.dev0}/memwal/utils.py

@@ -105,7 +105,7 @@ def build_signature_message(
 
     Current format (matches Rust server ``services/server/src/auth.rs``)::
 
-        "{timestamp}.{method}.{path}.{body_sha256}.{nonce}.{account_id}"
+        "{timestamp}.{method}.{path_and_query}.{body_sha256}.{nonce}.{account_id}"
 
     The trailing ``nonce`` was added in MED-1 (replay protection); the
     ``account_id`` was added in LOW-23 so an intermediary can't swap the

{memwal-0.1.0.dev3 → memwal-0.1.1.dev0}/pyproject.toml

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

{memwal-0.1.0.dev3 → memwal-0.1.1.dev0}/tests/test_client.py

@@ -16,7 +16,7 @@ import nacl.signing
 import pytest
 import respx
 
-from memwal.client import MemWal, MemWalError
+from memwal.client import MemWal, MemWalCompatibilityError, MemWalError
 from memwal.types import RecallManualOptions, RememberManualOptions
 from memwal.utils import build_signature_message, bytes_to_hex, sha256_hex
 
@@ -35,7 +35,35 @@ _TEST_PACKAGE_ID = "0x" + "11" * 32
 _TEST_SUI_RPC = "http://localhost:9001"
 
 
+def _version_payload(
+    api_version: str = "1.0.0",
+    min_python: str = "0.1.0",
+) -> dict[str, Any]:
+    return {
+        "relayerVersion": "0.1.0",
+        "apiVersion": api_version,
+        "minSupportedSdk": {
+            "typescript": "0.0.4",
+            "python": min_python,
+            "mcp": "0.0.1",
+        },
+        "featureFlags": {"runtime.versionEndpoint": True},
+        "deprecations": [],
+        "build": {},
+    }
+
+
+def _mock_version(
+    api_version: str = "1.0.0",
+    min_python: str = "0.1.0",
+) -> None:
+    respx.get(f"{_TEST_SERVER}/version").mock(
+        return_value=httpx.Response(200, json=_version_payload(api_version, min_python))
+    )
+
+
 def mock_seal_session_prereqs() -> None:
+    _mock_version()
     respx.get(f"{_TEST_SERVER}/config").mock(
         return_value=httpx.Response(
             200,
@@ -409,10 +437,58 @@ class TestHealth:
         assert result.status == "ok"
         assert result.version == "0.1.0"
 
+    @respx.mock
+    async def test_compatibility(self, memwal_client: MemWal) -> None:
+        _mock_version()
+
+        metadata = await memwal_client.compatibility()
+
+        assert metadata["apiVersion"] == "1.0.0"
+        assert metadata["minSupportedSdk"]["python"] == "0.1.0"
+
+    @respx.mock
+    async def test_compatibility_rejects_unsupported_relayer(
+        self, memwal_client: MemWal
+    ) -> None:
+        _mock_version(api_version="2.0.0")
+
+        with pytest.raises(MemWalCompatibilityError, match="supports relayer API 1.x"):
+            await memwal_client.compatibility()
+
+    @respx.mock
+    async def test_compatibility_rejects_old_sdk(self, memwal_client: MemWal) -> None:
+        _mock_version(min_python="9.0.0")
+
+        with pytest.raises(MemWalCompatibilityError, match="requires Python SDK >= 9.0.0"):
+            await memwal_client.recall("test")
+
+    @respx.mock
+    async def test_compatibility_rejects_missing_python_min(
+        self, memwal_client: MemWal
+    ) -> None:
+        payload = _version_payload()
+        del payload["minSupportedSdk"]["python"]
+        respx.get(f"{_TEST_SERVER}/version").mock(
+            return_value=httpx.Response(200, json=payload)
+        )
+
+        with pytest.raises(MemWalCompatibilityError, match="minSupportedSdk.python"):
+            await memwal_client.compatibility()
+
+    @respx.mock
+    async def test_compatibility_rejects_invalid_python_min(
+        self, memwal_client: MemWal
+    ) -> None:
+        _mock_version(min_python="latest")
+
+        with pytest.raises(MemWalCompatibilityError, match="invalid minSupportedSdk.python"):
+            await memwal_client.compatibility()
+
 
 class TestManualAPI:
     @respx.mock
     async def test_remember_manual(self, memwal_client: MemWal) -> None:
+        _mock_version()
         route = respx.post(f"{_TEST_SERVER}/api/remember/manual").mock(
             return_value=httpx.Response(
                 200,
@@ -441,6 +517,7 @@ class TestManualAPI:
 
     @respx.mock
     async def test_recall_manual(self, memwal_client: MemWal) -> None:
+        _mock_version()
         route = respx.post(f"{_TEST_SERVER}/api/recall/manual").mock(
             return_value=httpx.Response(
                 200,

{memwal-0.1.0.dev3 → memwal-0.1.1.dev0}/tests/test_integration.py

@@ -47,7 +47,7 @@ import httpx
 import nacl.signing
 import pytest
 
-from memwal.client import MemWal, MemWalError, MemWalSync
+from memwal.client import MemWal, MemWalCompatibilityError, MemWalError, MemWalSync
 from memwal.utils import build_signature_message, bytes_to_hex
 
 # ── Config ───────────────────────────────────────────────────────────────────
@@ -173,6 +173,8 @@ class TestAuthRejection:
         mw = MemWalSync.create(key=unregistered_key, account_id="0x0", server_url=SERVER_URL)
         with pytest.raises(MemWalError) as exc_info:
             mw.remember("hello")
+        if isinstance(exc_info.value, MemWalCompatibilityError):
+            pytest.skip("live relayer does not expose compatibility metadata yet")
         err = str(exc_info.value)
         assert "401" in err or "403" in err, f"Expected 401/403 in: {err}"
 

{memwal-0.1.0.dev3 → memwal-0.1.1.dev0}/tests/test_middleware.py

@@ -51,10 +51,31 @@ _SERVER = "http://localhost:8000"
 
 _RECALL_URL = f"{_SERVER}/api/recall"
 _ANALYZE_URL = f"{_SERVER}/api/analyze"
+_VERSION_URL = f"{_SERVER}/version"
 _SUI_RPC_URL = "http://localhost:9001"
 _PACKAGE_ID = "0x" + "11" * 32
 
 
+def _mock_version() -> None:
+    respx.get(_VERSION_URL).mock(
+        return_value=httpx.Response(
+            200,
+            json={
+                "relayerVersion": "0.1.0",
+                "apiVersion": "1.0.0",
+                "minSupportedSdk": {
+                    "typescript": "0.0.4",
+                    "python": "0.1.0",
+                    "mcp": "0.0.1",
+                },
+                "featureFlags": {"runtime.versionEndpoint": True},
+                "deprecations": [],
+                "build": {},
+            },
+        )
+    )
+
+
 def _mock_seal_session_prereqs() -> None:
     """Register mocks for the SEAL session prerequisites.
 
@@ -66,6 +87,7 @@ def _mock_seal_session_prereqs() -> None:
 
     Mirrors the helper of the same name in ``test_client.py``.
     """
+    _mock_version()
     respx.get(f"{_SERVER}/config").mock(
         return_value=httpx.Response(
             200,