tikuu-memory 0.1.0__tar.gz

tikuu_memory-0.1.0/PKG-INFO

@@ -0,0 +1,89 @@
+Metadata-Version: 2.3
+Name: tikuu-memory
+Version: 0.1.0
+Summary: Tikuu memory SDK: HTTP client and LangGraph snapshot checkpointer
+Author: Utkarsh Tiwari
+Author-email: Utkarsh Tiwari <tiwariutkarsh66@gmail.com>
+Requires-Dist: httpx>=0.28.0
+Requires-Dist: langgraph>=1.0.0
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+
+# tikuu-memory
+
+Python SDK for Tikuu short-term memory: HTTP client for
+[`tikuu-memory-service`](../tikuu-memory-service/) and a LangGraph
+`BaseCheckpointSaver` (`TikuuMemorySaver`).
+
+## Requirements
+
+- Python 3.13+
+- [uv](https://docs.astral.sh/uv/)
+- A running `tikuu-memory-service`
+
+## Install
+
+```bash
+uv add tikuu-memory
+```
+
+## Env (required)
+
+| Variable | Meaning |
+| --- | --- |
+| `TIKUU_MEMORY_SERVICE_URL` | Memory service base URL (no trailing slash) |
+| `TIKUU_AGENT_ID` | Agent UUID used as the storage partition |
+
+`TikuuMemorySaver.from_env()` / `TikuuMemoryClient.from_env()` raise
+`MemoryConfigurationError` if either is missing or blank.
+
+Inside Docker agent containers, tikuu-api-server injects both. For host-local
+runs use e.g. `http://127.0.0.1:8100`.
+
+## Usage
+
+```python
+from tikuu_memory import TikuuMemorySaver
+
+checkpointer = TikuuMemorySaver.from_env()
+# pass checkpointer into create_agent(..., checkpointer=checkpointer)
+
+config = {"configurable": {"thread_id": session_id}}
+```
+
+The CLI template sets `thread_id` to the Tikuu `X-Session-Id`. The saver
+never forces that mapping; any `thread_id` string is accepted.
+
+Storage key: `(agent_id, thread_id, checkpoint_ns)`.
+
+## Session-id-as-thread-id caveats
+
+When using the Tikuu session UUID as `thread_id`:
+
+- Omitting `X-Session-Id` on a later call mints a new session → new empty thread.
+- One session ⇒ one LangGraph thread ⇒ one container `{agent_id}--{session_id}`.
+- Concurrent invokes on the same session race (last snapshot wins); use one
+  in-flight invoke per session.
+- Custom `thread_id` values are allowed in user code.
+
+## V1 limitations
+
+- **Snapshot-only** storage (intentional).
+- **`put_writes` is a no-op** so LangGraph does not crash; interrupt/resume
+  and mid-step crash recovery are not supported yet.
+- Metadata `filter` on `list` is ignored.
+- No auth headers.
+
+## Deferred work
+
+- **TODO(auth):** Send session token header when API server injects one.
+- **TODO(writes):** Persist pending writes for interrupt/resume.
+- **TODO(actor_id):** Optional end-user / tenant key.
+- **TODO(legacy):** Non-snapshot event-log formats.
+- **TODO(serde):** Prefer JSON-only serde if pickle via JsonPlus is undesirable.
+
+## Docs
+
+- [Usage](docs/USAGE.md)
+- [Architecture](docs/ARCHITECTURE.md)
+- [End-to-end smoke path](../docs/MEMORY_SMOKE.md)

tikuu_memory-0.1.0/README.md

@@ -0,0 +1,78 @@
+# tikuu-memory
+
+Python SDK for Tikuu short-term memory: HTTP client for
+[`tikuu-memory-service`](../tikuu-memory-service/) and a LangGraph
+`BaseCheckpointSaver` (`TikuuMemorySaver`).
+
+## Requirements
+
+- Python 3.13+
+- [uv](https://docs.astral.sh/uv/)
+- A running `tikuu-memory-service`
+
+## Install
+
+```bash
+uv add tikuu-memory
+```
+
+## Env (required)
+
+| Variable | Meaning |
+| --- | --- |
+| `TIKUU_MEMORY_SERVICE_URL` | Memory service base URL (no trailing slash) |
+| `TIKUU_AGENT_ID` | Agent UUID used as the storage partition |
+
+`TikuuMemorySaver.from_env()` / `TikuuMemoryClient.from_env()` raise
+`MemoryConfigurationError` if either is missing or blank.
+
+Inside Docker agent containers, tikuu-api-server injects both. For host-local
+runs use e.g. `http://127.0.0.1:8100`.
+
+## Usage
+
+```python
+from tikuu_memory import TikuuMemorySaver
+
+checkpointer = TikuuMemorySaver.from_env()
+# pass checkpointer into create_agent(..., checkpointer=checkpointer)
+
+config = {"configurable": {"thread_id": session_id}}
+```
+
+The CLI template sets `thread_id` to the Tikuu `X-Session-Id`. The saver
+never forces that mapping; any `thread_id` string is accepted.
+
+Storage key: `(agent_id, thread_id, checkpoint_ns)`.
+
+## Session-id-as-thread-id caveats
+
+When using the Tikuu session UUID as `thread_id`:
+
+- Omitting `X-Session-Id` on a later call mints a new session → new empty thread.
+- One session ⇒ one LangGraph thread ⇒ one container `{agent_id}--{session_id}`.
+- Concurrent invokes on the same session race (last snapshot wins); use one
+  in-flight invoke per session.
+- Custom `thread_id` values are allowed in user code.
+
+## V1 limitations
+
+- **Snapshot-only** storage (intentional).
+- **`put_writes` is a no-op** so LangGraph does not crash; interrupt/resume
+  and mid-step crash recovery are not supported yet.
+- Metadata `filter` on `list` is ignored.
+- No auth headers.
+
+## Deferred work
+
+- **TODO(auth):** Send session token header when API server injects one.
+- **TODO(writes):** Persist pending writes for interrupt/resume.
+- **TODO(actor_id):** Optional end-user / tenant key.
+- **TODO(legacy):** Non-snapshot event-log formats.
+- **TODO(serde):** Prefer JSON-only serde if pickle via JsonPlus is undesirable.
+
+## Docs
+
+- [Usage](docs/USAGE.md)
+- [Architecture](docs/ARCHITECTURE.md)
+- [End-to-end smoke path](../docs/MEMORY_SMOKE.md)

tikuu_memory-0.1.0/pyproject.toml

@@ -0,0 +1,25 @@
+[project]
+name = "tikuu-memory"
+version = "0.1.0"
+description = "Tikuu memory SDK: HTTP client and LangGraph snapshot checkpointer"
+readme = "README.md"
+requires-python = ">=3.13"
+dependencies = [
+    "httpx>=0.28.0",
+    "langgraph>=1.0.0",
+]
+
+[[project.authors]]
+name = "Utkarsh Tiwari"
+email = "tiwariutkarsh66@gmail.com"
+
+[build-system]
+requires = ["uv_build>=0.12.1,<0.13.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-asyncio>=0.24.0",
+    "respx>=0.21.0",
+]

tikuu_memory-0.1.0/pyproject.toml.orig

@@ -0,0 +1,24 @@
+[project]
+name = "tikuu-memory"
+version = "0.1.0"
+description = "Tikuu memory SDK: HTTP client and LangGraph snapshot checkpointer"
+readme = "README.md"
+authors = [
+    { name = "Utkarsh Tiwari", email = "tiwariutkarsh66@gmail.com" }
+]
+requires-python = ">=3.13"
+dependencies = [
+    "httpx>=0.28.0",
+    "langgraph>=1.0.0",
+]
+
+[build-system]
+requires = ["uv_build>=0.12.1,<0.13.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-asyncio>=0.24.0",
+    "respx>=0.21.0",
+]

tikuu_memory-0.1.0/src/tikuu_memory/__init__.py

@@ -0,0 +1,17 @@
+"""Tikuu memory SDK: HTTP client and LangGraph snapshot checkpointer."""
+
+from tikuu_memory.client import TikuuMemoryClient
+from tikuu_memory.errors import (
+    MemoryClientError,
+    MemoryConfigurationError,
+    MemoryNotFoundError,
+)
+from tikuu_memory.saver import TikuuMemorySaver
+
+__all__ = [
+    "MemoryClientError",
+    "MemoryConfigurationError",
+    "MemoryNotFoundError",
+    "TikuuMemoryClient",
+    "TikuuMemorySaver",
+]

tikuu_memory-0.1.0/src/tikuu_memory/client.py

@@ -0,0 +1,284 @@
+"""HTTP client for tikuu-memory-service."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from tikuu_memory.config import MemorySettings, settings_from_env
+from tikuu_memory.errors import MemoryClientError, MemoryNotFoundError
+from tikuu_memory.models import CheckpointSnapshot
+
+
+class TikuuMemoryClient:
+    """Thin sync/async HTTP client for checkpoint snapshot routes.
+
+    TODO(auth): Send a session token header when tikuu-api-server starts
+    injecting one into agent containers.
+    """
+
+    def __init__(
+        self,
+        *,
+        base_url: str,
+        agent_id: str,
+        timeout: float = 30.0,
+    ) -> None:
+        self.base_url = base_url.rstrip("/")
+        self.agent_id = agent_id
+        self._timeout = timeout
+        self._sync: httpx.Client | None = None
+        self._async: httpx.AsyncClient | None = None
+
+    @classmethod
+    def from_env(cls, environ: dict[str, str] | None = None) -> TikuuMemoryClient:
+        """Build a client from ``TIKUU_*`` environment variables."""
+        settings = settings_from_env(environ)
+        return cls.from_settings(settings)
+
+    @classmethod
+    def from_settings(cls, settings: MemorySettings) -> TikuuMemoryClient:
+        """Build a client from resolved settings."""
+        return cls(base_url=settings.base_url, agent_id=settings.agent_id)
+
+    def _sync_client(self) -> httpx.Client:
+        if self._sync is None:
+            self._sync = httpx.Client(
+                base_url=self.base_url,
+                timeout=self._timeout,
+            )
+        return self._sync
+
+    def _async_client(self) -> httpx.AsyncClient:
+        if self._async is None:
+            self._async = httpx.AsyncClient(
+                base_url=self.base_url,
+                timeout=self._timeout,
+            )
+        return self._async
+
+    def close(self) -> None:
+        """Close the sync HTTP client if open."""
+        if self._sync is not None:
+            self._sync.close()
+            self._sync = None
+
+    async def aclose(self) -> None:
+        """Close the async HTTP client if open."""
+        if self._async is not None:
+            await self._async.aclose()
+            self._async = None
+
+    def put_checkpoint(
+        self,
+        *,
+        thread_id: str,
+        checkpoint_ns: str,
+        checkpoint_id: str,
+        parent_checkpoint_id: str | None,
+        metadata_blob: str,
+        checkpoint_blob: str,
+    ) -> CheckpointSnapshot:
+        """Upsert one snapshot (sync)."""
+        response = self._sync_client().put(
+            f"/v1/agents/{self.agent_id}/threads/{thread_id}/checkpoints",
+            json={
+                "checkpoint_ns": checkpoint_ns,
+                "checkpoint_id": checkpoint_id,
+                "parent_checkpoint_id": parent_checkpoint_id,
+                "metadata_blob": metadata_blob,
+                "checkpoint_blob": checkpoint_blob,
+            },
+        )
+        return self._parse_snapshot(response)
+
+    async def aput_checkpoint(
+        self,
+        *,
+        thread_id: str,
+        checkpoint_ns: str,
+        checkpoint_id: str,
+        parent_checkpoint_id: str | None,
+        metadata_blob: str,
+        checkpoint_blob: str,
+    ) -> CheckpointSnapshot:
+        """Upsert one snapshot (async)."""
+        response = await self._async_client().put(
+            f"/v1/agents/{self.agent_id}/threads/{thread_id}/checkpoints",
+            json={
+                "checkpoint_ns": checkpoint_ns,
+                "checkpoint_id": checkpoint_id,
+                "parent_checkpoint_id": parent_checkpoint_id,
+                "metadata_blob": metadata_blob,
+                "checkpoint_blob": checkpoint_blob,
+            },
+        )
+        return self._parse_snapshot(response)
+
+    def get_latest(
+        self,
+        *,
+        thread_id: str,
+        checkpoint_ns: str = "",
+    ) -> CheckpointSnapshot:
+        """Fetch the latest snapshot (sync)."""
+        response = self._sync_client().get(
+            f"/v1/agents/{self.agent_id}/threads/{thread_id}/checkpoints/latest",
+            params={"checkpoint_ns": checkpoint_ns},
+        )
+        return self._parse_snapshot(response)
+
+    async def aget_latest(
+        self,
+        *,
+        thread_id: str,
+        checkpoint_ns: str = "",
+    ) -> CheckpointSnapshot:
+        """Fetch the latest snapshot (async)."""
+        response = await self._async_client().get(
+            f"/v1/agents/{self.agent_id}/threads/{thread_id}/checkpoints/latest",
+            params={"checkpoint_ns": checkpoint_ns},
+        )
+        return self._parse_snapshot(response)
+
+    def get_checkpoint(
+        self,
+        *,
+        thread_id: str,
+        checkpoint_id: str,
+        checkpoint_ns: str = "",
+    ) -> CheckpointSnapshot:
+        """Fetch one snapshot by id (sync)."""
+        response = self._sync_client().get(
+            f"/v1/agents/{self.agent_id}/threads/{thread_id}/checkpoints/"
+            f"{checkpoint_id}",
+            params={"checkpoint_ns": checkpoint_ns},
+        )
+        return self._parse_snapshot(response)
+
+    async def aget_checkpoint(
+        self,
+        *,
+        thread_id: str,
+        checkpoint_id: str,
+        checkpoint_ns: str = "",
+    ) -> CheckpointSnapshot:
+        """Fetch one snapshot by id (async)."""
+        response = await self._async_client().get(
+            f"/v1/agents/{self.agent_id}/threads/{thread_id}/checkpoints/"
+            f"{checkpoint_id}",
+            params={"checkpoint_ns": checkpoint_ns},
+        )
+        return self._parse_snapshot(response)
+
+    def list_checkpoints(
+        self,
+        *,
+        thread_id: str,
+        checkpoint_ns: str = "",
+        before: str | None = None,
+        limit: int | None = None,
+    ) -> list[CheckpointSnapshot]:
+        """List snapshots newest-first (sync)."""
+        params: dict[str, Any] = {"checkpoint_ns": checkpoint_ns}
+        if before is not None:
+            params["before"] = before
+        if limit is not None:
+            params["limit"] = limit
+        response = self._sync_client().get(
+            f"/v1/agents/{self.agent_id}/threads/{thread_id}/checkpoints",
+            params=params,
+        )
+        return self._parse_list(response)
+
+    async def alist_checkpoints(
+        self,
+        *,
+        thread_id: str,
+        checkpoint_ns: str = "",
+        before: str | None = None,
+        limit: int | None = None,
+    ) -> list[CheckpointSnapshot]:
+        """List snapshots newest-first (async)."""
+        params: dict[str, Any] = {"checkpoint_ns": checkpoint_ns}
+        if before is not None:
+            params["before"] = before
+        if limit is not None:
+            params["limit"] = limit
+        response = await self._async_client().get(
+            f"/v1/agents/{self.agent_id}/threads/{thread_id}/checkpoints",
+            params=params,
+        )
+        return self._parse_list(response)
+
+    def delete_thread(
+        self,
+        *,
+        thread_id: str,
+        checkpoint_ns: str | None = None,
+    ) -> None:
+        """Delete all snapshots for a thread (sync)."""
+        params: dict[str, Any] = {}
+        if checkpoint_ns is not None:
+            params["checkpoint_ns"] = checkpoint_ns
+        response = self._sync_client().delete(
+            f"/v1/agents/{self.agent_id}/threads/{thread_id}",
+            params=params,
+        )
+        self._raise_for_status(response, allow_204=True)
+
+    async def adelete_thread(
+        self,
+        *,
+        thread_id: str,
+        checkpoint_ns: str | None = None,
+    ) -> None:
+        """Delete all snapshots for a thread (async)."""
+        params: dict[str, Any] = {}
+        if checkpoint_ns is not None:
+            params["checkpoint_ns"] = checkpoint_ns
+        response = await self._async_client().delete(
+            f"/v1/agents/{self.agent_id}/threads/{thread_id}",
+            params=params,
+        )
+        self._raise_for_status(response, allow_204=True)
+
+    def _parse_snapshot(self, response: httpx.Response) -> CheckpointSnapshot:
+        self._raise_for_status(response)
+        return CheckpointSnapshot.from_api(response.json())
+
+    def _parse_list(self, response: httpx.Response) -> list[CheckpointSnapshot]:
+        self._raise_for_status(response)
+        payload = response.json()
+        items = payload.get("items", [])
+        return [CheckpointSnapshot.from_api(item) for item in items]
+
+    @staticmethod
+    def _raise_for_status(
+        response: httpx.Response,
+        *,
+        allow_204: bool = False,
+    ) -> None:
+        if allow_204 and response.status_code == 204:
+            return
+        if response.status_code == 404:
+            detail = _detail(response)
+            raise MemoryNotFoundError(detail or "Checkpoint not found")
+        if response.is_success:
+            return
+        detail = _detail(response)
+        raise MemoryClientError(
+            detail or f"Memory service error (HTTP {response.status_code})",
+            status_code=response.status_code,
+        )
+
+
+def _detail(response: httpx.Response) -> str | None:
+    try:
+        data = response.json()
+    except Exception:
+        return response.text or None
+    if isinstance(data, dict) and "detail" in data:
+        return str(data["detail"])
+    return None

tikuu_memory-0.1.0/src/tikuu_memory/config.py

@@ -0,0 +1,47 @@
+"""Load memory client settings from the process environment."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+
+from tikuu_memory.constants import ENV_AGENT_ID, ENV_MEMORY_SERVICE_URL
+from tikuu_memory.errors import MemoryConfigurationError
+
+
+@dataclass(frozen=True)
+class MemorySettings:
+    """Resolved settings for talking to tikuu-memory-service.
+
+    Attributes:
+        base_url: Memory service origin without a trailing slash.
+        agent_id: Agent identity used as the storage partition key.
+    """
+
+    base_url: str
+    agent_id: str
+
+
+def settings_from_env(
+    environ: dict[str, str] | None = None,
+) -> MemorySettings:
+    """Read ``TIKUU_MEMORY_SERVICE_URL`` and ``TIKUU_AGENT_ID``.
+
+    Args:
+        environ: Mapping to read; defaults to ``os.environ``.
+
+    Raises:
+        MemoryConfigurationError: Either value is missing or blank.
+    """
+    env = environ if environ is not None else os.environ
+    raw_url = (env.get(ENV_MEMORY_SERVICE_URL) or "").strip()
+    agent_id = (env.get(ENV_AGENT_ID) or "").strip()
+    if not raw_url:
+        raise MemoryConfigurationError(
+            f"{ENV_MEMORY_SERVICE_URL} is required and must be non-empty"
+        )
+    if not agent_id:
+        raise MemoryConfigurationError(
+            f"{ENV_AGENT_ID} is required and must be non-empty"
+        )
+    return MemorySettings(base_url=raw_url.rstrip("/"), agent_id=agent_id)

tikuu_memory-0.1.0/src/tikuu_memory/constants.py

@@ -0,0 +1,5 @@
+"""Shared constants for the tikuu-memory SDK."""
+
+# Env vars injected by tikuu-api-server into every agent container (v1).
+ENV_MEMORY_SERVICE_URL = "TIKUU_MEMORY_SERVICE_URL"
+ENV_AGENT_ID = "TIKUU_AGENT_ID"

tikuu_memory-0.1.0/src/tikuu_memory/errors.py

@@ -0,0 +1,17 @@
+"""Errors raised by the tikuu-memory SDK."""
+
+
+class MemoryConfigurationError(Exception):
+    """Raised when required memory configuration is missing or invalid."""
+
+
+class MemoryClientError(Exception):
+    """Raised when the memory service returns an unexpected HTTP error."""
+
+    def __init__(self, message: str, *, status_code: int | None = None) -> None:
+        self.status_code = status_code
+        super().__init__(message)
+
+
+class MemoryNotFoundError(Exception):
+    """Raised when a requested checkpoint does not exist (HTTP 404)."""

tikuu_memory-0.1.0/src/tikuu_memory/models.py

@@ -0,0 +1,47 @@
+"""Dataclasses mirroring memory-service checkpoint payloads."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime
+from typing import Any
+from uuid import UUID
+
+
+@dataclass(frozen=True)
+class CheckpointSnapshot:
+    """One checkpoint snapshot as returned by the memory service."""
+
+    id: UUID
+    agent_id: str
+    thread_id: str
+    checkpoint_ns: str
+    checkpoint_id: str
+    parent_checkpoint_id: str | None
+    metadata_blob: str
+    checkpoint_blob: str
+    created_at: datetime
+
+    @classmethod
+    def from_api(cls, data: dict[str, Any]) -> CheckpointSnapshot:
+        """Build a snapshot from a decoded JSON object."""
+        created_raw = data["created_at"]
+        if isinstance(created_raw, str):
+            created_at = datetime.fromisoformat(created_raw.replace("Z", "+00:00"))
+        else:
+            created_at = created_raw
+        return cls(
+            id=UUID(str(data["id"])),
+            agent_id=str(data["agent_id"]),
+            thread_id=str(data["thread_id"]),
+            checkpoint_ns=str(data.get("checkpoint_ns", "")),
+            checkpoint_id=str(data["checkpoint_id"]),
+            parent_checkpoint_id=(
+                str(data["parent_checkpoint_id"])
+                if data.get("parent_checkpoint_id") is not None
+                else None
+            ),
+            metadata_blob=str(data["metadata_blob"]),
+            checkpoint_blob=str(data["checkpoint_blob"]),
+            created_at=created_at,
+        )

tikuu_memory-0.1.0/src/tikuu_memory/saver.py

@@ -0,0 +1,314 @@
+"""LangGraph ``BaseCheckpointSaver`` backed by tikuu-memory-service.
+
+V1 is snapshot-only: each ``put`` stores a complete checkpoint including
+``channel_values``. Pending writes are not persisted.
+
+TODO(writes): Persist ``put_writes`` for interrupt/resume and mid-step
+crash recovery. The no-op implementation exists so LangGraph's default
+durability does not crash.
+
+TODO(actor_id): Optional end-user / tenant partition key.
+
+TODO(legacy): Non-snapshot event-log reconstruction.
+
+TODO(auth): Forward session token header via the HTTP client.
+"""
+
+from __future__ import annotations
+
+import random
+from collections.abc import AsyncIterator, Iterator, Sequence
+from typing import Any
+
+from langchain_core.runnables import RunnableConfig
+from langgraph.checkpoint.base import (
+    BaseCheckpointSaver,
+    ChannelVersions,
+    Checkpoint,
+    CheckpointMetadata,
+    CheckpointTuple,
+    SerializerProtocol,
+    get_checkpoint_id,
+    get_checkpoint_metadata,
+)
+
+from tikuu_memory.client import TikuuMemoryClient
+from tikuu_memory.errors import MemoryConfigurationError, MemoryNotFoundError
+from tikuu_memory.models import CheckpointSnapshot
+from tikuu_memory.serde import SnapshotSerde
+
+
+class TikuuMemorySaver(BaseCheckpointSaver[str]):
+    """Snapshot checkpointer that stores state in tikuu-memory-service."""
+
+    def __init__(
+        self,
+        client: TikuuMemoryClient,
+        *,
+        serde: SerializerProtocol | None = None,
+    ) -> None:
+        super().__init__(serde=serde)
+        self.client = client
+        self._snapshot_serde = SnapshotSerde(self.serde)
+
+    @classmethod
+    def from_env(
+        cls,
+        environ: dict[str, str] | None = None,
+        *,
+        serde: SerializerProtocol | None = None,
+    ) -> TikuuMemorySaver:
+        """Build a saver from ``TIKUU_MEMORY_SERVICE_URL`` and ``TIKUU_AGENT_ID``.
+
+        Raises:
+            MemoryConfigurationError: Required env vars are missing/blank.
+        """
+        return cls(TikuuMemoryClient.from_env(environ), serde=serde)
+
+    def get_tuple(self, config: RunnableConfig) -> CheckpointTuple | None:
+        """Load a checkpoint tuple (exact id or latest)."""
+        thread_id, checkpoint_ns, checkpoint_id = _parse_config(config)
+        try:
+            if checkpoint_id:
+                snapshot = self.client.get_checkpoint(
+                    thread_id=thread_id,
+                    checkpoint_id=checkpoint_id,
+                    checkpoint_ns=checkpoint_ns,
+                )
+            else:
+                snapshot = self.client.get_latest(
+                    thread_id=thread_id,
+                    checkpoint_ns=checkpoint_ns,
+                )
+        except MemoryNotFoundError:
+            return None
+        return self._to_tuple(snapshot, thread_id=thread_id, checkpoint_ns=checkpoint_ns)
+
+    def list(
+        self,
+        config: RunnableConfig | None,
+        *,
+        filter: dict[str, Any] | None = None,
+        before: RunnableConfig | None = None,
+        limit: int | None = None,
+    ) -> Iterator[CheckpointTuple]:
+        """List checkpoints newest-first.
+
+        Metadata ``filter`` is ignored in v1 (documented; does not raise).
+        """
+        del filter  # unsupported in v1
+        if config is None:
+            return
+        thread_id, checkpoint_ns, _ = _parse_config(config)
+        before_id = get_checkpoint_id(before) if before else None
+        snapshots = self.client.list_checkpoints(
+            thread_id=thread_id,
+            checkpoint_ns=checkpoint_ns,
+            before=before_id,
+            limit=limit,
+        )
+        for snapshot in snapshots:
+            yield self._to_tuple(
+                snapshot,
+                thread_id=thread_id,
+                checkpoint_ns=checkpoint_ns,
+            )
+
+    def put(
+        self,
+        config: RunnableConfig,
+        checkpoint: Checkpoint,
+        metadata: CheckpointMetadata,
+        new_versions: ChannelVersions,
+    ) -> RunnableConfig:
+        """Persist a complete checkpoint snapshot."""
+        del new_versions  # snapshot stores full channel_values
+        thread_id, checkpoint_ns, parent_checkpoint_id = _parse_config(config)
+        checkpoint_id = checkpoint["id"]
+        metadata_blob = self._snapshot_serde.dumps_blob(
+            dict(get_checkpoint_metadata(config, metadata))
+        )
+        checkpoint_blob = self._snapshot_serde.dumps_blob(dict(checkpoint))
+        self.client.put_checkpoint(
+            thread_id=thread_id,
+            checkpoint_ns=checkpoint_ns,
+            checkpoint_id=checkpoint_id,
+            parent_checkpoint_id=parent_checkpoint_id,
+            metadata_blob=metadata_blob,
+            checkpoint_blob=checkpoint_blob,
+        )
+        return {
+            "configurable": {
+                "thread_id": thread_id,
+                "checkpoint_ns": checkpoint_ns,
+                "checkpoint_id": checkpoint_id,
+            }
+        }
+
+    def put_writes(
+        self,
+        config: RunnableConfig,
+        writes: Sequence[tuple[str, Any]],
+        task_id: str,
+        task_path: str = "",
+    ) -> None:
+        """No-op in v1.
+
+        TODO(writes): Persist pending writes for interrupt/resume.
+        """
+        del config, writes, task_id, task_path
+
+    def delete_thread(self, thread_id: str) -> None:
+        """Delete all snapshots for ``thread_id`` under this agent."""
+        self.client.delete_thread(thread_id=thread_id)
+
+    def get_next_version(
+        self,
+        current: str | int | None,
+        channel: None = None,
+    ) -> str:
+        """Generate the next monotonic channel version string."""
+        del channel
+        if current is None:
+            current_v = 0
+        elif isinstance(current, int):
+            current_v = current
+        else:
+            current_v = int(str(current).split(".")[0])
+        next_v = current_v + 1
+        next_h = random.random()
+        return f"{next_v:032}.{next_h:016}"
+
+    async def aget_tuple(self, config: RunnableConfig) -> CheckpointTuple | None:
+        thread_id, checkpoint_ns, checkpoint_id = _parse_config(config)
+        try:
+            if checkpoint_id:
+                snapshot = await self.client.aget_checkpoint(
+                    thread_id=thread_id,
+                    checkpoint_id=checkpoint_id,
+                    checkpoint_ns=checkpoint_ns,
+                )
+            else:
+                snapshot = await self.client.aget_latest(
+                    thread_id=thread_id,
+                    checkpoint_ns=checkpoint_ns,
+                )
+        except MemoryNotFoundError:
+            return None
+        return self._to_tuple(snapshot, thread_id=thread_id, checkpoint_ns=checkpoint_ns)
+
+    async def alist(
+        self,
+        config: RunnableConfig | None,
+        *,
+        filter: dict[str, Any] | None = None,
+        before: RunnableConfig | None = None,
+        limit: int | None = None,
+    ) -> AsyncIterator[CheckpointTuple]:
+        del filter
+        if config is None:
+            return
+        thread_id, checkpoint_ns, _ = _parse_config(config)
+        before_id = get_checkpoint_id(before) if before else None
+        snapshots = await self.client.alist_checkpoints(
+            thread_id=thread_id,
+            checkpoint_ns=checkpoint_ns,
+            before=before_id,
+            limit=limit,
+        )
+        for snapshot in snapshots:
+            yield self._to_tuple(
+                snapshot,
+                thread_id=thread_id,
+                checkpoint_ns=checkpoint_ns,
+            )
+
+    async def aput(
+        self,
+        config: RunnableConfig,
+        checkpoint: Checkpoint,
+        metadata: CheckpointMetadata,
+        new_versions: ChannelVersions,
+    ) -> RunnableConfig:
+        del new_versions
+        thread_id, checkpoint_ns, parent_checkpoint_id = _parse_config(config)
+        checkpoint_id = checkpoint["id"]
+        metadata_blob = self._snapshot_serde.dumps_blob(
+            dict(get_checkpoint_metadata(config, metadata))
+        )
+        checkpoint_blob = self._snapshot_serde.dumps_blob(dict(checkpoint))
+        await self.client.aput_checkpoint(
+            thread_id=thread_id,
+            checkpoint_ns=checkpoint_ns,
+            checkpoint_id=checkpoint_id,
+            parent_checkpoint_id=parent_checkpoint_id,
+            metadata_blob=metadata_blob,
+            checkpoint_blob=checkpoint_blob,
+        )
+        return {
+            "configurable": {
+                "thread_id": thread_id,
+                "checkpoint_ns": checkpoint_ns,
+                "checkpoint_id": checkpoint_id,
+            }
+        }
+
+    async def aput_writes(
+        self,
+        config: RunnableConfig,
+        writes: Sequence[tuple[str, Any]],
+        task_id: str,
+        task_path: str = "",
+    ) -> None:
+        """Async no-op; see ``put_writes``."""
+        del config, writes, task_id, task_path
+
+    async def adelete_thread(self, thread_id: str) -> None:
+        await self.client.adelete_thread(thread_id=thread_id)
+
+    def _to_tuple(
+        self,
+        snapshot: CheckpointSnapshot,
+        *,
+        thread_id: str,
+        checkpoint_ns: str,
+    ) -> CheckpointTuple:
+        checkpoint = self._snapshot_serde.loads_blob(snapshot.checkpoint_blob)
+        metadata = self._snapshot_serde.loads_blob(snapshot.metadata_blob)
+        parent_config = None
+        if snapshot.parent_checkpoint_id:
+            parent_config = {
+                "configurable": {
+                    "thread_id": thread_id,
+                    "checkpoint_ns": checkpoint_ns,
+                    "checkpoint_id": snapshot.parent_checkpoint_id,
+                }
+            }
+        return CheckpointTuple(
+            config={
+                "configurable": {
+                    "thread_id": thread_id,
+                    "checkpoint_ns": checkpoint_ns,
+                    "checkpoint_id": snapshot.checkpoint_id,
+                }
+            },
+            checkpoint=checkpoint,
+            metadata=metadata,
+            parent_config=parent_config,
+            pending_writes=[],
+        )
+
+
+def _parse_config(config: RunnableConfig) -> tuple[str, str, str | None]:
+    """Extract thread_id, checkpoint_ns, and optional checkpoint_id."""
+    configurable = config.get("configurable") or {}
+    thread_id = configurable.get("thread_id")
+    if not thread_id:
+        raise MemoryConfigurationError(
+            "RunnableConfig must contain configurable.thread_id"
+        )
+    checkpoint_ns = configurable.get("checkpoint_ns") or ""
+    checkpoint_id = configurable.get("checkpoint_id")
+    return str(thread_id), str(checkpoint_ns), (
+        str(checkpoint_id) if checkpoint_id else None
+    )

tikuu_memory-0.1.0/src/tikuu_memory/serde.py

@@ -0,0 +1,40 @@
+"""Serialize checkpoint and metadata values for opaque blob storage.
+
+Uses LangGraph's ``JsonPlusSerializer`` (typed base64 inside a small JSON
+envelope), matching the AgentCore checkpointer approach.
+
+TODO(serde): JsonPlus can embed pickle for some Python types. Prefer a
+JSON-only serializer later if agents only need standard LangGraph state.
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+from typing import Any
+
+from langgraph.checkpoint.serde.base import SerializerProtocol
+from langgraph.checkpoint.serde.jsonplus import JsonPlusSerializer
+
+
+class SnapshotSerde:
+    """Encode/decode checkpoint and metadata blobs for the memory service."""
+
+    def __init__(self, serde: SerializerProtocol | None = None) -> None:
+        self.serde = serde or JsonPlusSerializer()
+
+    def dumps_blob(self, value: Any) -> str:
+        """Serialize ``value`` to a JSON string for ``*_blob`` columns."""
+        type_tag, binary_data = self.serde.dumps_typed(value)
+        payload = {
+            "type": type_tag,
+            "data": base64.b64encode(binary_data).decode("utf-8"),
+        }
+        return json.dumps(payload)
+
+    def loads_blob(self, blob: str) -> Any:
+        """Deserialize a JSON blob string produced by ``dumps_blob``."""
+        payload = json.loads(blob)
+        type_tag = payload["type"]
+        binary_data = base64.b64decode(payload["data"])
+        return self.serde.loads_typed((type_tag, binary_data))