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

• 🔬 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

pip install CASSIA

To enable optional RAG functionality:

pip install CASSIA_rag

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

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")

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-4.6",
    score_model="anthropic/claude-sonnet-4.6",
    score_threshold=75
)

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

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, 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 \
  --tissue brain \
  --species human \
  --out runs/brain_codex

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

Agent CLI backends reuse the local tool's own authentication, so they do not require CASSIA API keys. 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, inferred columns, ranking columns, and prepared marker counts before running annotation. cassia boost auto automatically prioritizes low-confidence, mixed, or ambiguous clusters and writes aggregate CSV/HTML reports under RUN/boost/_auto. cassia subcluster run annotates subclusters inside one parent cluster from a subcluster marker table and writes CSV/HTML reports in the requested output directory. cassia consensus deterministically votes across multiple CASSIA summary/subcluster CSVs and writes CSV/HTML consensus reports without calling an LLM.

You can choose any model for annotation and scoring. CASSIA also supports custom providers and local open-source models.

📚 Complete Documentation & Vignettes

🤖 LLMs Annotation Benchmark

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

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

MIT License © 2025 Elliot Xie and contributors.

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