CASSIA

CASSIA (Collaborative Agent System for Single-cell Interpretable Annotation) is a Python and R package designed for automated, accurate, and interpretable single-cell RNA-seq cell type annotation using a modular multi-agent LLM framework.

📖 Read our paper in Nature Communications

Highlights

• 🔬 Reference-free and interpretable LLM-based cell type annotation
• 🧠 Multi-agent architecture with dedicated agents for annotation, validation, formatting, quality scoring, and reporting
• 📈 Quality scores (0–100) and optional consensus scoring to quantify annotation reliability
• 📊 Detailed HTML reports with reasoning and marker validation
• 💬 Supports OpenAI, Anthropic, OpenRouter, DeepSeek, and any OpenAI-compatible API (including local LLMs)
• 🧬 Compatible with markers from Seurat (FindAllMarkers) and Scanpy (tl.rank_genes_groups)
• 🚀 Optional agents: Annotation Boost, Subclustering, RAG (retrieval-augmented generation), Uncertainty Quantification
• 🌎 Cross-species annotation capabilities, validated across human, mouse, and non-model organisms
• 🧪 Web UI also available: cassia.bio

Installation

pip install CASSIA

To enable optional RAG functionality:

pip install CASSIA_rag

Note: For R users, see the R package on GitHub.

Set Up API Key

You only need one API key to use CASSIA. We recommend OpenRouter since it provides access to most models (OpenAI, Anthropic, Google, etc.) through a single API key.

import CASSIA

# For OpenRouter (recommended — access all models with one key)
CASSIA.set_api_key("your_openrouter_api_key", provider="openrouter")

# For OpenAI
CASSIA.set_api_key("your_openai_api_key", provider="openai")

# For Anthropic
CASSIA.set_api_key("your_anthropic_api_key", provider="anthropic")

# For custom OpenAI-compatible APIs (e.g., DeepSeek)
CASSIA.set_api_key("your_deepseek_api_key", provider="https://api.deepseek.com")

For CLI use with the official DeepSeek endpoint, you can instead export DEEPSEEK_API_KEY. DeepSeek V4 thinking remains enabled by default; use the optional reasoning setting to select its effort level.

Quick Start

import CASSIA

# Load example marker data
unprocessed_markers = CASSIA.load_example_markers(processed=False)

# Run the full CASSIA pipeline (annotation + scoring + boost + report)
CASSIA.runCASSIA_pipeline(
    output_file_name="MyAnalysis",
    tissue="large intestine",
    species="human",
    marker=unprocessed_markers,
    max_workers=4,
    overall_provider="openrouter",
    annotation_model="anthropic/claude-sonnet-5",
    score_model="anthropic/claude-sonnet-5",
    score_threshold=75
)

Quick annotation only? Use CASSIA.runCASSIA_batch() for fast batch annotation without scoring or boosting.

CLI Quick Start

The Python package installs a cassia command. In addition to API providers, it can call local agent CLIs such as Claude Code, Codex CLI, Cursor Agent, OpenCode, or any custom shell command.

cassia doctor
cassia backends list
cassia examples --out cassia_example
cassia validate markers.csv

cassia annotate \
  --input markers.csv \
  --backend codex-cli \
  --mode one-shot \
  --tissue brain \
  --species human \
  --out runs/brain_codex

cassia annotate \
  --input markers.csv \
  --backend codex-cli \
  --mode validated \
  --out runs/brain_validated

cassia annotate \
  --input raw_findallmarkers.csv \
  --cluster 3 \
  --backend codex-cli \
  --mode fused-boost \
  --out runs/brain_fused

cassia boost query \
  --markers raw_findallmarkers.csv \
  --cluster 3 \
  --genes CD3D,CD3E,TRAC

cassia boost run \
  --run runs/brain_codex \
  --markers raw_findallmarkers.csv \
  --cluster 3 \
  --backend codex-cli

cassia boost auto \
  --run runs/brain_codex \
  --markers raw_findallmarkers.csv \
  --backend codex-cli \
  --max-clusters 5

cassia subcluster run \
  --markers cd8_subcluster_markers.csv \
  --major-cluster-info "CD8 T cell in human tumor" \
  --backend codex-cli \
  --out runs/cd8_subcluster

cassia consensus \
  --inputs runs/brain_codex/summary.csv runs/brain_claude/summary.csv \
  --out runs/brain_consensus.csv

cassia judge \
  --truth truth.csv \
  --prediction baseline:runs/baseline/summary.csv \
  --prediction candidate:runs/candidate/summary.csv \
  --backend codex-cli \
  --judge-model gpt-5.6-luna \
  --judge-reasoning-effort high \
  --out runs/judge

Agent CLI backends reuse the local tool's own authentication, so they do not require CASSIA API keys. one-shot is the fast baseline; validated adds the CASSIA validator/revision loop; fused-boost performs primary annotation with active queries against a full target-vs-rest marker table. The Fused Boost default is v2-compact, selected by a paired 392-case benchmark; use --fused-prompt-version v2 to reproduce the legacy prompt.

cassia examples creates a runnable mini project with marker tables, consensus inputs, shell scripts, and an offline toy agent. cassia validate checks marker CSV structure and ranking columns before annotation. cassia guide prints a packaged operating guide for coding agents. cassia boost auto prioritizes low-confidence, mixed, or ambiguous clusters. cassia subcluster run annotates subclusters inside one parent population. cassia consensus combines multiple saved runs deterministically, and cassia judge provides a blinded, top-1-first stable evaluation protocol.

For integrated Seurat clustering and annotation, cassia agent uses short-lived, transactional R commands by default. The coding agent queries markers, makes bounded local merge/subcluster decisions, assigns evidence-backed labels, runs rule-based QA, and writes an annotated RDS plus exact cell-membership provenance. No persistent R or Python session is required:

cassia agent auto object.rds \
  --out runs/object_conservative \
  --strategy conservative \
  --backend codex-cli \
  --model gpt-6-astra \
  --reasoning-effort high

cassia agent compare runs/fixed runs/object_conservative runs/adaptive

fixed preserves the supplied partition, conservative permits at most two strongly evidenced topology edits, and adaptive uses a configurable bounded budget. Automatic subcluster resolution search rejects no-op, undersized, or over-fragmented splits before commit. Immutable checkpoints and audit records make interrupted runs resumable. cassia agent init object.rds --daemon remains an explicit optional accelerator for very large objects, not the default.

Run cassia help, cassia help annotate, or cassia COMMAND --help for the complete command reference. Release benchmark manifests and compact result records are checked in under Benchmark/cli_release.

Supported Models

You can choose any model for annotation and scoring. CASSIA also supports custom providers and local open-source models. These are current compatibility recommendations, not new CASSIA benchmark results.

Documentation

📚 Complete Documentation & Vignettes

🤖 LLMs Annotation Benchmark

Citation

Xie, E., Cheng, L., Shireman, J. et al. CASSIA: a multi-agent large language model for automated and interpretable cell annotation. Nat Commun (2025). https://doi.org/10.1038/s41467-025-67084-x

Contributing

We welcome contributions! Please submit pull requests or open issues via GitHub.

License

MIT License © 2025 Elliot Xie and contributors.

Support

Open an issue on GitHub or email xie227@wisc.edu for help.