memwal 0.1.0.dev0__py3-none-any.whl

memwal/types.py

@@ -0,0 +1,340 @@
+"""
+memwal — Core Types
+
+Dataclasses for all API request options and response types.
+Ed25519 delegate key based SDK that communicates with
+the MemWal Rust server (TEE).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import List, Optional
+
+# ============================================================
+# Config
+# ============================================================
+
+
+@dataclass
+class MemWalConfig:
+    """Configuration for creating a MemWal client.
+
+    Attributes:
+        key: Ed25519 private key (hex string). This is the delegate key from app.memwal.com.
+        account_id: MemWalAccount object ID on Sui.
+        server_url: Server URL (default: https://relayer.memwal.ai).
+        namespace: Default namespace for memory isolation (default: "default").
+    """
+
+    key: str
+    account_id: str
+    server_url: str = "https://relayer.memwal.ai"
+    namespace: str = "default"
+
+
+# ============================================================
+# API Response Types
+# ============================================================
+
+
+@dataclass
+class RememberResult:
+    """Result from remember()."""
+
+    id: str
+    blob_id: str
+    owner: str
+    namespace: str
+
+
+@dataclass
+class RecallMemory:
+    """A single recalled memory."""
+
+    blob_id: str
+    text: str
+    distance: float
+
+
+@dataclass
+class RecallResult:
+    """Result from recall()."""
+
+    results: List[RecallMemory]
+    total: int
+
+
+@dataclass
+class AnalyzedFact:
+    """A single extracted fact."""
+
+    text: str
+    id: str
+    blob_id: str
+
+
+@dataclass
+class AnalyzeResult:
+    """Result from analyze().
+
+    Per PR #121: each extracted fact is enqueued as a background remember
+    job. ``job_ids`` aligns with ``facts`` positionally; poll those
+    job_ids (e.g. via :meth:`MemWal.wait_for_remember_jobs`) to know when
+    the corresponding memory is fully persisted on Walrus.
+    """
+
+    facts: List[AnalyzedFact]
+    fact_count: int
+    job_ids: List[str]
+    status: str
+    owner: str
+
+    @property
+    def total(self) -> int:
+        """Backward-compat alias for ``fact_count`` (v0.1 callers)."""
+        return self.fact_count
+
+
+@dataclass
+class HealthResult:
+    """Server health response."""
+
+    status: str
+    version: str
+
+
+@dataclass
+class RestoreResult:
+    """Result from restore()."""
+
+    restored: int
+    skipped: int
+    total: int
+    namespace: str
+    owner: str
+
+
+@dataclass
+class AskMemory:
+    """A memory used to answer a question."""
+
+    blob_id: str
+    text: str
+    distance: float
+
+
+@dataclass
+class AskResult:
+    """Result from ask()."""
+
+    answer: str
+    memories_used: int
+    memories: List[AskMemory]
+
+
+# ============================================================
+# Manual Flow Types
+# ============================================================
+
+
+@dataclass
+class RememberManualOptions:
+    """Options for remember_manual().
+
+    Attributes:
+        blob_id: Walrus blob ID (user already uploaded encrypted data).
+        vector: Embedding vector (user already generated).
+        namespace: Namespace (default: config namespace or "default").
+    """
+
+    blob_id: str
+    vector: List[float]
+    namespace: Optional[str] = None
+
+
+@dataclass
+class RememberManualResult:
+    """Result from remember_manual()."""
+
+    id: str
+    blob_id: str
+    owner: str
+    namespace: str
+
+
+@dataclass
+class RecallManualOptions:
+    """Options for recall_manual().
+
+    Attributes:
+        vector: Pre-computed query embedding vector.
+        limit: Max number of results (default: 10).
+        namespace: Namespace (default: config namespace or "default").
+    """
+
+    vector: List[float]
+    limit: int = 10
+    namespace: Optional[str] = None
+
+
+@dataclass
+class RecallManualHit:
+    """A single search hit -- raw blob_id + distance (no decrypted text)."""
+
+    blob_id: str
+    distance: float
+
+
+@dataclass
+class RecallManualResult:
+    """Result from recall_manual()."""
+
+    results: List[RecallManualHit]
+    total: int
+
+
+# ============================================================
+# Async remember (PR #121: ENG-1406 / ENG-1408)
+# ============================================================
+
+
+@dataclass
+class RememberAcceptedResult:
+    """Result from remember() / remember_async() — server returns 202 immediately.
+
+    The actual upload + on-chain commit happen in a background worker.
+    Poll ``GET /api/remember/{job_id}`` (via wait_for_remember_job) to follow
+    progress until status reaches "done" or "failed".
+    """
+
+    job_id: str
+    status: str
+
+
+@dataclass
+class RememberJobStatus:
+    """One snapshot of an async remember job, returned by the status endpoint.
+
+    ``status`` transitions: pending → running → uploaded → done, or → failed.
+    ``not_found`` is returned when the job_id is unknown or not the caller's.
+    """
+
+    job_id: str
+    status: str
+    owner: Optional[str] = None
+    namespace: Optional[str] = None
+    blob_id: Optional[str] = None
+    error: Optional[str] = None
+
+
+# ============================================================
+# Bulk remember (ENG-1408)
+# ============================================================
+
+
+@dataclass
+class RememberBulkItem:
+    """One item in a bulk remember request.
+
+    ``namespace`` overrides the client default for this item only.
+    """
+
+    text: str
+    namespace: Optional[str] = None
+
+
+@dataclass
+class RememberBulkAcceptedResult:
+    """Result from remember_bulk() / remember_bulk_async() — 202 with job_ids.
+
+    ``job_ids`` aligns positionally with the input ``items`` list.
+    """
+
+    job_ids: List[str]
+    total: int
+    status: str
+
+
+@dataclass
+class RememberBulkStatusItem:
+    """Per-item status returned by the bulk status endpoint."""
+
+    job_id: str
+    status: str
+    blob_id: Optional[str] = None
+    error: Optional[str] = None
+
+
+@dataclass
+class RememberBulkStatusResult:
+    """Result from get_remember_bulk_status()."""
+
+    results: List[RememberBulkStatusItem]
+
+
+@dataclass
+class RememberBulkOptions:
+    """Polling options for remember_bulk_and_wait() / wait_for_remember_jobs().
+
+    ``poll_interval_ms`` is the base poll cadence (default 1500ms).
+    ``timeout_ms`` is the total wait budget before raising TimeoutError
+    (default 120_000ms).
+    """
+
+    poll_interval_ms: int = 1500
+    timeout_ms: int = 120_000
+
+
+@dataclass
+class RememberBulkItemResult:
+    """One settled item in a bulk-and-wait result."""
+
+    id: str
+    blob_id: str
+    status: str  # "done" | "failed" | "timeout"
+    error: Optional[str] = None
+
+
+@dataclass
+class RememberBulkResult:
+    """Aggregate result from remember_bulk_and_wait() / wait_for_remember_jobs().
+
+    ``succeeded + failed + timed_out == total``. ``results`` preserves input order.
+    """
+
+    results: List[RememberBulkItemResult]
+    total: int
+    succeeded: int
+    failed: int
+    timed_out: int
+
+
+# ============================================================
+# Embed + analyze
+# ============================================================
+
+
+@dataclass
+class EmbedResult:
+    """Result from embed() — raw embedding vector for a piece of text."""
+
+    vector: List[float]
+
+
+@dataclass
+class AnalyzeWaitResult:
+    """Result from analyze_and_wait().
+
+    Combines the analyze fact-extraction output with the bulk-style settled
+    results for each enqueued background remember job. Mirrors the TS SDK's
+    ``AnalyzeWaitResult extends RememberBulkResult``.
+    """
+
+    results: List[RememberBulkItemResult]
+    total: int
+    succeeded: int
+    failed: int
+    timed_out: int
+    facts: List[AnalyzedFact]
+    owner: str

memwal/utils.py

@@ -0,0 +1,172 @@
+"""
+memwal — Shared Utilities
+
+Crypto and encoding helpers for Ed25519 signing and SHA-256 hashing.
+Uses PyNaCl (nacl.signing) as the primary Ed25519 implementation.
+"""
+
+from __future__ import annotations
+
+import hashlib
+from typing import Tuple
+
+import nacl.signing
+
+
+def hex_to_bytes(hex_str: str) -> bytes:
+    """Convert a hex string to bytes.
+
+    Handles optional ``0x`` prefix.
+
+    Args:
+        hex_str: Hex-encoded string, optionally prefixed with ``0x``.
+
+    Returns:
+        Raw bytes.
+    """
+    clean = hex_str[2:] if hex_str.startswith("0x") else hex_str
+    return bytes.fromhex(clean)
+
+
+def bytes_to_hex(b: bytes) -> str:
+    """Convert bytes to a lowercase hex string (no ``0x`` prefix).
+
+    Args:
+        b: Raw bytes.
+
+    Returns:
+        Hex-encoded string.
+    """
+    return b.hex()
+
+
+def sha256_hex(data: str) -> str:
+    """Compute the SHA-256 hex digest of a UTF-8 string.
+
+    Args:
+        data: Input string.
+
+    Returns:
+        Lowercase hex SHA-256 digest.
+    """
+    return hashlib.sha256(data.encode("utf-8")).hexdigest()
+
+
+def build_signing_key(private_key_hex: str) -> nacl.signing.SigningKey:
+    """Build a PyNaCl ``SigningKey`` from an Ed25519 private key hex string.
+
+    Args:
+        private_key_hex: 32-byte Ed25519 seed as hex (64 hex chars), optionally ``0x``-prefixed.
+
+    Returns:
+        A ``nacl.signing.SigningKey`` instance.
+
+    Raises:
+        ValueError: If the decoded seed is not exactly 32 bytes.
+    """
+    seed_bytes = hex_to_bytes(private_key_hex)
+    if len(seed_bytes) != 32:
+        raise ValueError(
+            f"Ed25519 seed must be exactly 32 bytes, got {len(seed_bytes)}"
+        )
+    return nacl.signing.SigningKey(seed_bytes)
+
+
+def sign_message(message: str, signing_key: nacl.signing.SigningKey) -> Tuple[str, str]:
+    """Sign a UTF-8 message with an Ed25519 signing key.
+
+    Args:
+        message: The message string to sign.
+        signing_key: A PyNaCl ``SigningKey``.
+
+    Returns:
+        A tuple of ``(signature_hex, public_key_hex)``.
+    """
+    signed = signing_key.sign(message.encode("utf-8"))
+    signature_bytes: bytes = signed.signature
+    public_key_bytes: bytes = bytes(signing_key.verify_key)
+    return bytes_to_hex(signature_bytes), bytes_to_hex(public_key_bytes)
+
+
+def build_signature_message(
+    timestamp: str,
+    method: str,
+    path: str,
+    body_sha256: str,
+    nonce: str = "",
+    account_id: str = "",
+) -> str:
+    """Build the canonical signing message.
+
+    Current format (matches Rust server ``services/server/src/auth.rs``)::
+
+        "{timestamp}.{method}.{path}.{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
+    account hint without invalidating the signature. Both fields are
+    REQUIRED — passing empty strings will fail signature verification on
+    the server.
+
+    Args:
+        timestamp: Unix seconds as string.
+        method: Uppercase HTTP method (e.g. ``"POST"``).
+        path: URL path with query (e.g. ``"/api/remember"``).
+        body_sha256: SHA-256 hex digest of the JSON body string.
+        nonce: UUID v4 sent as the ``x-nonce`` header (required).
+        account_id: MemWalAccount object ID sent as ``x-account-id``
+            (required; empty string here will mismatch on server).
+    """
+    return f"{timestamp}.{method}.{path}.{body_sha256}.{nonce}.{account_id}"
+
+
+def delegate_key_to_sui_address(private_key_hex: str) -> str:
+    """Derive the Sui address from an Ed25519 delegate key.
+
+    Sui Ed25519 address derivation:
+        blake2b-256(0x00 || public_key)[0:32]
+
+    where ``0x00`` is the Ed25519 scheme flag byte.
+
+    This matches the TypeScript SDK's ``delegateKeyToSuiAddress()`` exactly,
+    and is the same derivation used by the Sui wallet.
+
+    Args:
+        private_key_hex: Ed25519 private key as hex (64 hex chars / 32 bytes),
+            optionally ``0x``-prefixed.
+
+    Returns:
+        Sui address as a ``0x``-prefixed lowercase hex string (32 bytes / 64 hex chars).
+
+    Example::
+
+        address = delegate_key_to_sui_address("944aa24c09d8b6d6...")
+        # "0x1a2b3c..."
+    """
+    signing_key = build_signing_key(private_key_hex)
+    public_key_bytes = bytes(signing_key.verify_key)  # 32 bytes
+
+    # Sui scheme flag for Ed25519 = 0x00, then the 32-byte public key
+    scheme_input = bytes([0x00]) + public_key_bytes  # 33 bytes total
+
+    # blake2b with 32-byte (256-bit) digest
+    address_bytes = hashlib.blake2b(scheme_input, digest_size=32).digest()
+    return "0x" + bytes_to_hex(address_bytes)
+
+
+def delegate_key_to_public_key(private_key_hex: str) -> bytes:
+    """Get the Ed25519 public key bytes from a delegate key.
+
+    Args:
+        private_key_hex: Ed25519 private key as hex, optionally ``0x``-prefixed.
+
+    Returns:
+        32-byte Ed25519 public key.
+
+    Example::
+
+        pub = delegate_key_to_public_key("944aa24c...")
+        print(pub.hex())  # "d5b76c57..."
+    """
+    signing_key = build_signing_key(private_key_hex)
+    return bytes(signing_key.verify_key)

memwal-0.1.0.dev0.dist-info/METADATA

@@ -0,0 +1,211 @@
+Metadata-Version: 2.4
+Name: memwal
+Version: 0.1.0.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
+Project-URL: Repository, https://github.com/MystenLabs/MemWal
+Author: MemWal Team
+License-Expression: MIT
+Keywords: ai,ed25519,memory,memwal,privacy,sui,walrus
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pynacl>=1.5.0
+Provides-Extra: all
+Requires-Dist: langchain-core>=0.2.0; extra == 'all'
+Requires-Dist: openai>=1.0.0; extra == 'all'
+Provides-Extra: dev
+Requires-Dist: langchain-core>=0.2.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: respx>=0.21.0; extra == 'dev'
+Requires-Dist: ruff>=0.4.0; extra == 'dev'
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=0.2.0; extra == 'langchain'
+Provides-Extra: openai
+Requires-Dist: openai>=1.0.0; extra == 'openai'
+Description-Content-Type: text/markdown
+
+# memwal
+
+Python SDK for [MemWal](https://memwal.ai) — Privacy-first AI memory with Ed25519 signing.
+
+All data processing (encryption, embedding, Walrus storage) happens server-side in a TEE. The SDK signs requests with your Ed25519 delegate key and sends text over HTTPS.
+
+## Installation
+
+```bash
+pip install memwal
+```
+
+With optional integrations:
+
+```bash
+pip install memwal[langchain]   # LangChain support
+pip install memwal[openai]      # OpenAI SDK support
+pip install memwal[all]         # Everything
+```
+
+## Quick Start
+
+Set your environment variables first:
+
+```bash
+export MEMWAL_KEY="your-ed25519-delegate-key-hex"
+export MEMWAL_ACCOUNT_ID="0x-your-memwal-account-id"
+export MEMWAL_SERVER_URL="https://relayer.memwal.ai"
+```
+
+### Async (recommended)
+
+```python
+import asyncio
+import os
+from memwal import MemWal
+
+async def main():
+    memwal = MemWal.create(
+        key=os.environ["MEMWAL_KEY"],
+        account_id=os.environ["MEMWAL_ACCOUNT_ID"],
+        server_url=os.environ.get("MEMWAL_SERVER_URL", "https://relayer.memwal.ai"),
+    )
+
+    # Store a memory
+    result = await memwal.remember("I'm allergic to peanuts")
+    print(result.blob_id)
+
+    # Recall memories
+    matches = await memwal.recall("food allergies")
+    for memory in matches.results:
+        print(f"{memory.text} (relevance: {1 - memory.distance:.2f})")
+
+    # Analyze conversation for facts
+    analysis = await memwal.analyze("I love coffee and live in Tokyo")
+    for fact in analysis.facts:
+        print(fact.text)
+
+    await memwal.close()
+
+asyncio.run(main())
+```
+
+### Sync
+
+```python
+import os
+from memwal import MemWalSync
+
+client = MemWalSync.create(
+    key=os.environ["MEMWAL_KEY"],
+    account_id=os.environ["MEMWAL_ACCOUNT_ID"],
+    server_url=os.environ.get("MEMWAL_SERVER_URL", "https://relayer.memwal.ai"),
+)
+
+result = client.remember("I'm allergic to peanuts")
+matches = client.recall("food allergies")
+client.close()
+```
+
+### Context Manager
+
+```python
+import os
+from memwal import MemWal
+
+async with MemWal.create(
+    key=os.environ["MEMWAL_KEY"],
+    account_id=os.environ["MEMWAL_ACCOUNT_ID"],
+) as memwal:
+    await memwal.remember("I prefer dark mode")
+```
+
+## AI Middleware
+
+### LangChain
+
+```python
+import os
+from langchain_openai import ChatOpenAI
+from langchain_core.messages import HumanMessage
+from memwal import with_memwal_langchain
+
+llm = ChatOpenAI(model="gpt-4o")
+smart_llm = with_memwal_langchain(
+    llm,
+    key=os.environ["MEMWAL_KEY"],
+    account_id=os.environ["MEMWAL_ACCOUNT_ID"],
+    server_url=os.environ.get("MEMWAL_SERVER_URL", "https://relayer.memwal.ai"),
+    max_memories=5,
+    min_relevance=0.3,
+)
+
+# Memories are automatically recalled and injected
+response = await smart_llm.ainvoke([HumanMessage("What are my food allergies?")])
+```
+
+### OpenAI SDK
+
+```python
+import os
+from openai import AsyncOpenAI
+from memwal import with_memwal_openai
+
+client = AsyncOpenAI()
+smart_client = with_memwal_openai(
+    client,
+    key=os.environ["MEMWAL_KEY"],
+    account_id=os.environ["MEMWAL_ACCOUNT_ID"],
+    server_url=os.environ.get("MEMWAL_SERVER_URL", "https://relayer.memwal.ai"),
+)
+
+# Memories are automatically recalled and injected
+response = await smart_client.chat.completions.create(
+    model="gpt-4o",
+    messages=[{"role": "user", "content": "What are my food allergies?"}],
+)
+```
+
+## API Reference
+
+### `MemWal.create(key, account_id, server_url?, namespace?)`
+
+Create a new async client.
+
+### Methods
+
+| Method | Description |
+|--------|-------------|
+| `await remember(text, namespace?)` | Store a memory |
+| `await recall(query, limit?, namespace?)` | Search memories |
+| `await analyze(text, namespace?)` | Extract and store facts |
+| `await ask(question, limit?, namespace?)` | Ask a question answered using memories |
+| `await restore(namespace, limit?)` | Restore a namespace |
+| `await health()` | Check server health |
+| `await remember_manual(opts)` | Store with pre-computed vector |
+| `await recall_manual(opts)` | Search with pre-computed vector |
+| `await get_public_key_hex()` | Get Ed25519 public key |
+
+## Authentication
+
+Every request is signed with Ed25519:
+
+```
+message = f"{timestamp}.{method}.{path}.{sha256(body)}.{nonce}.{account_id}"
+```
+
+Headers sent: `x-public-key`, `x-signature`, `x-timestamp`, `x-nonce`, `x-delegate-key`, `x-account-id`.
+
+## License
+
+MIT