etchmem 0.1.5__tar.gz → 0.2.0__tar.gz

etchmem-0.2.0/PKG-INFO

@@ -0,0 +1,165 @@
+Metadata-Version: 2.4
+Name: etchmem
+Version: 0.2.0
+Summary: Python SDK for etchmem-server — the Knowledge Consolidation Engine for AI agents
+Author: Andrey Olishchuk
+License: MIT
+Project-URL: Repository, https://github.com/vossmoos/etchmem-sdk-python
+Keywords: llm,agent,memory,knowledge,consolidation,rag,sdk,rest,client,etchmem
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.27
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.24; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Dynamic: license-file
+
+# etchmem
+
+**Python SDK for [etchmem-server](https://github.com/vossmoos/etchmem-sdk-python) — the Knowledge Consolidation Engine for AI agents.**
+
+Your agents' daily activity is full of hard-won facts — deals signed, decisions made, preferences learned. etchmem-server turns that stream of raw signals into a clean, typed, versioned knowledge base: one consolidated belief per fact, with confidence, provenance, conflict status, and full version history — queryable at any point in time.
+
+This package is the REST client. One dependency (`httpx`), sync and async, fully typed responses.
+
+```bash
+pip install etchmem
+```
+
+> **Note on MCP:** etchmem-server also exposes an MCP interface at `/mcp` with the same operations as tools. MCP clients (Claude, agent frameworks, IDEs) connect to it directly over the MCP protocol — no SDK needed. This package is for REST integrations only.
+
+---
+
+## Quickstart
+
+Run the server (see the etchmem-server repo — `docker compose up`), then:
+
+```python
+from etchmem import EtchMem
+
+mem = EtchMem("http://localhost:8000")   # default; also reads ETCHMEM_BASE_URL
+
+# Deposit a raw signal — no pre-structuring needed
+mem.remember(
+    "Acme signed the Q3 renewal at $40k. Maria approved the discount.",
+    source="agent-33",
+    scope="sales",
+)
+
+# Semantic recall over consolidated beliefs
+for hit in mem.recall("what did Acme sign?", top_k=5):
+    print(f"[{hit.origin}] {hit.content}  (confidence={hit.confidence})")
+```
+
+### Async
+
+```python
+from etchmem import AsyncEtchMem
+
+async with AsyncEtchMem("http://localhost:8000") as mem:
+    await mem.remember("...", source="agent-33", scope="sales")
+    hits = await mem.recall("what did Acme sign?")
+```
+
+---
+
+## API surface
+
+The SDK mirrors the seven REST endpoints one-to-one:
+
+| Method | Endpoint | Returns |
+|---|---|---|
+| `remember(data, *, source, scope, extract_mode="deferred", metadata=None)` | `POST /remember` | `RememberResult` |
+| `recall(query, *, scope=None, source=None, top_k=5, include_signals=True, as_of=None)` | `POST /recall` | `RecallResponse` (iterable of `RecallResult`) |
+| `sleep()` | `POST /sleep` | `SleepResult` |
+| `export()` | `POST /export` | `ExportResult` (list of `Etch`) |
+| `history(etch_id)` | `GET /etch/{id}/history` | `History` (iterable of `EtchVersion`) |
+| `stats()` | `GET /stats` | `Stats` |
+| `health()` | `GET /health` | `Health` |
+
+All responses are plain dataclasses — see `etchmem/models.py`.
+
+### remember
+
+`extract_mode="immediate"` marks the signal urgent (claims extracted on the next worker tick); `"deferred"` (default) batches it cheaply. Deposits are idempotent — identical content returns `stored=False`.
+
+### recall with time-travel
+
+Pass `as_of` (ISO-8601) to recall what the system believed at that moment — for auditing decisions or incident forensics:
+
+```python
+hits = mem.recall("Acme contract value", as_of="2026-06-01T00:00:00Z")
+```
+
+### sleep
+
+The server consolidates on its own cadence. `mem.sleep()` forces one pipeline tick now (batch → extract claims → fold into etches) — useful in tests and demos:
+
+```python
+tick = mem.sleep()
+print(tick.etches_formed, tick.etches_updated, tick.contested)
+```
+
+### history
+
+Every belief change writes an immutable version snapshot:
+
+```python
+for v in mem.history(etch_id):
+    print(v.version, v.current_value, v.status, v.confidence)
+```
+
+---
+
+## Configuration
+
+| Parameter | Env var | Default |
+|---|---|---|
+| `base_url` | `ETCHMEM_BASE_URL` | `http://localhost:8000` |
+| `api_key` | `ETCHMEM_API_KEY` | none (sent as `Authorization: Bearer …` when set) |
+| `timeout` | — | 30 s |
+
+You can also inject your own `httpx.Client` / `httpx.AsyncClient` via the `client` parameter (custom TLS, proxies, retries).
+
+## Errors
+
+All SDK errors derive from `EtchMemError`:
+
+- `ConnectionError` — server unreachable (network / timeout)
+- `APIError` — non-2xx response (`.status_code`, `.detail`), with subclasses `NotFoundError` (404), `AuthenticationError` (401/403), `ServerError` (5xx)
+
+```python
+from etchmem import EtchMem, NotFoundError
+
+try:
+    mem.history("no-such-etch")
+except NotFoundError as e:
+    print(e.detail)
+```
+
+---
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+python -m pytest tests/
+```
+
+Releasing to PyPI: see [PIP-DEPLOY.md](PIP-DEPLOY.md).
+
+## License
+
+MIT

etchmem-0.2.0/README.md

@@ -0,0 +1,137 @@
+# etchmem
+
+**Python SDK for [etchmem-server](https://github.com/vossmoos/etchmem-sdk-python) — the Knowledge Consolidation Engine for AI agents.**
+
+Your agents' daily activity is full of hard-won facts — deals signed, decisions made, preferences learned. etchmem-server turns that stream of raw signals into a clean, typed, versioned knowledge base: one consolidated belief per fact, with confidence, provenance, conflict status, and full version history — queryable at any point in time.
+
+This package is the REST client. One dependency (`httpx`), sync and async, fully typed responses.
+
+```bash
+pip install etchmem
+```
+
+> **Note on MCP:** etchmem-server also exposes an MCP interface at `/mcp` with the same operations as tools. MCP clients (Claude, agent frameworks, IDEs) connect to it directly over the MCP protocol — no SDK needed. This package is for REST integrations only.
+
+---
+
+## Quickstart
+
+Run the server (see the etchmem-server repo — `docker compose up`), then:
+
+```python
+from etchmem import EtchMem
+
+mem = EtchMem("http://localhost:8000")   # default; also reads ETCHMEM_BASE_URL
+
+# Deposit a raw signal — no pre-structuring needed
+mem.remember(
+    "Acme signed the Q3 renewal at $40k. Maria approved the discount.",
+    source="agent-33",
+    scope="sales",
+)
+
+# Semantic recall over consolidated beliefs
+for hit in mem.recall("what did Acme sign?", top_k=5):
+    print(f"[{hit.origin}] {hit.content}  (confidence={hit.confidence})")
+```
+
+### Async
+
+```python
+from etchmem import AsyncEtchMem
+
+async with AsyncEtchMem("http://localhost:8000") as mem:
+    await mem.remember("...", source="agent-33", scope="sales")
+    hits = await mem.recall("what did Acme sign?")
+```
+
+---
+
+## API surface
+
+The SDK mirrors the seven REST endpoints one-to-one:
+
+| Method | Endpoint | Returns |
+|---|---|---|
+| `remember(data, *, source, scope, extract_mode="deferred", metadata=None)` | `POST /remember` | `RememberResult` |
+| `recall(query, *, scope=None, source=None, top_k=5, include_signals=True, as_of=None)` | `POST /recall` | `RecallResponse` (iterable of `RecallResult`) |
+| `sleep()` | `POST /sleep` | `SleepResult` |
+| `export()` | `POST /export` | `ExportResult` (list of `Etch`) |
+| `history(etch_id)` | `GET /etch/{id}/history` | `History` (iterable of `EtchVersion`) |
+| `stats()` | `GET /stats` | `Stats` |
+| `health()` | `GET /health` | `Health` |
+
+All responses are plain dataclasses — see `etchmem/models.py`.
+
+### remember
+
+`extract_mode="immediate"` marks the signal urgent (claims extracted on the next worker tick); `"deferred"` (default) batches it cheaply. Deposits are idempotent — identical content returns `stored=False`.
+
+### recall with time-travel
+
+Pass `as_of` (ISO-8601) to recall what the system believed at that moment — for auditing decisions or incident forensics:
+
+```python
+hits = mem.recall("Acme contract value", as_of="2026-06-01T00:00:00Z")
+```
+
+### sleep
+
+The server consolidates on its own cadence. `mem.sleep()` forces one pipeline tick now (batch → extract claims → fold into etches) — useful in tests and demos:
+
+```python
+tick = mem.sleep()
+print(tick.etches_formed, tick.etches_updated, tick.contested)
+```
+
+### history
+
+Every belief change writes an immutable version snapshot:
+
+```python
+for v in mem.history(etch_id):
+    print(v.version, v.current_value, v.status, v.confidence)
+```
+
+---
+
+## Configuration
+
+| Parameter | Env var | Default |
+|---|---|---|
+| `base_url` | `ETCHMEM_BASE_URL` | `http://localhost:8000` |
+| `api_key` | `ETCHMEM_API_KEY` | none (sent as `Authorization: Bearer …` when set) |
+| `timeout` | — | 30 s |
+
+You can also inject your own `httpx.Client` / `httpx.AsyncClient` via the `client` parameter (custom TLS, proxies, retries).
+
+## Errors
+
+All SDK errors derive from `EtchMemError`:
+
+- `ConnectionError` — server unreachable (network / timeout)
+- `APIError` — non-2xx response (`.status_code`, `.detail`), with subclasses `NotFoundError` (404), `AuthenticationError` (401/403), `ServerError` (5xx)
+
+```python
+from etchmem import EtchMem, NotFoundError
+
+try:
+    mem.history("no-such-etch")
+except NotFoundError as e:
+    print(e.detail)
+```
+
+---
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+python -m pytest tests/
+```
+
+Releasing to PyPI: see [PIP-DEPLOY.md](PIP-DEPLOY.md).
+
+## License
+
+MIT

etchmem-0.2.0/etchmem/__init__.py

@@ -0,0 +1,54 @@
+"""
+etchmem — Python SDK for the etchmem-server REST API.
+
+The Knowledge Consolidation Engine for AI agents: raw signals in,
+consolidated, versioned beliefs (etches) out.
+
+Public surface::
+
+    from etchmem import EtchMem, AsyncEtchMem
+
+    mem = EtchMem("http://localhost:8000")
+    mem.remember("Acme signed the Q3 renewal at $40k.",
+                 source="agent-33", scope="sales")
+    hits = mem.recall("what did Acme sign?")
+
+Note: the server also exposes an MCP interface at ``/mcp``. MCP clients
+connect to it directly with the MCP protocol — no SDK needed there. This
+package is for REST integrations.
+"""
+from etchmem.async_client import AsyncEtchMem
+from etchmem.client import EtchMem
+from etchmem.errors import (
+    APIError, AuthenticationError, ConnectionError, EtchMemError,
+    NotFoundError, ServerError,
+)
+from etchmem.models import (
+    Etch, EtchVersion, ExportResult, Health, History, RecallResponse,
+    RecallResult, RememberResult, SleepResult, Stats,
+)
+
+__all__ = [
+    "EtchMem",
+    "AsyncEtchMem",
+    # models
+    "RememberResult",
+    "RecallResponse",
+    "RecallResult",
+    "SleepResult",
+    "ExportResult",
+    "Etch",
+    "EtchVersion",
+    "History",
+    "Stats",
+    "Health",
+    # errors
+    "EtchMemError",
+    "APIError",
+    "ConnectionError",
+    "AuthenticationError",
+    "NotFoundError",
+    "ServerError",
+]
+
+__version__ = "0.2.0"

etchmem-0.2.0/etchmem/async_client.py

@@ -0,0 +1,132 @@
+"""Asynchronous client for the etchmem-server REST API."""
+from __future__ import annotations
+
+import os
+from typing import Any
+
+import httpx
+
+from etchmem.client import DEFAULT_BASE_URL, DEFAULT_TIMEOUT
+from etchmem.errors import ConnectionError, error_for_status
+from etchmem.models import (
+    ExportResult, Health, History, RecallResponse, RememberResult,
+    SleepResult, Stats,
+)
+
+
+class AsyncEtchMem:
+    """Asynchronous etchmem client (same surface as :class:`etchmem.EtchMem`).
+
+    Usage::
+
+        from etchmem import AsyncEtchMem
+
+        async with AsyncEtchMem("http://localhost:8000") as mem:
+            await mem.remember("Acme signed the Q3 renewal at $40k.",
+                               source="agent-33", scope="sales")
+            hits = await mem.recall("what did Acme sign?")
+
+    Configuration falls back to environment variables:
+    ``ETCHMEM_BASE_URL`` and ``ETCHMEM_API_KEY``.
+    """
+
+    def __init__(
+        self,
+        base_url: str | None = None,
+        *,
+        api_key: str | None = None,
+        timeout: float = DEFAULT_TIMEOUT,
+        client: httpx.AsyncClient | None = None,
+    ) -> None:
+        self.base_url = (base_url
+                         or os.environ.get("ETCHMEM_BASE_URL")
+                         or DEFAULT_BASE_URL).rstrip("/")
+        self.api_key = api_key or os.environ.get("ETCHMEM_API_KEY")
+        headers = {"Accept": "application/json"}
+        if self.api_key:
+            headers["Authorization"] = f"Bearer {self.api_key}"
+        self._client = client or httpx.AsyncClient(
+            base_url=self.base_url, timeout=timeout)
+        self._client.headers.update(headers)
+
+    # ── lifecycle ──────────────────────────────────────────────────────
+
+    async def close(self) -> None:
+        await self._client.aclose()
+
+    async def __aenter__(self) -> "AsyncEtchMem":
+        return self
+
+    async def __aexit__(self, *exc: Any) -> None:
+        await self.close()
+
+    # ── internal ───────────────────────────────────────────────────────
+
+    async def _request(self, method: str, path: str,
+                       json: dict[str, Any] | None = None) -> dict[str, Any]:
+        try:
+            resp = await self._client.request(method, path, json=json)
+        except httpx.HTTPError as e:
+            raise ConnectionError(
+                f"etchmem server unreachable at {self.base_url}: {e}") from e
+        if resp.status_code >= 400:
+            try:
+                detail = resp.json().get("detail", resp.text)
+            except Exception:
+                detail = resp.text
+            raise error_for_status(resp.status_code, detail)
+        return resp.json()
+
+    # ── API surface ────────────────────────────────────────────────────
+
+    async def remember(
+        self,
+        data: str,
+        *,
+        source: str,
+        scope: str,
+        extract_mode: str = "deferred",
+        metadata: dict[str, Any] | None = None,
+    ) -> RememberResult:
+        """Deposit a raw text signal (see :meth:`etchmem.EtchMem.remember`)."""
+        payload = await self._request("POST", "/remember", json={
+            "data": data, "source": source, "scope": scope,
+            "extract_mode": extract_mode, "metadata": metadata or {}})
+        return RememberResult.from_dict(payload)
+
+    async def recall(
+        self,
+        query: str,
+        *,
+        scope: str | None = None,
+        source: str | None = None,
+        top_k: int = 5,
+        include_signals: bool = True,
+        as_of: str | None = None,
+    ) -> RecallResponse:
+        """Semantic recall over etches; ``as_of`` enables time-travel."""
+        payload = await self._request("POST", "/recall", json={
+            "query": query, "scope": scope, "source": source, "top_k": top_k,
+            "include_signals": include_signals, "as_of": as_of})
+        return RecallResponse.from_dict(payload)
+
+    async def sleep(self) -> SleepResult:
+        """Run one consolidation tick now (batch → extract → fold)."""
+        return SleepResult.from_dict(await self._request("POST", "/sleep"))
+
+    async def export(self) -> ExportResult:
+        """Dump all etches to JSON files on the server; returns them too."""
+        return ExportResult.from_dict(await self._request("POST", "/export"))
+
+    async def history(self, etch_id: str) -> History:
+        """Version timeline of one etch (immutable snapshots)."""
+        return History.from_dict(
+            await self._request("GET", f"/etch/{etch_id}/history"))
+
+    async def stats(self) -> Stats:
+        """Queue depths and store counts."""
+        return Stats.from_dict(await self._request("GET", "/stats"))
+
+    async def health(self) -> Health:
+        """Liveness probe plus active server configuration."""
+        return Health.from_dict(await self._request("GET", "/health"))

etchmem-0.2.0/etchmem/client.py

@@ -0,0 +1,150 @@
+"""Synchronous client for the etchmem-server REST API."""
+from __future__ import annotations
+
+import os
+from typing import Any
+
+import httpx
+
+from etchmem.errors import ConnectionError, error_for_status
+from etchmem.models import (
+    ExportResult, Health, History, RecallResponse, RememberResult,
+    SleepResult, Stats,
+)
+
+DEFAULT_BASE_URL = "http://localhost:8000"
+DEFAULT_TIMEOUT = 30.0
+
+
+class EtchMem:
+    """Synchronous etchmem client.
+
+    Usage::
+
+        from etchmem import EtchMem
+
+        mem = EtchMem("http://localhost:8000")
+        mem.remember("Acme signed the Q3 renewal at $40k.",
+                     source="agent-33", scope="sales")
+        for hit in mem.recall("what did Acme sign?"):
+            print(hit.content, hit.confidence)
+
+    Can be used as a context manager to close the underlying HTTP
+    connection pool deterministically::
+
+        with EtchMem() as mem:
+            mem.remember(...)
+
+    Configuration falls back to environment variables:
+    ``ETCHMEM_BASE_URL`` and ``ETCHMEM_API_KEY``.
+    """
+
+    def __init__(
+        self,
+        base_url: str | None = None,
+        *,
+        api_key: str | None = None,
+        timeout: float = DEFAULT_TIMEOUT,
+        client: httpx.Client | None = None,
+    ) -> None:
+        self.base_url = (base_url
+                         or os.environ.get("ETCHMEM_BASE_URL")
+                         or DEFAULT_BASE_URL).rstrip("/")
+        self.api_key = api_key or os.environ.get("ETCHMEM_API_KEY")
+        headers = {"Accept": "application/json"}
+        if self.api_key:
+            headers["Authorization"] = f"Bearer {self.api_key}"
+        self._client = client or httpx.Client(
+            base_url=self.base_url, timeout=timeout)
+        self._client.headers.update(headers)
+
+    # ── lifecycle ──────────────────────────────────────────────────────
+
+    def close(self) -> None:
+        self._client.close()
+
+    def __enter__(self) -> "EtchMem":
+        return self
+
+    def __exit__(self, *exc: Any) -> None:
+        self.close()
+
+    # ── internal ───────────────────────────────────────────────────────
+
+    def _request(self, method: str, path: str,
+                 json: dict[str, Any] | None = None) -> dict[str, Any]:
+        try:
+            resp = self._client.request(method, path, json=json)
+        except httpx.HTTPError as e:
+            raise ConnectionError(
+                f"etchmem server unreachable at {self.base_url}: {e}") from e
+        if resp.status_code >= 400:
+            try:
+                detail = resp.json().get("detail", resp.text)
+            except Exception:
+                detail = resp.text
+            raise error_for_status(resp.status_code, detail)
+        return resp.json()
+
+    # ── API surface ────────────────────────────────────────────────────
+
+    def remember(
+        self,
+        data: str,
+        *,
+        source: str,
+        scope: str,
+        extract_mode: str = "deferred",
+        metadata: dict[str, Any] | None = None,
+    ) -> RememberResult:
+        """Deposit a raw text signal.
+
+        ``extract_mode='immediate'`` marks the signal urgent (extracted on
+        the next worker tick); ``'deferred'`` (default) batches it cheaply.
+        Idempotent: re-depositing identical content returns ``stored=False``.
+        """
+        payload = self._request("POST", "/remember", json={
+            "data": data, "source": source, "scope": scope,
+            "extract_mode": extract_mode, "metadata": metadata or {}})
+        return RememberResult.from_dict(payload)
+
+    def recall(
+        self,
+        query: str,
+        *,
+        scope: str | None = None,
+        source: str | None = None,
+        top_k: int = 5,
+        include_signals: bool = True,
+        as_of: str | None = None,
+    ) -> RecallResponse:
+        """Semantic recall over consolidated etches (plus fresh raw signals).
+
+        Pass ``as_of`` (ISO-8601) for time-travel recall: results reflect
+        what the system believed at that ingest time.
+        """
+        payload = self._request("POST", "/recall", json={
+            "query": query, "scope": scope, "source": source, "top_k": top_k,
+            "include_signals": include_signals, "as_of": as_of})
+        return RecallResponse.from_dict(payload)
+
+    def sleep(self) -> SleepResult:
+        """Run one consolidation tick now (batch → extract → fold)."""
+        return SleepResult.from_dict(self._request("POST", "/sleep"))
+
+    def export(self) -> ExportResult:
+        """Dump all etches to JSON files on the server; returns them too."""
+        return ExportResult.from_dict(self._request("POST", "/export"))
+
+    def history(self, etch_id: str) -> History:
+        """Version timeline of one etch (immutable snapshots)."""
+        return History.from_dict(
+            self._request("GET", f"/etch/{etch_id}/history"))
+
+    def stats(self) -> Stats:
+        """Queue depths and store counts."""
+        return Stats.from_dict(self._request("GET", "/stats"))
+
+    def health(self) -> Health:
+        """Liveness probe plus active server configuration."""
+        return Health.from_dict(self._request("GET", "/health"))

etchmem-0.2.0/etchmem/errors.py

@@ -0,0 +1,44 @@
+"""Exception hierarchy for the etchmem SDK."""
+from __future__ import annotations
+
+from typing import Any
+
+
+class EtchMemError(Exception):
+    """Base class for all etchmem SDK errors."""
+
+
+class ConnectionError(EtchMemError):
+    """The server could not be reached (network error, timeout, DNS)."""
+
+
+class APIError(EtchMemError):
+    """The server returned a non-2xx HTTP status."""
+
+    def __init__(self, status_code: int, detail: Any = None) -> None:
+        self.status_code = status_code
+        self.detail = detail
+        super().__init__(f"HTTP {status_code}: {detail}")
+
+
+class NotFoundError(APIError):
+    """404 — resource (e.g. etch id) does not exist."""
+
+
+class AuthenticationError(APIError):
+    """401 / 403 — missing or invalid API key."""
+
+
+class ServerError(APIError):
+    """5xx — the server failed to process the request."""
+
+
+def error_for_status(status_code: int, detail: Any) -> APIError:
+    """Map an HTTP status code to the most specific APIError subclass."""
+    if status_code == 404:
+        return NotFoundError(status_code, detail)
+    if status_code in (401, 403):
+        return AuthenticationError(status_code, detail)
+    if status_code >= 500:
+        return ServerError(status_code, detail)
+    return APIError(status_code, detail)