memcode-sdk 2.3.1__py3-none-any.whl

memcode_sdk/client.py

@@ -0,0 +1,576 @@
+"""
+Synchronous Memcode client.
+
+Usage::
+
+    from memcode_sdk import MemcodeClient
+
+    client = MemcodeClient(api_url="http://localhost:8000", api_key="sk-...")
+
+    # Health check
+    health = client.ping()
+
+    # Ingest a conversation turn
+    result = client.ingest(
+        user_query="I just got promoted to senior engineer!",
+        agent_response="Congratulations on your promotion!",
+        user_id="user_42",
+    )
+
+    # Retrieve an answer grounded in stored memories
+    answer = client.retrieve(query="What is my job title?", user_id="user_42")
+    print(answer.answer)
+
+    # Raw semantic search
+    hits = client.search(query="work", user_id="user_42", domains=["profile"])
+    for r in hits.results:
+        print(r.domain, r.content, r.score)
+
+    client.close()
+"""
+
+from __future__ import annotations
+
+import os
+import warnings
+from typing import Any, Dict, List, Optional
+
+from ._http import DEFAULT_TIMEOUT, SyncTransport
+from .types import (
+    DomainResult,
+    HealthStatus,
+    HybridSearchResult,
+    IngestResult,
+    OperationDetail,
+    PersonalV2IngestResult,
+    PersonalV2IngestStatus,
+    PersonalV2RetrieveResult,
+    RetrieveResult,
+    SearchResult,
+    SourceRecord,
+    WeaverSummary,
+)
+
+
+class MemcodeClient:
+    """Synchronous 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 = SyncTransport(self._api_url, self._api_key, timeout)
+
+    # ── Health ─────────────────────────────────────────────────────────
+
+    def ping(self) -> HealthStatus:
+        """Check the Memcode API health. Never raises on a valid HTTP response."""
+        try:
+            env = 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"),
+        )
+
+    def is_ready(self) -> bool:
+        """Return ``True`` if the API is healthy and pipelines are loaded."""
+        return self.ping().pipelines_ready
+
+    # ── Ingest ─────────────────────────────────────────────────────────
+
+    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.
+
+        Returns:
+            IngestResult with classification, domain results, and timing.
+        """
+        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 = self._transport.post("/v1/memory/ingest", json=payload)
+        return _parse_ingest(env.data or {}, env.request_id, env.elapsed_ms)
+
+    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:
+        """Start an advanced durable personal v2 ingest job.
+
+        ``user_id`` is a deprecated compatibility field. Authenticated API
+        keys and JWTs determine the personal user, so new callers should omit
+        it.
+        """
+        payload = _personal_v2_ingest_payload(
+            user_query,
+            user_id,
+            agent_response,
+            session_datetime,
+            image_url,
+            effort_level,
+            forget,
+        )
+        headers = _optional_idempotency_headers(idempotency_key)
+        env = self._transport.post("/v2/memory/ingest", json=payload, headers=headers)
+        return _parse_personal_v2_ingest(env.data or {}, env.request_id, env.elapsed_ms)
+
+    def get_ingest_status_v2(self, job_id: str) -> PersonalV2IngestStatus:
+        """Poll a personal v2 ingest job using its normal-user status route."""
+        from urllib.parse import quote
+
+        normalized = str(job_id or "").strip()
+        if not normalized:
+            raise ValueError("MemcodeClient: job_id is required")
+        env = 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 ───────────────────────────────────────────────────────
+
+    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.
+
+        Returns:
+            RetrieveResult with the LLM answer, sources, and confidence.
+        """
+        env = 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)
+
+    def retrieve_v2(
+        self,
+        query: str,
+        user_id: Optional[str] = None,
+        top_k: int = 5,
+    ) -> PersonalV2RetrieveResult:
+        """Use advanced personal v2 retrieval with attribution learning.
+
+        ``user_id`` is deprecated and is only sent when explicitly supplied.
+        """
+        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 = self._transport.post("/v2/memory/retrieve", json=payload)
+        return _parse_personal_v2_retrieve(env.data or {}, env.request_id, env.elapsed_ms)
+
+    # ── Search ─────────────────────────────────────────────────────────
+
+    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.
+
+        Returns:
+            SearchResult with a flat list of SourceRecords.
+        """
+        payload: Dict[str, Any] = {
+            "query": query, "user_id": user_id, "top_k": top_k,
+        }
+        if domains is not None:
+            payload["domains"] = domains
+
+        env = self._transport.post("/v1/memory/search", json=payload)
+        return _parse_search(env.data or {}, env.request_id, env.elapsed_ms)
+
+    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`.
+
+        The method remains source-compatible but now uses the unified
+        ``/v2/memory/search`` endpoint.
+        """
+        return 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,
+        )
+
+    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:
+        """Search personal v2 memory and original chunks through one route.
+
+        The authenticated credential determines the personal user. ``user_id``
+        and ``memory_top_k`` are deprecated compatibility arguments.
+        """
+        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 = self._transport.post("/v2/memory/search", json=payload)
+        return _parse_hybrid_search(env.data or {}, env.request_id, env.elapsed_ms)
+
+    # ── Lifecycle ──────────────────────────────────────────────────────
+
+    def close(self) -> None:
+        """Release the underlying HTTP connection pool."""
+        self._transport.close()
+
+    def __enter__(self) -> "MemcodeClient":
+        return self
+
+    def __exit__(self, *exc) -> None:
+        self.close()
+
+
+# ═══════════════════════════════════════════════════════════════════════════
+# Response parsers (shared with async client)
+# ═══════════════════════════════════════════════════════════════════════════
+
+def _parse_domain(raw: Optional[Dict[str, Any]]) -> Optional[DomainResult]:
+    if not raw:
+        return None
+    ops = [
+        OperationDetail(
+            type=o.get("type", ""), content=o.get("content", ""), reason=o.get("reason", ""),
+        )
+        for o in raw.get("operations", [])
+    ]
+    ws_raw = raw.get("weaver")
+    ws = WeaverSummary(**ws_raw) if ws_raw else None
+    return DomainResult(confidence=raw.get("confidence", 0.0), operations=ops, weaver=ws)
+
+
+def _parse_sources(raw: List[Dict[str, Any]]) -> List[SourceRecord]:
+    return [
+        SourceRecord(
+            domain=s.get("domain", ""),
+            content=s.get("content", ""),
+            score=s.get("score", 0.0),
+            metadata=s.get("metadata", {}),
+        )
+        for s in raw
+    ]
+
+
+def _parse_ingest(
+    data: Dict[str, Any], request_id: Optional[str], elapsed_ms: Optional[float],
+) -> IngestResult:
+    return IngestResult(
+        model=data.get("model", ""),
+        classification=data.get("classification", []),
+        profile=_parse_domain(data.get("profile")),
+        temporal=_parse_domain(data.get("temporal")),
+        summary=_parse_domain(data.get("summary")),
+        image=_parse_domain(data.get("image")),
+        request_id=request_id,
+        elapsed_ms=elapsed_ms,
+    )
+
+
+def _required_personal(name: str, value: str) -> str:
+    normalized = value.strip() if isinstance(value, str) else ""
+    if not normalized:
+        raise ValueError(f"MemcodeClient: {name} is required")
+    return normalized
+
+
+def _append_legacy_user_id(
+    payload: Dict[str, Any],
+    user_id: Optional[str],
+    *,
+    stacklevel: int = 3,
+) -> None:
+    """Append the deprecated personal identifier only when explicitly supplied."""
+    if user_id is not None:
+        warnings.warn(
+            "personal v2 user_id is deprecated; identity is derived from authentication",
+            DeprecationWarning,
+            stacklevel=stacklevel,
+        )
+        payload["user_id"] = _required_personal("user_id", user_id)
+
+
+def _personal_v2_ingest_payload(
+    user_query: str,
+    user_id: Optional[str],
+    agent_response: str,
+    session_datetime: str,
+    image_url: str,
+    effort_level: str,
+    forget: bool,
+) -> Dict[str, Any]:
+    if effort_level not in {"low", "high"}:
+        raise ValueError("MemcodeClient: effort_level must be low or high")
+    payload: Dict[str, Any] = {
+        "user_query": _required_personal("user_query", user_query),
+        "agent_response": agent_response,
+        "session_datetime": session_datetime,
+        "image_url": image_url,
+        "effort_level": effort_level,
+        "forget": forget,
+    }
+    _append_legacy_user_id(payload, user_id, stacklevel=4)
+    return payload
+
+
+def _optional_idempotency_headers(value: str) -> Dict[str, str]:
+    if not value:
+        return {}
+    key = _required_personal("idempotency_key", value)
+    if len(key) > 256:
+        raise ValueError("MemcodeClient: idempotency_key cannot exceed 256 characters")
+    return {"Idempotency-Key": key}
+
+
+def _parse_personal_v2_ingest(
+    data: Dict[str, Any], request_id: Optional[str], elapsed_ms: Optional[float],
+) -> PersonalV2IngestResult:
+    return PersonalV2IngestResult(
+        job_id=data.get("job_id", ""),
+        status=data.get("status", ""),
+        created=data.get("created", False),
+        status_url=data.get("status_url", ""),
+        plan_id=data.get("plan_id"),
+        queued_for_batch=data.get("queued_for_batch"),
+        estimated_available_in_seconds=data.get("estimated_available_in_seconds"),
+        request_id=request_id,
+        elapsed_ms=elapsed_ms,
+    )
+
+
+def _parse_personal_v2_status(
+    data: Dict[str, Any], request_id: Optional[str], elapsed_ms: Optional[float],
+) -> PersonalV2IngestStatus:
+    allowed = set(PersonalV2IngestStatus.__dataclass_fields__) - {
+        "request_id",
+        "elapsed_ms",
+    }
+    parsed = {key: value for key, value in data.items() if key in allowed}
+    return PersonalV2IngestStatus(
+        **parsed,
+        request_id=request_id,
+        elapsed_ms=elapsed_ms,
+    )
+
+
+def _parse_retrieve(
+    data: Dict[str, Any], request_id: Optional[str], elapsed_ms: Optional[float],
+) -> RetrieveResult:
+    return RetrieveResult(
+        model=data.get("model", ""),
+        answer=data.get("answer", ""),
+        sources=_parse_sources(data.get("sources", [])),
+        confidence=data.get("confidence", 0.0),
+        request_id=request_id,
+        elapsed_ms=elapsed_ms,
+    )
+
+
+def _parse_personal_v2_retrieve(
+    data: Dict[str, Any], request_id: Optional[str], elapsed_ms: Optional[float],
+) -> PersonalV2RetrieveResult:
+    return PersonalV2RetrieveResult(
+        model=data.get("model", ""),
+        answer=data.get("answer", ""),
+        sources=_parse_sources(data.get("sources", [])),
+        confidence=data.get("confidence", 0.0),
+        used_source_indices=data.get("used_source_indices", []),
+        connection_learning_queued=data.get("connection_learning_queued", False),
+        used_refs=data.get("used_refs", []),
+        billing=data.get("billing"),
+        request_id=request_id,
+        elapsed_ms=elapsed_ms,
+    )
+
+
+def _parse_search(
+    data: Dict[str, Any], request_id: Optional[str], elapsed_ms: Optional[float],
+) -> SearchResult:
+    return SearchResult(
+        results=_parse_sources(data.get("results", [])),
+        total=data.get("total", 0),
+        request_id=request_id,
+        elapsed_ms=elapsed_ms,
+    )
+
+
+def _personal_v2_search_payload(
+    *,
+    query: str,
+    user_id: Optional[str],
+    domains: Optional[List[str]],
+    memory_top_k: Optional[int],
+    original_top_k: Optional[int],
+    include_original_chunks: bool,
+    search_mode: str,
+    top_k: Optional[int],
+    minimum_score: float,
+) -> Dict[str, Any]:
+    normalized_query = query.strip() if isinstance(query, str) else ""
+    if not normalized_query:
+        raise ValueError("MemcodeClient: query is required")
+    if search_mode not in {"default", "global"}:
+        raise ValueError("MemcodeClient: search_mode must be default or global")
+    if (
+        isinstance(minimum_score, bool)
+        or not isinstance(minimum_score, (int, float))
+        or not 0 <= minimum_score <= 1
+    ):
+        raise ValueError("MemcodeClient: minimum_score must be between 0 and 1")
+    if not isinstance(include_original_chunks, bool):
+        raise ValueError("MemcodeClient: include_original_chunks must be a boolean")
+
+    payload: Dict[str, Any] = {
+        "query": normalized_query,
+        "search_mode": search_mode,
+        "include_original_chunks": include_original_chunks,
+        "minimum_score": minimum_score,
+    }
+    _append_legacy_user_id(payload, user_id, stacklevel=4)
+    if domains is not None:
+        if not domains:
+            raise ValueError("MemcodeClient: domains cannot be empty")
+        allowed = {"profile", "temporal", "summary", "original_chunk"}
+        if any(domain not in allowed for domain in domains):
+            raise ValueError(
+                "MemcodeClient: domains must contain only profile, temporal, "
+                "summary, or original_chunk"
+            )
+        payload["domains"] = domains
+    for name, value in (
+        ("top_k", top_k),
+        ("memory_top_k", memory_top_k),
+        ("original_top_k", original_top_k),
+    ):
+        if value is not None:
+            if isinstance(value, bool) or not isinstance(value, int) or not 1 <= value <= 100:
+                raise ValueError(f"MemcodeClient: {name} must be an integer between 1 and 100")
+    if top_k is not None and memory_top_k is not None:
+        raise ValueError("MemcodeClient: provide only one of top_k or memory_top_k")
+    payload["top_k"] = (
+        top_k
+        if top_k is not None
+        else (memory_top_k if memory_top_k is not None else 10)
+    )
+    if original_top_k is not None:
+        payload["original_top_k"] = original_top_k
+    return payload
+
+
+def _parse_hybrid_search(
+    data: Dict[str, Any], request_id: Optional[str], elapsed_ms: Optional[float],
+) -> HybridSearchResult:
+    has_flat_results = "results" in data
+    results = _parse_sources(data.get("results", []))
+    if "memory_results" in data:
+        memory_results = _parse_sources(data.get("memory_results", []))
+    else:
+        memory_results = [item for item in results if item.domain != "original_chunk"]
+    if "original_chunks" in data:
+        original_chunks = _parse_sources(data.get("original_chunks", []))
+    else:
+        original_chunks = [item for item in results if item.domain == "original_chunk"]
+    if not has_flat_results:
+        results = memory_results + original_chunks
+    return HybridSearchResult(
+        memory_results=memory_results,
+        original_chunks=original_chunks,
+        results=results,
+        total=data.get("total", len(results)),
+        original_storage_enabled=data.get("original_storage_enabled", False),
+        failed_domains=data.get("failed_domains", []),
+        partial=data.get("partial", False),
+        billing=data.get("billing"),
+        request_id=request_id,
+        elapsed_ms=elapsed_ms,
+    )

memcode_sdk/errors.py

@@ -0,0 +1,64 @@
+"""
+Memcode SDK error hierarchy.
+
+All SDK-raised exceptions inherit from ``MemcodeSDKError`` so callers
+can catch the full family with a single ``except MemcodeSDKError``.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+
+class MemcodeSDKError(Exception):
+    """Base for every error raised by the Memcode client SDK."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: Optional[int] = None,
+        request_id: Optional[str] = None,
+        details: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status_code = status_code
+        self.request_id = request_id
+        self.details = details or {}
+
+    def __repr__(self) -> str:
+        parts = [f"message={self.message!r}"]
+        if self.status_code is not None:
+            parts.append(f"status_code={self.status_code}")
+        if self.request_id:
+            parts.append(f"request_id={self.request_id!r}")
+        return f"{self.__class__.__name__}({', '.join(parts)})"
+
+
+class AuthenticationError(MemcodeSDKError):
+    """401 / 403 — invalid or missing API key."""
+
+
+class RateLimitError(MemcodeSDKError):
+    """429 — caller exceeded their per-key quota."""
+
+    def __init__(self, message: str, *, retry_after: Optional[int] = None, **kwargs):
+        super().__init__(message, **kwargs)
+        self.retry_after = retry_after
+
+
+class ServerError(MemcodeSDKError):
+    """5xx — the Memcode API returned a server-side failure."""
+
+
+class ValidationError(MemcodeSDKError):
+    """400 / 422 — the request failed server-side validation."""
+
+
+class ConnectionError(MemcodeSDKError):
+    """Network-level failure (timeout, DNS, refused, etc.)."""
+
+
+class NotReadyError(MemcodeSDKError):
+    """503 — the Memcode API pipelines are still loading."""

memcode_sdk/py.typed

@@ -0,0 +1 @@
+