breeth 0.1.0

Official Python SDK for Breeth, a memory layer for agents.

breeth

Official Python SDK for Breeth, 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

pip install breeth

Quickstart (sync)

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)

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:

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.