Metadata-Version: 2.4
Name: breeth
Version: 0.1.0
Summary: Official Python SDK for Breeth, a memory layer for agents.
Project-URL: Homepage, https://thebreeth.com
Project-URL: Documentation, https://docs.thebreeth.com
Project-URL: Source, https://github.com/Gramies/cogram-sdk-python
Project-URL: Issues, https://github.com/Gramies/cogram-sdk-python/issues
Author-email: Breeth <team@thebreeth.com>
License: MIT
License-File: LICENSE
Keywords: agents,breeth,graph,knowledge,llm,memory
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Requires-Dist: pydantic>=2
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: respx>=0.21; extra == 'dev'
Description-Content-Type: text/markdown

# breeth

Official Python SDK for [Breeth](https://thebreeth.com), the memory layer for agents.

`breeth` is a thin, type-safe wrapper around the Breeth REST API. It ships with both a synchronous and an asynchronous client, runs on Python 3.10+, and depends only on `httpx` and `pydantic`.

## Install

```bash
pip install breeth
```

## Quickstart (sync)

```python
from breeth import BreethClient

with BreethClient(api_key="ck_live_...") as breeth:
    # Write a memory
    write_resp = breeth.write(
        "Candidate Jane Doe has 4 years HR-tech experience at Workday.",
        group_id="recruiting",
    )
    print(write_resp.episode_name, write_resp.extracted.entities)

    # Retrieve
    results = breeth.retrieve("HR-tech background", group_id="recruiting", limit=5)
    for edge in results.edges:
        print(edge.fact)

    # Inspect an entity
    entity = breeth.entity("Workday", mode="narrative")

    # Browse the graph
    nodes = breeth.graph.list_entities(query="Jane", limit=25)
    edges = breeth.graph.list_edges(limit=50)
    eps = breeth.graph.list_episodes()
    details = breeth.graph.node_details(nodes.entities[0].uuid)

    # List groups visible to the team
    groups = breeth.groups()
```

## Quickstart (async)

```python
import asyncio
from breeth import AsyncBreethClient

async def main():
    async with AsyncBreethClient(api_key="ck_live_...") as breeth:
        await breeth.write("Recruiter prefers iterative sourcing.")
        results = await breeth.retrieve("recruiter preferences")
        print(results.edges)

asyncio.run(main())
```

## Configuration

| Setting | Source |
| --- | --- |
| API key | `api_key=` argument, then `BREETH_API_KEY` env var, then `COGRAM_API_KEY` |
| Base URL | `base_url=` argument, then `COGRAM_API_URL` env var, default `https://api.thebreeth.com` |
| End user passthrough | `end_user_id=` argument, sent as `X-End-User-Id` |

## Errors

Every non-2xx response is raised as a `BreethError`:

```python
from breeth import BreethClient, BreethError

try:
    with BreethClient(api_key="ck_live_...") as breeth:
        breeth.write("...")
except BreethError as err:
    print(err.status)   # 429
    print(err.slug)     # "quota_exceeded"
    print(err.message)  # "Monthly write quota exceeded."
    print(err.body)     # raw JSON payload
```

The `slug` field is stable across API versions, so it is safe to branch on it.

## Roadmap

- v0.1.0: sync + async clients for write, retrieve, entity, graph, groups.
- v0.2.0: NDJSON streaming endpoints (`/v1/graph/nodes`, `/v1/graph/links`).

## Links

- Product: https://thebreeth.com
- Docs: https://docs.thebreeth.com
- Issues: https://github.com/Gramies/cogram-sdk-python/issues

## License

MIT. See [LICENSE](LICENSE).
