breeth 0.1.0__tar.gz

breeth-0.1.0/.gitignore

@@ -0,0 +1,42 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Environments
+.venv/
+venv/
+env/
+ENV/
+
+# Test / coverage
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+.cache
+
+# Editors
+.vscode/
+.idea/
+*.swp
+.DS_Store

breeth-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Breeth
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

breeth-0.1.0/PKG-INFO

@@ -0,0 +1,130 @@
+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).

breeth-0.1.0/README.md

@@ -0,0 +1,99 @@
+# 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).

breeth-0.1.0/pyproject.toml

@@ -0,0 +1,57 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "breeth"
+version = "0.1.0"
+description = "Official Python SDK for Breeth, a memory layer for agents."
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.10"
+authors = [{ name = "Breeth", email = "team@thebreeth.com" }]
+keywords = ["breeth", "memory", "agents", "llm", "graph", "knowledge"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+    "httpx>=0.27",
+    "pydantic>=2",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8",
+    "pytest-asyncio>=0.23",
+    "respx>=0.21",
+]
+
+[project.urls]
+Homepage = "https://thebreeth.com"
+Documentation = "https://docs.thebreeth.com"
+Source = "https://github.com/Gramies/cogram-sdk-python"
+Issues = "https://github.com/Gramies/cogram-sdk-python/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/breeth"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "/src",
+    "/tests",
+    "/README.md",
+    "/LICENSE",
+]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

breeth-0.1.0/src/breeth/__init__.py

@@ -0,0 +1,73 @@
+"""Breeth: the official Python SDK for the Breeth memory API.
+
+    from breeth import BreethClient
+
+    breeth = BreethClient(api_key="ck_live_...")
+    breeth.write("Recruiter prefers candidates with prior HR-tech roles.")
+    results = breeth.retrieve("HR-tech background")
+"""
+from __future__ import annotations
+
+from .client import AsyncBreethClient, BreethClient
+from .errors import BreethError
+from .types import (
+    CacheStats,
+    CogramTaskEnvelope,
+    DirectorProfileBlock,
+    EdgeHit,
+    EntityEdgeRow,
+    EntityEpisodeRow,
+    EntityMode,
+    EntityNarrativeRow,
+    EntityResponse,
+    EpisodeMentionRow,
+    ExtractedCounts,
+    GraphEdgeListResponse,
+    GraphEdgeRow,
+    GraphEntityListResponse,
+    GraphEntityRow,
+    GraphEpisodeListResponse,
+    GraphEpisodeRow,
+    GroupRow,
+    GroupsListResponse,
+    IntentSuggestion,
+    NeighborRow,
+    NodeDetailsResponse,
+    PatternEvidence,
+    RetrieveResponse,
+    WriteResponse,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "AsyncBreethClient",
+    "BreethClient",
+    "BreethError",
+    "CacheStats",
+    "CogramTaskEnvelope",
+    "DirectorProfileBlock",
+    "EdgeHit",
+    "EntityEdgeRow",
+    "EntityEpisodeRow",
+    "EntityMode",
+    "EntityNarrativeRow",
+    "EntityResponse",
+    "EpisodeMentionRow",
+    "ExtractedCounts",
+    "GraphEdgeListResponse",
+    "GraphEdgeRow",
+    "GraphEntityListResponse",
+    "GraphEntityRow",
+    "GraphEpisodeListResponse",
+    "GraphEpisodeRow",
+    "GroupRow",
+    "GroupsListResponse",
+    "IntentSuggestion",
+    "NeighborRow",
+    "NodeDetailsResponse",
+    "PatternEvidence",
+    "RetrieveResponse",
+    "WriteResponse",
+    "__version__",
+]

breeth-0.1.0/src/breeth/_base.py

@@ -0,0 +1,103 @@
+"""Shared base utilities for the sync and async Breeth clients.
+
+Both `BreethClient` and `AsyncBreethClient` are thin wrappers around
+``httpx.Client`` / ``httpx.AsyncClient``. This module centralises:
+
+* Base URL resolution (env var ``COGRAM_API_URL`` overrides the default).
+* Authorization header construction.
+* Optional ``X-End-User-Id`` passthrough for multi-end-user apps.
+* HTTP error to ``BreethError`` mapping.
+
+Note: ``X-Cogram-Team-Id`` is intentionally NOT set. The server resolves
+the team from the ``ck_live_`` API key.
+"""
+from __future__ import annotations
+
+import os
+from typing import Any, Mapping, Optional
+
+import httpx
+
+from .errors import BreethError
+
+
+DEFAULT_BASE_URL = "https://api.thebreeth.com"
+API_PREFIX = "/v1"
+DEFAULT_TIMEOUT = 30.0
+USER_AGENT = "breeth-python/0.1.0"
+
+
+def resolve_base_url(explicit: Optional[str]) -> str:
+    """Pick the base URL in order: explicit arg, ``COGRAM_API_URL``,
+    SDK default. Trailing slashes are stripped so URL joining is
+    predictable."""
+    raw = explicit or os.environ.get("COGRAM_API_URL") or DEFAULT_BASE_URL
+    return raw.rstrip("/")
+
+
+def resolve_api_key(explicit: Optional[str]) -> str:
+    key = explicit or os.environ.get("BREETH_API_KEY") or os.environ.get("COGRAM_API_KEY")
+    if not key:
+        raise BreethError(
+            "Missing API key. Pass api_key=... or set BREETH_API_KEY.",
+            status=0,
+            slug="missing_api_key",
+        )
+    return key
+
+
+def build_headers(api_key: str, end_user_id: Optional[str]) -> dict[str, str]:
+    headers = {
+        "Authorization": f"Bearer {api_key}",
+        "User-Agent": USER_AGENT,
+        "Accept": "application/json",
+    }
+    if end_user_id:
+        headers["X-End-User-Id"] = end_user_id
+    return headers
+
+
+def build_url(base_url: str, path: str) -> str:
+    """Join the base URL, the /v1 prefix, and a route path. The path
+    can be supplied with or without a leading slash."""
+    suffix = path if path.startswith("/") else f"/{path}"
+    return f"{base_url}{API_PREFIX}{suffix}"
+
+
+def raise_for_status(response: httpx.Response) -> None:
+    """Map any 4xx / 5xx response to a ``BreethError``.
+
+    The API returns JSON shaped like
+    ``{"detail": {"error": "<slug>", "message": "..."}}`` for handled
+    errors, and FastAPI's default ``{"detail": "..."}`` for unhandled
+    validation issues. We accept both and extract whatever we can.
+    """
+    if response.is_success:
+        return
+
+    slug: Optional[str] = None
+    message: str = response.reason_phrase or "Request failed"
+    body: Any = None
+    try:
+        body = response.json()
+    except Exception:
+        body = response.text or None
+
+    if isinstance(body, dict):
+        detail = body.get("detail", body)
+        if isinstance(detail, dict):
+            slug = detail.get("error") or detail.get("slug") or slug
+            message = detail.get("message") or detail.get("detail") or message
+        elif isinstance(detail, str):
+            message = detail
+
+    raise BreethError(message, status=response.status_code, slug=slug, body=body)
+
+
+def merge_query(params: Optional[Mapping[str, Any]]) -> Optional[dict[str, Any]]:
+    """Drop None-valued query parameters so callers can pass them
+    unconditionally without polluting the URL."""
+    if not params:
+        return None
+    out = {k: v for k, v in params.items() if v is not None}
+    return out or None