Evolla

Use Evolla to run evolla_v1 workflows — a single inference_evolla task answers a natural-language question about a structure, using the configured Evolla model inside the worker image.

Submit a run (SDK and CLI)

Python — local structure file (uploads to your library, then runs with targetSource: upload, same as the web UI):

wf = client.evolla.submit_from_local_file(
    "./structure.cif",
    "What structural features stand out in this fold?",
    name="Evolla upload demo",
)
print(wf.workflow_id)

Python — from a completed fold job (infers job run id and default protein sequence; resolves sourceUserId from the signed CIF path when possible):

from fastfold import Client

client = Client()
wf = client.evolla.submit_from_fold_job(
    "YOUR_JOB_ID",
    "What is the function of this protein?",
)
print(wf.workflow_id)

If job results expose a CIF URL whose path is not /{userId}/{jobRunId}/{sequenceId}/model.cif, pass source_user_id="YOUR_UUID" or set FASTFOLD_EVOLLA_SOURCE_USER_ID (or FASTFOLD_SOURCE_USER_ID).

Python — arbitrary workflow_input (upload, PDB, UniProt, library, or full sequence payload), same as the API:

wf = client.evolla.submit(
    {
        "targetSource": "pdb",
        "pdbId": "1ABC",
        "question": "What structural class is this?",
    },
    name="Evolla PDB demo",
)

CLI

fastfold-cli workflows evolla from-file ./structure.cif --question "What is the function of this protein?"
fastfold-cli workflows evolla from-fold-job YOUR_JOB_ID --question "What is the function of this protein?"
fastfold-cli workflows evolla from-input --file ./workflow_input.json --name "Evolla from file"

Packaged template: fastfold/examples/evolla/from_fold_job.template.json (replace placeholders). For the REST shape, see Create Workflow Run.

Metrics and Artifacts

Evolla does not use the shared POST /v1/workflows/node/output-schema catalog for inference_evolla today (that endpoint is used for BoltzGen composer fields and OpenMM-class MD metrics). Read answers from result_raw_json on each completed task instead.

Task results (GET /v1/workflows/task-results/<workflow_id>)

In tasksResults[], rows with task_type inference_evolla expose:

output_library_items is typically empty for Evolla; the primary artifact is the structured JSON above. Long-form logs may also be linked from the workflow record when the deployment uploads them.

Reading task results

from fastfold import Client

client = Client()
out = client.workflows.task_results(workflow_id)
print(out.raw)

fastfold-cli workflows task-results <workflow_id>
fastfold-cli workflows task-results <workflow_id> --json

Linked workflows and drafts

When Evolla is launched from a fold result, the API can list other workflows for the same job/run and update a draft question before execute:

• GET /v1/workflows/evolla/linked-history — history keyed by source_job_id, source_job_run_id, and source_sequence_id (API ref)
• GET /v1/workflows/evolla/linked-previews — lightweight linked rows by job/run (API ref)
• PATCH /v1/workflows/evolla/<workflow_id>/draft-question — set question on a DRAFT workflow (API ref)

Python (client.workflows):

• linked_history(source_job_id=..., source_job_run_id=..., source_sequence_id=..., limit=...)
• linked_previews(source_job_id=..., source_job_run_id=..., limit=...)
• update_evolla_draft_question(workflow_id, question)

See also

• Create Workflow Run — raw workflow_name: evolla_v1 payloads
• /workflows/getWorkflowTaskResults