Chiron Platform

Chiron platform

The Chiron platform (https://chiron.aicell.io) is a decentralized training and reuse platform for single-cell foundation models. It is built on top of BioEngine. The flagship model is Tabula, a privacy-preserving foundation model that combines tabular learning over genes with federated learning across institutions. Trained checkpoints are published to a shared Model Hub. Federated training rounds are coordinated by a central orchestrator. Each participating institution runs a BioEngine Worker pair (data server + trainer) on its own hardware so raw single-cell data never leaves the site.

This skill is the dispatcher. Pick a task below.

Pick your task

The Chiron platform in one paragraph

Chiron's Hypha workspace is chiron-platform. Published model checkpoints live in the Hypha artifact collection chiron-platform/chiron-models. Each participating institution runs a BioEngine Worker (registered under chiron-platform/<worker-id>) that hosts up to three Chiron BioEngine apps as separate Ray Serve deployments:

• Chiron Manager (<worker>:chiron-manager) — control plane: discovers datasets, launches and tears down orchestrator and trainer apps, surfaces logs, reports cluster state.
• Chiron Orchestrator (<orch-app>:chiron-orchestrator) — Flower-based FedAvg server that coordinates one federated training session at a time.
• Tabula Trainer (<trainer-app>:tabula-trainer) — local Flower client that trains on the institution's private datasets. There can be many trainer apps registered to one orchestrator.

Tabula's in_feature (gene-sequence length the model consumes) is hard-coded to 1,200 in tabula/framework.yaml and the data server pre-cuts every dataset to this width before exposing it to the trainer. Chiron runs on BioEngine v0.10.13. The bioengine skill at bioimage.io/public/skills/bioengine/SKILL.md targets v0.11; the Hypha RPC contract documented here is stable across both, but the BioEngine app build / manifest examples in that skill may differ slightly. Use this skill for everything Chiron-specific. Delegate to the bioengine skill for everything BioEngine-general.

1. Explore published Tabula models

See apps/explore-tabula-models.md.

2. Set up a Chiron worker

Before generating any launch command, gather the environment yourself rather than asking the user to guess.

Detect the host environment. Run these checks and only ask the user when a check fails or is ambiguous:

• Operating system: uname -srm (Linux/macOS) or systeminfo (Windows). Linux is the supported target; macOS and Windows work through Docker Desktop but cannot pass --gpus all.
• Container runtime: probe docker --version, podman --version, singularity --version, apptainer --version in that order and pick the first that responds. If more than one is installed, ask the user which to use. Docker is the default in the browser wizard.
• GPU and CUDA: nvidia-smi --query-gpu=name,memory.total --format=csv lists the GPUs and their memory. No NVIDIA driver means CPU-only mode (training will be unusably slow but the worker still boots).
• Compute headroom: nproc for CPU cores and free -h (Linux) or equivalent for RAM. The defaults from the wizard (3 CPU, 30 GB RAM, 1 GPU) are a safe starting point.

Ask the user for what you cannot detect:

• Training data location: either a directory of .h5ad files or a list of specific files. If the user has no data ready yet, the worker can still be launched in orchestrator-only mode (skip the data-server, omit the data volume mount).
• Worker name (optional): displayed in the Chiron UI; defaults to Chiron Worker if not provided.
• Hypha admin token: only needed if the user has not pasted one into the prompt themselves. Direct them to log in at chiron.aicell.io and use the "AI Agent" tab of the worker setup wizard to inject the token, or generate one manually at hypha.aicell.io.

Prepare and register datasets. Follow the data-prep sub-skill at references/data-prep.md. It explains the per-dataset folder layout, the manifest.yaml schema, the expected AnnData keys (adata.X raw counts, adata.var["gene_id"] gene tokens), and the per-dataset HVG ranking, value binning, and UMAP the data server computes on first read. Inspect each .h5ad against this contract, fix anything that needs adjustment, and gather the prepared datasets into a new data directory laid out as one subfolder per dataset with a manifest.yaml each.

Launch the worker. Follow the bioengine skill at bioimage.io/public/skills/bioengine/SKILL.md §1 (Set up a BioEngine worker) for the per-runtime command. For Chiron specifically: launch with --startup-applications '{"artifact_id":"chiron-platform/chiron-manager","application_id":"chiron-manager"}' so the Chiron Manager comes up on startup. Easiest is the browser wizard at chiron.aicell.io/#/worker, which writes a one-line launch command for Docker, Podman, Singularity or Apptainer based on the form values.

Confirm the worker is online. Once the worker is up, the Chiron interface at chiron.aicell.io/#/worker will show its name, its registered datasets, and its hardware. The data server rescans the data directory every 30 seconds. You can also query apps/chiron-manager.md get_worker_info() and get_datasets_info() directly via Hypha RPC.

3. Run federated training

A federated training run involves three apps cooperating: the manager spawns the orchestrator and trainer apps, the trainers register to the orchestrator, the orchestrator runs FedAvg rounds, and at the end either the orchestrator or a trainer publishes a checkpoint to the Hub. Read the three sub-skills in order:

• apps/chiron-manager.md — how to discover workers, datasets, and trainer artifacts; how to launch and tear down orchestrator and trainer applications.
• apps/chiron-orchestrator.md — how to start a training session, configure fit and eval parameters, monitor progress, and publish the aggregated transformer checkpoint to the Hub.
• apps/tabula-trainer.md — what the trainer exposes; mostly internal but covers manual orchestrator binding, loading pretrained weights, and publishing a full per-trainer model.

The Chiron web interface at chiron.aicell.io/#/training wraps the same RPC surface in a browser-based form. Driving it via RPC and via the UI are equivalent.

4. Contribute a trainer for another single cell foundation model

Chiron's orchestrator does not require code changes to host a new foundation model. The trainer template at references/trainer-artifact-template.md documents the per-model engineering: extend the base trainer image with the model's Python dependencies, implement the trainer.py against the same Flower client + Hypha RPC contract that tabula-trainer uses, and register the result as a new trainer artifact. Each worker image bundles a single foundation model's trainer at build time, so a site that wants to participate in federations for multiple foundation models deploys one worker per model. External contributions for additional foundation models are welcome.

Conventions (read once)

Workspace. Everything Chiron-related lives in the Hypha workspace chiron-platform on the server https://hypha.aicell.io.

Service IDs. Chiron service IDs follow the BioEngine pattern <workspace>/<application_id>:<service_name>, for example chiron-platform/europa:chiron-manager. Discover live service IDs at runtime instead of hard-coding them:

from hypha_rpc import connect_to_server

server = await connect_to_server({
    "server_url": "https://hypha.aicell.io",
    "token": HYPHA_TOKEN,
    "workspace": "chiron-platform",
})

services = await server.list_services()
managers = [s for s in services if s["id"].endswith(":chiron-manager")]
manager = await server.get_service(managers[0]["id"])

Authentication. Set the HYPHA_TOKEN environment variable from a token issued for the chiron-platform workspace. The browser flow at hypha.aicell.io issues tokens. Read-only methods (get_worker_info, get_datasets_info, list_trainers, etc.) are accessible to any authenticated user. Write methods (create_orchestrator, create_trainer, start_training, save_*_weights) enforce ownership via the caller_id and owner_id parameters; see apps/chiron-manager.md § Permissions.

Model Hub collection. Every published checkpoint, whether transformer-only (orchestrator save) or full (trainer save), lives in chiron-platform/chiron-models. The artifact manifest carries a global_transformer boolean flag that distinguishes the two. See apps/explore-tabula-models.md.

Common pitfalls

• Stale BioEngine pin. Chiron expects v0.10.13 (commit 375dadf on aicell-lab/bioengine). A worker on a much older or newer BioEngine version may speak a different RPC dialect.
• Mixing workspaces. A HYPHA_TOKEN issued for a personal workspace will not see Chiron services. Make sure the token is for chiron-platform and that connect_to_server passes workspace="chiron-platform".
• Orphan trainer registrations. A trainer that registered to an orchestrator and then crashed without unregistering will leave a stale entry. Call orchestrator.list_trainers() and orchestrator.remove_trainer(trainer_service_id) to clean up, or restart the orchestrator app.
• Wrong artifact ID format for pretrained weights. load_pretrained_weights and create_trainer(pretrained_weights_artifact=...) expect {"artifact_id": "<ws>/<alias>", "file_path": "model.pth"}. Passing only artifact_id (no file_path) silently does nothing.
• Forgetting manifest.yaml. The data server discovers a dataset folder only if it contains a manifest.yaml. See references/data-prep.md.