CyteType is not a single LLM call with a prompt. It is a coordinated pipeline of specialized agents that collaborate to produce a single annotation with a full evidence trail.
The structured annotation workflow
Data preparation (local)
Before anything is sent to the API, the client SDK preprocesses your object locally: extracting top marker genes per cluster, computing expression percentages across all genes, aggregating observation metadata per cluster, and sampling UMAP coordinates for visualization. This preprocessing runs in your environment and does not require a network connection.
Artifact generation
Two artifacts are created and uploaded alongside the annotation request:
obs.duckdb— a DuckDB database of cell metadata, powering metadata filtering and exploration in the reportvars.h5— a compressed HDF5 file of the normalized expression matrix, used by the server for on-demand gene expression lookups in the interactive report
Agent roles
Six specialized agents run per cluster:
| Agent | Role |
|---|---|
| Contextualizer | Frames the biological context from study_context, cluster metadata, and marker expression before annotation begins |
| Annotator | Proposes candidate cell types using markers, expression percentages, and Cell Ontology knowledge |
| Reviewer | Multiple independent reviewers evaluate each candidate, surfacing strengths, weaknesses, and alternatives |
| Summarizer | Synthesizes reviewer outputs into a final annotation with confidence scores |
| Clinician | Applies disease-context validation to catch biologically implausible calls |
| Chat | Powers the Cluster Copilot, staying connected to the cluster's expression data |
Cell Ontology mapping
Every annotation is mapped to a Cell Ontology (CL) term. CL is a community-maintained, hierarchical vocabulary for cell types. CL IDs enable cross-study comparison, downstream ontology-based analyses (for example enrichment against cell type databases), and regulatory traceability. The ID format is CL:xxxxxxx.
LLM infrastructure
Each cluster requires hundreds of LLM calls. The CyteType API handles rate limit management, automatic retries, health-aware model fallbacks, and parallel cluster processing. The n_parallel_clusters parameter controls how many clusters are annotated simultaneously.
Data flow summary
Your object (AnnData / Seurat)
↓ SDK preprocessing (local)
marker genes, expression %, metadata, UMAP coords
↓ Artifact upload
vars.h5 (expression matrix) + obs.duckdb (cell metadata)
↓ /annotate API call
payload: study context, markers, expression, metadata
↓ Structured workflow (per cluster, in parallel)
Contextualizer → Annotator → Reviewer × N → Summarizer → Clinician
↓ /results fetch
annotations, ontology terms, confidence scores, evidence
↓ Results written back to your object
adata.obs / obj@meta.data + adata.uns / obj@misc
↓ Interactive HTML report
live at prod.cytetype.nygen.io/report/{job_id}
💡 Note: The performance gains originate from the workflow rather than the LLM tier. Each agent contributes a different biological perspective, and a reconciliation step produces a stable, evidence-supported annotation.
Learn more
