atomicmemory 1.0.0__py3-none-any.whl

atomicmemory/providers/atomicmemory/lessons.py

@@ -0,0 +1,133 @@
+"""AtomicMemoryLessons — lessons category.
+
+Port of the lessons section of
+`atomicmemory-sdk/src/memory/atomicmemory-provider/handle-impl.ts:895-993`.
+All routes are user-scoped.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+from urllib.parse import quote
+
+import httpx
+
+from atomicmemory.providers.atomicmemory.handle import (
+    Lesson,
+    LessonSeverity,
+    LessonsListResult,
+    LessonStats,
+    ReportLessonResult,
+)
+from atomicmemory.providers.atomicmemory.http import (
+    HttpOptions,
+    afetch_json,
+    afetch_void,
+    fetch_json,
+    fetch_void,
+)
+
+Route = Callable[[str], str]
+
+# `Lessons.list` shadows the `list` builtin inside the class body, so
+# `list[str]` annotations there refer to the method. Module-level alias.
+_StrList = list[str]
+
+
+class AtomicMemoryLessons:
+    """Lesson list / report / delete operations for a user."""
+
+    def __init__(self, client: httpx.Client, http: HttpOptions, route: Route) -> None:
+        self._client = client
+        self._http = http
+        self._route = route
+
+    def list(self, user_id: str) -> LessonsListResult:
+        path = self._route(f"/memories/lessons?user_id={quote(user_id, safe='')}")
+        raw = fetch_json(self._client, self._http, path)
+        return LessonsListResult.model_validate(
+            {
+                "lessons": [Lesson.model_validate(row) for row in raw.get("lessons", [])],
+                "count": raw.get("count", 0),
+            }
+        )
+
+    def stats(self, user_id: str) -> LessonStats:
+        path = self._route(f"/memories/lessons/stats?user_id={quote(user_id, safe='')}")
+        raw = fetch_json(self._client, self._http, path)
+        return LessonStats.model_validate(raw)
+
+    def report(
+        self,
+        user_id: str,
+        pattern: str,
+        sources: _StrList | None = None,
+        severity: LessonSeverity | None = None,
+    ) -> ReportLessonResult:
+        body: dict[str, Any] = {"user_id": user_id, "pattern": pattern}
+        if sources:
+            body["source_memory_ids"] = sources
+        if severity is not None:
+            body["severity"] = severity
+        raw = fetch_json(
+            self._client,
+            self._http,
+            self._route("/memories/lessons/report"),
+            method="POST",
+            json=body,
+        )
+        return ReportLessonResult.model_validate(raw)
+
+    def delete(self, lesson_id: str, user_id: str) -> None:
+        path = self._route(f"/memories/lessons/{quote(lesson_id, safe='')}?user_id={quote(user_id, safe='')}")
+        fetch_void(self._client, self._http, path, method="DELETE")
+
+
+class AsyncAtomicMemoryLessons:
+    """Async counterpart of :class:`AtomicMemoryLessons`."""
+
+    def __init__(self, client: httpx.AsyncClient, http: HttpOptions, route: Route) -> None:
+        self._client = client
+        self._http = http
+        self._route = route
+
+    async def list(self, user_id: str) -> LessonsListResult:
+        path = self._route(f"/memories/lessons?user_id={quote(user_id, safe='')}")
+        raw = await afetch_json(self._client, self._http, path)
+        return LessonsListResult.model_validate(
+            {
+                "lessons": [Lesson.model_validate(row) for row in raw.get("lessons", [])],
+                "count": raw.get("count", 0),
+            }
+        )
+
+    async def stats(self, user_id: str) -> LessonStats:
+        path = self._route(f"/memories/lessons/stats?user_id={quote(user_id, safe='')}")
+        raw = await afetch_json(self._client, self._http, path)
+        return LessonStats.model_validate(raw)
+
+    async def report(
+        self,
+        user_id: str,
+        pattern: str,
+        sources: _StrList | None = None,
+        severity: LessonSeverity | None = None,
+    ) -> ReportLessonResult:
+        body: dict[str, Any] = {"user_id": user_id, "pattern": pattern}
+        if sources:
+            body["source_memory_ids"] = sources
+        if severity is not None:
+            body["severity"] = severity
+        raw = await afetch_json(
+            self._client,
+            self._http,
+            self._route("/memories/lessons/report"),
+            method="POST",
+            json=body,
+        )
+        return ReportLessonResult.model_validate(raw)
+
+    async def delete(self, lesson_id: str, user_id: str) -> None:
+        path = self._route(f"/memories/lessons/{quote(lesson_id, safe='')}?user_id={quote(user_id, safe='')}")
+        await afetch_void(self._client, self._http, path, method="DELETE")

atomicmemory/providers/atomicmemory/lifecycle.py

@@ -0,0 +1,202 @@
+"""AtomicMemoryLifecycle — admin lifecycle category.
+
+Port of the lifecycle section of
+`atomicmemory-sdk/src/memory/atomicmemory-provider/handle-impl.ts:474-564`.
+All routes are user-scoped per core (no workspace_id / agent_id
+accepted); cross-workspace admin lives elsewhere.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+import httpx
+
+from atomicmemory.providers.atomicmemory.handle import (
+    CapCheckResult,
+    ConsolidationExecutionResult,
+    ConsolidationResult,
+    ConsolidationScanResult,
+    DecayResult,
+    ReconcileStatus,
+    ReconciliationResult,
+    ResetSourceResult,
+    StatsResult,
+)
+from atomicmemory.providers.atomicmemory.http import HttpOptions, afetch_json, fetch_json
+
+Route = Callable[[str], str]
+
+
+def _to_consolidation_result(raw: dict[str, Any]) -> ConsolidationResult:
+    if "consolidated_memory_ids" in raw:
+        return ConsolidationExecutionResult.model_validate(raw)
+    return ConsolidationScanResult.model_validate(raw)
+
+
+class AtomicMemoryLifecycle:
+    """Lifecycle admin operations for a user."""
+
+    def __init__(self, client: httpx.Client, http: HttpOptions, route: Route) -> None:
+        self._client = client
+        self._http = http
+        self._route = route
+
+    def consolidate(self, user_id: str, execute: bool = False) -> ConsolidationResult:
+        body: dict[str, Any] = {"user_id": user_id}
+        if execute:
+            body["execute"] = True
+        raw = fetch_json(
+            self._client,
+            self._http,
+            self._route("/memories/consolidate"),
+            method="POST",
+            json=body,
+        )
+        return _to_consolidation_result(raw)
+
+    def decay(self, user_id: str, dry_run: bool = True) -> DecayResult:
+        body: dict[str, Any] = {"user_id": user_id}
+        # Core treats dry_run as true unless explicitly false; only forward
+        # the flag when the caller opted into a non-dry pass.
+        if dry_run is False:
+            body["dry_run"] = False
+        raw = fetch_json(
+            self._client,
+            self._http,
+            self._route("/memories/decay"),
+            method="POST",
+            json=body,
+        )
+        return DecayResult.model_validate(raw)
+
+    def cap(self, user_id: str) -> CapCheckResult:
+        path = self._route(f"/memories/cap?user_id={user_id}")
+        raw = fetch_json(self._client, self._http, path)
+        return CapCheckResult.model_validate(raw)
+
+    def stats(self, user_id: str) -> StatsResult:
+        path = self._route(f"/memories/stats?user_id={user_id}")
+        raw = fetch_json(self._client, self._http, path)
+        return StatsResult.model_validate(raw)
+
+    def reset_source(self, user_id: str, source_site: str) -> ResetSourceResult:
+        raw = fetch_json(
+            self._client,
+            self._http,
+            self._route("/memories/reset-source"),
+            method="POST",
+            json={"user_id": user_id, "source_site": source_site},
+        )
+        return ResetSourceResult.model_validate(raw)
+
+    def reconcile(self, user_id: str) -> ReconciliationResult:
+        raw = fetch_json(
+            self._client,
+            self._http,
+            self._route("/memories/reconcile"),
+            method="POST",
+            json={"user_id": user_id},
+        )
+        return ReconciliationResult.model_validate(raw)
+
+    def reconcile_all(self) -> ReconciliationResult:
+        """Run reconciliation across every user (privileged batch pass).
+
+        Maps to the no-``user_id`` branch of core's ``POST
+        /memories/reconcile`` route.
+        """
+        raw = fetch_json(
+            self._client,
+            self._http,
+            self._route("/memories/reconcile"),
+            method="POST",
+            json={},
+        )
+        return ReconciliationResult.model_validate(raw)
+
+    def reconcile_status(self, user_id: str) -> ReconcileStatus:
+        path = self._route(f"/memories/reconcile/status?user_id={user_id}")
+        raw = fetch_json(self._client, self._http, path)
+        return ReconcileStatus.model_validate(raw)
+
+
+class AsyncAtomicMemoryLifecycle:
+    """Async counterpart of :class:`AtomicMemoryLifecycle`."""
+
+    def __init__(self, client: httpx.AsyncClient, http: HttpOptions, route: Route) -> None:
+        self._client = client
+        self._http = http
+        self._route = route
+
+    async def consolidate(self, user_id: str, execute: bool = False) -> ConsolidationResult:
+        body: dict[str, Any] = {"user_id": user_id}
+        if execute:
+            body["execute"] = True
+        raw = await afetch_json(
+            self._client,
+            self._http,
+            self._route("/memories/consolidate"),
+            method="POST",
+            json=body,
+        )
+        return _to_consolidation_result(raw)
+
+    async def decay(self, user_id: str, dry_run: bool = True) -> DecayResult:
+        body: dict[str, Any] = {"user_id": user_id}
+        if dry_run is False:
+            body["dry_run"] = False
+        raw = await afetch_json(
+            self._client,
+            self._http,
+            self._route("/memories/decay"),
+            method="POST",
+            json=body,
+        )
+        return DecayResult.model_validate(raw)
+
+    async def cap(self, user_id: str) -> CapCheckResult:
+        path = self._route(f"/memories/cap?user_id={user_id}")
+        raw = await afetch_json(self._client, self._http, path)
+        return CapCheckResult.model_validate(raw)
+
+    async def stats(self, user_id: str) -> StatsResult:
+        path = self._route(f"/memories/stats?user_id={user_id}")
+        raw = await afetch_json(self._client, self._http, path)
+        return StatsResult.model_validate(raw)
+
+    async def reset_source(self, user_id: str, source_site: str) -> ResetSourceResult:
+        raw = await afetch_json(
+            self._client,
+            self._http,
+            self._route("/memories/reset-source"),
+            method="POST",
+            json={"user_id": user_id, "source_site": source_site},
+        )
+        return ResetSourceResult.model_validate(raw)
+
+    async def reconcile(self, user_id: str) -> ReconciliationResult:
+        raw = await afetch_json(
+            self._client,
+            self._http,
+            self._route("/memories/reconcile"),
+            method="POST",
+            json={"user_id": user_id},
+        )
+        return ReconciliationResult.model_validate(raw)
+
+    async def reconcile_all(self) -> ReconciliationResult:
+        raw = await afetch_json(
+            self._client,
+            self._http,
+            self._route("/memories/reconcile"),
+            method="POST",
+            json={},
+        )
+        return ReconciliationResult.model_validate(raw)
+
+    async def reconcile_status(self, user_id: str) -> ReconcileStatus:
+        path = self._route(f"/memories/reconcile/status?user_id={user_id}")
+        raw = await afetch_json(self._client, self._http, path)
+        return ReconcileStatus.model_validate(raw)

atomicmemory/providers/atomicmemory/mappers.py

@@ -0,0 +1,125 @@
+"""Wire-format ↔ V3 type mappers for the AtomicMemory provider.
+
+Port of `atomicmemory-sdk/src/memory/atomicmemory-provider/mappers.ts`.
+Field-for-field equivalent. Date strings are parsed with
+``datetime.fromisoformat`` (handles both ``+00:00`` and ``Z`` in 3.11+
+via the small normalization helper below).
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import Any
+
+from atomicmemory.memory.types import (
+    IngestResult,
+    Memory,
+    MemoryVersion,
+    MemoryVersionEvent,
+    Provenance,
+    Scope,
+    SearchResult,
+)
+
+_AUDIT_EVENTS: set[MemoryVersionEvent] = {"created", "updated", "superseded", "invalidated"}
+
+
+def _coalesce(*values: Any) -> Any:
+    """Return the first value that is not None.
+
+    Python equivalent of TS's ``??`` (nullish coalescing). Crucial for
+    score fields where ``0.0`` is a legitimate value: ``a or b`` would
+    incorrectly treat ``0.0`` as missing.
+    """
+    for value in values:
+        if value is not None:
+            return value
+    return None
+
+
+def _parse_iso(value: str | None) -> datetime | None:
+    """Parse an ISO 8601 datetime, normalizing trailing 'Z' to UTC."""
+    if value is None:
+        return None
+    text = value.replace("Z", "+00:00") if value.endswith("Z") else value
+    return datetime.fromisoformat(text)
+
+
+def to_memory(raw: dict[str, Any], scope: Scope) -> Memory:
+    """Map a single core memory record to a V3 ``Memory``."""
+    created_at = _parse_iso(raw.get("created_at")) or datetime.now(tz=timezone.utc)
+    return Memory(
+        id=raw["id"],
+        content=raw["content"],
+        scope=scope,
+        created_at=created_at,
+        provenance=_build_provenance(raw),
+        metadata=_build_metadata(raw),
+    )
+
+
+def _build_provenance(raw: dict[str, Any]) -> Provenance | None:
+    fields: dict[str, Any] = {}
+    if "source_site" in raw and raw["source_site"] is not None:
+        fields["source"] = raw["source_site"]
+    if "source_url" in raw and raw["source_url"] is not None:
+        fields["source_url"] = raw["source_url"]
+    if not fields:
+        return None
+    return Provenance(**fields)
+
+
+def _build_metadata(raw: dict[str, Any]) -> dict[str, Any] | None:
+    metadata: dict[str, Any] = {}
+    if "importance" in raw and raw["importance"] is not None:
+        metadata["importance"] = raw["importance"]
+    if "episode_id" in raw and raw["episode_id"] is not None:
+        metadata["episode_id"] = raw["episode_id"]
+    return metadata or None
+
+
+def to_search_result(raw: dict[str, Any], scope: Scope) -> SearchResult:
+    """Map a single search hit, preserving every score variant core emits.
+
+    Mirrors TS's ``??`` semantics so that legitimate ``0.0`` scores are
+    not silently replaced by a fallback field.
+    """
+    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)
+    return SearchResult(
+        memory=to_memory(raw, scope),
+        score=score,
+        similarity=similarity,
+        ranking_score=ranking_score,
+        relevance=relevance,
+    )
+
+
+def to_ingest_result(raw: dict[str, Any]) -> IngestResult:
+    """Map ``POST /memories/ingest[/quick]`` response to V3 IngestResult."""
+    return IngestResult(
+        created=list(raw.get("stored_memory_ids") or []),
+        updated=list(raw.get("updated_memory_ids") or []),
+        unchanged=[],
+    )
+
+
+def to_memory_version(raw: dict[str, Any]) -> MemoryVersion:
+    """Map an audit-trail entry to a V3 ``MemoryVersion``.
+
+    Unknown ``event`` values are normalized to ``"created"`` (matches TS).
+    """
+    raw_event = raw.get("event")
+    event: MemoryVersionEvent = raw_event if raw_event in _AUDIT_EVENTS else "created"
+    created_at = _parse_iso(raw.get("created_at"))
+    if created_at is None:
+        raise ValueError("audit entry missing created_at")
+    return MemoryVersion(
+        id=raw["id"],
+        content=raw["content"],
+        created_at=created_at,
+        parent_id=raw.get("parent_id"),
+        event=event,
+    )

atomicmemory/providers/atomicmemory/path.py

@@ -0,0 +1,20 @@
+"""Route-path helpers for the AtomicMemory provider.
+
+Port of `atomicmemory-sdk/src/memory/atomicmemory-provider/path.ts`.
+"""
+
+from __future__ import annotations
+
+
+def normalize_api_version(api_version: str) -> str:
+    """Normalize a config value to a leading-slash prefix, no trailing slash.
+
+    Examples:
+        ``"v1"`` → ``"/v1"``
+        ``"/v1/"`` → ``"/v1"``
+        ``""`` → ``""``  (empty disables prefixing)
+    """
+    trimmed = api_version.strip("/")
+    if trimmed == "":
+        return ""
+    return f"/{trimmed}"