cognethics 0.1.1

Official Python SDK for the Cognethics platform

cognethics

Official Python SDK for the Cognethics platform. cognethics provides an ergonomic, typed client for calling the platform's MCP-style handlers — entity CRUD, document operations, workflow actions, reports, and agent commands — over HTTPS, with API-key auth, organization scoping, pagination helpers, and structured error types.

Installation

pip install cognethics

Quickstart

from cognethics import Client

client = Client(
    api_key="mcp_...",
    base_url="https://gtm.cognethics.com",
)

invoices = client.invoices.list(page_size=10)
print(invoices["data"])

Authentication

The SDK supports API-key authentication today (Phase B). Generate an MCP API key in the Cognethics platform UI under Settings -> API Keys, then pass it to the client:

client = Client(api_key="mcp_...", base_url="https://gtm.cognethics.com")

OAuth-based authentication is planned for v0.2.

Calling low-level handlers

Every MCP handler exposed by the Cognethics platform is reachable in two ways:

# 1. Generic dispatch — useful for handlers not yet covered by the codegen tree.
result = client.call(
    "prism_entity_crud",
    app="spare_parts",
    entity="work_order",
    operation="list",
)

# 2. Generated tree — type-friendly attribute access for entity_crud handlers.
result = client.entity_crud.spare_parts.work_order.list(page_size=10)

The generated tree is produced from the platform's introspection schema, so new entities show up automatically when the SDK is regenerated.

Pagination

Use the paginate helper to iterate through multi-page results without managing cursors yourself:

for row in client.paginate(client.invoices.list, page_size=50):
    print(row["id"], row["amount"])

Error handling

The SDK raises typed exceptions that map to the platform's standard error envelope:

import cognethics

try:
    # Generated update methods take a `data` dict for the update payload.
    client.entity_crud.finance.invoice.update(
        id="<invoice-uuid>",
        data={"status": "paid"},
    )
except cognethics.PermissionDenied:
    print("This API key cannot update invoices in this org.")
except cognethics.NotFound:
    print("Invoice does not exist.")
except cognethics.ValidationError as exc:
    print(f"Invalid payload: {exc}")

Org switching

The Cognethics platform is multi-tenant and multi-org. The active org depends on auth method:

• API-key auth (this version): each API key is bound to one organization at creation time. To access a different org, mint a separate API key for that org. The org= constructor argument and _org= per-call override are sent as X-Organization-Context but are silently ignored by the API-key auth path.
• OAuth (planned for v0.2): the org= argument and _org= per-call override will switch the active organization for OAuth-issued bearer tokens.

# v0.1: one API key per org
constance_client = Client(api_key="mcp_constance_key", base_url="https://gtm.cognethics.com")
acme_client = Client(api_key="mcp_acme_key", base_url="https://gtm.cognethics.com")

Examples

Two runnable smoke tests live under examples/:

Script	What it does
examples/01_list_overdue_invoices.py	Lists customer invoices with status=overdue via the generated tree.
examples/02_create_work_order.py	Creates a maintenance work order. Requires a real spare_parts.item UUID (COGNETHICS_DEMO_ITEM_ID).

Run them with the SDK installed in your venv:

COGNETHICS_API_KEY=mcp_... \
COGNETHICS_BASE_URL=http://localhost:8000 \
python examples/01_list_overdue_invoices.py

COGNETHICS_API_KEY=mcp_... \
COGNETHICS_BASE_URL=http://localhost:8000 \
COGNETHICS_DEMO_ITEM_ID=<spare-parts-item-uuid> \
python examples/02_create_work_order.py

Limitations

• v0.1 is sync-only. An async wrapper backed by httpx.AsyncClient is planned for v0.2.
• Some handlers in integration_call, document_op, notification_send, and config_manage may not signature-filter unknown kwargs. Only pass parameters declared in the introspect schema for those handlers.
• The SDK uses raw dicts for request and response bodies; pydantic models are intentionally not in the dependency footprint.

Documentation

Full API reference and guides: https://developers.cognethics.com