memcode-sdk 2.3.1__py3-none-any.whl

memcode_sdk/__init__.py

@@ -0,0 +1,104 @@
+"""
+Memcode Python SDK — client library for the Memcode long-term memory API.
+
+Quickstart::
+
+    from memcode_sdk import MemcodeClient
+
+    client = MemcodeClient(api_key="sk-...")
+    result = client.ingest(user_query="I love Python", user_id="u1")
+    answer = client.retrieve(query="hobbies", user_id="u1")
+    client.close()
+
+Async::
+
+    from memcode_sdk import AsyncMemcodeClient
+
+    async with AsyncMemcodeClient(api_key="sk-...") as client:
+        result = await client.ingest(user_query="I love Python", user_id="u1")
+"""
+
+from .client import MemcodeClient
+from .async_client import AsyncMemcodeClient
+from .v2_client import MemoryV2Client, MemcodeV2Client
+from .async_v2_client import AsyncMemoryV2Client, AsyncMemcodeV2Client
+from .types import (
+    DomainResult,
+    HealthStatus,
+    HybridSearchResult,
+    IngestResult,
+    OperationDetail,
+    PersonalV2IngestResult,
+    PersonalV2IngestStatus,
+    PersonalV2RetrieveResult,
+    RetrieveResult,
+    SearchResult,
+    SourceRecord,
+    WeaverSummary,
+)
+from .errors import (
+    MemcodeSDKError,
+    AuthenticationError,
+    ConnectionError,
+    NotReadyError,
+    RateLimitError,
+    ServerError,
+    ValidationError,
+)
+from .v2_types import (
+    V2IngestResult,
+    V2IngestStatus,
+    V2MemorySource,
+    V2OperationCounts,
+    V2OriginalStorageStatus,
+    V2RetrieveResult,
+    V2SearchResult,
+    V2SourceLineage,
+    V2SourceProvenance,
+    V2SourceSpace,
+)
+
+__author__ = "Memcode Team"
+__version__ = "2.3.1"
+__license__ = "Apache-2.0"
+
+__all__ = [
+    # Clients
+    "MemcodeClient",
+    "AsyncMemcodeClient",
+    "MemcodeV2Client",
+    "MemoryV2Client",
+    "AsyncMemcodeV2Client",
+    "AsyncMemoryV2Client",
+    # Result types
+    "DomainResult",
+    "HealthStatus",
+    "HybridSearchResult",
+    "IngestResult",
+    "OperationDetail",
+    "PersonalV2IngestResult",
+    "PersonalV2IngestStatus",
+    "PersonalV2RetrieveResult",
+    "RetrieveResult",
+    "SearchResult",
+    "SourceRecord",
+    "WeaverSummary",
+    "V2IngestResult",
+    "V2IngestStatus",
+    "V2MemorySource",
+    "V2OperationCounts",
+    "V2OriginalStorageStatus",
+    "V2RetrieveResult",
+    "V2SearchResult",
+    "V2SourceLineage",
+    "V2SourceProvenance",
+    "V2SourceSpace",
+    # Errors
+    "MemcodeSDKError",
+    "AuthenticationError",
+    "ConnectionError",
+    "NotReadyError",
+    "RateLimitError",
+    "ServerError",
+    "ValidationError",
+]

memcode_sdk/_http.py

@@ -0,0 +1,162 @@
+"""
+Internal HTTP transport layer for the Memcode SDK.
+
+Handles request construction, response unpacking, and error mapping
+for both sync (httpx.Client) and async (httpx.AsyncClient) transports.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, Dict, Optional
+
+import httpx
+
+from .errors import (
+    AuthenticationError,
+    ConnectionError,
+    NotReadyError,
+    RateLimitError,
+    ServerError,
+    ValidationError,
+    MemcodeSDKError,
+)
+from .types import APIEnvelope, Status
+
+logger = logging.getLogger("memcode.sdk.http")
+
+DEFAULT_TIMEOUT = 120
+
+
+def _build_headers(api_key: Optional[str]) -> Dict[str, str]:
+    headers: Dict[str, str] = {"Content-Type": "application/json"}
+    if api_key:
+        headers["Authorization"] = f"Bearer {api_key}"
+    return headers
+
+
+def _map_error(status_code: int, body: Dict[str, Any]) -> MemcodeSDKError:
+    """Convert an API error response into a typed SDK exception."""
+    raw_message = body.get("error") or body.get("detail") or body.get("message")
+    if isinstance(raw_message, dict):
+        raw_message = raw_message.get("message") or raw_message.get("code")
+    if isinstance(raw_message, list):
+        raw_message = "; ".join(
+            str(item.get("msg", item)) if isinstance(item, dict) else str(item)
+            for item in raw_message
+        )
+    msg = str(raw_message or f"HTTP {status_code}")
+    request_id = body.get("request_id")
+
+    if status_code == 401:
+        return AuthenticationError(msg, status_code=status_code, request_id=request_id)
+    if status_code == 403:
+        return AuthenticationError(msg, status_code=status_code, request_id=request_id)
+    if status_code in {400, 422}:
+        return ValidationError(msg, status_code=status_code, request_id=request_id, details=body)
+    if status_code == 429:
+        return RateLimitError(
+            msg, status_code=status_code, request_id=request_id,
+            retry_after=int(body.get("retry_after", 60)),
+        )
+    if status_code == 503:
+        return NotReadyError(msg, status_code=status_code, request_id=request_id)
+    if status_code >= 500:
+        return ServerError(msg, status_code=status_code, request_id=request_id)
+
+    return MemcodeSDKError(msg, status_code=status_code, request_id=request_id)
+
+
+def _unpack(response: httpx.Response) -> APIEnvelope:
+    """Parse and validate a raw HTTP response into an ``APIEnvelope``."""
+    try:
+        body = response.json()
+    except Exception:
+        if response.status_code >= 400:
+            raise _map_error(response.status_code, {"error": response.text[:500]})
+        raise MemcodeSDKError(f"Unparseable response (HTTP {response.status_code})")
+
+    if response.status_code >= 400:
+        raise _map_error(response.status_code, body)
+
+    status_raw = body.get("status", "ok")
+    status = Status.ERROR if status_raw == "error" else Status.OK
+
+    if status == Status.ERROR:
+        raise _map_error(response.status_code or 500, body)
+
+    return APIEnvelope(
+        status=status,
+        data=body.get("data"),
+        error=body.get("error"),
+        request_id=body.get("request_id"),
+        elapsed_ms=body.get("elapsed_ms"),
+    )
+
+
+# ═══════════════════════════════════════════════════════════════════════════
+# Sync transport
+# ═══════════════════════════════════════════════════════════════════════════
+
+class SyncTransport:
+    """Thin wrapper around ``httpx.Client``."""
+
+    def __init__(self, base_url: str, api_key: Optional[str], timeout: int) -> None:
+        self._client = httpx.Client(
+            base_url=base_url.rstrip("/"),
+            headers=_build_headers(api_key),
+            timeout=timeout,
+        )
+
+    def get(self, path: str, **kwargs) -> APIEnvelope:
+        try:
+            return _unpack(self._client.get(path, **kwargs))
+        except httpx.ConnectError as exc:
+            raise ConnectionError(f"Connection failed: {exc}") from exc
+        except httpx.TimeoutException as exc:
+            raise ConnectionError(f"Request timed out: {exc}") from exc
+
+    def post(self, path: str, *, json: Any = None, **kwargs) -> APIEnvelope:
+        try:
+            return _unpack(self._client.post(path, json=json, **kwargs))
+        except httpx.ConnectError as exc:
+            raise ConnectionError(f"Connection failed: {exc}") from exc
+        except httpx.TimeoutException as exc:
+            raise ConnectionError(f"Request timed out: {exc}") from exc
+
+    def close(self) -> None:
+        self._client.close()
+
+
+# ═══════════════════════════════════════════════════════════════════════════
+# Async transport
+# ═══════════════════════════════════════════════════════════════════════════
+
+class AsyncTransport:
+    """Thin wrapper around ``httpx.AsyncClient``."""
+
+    def __init__(self, base_url: str, api_key: Optional[str], timeout: int) -> None:
+        self._client = httpx.AsyncClient(
+            base_url=base_url.rstrip("/"),
+            headers=_build_headers(api_key),
+            timeout=timeout,
+        )
+
+    async def get(self, path: str, **kwargs) -> APIEnvelope:
+        try:
+            return _unpack(await self._client.get(path, **kwargs))
+        except httpx.ConnectError as exc:
+            raise ConnectionError(f"Connection failed: {exc}") from exc
+        except httpx.TimeoutException as exc:
+            raise ConnectionError(f"Request timed out: {exc}") from exc
+
+    async def post(self, path: str, *, json: Any = None, **kwargs) -> APIEnvelope:
+        try:
+            return _unpack(await self._client.post(path, json=json, **kwargs))
+        except httpx.ConnectError as exc:
+            raise ConnectionError(f"Connection failed: {exc}") from exc
+        except httpx.TimeoutException as exc:
+            raise ConnectionError(f"Request timed out: {exc}") from exc
+
+    async def close(self) -> None:
+        await self._client.aclose()

memcode_sdk/async_client.py

@@ -0,0 +1,277 @@
+"""
+Asynchronous Memcode client.
+
+Usage::
+
+    from memcode_sdk import AsyncMemcodeClient
+
+    async with AsyncMemcodeClient(api_url="http://localhost:8000") as client:
+        health = await client.ping()
+        result = await client.ingest(
+            user_query="I love hiking in the Rockies.",
+            user_id="user_42",
+        )
+        answer = await client.retrieve(query="hobbies", user_id="user_42")
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Any, Dict, List, Optional
+
+from ._http import DEFAULT_TIMEOUT, AsyncTransport
+from .client import (
+    _append_legacy_user_id,
+    _optional_idempotency_headers,
+    _personal_v2_search_payload,
+    _parse_personal_v2_ingest,
+    _parse_personal_v2_retrieve,
+    _parse_personal_v2_status,
+    _parse_hybrid_search,
+    _parse_ingest,
+    _parse_retrieve,
+    _parse_search,
+    _personal_v2_ingest_payload,
+    _required_personal,
+)
+from .types import (
+    HealthStatus,
+    HybridSearchResult,
+    IngestResult,
+    PersonalV2IngestResult,
+    PersonalV2IngestStatus,
+    PersonalV2RetrieveResult,
+    RetrieveResult,
+    SearchResult,
+)
+
+
+class AsyncMemcodeClient:
+    """Asynchronous client for compatible v1 and advanced personal v2 APIs."""
+
+    def __init__(
+        self,
+        api_url: Optional[str] = None,
+        api_key: Optional[str] = None,
+        timeout: int = DEFAULT_TIMEOUT,
+    ) -> None:
+        self._api_url = (
+            api_url
+            or os.getenv("MEMCODE_API_URL")
+            or "http://localhost:8000"
+        )
+        self._api_key = api_key or os.getenv("MEMCODE_API_KEY") or ""
+        self._transport = AsyncTransport(self._api_url, self._api_key, timeout)
+
+    # ── Health ─────────────────────────────────────────────────────────
+
+    async def ping(self) -> HealthStatus:
+        try:
+            env = await self._transport.get("/health")
+            d = env.data or {}
+        except Exception:
+            return HealthStatus(status="unreachable", pipelines_ready=False)
+
+        return HealthStatus(
+            status=d.get("status", "unknown"),
+            pipelines_ready=d.get("pipelines_ready", False),
+            version=d.get("version", ""),
+            uptime_seconds=d.get("uptime_seconds"),
+            error=d.get("error"),
+        )
+
+    async def is_ready(self) -> bool:
+        return (await self.ping()).pipelines_ready
+
+    # ── Ingest ─────────────────────────────────────────────────────────
+
+    async def ingest(
+        self,
+        user_query: str,
+        user_id: str,
+        agent_response: str = "",
+        session_datetime: str = "",
+        image_url: str = "",
+    ) -> IngestResult:
+        """Ingest a conversation turn into long-term memory.
+
+        Args:
+            user_query:       The user's message to memorize.
+            user_id:          Unique user identifier.
+            agent_response:   Assistant reply (improves summary extraction).
+            session_datetime: ISO-8601 datetime for temporal extraction.
+            image_url:        URL or base64 data-URI of an attached image.
+        """
+        payload: Dict[str, Any] = {
+            "user_query": user_query,
+            "user_id": user_id,
+        }
+        if agent_response:
+            payload["agent_response"] = agent_response
+        if session_datetime:
+            payload["session_datetime"] = session_datetime
+        if image_url:
+            payload["image_url"] = image_url
+
+        env = await self._transport.post("/v1/memory/ingest", json=payload)
+        return _parse_ingest(env.data or {}, env.request_id, env.elapsed_ms)
+
+    async def ingest_v2(
+        self,
+        user_query: str,
+        user_id: Optional[str] = None,
+        agent_response: str = "",
+        session_datetime: str = "",
+        image_url: str = "",
+        effort_level: str = "low",
+        forget: bool = False,
+        idempotency_key: str = "",
+    ) -> PersonalV2IngestResult:
+        payload = _personal_v2_ingest_payload(
+            user_query,
+            user_id,
+            agent_response,
+            session_datetime,
+            image_url,
+            effort_level,
+            forget,
+        )
+        env = await self._transport.post(
+            "/v2/memory/ingest",
+            json=payload,
+            headers=_optional_idempotency_headers(idempotency_key),
+        )
+        return _parse_personal_v2_ingest(env.data or {}, env.request_id, env.elapsed_ms)
+
+    async def get_ingest_status_v2(self, job_id: str) -> PersonalV2IngestStatus:
+        from urllib.parse import quote
+
+        normalized = _required_personal("job_id", job_id)
+        env = await self._transport.get(
+            f"/v2/memory/ingest/{quote(normalized, safe='')}/status"
+        )
+        return _parse_personal_v2_status(env.data or {}, env.request_id, env.elapsed_ms)
+
+    # ── Retrieve ───────────────────────────────────────────────────────
+
+    async def retrieve(
+        self,
+        query: str,
+        user_id: str,
+        top_k: int = 5,
+    ) -> RetrieveResult:
+        """Answer a question using stored memories.
+
+        Args:
+            query:   The question to answer.
+            user_id: User identifier.
+            top_k:   Number of source records to consider.
+        """
+        env = await self._transport.post("/v1/memory/retrieve", json={
+            "query": query, "user_id": user_id, "top_k": top_k,
+        })
+        return _parse_retrieve(env.data or {}, env.request_id, env.elapsed_ms)
+
+    async def retrieve_v2(
+        self,
+        query: str,
+        user_id: Optional[str] = None,
+        top_k: int = 5,
+    ) -> PersonalV2RetrieveResult:
+        if isinstance(top_k, bool) or not isinstance(top_k, int) or not 1 <= top_k <= 50:
+            raise ValueError("MemcodeClient: top_k must be an integer between 1 and 50")
+        payload: Dict[str, Any] = {
+            "query": _required_personal("query", query),
+            "top_k": top_k,
+        }
+        _append_legacy_user_id(payload, user_id)
+        env = await self._transport.post("/v2/memory/retrieve", json=payload)
+        return _parse_personal_v2_retrieve(env.data or {}, env.request_id, env.elapsed_ms)
+
+    # ── Search ─────────────────────────────────────────────────────────
+
+    async def search(
+        self,
+        query: str,
+        user_id: str,
+        domains: Optional[List[str]] = None,
+        top_k: int = 10,
+    ) -> SearchResult:
+        """Raw semantic search across memory domains.
+
+        Args:
+            query:   Natural-language search query.
+            user_id: User identifier.
+            domains: Subset of ``["profile", "temporal", "summary"]``.
+            top_k:   Max results per domain.
+        """
+        payload: Dict[str, Any] = {
+            "query": query, "user_id": user_id, "top_k": top_k,
+        }
+        if domains is not None:
+            payload["domains"] = domains
+
+        env = await self._transport.post("/v1/memory/search", json=payload)
+        return _parse_search(env.data or {}, env.request_id, env.elapsed_ms)
+
+    async def hybrid_search(
+        self,
+        query: str,
+        user_id: Optional[str] = None,
+        domains: Optional[List[str]] = None,
+        memory_top_k: Optional[int] = None,
+        original_top_k: Optional[int] = None,
+        include_original_chunks: bool = True,
+        search_mode: str = "default",
+        top_k: Optional[int] = None,
+        minimum_score: float = 0.0,
+    ) -> HybridSearchResult:
+        """Deprecated alias for :meth:`search_v2`."""
+        return await self.search_v2(
+            query=query,
+            user_id=user_id,
+            domains=domains,
+            memory_top_k=memory_top_k,
+            original_top_k=original_top_k,
+            include_original_chunks=include_original_chunks,
+            search_mode=search_mode,
+            top_k=top_k,
+            minimum_score=minimum_score,
+        )
+
+    async def search_v2(
+        self,
+        query: str,
+        user_id: Optional[str] = None,
+        domains: Optional[List[str]] = None,
+        memory_top_k: Optional[int] = None,
+        original_top_k: Optional[int] = None,
+        include_original_chunks: bool = True,
+        search_mode: str = "default",
+        top_k: Optional[int] = None,
+        minimum_score: float = 0.0,
+    ) -> HybridSearchResult:
+        payload = _personal_v2_search_payload(
+            query=query,
+            user_id=user_id,
+            domains=domains,
+            memory_top_k=memory_top_k,
+            original_top_k=original_top_k,
+            include_original_chunks=include_original_chunks,
+            search_mode=search_mode,
+            top_k=top_k,
+            minimum_score=minimum_score,
+        )
+        env = await self._transport.post("/v2/memory/search", json=payload)
+        return _parse_hybrid_search(env.data or {}, env.request_id, env.elapsed_ms)
+
+    # ── Lifecycle ──────────────────────────────────────────────────────
+
+    async def close(self) -> None:
+        await self._transport.close()
+
+    async def __aenter__(self) -> "AsyncMemcodeClient":
+        return self
+
+    async def __aexit__(self, *exc) -> None:
+        await self.close()

memcode_sdk/async_v2_client.py

@@ -0,0 +1,147 @@
+"""Asynchronous client for tenant-bound Memcode v2 memory operations."""
+
+from __future__ import annotations
+
+import os
+from typing import Any, Dict, List, Optional
+from urllib.parse import quote
+
+from ._http import DEFAULT_TIMEOUT, AsyncTransport
+from .v2_client import (
+    _parse_ingest,
+    _parse_ingest_status,
+    _parse_retrieve,
+    _parse_search,
+    _required,
+    _scope,
+    _search_mode,
+    _top_k,
+)
+from .v2_types import V2IngestResult, V2IngestStatus, V2RetrieveResult, V2SearchResult
+
+
+class AsyncMemcodeV2Client:
+    """Asynchronous tenant-bound v2 client."""
+
+    def __init__(
+        self,
+        api_url: Optional[str] = None,
+        api_key: Optional[str] = None,
+        timeout: int = DEFAULT_TIMEOUT,
+    ) -> None:
+        resolved_url = api_url or os.getenv("MEMCODE_API_URL") or "http://localhost:8000"
+        resolved_key = _required("api_key", api_key or os.getenv("MEMCODE_API_KEY") or "")
+        self._transport = AsyncTransport(resolved_url, resolved_key, timeout)
+
+    async def ingest(
+        self,
+        *,
+        space_id: str,
+        content: str,
+        idempotency_key: str,
+        actor_id: Optional[str] = None,
+        title: Optional[str] = None,
+        occurred_at: Optional[str] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+        tags: Optional[List[str]] = None,
+    ) -> V2IngestResult:
+        key = _required("idempotency_key", idempotency_key)
+        if len(key) > 256:
+            raise ValueError("MemcodeV2Client: idempotency_key cannot exceed 256 characters")
+        payload: Dict[str, Any] = {
+            "space_id": _required("space_id", space_id),
+            "content": _required("content", content),
+        }
+        for name, value in (("actor_id", actor_id), ("title", title), ("occurred_at", occurred_at)):
+            if value is not None:
+                payload[name] = _required(name, value)
+        if metadata is not None:
+            payload["metadata"] = metadata
+        if tags is not None:
+            payload["tags"] = list(dict.fromkeys(_required("tag", tag) for tag in tags))
+        env = await self._transport.post(
+            "/v2/memory/ingest",
+            json=payload,
+            headers={"Idempotency-Key": key},
+        )
+        return _parse_ingest(env.data or {}, env.request_id, env.elapsed_ms)
+
+    async def get_ingest_status(self, job_id: str) -> V2IngestStatus:
+        encoded = quote(_required("job_id", job_id), safe="")
+        env = await self._transport.get(f"/v2/memory/ingest/{encoded}")
+        return _parse_ingest_status(env.data or {}, env.request_id, env.elapsed_ms)
+
+    async def search(
+        self,
+        *,
+        context_space_id: str,
+        query: str,
+        actor_id: Optional[str] = None,
+        scope: str = "inherited",
+        search_mode: str = "default",
+        top_k: int = 10,
+        minimum_score: float = 0.0,
+        domains: Optional[List[str]] = None,
+        include_original_chunks: Optional[bool] = None,
+        original_top_k: Optional[int] = None,
+    ) -> V2SearchResult:
+        if isinstance(minimum_score, bool) or not 0 <= minimum_score <= 1:
+            raise ValueError("MemcodeV2Client: minimum_score must be between 0 and 1")
+        payload: Dict[str, Any] = {
+            "context_space_id": _required("context_space_id", context_space_id),
+            "query": _required("query", query),
+            "scope": _scope(scope),
+            "search_mode": _search_mode(search_mode),
+            "top_k": _top_k(top_k),
+            "minimum_score": minimum_score,
+        }
+        if actor_id is not None:
+            payload["actor_id"] = _required("actor_id", actor_id)
+        if domains is not None:
+            if not domains:
+                raise ValueError("MemcodeV2Client: domains cannot be empty")
+            payload["domains"] = list(
+                dict.fromkeys(_required("domain", domain) for domain in domains)
+            )
+        if include_original_chunks is not None:
+            if not isinstance(include_original_chunks, bool):
+                raise ValueError(
+                    "MemcodeV2Client: include_original_chunks must be a boolean"
+                )
+            payload["include_original_chunks"] = include_original_chunks
+        if original_top_k is not None:
+            payload["original_top_k"] = _top_k(original_top_k)
+        env = await self._transport.post("/v2/memory/search", json=payload)
+        return _parse_search(env.data or {}, env.request_id, env.elapsed_ms)
+
+    async def retrieve(
+        self,
+        *,
+        context_space_id: str,
+        query: str,
+        actor_id: Optional[str] = None,
+        scope: str = "inherited",
+        top_k: int = 5,
+    ) -> V2RetrieveResult:
+        payload: Dict[str, Any] = {
+            "context_space_id": _required("context_space_id", context_space_id),
+            "query": _required("query", query),
+            "scope": _scope(scope),
+            "top_k": _top_k(top_k),
+        }
+        if actor_id is not None:
+            payload["actor_id"] = _required("actor_id", actor_id)
+        env = await self._transport.post("/v2/memory/retrieve", json=payload)
+        return _parse_retrieve(env.data or {}, env.request_id, env.elapsed_ms)
+
+    async def close(self) -> None:
+        await self._transport.close()
+
+    async def __aenter__(self) -> "AsyncMemcodeV2Client":
+        return self
+
+    async def __aexit__(self, *exc: Any) -> None:
+        await self.close()
+
+
+AsyncMemoryV2Client = AsyncMemcodeV2Client