---
title: Workflows
description: Four end-to-end helpers that chain the lower-level API into one call.
section: Workflows
order: 0
---
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.

```python
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`](/docs/workflows/full-pipeline.md) | upload → auto-annotate → train | You have a folder of images and want a trained model |
| [`upload_dataset_from_folder`](/docs/workflows/upload.md) | walk folder → bulk upload | You only need the upload step (annotations come later) |
| [`auto_annotate_dataset`](/docs/workflows/auto-annotate.md) | list images → SAM3 batch → save | The dataset is uploaded; you want SAM3 to label it |
| [`train_pipeline`](/docs/workflows/train.md) | 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.

```python
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](/docs/error-handling.md).