breeth 0.1.0__py3-none-any.whl

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/_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

breeth/client.py

@@ -0,0 +1,369 @@
+"""Sync and async clients for the Breeth API.
+
+Usage:
+
+    from breeth import BreethClient
+
+    with BreethClient(api_key="ck_live_...") as breeth:
+        breeth.write("Recruiter prefers candidates with HR-tech experience.")
+        hits = breeth.retrieve("HR-tech experience")
+
+    # Async
+    from breeth import AsyncBreethClient
+
+    async with AsyncBreethClient(api_key="ck_live_...") as breeth:
+        await breeth.write("...")
+"""
+from __future__ import annotations
+
+from typing import Any, Optional
+
+import httpx
+
+from ._base import (
+    DEFAULT_TIMEOUT,
+    build_headers,
+    build_url,
+    merge_query,
+    raise_for_status,
+    resolve_api_key,
+    resolve_base_url,
+)
+from .types import (
+    EntityMode,
+    EntityResponse,
+    GraphEdgeListResponse,
+    GraphEntityListResponse,
+    GraphEpisodeListResponse,
+    GroupsListResponse,
+    NodeDetailsResponse,
+    RetrieveResponse,
+    WriteResponse,
+)
+
+
+# ---------------------------------------------------------------------------
+# Sync client
+# ---------------------------------------------------------------------------
+
+class _GraphNamespace:
+    """Nested namespace exposed as ``client.graph``. Reuses the parent
+    client's httpx.Client so we don't open extra connections."""
+
+    def __init__(self, client: "BreethClient") -> None:
+        self._client = client
+
+    def node_details(self, identifier: str) -> NodeDetailsResponse:
+        data = self._client._get(f"/graph/nodes/{identifier}/details")
+        return NodeDetailsResponse.model_validate(data)
+
+    def list_entities(
+        self,
+        *,
+        query: Optional[str] = None,
+        limit: Optional[int] = None,
+        offset: Optional[int] = None,
+    ) -> GraphEntityListResponse:
+        params = merge_query({"query": query, "limit": limit, "offset": offset})
+        data = self._client._get("/graph/entities", params=params)
+        return GraphEntityListResponse.model_validate(data)
+
+    def list_edges(
+        self,
+        *,
+        query: Optional[str] = None,
+        limit: Optional[int] = None,
+        offset: Optional[int] = None,
+    ) -> GraphEdgeListResponse:
+        params = merge_query({"query": query, "limit": limit, "offset": offset})
+        data = self._client._get("/graph/edges", params=params)
+        return GraphEdgeListResponse.model_validate(data)
+
+    def list_episodes(
+        self,
+        *,
+        query: Optional[str] = None,
+        limit: Optional[int] = None,
+        offset: Optional[int] = None,
+    ) -> GraphEpisodeListResponse:
+        params = merge_query({"query": query, "limit": limit, "offset": offset})
+        data = self._client._get("/graph/episodes", params=params)
+        return GraphEpisodeListResponse.model_validate(data)
+
+
+class BreethClient:
+    """Synchronous client for the Breeth API.
+
+    Args:
+        api_key: ``ck_live_...`` token. Falls back to ``BREETH_API_KEY``
+            then ``COGRAM_API_KEY``.
+        base_url: Override the API host. Falls back to ``COGRAM_API_URL``
+            then the SDK default (``https://api.thebreeth.com``).
+        end_user_id: Optional ``X-End-User-Id`` header forwarded on
+            every request. Useful when one API key fronts many end users.
+        timeout: httpx timeout in seconds.
+        http_client: Inject a pre-configured ``httpx.Client`` (for
+            advanced transport, proxies, custom TLS, etc.). When supplied
+            the SDK does not close it on ``__exit__``.
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        *,
+        base_url: Optional[str] = None,
+        end_user_id: Optional[str] = None,
+        timeout: float = DEFAULT_TIMEOUT,
+        http_client: Optional[httpx.Client] = None,
+    ) -> None:
+        self._api_key = resolve_api_key(api_key)
+        self._base_url = resolve_base_url(base_url)
+        self._end_user_id = end_user_id
+        self._headers = build_headers(self._api_key, end_user_id)
+        self._owns_http = http_client is None
+        self._http = http_client or httpx.Client(timeout=timeout)
+        self.graph = _GraphNamespace(self)
+
+    # ---- context manager ------------------------------------------------
+
+    def __enter__(self) -> "BreethClient":
+        return self
+
+    def __exit__(self, exc_type, exc, tb) -> None:
+        self.close()
+
+    def close(self) -> None:
+        if self._owns_http:
+            self._http.close()
+
+    # ---- low-level helpers ---------------------------------------------
+
+    def _get(self, path: str, *, params: Optional[dict[str, Any]] = None) -> Any:
+        response = self._http.get(
+            build_url(self._base_url, path),
+            headers=self._headers,
+            params=params,
+        )
+        raise_for_status(response)
+        return response.json()
+
+    def _post(self, path: str, *, json: dict[str, Any]) -> Any:
+        response = self._http.post(
+            build_url(self._base_url, path),
+            headers=self._headers,
+            json=json,
+        )
+        raise_for_status(response)
+        return response.json()
+
+    # ---- public methods ------------------------------------------------
+
+    def write(
+        self,
+        content: str,
+        *,
+        group_id: str = "default",
+        source_description: str = "api",
+        extract_intent: bool = False,
+    ) -> WriteResponse:
+        """Ingest a prose episode. The graph pipeline runs in the
+        background server-side; this returns once the episode is
+        persisted."""
+        payload = {
+            "content": content,
+            "group_id": group_id,
+            "source_description": source_description,
+            "extract_intent": extract_intent,
+        }
+        data = self._post("/episodes", json=payload)
+        return WriteResponse.model_validate(data)
+
+    def retrieve(
+        self,
+        query: str,
+        *,
+        group_id: str = "default",
+        limit: int = 10,
+    ) -> RetrieveResponse:
+        """Hybrid semantic + graph search. Returns edges plus, on
+        first-person queries, the director profile block."""
+        payload = {"query": query, "group_id": group_id, "limit": limit}
+        data = self._post("/search", json=payload)
+        return RetrieveResponse.model_validate(data)
+
+    def entity(
+        self,
+        name: str,
+        *,
+        mode: Optional[EntityMode] = None,
+        limit: Optional[int] = None,
+    ) -> EntityResponse:
+        """Look up an entity by name substring. ``mode`` selects which
+        view to return (``narrative`` is the server default)."""
+        params = merge_query({"mode": mode, "limit": limit})
+        data = self._get(f"/entities/{name}", params=params)
+        return EntityResponse.model_validate(data)
+
+    def groups(
+        self,
+        *,
+        query: Optional[str] = None,
+        limit: Optional[int] = None,
+        offset: Optional[int] = None,
+    ) -> GroupsListResponse:
+        """List the memory groups visible to the current team / member."""
+        params = merge_query({"query": query, "limit": limit, "offset": offset})
+        data = self._get("/groups", params=params)
+        return GroupsListResponse.model_validate(data)
+
+
+# ---------------------------------------------------------------------------
+# Async client
+# ---------------------------------------------------------------------------
+
+class _AsyncGraphNamespace:
+    def __init__(self, client: "AsyncBreethClient") -> None:
+        self._client = client
+
+    async def node_details(self, identifier: str) -> NodeDetailsResponse:
+        data = await self._client._get(f"/graph/nodes/{identifier}/details")
+        return NodeDetailsResponse.model_validate(data)
+
+    async def list_entities(
+        self,
+        *,
+        query: Optional[str] = None,
+        limit: Optional[int] = None,
+        offset: Optional[int] = None,
+    ) -> GraphEntityListResponse:
+        params = merge_query({"query": query, "limit": limit, "offset": offset})
+        data = await self._client._get("/graph/entities", params=params)
+        return GraphEntityListResponse.model_validate(data)
+
+    async def list_edges(
+        self,
+        *,
+        query: Optional[str] = None,
+        limit: Optional[int] = None,
+        offset: Optional[int] = None,
+    ) -> GraphEdgeListResponse:
+        params = merge_query({"query": query, "limit": limit, "offset": offset})
+        data = await self._client._get("/graph/edges", params=params)
+        return GraphEdgeListResponse.model_validate(data)
+
+    async def list_episodes(
+        self,
+        *,
+        query: Optional[str] = None,
+        limit: Optional[int] = None,
+        offset: Optional[int] = None,
+    ) -> GraphEpisodeListResponse:
+        params = merge_query({"query": query, "limit": limit, "offset": offset})
+        data = await self._client._get("/graph/episodes", params=params)
+        return GraphEpisodeListResponse.model_validate(data)
+
+
+class AsyncBreethClient:
+    """Asynchronous client for the Breeth API. Same surface as
+    ``BreethClient`` but every method is a coroutine."""
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        *,
+        base_url: Optional[str] = None,
+        end_user_id: Optional[str] = None,
+        timeout: float = DEFAULT_TIMEOUT,
+        http_client: Optional[httpx.AsyncClient] = None,
+    ) -> None:
+        self._api_key = resolve_api_key(api_key)
+        self._base_url = resolve_base_url(base_url)
+        self._end_user_id = end_user_id
+        self._headers = build_headers(self._api_key, end_user_id)
+        self._owns_http = http_client is None
+        self._http = http_client or httpx.AsyncClient(timeout=timeout)
+        self.graph = _AsyncGraphNamespace(self)
+
+    # ---- context manager ------------------------------------------------
+
+    async def __aenter__(self) -> "AsyncBreethClient":
+        return self
+
+    async def __aexit__(self, exc_type, exc, tb) -> None:
+        await self.aclose()
+
+    async def aclose(self) -> None:
+        if self._owns_http:
+            await self._http.aclose()
+
+    # ---- low-level helpers ---------------------------------------------
+
+    async def _get(self, path: str, *, params: Optional[dict[str, Any]] = None) -> Any:
+        response = await self._http.get(
+            build_url(self._base_url, path),
+            headers=self._headers,
+            params=params,
+        )
+        raise_for_status(response)
+        return response.json()
+
+    async def _post(self, path: str, *, json: dict[str, Any]) -> Any:
+        response = await self._http.post(
+            build_url(self._base_url, path),
+            headers=self._headers,
+            json=json,
+        )
+        raise_for_status(response)
+        return response.json()
+
+    # ---- public methods ------------------------------------------------
+
+    async def write(
+        self,
+        content: str,
+        *,
+        group_id: str = "default",
+        source_description: str = "api",
+        extract_intent: bool = False,
+    ) -> WriteResponse:
+        payload = {
+            "content": content,
+            "group_id": group_id,
+            "source_description": source_description,
+            "extract_intent": extract_intent,
+        }
+        data = await self._post("/episodes", json=payload)
+        return WriteResponse.model_validate(data)
+
+    async def retrieve(
+        self,
+        query: str,
+        *,
+        group_id: str = "default",
+        limit: int = 10,
+    ) -> RetrieveResponse:
+        payload = {"query": query, "group_id": group_id, "limit": limit}
+        data = await self._post("/search", json=payload)
+        return RetrieveResponse.model_validate(data)
+
+    async def entity(
+        self,
+        name: str,
+        *,
+        mode: Optional[EntityMode] = None,
+        limit: Optional[int] = None,
+    ) -> EntityResponse:
+        params = merge_query({"mode": mode, "limit": limit})
+        data = await self._get(f"/entities/{name}", params=params)
+        return EntityResponse.model_validate(data)
+
+    async def groups(
+        self,
+        *,
+        query: Optional[str] = None,
+        limit: Optional[int] = None,
+        offset: Optional[int] = None,
+    ) -> GroupsListResponse:
+        params = merge_query({"query": query, "limit": limit, "offset": offset})
+        data = await self._get("/groups", params=params)
+        return GroupsListResponse.model_validate(data)

breeth/errors.py

@@ -0,0 +1,38 @@
+"""Exception types raised by the Breeth SDK."""
+from __future__ import annotations
+
+from typing import Any, Optional
+
+
+class BreethError(Exception):
+    """Base error for every non-2xx response from the Breeth API.
+
+    Attributes:
+        status: HTTP status code (e.g. 401, 429, 500).
+        slug: Stable machine-readable error code from the API
+            (e.g. "quota_exceeded", "invalid_token"). May be None if
+            the server returned a non-standard payload.
+        message: Human-readable message from the API, falls back to a
+            generic string.
+        body: The full parsed response body for advanced inspection.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status: int,
+        slug: Optional[str] = None,
+        body: Any = None,
+    ) -> None:
+        super().__init__(message)
+        self.status = status
+        self.slug = slug
+        self.message = message
+        self.body = body
+
+    def __repr__(self) -> str:
+        return (
+            f"BreethError(status={self.status}, slug={self.slug!r}, "
+            f"message={self.message!r})"
+        )

breeth/types.py

@@ -0,0 +1,237 @@
+"""Pydantic v2 request and response models for the Breeth API.
+
+These mirror the server schemas in cogram-core. Fields with a leading
+underscore on the wire (e.g. ``_cache``, ``_tier``, ``_source``,
+``_note``) use aliases so Python users can access them as normal
+attributes (``response.cache`` rather than ``response["_cache"]``).
+"""
+from __future__ import annotations
+
+from typing import Any, Literal, Optional
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+# ---------------------------------------------------------------------------
+# Write (POST /v1/episodes)
+# ---------------------------------------------------------------------------
+
+class ExtractedCounts(BaseModel):
+    entities: int
+    edges: int
+
+
+class CogramTaskEnvelope(BaseModel):
+    mode: str
+    status: str
+    task_id: Optional[str] = None
+    note: Optional[str] = None
+
+
+class IntentSuggestion(BaseModel):
+    should_extract: bool = True
+    confidence: float
+    reason: str
+
+
+class WriteResponse(BaseModel):
+    ok: bool = True
+    episode_name: str
+    extracted: ExtractedCounts
+    group_id: str
+    warning: Optional[str] = None
+    cogram: Optional[CogramTaskEnvelope] = None
+    intent_suggestion: Optional[IntentSuggestion] = None
+
+
+# ---------------------------------------------------------------------------
+# Retrieve (POST /v1/search)
+# ---------------------------------------------------------------------------
+
+class EdgeHit(BaseModel):
+    model_config = ConfigDict(populate_by_name=True)
+
+    edge_uuid: Optional[str] = None
+    source_node: str
+    target_node: str
+    fact: str
+    name: Optional[str] = None
+    intent_meta: Any = None
+    tier: str = Field(alias="_tier")
+
+
+class CacheStats(BaseModel):
+    tier: str
+    hot_hits: int
+    cold_hits: int
+    group_id: str
+
+
+class PatternEvidence(BaseModel):
+    name: str
+    stored_confidence: float
+    effective_confidence: float
+    examples: list[dict] = Field(default_factory=list)
+
+
+class DirectorProfileBlock(BaseModel):
+    model_config = ConfigDict(populate_by_name=True)
+
+    summary: str
+    visions: list[str] = Field(default_factory=list)
+    top_patterns: list[PatternEvidence] = Field(default_factory=list)
+    source: str = Field(alias="_source")
+    note: str = Field(alias="_note")
+
+
+class RetrieveResponse(BaseModel):
+    model_config = ConfigDict(populate_by_name=True)
+
+    director_profile: Optional[DirectorProfileBlock] = None
+    edges: list[EdgeHit] = Field(default_factory=list)
+    cache: CacheStats = Field(alias="_cache")
+    note: Optional[str] = None
+
+
+# ---------------------------------------------------------------------------
+# Entity (GET /v1/entities/{name})
+# ---------------------------------------------------------------------------
+
+EntityMode = Literal["narrative", "edges", "episodes", "all"]
+
+
+class EntityNarrativeRow(BaseModel):
+    uuid: str
+    name: str
+    degree: int
+    summary: str
+    narrative: Any
+    confidence_stored: float
+    confidence_decayed: float
+    confidence_label: str
+
+
+class EntityEdgeRow(BaseModel):
+    a: str
+    b: str
+    fact: str
+    intent_meta: Any = None
+
+
+class EntityEpisodeRow(BaseModel):
+    uuid: str
+    name: str
+    content_excerpt: str
+    timestamp: Any = None
+
+
+class EntityResponse(BaseModel):
+    entity_name: str
+    mode: str
+    narrative: Optional[list[EntityNarrativeRow]] = None
+    edges: Optional[list[EntityEdgeRow]] = None
+    episodes: Optional[list[EntityEpisodeRow]] = None
+    note: Optional[str] = None
+
+
+# ---------------------------------------------------------------------------
+# Graph (GET /v1/graph/*)
+# ---------------------------------------------------------------------------
+
+class GraphEntityRow(BaseModel):
+    uuid: str
+    name: str
+    labels: list[str] = Field(default_factory=list)
+    summary: Optional[str] = None
+    edge_count: int = 0
+    episode_count: int = 0
+    space: str = "individual"
+    member_id: Optional[str] = None
+    created_at: Optional[str] = None
+    knot_narrative: Optional[str] = None
+    knot_score: Optional[float] = None
+    knot_synthesized_at: Optional[float] = None
+    knot_model: Optional[str] = None
+
+
+class GraphEntityListResponse(BaseModel):
+    entities: list[GraphEntityRow]
+    count: int
+
+
+class GraphEdgeRow(BaseModel):
+    uuid: str
+    fact: str
+    source_name: str
+    target_name: str
+    cognitive_pattern: Optional[str] = None
+    intent_meta: Optional[dict] = None
+    retracted_at: Optional[str] = None
+    space: str = "individual"
+    member_id: Optional[str] = None
+    created_at: Optional[str] = None
+
+
+class GraphEdgeListResponse(BaseModel):
+    edges: list[GraphEdgeRow]
+    count: int
+
+
+class GraphEpisodeRow(BaseModel):
+    uuid: str
+    name: str
+    source_description: Optional[str] = None
+    content_excerpt: str = ""
+    group_id: str = ""
+    valid_at: Optional[str] = None
+    space: str = "individual"
+    member_id: Optional[str] = None
+
+
+class GraphEpisodeListResponse(BaseModel):
+    episodes: list[GraphEpisodeRow]
+    count: int
+
+
+class NeighborRow(BaseModel):
+    peer: str
+    direction: str
+    fact: Optional[str] = None
+    cognitive_pattern: Optional[str] = None
+    intent_meta: Optional[dict] = None
+    edge_uuid: Optional[str] = None
+
+
+class EpisodeMentionRow(BaseModel):
+    uuid: str
+    name: str
+    valid_at: Optional[str] = None
+
+
+class NodeDetailsResponse(BaseModel):
+    entity: GraphEntityRow
+    neighbors: list[NeighborRow]
+    episodes: list[EpisodeMentionRow]
+
+
+# ---------------------------------------------------------------------------
+# Groups (GET /v1/groups)
+# ---------------------------------------------------------------------------
+
+class GroupRow(BaseModel):
+    group_id: str
+    episodes: int
+    entities: int
+    patterns: int
+    knots: int
+    has_director_profile: bool
+
+
+class GroupsListResponse(BaseModel):
+    groups: list[GroupRow]
+    total: int
+    returned: int
+    query: Optional[str] = None
+    next_offset: Optional[int] = None
+    hint: Optional[str] = None
+    note: Optional[str] = None

breeth-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,9 @@
+breeth/__init__.py,sha256=Nv8BnkurpD9FD5XuCHWDIC0oNd0kBCwjpRG3aUJfAc8,1660
+breeth/_base.py,sha256=ysb6EwCTHSKY5iH6sk3nRteIujOUUSE7keaNrn0AtvI,3396
+breeth/client.py,sha256=a8yGlX3cmqQiW2QiCrXGdCkoguZORQhoPSeuRVrN5Ww,12375
+breeth/errors.py,sha256=kVW9vXnufRCSZ_frm3PTcXjdyhZJYdKY5rIVIuP0m-4,1127
+breeth/types.py,sha256=IdMruQiMjbHvhTMLh_k2Y0OwtpqryeHkbIzBuA1Hmf4,6010
+breeth-0.1.0.dist-info/METADATA,sha256=_ox-dSbAi_b6N0tHsIW-XtOr6kvanKfFlN4_J8bh3-Q,4020
+breeth-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+breeth-0.1.0.dist-info/licenses/LICENSE,sha256=HLhqMVIwZmy5mQwhOgcZSCBUYBTsLcrBjIed2C_2Z-g,1063
+breeth-0.1.0.dist-info/RECORD,,

breeth-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

breeth-0.1.0.dist-info/licenses/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.