Metadata-Version: 2.3
Name: c3po-sdk
Version: 0.4.0
Summary: Python SDK, CLI, and MCP server for the C3PO research platform
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Dist: asyncer>=0.0.8
Requires-Dist: boto3>=1.35
Requires-Dist: fastmcp>=2.0
Requires-Dist: httpx>=0.27
Requires-Dist: pydantic-settings>=2.0
Requires-Dist: rich>=13.0
Requires-Dist: sentry-sdk>=2.59
Requires-Dist: typer>=0.26
Requires-Dist: prompt-toolkit>=3.0 ; extra == 'interactive'
Requires-Python: >=3.11
Provides-Extra: interactive
Description-Content-Type: text/markdown

# c3po-sdk

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

## Installation

```bash
uv tool install c3po-sdk
```

## Modules

### Client (`c3po_sdk.client`)

Python SDK for the C3PO API.

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

```bash
c3po --help
```

#### CLI commands

Global options (where supported): `--output` / `-o` (`rich` | `plain` | `json`), `--profile`, `--version` / `-V`. Use `c3po <group> <command> --help` for flags and arguments.

**auth**

- `c3po auth status`

**configure**

- `c3po configure auth`

**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](docs/MCP.md) for detailed configuration instructions.

```bash
c3po.mcp
```
