Run a workflow from Python or the command line

A workflow file runs without the editor. These examples use blur_faces.json from the editor page, which finds faces with Grounding DINO, blurs them and saves the picture.

Run it once

Python
from mozo.workflow import Workflow

workflow = Workflow.load("blur_faces.json")
results = workflow.run(source="example.jpg")

len(results["find"])        # 5: the faces Grounding DINO found

run() returns every node's output, keyed by node id, not only the last one: an intermediate result is often the one worth looking at. workflow.terminals names the nodes at the ends. A node that failed is missing from the results, with everything after it.

From the command line:

Bash
mozo run blur_faces.json --file example.jpg
Text only
Blur faces -- Find every face and blur it.
  1 item in 2.8s (0/s)

--file runs on another image or video than the one saved in the workflow. --test runs one item and describes what every node produced.

Change parameters for one run

Name a parameter to use another value than the one saved in the file:

Python
results = workflow.run(source="example.jpg", threshold=0.5)
Bash
mozo run blur_faces.json --file example.jpg --set threshold=0.5

When two nodes have a parameter of the same name, a bare name is refused rather than guessed at. Address one node's parameter as node.parameter instead, which is how two models side by side get different thresholds:

Python
workflow.run(source="example.jpg", **{"find.threshold": 0.5})
Bash
mozo run blur_faces.json --set find.threshold=0.5

A name that matches nothing raises a KeyError listing the parameters there are. Giving one parameter two ways in one run, threshold and find.threshold, is refused too.

workflow.prompt_parameters names every parameter that takes phrases, as node.parameter keys (here ('find.text',)). Use it to give your own class list to every prompted node without knowing what each node calls it:

Python
prompts = ["face", "licence plate"]
results = workflow.run(source="example.jpg",
                       **{key: prompts for key in workflow.prompt_parameters})

Run it over many images

run_many runs the workflow once per item and yields (item, results) as each one finishes:

Python
from pathlib import Path

for path, results in workflow.run_many(sorted(Path("photos").glob("*.jpg"))):
    print(path, len(results["find"]))

Items are read lazily, so a folder of a million images costs no more memory than a handful. Each item is bound to the workflow's file input (read.source here); pass over= to bind another parameter. By default two items are in flight at once, as a pipeline: the model works on one image while the next is already being decoded. workers=1 runs them strictly one after another.

A failure stops the run. To skip the item instead, pass on_error:

Python
def skip(item, event):
    print(f"{item}: {event.node} failed: {event.error}")

for path, results in workflow.run_many(paths, on_error=skip):
    ...

To stop early, leave the for loop. No further item starts, a model call already running finishes, and the run's threads exit.

For a video, or anything else whose source decides how many items there are, use process(): Videos and folders covers it.

Check it before it runs

Python
check = workflow.check(device="cuda")
check.missing       # files the workflow names that are not there
check.models        # every model it loads: node, family, variant, licence, bytes still to download
check.downloads     # the models with bytes still to download

Every run does this first. A run refuses to start if a file the workflow names is missing, listing all of them at once, and it logs which models it will download and how much. check() answers both without running anything, and with device given it does not even import torch: a host can show what a workflow needs, and under which licences, before anything is fetched.

stream() runs the workflow and reports each node as it starts and finishes, which is how the editor draws progress:

Python
for event in workflow.stream(source="example.jpg"):
    print(event.node, event.status)      # read running, read completed, find running, ...

A failure yields one failed event naming the node and the error, and ends the stream.

Use your own models

Model nodes load through the shared cache behind mozo.get_model unless you say otherwise. Pass models= to any run method to use your own ModelManager, with its device choice and lifetime:

Python
from mozo import ModelManager

models = ModelManager()
workflow.run(source="example.jpg", models=models)

Any function shaped like get_model works too, which is how download progress and cancellation reach a model that loads part way into a run:

Python
workflow.run(source="example.jpg", models=lambda family, variant, **kwargs: models.get_model(
    family, variant, progress=show_progress, cancelled=job.cancelled, **kwargs))

Over HTTP, a running server runs workflows at POST /workflow/run, with the document as the form field workflow, overrides as a JSON object in inputs, and an optional file:

Bash
curl -X POST "http://localhost:8000/workflow/run" \
  -F "workflow=<blur_faces.json" -F 'inputs={"threshold": 0.4}' -F "file=@example.jpg"
JSON
{"results": {"save": null}, "terminals": ["save"]}

HTTP API lists the other workflow routes: validate, stream and process.