Overview

Each guide answers one question end to end. In order, they follow the path a dataset actually takes.

Guide	The question it answers
Upload a directory of images	How do I get a directory of images in?
SAM3 auto-annotation	How do I label them without drawing every shape?
Tile and augment	How do I reshape the set before training?
Train a model	How do I get weights out?
Deployments	How do I serve the model behind a URL?
Export & conversion	How do I get my data out, or someone else’s in?
Local inference	How do I run a trained model on my own machine?

For a single REST call - one image, one export, one training run - go to the API reference instead.

Methods that chain several calls

Some steps have a one-call method that does the whole thing: walking a directory, polling a job, waiting on an export. Each lives on the resource that owns its noun, so everything hangs off the client you already have.

from pictograph import Client, TrainingRun

client = Client()

client.images.upload_from_directory(
    dataset_name="road-signs",
    directory="./road_signs",
)
client.auto_annotate.dataset(
    dataset_name="road-signs",
    classes=[("stop_sign", "bbox"), ("yield", "polygon")],
)
client.exports.create(
    dataset_name="road-signs",
    name="road-signs-v1",
    format="pictograph",
    include_images=True,
    wait=True,
)
run: TrainingRun = client.training.create(
    dataset_name="road-signs",
    export_name="road-signs-v1",
    pipeline_type="yolox",
    name="road-signs-detector",
)
print("model:", run.model_id or run.status)

Method	What it chains	Guide	Source
client.images.upload_from_directory	walk directory → bulk upload	Upload	images.py
client.auto_annotate.dataset	list images → SAM3 batch → save	SAM3	auto_annotate.py
client.images.tile	download → slice into a grid → upload tiles	Tile and augment	images.py
client.images.augment	download → augment → upload variants	Tile and augment	images.py
client.training.create	train a completed export	Train	training.py

client.annotations.import_coco, client.annotations.import_pascal_voc and client.annotations.import_yolo bring existing labels into a dataset - see Export and conversion.

Everything they do is also reachable one call at a time on the same resources; these just save you the loop. “Workflow” means one thing only: the composable node-graph resource (client.workflows).

What they return

These methods do not raise on partial failure. Each returns a dataclass with counts, a success flag and a failures list, because agents and CI jobs need to act on a partial outcome rather than unwind on the first 4xx. The report types are top-level exports (from pictograph import UploadReport).

report = client.images.upload_from_directory(
    dataset_name="road-signs",
    directory="./road_signs",
)
if report.success:
    print(f"Uploaded {report.images_uploaded}")
else:
    for failure in report.failures:
        print(failure.path, failure.reason)

success means zero failures and at least one item processed, so an empty run reports success=False rather than a silent pass.

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.