Quick start

Install

pip install pictograph

For the CLI + Rich-formatted output:

pip install 'pictograph[cli]'

For the agent toolkit (Claude Agent SDK + openai-agents):

pip install 'pictograph[agents]'

Get an API key

1. Sign in at app.pictograph.io.
2. Navigate to Settings → API Keys.
3. Click Create API Key, give it a role (viewer / member / admin / owner).
4. Copy the key (pk_live_…) — it is only shown once.

export PICTOGRAPH_API_KEY=pk_live_…

Or use the CLI’s interactive setup:

pictograph login

This writes ~/.pictograph/config.toml.

First call

from pictograph import Client

client = Client()  # reads PICTOGRAPH_API_KEY
datasets = client.datasets.list(limit=10)
print(datasets)

End-to-end: upload, annotate, train

The headline workflow — one function call:

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",
)

if report.success:
    print(f"Trained model: {report.model.id}")
else:
    print(report.credit_skip_reason or "see sub-reports")

Each phase short-circuits on failure and the PipelineReport carries every sub-report. See full_pipeline for every parameter.

CLI equivalent

pictograph login                                # one-time
pictograph datasets list
pictograph train start road-signs --pipeline yolox --gpu a10g
pictograph models download <model-id> -o ./yolox.onnx

Next

• Workflows — the four batteries-included helpers
• Agents — wire Pictograph into Claude or OpenAI
• Annotation format — the canonical JSON schema
• Credits — budget gating and cost estimation