Python SDK and CLI for Fastfold jobs, workflows, library operations, and reports.
Install from PyPI:
pip install fastfold-aiOr for development:
pip install -e .Requires Python 3.8+.
Set your API key in the environment:
export FASTFOLD_API_KEY="sk-...your-api-key"You can also pass an API key when creating the client or via the CLI flag --api-key.
The SDK exposes both typed helpers and capability-oriented services:
client.foldfor the simplest fold-job flowclient.jobsfor raw payloads, YAML submission, polling, and rendering helpersclient.workflowsfor generic workflow create/get/status/task-results/execute/YAML APIsclient.libraryfor library item creation and file uploadsclient.openmm,client.openmmdl,client.evolla, andclient.boltzgenfor the most common multi-step workflow flowsclient.reportsfor Slack markdown report submission
For end-to-end walkthroughs, downloadable input files, and additional variants, see:
Create a fold job, wait for completion, then inspect the returned artifacts:
from fastfold import Client
client = Client()
job = client.fold.create(
sequence="LLGDFFRKSKEKIGKEFKRIVQRIKDFLRNLVPRTES",
model="boltz-2",
is_public=True,
)
results = client.jobs.wait_for_completion(job.id, poll_interval=5.0, timeout=900.0)
print(results.job.status)
print(results.cif_url())
print(results.metrics().mean_PLDDT)
print(results.get_viewer_link())Submit an OpenMM workflow from a local structure file and its matching PAE JSON:
from fastfold import Client
client = Client()
workflow = client.openmm.submit_from_manual_files(
pdb_path="./protein.pdb",
pae_path="./pae.json",
simulation_name="AF-P00698",
residue_profile="calvados3",
temp=293.15,
ionic=0.15,
ph=7.5,
step_size_ns=0.01,
sim_length_ns=10.0,
box_length=50,
)
print(workflow.workflow_id)Submit an OpenMMDL workflow from local topology and ligand files:
from fastfold import Client
client = Client()
workflow = client.openmmdl.submit_from_local_files(
topology_path="./KEAP1kd.pdb",
ligand_paths=["./IQK.sdf"],
simulation_name="KEAP1 + IQK",
input_json={
"smallMoleculeMode": "single",
"equilibration": "only_minimization",
"sim_length_ns": 0.05,
"step_time_ps": 0.002,
"failure_retries": 0,
"addWater": False,
"addMembrane": False,
"boxType": "geometry",
"geomPadding": 1.0,
"geometryDropdown": "cube",
"membranePadding": 2.0,
"writeDCD": True,
"dcdFrames": 5,
"pdbInterval_ns": 0.05,
"writeData": False,
"writeCheckpoint": False,
},
)
print(workflow.workflow_id)Upload a .cif / .mmcif / .pdb to your library and start Evolla in one call:
from fastfold import Client
client = Client()
workflow = client.evolla.submit_from_local_file(
"./structure.cif",
"What is the likely function of this domain?",
)
print(workflow.workflow_id)Ask a natural-language question about a structure from an existing fold (uses the same workflow_input shape as the web app: sourceType / targetSource sequence, artifact URL, and ids):
from fastfold import Client
client = Client()
workflow = client.evolla.submit_from_fold_job(
"YOUR_JOB_ID",
"What is the likely function of this domain?",
)
print(workflow.workflow_id)If the CIF URL in job results is not a signed path that embeds your user id, pass source_user_id="..." or set FASTFOLD_EVOLLA_SOURCE_USER_ID. See Evolla.
Create a draft BoltzGen workflow, upload a minimal workflow.yml, and execute it:
from pathlib import Path
from fastfold import Client
client = Client()
draft = client.boltzgen.create_draft(name="boltzgen_demo")
client.boltzgen.upsert_workflow_yml(
draft.workflow_id,
Path("fastfold/examples/boltzgen/minimal.workflow.yml").read_text(),
)
client.boltzgen.execute(draft.workflow_id)
print(draft.workflow_id)For preset bundles, downloadable design-spec files, and multi-spec examples, see BoltzGen.
Send a markdown report and optionally persist it as a library item:
from fastfold import Client
client = Client()
result = client.reports.send_agent_cli_report(
"## Demo Report\n\n- Workflow completed.\n- Artifacts are ready.",
report_name="demo_report",
)
print(result.ok, result.library_item_id)The CLI keeps fastfold-cli fold working, but it now also exposes resource-oriented subcommands.
For the complete command matrix, see CLI.
# Fold job
fastfold-cli fold --sequence "LLGDFFRKSKEKIGKEFKRIVQRIKDFLRNLVPRTES" --model boltz-2
# OpenMM first run from local files
fastfold-cli workflows openmm from-manual-files \
--pdb ./protein.pdb \
--pae ./pae.json \
--simulation-name AF-P00698 \
--force-field calvados3 \
--temperature 293.15 \
--ionic 0.15 \
--ph 7.5 \
--step-size-ns 0.01 \
--sim-length-ns 10 \
--box-length 50
# OpenMMDL from local files
fastfold-cli workflows openmmdl from-local-files \
--topology ./KEAP1kd.pdb \
--ligand ./IQK.sdf \
--simulation-name "KEAP1 + IQK" \
--input-json fastfold/examples/openmmdl/workflow_input.json
# Evolla from a local structure
fastfold-cli workflows evolla from-file ./structure.cif --question "What is the function of this protein?"
# Evolla from fold results
fastfold-cli workflows evolla from-fold-job YOUR_JOB_ID --question "What is the function of this protein?"
# BoltzGen draft
fastfold-cli workflows boltzgen create-draft --name demo
# Report sharing
fastfold-cli reports slack --markdown-file fastfold/examples/reports/sample_report.mdMost create and inspection commands are script-friendly: they print IDs by default, or full JSON with --json.
Small, reusable text assets ship under fastfold/examples/:
fastfold/examples/fold/job_payload.jsonfastfold/examples/openmm/from_manual_files.jsonfastfold/examples/openmm/from_fold_job.jsonfastfold/examples/openmmdl/workflow_input.jsonfastfold/examples/openmmdl/from_local_files.jsonfastfold/examples/openmmdl/quick_water_box.workflow_input.jsonfastfold/examples/openmmdl/quick_membrane.workflow_input.jsonfastfold/examples/evolla/from_fold_job.template.jsonfastfold/examples/boltzgen/minimal.workflow.ymlfastfold/examples/boltzgen/design_spec.example.yamlfastfold/examples/boltzgen/replacements.example.jsonfastfold/examples/fold/boltz2_affinity_input.yamlfastfold/examples/reports/sample_report.md
Larger reference bundles and downloadable preset files live in the docs: