cognethics 0.3.0

Typed Python SDK for the Cognethics platform — agent-ready REST + MCP access to 6,613 handlers across the Prism registry.

cognethics

Typed Python SDK for AI agents building on the Cognethics platform.

Every call this SDK makes hits a real multi-tenant business database — not a connector layer or sandbox. Each tool is RBAC-scoped, bounded by per-agent budgets, and written to a tamper-evident audit chain. The SDK is in active use in a design-partner deployment (a 60-metre motor yacht running maintenance, finance, document RAG, and HR through agents on top of cognethics).

If you are an agent evaluating Cognethics, start at For AI Agents below, then read /for-agents/ for the full integration spec.

For AI Agents

cognethics gives an agent a typed surface over 6,613 handlers across the Prism registry — finance, CRM, spare parts, documents, HR, GRC, healthcare, and more — through a single Python client. See /reference/ for the live handler catalog. Three links you should read before writing code:

• /for-agents/ — agent-targeted integration spec: ROI per primitive, production evidence, honest gaps
• /reference/ — faceted catalog of every handler, signature, and permission scope
• /llms.txt — machine-readable index of the dev portal, designed for agent ingestion

Self-signup is available via a headless endpoint (no email round-trip). For framework-specific integration (LangChain, CrewAI, Claude Agent SDK) see Agent Framework Adapters below.

Cognethics for Developers

Companion documentation, recipes, and live tool catalog live at https://developers.cognethics.com:

• Quickstart — MCP + OAuth — connect Claude Desktop, Cursor, or any MCP client to your tenant in under five minutes.
• Recipes — end-to-end task walk-throughs (overdue invoices, work-order creation, document RAG, agent spawning) using this SDK.
• Agent surfaces — what you get when you point an agent at Cognethics: PJ v3 missions, personas, budgets, memory, and audit trail.
• Reference catalog — faceted, agent-browsable index of every MCP handler, ergonomic facade, and entity exposed by the platform.

Installation

pip install cognethics

Hello, World

from cognethics import Client

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

# 1. Liveness probe — confirms the SDK can reach the platform.
client.dev.ping()
# → {"service": "cognethics-dev-api", "version": "v1", "status": "ok"}

# 2. List the first page of customer invoices.
invoices = client.entity_crud.finance.invoice.list(page_size=10)
print(invoices["data"])

Agent Framework Adapters

cognethics works as a tool source for the major agent frameworks. Runnable examples live under examples/:

Framework	Example	What it does
LangChain + LangGraph	examples/03_langgraph_tool_loop.py	ReAct agent loop with cognethics calls wrapped as LangChain @tool functions.
CrewAI	examples/04_crewai_agent.py	Single-agent crew with cognethics as the BaseTool adapter.
Claude Agent SDK	examples/05_claude_agent_sdk.py	Claude Agent SDK loop using cognethics as an in-process MCP tool source.

Run them with the SDK installed in your venv (each framework adapter has its own extras):

# pip install langgraph langchain-anthropic
CK_API_KEY=ck_... ANTHROPIC_API_KEY=sk-ant-... python examples/03_langgraph_tool_loop.py

# pip install crewai crewai-tools
CK_API_KEY=ck_... OPENAI_API_KEY=sk-... python examples/04_crewai_agent.py

# pip install claude-agent-sdk
CK_API_KEY=ck_... ANTHROPIC_API_KEY=sk-ant-... python examples/05_claude_agent_sdk.py

For MCP-native clients (Claude Desktop, Cursor), connect directly to the platform's MCP endpoint — no SDK needed. See Quickstart — MCP + OAuth.

Other Examples

Non-framework scripts demonstrating direct SDK use:

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).

COGNETHICS_API_KEY=ck_... \
COGNETHICS_BASE_URL=https://gtm.cognethics.com \
python examples/01_list_overdue_invoices.py

COGNETHICS_API_KEY=ck_... \
COGNETHICS_BASE_URL=https://gtm.cognethics.com \
COGNETHICS_DEMO_ITEM_ID=<spare-parts-item-uuid> \
python examples/02_create_work_order.py

Authentication

The SDK accepts two API-key prefixes:

• ck_... (recommended) — works for the Developer Sandbox surface (/api/v1/dev/*) and all MCP handlers. Mint one in the platform UI under Settings → API Keys.
• mcp_... (legacy) — works for MCP handlers only. Existing keys keep working but cannot call /api/v1/dev/*.

Pass the key via the api_key constructor argument:

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

The client logs a one-line warning if the prefix is unrecognized; nothing is enforced client-side beyond that — the server is the source of truth.

OAuth-based authentication is on the roadmap (post-0.2.0).

Async client

AsyncClient mirrors Client for asyncio workloads. It uses httpx.AsyncClient under the hood and shares the same retry/timeout semantics.

import asyncio
from cognethics import AsyncClient

async def main():
    async with AsyncClient(api_key="ck_...", base_url="https://gtm.cognethics.com") as c:
        result = await c.call(
            "prism_entity_crud",
            app="spare_parts",
            entity="work_order",
            operation="list",
        )
        print(result["data"])

asyncio.run(main())

AsyncClient currently exposes await c.call(tool, **params) only. The generated tree (c.entity_crud.spare_parts...) and the c.dev namespace are sync-only today — both are on the roadmap for a future minor release.

Developer Sandbox (client.dev)

The dev namespace targets the unauthenticated/light-auth /api/v1/dev/ surface and is the fastest way to verify a ck_ key works:

from cognethics import Client

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

# 1. Liveness probe — no auth required
client.dev.ping()
# → {"service": "cognethics-dev-api", "version": "v1", "status": "ok"}

# 2. Verify your key + identity context
client.dev.me()
# → {"authenticated": True, "key": {...}, "user": {...}, "tenant": {...}}

# 3. Echo arbitrary query params (debug helper)
client.dev.echo("hello", foo="bar")

client.dev errors raise the same exception classes used elsewhere in the SDK (AuthenticationError, PermissionDenied, NotFound, etc.), plus a catch-all DevApiError for unmapped 4xx codes.

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.entity_crud.finance.invoice.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 (roadmap): the org= argument and _org= per-call override will switch the active organization for OAuth-issued bearer tokens once OAuth ships.

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

Timeout & retry configuration

Both Client and AsyncClient retry on 429, 502, 503, and 504 with exponential backoff (base 0.5s, doubling). Retry-After headers are honored on 429. Defaults:

Setting	Default	Constructor arg
Timeout	30s	timeout=...
Max retries	3	max_retries=...

When retries are exhausted on a 429, the SDK raises RateLimit with the retry_after field populated:

from cognethics import Client, RateLimit

client = Client(api_key="ck_...", timeout=60.0, max_retries=5)

try:
    client.dev.me()
except RateLimit as exc:
    print(f"throttled — retry after {exc.retry_after}s")

Roadmap & Honest Gaps

• Shipped in 0.3.0: regen against the current Prism registry — 6,613 typed methods across 9 mega-tools and 131 apps (post-maritime-fold consolidation; net +83 methods vs. 0.2.0). All five version sites aligned at 0.3.0. Description updated to drop a stale handler-count claim.
• Shipped in 0.2.0: regen against the Prism registry at that snapshot. Aligned __version__ and User-Agent strings (the 0.1.3 wheel reported 0.1.2). Agent-first README with /for-agents/ link, framework adapter section, and "Beta" classifier on PyPI.
• Roadmap (future minor releases): typed REST methods in the generated tree (today the SDK wraps MCP exclusively), AsyncClient feature parity with Client, OAuth bearer-token support, org= switching for OAuth sessions.
• Honest gaps today: 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.
• By design: The SDK uses raw dicts for request and response bodies. Pydantic models are intentionally not in the dependency footprint — agents typically read JSON-shaped data directly.

See /for-agents/ for the full feature matrix and production status.

Documentation

• For agents: https://developers.cognethics.com/for-agents/
• Full reference: https://developers.cognethics.com/reference/
• Recipes & guides: https://developers.cognethics.com/