Python SDK

cognethics v0.5.1 — a typed Python client over the full Cognethics tool surface. Three layers (raw dispatch, generated tree, ergonomic facade), httpx transport, Python 3.10+. Sync and async clients ship side by side.

Prefer TypeScript? The TypeScript SDK (@cognethics/sdk) exposes the same typed tree over the same surface — a first-class peer to this client.

Install

pip install cognethics

Quickstart

from cognethics import Client, PermissionDenied, NotFound

client = Client(
    api_key="ck_…",                         # scoped key you mint from the dashboard once your workspace is provisioned
    # mcp_… keys (operator-issued via the developer dashboard) work identically — substitute either prefix.
    base_url="https://{tenant}.cognethics.com",
    timeout=30.0,
    max_retries=3,
)

# 1. Generic dispatch — any governed tool
client.call("prism_introspect", dimension="stats")

# 2. Generated tree (typed, IDE-autocompletable)
client.entity_crud.spare_parts.work_order.list(page=1, page_size=50)
client.entity_crud.finance.invoice.read(id="<uuid>")
client.entity_crud.finance.invoice.update(id="<uuid>", data={"status": "paid"})  # data: InvoiceUpdateData — typed payload, required keys enforced
client.report_query.finance.aging_ap_summary(date_range={"from": "...", "to": "..."})

# 3. Ergonomic facade — top-10 resource families
client.invoices.list(status="overdue", page_size=50)
client.work_orders.create(title=..., scheduled_datetime=..., item_id=...)
client.documents.search("invoice", page_size=20)

# 4. Pagination iterator
for row in client.paginate(client.invoices.list, page_size=100):
    process(row)

# 5. Errors
try:
    client.invoices.update(invoice_id="...", status="paid")
except PermissionDenied as e:
    print(e.code, e.message, e.hint, e.request_id)

Three layers, one client

Layer	What it gives you	When to use
`client.call(tool, **args)`	Generic dispatch to any tool	One-off calls, scripts, when you don't want IDE autocomplete
`client.<mega_tool>.<app>.<entity>.<op>()`	Codegen-typed methods with parameter hints	Production code where you want the type checker to catch bad calls
`client.invoices`, `client.work_orders`, …	Hand-curated facade for the top 10 resource families	Most application code — Stripe-shape ergonomics

Get an API key

The SDK uses API-key auth (Authorization: Bearer ck_…). Workspaces are provisioned and configured for your team — tell us what you're building at developers.cognethics.com/signup/ and we set yours up. Once it's live, you mint and rotate scoped ck_ keys yourself from the dashboard, each bound to one organization.

# Once your workspace is provisioned, mint a scoped key from your tenant
# dashboard, then drive the SDK with it:
from cognethics import Client

client = Client(
    api_key="ck_…",                                # minted from https://platform.cognethics.com/dashboard/
    base_url="https://<your-tenant>.cognethics.com",  # your tenant subdomain
)

# Verify the key end to end:
print(client.call("prism_whoami"))   # confirms identity, tenant, and scope

Operators can also mint mcp_ keys (org-scoped) via the developer dashboard or POST /api/mcp/api-keys/register/ (rate-limited 5/min). Both prefixes authenticate identically — pass the plaintext as api_key= when constructing the Client.

Capabilities

Typed methods for every Prism handler covering CRUD, search, action, report, and workflow operations across 50 modules
12 primary tools wrapped: entity_crud, workflow_action, report_query, agent_command, integration_call, smart_action, document_op, notification_send, config_manage
10 ergonomic facades: Invoices, VendorInvoices, Customers, Vendors, Payments, PurchaseOrders, WorkOrders, SpareParts, Documents, Reports
Pagination iterator via client.paginate(method, **filters) — walks every page lazily
Typed exceptions: Error, PermissionDenied, NotFound, ValidationError, RateLimited, ServerError, plus two more
Retries with exponential backoff on 5xx and 429, configurable via max_retries

Available on PyPI: pypi.org/project/cognethics. See the handler reference for every method's parameters and permissions.