Bio Orchestrator

Decision Process

When receiving a bioinformatics request:

1. Identify file types: Check file extensions and headers. If the user mentions a file, verify it exists and determine its format.
2. Map to skill: Use the routing table above. If a query implies a two-step scRNA latent workflow, explain the scrna-embedding -> scrna-orchestrator --use-rep X_scvi chain rather than hiding it. If ambiguous, ask the user to clarify.
   • For .csv / .tsv, inspect headers to distinguish raw count matrices and metadata from finished DE / marker result tables.
3. Check dependencies: Before invoking a skill, verify its required binaries are installed (e.g., which samtools).
4. Plan the analysis: For multi-step requests, outline the plan and get user confirmation before proceeding.
5. Execute: Run the appropriate skill(s) sequentially, passing outputs between them.
6. Report: Generate a markdown report with:
   • Methods section (tools used, versions, parameters)
   • Results (tables, figures, key findings)
   • Reproducibility block (commands to re-run, conda env, checksums)
7. Audit log: Append every action to analysis_log.md in the working directory.

File Type Detection

EXTENSION_MAP = {
    ".vcf": "equity-scorer",
    ".vcf.gz": "equity-scorer",
    "directory with SampleSheet + VCF": "illumina-bridge",
    ".fastq": "seq-wrangler",
    ".fastq.gz": "seq-wrangler",
    ".fq": "seq-wrangler",
    ".fq.gz": "seq-wrangler",
    ".bam": "seq-wrangler",
    ".cram": "seq-wrangler",
    ".pdb": "struct-predictor",
    ".cif": "struct-predictor",
    ".h5ad": "scrna-orchestrator",
    ".mtx": "scrna-orchestrator",
    ".mtx.gz": "scrna-orchestrator",
    ".rds": "scrna-orchestrator",
    ".csv": "equity-scorer",  # default for tabular; inspect headers
    ".tsv": "equity-scorer",
}

Header-aware tabular routing:

• gene + log2FoldChange + padj/pvalue → diff-visualizer
• names + scores with optional cluster → diff-visualizer
• sample_id plus design columns like condition / batch → rnaseq-de
• Gene rows plus multiple numeric sample columns → rnaseq-de

Embedding-specific keyword routes:

• scvi
• latent
• embedding
• integration
• batch correction

Bioconductor-specific keyword routes:

• bioconductor
• bioc
• biocmanager
• summarizedexperiment
• singlecellexperiment
• genomicranges
• variantannotation
• annotationhub
• experimenthub

Report Template

Every analysis produces a report following this structure:

# Analysis Report: [Title]

**Date**: [ISO date]
**Skill(s) used**: [list]
**Input files**: [list with checksums]

## Methods
[Tool versions, parameters, reference genomes used]

## Results
[Tables, figures, key findings]

## Reproducibility
[Commands to re-run this exact analysis]
[Conda environment export]
[Data checksums (SHA-256)]

## References
[Software citations in BibTeX]

Multi-Skill Chaining Example

User: "Annotate the variants in sample.vcf and then score the population for diversity"

Plan:

1. VCF Annotator: Annotate sample.vcf with VEP, add ancestry context
2. Equity Scorer: Compute HEIM metrics from annotated VCF
3. Bio Orchestrator: Combine into unified report

Safety Rules

• Never upload genomic data to external services without explicit user confirmation.
• Metadata-only cloud access: platform metadata lookups are acceptable only when genomic payloads remain local.
• Always verify file paths before reading or writing. Refuse to operate on paths outside the working directory unless the user explicitly allows it.
• Log everything: Every command executed, every file read/written, every tool version.
• Human checkpoint: Before any destructive action (overwriting files, deleting intermediates), ask the user.

Example Queries

• "What kind of file is this? [path]"
• "Analyse the diversity in my 1000 Genomes VCF"
• "Run full QC on these FASTQ files and align to hg38"
• "Find recent papers on CRISPR base editing in sickle cell disease"
• "Which Bioconductor package should I use for bulk RNA-seq?"
• "Predict the structure of this protein sequence: MKWVTFISLLFLFSSAYS..."
• "Make my analysis reproducible as a Nextflow pipeline"