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 submission, the client SDK preprocesses the object locally. It extracts top marker genes per cluster, computes expression percentages across all genes, aggregates categorical observation metadata per cluster when enabled, and samples visualization coordinates. The client also creates the matrix and observation artifacts described below.
Artifact generation
Two artifacts are created and uploaded alongside the annotation request:
obs.duckdb: a DuckDB database containing the complete cell observation metadata table and visualization coordinates, used for metadata filtering and explorationvars.h5: a compressed HDF5 file containing the full normalized expression matrix, feature metadata, and raw counts when an integer-valued count source is available
The official clients do not upload the original AnnData or Seurat object as a single file. They also do not upload FASTQ or BAM files. The two artifacts still represent expression and metadata from the analysis object and should be reviewed before submission.
Agent roles
CyteType coordinates specialized roles during annotation and report use:
| 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 |
| Citation linker | Finds and evaluates literature evidence for report claims |
| 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 summaries, visualization coords
↓ Artifact upload
vars.h5 (normalized matrix, feature metadata, optional raw counts)
obs.duckdb (complete observation table and visualization coords)
↓ /annotate API call
payload: study context, markers, expression summaries, metadata summaries
↓ 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 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.
Data available to workflow tools
The hosted workflow uses the uploaded matrices and observation table for server-side calculations, report visualizations, expression lookups, metadata filters, and interactive research tools. The complete artifact files are not sent to model providers. Model prompts can include study context, markers, expression summaries, metadata summaries, annotation hypotheses, and focused values retrieved by an interactive tool.
Setting aggregate_metadata=False removes aggregated metadata from the annotation request, but it does not remove the observation table from obs.duckdb. Setting require_artifacts=False allows annotation to continue when an artifact fails; it does not prevent successful artifacts from being uploaded.
For the provider, access-control, and institutional-review details, see Security and privacy.
Learn more
