pcmi 1.51.0__tar.gz

pcmi-1.51.0/.gitignore

@@ -0,0 +1,86 @@
+# ====================== ENVIRONMENT & SECRETS ======================
+.env
+.env.local
+.env.*.local
+.env.pcmi-test-backup
+.env.pre-manual-tests
+.env.bak
+!.env.example
+
+# ====================== GO BUILD & RUNTIME ======================
+*.exe
+*.exe~
+*.dll
+*.so
+*.dylib
+*.test
+*.out
+
+# Compiled service binaries (local `go build` / smoke scripts; CI builds fresh to bin/ or in Docker)
+bin/
+/api
+/worker
+/pcmi-api
+/pcmi-worker
+
+# Dependency directories
+vendor/
+
+# Go workspace
+go.work
+go.work.sum
+
+# ====================== DOCKER & CONTAINERS ======================
+docker-compose.override.yml
+*.log
+**/.dockerignore
+
+# Volumes (non committare dati locali)
+postgres_data/
+pcmi_postgres_data/
+
+# ====================== IDE & EDITOR ======================
+# VS Code: commit shared workspace defaults; keep personal/debug configs local.
+.vscode/*
+!.vscode/settings.json
+!.vscode/extensions.json
+.idea/
+*.swp
+*.swo
+.DS_Store
+Thumbs.db
+
+# ====================== LOGS & TEMP ======================
+*.log
+logs/
+tmp/
+temp/
+
+# ====================== TEST & COVERAGE ======================
+coverage.out
+coverage.html
+coverage-summary.md
+coverage-summary.txt
+coverage-badge.txt
+
+# ====================== PCMI SPECIFIC ======================
+# Distillation e2e test artifacts (local only)
+.venv_e2e/
+.pcmi_test_out/
+
+# Smoke script venv (local only)
+examples/temporal/.venv_smoke/
+examples/celery/.venv_smoke/
+examples/langchain/.venv/
+examples/llamaindex/.venv/
+examples/autogen/.venv/
+examples/crewai/.venv/
+sdk/python/.venv/
+sdk/python/pcmi.egg-info/
+sdk/typescript/node_modules/
+scripts/e2e/node_modules/
+sdk/typescript/dist/
+__pycache__/
+*.py[cod]
+.cursorignore
+.claude/

pcmi-1.51.0/PKG-INFO

@@ -0,0 +1,69 @@
+Metadata-Version: 2.4
+Name: pcmi
+Version: 1.51.0
+Summary: PCMI Python SDK — async HTTP client for the Persistent Cognitive Memory Infrastructure API
+Project-URL: Homepage, https://github.com/marco-spagn/pcmi
+Project-URL: Repository, https://github.com/marco-spagn/pcmi
+Project-URL: Documentation, https://github.com/marco-spagn/pcmi/tree/main/sdk/python
+Author: Marco Spagnuolo
+License: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2
+Description-Content-Type: text/markdown
+
+# PCMI Python SDK
+
+Async **HTTP** client for [PCMI](https://github.com/marco-spagn/pcmi). For high-throughput store/retrieve, use gRPC or REST directly.
+
+## Requirements
+
+- Python 3.10+
+
+## Install
+
+The `pcmi` package is published to PyPI on each GitHub Release. Until the first publish:
+
+```bash
+pip install -e .                                    # from this directory
+pip install "git+https://github.com/marco-spagn/pcmi.git#subdirectory=sdk/python"
+```
+
+After publish:
+
+```bash
+pip install pcmi
+```
+
+## Quick start
+
+```bash
+export PCMI_BASE_URL=http://localhost:8000 PCMI_API_KEY=testkey123
+python smoke.py
+```
+
+```python
+import asyncio
+from pcmi import PCMIClient
+
+async def main() -> None:
+    async with PCMIClient("http://localhost:8000", "your-api-key") as client:
+        await client.store("user.note", "hello", tags=["demo"])
+        result = await client.retrieve("user.note", tags=["demo"])
+        print(result)
+
+asyncio.run(main())
+```
+
+## Documentation
+
+- [SDK overview](../README.md)
+- [HTTP API](../HTTP-API.md)

pcmi-1.51.0/README.md

@@ -0,0 +1,47 @@
+# PCMI Python SDK
+
+Async **HTTP** client for [PCMI](https://github.com/marco-spagn/pcmi). For high-throughput store/retrieve, use gRPC or REST directly.
+
+## Requirements
+
+- Python 3.10+
+
+## Install
+
+The `pcmi` package is published to PyPI on each GitHub Release. Until the first publish:
+
+```bash
+pip install -e .                                    # from this directory
+pip install "git+https://github.com/marco-spagn/pcmi.git#subdirectory=sdk/python"
+```
+
+After publish:
+
+```bash
+pip install pcmi
+```
+
+## Quick start
+
+```bash
+export PCMI_BASE_URL=http://localhost:8000 PCMI_API_KEY=testkey123
+python smoke.py
+```
+
+```python
+import asyncio
+from pcmi import PCMIClient
+
+async def main() -> None:
+    async with PCMIClient("http://localhost:8000", "your-api-key") as client:
+        await client.store("user.note", "hello", tags=["demo"])
+        result = await client.retrieve("user.note", tags=["demo"])
+        print(result)
+
+asyncio.run(main())
+```
+
+## Documentation
+
+- [SDK overview](../README.md)
+- [HTTP API](../HTTP-API.md)

pcmi-1.51.0/admin_smoke.py

@@ -0,0 +1,21 @@
+#!/usr/bin/env python3
+"""Admin SDK smoke (read-only). Requires admin API key (testkey123 in default migrations)."""
+import asyncio
+import os
+
+from pcmi import PCMIClient
+
+
+async def main() -> None:
+    base = os.environ.get("PCMI_BASE_URL", "http://localhost:8000")
+    key = os.environ.get("PCMI_API_KEY", "testkey123")
+
+    async with PCMIClient(base, key) as c:
+        tenants = await c.list_tenants(limit=5)
+        print("tenants total:", tenants.get("total", 0))
+        keys = await c.list_api_keys(limit=5)
+        print("api_keys total:", keys.get("total", 0))
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

pcmi-1.51.0/pcmi/__init__.py

@@ -0,0 +1,4 @@
+from .client import PCMIClient
+from .webhook import verify_signature
+
+__all__ = ["PCMIClient", "verify_signature"]

pcmi-1.51.0/pcmi/client.py

@@ -0,0 +1,434 @@
+import json
+from collections.abc import AsyncIterator
+from typing import Any
+
+import httpx
+
+from .models import MemoryStore, MemoryRetrieve, MemoryRollback, IngestEvent, CompactMemory
+
+
+class PCMIClient:
+    def __init__(self, base_url: str, api_key: str):
+        self.base_url = base_url.rstrip("/")
+        self.api_key = api_key
+        self.client = httpx.AsyncClient(
+            base_url=self.base_url,
+            headers={"X-API-Key": api_key, "Content-Type": "application/json"},
+        )
+
+    async def __aenter__(self):
+        return self
+
+    async def __aexit__(self, *_args):
+        await self.close()
+
+    async def close(self):
+        await self.client.aclose()
+
+    async def store(
+        self,
+        path: str,
+        content: str,
+        metadata: dict | None = None,
+        *,
+        tags: list[str] | None = None,
+        embedding_model: str | None = None,
+        embedding_space: str | None = None,
+        embedding: list[float] | None = None,
+        source_agent_id: str | None = None,
+        encrypt_content: bool | None = None,
+        expires_at: str | None = None,
+    ):
+        payload = MemoryStore(
+            path=path,
+            content=content,
+            metadata=metadata or {},
+            tags=tags,
+            embedding_model=embedding_model,
+            embedding_space=embedding_space,
+            embedding=embedding,
+            source_agent_id=source_agent_id,
+            encrypt_content=encrypt_content,
+            expires_at=expires_at,
+        )
+        resp = await self.client.post("/v1/memories", json=payload.model_dump(exclude_none=True))
+        resp.raise_for_status()
+        return resp.json()
+
+    async def retrieve(
+        self,
+        path_prefix: str,
+        query: str = "",
+        limit: int = 10,
+        *,
+        as_of: str | None = None,
+        source_agent_id: str | None = None,
+        embedding_space: str | None = None,
+        tags: list[str] | None = None,
+        tags_match: str | None = None,
+    ):
+        payload = MemoryRetrieve(
+            path_prefix=path_prefix,
+            query=query,
+            limit=limit,
+            as_of=as_of,
+            source_agent_id=source_agent_id,
+            embedding_space=embedding_space,
+            tags=tags,
+            tags_match=tags_match,
+        )
+        resp = await self.client.post("/v1/retrieve", json=payload.model_dump(exclude_none=True))
+        resp.raise_for_status()
+        return resp.json()
+
+    async def rollback(
+        self,
+        path: str,
+        *,
+        version: int | None = None,
+        as_of: str | None = None,
+    ):
+        payload = MemoryRollback(path=path, version=version, as_of=as_of)
+        resp = await self.client.post(
+            "/v1/memories/rollback", json=payload.model_dump(exclude_none=True)
+        )
+        resp.raise_for_status()
+        return resp.json()
+
+    async def ingest_event(
+        self,
+        event_type: str,
+        payload: dict | None = None,
+        *,
+        agent_id: str | None = None,
+        correlation_id: str | None = None,
+    ):
+        body = IngestEvent(
+            event_type=event_type,
+            agent_id=agent_id,
+            correlation_id=correlation_id,
+            payload=payload or {},
+        )
+        resp = await self.client.post("/v1/events", json=body.model_dump(exclude_none=True))
+        resp.raise_for_status()
+        return resp.json()
+
+    async def get_memory(self, path: str, *, version: int | None = None, as_of: str | None = None):
+        params: dict[str, str | int] = {}
+        if version is not None:
+            params["version"] = version
+        if as_of:
+            params["as_of"] = as_of
+        resp = await self.client.get(f"/v1/memories/{path}", params=params)
+        resp.raise_for_status()
+        return resp.json()
+
+    async def batch_store(self, items: list[dict]):
+        resp = await self.client.post("/v1/memories/batch", json={"items": items})
+        resp.raise_for_status()
+        return resp.json()
+
+    async def batch_retrieve(self, queries: list[dict]):
+        resp = await self.client.post("/v1/retrieve/batch", json={"queries": queries})
+        resp.raise_for_status()
+        return resp.json()
+
+    async def export_memories(self, path_prefix: str, limit: int = 500, include_embeddings: bool = False):
+        resp = await self.client.post(
+            "/v1/memories/export",
+            json={"path_prefix": path_prefix, "limit": limit, "include_embeddings": include_embeddings},
+        )
+        resp.raise_for_status()
+        return resp.json()
+
+    async def import_memories(self, entries: list[dict], mode: str = "skip"):
+        resp = await self.client.post("/v1/memories/import", json={"entries": entries, "mode": mode})
+        resp.raise_for_status()
+        return resp.json()
+
+    async def list_tenants(self, limit: int = 100):
+        resp = await self.client.get("/v1/admin/tenants", params={"limit": limit})
+        resp.raise_for_status()
+        return resp.json()
+
+    async def create_tenant(self, slug: str, name: str, settings: dict | None = None):
+        resp = await self.client.post(
+            "/v1/admin/tenants",
+            json={"slug": slug, "name": name, "settings": settings or {}},
+        )
+        resp.raise_for_status()
+        return resp.json()
+
+    async def list_api_keys(self, *, tenant_id: str | None = None, limit: int = 50):
+        params: dict[str, str | int] = {"limit": limit}
+        if tenant_id:
+            params["tenant_id"] = tenant_id
+        resp = await self.client.get("/v1/admin/api-keys", params=params)
+        resp.raise_for_status()
+        return resp.json()
+
+    async def create_api_key(
+        self,
+        name: str,
+        *,
+        tenant_id: str | None = None,
+        role: str = "user",
+        expires_at: str | None = None,
+    ):
+        body: dict = {"name": name, "role": role}
+        if tenant_id:
+            body["tenant_id"] = tenant_id
+        if expires_at:
+            body["expires_at"] = expires_at
+        resp = await self.client.post("/v1/admin/api-keys", json=body)
+        resp.raise_for_status()
+        return resp.json()
+
+    async def rotate_api_key(self, key_id: str, name: str = ""):
+        resp = await self.client.post(
+            f"/v1/admin/api-keys/{key_id}/rotate",
+            json={"name": name},
+        )
+        resp.raise_for_status()
+        return resp.json()
+
+    async def get_history(self, path: str, limit: int = 50):
+        resp = await self.client.get(
+            "/v1/memories/history",
+            params={"path": path, "limit": limit},
+        )
+        resp.raise_for_status()
+        return resp.json()
+
+    async def list_audit(self, limit: int = 50, offset: int = 0, since: str | None = None):
+        params: dict[str, str | int] = {"limit": limit, "offset": offset}
+        if since:
+            params["since"] = since
+        resp = await self.client.get("/v1/audit", params=params)
+        resp.raise_for_status()
+        return resp.json()
+
+    async def list_event_schemas(self):
+        resp = await self.client.get("/v1/events/schemas")
+        resp.raise_for_status()
+        return resp.json()
+
+    async def summarize(self, path_prefix: str, limit: int = 20, style: str = "brief"):
+        resp = await self.client.post(
+            "/v1/memories/summarize",
+            json={"path_prefix": path_prefix, "limit": limit, "style": style},
+        )
+        resp.raise_for_status()
+        return resp.json()
+
+    async def list_webhook_dead_letter(self, limit: int = 50):
+        resp = await self.client.get("/v1/webhooks/dead-letter", params={"limit": limit})
+        resp.raise_for_status()
+        return resp.json()
+
+    async def list_distilled(self, path_prefix: str, limit: int = 50):
+        resp = await self.client.get(
+            "/v1/distilled",
+            params={"path_prefix": path_prefix, "limit": limit},
+        )
+        resp.raise_for_status()
+        return resp.json()
+
+    async def compact(self, path: str, *, keep_superseded: int = 20):
+        payload = CompactMemory(path=path, keep_superseded=keep_superseded)
+        resp = await self.client.post(
+            "/v1/memories/compact", json=payload.model_dump(exclude_none=True)
+        )
+        resp.raise_for_status()
+        return resp.json()
+
+    async def register_webhook(
+        self,
+        url: str,
+        *,
+        event_types: list[str] | None = None,
+        secret: str = "",
+    ):
+        resp = await self.client.post(
+            "/v1/webhooks",
+            json={"url": url, "event_types": event_types or [], "secret": secret},
+        )
+        resp.raise_for_status()
+        return resp.json()
+
+    async def list_webhooks(self, limit: int = 50):
+        resp = await self.client.get("/v1/webhooks", params={"limit": limit})
+        resp.raise_for_status()
+        return resp.json()
+
+    async def migrate_embeddings(
+        self,
+        path_prefix: str,
+        *,
+        target_model: str = "",
+        embedding_space: str | None = None,
+    ):
+        body: dict[str, Any] = {"path_prefix": path_prefix, "target_model": target_model}
+        if embedding_space:
+            body["embedding_space"] = embedding_space
+        resp = await self.client.post("/v1/embeddings/migrate", json=body)
+        resp.raise_for_status()
+        return resp.json()
+
+    async def refine(self, path_prefix: str) -> dict:
+        """Queue asynchronous distillation for a path prefix (worker consumes Redis event)."""
+        resp = await self.client.post(
+            "/v1/memories/refine",
+            json={"path_prefix": path_prefix},
+        )
+        resp.raise_for_status()
+        return resp.json()
+
+    async def memory_lineage(self, path: str):
+        resp = await self.client.get("/v1/lineage/memory", params={"path": path})
+        resp.raise_for_status()
+        return resp.json()
+
+    async def distilled_lineage(self, distilled_id: int):
+        resp = await self.client.get(f"/v1/lineage/distilled/{distilled_id}")
+        resp.raise_for_status()
+        return resp.json()
+
+    async def create_link(
+        self,
+        from_path: str,
+        to_path: str,
+        *,
+        link_type: str = "related",
+        metadata: dict | None = None,
+    ):
+        resp = await self.client.post(
+            "/v1/memories/links",
+            json={
+                "from_path": from_path,
+                "to_path": to_path,
+                "link_type": link_type,
+                "metadata": metadata or {},
+            },
+        )
+        resp.raise_for_status()
+        return resp.json()
+
+    async def list_links(self, **params):
+        resp = await self.client.get("/v1/memories/links", params=params)
+        resp.raise_for_status()
+        return resp.json()
+
+    async def tenant_stats(self):
+        resp = await self.client.get("/v1/stats")
+        resp.raise_for_status()
+        return resp.json()
+
+    async def subscribe(
+        self,
+        *,
+        types: list[str] | None = None,
+    ) -> AsyncIterator[dict[str, Any]]:
+        """Stream events from GET /v1/events (SSE). Yields `{type, payload}` objects."""
+        params: dict[str, str] = {}
+        if types:
+            params["types"] = ",".join(types)
+        async with httpx.AsyncClient(
+            base_url=self.base_url,
+            headers={"X-API-Key": self.api_key, "Accept": "text/event-stream"},
+            timeout=None,
+        ) as stream_client:
+            async with stream_client.stream("GET", "/v1/events", params=params) as resp:
+                resp.raise_for_status()
+                buffer = ""
+                async for chunk in resp.aiter_text():
+                    buffer += chunk
+                    while "\n\n" in buffer:
+                        block, buffer = buffer.split("\n\n", 1)
+                        data = ""
+                        for line in block.split("\n"):
+                            if line.startswith("data:"):
+                                data += line[5:].lstrip()
+                        if not data:
+                            continue
+                        yield json.loads(data)
+
+    # ── Session API ─────────────────────────────────────────────────────────
+    # FIX-9: Sessions were missing from the Python SDK. The Go and TypeScript
+    # SDKs both expose session lifecycle (create / end / store / list / promote).
+    # Python agents using sessions had to fall back to raw HTTP calls.
+
+    async def create_session(
+        self,
+        agent_id: str | None = None,
+        metadata: dict | None = None,
+    ) -> dict:
+        """Start a new agent session (POST /v1/sessions)."""
+        body: dict = {}
+        if agent_id:
+            body["agent_id"] = agent_id
+        if metadata:
+            body["metadata"] = metadata
+        resp = await self.client.post("/v1/sessions", json=body)
+        resp.raise_for_status()
+        return resp.json()
+
+    async def end_session(self, session_id: str) -> dict:
+        """End an agent session (DELETE /v1/sessions/{id})."""
+        resp = await self.client.delete(f"/v1/sessions/{session_id}")
+        resp.raise_for_status()
+        return resp.json()
+
+    async def store_session_memory(
+        self,
+        session_id: str,
+        path: str,
+        content: str,
+        metadata: dict | None = None,
+        tags: list[str] | None = None,
+    ) -> None:
+        """Store working memory scoped to a session."""
+        body: dict = {"path": path, "content": content}
+        if metadata:
+            body["metadata"] = metadata
+        if tags:
+            body["tags"] = tags
+        resp = await self.client.post(
+            f"/v1/sessions/{session_id}/memories", json=body
+        )
+        resp.raise_for_status()
+
+    async def list_session_memories(
+        self,
+        session_id: str,
+        *,
+        limit: int = 50,
+        path_prefix: str | None = None,
+        include_long_term: bool = False,
+    ) -> dict:
+        """List working-memory entries for a session."""
+        params: dict = {"limit": limit}
+        if path_prefix:
+            params["path_prefix"] = path_prefix
+        if include_long_term:
+            params["include_long_term"] = "true"
+        resp = await self.client.get(
+            f"/v1/sessions/{session_id}/memories", params=params
+        )
+        resp.raise_for_status()
+        return resp.json()
+
+    async def promote_session(
+        self,
+        session_id: str,
+        target_prefix: str | None = None,
+    ) -> dict:
+        """Promote working memory to long-term paths."""
+        body: dict = {}
+        if target_prefix:
+            body["target_prefix"] = target_prefix
+        resp = await self.client.post(
+            f"/v1/sessions/{session_id}/promote", json=body
+        )
+        resp.raise_for_status()
+        return resp.json()

pcmi-1.51.0/pcmi/models.py

@@ -0,0 +1,44 @@
+from pydantic import BaseModel, Field
+from typing import Any
+
+
+class MemoryStore(BaseModel):
+    path: str
+    content: str
+    metadata: dict[str, Any] = Field(default_factory=dict)
+    tags: list[str] | None = None
+    embedding_model: str | None = None
+    embedding_space: str | None = None
+    embedding: list[float] | None = None
+    source_agent_id: str | None = None
+    encrypt_content: bool | None = None
+    expires_at: str | None = None
+
+
+class MemoryRetrieve(BaseModel):
+    path_prefix: str = ""
+    query: str = ""
+    limit: int = 10
+    as_of: str | None = None
+    source_agent_id: str | None = None
+    embedding_space: str | None = None
+    tags: list[str] | None = None
+    tags_match: str | None = None
+
+
+class CompactMemory(BaseModel):
+    path: str
+    keep_superseded: int = 20
+
+
+class IngestEvent(BaseModel):
+    event_type: str
+    agent_id: str | None = None
+    correlation_id: str | None = None
+    payload: dict[str, Any] = Field(default_factory=dict)
+
+
+class MemoryRollback(BaseModel):
+    path: str
+    version: int | None = None
+    as_of: str | None = None

pcmi-1.51.0/pcmi/test_sessions.py

@@ -0,0 +1,86 @@
+"""Tests for FIX-9: session methods in Python SDK.
+Run with: pytest sdk/python/pcmi/test_sessions.py
+"""
+from unittest.mock import AsyncMock, MagicMock, patch
+import pytest
+from .client import PCMIClient
+
+
+@pytest.fixture
+def mock_client():
+    client = PCMIClient(base_url="http://localhost:8000", api_key="test-key")
+    client.client = MagicMock()
+    return client
+
+
+@pytest.mark.asyncio
+async def test_create_session_posts_to_sessions(mock_client):
+    mock_resp = MagicMock()
+    mock_resp.raise_for_status = MagicMock()
+    mock_resp.json.return_value = {"id": "sess-123", "status": "active"}
+    mock_client.client.post = AsyncMock(return_value=mock_resp)
+
+    result = await mock_client.create_session(agent_id="agent-1",
+                                               metadata={"k": "v"})
+    mock_client.client.post.assert_called_once_with(
+        "/v1/sessions", json={"agent_id": "agent-1", "metadata": {"k": "v"}}
+    )
+    assert result["id"] == "sess-123"
+
+
+@pytest.mark.asyncio
+async def test_end_session_deletes_session(mock_client):
+    mock_resp = MagicMock()
+    mock_resp.raise_for_status = MagicMock()
+    mock_resp.json.return_value = {"id": "sess-123", "status": "ended"}
+    mock_client.client.delete = AsyncMock(return_value=mock_resp)
+
+    result = await mock_client.end_session("sess-123")
+    mock_client.client.delete.assert_called_once_with("/v1/sessions/sess-123")
+    assert result["status"] == "ended"
+
+
+@pytest.mark.asyncio
+async def test_store_session_memory(mock_client):
+    mock_resp = MagicMock()
+    mock_resp.raise_for_status = MagicMock()
+    mock_client.client.post = AsyncMock(return_value=mock_resp)
+
+    await mock_client.store_session_memory(
+        "sess-123", "root.test", "content", tags=["a"]
+    )
+    mock_client.client.post.assert_called_once_with(
+        "/v1/sessions/sess-123/memories",
+        json={"path": "root.test", "content": "content", "tags": ["a"]},
+    )
+
+
+@pytest.mark.asyncio
+async def test_list_session_memories(mock_client):
+    mock_resp = MagicMock()
+    mock_resp.raise_for_status = MagicMock()
+    mock_resp.json.return_value = {"entries": [], "total": 0}
+    mock_client.client.get = AsyncMock(return_value=mock_resp)
+
+    await mock_client.list_session_memories("sess-123", limit=10,
+                                             path_prefix="root.test")
+    mock_client.client.get.assert_called_once_with(
+        "/v1/sessions/sess-123/memories",
+        params={"limit": 10, "path_prefix": "root.test"},
+    )
+
+
+@pytest.mark.asyncio
+async def test_promote_session(mock_client):
+    mock_resp = MagicMock()
+    mock_resp.raise_for_status = MagicMock()
+    mock_resp.json.return_value = {"promoted": 3}
+    mock_client.client.post = AsyncMock(return_value=mock_resp)
+
+    result = await mock_client.promote_session("sess-123",
+                                                target_prefix="root.agent")
+    mock_client.client.post.assert_called_once_with(
+        "/v1/sessions/sess-123/promote",
+        json={"target_prefix": "root.agent"},
+    )
+    assert result["promoted"] == 3

pcmi-1.51.0/pcmi/webhook.py

@@ -0,0 +1,52 @@
+"""Webhook signature verification for PCMI HTTP deliveries."""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import time
+from typing import Union
+
+DEFAULT_MAX_AGE_SECS = 300
+CLOCK_SKEW_SECS = 60
+
+
+def verify_signature(
+    secret: str,
+    signature: str,
+    timestamp: str,
+    body: bytes,
+    *,
+    now: float | None = None,
+    max_age_secs: int = DEFAULT_MAX_AGE_SECS,
+) -> bool:
+    """Verify X-PCMI-Signature for a webhook POST body.
+
+    Signature format: sha256={hex(HMAC-SHA256(secret, timestamp + "." + body))}
+    """
+    if not secret or not signature or not timestamp:
+        return False
+    if not signature.startswith("sha256="):
+        return False
+    try:
+        ts = int(timestamp)
+    except ValueError:
+        return False
+    now_ts = time.time() if now is None else now
+    age = now_ts - ts
+    if age > max_age_secs or ts - now_ts > CLOCK_SKEW_SECS:
+        return False
+    expected = _sign(secret, timestamp, body)
+    got_hex = signature[7:]
+    try:
+        got = bytes.fromhex(got_hex)
+        want = bytes.fromhex(expected[7:])
+    except ValueError:
+        return False
+    return hmac.compare_digest(got, want)
+
+
+def _sign(secret: str, timestamp: str, body: bytes) -> str:
+    msg = timestamp.encode() + b"." + body
+    digest = hmac.new(secret.encode(), msg, hashlib.sha256).hexdigest()
+    return f"sha256={digest}"

pcmi-1.51.0/pyproject.toml

@@ -0,0 +1,33 @@
+[project]
+name = "pcmi"
+version = "1.51.0"
+description = "PCMI Python SDK — async HTTP client for the Persistent Cognitive Memory Infrastructure API"
+readme = "README.md"
+requires-python = ">=3.10"
+license = {text = "MIT"}
+authors = [
+  {name = "Marco Spagnuolo"},
+]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "License :: OSI Approved :: MIT License",
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = ["httpx>=0.27", "pydantic>=2"]
+
+[project.urls]
+Homepage      = "https://github.com/marco-spagn/pcmi"
+Repository    = "https://github.com/marco-spagn/pcmi"
+Documentation = "https://github.com/marco-spagn/pcmi/tree/main/sdk/python"
+
+[build-system]
+requires      = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["pcmi"]

pcmi-1.51.0/smoke.py

@@ -0,0 +1,31 @@
+#!/usr/bin/env python3
+"""Manual SDK smoke (HTTP). From sdk/python with venv active:
+  export PCMI_BASE_URL=http://localhost:8000 PCMI_API_KEY=testkey123
+  python smoke.py
+"""
+import asyncio
+import os
+
+from pcmi import PCMIClient
+
+
+async def main() -> None:
+    base = os.environ.get("PCMI_BASE_URL", "http://localhost:8000")
+    key = os.environ.get("PCMI_API_KEY", "testkey123")
+    path = "root.sdk.python.smoke"
+
+    async with PCMIClient(base, key) as c:
+        await c.store(
+            path,
+            "hello from python sdk",
+            tags=["sdk-smoke"],
+            embedding_model="unspecified",
+        )
+        out = await c.retrieve(path, tags=["sdk-smoke"], tags_match="all", limit=5)
+        print("retrieve total:", out["total"])
+        compact = await c.compact(path, keep_superseded=20)
+        print("compact:", compact)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())