c3po-sdk 0.4.0a1__tar.gz

c3po_sdk-0.4.0a1/PKG-INFO

@@ -0,0 +1,129 @@
+Metadata-Version: 2.3
+Name: c3po-sdk
+Version: 0.4.0a1
+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: 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
+```

c3po_sdk-0.4.0a1/README.md

@@ -0,0 +1,108 @@
+# 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
+```

c3po_sdk-0.4.0a1/pyproject.toml

@@ -0,0 +1,113 @@
+[build-system]
+build-backend = "uv_build"
+requires = [ "uv-build>=0.11.7,<0.12.0" ]
+
+[project]
+name = "c3po-sdk"
+version = "0.4.0a1"
+description = "Python SDK, CLI, and MCP server for the C3PO research platform"
+readme = "README.md"
+requires-python = ">=3.11"
+classifiers = [
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+]
+dependencies = [
+  "asyncer>=0.0.8",
+  "fastmcp>=2.0",
+  "httpx>=0.27",
+  "pydantic-settings>=2.0",
+  "rich>=13.0",
+  "sentry-sdk>=2.59",
+  "typer>=0.26",
+]
+optional-dependencies.interactive = [ "prompt-toolkit>=3.0" ]
+scripts."c3po.mcp" = "c3po_sdk.mcp.server:main"
+scripts.c3po = "c3po_sdk.cli.main:app"
+
+[dependency-groups]
+dev = [
+  "polyfactory>=2.0",
+  "pre-commit>=4.5.1",
+  "pytest>=8.0",
+  "pytest-asyncio>=0.23",
+  "pytest-cov>=5.0",
+  "respx>=0.21",
+  "ruff>=0.15.12",
+  "ty>=0.0.30",
+]
+
+[tool.uv]
+exclude-newer = "P7D"
+exclude-newer-package = { typer = "P0D" }
+
+[tool.ruff]
+extend-exclude = [ "uv.lock" ]
+lint.extend-select = [
+  "B",
+  "C4",
+  "D",
+  "FLY",
+  "I",
+  "ICN",
+  "N",
+  "NPY",
+  "PERF",
+  "PTH",
+  "RET",
+  "RUF",
+  "SIM",
+  "UP",
+]
+lint.ignore = [
+  "D100",
+  "D104",
+  "D107",
+  "D212",
+  "N802",
+  "N803",
+  "N806",
+]
+lint.per-file-ignores."__init__.py" = [ "F401", "F403" ]
+lint.per-file-ignores."tests/**" = [ "D100", "D101", "D102", "D103" ]
+lint.pydocstyle.convention = "google"
+
+[tool.pyproject-fmt]
+keep_full_version = true
+
+[tool.ty]
+rules.possibly-missing-attribute = "ignore"
+src.exclude = [
+  "**/site-packages",
+  "**/.venv",
+  "**/.ruff_cache",
+  "**/.pytest_cache",
+  "**/htmlcov",
+  "**/node_modules",
+  "**/__pycache__",
+  "**/.*",
+]
+
+[tool.pytest]
+ini_options.testpaths = [ "tests" ]
+ini_options.asyncio_mode = "auto"
+ini_options.addopts = "--import-mode=importlib --cov=. --cov-report=html"
+ini_options.filterwarnings = [
+  "ignore:datetime.datetime.utcnow\\(\\) is deprecated",
+  "ignore::FutureWarning",
+  "ignore::DeprecationWarning",
+]
+ini_options.python_files = [ "*_tests.py", "test_*.py", "tests.py" ]
+
+[tool.coverage]
+run.branch = true
+run.omit = [ "*/tests*", "*/tests/*", "*__init__*" ]
+run.relative_files = true
+report.exclude_lines = [ "pragma: no cover" ]
+report.include = [ "src/*" ]
+report.include_namespace_packages = true
+report.omit = [ "*/tests*", "*/tests/*", "*__init__*" ]
+report.show_missing = true

c3po_sdk-0.4.0a1/src/c3po_sdk/__init__.py

@@ -0,0 +1,5 @@
+"""c3po_sdk — Python SDK, CLI, and MCP server for the C3PO research platform."""
+
+from importlib.metadata import version
+
+__version__ = version("c3po-sdk")

c3po_sdk-0.4.0a1/src/c3po_sdk/cli/__init__.py

@@ -0,0 +1,5 @@
+"""c3po_sdk.cli package."""
+
+from c3po_sdk import __version__
+
+__all__ = ["__version__"]

c3po_sdk-0.4.0a1/src/c3po_sdk/cli/commands/__init__.py

@@ -0,0 +1 @@
+"""c3po_sdk.cli.commands package."""

c3po_sdk-0.4.0a1/src/c3po_sdk/cli/commands/cluster.py

@@ -0,0 +1,90 @@
+"""Cell cluster sub-commands under ``c3po nodes clusters``."""
+
+from __future__ import annotations
+
+from functools import partial
+from typing import Annotated
+
+import typer
+from asyncer import syncify
+
+from c3po_sdk.cli.context import GlobalCommand, get_ctx
+from c3po_sdk.cli.output import get_console
+from c3po_sdk.cli.pagination import paginate
+from c3po_sdk.client.exceptions import ApiError
+from c3po_sdk.client.models import ClusterList, Page
+from c3po_sdk.client.session import Session
+
+clusters_app = typer.Typer(
+    name="clusters",
+    help="Cluster commands.",
+    no_args_is_help=True,
+)
+
+
+@clusters_app.command("list", cls=GlobalCommand)
+@partial(syncify, raise_sync_error=False)
+async def clusters_list(
+    node_id: Annotated[str, typer.Argument(help="Node ID")],
+    fetch_all: Annotated[
+        bool,
+        typer.Option(
+            "--all",
+            "-a",
+            help="Fetch every page (otherwise only the first page is shown).",
+        ),
+    ] = False,
+    limit: Annotated[
+        int,
+        typer.Option("--limit", min=1, max=100, help="Page size."),
+    ] = 10,
+) -> None:
+    """List cell clusters for a node."""
+    console = get_console()
+    ctx = get_ctx()
+
+    try:
+        async with Session(profile=ctx.profile).client() as client:
+
+            async def fetch(cursor: str | None) -> Page[ClusterList]:
+                return await client.nodes.clusters.list(
+                    node_id,
+                    last_evaluated_key=cursor,
+                    limit=limit,
+                )
+
+            items = await paginate(fetch, fetch_all=fetch_all)
+    except ApiError as exc:
+        console.error(f"Failed to list clusters: {exc}")
+        raise typer.Exit(code=1) from None
+
+    console.rows_table(
+        items,
+        columns={
+            "id",
+            "label",
+            "created_at",
+            "updated_at",
+        },
+        title="Clusters",
+    )
+
+
+@clusters_app.command("get", cls=GlobalCommand)
+@partial(syncify, raise_sync_error=False)
+async def clusters_get(
+    node_id: Annotated[str, typer.Argument(help="Node ID")],
+    cluster_id: Annotated[str, typer.Argument(help="Cluster ID")],
+) -> None:
+    """Show full details of a cell cluster."""
+    console = get_console()
+    ctx = get_ctx()
+
+    try:
+        async with Session(profile=ctx.profile).client() as client:
+            cluster = await client.nodes.clusters.get(node_id, cluster_id)
+    except ApiError as exc:
+        console.error(f"Failed to fetch cluster: {exc}")
+        raise typer.Exit(code=1) from None
+
+    console.kv_table(cluster, title="Cluster")

c3po_sdk-0.4.0a1/src/c3po_sdk/cli/commands/configure.py

@@ -0,0 +1,123 @@
+"""Configure commands: one-time credential setup."""
+
+from __future__ import annotations
+
+from functools import partial
+
+import typer
+from asyncer import syncify
+
+from c3po_sdk.cli.context import GlobalCommand, get_ctx
+from c3po_sdk.cli.output import get_console
+from c3po_sdk.client.client import C3poClient
+from c3po_sdk.client.config.credentials import (
+    _CREDENTIALS_PATH,
+    CredentialsFile,
+    Profile,
+)
+from c3po_sdk.client.config.settings import Settings
+from c3po_sdk.client.exceptions import ApiError
+from c3po_sdk.client.models._utils import RichModel
+
+
+class _AuthResult(RichModel):
+    email: str
+    tenant_id: str
+    profile: str
+
+
+configure_app = typer.Typer(
+    name="configure",
+    help="Configure the CLI.",
+    no_args_is_help=True,
+)
+
+
+@configure_app.command(name="auth", cls=GlobalCommand)
+@partial(syncify, raise_sync_error=False)
+async def configure_auth() -> None:
+    """Authenticate and store a user access token."""
+    console = get_console()
+    ctx = get_ctx()
+    profile = ctx.profile or "default"
+
+    creds = CredentialsFile.load(_CREDENTIALS_PATH)
+    existing = creds.get_profile(profile)
+    if (
+        existing
+        and existing.api_token
+        and not typer.confirm(
+            f"Profile '{profile}' already has credentials. Overwrite?",
+            default=False,
+        )
+    ):
+        raise typer.Exit()
+
+    email = typer.prompt("Email")
+
+    async with C3poClient(settings=Settings(api_token="dummy")) as client:
+        with console.status("Sending sign-in code…"):
+            try:
+                signin_resp = await client.auth.signin(email)
+            except ApiError as exc:
+                console.error(f"Sign-in failed: {exc}")
+                raise typer.Exit(code=1) from None
+        console.print("[dim]A sign-in code has been sent to your email.[/dim]")
+
+        code = typer.prompt("Code")
+
+        with console.status("Verifying code…"):
+            try:
+                token_resp = await client.auth.token(
+                    "authorization_code",
+                    code=code,
+                    tenant_id=signin_resp.tenant_id,
+                )
+            except ApiError as exc:
+                console.error(f"Authentication failed: {exc}")
+                raise typer.Exit(code=1) from None
+
+    jwt_settings = Settings(api_token=token_resp.access_token)
+    async with C3poClient(jwt_settings) as jwt_client:
+        with console.status("Fetching tenants…"):
+            try:
+                tenants_page = await jwt_client.user.tenants.list()
+            except ApiError as exc:
+                console.error(f"Failed to list tenants: {exc}")
+                raise typer.Exit(code=1) from None
+        tenants = [{"id": t.id, "name": t.name} for t in tenants_page.items]
+
+        if not tenants:
+            console.error("No tenants available for this account.")
+            raise typer.Exit(code=1)
+
+        if len(tenants) == 1:
+            chosen = tenants[0]
+            console.print(f"Authenticated to tenant: [bold]{chosen['name']}[/bold]")
+        else:
+            chosen = console.select(
+                tenants,
+                heading="Available tenants:",
+                label="name",
+                detail="id",
+                prompt="Select a tenant",
+            )
+
+        with console.status("Creating access token…"):
+            try:
+                uat = await jwt_client.user.tokens.create(name=profile)
+            except ApiError as exc:
+                console.error(f"Failed to create access token: {exc}")
+                raise typer.Exit(code=1) from None
+
+    creds = CredentialsFile.load(_CREDENTIALS_PATH)
+    creds.set_profile(
+        Profile(api_token=uat.token, tenant_id=chosen["id"]),
+        name=profile,
+    )
+    creds.save(_CREDENTIALS_PATH)
+
+    console.kv_table(
+        _AuthResult(email=email, tenant_id=chosen["id"], profile=profile),
+        title="Authenticated",
+    )