cmxflow

Docs CI codecov Python 3.11+ Code style: black License: MIT

Build cheminformatics and computational chemistry pipelines with composable blocks. Tune end-to-end with Bayesian Optimization. Or ask an LLM agent to do it.

Quick examples

Prepare ligands for docking

from cmxflow import Workflow
from cmxflow.sources import MoleculeSourceBlock
from cmxflow.operators import (
    MoleculeStandardizeBlock,
    IonizeMoleculeBlock,
    EnumerateStereoBlock,
    ConformerGenerationBlock,
)
from cmxflow.sinks import MoleculeSinkBlock

# Standardize → ionize (pH 6.4–8.4) → enumerate stereo → generate 3D conformers
workflow = Workflow()
workflow.add(
    MoleculeSourceBlock(),
    MoleculeStandardizeBlock(),
    IonizeMoleculeBlock(),
    EnumerateStereoBlock(),
    ConformerGenerationBlock(),
    MoleculeSinkBlock(),
)
workflow("library.smi", "prepared.sdf")

Dock a congeneric series

Pure-Python docking. Free docking is the default (index_poses=False); scaffold-indexed mode caches poses by Bemis–Murcko scaffold for ~3× faster throughput on congeneric series with consistent pose alignment.

from cmxflow import Workflow
from cmxflow.sources import MoleculeSourceBlock
from cmxflow.operators import ConformerGenerationBlock, MoleculeDockBlock
from cmxflow.sinks import MoleculeSinkBlock
from cmxflow.utils.parallel import make_parallel

workflow = Workflow()
workflow.add(
    MoleculeSourceBlock(),
    ConformerGenerationBlock(),
    make_parallel(
        MoleculeDockBlock(
            receptor="receptor.pdb",
            site_reference="crystal_ligand.sdf",
            index_poses=True,  # omit for free docking
        )
    ),
    MoleculeSinkBlock(),
)
workflow("library.smi", "docked.sdf")

Tune a ligand-based virtual screen

from cmxflow import Workflow
from cmxflow.sources import MoleculeSourceBlock
from cmxflow.operators import MoleculeSimilarityBlock
from cmxflow.scores import EnrichmentScoreBlock
from cmxflow.opt import Optimizer

# Rank a library by 2D similarity to a known active, then tune the
# fingerprint end-to-end to maximize enrichment AUC.
workflow = Workflow()
workflow.add(
    MoleculeSourceBlock(),
    MoleculeSimilarityBlock(queries="crystal_ligand.sdf"),
    EnrichmentScoreBlock(target="active"),
)

opt = Optimizer(workflow, "benchmark.csv")
opt.optimize(n_trials=30, direction="maximize")

print(f"Best enrichment AUC: {opt.best_score:.3f}")
print(opt.best_params)
# Best enrichment AUC: 0.836
# {'fingerprint_type': 'morgan', 'similarity_metric': 'sokal', 'radius': 2, 'nbits': 2545}

The four fingerprint parameters above are searched automatically — every block exposes its mutable parameters to the optimizer.

Or build it conversationally via an LLM agent

claude mcp add cmxflow -- cmxflow-mcp

"How many of the molecules in library.csv pass Lipinski's rules?"

"I need to build a ligand-based virtual screening workflow. I'm not sure if 2D or 3D is better. Can you optimize two workflows?"

"Dock the molecules in hits.csv against receptor.pdb with crystal_ligand.sdf as a reference."

The agent can build, run, and optimize workflows. See Using with Claude for full transcripts.

What's in the box

• 15+ blocks for sourcing, transforming, filtering, clustering, scoring, and docking molecules
• Bayesian optimization of pipeline parameters via Optuna
• Parallel execution for compute-heavy blocks (conformer generation, docking)
• Workflow serialization for save / load / reuse
• An MCP server with five tools: build_workflow, run_workflow, optimize_workflow, manage_workflows, view_structures

Install

pip install cmxflow

MCP server

claude mcp add cmxflow -- cmxflow-mcp

Optional: PyMOL

Required only for the view_structures MCP tool (3D visualization):

conda install -c conda-forge pymol-open-source

Documentation

• Docs site
• Block catalog
• Using with Claude — agent transcripts
• examples/basic_usage.ipynb — full tutorial
• examples/docking/docking.ipynb — docking walkthrough (ILS, scaffold-indexed, and template modes)

Project

MIT licensed. See CONTRIBUTING.md and RELEASING.md.