c3po-sdk

Python SDK, CLI, and MCP server for the C3PO research platform.

Installation

uv tool install c3po-sdk

Modules

Client (c3po_sdk.client)

Python SDK for the C3PO API.

from c3po_sdk.client.client import C3poClient

async with C3poClient() as client:
    cursor: str | None = None
    while True:
        page = await client.datasets.list(last_evaluated_key=cursor, limit=50)
        for dataset in page.items:
            ...
        if not page.has_more:
            break
        cursor = page.last_evaluated_key

CLI (c3po_sdk.cli)

c3po --help

CLI commands

Global options (where supported): --output / -o (rich | plain | json), --profile, --no-pager (skip paging for JSON on a TTY), --output-file / -O PATH (write JSON to a file; requires -o json), --version / -V. Set C3PO_NO_PAGER=1 to disable paging without a flag. Use c3po <group> <command> --help for flags and arguments.

login

• c3po login — browser-based AuthKit login (device flow)

datasets

• c3po datasets list
• c3po datasets get
• c3po datasets update
• c3po datasets tree
• c3po datasets assets

kb (analytics knowledge base — POST /v1/kb/query: NL question → generated SQL and executed result rows in one response)

• c3po kb query [QUESTION] — pass the question as an argument or pipe text on stdin; use --output json for the raw sql / columns / rows object.
• Timeouts: In CDK this route uses the streaming API Lambda with a 15-minute Lambda and API Gateway integration timeout (c3po_backend/services/api/_constructs/api.py). The SDK applies the same ceiling for the HTTP read timeout so long NL2SQL + Redshift runs are not cut off early by the default httpx limits used elsewhere.

nodes (all subcommands take a NODE_ID unless noted)

• c3po nodes get NODE_ID — node details; optional --tree for dataset subtree
• c3po nodes update NODE_ID — --name, --description
• c3po nodes reset NODE_ID — clear pipeline outputs (--force / -f)
• c3po nodes cluster NODE_ID — cell clustering (--obs-variable, repeatable --obs-values, --run-pipeline)
• c3po nodes assets NODE_ID — presigned asset URLs; --download to fetch files

nodes pipeline

• c3po nodes pipeline run NODE_ID — start execution (see --help for Leiden / IDS params); --watch / --no-watch
• c3po nodes pipeline list NODE_ID — paginated history (--all / -a, --limit)
• c3po nodes pipeline status NODE_ID EXECUTION_ID — Step Functions payload; --watch to poll until terminal

nodes programs (gene programs for a node)

• c3po nodes programs list NODE_ID — paginated (--all / -a, --limit)
• c3po nodes programs get NODE_ID PROGRAM_ID — full program record

nodes clusters (cell clusters for a node)

• c3po nodes clusters list NODE_ID — paginated (--all / -a, --limit)
• c3po nodes clusters get NODE_ID CLUSTER_ID — full cluster record

tenants

• c3po tenants me
• c3po tenants users list
• c3po tenants credentials generate
• c3po tenants credentials regenerate

users

• c3po users me
• c3po users update
• c3po users tenants list
• c3po users tokens list
• c3po users tokens create
• c3po users tokens revoke

MCP Server (c3po_sdk.mcp)

See docs/MCP.md for detailed configuration instructions.

c3po.mcp