Pictograph
Label images, train vision models, run them anywhere.
Docs · Quick start · API reference · App
Four ways in. Same API underneath, so you can move between them.
| Python | pip install pictograph, this repo |
| CLI | pip install "pictograph[cli]" · reference |
| REST | Any language, X-API-Key header · reference |
| Claude skill | Let an agent drive it · guide |
Quick start
pip install pictograph
Upload a directory, label it from a text prompt, train, predict.
from pictograph import AnnotateReport, Client, TrainingRun, UploadReport
client = Client() # reads PICTOGRAPH_API_KEY
uploaded: UploadReport = client.images.upload_from_directory(
dataset_name="road-signs",
directory="./road_signs",
)
print(f"{uploaded.images_uploaded} images uploaded")
labelled: AnnotateReport = client.auto_annotate.dataset(
dataset_name="road-signs",
classes=[("stop_sign", "bbox"), ("yield", "bbox")],
)
print(f"{labelled.annotations_added} annotations added")
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("Trained model:", run.model_id or run.status)
A class is a (name, output_type) pair, where the output type is bbox,
polygon or tag, because auto-annotation has to know what shape to produce.
Training runs on an export, never on a dataset directly: you create the
export, see what went into it, then train that.
The same thing from the shell:
pictograph login
pictograph images upload-directory road-signs ./road_signs
pictograph auto-annotate batch road-signs --images 001.jpg,002.jpg --classes "stop_sign:bbox"
pictograph exports create road-signs --name road-signs-v1 -f pictograph --include-images
pictograph train start road-signs road-signs-v1 --pipeline yolox --gpu a10g
pictograph models download "road-signs-detector" -o ./yolox.onnx
Or over REST:
curl -s https://api.pictograph.io/api/v1/developer/datasets/ \
-H "X-API-Key: $PICTOGRAPH_API_KEY"
Resources are addressed by name everywhere. There are no IDs to look up first.
Typed
Responses are Pydantic models. Failures are typed exceptions.
from pictograph.exceptions import NotFoundError, PaymentRequiredError, RateLimitError
try:
client.datasets.get(name="does-not-exist")
except NotFoundError:
...
Transient failures retry with backoff, and writes carry an idempotency key so a retry cannot apply twice.
Async
Every method has an async twin with the same signature.
import asyncio
from pictograph import AsyncClient
async def main() -> None:
async with AsyncClient() as client:
datasets = await client.datasets.list(limit=5)
print([d.name for d in datasets])
asyncio.run(main())
Run models on your own hardware
from pictograph import get_model
model = get_model(name="signs-detector", task="object_detection")
result = model.predict(image="test.jpg")
Weights download and cache on first use. ONNX, PyTorch, ExecuTorch and TensorRT are supported targets. See local inference.
Agents
pip install "pictograph[agents]"
pictograph agents install-skill --target claude-code
from pictograph.agents import Toolkit
tools = Toolkit(client).as_anthropic_tools() # or .as_openai_tools()
Offline utilities
No network needed, so an existing local dataset can be brought into typed models before uploading anything.
pictograph.formats |
Read and write COCO, YOLO, Pascal VOC |
pictograph.metrics |
Score detections against ground truth by IoU |
pictograph.augment |
Transform images, remapping annotation geometry with them |
pictograph.tile |
Slice images into a grid, clipping annotations per tile |
Documentation
Full reference at pictograph.io/docs.
Quick start · Installation · Authentication · API reference · CLI · Agents · Annotation format · Auto-annotation · Local inference · Deployments · Export conversion · Async client · Error handling · Rate limits
Requires Python 3.10 or newer. Extras: [cli], [agents], [inference],
[torch], [all].
Contributing, security, license
CONTRIBUTING.md has the development setup and the checks a change must pass. Report vulnerabilities per SECURITY.md, not as a public issue.
The SDK is MIT licensed, see LICENSE. Two model architectures are vendored so local inference works without pulling their full training stacks; both are Apache-2.0 and keep their own licence and attribution alongside the code:
| Component | Upstream | Licence |
|---|---|---|
pictograph.inference._rfdetr |
RF-DETR (Roboflow) | Apache-2.0 · NOTICE |
pictograph.inference._yolox |
YOLOX (Megvii) | Apache-2.0 · NOTICE |
1 maintainer
Release files for pictograph 1.69.83
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| pictograph-1.69.83.tar.gz | 1.0 MB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| pictograph-1.69.83-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 1.8 MB
Release files / pictograph-1.69.83.tar.gz
| Download URL | pictograph-1.69.83.tar.gz |
|---|---|
| Size | 1.0 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
79dc395533056c72db716b4213c0bd2ad794906f1508d3a8444ee8cf70714cfa
|
|
BLAKE2b-256 checksum How to use checksums |
f9eb8a5f1248f9d6e8a8db442fa046a460121550f513f2dbd364d57182ab90da
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.2
|
Release files / pictograph-1.69.83-py3-none-any.whl
| Download URL | pictograph-1.69.83-py3-none-any.whl |
|---|---|
| Size | 747.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
00f0b87113d3e617ace0e60a116a4261e070645f6d4a5894cca5187ace56032f
|
|
BLAKE2b-256 checksum How to use checksums |
9d4c4986651d0deb63440f327ba2f3ecf80448cee2acb36dca62d88857030d64
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.2
|
