Submit computational biology jobs using natural language with automatic AI routing to the right tools.

AI orchestration lets you describe a drug discovery task in plain English and have the CLI pick the right tools, extract parameters, and run them for you. Reach for it when you don't want to remember exact tool names or parameter syntax, or when a request spans several tools in one step. It runs on the same backend and job history as the rest of the CLI, so orchestrated jobs are monitored and downloaded just like any other. For the full command set, see the CLI overview.

Difficulty

beginner

AI Orchestration (since v0.8.10)

Submit computational biology jobs using natural language with automatic AI routing to the right tools.

Overview

The orchestrate command lets you describe what you want in plain English. An AI model interprets your request, selects the appropriate tools, and executes them:

A plain-English request is interpreted into a tool, its parameters, and a submitted job.

This is the simplest way to use ivybloom — no need to know tool names or parameter syntax.

Usage

# Basic: natural language request
ivybloom orchestrate "Predict the structure of insulin"

# Multi-step request
ivybloom orchestrate "Run ADMET on aspirin and ibuprofen"

# Restrict the tools it may call
ivybloom orchestrate "Dock caffeine against 1ABC" --tools diffdock

# Override the AI model
ivybloom orchestrate "Explain BRCA1 druggability" --model MODEL_ID

PROMPTstringrequired

Natural language description of your request (positional argument, quoted).

--modelstring

Override the AI model used for intent detection and routing.

--toolsstring

Restrict available tools (comma-separated). Example: --tools esmfold,diffdock.

--outputstringdefault: text

Output format: text, json, or yaml (-o shorthand).

--preflightbool

Run health check before orchestration.

--statelessbool

Run one turn with no session persistence (for evaluation and CI).

Examples

Single Tool Invocation

# Protein folding
ivybloom orchestrate "Fold BRCA1"

# ADMET prediction
ivybloom orchestrate "Check drug-likeness of aspirin"

# Molecular docking
ivybloom orchestrate "Dock erlotinib into EGFR binding site"

Multi-Step Requests

The orchestrator can chain multiple tools in a single request:

# Fold, then find binding sites
ivybloom orchestrate "Fold EGFR, find its binding sites, and dock erlotinib"

# Screen multiple compounds
ivybloom orchestrate "Screen aspirin, ibuprofen, and caffeine for drug-likeness"

Restricted Tool Set

Limit the orchestrator to specific tools for predictable behavior:

# Only allow folding and docking
ivybloom orchestrate "Analyze this protein" --tools esmfold,diffdock

Headless Mode

Root flags provide quick single-message interactions without the TUI:

# Single headless message
ivybloom -m "Fold BRCA1"

# Wait for job completion
ivybloom -m "Fold BRCA1" --follow

# Structured JSON output for scripting
ivybloom -m "Fold BRCA1" --agent

For CI/CD automation, combine -m with --agent for structured JSON output. See Agent Mode for the full envelope schema.

Streaming

Stream partial text output as the AI generates its response. --stream-partial-output is a root flag, so use it with -m:

ivybloom -m "Explain the mechanism of EGFR inhibition" --stream-partial-output

This is useful for long explanatory responses where you want to see output incrementally.

AI Model Selection

The orchestrator uses the default AI model from your config. You can override it per-request:

# Use a specific model
ivybloom orchestrate "Fold BRCA1" --model claude-3-opus

# Check available models
ivybloom config models list

Model Pricing

How a model choice affects credit spend is covered in plans and tiers.

See Billing & Credits for cost details and Configuration for BYOK setup.

Output Formats

I'll fold the BRCA1 protein sequence using ESMFold.

Job submitted: job_abc123
Tool: esmfold
Status: running

The structure prediction is in progress. You can monitor it with:
  ivybloom jobs follow job_abc123

AI Orchestration