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
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 foundrun() 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:
mozo run blur_faces.json --file example.jpgBlur 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:
results = workflow.run(source="example.jpg", threshold=0.5)mozo run blur_faces.json --file example.jpg --set threshold=0.5When 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:
workflow.run(source="example.jpg", **{"find.threshold": 0.5})mozo run blur_faces.json --set find.threshold=0.5A 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:
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:
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:
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
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 downloadEvery 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:
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:
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:
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:
curl -X POST "http://localhost:8000/workflow/run" \
-F "workflow=<blur_faces.json" -F 'inputs={"threshold": 0.4}' -F "file=@example.jpg"{"results": {"save": null}, "terminals": ["save"]}HTTP API lists the other workflow routes: validate, stream and process.