Command Line Interface¶

The RetroCast CLI provides a unified interface for standardizing, scoring, and analyzing retrosynthesis predictions.

Installation¶

uv tool install retrocast

uv tool install "retrocast[viz]"

pip install retrocast

uv tool install "retrocast[viz]"

Verify installation:

retrocast --version

Ad-Hoc Workflow¶

adapt - Convert Raw Predictions¶

Convert raw output from a supported model into the standardized RetroCast format.

retrocast adapt \
  --input raw_predictions.json.gz \
  --adapter aizynth \ # (1)!
  --output standardized_routes.json.gz \
  --benchmark benchmark.json.gz  # (2)!

1. See available adapters with retrocast list-adapters
2. Optional: Ensures target IDs match exactly

Supported adapters: aizynth, dms, retrostar, synplanner, syntheseus, askcos, retrochimera, dreamretro, multistepttl, synllama, paroutes

score-file - Evaluate Routes¶

Evaluate standardized routes against a stock file.

retrocast score-file \
  --benchmark benchmark.json.gz \
  --routes standardized_routes.json.gz \
  --stock stock_smiles.txt \ # (1)!
  --output scores.json.gz \
  --model-name "My-Experiment"

1. Text file with one canonical SMILES per line

Output: JSON file with boolean flags (is_solved, matches_ground_truth, etc.)

create-benchmark - Generate Benchmarks¶

Generate a benchmark definition file from a simple list of SMILES strings.

retrocast create-benchmark \
  --input targets.txt \ # (1)!
  --name "custom-benchmark" \
  --stock-name "zinc-stock" \
  --output custom-benchmark.json.gz

1. Text file or CSV with SMILES strings

Project Workflow¶

init - Initialize Project¶

Generate a default configuration file and directory structure:

retrocast init

Creates:

• retrocast-config.yaml - Model configuration
• data/ directory structure

Configuration¶

Edit retrocast-config.yaml to register your models:

models:
  dms-explorer: # (1)!
    adapter: dms # (2)!
    raw_results_filename: predictions.json # (3)!
    sampling: # (4)!
      strategy: top-k
      k: 50

1. Model identifier (used in CLI commands)
2. Adapter type (see retrocast list-adapters)
3. Expected filename in data/2-raw/<model>/<benchmark>/
4. Optional: Limit routes per target

models:
  my-model:
    adapter: aizynth
    raw_results_filename: results.json.gz
    sampling:
      strategy: top-k
      k: 100
    # Custom metadata
    metadata:
      version: "2.0"
      training_data: "USPTO-50k"

The Pipeline¶

graph LR
    A[data/2-raw/] --> B[ingest]
    B --> C[data/3-processed/]
    C --> D[score]
    D --> E[data/4-scored/]
    E --> F[analyze]
    F --> G[data/5-results/]

ingest - Standardize Routes¶

Transforms raw model outputs into standardized Route objects.

retrocast ingest \
  --model dms-explorer \
  --dataset paroutes-n1 \
  --anonymize  # (1)!

1. Optional: Hashes the model name for blind review

Input: data/2-raw/<model>/<dataset>/<raw_results_filename>
Output: data/3-processed/<model>/<dataset>/routes.json.gz

Operations:

• Parse raw format via adapter
• Canonicalize SMILES
• Deduplicate routes
• Apply sampling strategy (if configured)

score - Evaluate Routes¶

Evaluates processed routes against benchmark stock.

retrocast score \
  --model dms-explorer \
  --dataset paroutes-n1 \
  --stock-override zinc-stock  # (1)!

1. Optional: Override default benchmark stock

Input: data/3-processed/<model>/<dataset>/routes.json.gz
Output: data/4-scored/<model>/<dataset>/<stock>/scores.json.gz

Annotations added:

• is_solved - All leaves in stock
• matches_ground_truth - Route matches reference
• length - Number of steps
• is_convergent - Contains convergent reactions

analyze - Generate Reports¶

Aggregates scores into statistical reports with confidence intervals.

retrocast analyze \
  --model dms-explorer \
  --dataset paroutes-n1 \
  --make-plots \  # (1)!
  --top-k 1 5 10 50  # (2)!

1. Generates interactive HTML visualizations
2. Customizes K values (default: 1, 3, 5, 10, 20, 50, 100)

Input: data/4-scored/<model>/<dataset>/<stock>/scores.json.gz
Output: data/5-results/<dataset>/<model>/

• report.md - Statistical summary
• *.html - Interactive plots (if --make-plots)

Metrics computed:

• Overall Solvability with 95% CI (bootstrap)
• Top-K accuracy (K ∈ {1, 3, 5, 10, ...})
• Stratified performance by route length
• Ground truth match rate

Verification & Auditing¶

verify - Check Data Integrity¶

Verify the integrity of your data pipeline:

retrocast verify \
  --target data/5-results/paroutes-n1/dms-explorer \
  --deep  # (1)!

1. Optional: Recursively verify entire dependency graph

Verification modes:

retrocast verify --target data/4-scored/model/dataset/

Analyze → Score → Ingest → Raw

retrocast verify --target data/5-results/model/dataset/ --deep

What it detects:

• Data corruption
• Manual file tampering
• Out-of-order execution
• Hash mismatches

Helper Commands¶

list - Show Configured Models¶

Lists all models in retrocast-config.yaml:

retrocast list

Output:

Configured models:
  - dms-explorer (adapter: dms)
  - aizynthfinder-mcts (adapter: aizynth)
  - retro-star (adapter: retrostar)

list-adapters - Show Available Adapters¶

Lists all built-in adapters:

retrocast list-adapters

Output:

Available adapters:
  - aizynth: AiZynthFinder (bipartite graph)
  - dms: DirectMultiStep (recursive dict)
  - retrostar: Retro* (precursor map)
  - synplanner: SynPlanner (bipartite graph)
  - syntheseus: Syntheseus (bipartite graph)
  - askcos: ASKCOS (custom format)
  - retrochimera: RetroChimera (precursor map)
  - dreamretro: DreamRetro (precursor map)
  - multistepttl: MultiStepTTL (custom format)
  - synllama: SynLlama (precursor map)
  - paroutes: PaRoutes (reference format)

info - Show Model Details¶

Display configuration details for a specific model:

retrocast info --model dms-explorer

Output:

Model: dms-explorer
  Adapter: dms
  Raw results filename: predictions.json
  Sampling:
    Strategy: top-k
    K: 50

Command Reference¶

Quick Lookup¶