audrey-memory 0.23.1__tar.gz

audrey_memory-0.23.1/PKG-INFO

@@ -0,0 +1,104 @@
+Metadata-Version: 2.1
+Name: audrey-memory
+Version: 0.23.1
+Summary: Typed Python client for the Audrey LLM memory server
+Author: evilander
+License: MIT
+Project-URL: Homepage, https://github.com/Evilander/Audrey
+Project-URL: Repository, https://github.com/Evilander/Audrey
+Project-URL: Issues, https://github.com/Evilander/Audrey/issues
+Keywords: ai,agents,audrey,llm,memory,pydantic,python
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: pydantic<3,>=2.7
+
+# Audrey Python SDK
+
+Typed Python client for the Audrey REST API.
+
+## Install
+
+```bash
+pip install audrey-memory
+```
+
+For local development from this repository:
+
+```bash
+cd python
+python -m pip install -e .
+```
+
+## Quick Start
+
+Start Audrey's REST API:
+
+```bash
+npx audrey serve
+```
+
+Then use the client:
+
+```python
+from audrey_memory import Audrey
+
+brain = Audrey(
+    base_url="http://127.0.0.1:7437",
+    api_key="secret",
+    agent="support-agent",
+)
+
+memory_id = brain.encode(
+    "Stripe returns HTTP 429 above 100 req/s",
+    source="direct-observation",
+    tags=["stripe", "rate-limit"],
+)
+
+results = brain.recall("stripe rate limits", limit=5)
+snapshot = brain.snapshot()
+brain.close()
+```
+
+Restore snapshots only into an empty Audrey store, such as a sidecar started with a fresh `AUDREY_DATA_DIR`:
+
+```python
+restore_target = Audrey(base_url="http://127.0.0.1:7437", api_key="secret")
+restore_target.restore(snapshot)
+restore_target.close()
+```
+
+Async usage:
+
+```python
+import asyncio
+
+from audrey_memory import AsyncAudrey
+
+
+async def main() -> None:
+    async with AsyncAudrey(base_url="http://127.0.0.1:7437") as brain:
+        await brain.health()
+        await brain.encode("Deploy failed due to OOM", source="direct-observation")
+        await brain.recall("deploy failure", limit=3)
+
+
+asyncio.run(main())
+```
+
+## Features
+
+- Sync and async clients powered by `httpx`
+- Pydantic request and response models
+- Bearer auth via `AUDREY_API_KEY`
+- Optional `X-Audrey-Agent` header on client requests
+- Snapshot export and restore support

audrey_memory-0.23.1/README.md

@@ -0,0 +1,80 @@
+# Audrey Python SDK
+
+Typed Python client for the Audrey REST API.
+
+## Install
+
+```bash
+pip install audrey-memory
+```
+
+For local development from this repository:
+
+```bash
+cd python
+python -m pip install -e .
+```
+
+## Quick Start
+
+Start Audrey's REST API:
+
+```bash
+npx audrey serve
+```
+
+Then use the client:
+
+```python
+from audrey_memory import Audrey
+
+brain = Audrey(
+    base_url="http://127.0.0.1:7437",
+    api_key="secret",
+    agent="support-agent",
+)
+
+memory_id = brain.encode(
+    "Stripe returns HTTP 429 above 100 req/s",
+    source="direct-observation",
+    tags=["stripe", "rate-limit"],
+)
+
+results = brain.recall("stripe rate limits", limit=5)
+snapshot = brain.snapshot()
+brain.close()
+```
+
+Restore snapshots only into an empty Audrey store, such as a sidecar started with a fresh `AUDREY_DATA_DIR`:
+
+```python
+restore_target = Audrey(base_url="http://127.0.0.1:7437", api_key="secret")
+restore_target.restore(snapshot)
+restore_target.close()
+```
+
+Async usage:
+
+```python
+import asyncio
+
+from audrey_memory import AsyncAudrey
+
+
+async def main() -> None:
+    async with AsyncAudrey(base_url="http://127.0.0.1:7437") as brain:
+        await brain.health()
+        await brain.encode("Deploy failed due to OOM", source="direct-observation")
+        await brain.recall("deploy failure", limit=3)
+
+
+asyncio.run(main())
+```
+
+## Features
+
+- Sync and async clients powered by `httpx`
+- Pydantic request and response models
+- Bearer auth via `AUDREY_API_KEY`
+- Optional `X-Audrey-Agent` header on client requests
+- Snapshot export and restore support

audrey_memory-0.23.1/audrey_memory/__init__.py

@@ -0,0 +1,51 @@
+from ._version import __version__
+from .client import AsyncAudrey, Audrey, AudreyAPIError
+from .types import (
+    AckResponse,
+    Affect,
+    AnalyticsResponse,
+    ConsolidateRequest,
+    ContradictionStatus,
+    DreamRequest,
+    EncodeRequest,
+    EncodeResponse,
+    ForgetRequest,
+    ForgetResponse,
+    HealthResponse,
+    MarkUsedRequest,
+    MemorySnapshot,
+    OperationResult,
+    RecallError,
+    RecallRequest,
+    RecallResponse,
+    RecallResult,
+    RestoreResponse,
+    StatusResponse,
+)
+
+__all__ = [
+    "__version__",
+    "AckResponse",
+    "Affect",
+    "AnalyticsResponse",
+    "AsyncAudrey",
+    "Audrey",
+    "AudreyAPIError",
+    "ConsolidateRequest",
+    "ContradictionStatus",
+    "DreamRequest",
+    "EncodeRequest",
+    "EncodeResponse",
+    "ForgetRequest",
+    "ForgetResponse",
+    "HealthResponse",
+    "MarkUsedRequest",
+    "MemorySnapshot",
+    "OperationResult",
+    "RecallError",
+    "RecallRequest",
+    "RecallResponse",
+    "RecallResult",
+    "RestoreResponse",
+    "StatusResponse",
+]

audrey_memory-0.23.1/audrey_memory/_version.py

@@ -0,0 +1 @@
+__version__ = "0.23.1"

audrey_memory-0.23.1/audrey_memory/client.py

@@ -0,0 +1,372 @@
+from __future__ import annotations
+
+from typing import Any, Mapping, TypeVar
+
+import httpx
+from pydantic import BaseModel
+
+from ._version import __version__
+from .types import (
+    AckResponse,
+    ConsolidateRequest,
+    DreamRequest,
+    EncodeRequest,
+    EncodeResponse,
+    ForgetRequest,
+    ForgetResponse,
+    HealthResponse,
+    MarkUsedRequest,
+    MemorySnapshot,
+    OperationResult,
+    RecallRequest,
+    RecallResponse,
+    RecallResult,
+    RestoreResponse,
+    StatusResponse,
+)
+
+ModelT = TypeVar("ModelT", bound=BaseModel)
+DEFAULT_TIMEOUT = 30.0
+DEFAULT_BASE_URL = "http://127.0.0.1:7437"
+
+
+class AudreyAPIError(RuntimeError):
+    def __init__(self, status_code: int, message: str, response_body: Any = None) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.response_body = response_body
+
+
+def _build_headers(api_key: str | None, agent: str | None) -> dict[str, str]:
+    headers = {
+        "Accept": "application/json",
+        "Content-Type": "application/json",
+        "User-Agent": f"audrey-memory-python/{__version__}",
+    }
+    if api_key:
+        headers["Authorization"] = f"Bearer {api_key}"
+    if agent:
+        headers["X-Audrey-Agent"] = agent
+    return headers
+
+
+def _dump_payload(payload: BaseModel | Mapping[str, Any] | None) -> dict[str, Any] | None:
+    if payload is None:
+        return None
+    if isinstance(payload, BaseModel):
+        return payload.model_dump(exclude_none=True, mode="json")
+    return {key: value for key, value in dict(payload).items() if value is not None}
+
+
+def _error_message(response: httpx.Response, data: Any) -> str:
+    if isinstance(data, dict):
+        detail = data.get("error") or data.get("message")
+        if isinstance(detail, str) and detail.strip():
+            return detail
+    return f"Audrey API request failed with status {response.status_code}"
+
+
+def _decode_json(response: httpx.Response) -> Any:
+    try:
+        data = response.json()
+    except ValueError:
+        data = None
+    if response.is_error:
+        raise AudreyAPIError(response.status_code, _error_message(response, data), data)
+    return data
+
+
+def _validate(model_type: type[ModelT], data: Any) -> ModelT:
+    return model_type.model_validate(data)
+
+
+def _build_model_payload(
+    payload: BaseModel | Mapping[str, Any] | str,
+    model_type: type[ModelT],
+    field_name: str,
+    extra: dict[str, Any],
+) -> ModelT:
+    if isinstance(payload, model_type):
+        if extra:
+            raise TypeError(f"{model_type.__name__} payload cannot be combined with keyword overrides")
+        return payload
+    if isinstance(payload, Mapping):
+        if extra:
+            raise TypeError(f"Mapping payload cannot be combined with keyword overrides for {model_type.__name__}")
+        return model_type.model_validate(payload)
+    return model_type.model_validate({field_name: payload, **extra})
+
+
+def _optional_model_payload(
+    payload: BaseModel | Mapping[str, Any] | None,
+    model_type: type[ModelT],
+    extra: dict[str, Any],
+) -> ModelT | None:
+    if isinstance(payload, model_type):
+        if extra:
+            raise TypeError(f"{model_type.__name__} payload cannot be combined with keyword overrides")
+        return payload
+    if payload is None:
+        return model_type.model_validate(extra) if extra else None
+    if extra:
+        raise TypeError(f"Mapping payload cannot be combined with keyword overrides for {model_type.__name__}")
+    return model_type.model_validate(payload)
+
+
+class Audrey:
+    def __init__(
+        self,
+        base_url: str = DEFAULT_BASE_URL,
+        *,
+        api_key: str | None = None,
+        agent: str | None = None,
+        timeout: float | httpx.Timeout = DEFAULT_TIMEOUT,
+        transport: httpx.BaseTransport | None = None,
+    ) -> None:
+        self._client = httpx.Client(
+            base_url=base_url.rstrip("/"),
+            timeout=timeout,
+            transport=transport,
+            headers=_build_headers(api_key, agent),
+        )
+
+    def close(self) -> None:
+        self._client.close()
+
+    def __enter__(self) -> Audrey:
+        return self
+
+    def __exit__(self, exc_type: object, exc: object, traceback: object) -> None:
+        self.close()
+
+    def health(self) -> HealthResponse:
+        return _validate(HealthResponse, _decode_json(self._client.get("/health")))
+
+    def status(self) -> StatusResponse:
+        return _validate(StatusResponse, _decode_json(self._client.get("/v1/status")))
+
+    def impact(self, *, window_days: int = 7, limit: int = 5) -> dict[str, Any]:
+        """Closed-loop visibility report: validations, decay, promotions over a window.
+
+        Mirrors `audrey impact` and `Audrey.impact()` on the TypeScript side.
+        """
+        return _decode_json(
+            self._client.get(
+                "/v1/impact",
+                params={"windowDays": window_days, "limit": limit},
+            )
+        )
+
+    def analytics(self) -> dict[str, Any]:
+        # analytics() is kept as an alias of impact() for callers that already
+        # adopted the older spelling. New code should call impact() directly.
+        return self.impact()
+
+    def encode(self, payload: EncodeRequest | Mapping[str, Any] | str, /, **kwargs: Any) -> str:
+        request = _build_model_payload(payload, EncodeRequest, "content", kwargs)
+        data = _decode_json(self._client.post("/v1/encode", json=_dump_payload(request)))
+        return _validate(EncodeResponse, data).id
+
+    def recall(self, payload: RecallRequest | Mapping[str, Any] | str, /, **kwargs: Any):
+        request = _build_model_payload(payload, RecallRequest, "query", kwargs)
+        data = _decode_json(self._client.post("/v1/recall", json=_dump_payload(request)))
+        if isinstance(data, dict) and isinstance(data.get("results"), list):
+            data = data["results"]
+        elif not isinstance(data, list):
+            raise TypeError(f"unexpected /v1/recall payload shape: {type(data).__name__}")
+        return [_validate(RecallResult, row) for row in data]
+
+    def recall_response(self, payload: RecallRequest | Mapping[str, Any] | str, /, **kwargs: Any) -> RecallResponse:
+        request = _build_model_payload(payload, RecallRequest, "query", kwargs)
+        data = _decode_json(self._client.post("/v1/recall", json=_dump_payload(request)))
+        if isinstance(data, list):
+            return RecallResponse(results=[_validate(RecallResult, row) for row in data])
+        if isinstance(data, dict):
+            return _validate(RecallResponse, data)
+        raise TypeError(f"unexpected /v1/recall payload shape: {type(data).__name__}")
+
+    def dream(self, payload: DreamRequest | Mapping[str, Any] | None = None, /, **kwargs: Any) -> OperationResult:
+        request = _optional_model_payload(payload, DreamRequest, kwargs)
+        data = _decode_json(self._client.post("/v1/dream", json=_dump_payload(request)))
+        return _validate(OperationResult, data)
+
+    def consolidate(
+        self,
+        payload: ConsolidateRequest | Mapping[str, Any] | None = None,
+        /,
+        **kwargs: Any,
+    ) -> OperationResult:
+        request = _optional_model_payload(payload, ConsolidateRequest, kwargs)
+        data = _decode_json(self._client.post("/v1/consolidate", json=_dump_payload(request)))
+        return _validate(OperationResult, data)
+
+    def mark_used(self, memory_id: str) -> AckResponse:
+        request = MarkUsedRequest(id=memory_id)
+        data = _decode_json(self._client.post("/v1/mark-used", json=_dump_payload(request)))
+        return _validate(AckResponse, data)
+
+    def validate(self, memory_id: str, outcome: str = "used") -> dict[str, Any]:
+        """Closed-loop feedback. outcome is one of {"used","helpful","wrong"}.
+
+        "helpful" reinforces salience and retrieval. "wrong" decreases
+        salience and bumps challenge_count for semantic memories. "used"
+        is a neutral signal that the memory was referenced.
+        """
+        if outcome not in ("used", "helpful", "wrong"):
+            raise ValueError(f"outcome must be used|helpful|wrong, got {outcome!r}")
+        return _decode_json(self._client.post("/v1/validate", json={"id": memory_id, "outcome": outcome}))
+
+    def forget(
+        self,
+        *,
+        id: str | None = None,
+        query: str | None = None,
+        purge: bool | None = None,
+        min_similarity: float | None = None,
+    ) -> ForgetResponse | None:
+        request = ForgetRequest(
+            id=id,
+            query=query,
+            purge=purge,
+            minSimilarity=min_similarity,
+        )
+        data = _decode_json(self._client.post("/v1/forget", json=_dump_payload(request)))
+        if data is None:
+            return None
+        return _validate(ForgetResponse, data)
+
+    def snapshot(self) -> MemorySnapshot:
+        # Server exposes snapshot as GET /v1/export.
+        data = _decode_json(self._client.get("/v1/export"))
+        return _validate(MemorySnapshot, data)
+
+    def restore(self, snapshot: MemorySnapshot | Mapping[str, Any]) -> RestoreResponse:
+        # Server exposes restore as POST /v1/import. The TS handler reads
+        # body.snapshot (not the body root), so wrap the payload accordingly.
+        request = snapshot if isinstance(snapshot, MemorySnapshot) else MemorySnapshot.model_validate(snapshot)
+        data = _decode_json(self._client.post("/v1/import", json={"snapshot": _dump_payload(request)}))
+        return _validate(RestoreResponse, data)
+
+
+class AsyncAudrey:
+    def __init__(
+        self,
+        base_url: str = DEFAULT_BASE_URL,
+        *,
+        api_key: str | None = None,
+        agent: str | None = None,
+        timeout: float | httpx.Timeout = DEFAULT_TIMEOUT,
+        transport: httpx.AsyncBaseTransport | None = None,
+    ) -> None:
+        self._client = httpx.AsyncClient(
+            base_url=base_url.rstrip("/"),
+            timeout=timeout,
+            transport=transport,
+            headers=_build_headers(api_key, agent),
+        )
+
+    async def aclose(self) -> None:
+        await self._client.aclose()
+
+    async def __aenter__(self) -> AsyncAudrey:
+        return self
+
+    async def __aexit__(self, exc_type: object, exc: object, traceback: object) -> None:
+        await self.aclose()
+
+    async def health(self) -> HealthResponse:
+        return _validate(HealthResponse, _decode_json(await self._client.get("/health")))
+
+    async def status(self) -> StatusResponse:
+        return _validate(StatusResponse, _decode_json(await self._client.get("/v1/status")))
+
+    async def impact(self, *, window_days: int = 7, limit: int = 5) -> dict[str, Any]:
+        """Closed-loop visibility report — async counterpart of `Audrey.impact`."""
+        response = await self._client.get(
+            "/v1/impact",
+            params={"windowDays": window_days, "limit": limit},
+        )
+        return _decode_json(response)
+
+    async def analytics(self) -> dict[str, Any]:
+        return await self.impact()
+
+    async def encode(self, payload: EncodeRequest | Mapping[str, Any] | str, /, **kwargs: Any) -> str:
+        request = _build_model_payload(payload, EncodeRequest, "content", kwargs)
+        data = _decode_json(await self._client.post("/v1/encode", json=_dump_payload(request)))
+        return _validate(EncodeResponse, data).id
+
+    async def recall(self, payload: RecallRequest | Mapping[str, Any] | str, /, **kwargs: Any):
+        request = _build_model_payload(payload, RecallRequest, "query", kwargs)
+        data = _decode_json(await self._client.post("/v1/recall", json=_dump_payload(request)))
+        if isinstance(data, dict) and isinstance(data.get("results"), list):
+            data = data["results"]
+        elif not isinstance(data, list):
+            raise TypeError(f"unexpected /v1/recall payload shape: {type(data).__name__}")
+        return [_validate(RecallResult, row) for row in data]
+
+    async def recall_response(self, payload: RecallRequest | Mapping[str, Any] | str, /, **kwargs: Any) -> RecallResponse:
+        request = _build_model_payload(payload, RecallRequest, "query", kwargs)
+        data = _decode_json(await self._client.post("/v1/recall", json=_dump_payload(request)))
+        if isinstance(data, list):
+            return RecallResponse(results=[_validate(RecallResult, row) for row in data])
+        if isinstance(data, dict):
+            return _validate(RecallResponse, data)
+        raise TypeError(f"unexpected /v1/recall payload shape: {type(data).__name__}")
+
+    async def dream(self, payload: DreamRequest | Mapping[str, Any] | None = None, /, **kwargs: Any) -> OperationResult:
+        request = _optional_model_payload(payload, DreamRequest, kwargs)
+        data = _decode_json(await self._client.post("/v1/dream", json=_dump_payload(request)))
+        return _validate(OperationResult, data)
+
+    async def consolidate(
+        self,
+        payload: ConsolidateRequest | Mapping[str, Any] | None = None,
+        /,
+        **kwargs: Any,
+    ) -> OperationResult:
+        request = _optional_model_payload(payload, ConsolidateRequest, kwargs)
+        data = _decode_json(await self._client.post("/v1/consolidate", json=_dump_payload(request)))
+        return _validate(OperationResult, data)
+
+    async def mark_used(self, memory_id: str) -> AckResponse:
+        request = MarkUsedRequest(id=memory_id)
+        data = _decode_json(await self._client.post("/v1/mark-used", json=_dump_payload(request)))
+        return _validate(AckResponse, data)
+
+    async def validate(self, memory_id: str, outcome: str = "used") -> dict[str, Any]:
+        """Closed-loop feedback. See sync validate()."""
+        if outcome not in ("used", "helpful", "wrong"):
+            raise ValueError(f"outcome must be used|helpful|wrong, got {outcome!r}")
+        return _decode_json(await self._client.post("/v1/validate", json={"id": memory_id, "outcome": outcome}))
+
+    async def forget(
+        self,
+        *,
+        id: str | None = None,
+        query: str | None = None,
+        purge: bool | None = None,
+        min_similarity: float | None = None,
+    ) -> ForgetResponse | None:
+        request = ForgetRequest(
+            id=id,
+            query=query,
+            purge=purge,
+            minSimilarity=min_similarity,
+        )
+        data = _decode_json(await self._client.post("/v1/forget", json=_dump_payload(request)))
+        if data is None:
+            return None
+        return _validate(ForgetResponse, data)
+
+    async def snapshot(self) -> MemorySnapshot:
+        # Server exposes snapshot as GET /v1/export.
+        data = _decode_json(await self._client.get("/v1/export"))
+        return _validate(MemorySnapshot, data)
+
+    async def restore(self, snapshot: MemorySnapshot | Mapping[str, Any]) -> RestoreResponse:
+        # Server exposes restore as POST /v1/import. The TS handler reads
+        # body.snapshot (not the body root), so wrap the payload accordingly.
+        request = snapshot if isinstance(snapshot, MemorySnapshot) else MemorySnapshot.model_validate(snapshot)
+        data = _decode_json(await self._client.post("/v1/import", json={"snapshot": _dump_payload(request)}))
+        return _validate(RestoreResponse, data)

audrey_memory-0.23.1/audrey_memory/py.typed

@@ -0,0 +1 @@
+

audrey_memory-0.23.1/audrey_memory/types.py

@@ -0,0 +1,157 @@
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class AudreyModel(BaseModel):
+    model_config = ConfigDict(extra="allow", populate_by_name=True)
+
+
+class Affect(AudreyModel):
+    valence: float
+    arousal: float | None = None
+    label: str | None = None
+
+
+class HealthResponse(AudreyModel):
+    ok: bool
+    version: str
+
+
+class ContradictionStatus(AudreyModel):
+    open: int = 0
+    resolved: int = 0
+    context_dependent: int = 0
+    reopened: int = 0
+
+
+class StatusResponse(AudreyModel):
+    episodic: int | None = None
+    semantic: int | None = None
+    procedural: int | None = None
+    causalLinks: int | None = None
+    contradictions: ContradictionStatus | None = None
+    dormant: int | None = None
+    lastConsolidation: str | None = None
+    totalConsolidationRuns: int | None = None
+
+
+class AnalyticsRow(AudreyModel):
+    id: str | None = None
+    content: str | None = None
+    agent: str | None = None
+
+
+class AnalyticsResponse(AudreyModel):
+    topEpisodes: list[AnalyticsRow] = Field(default_factory=list)
+    topSemantics: list[AnalyticsRow] = Field(default_factory=list)
+    recentRuns: list[AnalyticsRow] = Field(default_factory=list)
+    metrics: list[AnalyticsRow] = Field(default_factory=list)
+    agents: list[AnalyticsRow] = Field(default_factory=list)
+
+
+class EncodeRequest(AudreyModel):
+    content: str
+    source: str
+    salience: float | None = Field(default=None, ge=0, le=1)
+    tags: list[str] | None = None
+    context: dict[str, Any] | None = None
+    affect: Affect | None = None
+    causal: dict[str, Any] | None = None
+    supersedes: str | None = None
+    private: bool | None = None
+    agent: str | None = None
+
+
+class EncodeResponse(AudreyModel):
+    id: str
+
+
+class RecallRequest(AudreyModel):
+    query: str
+    limit: int | None = Field(default=None, ge=1, le=50)
+    context: dict[str, Any] | None = None
+    mood: dict[str, Any] | None = None
+    types: list[str] | None = None
+    scope: str | None = None
+    includePrivate: bool | None = None
+    agent: str | None = None
+
+
+class RecallResult(AudreyModel):
+    id: str
+    content: str
+    type: str | None = None
+    confidence: float | None = None
+    score: float | None = None
+    source: str | None = None
+    createdAt: str | None = None
+    agent: str | None = None
+
+
+class RecallError(AudreyModel):
+    type: str | None = None
+    stage: str | None = None
+    message: str | None = None
+
+
+class RecallResponse(AudreyModel):
+    results: list[RecallResult] = Field(default_factory=list)
+    partialFailure: bool = Field(default=False, alias="partial_failure")
+    errors: list[RecallError] = Field(default_factory=list)
+
+
+class DreamRequest(AudreyModel):
+    dormantThreshold: float | None = Field(default=None, ge=0, le=1)
+    minClusterSize: int | None = Field(default=None, ge=1)
+    similarityThreshold: float | None = Field(default=None, ge=0, le=1)
+
+
+class ConsolidateRequest(AudreyModel):
+    minClusterSize: int | None = Field(default=None, ge=1)
+    similarityThreshold: float | None = Field(default=None, ge=0, le=1)
+
+
+class OperationResult(AudreyModel):
+    ok: bool | None = None
+    status: str | None = None
+
+
+class MarkUsedRequest(AudreyModel):
+    id: str
+
+
+class AckResponse(AudreyModel):
+    ok: bool
+
+
+class ForgetRequest(AudreyModel):
+    id: str | None = None
+    query: str | None = None
+    purge: bool | None = None
+    minSimilarity: float | None = Field(default=None, ge=0, le=1)
+
+
+class ForgetResponse(AudreyModel):
+    id: str | None = None
+    type: str | None = None
+    purged: bool | None = None
+
+
+class MemorySnapshot(AudreyModel):
+    version: str
+    exportedAt: str | None = None
+    episodes: list[dict[str, Any]] = Field(default_factory=list)
+    semantics: list[dict[str, Any]] = Field(default_factory=list)
+    procedures: list[dict[str, Any]] = Field(default_factory=list)
+    causalLinks: list[dict[str, Any]] = Field(default_factory=list)
+    contradictions: list[dict[str, Any]] = Field(default_factory=list)
+    consolidationRuns: list[dict[str, Any]] = Field(default_factory=list)
+    consolidationMetrics: list[dict[str, Any]] = Field(default_factory=list)
+    config: dict[str, Any] = Field(default_factory=dict)
+
+
+class RestoreResponse(StatusResponse):
+    ok: bool

audrey_memory-0.23.1/audrey_memory.egg-info/PKG-INFO

@@ -0,0 +1,104 @@
+Metadata-Version: 2.1
+Name: audrey-memory
+Version: 0.23.1
+Summary: Typed Python client for the Audrey LLM memory server
+Author: evilander
+License: MIT
+Project-URL: Homepage, https://github.com/Evilander/Audrey
+Project-URL: Repository, https://github.com/Evilander/Audrey
+Project-URL: Issues, https://github.com/Evilander/Audrey/issues
+Keywords: ai,agents,audrey,llm,memory,pydantic,python
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: pydantic<3,>=2.7
+
+# Audrey Python SDK
+
+Typed Python client for the Audrey REST API.
+
+## Install
+
+```bash
+pip install audrey-memory
+```
+
+For local development from this repository:
+
+```bash
+cd python
+python -m pip install -e .
+```
+
+## Quick Start
+
+Start Audrey's REST API:
+
+```bash
+npx audrey serve
+```
+
+Then use the client:
+
+```python
+from audrey_memory import Audrey
+
+brain = Audrey(
+    base_url="http://127.0.0.1:7437",
+    api_key="secret",
+    agent="support-agent",
+)
+
+memory_id = brain.encode(
+    "Stripe returns HTTP 429 above 100 req/s",
+    source="direct-observation",
+    tags=["stripe", "rate-limit"],
+)
+
+results = brain.recall("stripe rate limits", limit=5)
+snapshot = brain.snapshot()
+brain.close()
+```
+
+Restore snapshots only into an empty Audrey store, such as a sidecar started with a fresh `AUDREY_DATA_DIR`:
+
+```python
+restore_target = Audrey(base_url="http://127.0.0.1:7437", api_key="secret")
+restore_target.restore(snapshot)
+restore_target.close()
+```
+
+Async usage:
+
+```python
+import asyncio
+
+from audrey_memory import AsyncAudrey
+
+
+async def main() -> None:
+    async with AsyncAudrey(base_url="http://127.0.0.1:7437") as brain:
+        await brain.health()
+        await brain.encode("Deploy failed due to OOM", source="direct-observation")
+        await brain.recall("deploy failure", limit=3)
+
+
+asyncio.run(main())
+```
+
+## Features
+
+- Sync and async clients powered by `httpx`
+- Pydantic request and response models
+- Bearer auth via `AUDREY_API_KEY`
+- Optional `X-Audrey-Agent` header on client requests
+- Snapshot export and restore support

audrey_memory-0.23.1/audrey_memory.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+README.md
+pyproject.toml
+audrey_memory/__init__.py
+audrey_memory/_version.py
+audrey_memory/client.py
+audrey_memory/py.typed
+audrey_memory/types.py
+audrey_memory.egg-info/PKG-INFO
+audrey_memory.egg-info/SOURCES.txt
+audrey_memory.egg-info/dependency_links.txt
+audrey_memory.egg-info/requires.txt
+audrey_memory.egg-info/top_level.txt
+tests/test_client.py

audrey_memory-0.23.1/audrey_memory.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

audrey_memory-0.23.1/audrey_memory.egg-info/requires.txt

@@ -0,0 +1,2 @@
+httpx<1,>=0.27
+pydantic<3,>=2.7

audrey_memory-0.23.1/audrey_memory.egg-info/top_level.txt

@@ -0,0 +1 @@
+audrey_memory

audrey_memory-0.23.1/pyproject.toml

@@ -0,0 +1,56 @@
+[build-system]
+requires = ["setuptools>=69", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "audrey-memory"
+dynamic = ["version"]
+description = "Typed Python client for the Audrey LLM memory server"
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [
+  { name = "evilander" }
+]
+keywords = [
+  "ai",
+  "agents",
+  "audrey",
+  "llm",
+  "memory",
+  "pydantic",
+  "python",
+]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Scientific/Engineering :: Artificial Intelligence",
+  "Typing :: Typed",
+]
+dependencies = [
+  "httpx>=0.27,<1",
+  "pydantic>=2.7,<3",
+]
+
+[project.urls]
+Homepage = "https://github.com/Evilander/Audrey"
+Repository = "https://github.com/Evilander/Audrey"
+Issues = "https://github.com/Evilander/Audrey/issues"
+
+[tool.setuptools.dynamic]
+version = { attr = "audrey_memory._version.__version__" }
+
+[tool.setuptools]
+include-package-data = true
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["audrey_memory*"]
+
+[tool.setuptools.package-data]
+audrey_memory = ["py.typed"]

audrey_memory-0.23.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

audrey_memory-0.23.1/tests/test_client.py

@@ -0,0 +1,252 @@
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+import socket
+import subprocess
+import sys
+import tempfile
+import time
+import unittest
+from pathlib import Path
+
+import httpx
+
+PYTHON_ROOT = Path(__file__).resolve().parents[1]
+REPO_ROOT = PYTHON_ROOT.parent
+
+if str(PYTHON_ROOT) not in sys.path:
+    sys.path.insert(0, str(PYTHON_ROOT))
+
+from audrey_memory import AsyncAudrey, Audrey, AudreyAPIError, MemorySnapshot, __version__
+
+
+def _free_port() -> int:
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as sock:
+        sock.bind(("127.0.0.1", 0))
+        return int(sock.getsockname()[1])
+
+
+class AudreyClientUnitTests(unittest.TestCase):
+    def test_sync_client_sends_auth_and_agent_headers(self) -> None:
+        seen: dict[str, object] = {}
+
+        def handler(request: httpx.Request) -> httpx.Response:
+            seen["authorization"] = request.headers.get("Authorization")
+            seen["agent"] = request.headers.get("X-Audrey-Agent")
+            seen["body"] = json.loads(request.content.decode("utf-8"))
+            return httpx.Response(201, json={"id": "mem_123"})
+
+        client = Audrey(
+            base_url="http://audrey.test",
+            api_key="secret-token",
+            agent="python-sdk",
+            transport=httpx.MockTransport(handler),
+        )
+        self.addCleanup(client.close)
+
+        memory_id = client.encode(
+            "Stripe returns HTTP 429 above 100 req/s",
+            source="direct-observation",
+            tags=["stripe"],
+        )
+
+        self.assertEqual(memory_id, "mem_123")
+        self.assertEqual(seen["authorization"], "Bearer secret-token")
+        self.assertEqual(seen["agent"], "python-sdk")
+        self.assertEqual(
+            seen["body"],
+            {
+                "content": "Stripe returns HTTP 429 above 100 req/s",
+                "source": "direct-observation",
+                "tags": ["stripe"],
+            },
+        )
+
+    def test_sync_client_raises_structured_api_error(self) -> None:
+        def handler(_: httpx.Request) -> httpx.Response:
+            return httpx.Response(400, json={"error": "content is required"})
+
+        client = Audrey(
+            base_url="http://audrey.test",
+            transport=httpx.MockTransport(handler),
+        )
+        self.addCleanup(client.close)
+
+        with self.assertRaises(AudreyAPIError) as exc:
+            client.encode("", source="direct-observation")
+
+        self.assertEqual(exc.exception.status_code, 400)
+        self.assertEqual(str(exc.exception), "content is required")
+
+
+class AudreyAsyncClientUnitTests(unittest.IsolatedAsyncioTestCase):
+    async def test_async_client_parses_recall_response(self) -> None:
+        # The TS server returns an envelope so degraded-recall diagnostics survive JSON.
+        # this test handler returned a {results: [...]} object — that matched
+        def handler(request: httpx.Request) -> httpx.Response:
+            payload = json.loads(request.content.decode("utf-8"))
+            self.assertEqual(payload["query"], "stripe rate limits")
+            self.assertEqual(payload["limit"], 2)
+            return httpx.Response(
+                200,
+                json={
+                    "results": [
+                        {
+                            "id": "mem_1",
+                            "content": "Stripe returns HTTP 429 above 100 req/s",
+                            "type": "episodic",
+                            "confidence": 0.92,
+                            "score": 0.88,
+                            "source": "direct-observation",
+                        }
+                    ],
+                    "partial_failure": True,
+                    "errors": [{"type": "fts", "stage": "recall.fts_lookup", "message": "missing FTS table"}],
+                },
+            )
+
+        client = AsyncAudrey(
+            base_url="http://audrey.test",
+            transport=httpx.MockTransport(handler),
+        )
+        self.addAsyncCleanup(client.aclose)
+
+        response = await client.recall_response("stripe rate limits", limit=2)
+
+        self.assertTrue(response.partialFailure)
+        self.assertEqual(len(response.results), 1)
+        self.assertEqual(response.results[0].id, "mem_1")
+        self.assertEqual(response.errors[0].stage, "recall.fts_lookup")
+
+
+# Spins up the real TS REST sidecar via `node dist/mcp-server/index.js serve`
+# and exercises the Python client end-to-end. Requires the build artifacts
+# under dist/, so run `npm run build` before invoking this suite.
+class AudreyClientIntegrationTests(unittest.TestCase):
+    @classmethod
+    def setUpClass(cls) -> None:
+        cls.api_key = "integration-secret"
+        cls.port = _free_port()
+        cls.base_url = f"http://127.0.0.1:{cls.port}"
+        cls.temp_dir = tempfile.TemporaryDirectory(prefix="audrey-python-sdk-")
+        env = os.environ.copy()
+        env.update(
+            {
+                "AUDREY_DATA_DIR": cls.temp_dir.name,
+                "AUDREY_EMBEDDING_PROVIDER": "mock",
+                "AUDREY_LLM_PROVIDER": "mock",
+                "AUDREY_API_KEY": cls.api_key,
+                # mcp-server/index.ts parses port from env, not argv.
+                "AUDREY_PORT": str(cls.port),
+                # snapshot()/restore() in the integration test exercise the
+                # admin-only /v1/export and /v1/import routes.
+                "AUDREY_ENABLE_ADMIN_TOOLS": "1",
+            }
+        )
+        cls.process = subprocess.Popen(
+            ["node", "dist/mcp-server/index.js", "serve"],
+            cwd=REPO_ROOT,
+            env=env,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.STDOUT,
+            text=True,
+        )
+        cls._wait_for_ready()
+
+    @classmethod
+    def tearDownClass(cls) -> None:
+        if hasattr(cls, "process") and cls.process.poll() is None:
+            cls.process.terminate()
+            try:
+                cls.process.wait(timeout=10)
+            except subprocess.TimeoutExpired:
+                cls.process.kill()
+                cls.process.wait(timeout=10)
+        if hasattr(cls, "temp_dir"):
+            cls.temp_dir.cleanup()
+
+    @classmethod
+    def _wait_for_ready(cls) -> None:
+        deadline = time.time() + 30
+        last_error: Exception | None = None
+        while time.time() < deadline:
+            if cls.process.poll() is not None:
+                output = ""
+                if cls.process.stdout is not None:
+                    output = cls.process.stdout.read()
+                raise RuntimeError(
+                    f"Audrey server exited before becoming ready (code {cls.process.returncode}):\n{output}"
+                )
+            try:
+                response = httpx.get(
+                    f"{cls.base_url}/health",
+                    headers={"Authorization": f"Bearer {cls.api_key}"},
+                    timeout=1.0,
+                )
+                if response.status_code == 200:
+                    return
+            except Exception as exc:  # pragma: no cover - readiness race
+                last_error = exc
+            time.sleep(0.25)
+        raise RuntimeError(f"Timed out waiting for Audrey server readiness: {last_error}")
+
+    def test_sync_end_to_end_against_real_server(self) -> None:
+        with Audrey(
+            base_url=self.base_url,
+            api_key=self.api_key,
+            agent="python-sync-test",
+        ) as client:
+            health = client.health()
+            self.assertTrue(health.ok)
+
+            memory_id = client.encode(
+                "Python SDK integration remembers Stripe rate limits",
+                source="direct-observation",
+                tags=["python", "stripe"],
+            )
+            self.assertTrue(memory_id)
+
+            client.mark_used(memory_id)
+
+            results = client.recall("stripe rate limits", limit=5, scope="agent")
+            self.assertGreaterEqual(len(results), 1)
+            self.assertIn("Stripe", results[0].content)
+
+            impact = client.impact(window_days=7, limit=3)
+            self.assertIn("validatedTotal", impact)
+            self.assertGreaterEqual(impact["validatedTotal"], 1)
+
+            snapshot = client.snapshot()
+            self.assertIsInstance(snapshot, MemorySnapshot)
+            self.assertEqual(snapshot.version, __version__)
+            # restore() refuses to import into a non-empty store on purpose.
+            # The round-trip test would need to spin up a second server with
+            # a fresh data dir; we cover the empty-store import path in unit
+            # tests on the TS side and don't replicate the harness here.
+            with self.assertRaises(Exception):
+                client.restore(snapshot)
+
+    def test_async_end_to_end_against_real_server(self) -> None:
+        async def run() -> None:
+            async with AsyncAudrey(
+                base_url=self.base_url,
+                api_key=self.api_key,
+                agent="python-async-test",
+            ) as client:
+                health = await client.health()
+                self.assertTrue(health.ok)
+                memory_id = await client.encode(
+                    "Async Python SDK remembers deployment failures",
+                    source="direct-observation",
+                )
+                self.assertTrue(memory_id)
+                results = await client.recall("deployment failures", limit=5, scope="agent")
+                self.assertGreaterEqual(len(results), 1)
+
+        asyncio.run(run())
+
+
+if __name__ == "__main__":
+    unittest.main()