atomicmemory 1.0.0__py3-none-any.whl

atomicmemory/providers/atomicmemory/handle_impl.py

@@ -0,0 +1,325 @@
+"""AtomicMemoryHandle root implementation — base routes + categories.
+
+Port of `atomicmemory-sdk/src/memory/atomicmemory-provider/handle-impl.ts:78-191`
+plus the namespace-specific memory/search mappers (lines 321-463).
+
+This module owns the base 8 routes (ingestFull, ingestQuick, search,
+searchFast, expand, list, get, delete) and exposes the five category
+sub-handles. Per-category modules live alongside.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from datetime import datetime
+from typing import Any
+from urllib.parse import quote, urlencode
+
+import httpx
+
+from atomicmemory.core.errors import ProviderError, ValidationError
+from atomicmemory.providers.atomicmemory.agents import AtomicMemoryAgents
+from atomicmemory.providers.atomicmemory.audit import AtomicMemoryAudit
+from atomicmemory.providers.atomicmemory.config_handle import AtomicMemoryConfig
+from atomicmemory.providers.atomicmemory.handle import (
+    AtomicMemoryIngestInput,
+    AtomicMemoryIngestResult,
+    AtomicMemoryListOptions,
+    AtomicMemoryListResultPage,
+    AtomicMemoryMemory,
+    AtomicMemorySearchRequest,
+    AtomicMemorySearchResult,
+    AtomicMemorySearchResultPage,
+    MemoryScope,
+    WorkspaceScope,
+)
+from atomicmemory.providers.atomicmemory.http import HttpOptions, fetch_json, fetch_json_or_none, fetch_void
+from atomicmemory.providers.atomicmemory.lessons import AtomicMemoryLessons
+from atomicmemory.providers.atomicmemory.lifecycle import AtomicMemoryLifecycle
+from atomicmemory.providers.atomicmemory.scope_mapper import (
+    assert_scope_allows_visibility,
+    scope_to_fields,
+    scope_to_query_pairs,
+    strip_agent_scope,
+)
+
+Route = Callable[[str], str]
+
+
+class AtomicMemoryHandle:
+    """Typed access to AtomicMemory-specific routes.
+
+    Constructed by :class:`AtomicMemoryProvider` and exposed via
+    ``MemoryClient.atomicmemory``. Base routes hang off this object;
+    category handles hang off ``.lifecycle``, ``.audit``, ``.lessons``,
+    ``.config``, ``.agents``.
+    """
+
+    def __init__(self, client: httpx.Client, http: HttpOptions, route: Route) -> None:
+        self._client = client
+        self._http = http
+        self._route = route
+        self.lifecycle = AtomicMemoryLifecycle(client, http, route)
+        self.audit = AtomicMemoryAudit(client, http, route)
+        self.lessons = AtomicMemoryLessons(client, http, route)
+        self.config = AtomicMemoryConfig(client, http, route)
+        self.agents = AtomicMemoryAgents(client, http, route)
+
+    # ------------------------------------------------------------------
+    # Base routes
+    # ------------------------------------------------------------------
+
+    def ingest_full(self, input: AtomicMemoryIngestInput, scope: MemoryScope) -> AtomicMemoryIngestResult:
+        return self._post_ingest(self._route("/memories/ingest"), input, scope)
+
+    def ingest_quick(
+        self,
+        input: AtomicMemoryIngestInput,
+        scope: MemoryScope,
+        skip_extraction: bool = False,
+    ) -> AtomicMemoryIngestResult:
+        return self._post_ingest(self._route("/memories/ingest/quick"), input, scope, skip_extraction=skip_extraction)
+
+    def search(self, request: AtomicMemorySearchRequest, scope: MemoryScope) -> AtomicMemorySearchResultPage:
+        return self._post_search(self._route("/memories/search"), request, scope)
+
+    def search_fast(self, request: AtomicMemorySearchRequest, scope: MemoryScope) -> AtomicMemorySearchResultPage:
+        # Core's fast-search handler parses `as_of` but drops it; we still
+        # send it for forward-compat per TS handle-impl.
+        return self._post_search(self._route("/memories/search/fast"), request, scope)
+
+    def expand(self, refs: list[str], scope: MemoryScope) -> list[AtomicMemoryMemory]:
+        body: dict[str, Any] = {**scope_to_fields(scope), "memory_ids": refs}
+        raw = fetch_json(
+            self._client,
+            self._http,
+            self._route("/memories/expand"),
+            method="POST",
+            json=body,
+        )
+        echoed = strip_agent_scope(scope)
+        return [_to_atomic_memory(m, echoed) for m in raw.get("memories", [])]
+
+    def list(
+        self,
+        scope: MemoryScope,
+        options: AtomicMemoryListOptions | dict[str, Any] | None = None,
+    ) -> AtomicMemoryListResultPage:
+        opts = _coerce_list_options(options)
+        _assert_list_options_scope_compat(scope, opts)
+        pairs: list[tuple[str, str]] = scope_to_query_pairs(scope)
+        if opts.limit is not None:
+            pairs.append(("limit", str(opts.limit)))
+        if opts.offset is not None:
+            pairs.append(("offset", str(opts.offset)))
+        if opts.source_site:
+            pairs.append(("source_site", opts.source_site))
+        if opts.episode_id:
+            pairs.append(("episode_id", opts.episode_id))
+        path = self._route(f"/memories/list?{urlencode(pairs)}")
+        raw = fetch_json(self._client, self._http, path)
+        limit = opts.limit if opts.limit is not None else 20
+        offset = opts.offset if opts.offset is not None else 0
+        memories_raw = raw.get("memories", [])
+        next_offset = offset + len(memories_raw)
+        has_more = len(memories_raw) == limit
+        echoed = strip_agent_scope(scope)
+        return AtomicMemoryListResultPage(
+            memories=[_to_atomic_memory(m, echoed) for m in memories_raw],
+            count=raw.get("count", len(memories_raw)),
+            cursor=str(next_offset) if has_more else None,
+        )
+
+    def get(self, id: str, scope: MemoryScope) -> AtomicMemoryMemory | None:
+        path = self._route(f"/memories/{quote(id, safe='')}?{urlencode(scope_to_query_pairs(scope))}")
+        raw = fetch_json_or_none(self._client, self._http, path)
+        if raw is None:
+            return None
+        return _to_atomic_memory(raw, strip_agent_scope(scope))
+
+    def delete(self, id: str, scope: MemoryScope) -> None:
+        path = self._route(f"/memories/{quote(id, safe='')}?{urlencode(scope_to_query_pairs(scope))}")
+        try:
+            fetch_void(self._client, self._http, path, method="DELETE")
+        except ProviderError as exc:
+            if exc.status_code == 404:
+                return
+            raise
+
+    # ------------------------------------------------------------------
+    # Internals
+    # ------------------------------------------------------------------
+
+    def _post_ingest(
+        self,
+        path: str,
+        input: AtomicMemoryIngestInput,
+        scope: MemoryScope,
+        *,
+        skip_extraction: bool = False,
+    ) -> AtomicMemoryIngestResult:
+        assert_scope_allows_visibility(scope, input.visibility)
+        body: dict[str, Any] = {
+            **scope_to_fields(scope),
+            "conversation": input.conversation,
+            "source_site": input.source_site,
+            "source_url": input.source_url or "",
+        }
+        if isinstance(scope, WorkspaceScope) and input.visibility:
+            body["visibility"] = input.visibility
+        if input.config_override is not None:
+            body["config_override"] = input.config_override
+        if skip_extraction:
+            body["skip_extraction"] = True
+        raw = fetch_json(self._client, self._http, path, method="POST", json=body)
+        return AtomicMemoryIngestResult.model_validate(raw)
+
+    def _post_search(
+        self,
+        path: str,
+        request: AtomicMemorySearchRequest,
+        scope: MemoryScope,
+    ) -> AtomicMemorySearchResultPage:
+        body: dict[str, Any] = {
+            **scope_to_fields(scope, include_agent_scope=True),
+            "query": request.query,
+        }
+        if request.limit is not None:
+            body["limit"] = request.limit
+        if request.threshold is not None:
+            body["threshold"] = request.threshold
+        if request.as_of is not None:
+            body["as_of"] = request.as_of.isoformat()
+        if request.retrieval_mode is not None:
+            body["retrieval_mode"] = request.retrieval_mode
+        if request.token_budget is not None:
+            body["token_budget"] = request.token_budget
+        if request.namespace_scope is not None:
+            body["namespace_scope"] = request.namespace_scope
+        if request.source_site is not None:
+            body["source_site"] = request.source_site
+        if request.skip_repair:
+            body["skip_repair"] = True
+        if request.config_override is not None:
+            body["config_override"] = request.config_override
+        raw = fetch_json(self._client, self._http, path, method="POST", json=body)
+        return _map_search_response(raw, scope)
+
+
+# ---------------------------------------------------------------------------
+# Mapping helpers (namespace-specific; do NOT reuse V3's mappers)
+# ---------------------------------------------------------------------------
+
+
+def _coerce_list_options(
+    options: AtomicMemoryListOptions | dict[str, Any] | None,
+) -> AtomicMemoryListOptions:
+    if options is None:
+        return AtomicMemoryListOptions()
+    if isinstance(options, dict):
+        return AtomicMemoryListOptions.model_validate(options)
+    return options
+
+
+def _assert_list_options_scope_compat(scope: MemoryScope, options: AtomicMemoryListOptions) -> None:
+    """Reject options core silently drops on workspace lists.
+
+    ``source_site`` and ``episode_id`` are user-scope only. Core
+    ignores them on workspace lists *but still validates* episode_id as
+    a UUID before branching, which can surface as a misleading 400.
+    Fail closed in the SDK so the mismatch surfaces at the call site.
+    """
+    if not isinstance(scope, WorkspaceScope):
+        return
+    if options.source_site is not None:
+        raise ValidationError(
+            "`source_site` is only valid on user scope; core ignores it on "
+            "workspace list queries. Omit the option or use a user-scope list.",
+            context={"scope_kind": "workspace"},
+        )
+    if options.episode_id is not None:
+        raise ValidationError(
+            "`episode_id` is only valid on user scope; core ignores it on "
+            "workspace list queries but still validates it as a UUID first. "
+            "Omit the option or use a user-scope list.",
+            context={"scope_kind": "workspace"},
+        )
+
+
+def _coalesce(*values: Any) -> Any:
+    for value in values:
+        if value is not None:
+            return value
+    return None
+
+
+def _to_atomic_memory(raw: dict[str, Any], scope: MemoryScope) -> AtomicMemoryMemory:
+    """Map raw core memory to AtomicMemoryMemory, preserving full scope.
+
+    Distinct from V3's ``to_memory`` which flattens scope to a `Scope`
+    and drops ``importance`` into metadata. The namespace surface keeps
+    those as first-class fields.
+    """
+    payload: dict[str, Any] = {
+        "id": raw["id"],
+        "content": raw.get("content") or "",
+        "scope": scope,
+        "created_at": _parse_iso(raw.get("created_at")) or _now_utc(),
+    }
+    if raw.get("updated_at"):
+        payload["updated_at"] = _parse_iso(raw["updated_at"])
+    for field in ("importance", "source_site", "source_url", "episode_id", "visibility", "metadata"):
+        if raw.get(field) is not None:
+            payload[field] = raw[field]
+    return AtomicMemoryMemory.model_validate(payload)
+
+
+def _to_atomic_search_result(raw: dict[str, Any], scope: MemoryScope) -> AtomicMemorySearchResult:
+    similarity = _coalesce(raw.get("semantic_similarity"), raw.get("similarity"))
+    ranking_score = _coalesce(raw.get("ranking_score"), raw.get("score"))
+    relevance = raw.get("relevance")
+    score = _coalesce(ranking_score, similarity, 0.0)
+    payload: dict[str, Any] = {
+        "memory": _to_atomic_memory(raw, scope),
+        "score": score,
+    }
+    if similarity is not None:
+        payload["similarity"] = similarity
+    if ranking_score is not None:
+        payload["ranking_score"] = ranking_score
+    if relevance is not None:
+        payload["relevance"] = relevance
+    if raw.get("importance") is not None:
+        payload["importance"] = raw["importance"]
+    return AtomicMemorySearchResult.model_validate(payload)
+
+
+def _map_search_response(raw: dict[str, Any], scope: MemoryScope) -> AtomicMemorySearchResultPage:
+    memories_raw = raw.get("memories") or []
+    payload: dict[str, Any] = {
+        "count": raw.get("count", len(memories_raw)),
+        "retrieval_mode": raw.get("retrieval_mode") or "flat",
+        "scope": scope,
+        "results": [_to_atomic_search_result(m, scope) for m in memories_raw],
+    }
+    if raw.get("injection_text") is not None:
+        payload["injection_text"] = raw["injection_text"]
+    for field in ("citations", "tier_assignments", "expand_ids", "lesson_check", "consensus", "observability"):
+        if raw.get(field) is not None:
+            payload[field] = raw[field]
+    if raw.get("estimated_context_tokens") is not None:
+        payload["estimated_context_tokens"] = raw["estimated_context_tokens"]
+    return AtomicMemorySearchResultPage.model_validate(payload)
+
+
+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 _now_utc() -> datetime:
+    from datetime import timezone
+
+    return datetime.now(tz=timezone.utc)

atomicmemory/providers/atomicmemory/http.py

@@ -0,0 +1,255 @@
+"""Sync HTTP transport for the AtomicMemory provider.
+
+Port of `atomicmemory-sdk/src/memory/atomicmemory-provider/http.ts` and
+the shared client at `atomicmemory-sdk/src/memory/shared/http-client.ts`.
+
+This module owns the wire-error mapping policy:
+
+- 429 → ``RateLimitError`` (with optional ``Retry-After`` seconds).
+- non-2xx → ``ProviderError`` with ``status_code`` and decoded body.
+- transport failure (timeout, DNS, connection) → ``NetworkError``.
+- 404 is special-cased on ``fetch_json_or_none`` and ``delete_ignore_404``.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+import httpx
+
+from atomicmemory.core.errors import NetworkError, ProviderError, RateLimitError
+
+_PROVIDER_NAME = "atomicmemory"
+
+
+@dataclass(frozen=True)
+class HttpOptions:
+    """Per-request transport options, derived from provider config."""
+
+    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:
+        retry_after = _parse_retry_after(response.headers.get("Retry-After"))
+        raise RateLimitError(
+            "Rate limited",
+            provider=_PROVIDER_NAME,
+            retry_after_seconds=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,
+    headers: dict[str, str] | None = None,
+) -> httpx.Response:
+    url = f"{options.api_url}{path}"
+    try:
+        return client.request(
+            method,
+            url,
+            headers=_headers(options, headers),
+            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:
+    """Send a request and return the decoded JSON response body."""
+    response = _request(client, options, method, path, json=json)
+    _raise_for_status(response, path)
+    return response.json()
+
+
+def fetch_void(
+    client: httpx.Client,
+    options: HttpOptions,
+    path: str,
+    *,
+    method: str = "GET",
+    json: Any | None = None,
+) -> None:
+    """Send a request and discard the body."""
+    response = _request(client, options, method, path, json=json)
+    _raise_for_status(response, path)
+
+
+def fetch_json_or_none(
+    client: httpx.Client,
+    options: HttpOptions,
+    path: str,
+    *,
+    method: str = "GET",
+    json: Any | None = None,
+) -> Any | None:
+    """Send a request; return None on 404, decoded JSON otherwise."""
+    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:
+    """DELETE that swallows 404 (V3 contract: missing target = success)."""
+    response = _request(client, options, "DELETE", path)
+    if response.status_code == 404:
+        return
+    _raise_for_status(response, path)
+
+
+# ---------------------------------------------------------------------------
+# Async transport — paired with the sync helpers above.
+# ---------------------------------------------------------------------------
+
+
+async def _arequest(
+    client: httpx.AsyncClient,
+    options: HttpOptions,
+    method: str,
+    path: str,
+    *,
+    json: Any | None = None,
+    headers: dict[str, str] | None = None,
+) -> httpx.Response:
+    url = f"{options.api_url}{path}"
+    try:
+        return await client.request(
+            method,
+            url,
+            headers=_headers(options, headers),
+            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_void(
+    client: httpx.AsyncClient,
+    options: HttpOptions,
+    path: str,
+    *,
+    method: str = "GET",
+    json: Any | None = None,
+) -> None:
+    response = await _arequest(client, options, method, path, json=json)
+    _raise_for_status(response, path)
+
+
+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)