ChatCellAnno: Multimodal AI-Powered Single-Cell Annotation Assistant

ChatCellAnno is a desktop application for single-cell annotation that combines marker genes, optional expression matrices, enrichment evidence, and visual context for LLM-assisted cluster labeling.

中文文档

Features

• Multimodal context: marker genes, optional UMAP image context, and optional expression matrix.
• Enrichment-assisted prompting: integrates GO/KEGG and related knowledge to reduce annotation ambiguity.
• Flexible interaction modes: built-in browser flow plus configurable API settings.
• Structured parsing: turns LLM responses into cluster annotations.
• One-click report export: bundles input file info, prompt, raw output, and parsed results.
• Detailed annotation mode: per-cluster evidence analysis, confidence scores, and key literature references.
• Modular GUI: PySide6-based layout with separate core logic and UI modules.

Project Structure

• chatcellanno/core.py: workflow orchestration (generate and parse).
• chatcellanno/extractor.py: marker extraction from CSV/TSV formats.
• chatcellanno/prompt.py: prompt construction.
• chatcellanno/parser.py: response parsing (JSON-first, table-heuristic fallback).
• chatcellanno/enrichment.py: enrichment analysis integration.
• chatcellanno/gui/: main window, UI blocks, and worker threads.
• gui.py: desktop app entry point.

Installation

Requirements

• Python 3.10+

Complete Environment Setup and Installation

It is recommended to use conda to create an isolated environment to prevent conflicts with other python projects.

# 1. Create and activate a conda virtual environment
conda create -n chatcellanno python=3.11 -y
conda activate chatcellanno

# 2. Install all required dependencies from requirements.txt
pip install -r requirements.txt

If you don't have the source code cloned yet, you can also install the fundamental dependencies manually:

pip install pandas pyperclip gseapy matplotlib openai keyring click tabulate PySide6

Configuration and API keys live in the user data directory (%APPDATA%\ChatCellAnno on Windows, ~/.config/ChatCellAnno on Linux). API keys are stored via the system keyring, never plaintext in the repo.

Startup Mode Selection

On startup, choose one of two big buttons: 🚀 API Mode (direct model API with a multi-turn streaming chat panel; one-click annotate: prompt → auto-send → auto-parse results when the reply finishes) or 🌐 Browser Mode (embedded browser + bookmark bar). Tick "show every startup" or remember the last choice; switch anytime via the gear menu.

Command-Line (Linux / headless)

The CLI shares the same core logic and config as the GUI, with no PySide6 dependency. It supports the full pipeline from the terminal: a marker file (required) plus optional expression matrix / cluster image / enrichment as inputs, returning an annotation table and the raw reply file.

conda create -n chatcellanno python=3.11 -y
conda activate chatcellanno
pip install pandas pyperclip openai keyring click tabulate gseapy matplotlib
pip install -e .

# Configure the API (key is stored in the system keyring)
chatcellanno config set --base-url https://api.deepseek.com/v1 --model deepseek-chat --api-key sk-xxxx
chatcellanno doctor

# One-shot end-to-end annotation (most common): prompt → API → table
chatcellanno run markers.csv

# Full example with every input file and parameter, results written to disk
chatcellanno run markers.csv --species Mouse --tissue Brain --top-n 15 \
    --matrix expr_matrix.csv --image umap.png --use-enrichment \
    -o ./result/anno
#   → writes anno.csv (table) / anno.reply.txt (raw reply)

# Step-by-step usage (manual control over each stage)
chatcellanno generate markers.csv --mode json
chatcellanno query markers.csv --mode json
chatcellanno parse reply.txt --marker-file markers.csv

run options: --species/--tissue/--top-n/--exclude/--mode (prompt), --matrix/--image/--use-enrichment/--enrich-db (extra context), --base-url/--model/--api-key/--temperature/--max-tokens/--no-stream (API), --out-prefix(-o) (output).

See docs/linux_cli.md for details.

Direct Run

Once the environment is properly configured, run the following command to launch the GUI:

conda activate chatcellanno
python gui.py

Build Standalone Executable (Windows)

Package the application into a single, standalone .exe (anyone can double-click and run it without a Python install):

1. Prepare the build environment (once)

conda create -n chatcellanno python=3.11 -y
conda activate chatcellanno
pip install -r requirements.txt

Edit build.ps1 at the project root if you need to tweak PyInstaller arguments.

2. Run the build

conda activate chatcellanno
cd <project-root>     # e.g. D:\transient\Documents\GitHub\ChatCellAnno
./build.ps1

3. Output

After the build completes (first run takes ~5-15 min), a single-file dist\ChatCellAnno.exe is produced (~250 MB because it bundles the QtWebEngine browser kernel). Share that one exe with other users.

• build\ is intermediate output; everything in dist\ except ChatCellAnno.exe (stale database/, plugins/, chatcellanno_web_data/, etc.) can be deleted.
• First launch is slow (single-file extracts to a temp dir) — that is expected.

4. Troubleshooting

Symptom	Fix
ModuleNotFoundError at build	add --hidden-import <module> in build.ps1 and rebuild
keyring backend unavailable at runtime	keep --collect-submodules keyring in build.ps1 (backends load dynamically)
database/ not bundled	ensure the folder exists; build.ps1 auto-adds --add-data when available
stale cache on rebuild	build.ps1 already uses --clean; else delete build\ and dist\ and retry

Typical Workflow

1. Load marker file (.csv or .tsv).
2. Optionally add enrichment and image/matrix context; set species/tissue and the prompt detail level (Concise / Detailed).
3. Generate a prompt in Step 2. In API Mode click One-Click Annotate: the prompt (structured JSON request) is auto-sent to the built-in streaming chat panel; in Browser Mode drag the prompt file into the embedded browser chat.
4. In Step 3 (Export Report), paste the model reply (auto-filled in API Mode) and click Export Report: the input file information (paths, row/cluster counts), the prompt, the raw model output, and the parsed annotation table are written together into a single Markdown/text file of your choosing.

Concise mode asks for a compact table only; Detailed mode additionally requires per-cluster evidence analysis, a 0-1 confidence score, and 1-3 key literature references. JSON mode returns structured JSON (cluster → cell type/confidence/reasoning). Parsing is JSON-first with a table-heuristic fallback; the app does not generate executable code — annotations are applied by the user's own downstream workflow.

Development

• Run tests from tests/ to verify parser and enrichment behavior.
• Keep large runtime data (database/, results/) out of source control.

License

MIT. See LICENSE.