memcode-sdk 2.3.1__py3-none-any.whl

memcode_sdk/types.py

@@ -0,0 +1,172 @@
+"""
+Public data types returned by the Memcode SDK.
+
+These are plain dataclasses / Pydantic models that mirror the API's
+JSON responses but are fully typed for IDE auto-complete and safety.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any, Dict, List, Optional
+
+
+# ── Shared envelope ────────────────────────────────────────────────────────
+
+class Status(str, Enum):
+    OK = "ok"
+    ERROR = "error"
+
+
+@dataclass(frozen=True)
+class APIEnvelope:
+    """Raw API envelope — internal use only."""
+    status: Status
+    data: Optional[Dict[str, Any]] = None
+    error: Optional[str] = None
+    request_id: Optional[str] = None
+    elapsed_ms: Optional[float] = None
+
+
+# ── Health ─────────────────────────────────────────────────────────────────
+
+@dataclass(frozen=True)
+class HealthStatus:
+    status: str
+    pipelines_ready: bool
+    version: str = ""
+    uptime_seconds: Optional[float] = None
+    error: Optional[str] = None
+
+
+# ── Ingest ─────────────────────────────────────────────────────────────────
+
+@dataclass(frozen=True)
+class OperationDetail:
+    type: str
+    content: str
+    reason: str
+
+
+@dataclass(frozen=True)
+class WeaverSummary:
+    succeeded: int = 0
+    skipped: int = 0
+    failed: int = 0
+
+
+@dataclass(frozen=True)
+class DomainResult:
+    confidence: float = 0.0
+    operations: List[OperationDetail] = field(default_factory=list)
+    weaver: Optional[WeaverSummary] = None
+
+
+@dataclass(frozen=True)
+class IngestResult:
+    """Returned by ``client.ingest()``."""
+    model: str = ""
+    classification: List[Any] = field(default_factory=list)
+    profile: Optional[DomainResult] = None
+    temporal: Optional[DomainResult] = None
+    summary: Optional[DomainResult] = None
+    image: Optional[DomainResult] = None
+    request_id: Optional[str] = None
+    elapsed_ms: Optional[float] = None
+
+
+@dataclass(frozen=True)
+class PersonalV2IngestResult:
+    """Durable receipt returned by personal ``/v2/memory/ingest``."""
+    job_id: str
+    status: str
+    created: bool
+    status_url: str
+    plan_id: Optional[str] = None
+    queued_for_batch: Optional[bool] = None
+    estimated_available_in_seconds: Optional[float] = None
+    request_id: Optional[str] = None
+    elapsed_ms: Optional[float] = None
+
+
+@dataclass(frozen=True)
+class PersonalV2IngestStatus:
+    job_id: str
+    status: str
+    job_type: Optional[str] = None
+    retry_count: int = 0
+    attempt_count: int = 0
+    max_attempts: int = 0
+    timeout_seconds: Optional[float] = None
+    workflow_id: Optional[str] = None
+    run_id: Optional[str] = None
+    progress: Optional[Dict[str, Any]] = None
+    error: Any = None
+    error_state: Optional[Dict[str, Any]] = None
+    result: Optional[Dict[str, Any]] = None
+    created_at: Optional[str] = None
+    updated_at: Optional[str] = None
+    started_at: Optional[str] = None
+    completed_at: Optional[str] = None
+    dead_lettered_at: Optional[str] = None
+    cancelled_at: Optional[str] = None
+    request_id: Optional[str] = None
+    elapsed_ms: Optional[float] = None
+
+
+# ── Retrieve ───────────────────────────────────────────────────────────────
+
+@dataclass(frozen=True)
+class SourceRecord:
+    domain: str
+    content: str
+    score: float = 0.0
+    metadata: Dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class RetrieveResult:
+    """Returned by ``client.retrieve()``."""
+    model: str = ""
+    answer: str = ""
+    sources: List[SourceRecord] = field(default_factory=list)
+    confidence: float = 0.0
+    request_id: Optional[str] = None
+    elapsed_ms: Optional[float] = None
+
+
+@dataclass(frozen=True)
+class PersonalV2RetrieveResult(RetrieveResult):
+    used_source_indices: List[int] = field(default_factory=list)
+    connection_learning_queued: bool = False
+    used_refs: List[str] = field(default_factory=list)
+    billing: Optional[Dict[str, Any]] = None
+
+
+# ── Search ─────────────────────────────────────────────────────────────────
+
+@dataclass(frozen=True)
+class SearchResult:
+    """Returned by ``client.search()``."""
+    results: List[SourceRecord] = field(default_factory=list)
+    total: int = 0
+    request_id: Optional[str] = None
+    elapsed_ms: Optional[float] = None
+
+
+@dataclass(frozen=True)
+class HybridSearchResult:
+    """Returned by unified personal v2 search and its deprecated hybrid alias."""
+    memory_results: List[SourceRecord] = field(default_factory=list)
+    original_chunks: List[SourceRecord] = field(default_factory=list)
+    results: List[SourceRecord] = field(default_factory=list)
+    total: int = 0
+    original_storage_enabled: bool = False
+    billing: Optional[Dict[str, Any]] = None
+    request_id: Optional[str] = None
+    elapsed_ms: Optional[float] = None
+    # Keep additive fields last so existing positional construction remains
+    # source-compatible.
+    failed_domains: List[str] = field(default_factory=list)
+    partial: bool = False

memcode_sdk/v2_client.py

@@ -0,0 +1,214 @@
+"""Synchronous 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, SyncTransport
+from .v2_types import (
+    V2IngestResult,
+    V2IngestStatus,
+    V2MemorySource,
+    V2OperationCounts,
+    V2OriginalStorageStatus,
+    V2RetrieveResult,
+    V2SearchResult,
+    V2SourceLineage,
+    V2SourceProvenance,
+    V2SourceSpace,
+)
+
+_READ_SCOPES = {"inherited", "context_only"}
+_SEARCH_MODES = {"default", "global"}
+
+
+def _required(name: str, value: str) -> str:
+    normalized = str(value or "").strip()
+    if not normalized:
+        raise ValueError(f"MemcodeV2Client: {name} is required")
+    return normalized
+
+
+def _top_k(value: int) -> int:
+    if isinstance(value, bool) or not isinstance(value, int) or not 1 <= value <= 100:
+        raise ValueError("MemcodeV2Client: top_k must be an integer between 1 and 100")
+    return value
+
+
+def _scope(value: str) -> str:
+    if value not in _READ_SCOPES:
+        raise ValueError("MemcodeV2Client: scope must be inherited or context_only")
+    return value
+
+
+def _search_mode(value: str) -> str:
+    if value not in _SEARCH_MODES:
+        raise ValueError("MemcodeV2Client: search_mode must be default or global")
+    return value
+
+
+def _metadata(data: Dict[str, Any], request_id: Optional[str], elapsed_ms: Optional[float]) -> Dict[str, Any]:
+    return {**data, "request_id": request_id, "elapsed_ms": elapsed_ms}
+
+
+def _parse_ingest(data: Dict[str, Any], request_id: Optional[str], elapsed_ms: Optional[float]) -> V2IngestResult:
+    return V2IngestResult(**_metadata(data, request_id, elapsed_ms))
+
+
+def _parse_ingest_status(data: Dict[str, Any], request_id: Optional[str], elapsed_ms: Optional[float]) -> V2IngestStatus:
+    parsed = dict(data)
+    if parsed.get("operation_counts"):
+        parsed["operation_counts"] = V2OperationCounts(**parsed["operation_counts"])
+    if parsed.get("source"):
+        parsed["source"] = V2SourceLineage(**parsed["source"])
+    if parsed.get("original_storage"):
+        parsed["original_storage"] = V2OriginalStorageStatus(**parsed["original_storage"])
+    return V2IngestStatus(**_metadata(parsed, request_id, elapsed_ms))
+
+
+def _parse_source(data: Dict[str, Any]) -> V2MemorySource:
+    parsed = dict(data)
+    parsed["space"] = V2SourceSpace(**parsed["space"])
+    parsed["provenance"] = V2SourceProvenance(**parsed["provenance"])
+    return V2MemorySource(**parsed)
+
+
+def _parse_search(data: Dict[str, Any], request_id: Optional[str], elapsed_ms: Optional[float]) -> V2SearchResult:
+    parsed = dict(data)
+    parsed["results"] = [_parse_source(item) for item in parsed.get("results", [])]
+    return V2SearchResult(**_metadata(parsed, request_id, elapsed_ms))
+
+
+def _parse_retrieve(data: Dict[str, Any], request_id: Optional[str], elapsed_ms: Optional[float]) -> V2RetrieveResult:
+    parsed = dict(data)
+    parsed["sources"] = [_parse_source(item) for item in parsed.get("sources", [])]
+    return V2RetrieveResult(**_metadata(parsed, request_id, elapsed_ms))
+
+
+class MemcodeV2Client:
+    """Tenant-bound v2 client. Credentials determine the organization."""
+
+    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 = SyncTransport(resolved_url, resolved_key, timeout)
+
+    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 = self._transport.post(
+            "/v2/memory/ingest",
+            json=payload,
+            headers={"Idempotency-Key": key},
+        )
+        return _parse_ingest(env.data or {}, env.request_id, env.elapsed_ms)
+
+    def get_ingest_status(self, job_id: str) -> V2IngestStatus:
+        encoded = quote(_required("job_id", job_id), safe="")
+        env = self._transport.get(f"/v2/memory/ingest/{encoded}")
+        return _parse_ingest_status(env.data or {}, env.request_id, env.elapsed_ms)
+
+    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 = self._transport.post("/v2/memory/search", json=payload)
+        return _parse_search(env.data or {}, env.request_id, env.elapsed_ms)
+
+    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 = self._transport.post("/v2/memory/retrieve", json=payload)
+        return _parse_retrieve(env.data or {}, env.request_id, env.elapsed_ms)
+
+    def close(self) -> None:
+        self._transport.close()
+
+    def __enter__(self) -> "MemcodeV2Client":
+        return self
+
+    def __exit__(self, *exc: Any) -> None:
+        self.close()
+
+
+MemoryV2Client = MemcodeV2Client

memcode_sdk/v2_types.py

@@ -0,0 +1,116 @@
+"""Typed results for the tenant-bound Memcode v2 memory routes."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional
+
+
+@dataclass(frozen=True)
+class V2OperationCounts:
+    total: int = 0
+    succeeded: int = 0
+    skipped: int = 0
+    failed: int = 0
+
+
+@dataclass(frozen=True)
+class V2SourceLineage:
+    type: str
+    id: Optional[str] = None
+    record_id: Optional[str] = None
+    version: Optional[str] = None
+
+
+@dataclass(frozen=True)
+class V2OriginalStorageStatus:
+    status: str
+    required: bool
+    indexed_chunks: int = 0
+    expected_chunks: Optional[int] = None
+    cleanup_required: bool = False
+    failure_stage: Optional[str] = None
+
+
+@dataclass(frozen=True)
+class V2IngestResult:
+    id: str
+    space_id: str
+    status: str
+    status_url: Optional[str] = None
+    request_id: Optional[str] = None
+    elapsed_ms: Optional[float] = None
+
+
+@dataclass(frozen=True)
+class V2IngestStatus:
+    id: str
+    space_id: str
+    status: str
+    updated_at: Optional[str] = None
+    operation_counts: Optional[V2OperationCounts] = None
+    produced_memory_ids: List[str] = field(default_factory=list)
+    affected_memory_ids: List[str] = field(default_factory=list)
+    source: Optional[V2SourceLineage] = None
+    original_storage: Optional[V2OriginalStorageStatus] = None
+    retryable: bool = False
+    error: Optional[str] = None
+    status_url: Optional[str] = None
+    request_id: Optional[str] = None
+    elapsed_ms: Optional[float] = None
+
+
+@dataclass(frozen=True)
+class V2SourceSpace:
+    id: str
+    kind: str
+    visibility: str
+    name: str
+
+
+@dataclass(frozen=True)
+class V2SourceProvenance:
+    type: str
+    source_id: Optional[str] = None
+    source_url: Optional[str] = None
+    source_record_id: Optional[str] = None
+    source_version: Optional[str] = None
+    promoted_from_space_id: Optional[str] = None
+    promoted_from_memory_id: Optional[str] = None
+
+
+@dataclass(frozen=True)
+class V2MemorySource:
+    id: str
+    content: str
+    score: float
+    metadata: Dict[str, Any]
+    space: V2SourceSpace
+    provenance: V2SourceProvenance
+    title: Optional[str] = None
+    domain: Optional[str] = None
+
+
+@dataclass(frozen=True)
+class V2SearchResult:
+    results: List[V2MemorySource] = field(default_factory=list)
+    total: int = 0
+    searched_space_ids: List[str] = field(default_factory=list)
+    failed_space_ids: List[str] = field(default_factory=list)
+    partial: bool = False
+    routing_fallback: bool = False
+    request_id: Optional[str] = None
+    elapsed_ms: Optional[float] = None
+
+
+@dataclass(frozen=True)
+class V2RetrieveResult:
+    answer: str = ""
+    sources: List[V2MemorySource] = field(default_factory=list)
+    confidence: float = 0.0
+    searched_space_ids: List[str] = field(default_factory=list)
+    failed_space_ids: List[str] = field(default_factory=list)
+    partial: bool = False
+    routing_fallback: bool = False
+    request_id: Optional[str] = None
+    elapsed_ms: Optional[float] = None