Metadata-Version: 2.4
Name: CASSIA
Version: 1.4.0
Summary: CASSIA (Cell type Annotation using Specialized System with Integrated AI) is a Python package for automated cell type annotation in single-cell RNA sequencing data using large language models.
Home-page: https://github.com/elliotxe/CASSIA
Author: Elliot Yixuan Xie
Author-email: xie227@wisc.edu
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: numpy>=1.21.0
Requires-Dist: pandas>=1.3.0
Requires-Dist: openai>=2.0.0
Requires-Dist: anthropic>=0.125.0
Requires-Dist: requests>=2.25.0
Requires-Dist: matplotlib>=3.3.0
Requires-Dist: seaborn>=0.11.0
Requires-Dist: mygene>=3.2.0
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# 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](https://doi.org/10.1038/s41467-025-67084-x)

## 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](https://www.cassia.bio/)

## Installation

```bash
pip install CASSIA
```

To enable optional RAG functionality:

```bash
pip install CASSIA_rag
```

**Note**: For R users, see the R package on [GitHub](https://github.com/ElliotXie/CASSIA-SingleCell-LLM-Annotation).

## 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.

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

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

```bash
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:

```bash
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`](https://github.com/ElliotXie/CASSIA/tree/main/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.

| Provider | Model | Notes |
|----------|-------|-------|
| OpenRouter | `anthropic/claude-sonnet-5` | Balanced default (Recommended) |
| OpenRouter | `openai/gpt-6-astra` | Current OpenAI flagship |
| OpenRouter | `google/gemini-3.8-flash` | Fast, low-cost option |
| OpenRouter | `deepseek/deepseek-v4-flash-0731` | Very low-cost option |
| OpenAI | `gpt-5.6-terra` | Balanced default |
| OpenAI | `gpt-6-astra` | Current flagship; availability may vary |
| Anthropic | `claude-sonnet-5` | Balanced default |
| Anthropic | `claude-opus-5` | Current flagship |
| DeepSeek | `deepseek-v4-flash` | Very affordable direct-provider option |
| Local | Any Ollama model | Zero cost, full privacy |

## Documentation

📚 [Complete Documentation & Vignettes](https://docs.cassia.bio/en)

🤖 [LLMs Annotation Benchmark](https://sc-llm-benchmark.pages.dev/methods/cassia)

## 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](https://github.com/ElliotXie/CASSIA/issues).

## License

MIT License © 2025 Elliot Xie and contributors.

## Support

Open an issue on [GitHub](https://github.com/ElliotXie/CASSIA/issues) or email **xie227@wisc.edu** for help.
