Metadata-Version: 2.4
Name: ebbmem-client
Version: 0.2.0
Summary: Client SDK for the Ebb cognitive memory HTTP API
Author: Spectrayan
License-Expression: LicenseRef-Proprietary
Project-URL: Homepage, https://ebbmem.ai
Project-URL: Repository, https://ebbmem.ai
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: urllib3>=2.1.0
Requires-Dist: python-dateutil>=2.8.2
Requires-Dist: pydantic>=2
Requires-Dist: typing-extensions>=4.7.1
Requires-Dist: httpx>=0.27

# ebbmem-client

Python client for the Ebb memory HTTP API. Version 0.2.0. Homepage: https://ebbmem.ai.

The import name is `ebbmem_client`. The in-process engine wheel already owns the `ebbmem` import.

This package is not yet published. When it is, install it from the package registry:

```bash
pip install ebbmem-client
```

## Quickstart

```python
from ebbmem_client import EbbmemClient

client = EbbmemClient()  # reads EBBMEM_ORIGIN and EBBMEM_TOKEN
stored = client.memory.remember("the harbor light is cobalt")
found = client.memory.recall("harbor light")
```

`AsyncEbbmemClient` is a native async client. It uses httpx for HTTP and the generated models for request and response bodies.

## Auth

`EBBMEM_ORIGIN` is required. There is no default origin. `EBBMEM_TOKEN` is sent as `Authorization: Bearer`. `EBBMEM_API_KEY` is sent as `X-API-Key`. `EBBMEM_NAMESPACE` is sent as `X-Ebb-Namespace`. An explicit argument overrides the matching environment variable. The token is omitted from `repr`.

## Methods

`client.memory` exposes `remember`, `remember_batch`, `recall`, `recall_federated`, `get`, `list`, `update`, `forget`, `reinforce`, `reflect`, `why_not`, and `status`. `client.tasks` exposes `get`, `list`, and `cancel`. `client.events.stream` reads the SSE event stream. `client.health` calls the health endpoint.

## Errors and retries

Failures raise `EbbmemError` with `status`, `code` (`EBB-…` from the error envelope), `message`, `details`, and `request_id`. Subclasses are `AuthError` (401/403), `NotFoundError` (404), `ValidationError` (400/422), `RateLimitError` (429, `retry_after`), `ServerError` (5xx), and `ConnectionError`.

The client retries connection errors, 429 (honoring `Retry-After`), and 502/503/504. Retries apply to idempotent methods, and to `remember` / `remember_batch` when an idempotency key is set. `max_retries` defaults to 2. `timeout` defaults to 30 seconds. The user agent is `ebbmem-client-python/0.2.0`.

## Pagination

`memory.list()` follows `next_cursor` until `has_more` is false and yields each row.

## Events

`client.events.stream()` yields parsed SSE data objects. Pass `token` only when the stream must authenticate with the query parameter.

## Raw API

`client.raw` is the generated client (`memory`, `tasks`, `events`, `health`).

## License

Proprietary, (c) Spectrayan.
