Metadata-Version: 2.4
Name: cerebrio-py
Version: 0.1.0
Summary: Official Python SDK for Cerebrio — agentic AI knowledge infrastructure
Project-URL: Homepage, https://thecerebrio.ai
Project-URL: Documentation, https://github.com/avinash-singh-io/cerebrio-py#readme
Project-URL: Repository, https://github.com/avinash-singh-io/cerebrio-py
Project-URL: Issues, https://github.com/avinash-singh-io/cerebrio-py/issues
Project-URL: Changelog, https://github.com/avinash-singh-io/cerebrio-py/blob/main/CHANGELOG.md
Author-email: Cerebrio <support@thecerebrio.ai>
License: Apache-2.0
License-File: LICENSE
Keywords: agent,ai,cerebrio,knowledge-graph,memory,sdk
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.12
Requires-Dist: httpx>=0.27
Requires-Dist: pydantic>=2.0
Provides-Extra: dev
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Description-Content-Type: text/markdown

# cerebrio-py

> Official Python SDK for **[Cerebrio](https://thecerebrio.ai)** — agentic AI knowledge infrastructure.

[![PyPI version](https://img.shields.io/pypi/v/cerebrio-py.svg)](https://pypi.org/project/cerebrio-py/)
[![Python versions](https://img.shields.io/pypi/pyversions/cerebrio-py.svg)](https://pypi.org/project/cerebrio-py/)
[![License](https://img.shields.io/pypi/l/cerebrio-py.svg)](LICENSE)

## Install

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

Requires Python 3.12+.

## Quickstart

```python
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(...)`)

```python
# 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](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

```bash
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](https://github.com/avinash-singh-io/cerebrio-py/issues).

## License

[Apache-2.0](LICENSE).
