orchestrator

Multi-omics query routing and pipeline orchestration across all OmicsClaw domains. Routes natural language queries to the correct analysis skill across spatial transcriptomics, single-cell omics, geno

SKILL.md

GitHub

🎯 Multi-Omics Orchestrator

You are the OmicsClaw Orchestrator, the meta-skill that routes user queries to the correct analysis skill across all omics domains. You never perform analysis yourself — you dispatch to the right specialist.

Why This Exists

<!-- ORCH-INTRO-START -->
  • Without it: Users must know exact skill names and CLI flags across 88 skills in 7 domains<!-- ORCH-INTRO-END -->
  • With it: Natural language queries are automatically matched to the correct skill
  • Why OmicsClaw: Single unified entry point for all multi-omics analysis capabilities

Supported Domains

<!-- ORCH-DOMAINS-START -->

OmicsClaw currently supports 88 skills across 7 domains:

  1. Spatial Transcriptomics (17 skills) - .h5ad, .h5, .zarr, .loom
  2. Single-Cell Omics (30 skills) - .h5ad, .h5, .loom, .mtx
  3. Genomics (10 skills) - .vcf, .bam, .cram, .fasta, .fastq, .bed
  4. Proteomics (8 skills) - .mzml, .mzxml, .csv
  5. Metabolomics (8 skills) - .mzml, .cdf, .csv
  6. Bulk RNA-seq (13 skills) - .csv, .tsv, .fastq
  7. Orchestrator (2 skills) - * (all types)<!-- ORCH-DOMAINS-END -->
<!-- Note: counts above are regenerated by scripts/generate_orchestrator_counts.py -->

Workflow

  1. Detect Domain: Identify omics domain from file extension or query keywords
  2. Route Query: Match query text to best skill within domain using keyword maps
  3. Execute: Dispatch to chosen analysis skill with appropriate parameters
  4. Monitor: Track execution status and collect results
  5. Report: Return structured output with skill name, confidence, and results

Core Capabilities

1. Domain Detection

Automatically detect the omics domain from:

  • File extension: .h5ad → spatial/singlecell, .vcf → genomics, .mzml → proteomics/metabolomics
  • Query keywords: "spatially variable" → spatial, "variant calling" → genomics

2. Query Routing

Match natural language queries to skills using domain-specific keyword maps with confidence scoring.

Three routing modes available:

  1. Keyword Mode (default): Fast pattern matching using curated keyword maps

    • Matches query keywords to skill names
    • Confidence based on keyword length and position
    • No external dependencies, instant results
    • Best for: Standard queries with clear keywords
  2. LLM Mode: AI-powered semantic understanding

    • Uses language model to interpret query intent
    • Considers skill descriptions and context
    • Requires LLM API access
    • Best for: Complex or ambiguous queries
  3. Hybrid Mode: Combines keyword and LLM approaches

    • Falls back to LLM if keyword confidence is low
    • Balances speed and accuracy
    • Best for: Production systems with varied query types

3. Pipeline Orchestration

Execute multi-skill pipelines (e.g., preprocess → domains → de → genes → statistics).

4. Skill Discovery

List all available skills with status (ready/planned) and descriptions.

Routing Maps

Spatial Transcriptomics Keywords → Skills

Query Keywords Skill Description
spatial domain, tissue region, niche spatial-domain-identification Tissue region/niche identification
cell type annotation spatial-cell-annotation Cell type annotation
deconvolution, cell proportion spatial-deconvolution Cell type deconvolution
spatial statistics, moran, autocorrelation spatial-statistics Spatial statistics
spatially variable gene spatial-svg-detection Spatially variable genes
differential expression, marker genes spatial-de Differential expression
condition comparison, pseudobulk spatial-condition-comparison Condition comparison
ligand receptor, cell communication spatial-cell-communication Cell-cell communication
rna velocity spatial-velocity RNA velocity
trajectory, pseudotime spatial-trajectory Trajectory inference
pathway enrichment, gsea spatial-enrichment Pathway enrichment
cnv, copy number spatial-cnv Copy number variation
batch correction, integration spatial-integration Multi-sample integration
spatial registration, alignment spatial-registration Spatial registration
preprocess, qc, normalization spatial-preprocessing Data preprocessing

Single-Cell Omics Keywords → Skills

Query Keywords Skill Description
qc metrics, quality control sc-qc QC metrics calculation
filter cells, gene filtering sc-filter Cell/gene filtering
ambient rna, cellbender sc-ambient-removal Ambient RNA removal
single cell, scrna-seq sc-preprocessing scRNA-seq preprocessing
doublet detection, scrublet sc-doublet-detection Doublet detection
trajectory, pseudotime, paga, dpt sc-pseudotime Trajectory inference
rna velocity, scvelo sc-velocity RNA velocity analysis
cell type annotation, celltypist sc-cell-annotation Cell type annotation
integration, batch correction, harmony sc-batch-integration Batch correction
differential expression, pseudobulk sc-de Differential expression
marker genes, find markers sc-markers Marker gene detection
cluster enrichment, marker enrichment, single-cell gsea sc-enrichment Statistical enrichment on marker / DE rankings
pathway scoring, signature score sc-pathway-scoring Per-cell pathway / signature activity scoring
gene regulatory network, grn, pyscenic sc-grn Gene regulatory network

Genomics Keywords → Skills

Query Keywords Skill Description
variant calling, snp genomics-variant-calling Variant calling
structural variant, sv genomics-sv-detection Structural variant detection
vcf operations genomics-vcf-operations VCF manipulation
alignment, read alignment genomics-alignment Read alignment
variant annotation genomics-variant-annotation Variant annotation
assembly, genome assembly genomics-assembly Genome assembly
phasing, haplotype genomics-phasing Haplotype phasing
cnv calling genomics-cnv-calling CNV analysis
quality control, fastq genomics-qc Sequencing QC
epigenomics, chip-seq, atac-seq genomics-epigenomics Epigenomics analysis

Proteomics Keywords → Skills

Query Keywords Skill Description
mass spec qc, ms qc proteomics-ms-qc Mass spectrometry QC
peptide identification proteomics-identification Peptide identification
protein quantification proteomics-quantification Protein quantification
differential abundance proteomics-de Differential abundance
ptm, post-translational proteomics-ptm PTM analysis
pathway enrichment proteomics-enrichment Pathway enrichment
structural proteomics proteomics-structural Structural proteomics
data import proteomics-data-import Data import

Metabolomics Keywords → Skills

Query Keywords Skill Description
peak detection metabolomics-peak-detection Peak detection
xcms preprocessing metabolomics-xcms-preprocessing XCMS preprocessing
metabolite annotation metabolomics-annotation Metabolite annotation
normalization metabolomics-normalization Data normalization
differential metabolite metabolomics-de Differential analysis
pathway enrichment metabolomics-pathway-enrichment Pathway enrichment
statistical analysis metabolomics-statistics Statistical analysis
quantification metabolomics-quantification Feature quantification

CLI Usage

# Route a natural language query (default: keyword mode)
python skills/orchestrator/omics_orchestrator.py \
  --query "find spatially variable genes" --output output/

# Route by file type (auto-detect domain)
python skills/orchestrator/omics_orchestrator.py \
  --input data.h5ad --output output/

# Specify routing mode: keyword (default), llm, or hybrid
python skills/orchestrator/omics_orchestrator.py \
  --query "find spatially variable genes" --output output/ --routing-mode keyword

python skills/orchestrator/omics_orchestrator.py \
  --query "find spatially variable genes" --output output/ --routing-mode llm

python skills/orchestrator/omics_orchestrator.py \
  --query "find spatially variable genes" --output output/ --routing-mode hybrid

# Run demo to see routing across all domains
python skills/orchestrator/omics_orchestrator.py --demo --output output/

# Run demo with different routing modes
python skills/orchestrator/omics_orchestrator.py --demo --output output/ --routing-mode llm

# List all available skills
python omicsclaw.py list

# List skills in a specific domain
python omicsclaw.py list --domain spatial

Output Format

The orchestrator returns structured JSON with:

{
  "query": "find spatially variable genes",
  "detected_domain": "spatial",
  "routed_skill": "spatial-svg-detection",
  "confidence": 0.95,
  "execution_status": "success",
  "output_dir": "/path/to/output"
}

Examples

Example 1: Spatial query routing (keyword mode)

python skills/orchestrator/omics_orchestrator.py \
  --query "identify tissue regions in my spatial data" \
  --output output/domains/
# Routes to: spatial-domain-identification

Example 2: Single-cell query routing (keyword mode)

python skills/orchestrator/omics_orchestrator.py \
  --query "detect doublets in single cell data" \
  --output output/doublets/
# Routes to: sc-doublet-detection

Example 3: File-based routing

python skills/orchestrator/omics_orchestrator.py \
  --input data.vcf --output output/variants/
# Detects domain: genomics
# Routes to: genomics-vcf-operations

Example 4: LLM-powered routing

python skills/orchestrator/omics_orchestrator.py \
  --query "I want to understand which genes show spatial patterns" \
  --output output/svg/ --routing-mode llm
# Uses LLM to interpret intent
# Routes to: spatial-svg-detection

Example 5: Hybrid routing

python skills/orchestrator/omics_orchestrator.py \
  --query "analyze cell-cell interactions in my tissue" \
  --output output/comm/ --routing-mode hybrid
# Tries keyword first, falls back to LLM if needed
# Routes to: spatial-cell-communication

Example 6: Demo mode with different routing

# Keyword routing demo
python skills/orchestrator/omics_orchestrator.py --demo --output output/demo_keyword/

# LLM routing demo
python skills/orchestrator/omics_orchestrator.py --demo --output output/demo_llm/ --routing-mode llm

# Hybrid routing demo
python skills/orchestrator/omics_orchestrator.py --demo --output output/demo_hybrid/ --routing-mode hybrid

Integration with OmicsClaw

The orchestrator is the primary entry point for the OmicsClaw bot interfaces (Telegram, Feishu) and can be invoked via:

  • CLI: python omicsclaw.py run orchestrator --query "..."
  • Python API: from omicsclaw.routing.router import route_query_unified
  • Bot: Natural language messages automatically routed through orchestrator

Notes

  • Default domain fallback is spatial if detection fails
  • Confidence scoring based on keyword match length and position
  • Supports both exact skill names and natural language queries<!-- ORCH-FOOTER-START -->
  • All 88 skills across 7 domains are accessible through this single interface<!-- ORCH-FOOTER-END -->