Workflows

Workflows are the headline UX of the SDK. Each one chains several REST calls into a single Python function so you can express “upload this folder and train a model” without orchestrating it yourself. Failures fail open — every workflow returns a report you can inspect.

from pictograph import Client
from pictograph.workflows import full_pipeline

client = Client()
report = full_pipeline(
    client,
    dataset_name="road-signs",
    folder="./road_signs",
    classes=[("stop_sign", "bbox"), ("yield", "bbox")],
    pipeline="yolox",
)
print("model:", report.model.id if report.success else report.upload.failures)

When to reach for each

Workflow	What it chains	Use when
full_pipeline	upload → auto-annotate → train	You have a folder of images and want a trained model
upload_dataset_from_folder	walk folder → bulk upload	You only need the upload step (annotations come later)
auto_annotate_dataset	list images → SAM3 batch → save	The dataset is uploaded; you want SAM3 to label it
train_pipeline	create export → train → fetch model	Annotations are saved; you want the model

Report objects, not exceptions

Workflows don’t raise on partial failure. They return dataclasses with per-phase success flags and failure lists. This is intentional — agents and CI jobs need to make decisions on partial outcomes, not unwind on the first 4xx.

report = upload_dataset_from_folder(client, "my-dataset", "./images")
if report.success:
    print(f"Uploaded {report.images_uploaded}")
else:
    for failure in report.failures:
        print(failure.path, failure.reason)

Exceptions are still raised for unrecoverable errors before any work happens (NotFoundError on a missing dataset, ValidationError on a bad pipeline name). See Error handling.