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, draft labels from a text prompt, review them, then export and train.
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")
# They are drafts: a person reviews them before you train. Start with the least
# confident (the app's review stage approves an image or sends it back).
for image in client.images.list(
dataset_name="road-signs",
min_confidence_lt=0.5,
):
print("review first:", image.filename)
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 images list road-signs --min-confidence-lt 0.5 # review the drafts, least confident first
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
Metadata
1 maintainer
Release files for pictograph 1.69.125
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | |
|---|---|---|---|---|
| pictograph-1.69.125.tar.gz | 1.3 MB | Without provenance | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| pictograph-1.69.125-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 2.2 MB
Release files / pictograph-1.69.125.tar.gz
| Download URL | pictograph-1.69.125.tar.gz |
|---|---|
| Size | 1.3 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
88bbf4e3a4d41ffea6bd9afae98621de88f00ef8b1be9b7cb775abee6b44f8f4
|
|
BLAKE2b-256 checksum How to use checksums |
941def87a323c3843bcac64ba3671ae3758bc796a72c903cf30008dd226d59f6
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.8
|
Release files / pictograph-1.69.125-py3-none-any.whl
| Download URL | pictograph-1.69.125-py3-none-any.whl |
|---|---|
| Size | 910.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
15ca301b8cf8fc3b134623405da4f0902cc13a772d7d24cfd187c4b7dbf630dd
|
|
BLAKE2b-256 checksum How to use checksums |
326a6e7f68305e6040d1c4b61cad30c9121d09841db16ac08c0bf1196e7d5696
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.8
|
Security for pictograph 1.69.125
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
