atomicmemory 1.0.0__py3-none-any.whl

atomicmemory/providers/mem0/http.py

@@ -0,0 +1,195 @@
+"""HTTP transport for the Mem0 provider — provider-tagged sync + async helpers.
+
+Port of the Mem0-bound layer in `atomicmemory-sdk/src/memory/mem0-provider/http.ts`
+(which itself wraps the shared `shared/http-client.ts`). Same error-mapping
+policy as the AtomicMemory transport, but errors are tagged with
+``provider="mem0"`` so callers can route them.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+import httpx
+
+from atomicmemory.core.errors import NetworkError, ProviderError, RateLimitError
+
+_PROVIDER_NAME = "mem0"
+
+
+@dataclass(frozen=True)
+class HttpOptions:
+    api_url: str
+    api_key: str | None
+    timeout_seconds: float
+
+
+def _headers(options: HttpOptions, extra: dict[str, str] | None = None) -> dict[str, str]:
+    headers: dict[str, str] = {"Content-Type": "application/json"}
+    if options.api_key:
+        headers["Authorization"] = f"Bearer {options.api_key}"
+    if extra:
+        headers.update(extra)
+    return headers
+
+
+def _parse_retry_after(value: str | None) -> float | None:
+    if not value:
+        return None
+    try:
+        return float(value)
+    except ValueError:
+        return None
+
+
+def _raise_for_status(response: httpx.Response, path: str) -> None:
+    if response.status_code == 429:
+        raise RateLimitError(
+            "Rate limited",
+            provider=_PROVIDER_NAME,
+            retry_after_seconds=_parse_retry_after(response.headers.get("Retry-After")),
+            context={"path": path},
+        )
+    if response.is_success:
+        return
+    body_text = response.text
+    body_decoded: Any = body_text
+    try:
+        body_decoded = response.json()
+    except (ValueError, httpx.DecodingError):
+        body_decoded = body_text
+    raise ProviderError(
+        f"HTTP {response.status_code}: {body_text or response.reason_phrase}",
+        provider=_PROVIDER_NAME,
+        status_code=response.status_code,
+        response_body=body_decoded,
+        context={"path": path},
+    )
+
+
+def _request(
+    client: httpx.Client,
+    options: HttpOptions,
+    method: str,
+    path: str,
+    *,
+    json: Any | None = None,
+) -> httpx.Response:
+    url = f"{options.api_url}{path}"
+    try:
+        return client.request(method, url, headers=_headers(options), json=json, timeout=options.timeout_seconds)
+    except httpx.TimeoutException as exc:
+        raise NetworkError(
+            f"Timeout after {options.timeout_seconds}s",
+            provider=_PROVIDER_NAME,
+            cause=exc,
+            context={"path": path, "method": method},
+        ) from exc
+    except httpx.RequestError as exc:
+        raise NetworkError(
+            f"Transport error: {exc}",
+            provider=_PROVIDER_NAME,
+            cause=exc,
+            context={"path": path, "method": method},
+        ) from exc
+
+
+def fetch_json(
+    client: httpx.Client,
+    options: HttpOptions,
+    path: str,
+    *,
+    method: str = "GET",
+    json: Any | None = None,
+) -> Any:
+    response = _request(client, options, method, path, json=json)
+    _raise_for_status(response, path)
+    return response.json()
+
+
+def fetch_json_or_none(
+    client: httpx.Client,
+    options: HttpOptions,
+    path: str,
+    *,
+    method: str = "GET",
+    json: Any | None = None,
+) -> Any | None:
+    response = _request(client, options, method, path, json=json)
+    if response.status_code == 404:
+        return None
+    _raise_for_status(response, path)
+    return response.json()
+
+
+def delete_ignore_404(client: httpx.Client, options: HttpOptions, path: str) -> None:
+    response = _request(client, options, "DELETE", path)
+    if response.status_code == 404:
+        return
+    _raise_for_status(response, path)
+
+
+# ---- async ---------------------------------------------------------------
+
+
+async def _arequest(
+    client: httpx.AsyncClient,
+    options: HttpOptions,
+    method: str,
+    path: str,
+    *,
+    json: Any | None = None,
+) -> httpx.Response:
+    url = f"{options.api_url}{path}"
+    try:
+        return await client.request(method, url, headers=_headers(options), json=json, timeout=options.timeout_seconds)
+    except httpx.TimeoutException as exc:
+        raise NetworkError(
+            f"Timeout after {options.timeout_seconds}s",
+            provider=_PROVIDER_NAME,
+            cause=exc,
+            context={"path": path, "method": method},
+        ) from exc
+    except httpx.RequestError as exc:
+        raise NetworkError(
+            f"Transport error: {exc}",
+            provider=_PROVIDER_NAME,
+            cause=exc,
+            context={"path": path, "method": method},
+        ) from exc
+
+
+async def afetch_json(
+    client: httpx.AsyncClient,
+    options: HttpOptions,
+    path: str,
+    *,
+    method: str = "GET",
+    json: Any | None = None,
+) -> Any:
+    response = await _arequest(client, options, method, path, json=json)
+    _raise_for_status(response, path)
+    return response.json()
+
+
+async def afetch_json_or_none(
+    client: httpx.AsyncClient,
+    options: HttpOptions,
+    path: str,
+    *,
+    method: str = "GET",
+    json: Any | None = None,
+) -> Any | None:
+    response = await _arequest(client, options, method, path, json=json)
+    if response.status_code == 404:
+        return None
+    _raise_for_status(response, path)
+    return response.json()
+
+
+async def adelete_ignore_404(client: httpx.AsyncClient, options: HttpOptions, path: str) -> None:
+    response = await _arequest(client, options, "DELETE", path)
+    if response.status_code == 404:
+        return
+    _raise_for_status(response, path)

atomicmemory/providers/mem0/mappers.py

@@ -0,0 +1,145 @@
+"""Wire-format mappers + body builders for the Mem0 provider.
+
+Port of `atomicmemory-sdk/src/memory/mem0-provider/mappers.ts`. Pure
+functions — shared by the sync and async providers.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any
+
+from atomicmemory.memory.types import (
+    IngestInput,
+    IngestResult,
+    Memory,
+    Scope,
+    SearchResult,
+)
+from atomicmemory.providers.mem0.config import Mem0ProviderConfig
+
+_MetadataDict = dict[str, Any]
+
+
+def unwrap_mem0_array(raw: Any) -> list[_MetadataDict]:
+    """Return a list of memory dicts from either a bare array or ``{results: [...]}``."""
+    if isinstance(raw, list):
+        return list(raw)
+    if isinstance(raw, dict) and "results" in raw:
+        results = raw["results"]
+        if isinstance(results, list):
+            return list(results)
+    return []
+
+
+def _parse_iso(value: str | None) -> datetime | None:
+    if value is None:
+        return None
+    text = value.replace("Z", "+00:00") if value.endswith("Z") else value
+    return datetime.fromisoformat(text)
+
+
+def _extract_memory_text(raw: dict[str, Any]) -> str:
+    """Pick the memory text from either flat ``memory`` or nested ``data.memory``."""
+    if raw.get("memory") is not None:
+        return str(raw["memory"])
+    data = raw.get("data")
+    if isinstance(data, dict) and data.get("memory") is not None:
+        return str(data["memory"])
+    return ""
+
+
+def to_memory(raw: dict[str, Any], scope: Scope) -> Memory:
+    return Memory(
+        id=str(raw["id"]),
+        content=_extract_memory_text(raw),
+        scope=scope,
+        created_at=_parse_iso(raw.get("created_at")) or datetime.now().astimezone(),
+        updated_at=_parse_iso(raw.get("updated_at")),
+        metadata=raw.get("metadata"),
+    )
+
+
+def to_search_result(raw: dict[str, Any], scope: Scope) -> SearchResult:
+    raw_score = raw.get("score")
+    score: float = float(raw_score) if raw_score is not None else 0.0
+    return SearchResult(memory=to_memory(raw, scope), score=score)
+
+
+def to_ingest_result(raw_memories: list[dict[str, Any]]) -> IngestResult:
+    created: list[str] = []
+    updated: list[str] = []
+    unchanged: list[str] = []
+    for mem in raw_memories:
+        event = (mem.get("event") or "ADD").upper()
+        if event == "ADD":
+            created.append(str(mem.get("id", "")))
+        elif event == "UPDATE":
+            updated.append(str(mem.get("id", "")))
+        elif event in {"NONE", "NOOP"}:
+            unchanged.append(str(mem.get("id", "")))
+        else:
+            created.append(str(mem.get("id", "")))
+    return IngestResult(created=created, updated=updated, unchanged=unchanged)
+
+
+def resolve_infer_flag(input: IngestInput, config: Mem0ProviderConfig) -> bool:
+    metadata = input.metadata or {}
+    metadata_infer = metadata.get("infer") if isinstance(metadata, dict) else None
+    if isinstance(metadata_infer, bool):
+        return metadata_infer
+    return config.default_infer
+
+
+def build_ingest_body(input: IngestInput, user_id: str, config: Mem0ProviderConfig) -> dict[str, Any]:
+    """Compose Mem0's ``POST /v1/memories/`` request body."""
+    metadata = input.metadata or {}
+    clean_metadata = {k: v for k, v in metadata.items() if k != "infer"} if isinstance(metadata, dict) else {}
+    body: dict[str, Any] = {
+        "user_id": user_id,
+        "infer": resolve_infer_flag(input, config),
+    }
+    if clean_metadata:
+        body["metadata"] = clean_metadata
+    if input.mode == "text":
+        body["messages"] = [{"role": "user", "content": input.content}]
+    elif input.mode == "messages":
+        body["messages"] = [{"role": m.role, "content": m.content} for m in input.messages]
+    _apply_enterprise_fields(body, config)
+    _apply_scope_identifiers(body, input.scope)
+    return body
+
+
+def build_search_body(
+    query: str,
+    scope: Scope,
+    config: Mem0ProviderConfig,
+    limit: int | None = None,
+) -> dict[str, Any]:
+    """Compose Mem0 v2's ``POST /v2/memories/search/`` body with nested filters."""
+    filters: dict[str, Any] = {}
+    if scope.user:
+        filters["user_id"] = scope.user
+    if scope.agent:
+        filters["agent_id"] = scope.agent
+    if scope.thread:
+        filters["run_id"] = scope.thread
+    body: dict[str, Any] = {"query": query, "filters": filters}
+    if limit is not None:
+        body["limit"] = limit
+    _apply_enterprise_fields(body, config)
+    return body
+
+
+def _apply_enterprise_fields(body: dict[str, Any], config: Mem0ProviderConfig) -> None:
+    if config.org_id:
+        body["org_id"] = config.org_id
+    if config.project_id:
+        body["project_id"] = config.project_id
+
+
+def _apply_scope_identifiers(body: dict[str, Any], scope: Scope) -> None:
+    if scope.agent:
+        body["agent_id"] = scope.agent
+    if scope.thread:
+        body["run_id"] = scope.thread

atomicmemory/providers/mem0/provider.py

@@ -0,0 +1,202 @@
+"""Sync Mem0Provider — V3 core + Health.
+
+Port of `atomicmemory-sdk/src/memory/mem0-provider/mem0-provider.ts`.
+Mem0's ``/memories`` endpoint always runs server-side extraction, so
+``verbatim`` ingest is rejected — capabilities advertise only
+``text`` + ``messages`` modes, and ``do_ingest`` raises
+``ProviderError("Unsupported")`` if a verbatim input slips through.
+"""
+
+from __future__ import annotations
+
+import logging
+import time
+from typing import Any
+
+import httpx
+
+from atomicmemory.core.errors import ProviderError
+from atomicmemory.memory.provider import BaseMemoryProvider
+from atomicmemory.memory.types import (
+    Capabilities,
+    CapabilitiesExtensions,
+    CapabilitiesRequiredScope,
+    HealthStatus,
+    IngestInput,
+    IngestResult,
+    ListRequest,
+    ListResultPage,
+    Memory,
+    MemoryRef,
+    SearchRequest,
+    SearchResultPage,
+)
+from atomicmemory.providers.mem0.config import Mem0ProviderConfig
+from atomicmemory.providers.mem0.http import (
+    HttpOptions,
+    delete_ignore_404,
+    fetch_json,
+    fetch_json_or_none,
+)
+from atomicmemory.providers.mem0.mappers import (
+    build_ingest_body,
+    build_search_body,
+    resolve_infer_flag,
+    to_ingest_result,
+    to_memory,
+    to_search_result,
+    unwrap_mem0_array,
+)
+
+_logger = logging.getLogger("atomicmemory.providers.mem0")
+
+
+class Mem0Provider(BaseMemoryProvider):
+    """Sync HTTP-backed V3 provider for Mem0 (OSS + hosted)."""
+
+    name = "mem0"
+
+    def __init__(self, config: Mem0ProviderConfig) -> None:
+        self._config = config
+        self._http_options = HttpOptions(
+            api_url=config.api_url.rstrip("/"),
+            api_key=config.api_key,
+            timeout_seconds=config.timeout_seconds,
+        )
+        self._prefix = config.path_prefix
+        self._client: httpx.Client | None = None
+        self._initialized = False
+
+    def initialize(self) -> None:
+        if self._client is None:
+            self._client = httpx.Client()
+        self._initialized = True
+
+    def close(self) -> None:
+        if self._client is not None:
+            self._client.close()
+            self._client = None
+        self._initialized = False
+
+    # ------------------------------------------------------------------
+    # V3 core methods
+    # ------------------------------------------------------------------
+
+    def do_ingest(self, input: IngestInput) -> IngestResult:
+        if input.mode == "verbatim":
+            raise ProviderError(
+                "mem0 does not support verbatim ingest; use the atomicmemory provider for "
+                "deterministic one-input-equals-one-memory storage.",
+                provider=self.name,
+                context={"operation": "ingest", "mode": "verbatim"},
+            )
+        user_id = input.scope.user or ""
+        body = build_ingest_body(input, user_id, self._config)
+        should_defer = self._config.defer_inference and resolve_infer_flag(input, self._config)
+        if should_defer:
+            body["infer"] = False
+        raw = fetch_json(
+            self._require_client(),
+            self._http_options,
+            self._path("/memories/"),
+            method="POST",
+            json=body,
+        )
+        memories = unwrap_mem0_array(raw)
+        if should_defer:
+            self._fire_background_inference(body)
+        return to_ingest_result(memories)
+
+    def do_search(self, request: SearchRequest) -> SearchResultPage:
+        body = build_search_body(request.query, request.scope, self._config, request.limit)
+        raw = fetch_json(
+            self._require_client(),
+            self._http_options,
+            self._search_path(),
+            method="POST",
+            json=body,
+        )
+        results = [to_search_result(m, request.scope) for m in unwrap_mem0_array(raw)]
+        return SearchResultPage(results=results)
+
+    def do_get(self, ref: MemoryRef) -> Memory | None:
+        raw = fetch_json_or_none(self._require_client(), self._http_options, self._path(f"/memories/{ref.id}/"))
+        if raw is None:
+            return None
+        return to_memory(raw, ref.scope)
+
+    def do_delete(self, ref: MemoryRef) -> None:
+        delete_ignore_404(self._require_client(), self._http_options, self._path(f"/memories/{ref.id}/"))
+
+    def do_list(self, request: ListRequest) -> ListResultPage:
+        limit = request.limit if request.limit is not None else 20
+        offset = int(request.cursor) if request.cursor else 0
+        page = (offset // limit) + 1 if offset > 0 else None
+        path = self._path(f"/memories/?user_id={request.scope.user or ''}&page_size={limit}")
+        if page is not None:
+            path += f"&page={page}"
+        raw = fetch_json(self._require_client(), self._http_options, path)
+        memories = [to_memory(m, request.scope) for m in unwrap_mem0_array(raw)]
+        next_offset = offset + len(memories)
+        cursor = str(next_offset) if len(memories) == limit else None
+        return ListResultPage(memories=memories, cursor=cursor)
+
+    # ------------------------------------------------------------------
+    # Capabilities + extensions
+    # ------------------------------------------------------------------
+
+    def capabilities(self) -> Capabilities:
+        return Capabilities(
+            ingest_modes=["text", "messages"],
+            required_scope=CapabilitiesRequiredScope(default=["user"]),
+            extensions=CapabilitiesExtensions(health=True),
+        )
+
+    def get_extension(self, name: str) -> Any | None:
+        if name == "health":
+            return self
+        return None
+
+    def health(self) -> HealthStatus:
+        start = time.monotonic()
+        try:
+            fetch_json(
+                self._require_client(),
+                self._http_options,
+                self._path("/memories/?user_id=health-check&page_size=1"),
+            )
+            return HealthStatus(ok=True, latency_ms=(time.monotonic() - start) * 1000.0)
+        except (ProviderError, ValueError):
+            return HealthStatus(ok=False, latency_ms=(time.monotonic() - start) * 1000.0)
+
+    # ------------------------------------------------------------------
+    # Internals
+    # ------------------------------------------------------------------
+
+    def _path(self, endpoint: str) -> str:
+        return f"{self._prefix}{endpoint}"
+
+    def _search_path(self) -> str:
+        # mem0 2.0 split search out of the v1 family.
+        return "/memories/search/" if self._prefix == "" else "/v2/memories/search/"
+
+    def _require_client(self) -> httpx.Client:
+        if self._client is None:
+            raise ProviderError(
+                "Mem0Provider is not initialized. Call initialize() first.",
+                provider=self.name,
+            )
+        return self._client
+
+    def _fire_background_inference(self, body: dict[str, Any]) -> None:
+        """Best-effort re-ingest with infer=true. Errors are logged, never raised."""
+        try:
+            fetch_json(
+                self._require_client(),
+                self._http_options,
+                self._path("/memories/"),
+                method="POST",
+                json={**body, "infer": True},
+            )
+        except Exception as exc:
+            _logger.warning("[mem0] deferred AUDN failed: %s", exc)

atomicmemory/search/__init__.py

@@ -0,0 +1,47 @@
+"""Local search primitives — similarity, chunking, ranking, and orchestration.
+
+Port of `atomicmemory-sdk/src/search/` and the chunking helpers at
+`src/utils/chunking.ts`. These are pure Python (numpy + stdlib) and work
+without any provider configured — useful for offline experiments,
+fixture-driven benchmarks, and embedding the SDK in non-Atomicmem
+contexts.
+"""
+
+from atomicmemory.search.chunking import (
+    ChunkOptions,
+    ChunkResult,
+    chunk_by_paragraphs,
+    chunk_by_sentences,
+    chunk_text,
+    chunk_text_with_metadata,
+)
+from atomicmemory.search.ranking import RankingConfig, rerank
+from atomicmemory.search.semantic_search import (
+    SemanticSearch,
+    SemanticSearchConfig,
+    SemanticSearchResult,
+    StoredContext,
+)
+from atomicmemory.search.similarity import (
+    cosine_similarity,
+    find_top_k,
+    rank_by_similarity,
+)
+
+__all__ = [
+    "ChunkOptions",
+    "ChunkResult",
+    "RankingConfig",
+    "SemanticSearch",
+    "SemanticSearchConfig",
+    "SemanticSearchResult",
+    "StoredContext",
+    "chunk_by_paragraphs",
+    "chunk_by_sentences",
+    "chunk_text",
+    "chunk_text_with_metadata",
+    "cosine_similarity",
+    "find_top_k",
+    "rank_by_similarity",
+    "rerank",
+]