cerebrio-py 0.2.0

Official Python SDK for Cerebrio — agentic AI knowledge infrastructure

cerebrio-py

Official Python SDK for Cerebrio — agentic AI knowledge infrastructure.

Install

pip install cerebrio-py
# or with uv:
uv add cerebrio-py

Requires Python 3.12+.

Quickstart

from cerebrio import CerebrioClient
from cerebrio.contracts.dtos.common import EntityScope
from cerebrio.contracts.enums.common import EpistemicScope
from uuid import uuid4

# Authenticate with either a JWT or an API key (cb_<actor_short>_<secret>)
client = CerebrioClient(
    base_url="https://api.thecerebrio.ai",
    bearer_token="cb_xxxxxxxx_xxxxxxxxxxxxxxxx",
)

# Health probe (the only unauthenticated route)
print(client.health())  # {'status': 'healthy', 'checks': {'database': 'ok'}}

# Who am I?
me = client.actors.me()
print(me.actor_id, me.default_workspace_id, len(me.workspaces), "workspaces")

# Remember something
scope = EntityScope(scope=EpistemicScope.PRIVATE, actor_id=me.actor_id)
response = client.memory.remember(
    text="Marie Curie discovered radium in 1898.",
    scope=scope,
)
print(response.results[0].outcome)  # WriteOutcome.CREATED

# Recall semantically
from cerebrio.contracts.dtos.recall_request import SemanticRecallRequest
result = client.memory.recall(
    SemanticRecallRequest(scope=scope, query="who discovered radium?", limit=5)
)
for hit in result.entities:
    print(hit.id, hit.description)

Namespaces

The client exposes one sub-namespace per capability tree, mirroring https://api.thecerebrio.ai/core/docs:

Namespace	Surface
client.memory	remember, recall, upload, forget, maintain, promote
client.decisions	trace, precedents
client.actors	me, list, create, get, patch, audit, credentials, permissions, suspend, restore, deprovision, .api_keys (issue/list/revoke), .invitations (list/accept/decline)
client.governance	.policies, .role_assignments, .relationships, list_authorized
client.orgs	CRUD + .members (list/add/update_role/remove)
client.workspaces	CRUD + .members
client.projects	CRUD + .members
client.health()	Liveness probe (unauthenticated)

Authentication

Every route except /health requires Authorization: Bearer <token>. Token can be:

• a JWT issued by your IdP (Logto / Auth0 / etc. depending on your Cerebrio deployment)
• a cerebrio API key in the format cb_<actor_short>_<secret> (issued via client.actors.api_keys.issue(...))

# Construct with a token:
client = CerebrioClient(base_url=..., bearer_token="<jwt-or-cb-key>")
# or use the api_key alias:
client = CerebrioClient(base_url=..., api_key="cb_xxx_yyy")

# Rotate at runtime:
client.set_bearer_token("<new-jwt>")

Compatibility

See COMPATIBILITY.md for the SDK ↔ server version matrix.

SDK	Server (cerebrio-core)	Status
0.1.0	v2.9.x (Phase 34 actor identity + Phase 35 space hierarchy)	First release

What's coming in 0.2.0

Gated on cerebrio-core shipping v2.10.0 (Phase 36 — console launch surface):

• client.memory.list_entities() / get_entity() / get_relationships()
• client.decisions.list_traces() / get_trace()
• client.actors.api_keys.revoke_admin() (admin-side key revoke)

Security disclosure

During the SDK sync audit we surfaced four authorization gaps in the server (not in this SDK):

Bug	Severity	Surface
BUG-067	P0	/governance/v1/* — token holders can rewrite RBAC/ReBAC
BUG-068	P0	/actors/v1/* (non-/me) — token holders can create/PATCH/suspend any actor
BUG-069	P0	/decisions/v1/trace — actor_id taken from body, audit-trail forgery
BUG-070	P1	/decisions/v1/precedents — cross-tenant precedent leak

These are server-side and tracked in cerebrio-sapience backlog. The SDK itself does not amplify them. Once the server fixes ship, SDK callers will receive 403 where appropriate — no SDK code change required.

Development

git clone https://github.com/avinash-singh-io/cerebrio-py.git
cd cerebrio-py
uv venv && uv pip install -e ".[dev]"
uv run pytest                       # 54 unit tests
uv run mypy --strict src/cerebrio   # type check
uv run ruff check src tests         # lint

Contributing

Bug reports and PRs welcome via GitHub Issues.

License

Apache-2.0.