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.126
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.126.tar.gz | 1.3 MB | Without provenance | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| pictograph-1.69.126-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 2.2 MB
Release files / pictograph-1.69.126.tar.gz
| Download URL | pictograph-1.69.126.tar.gz |
|---|---|
| Size | 1.3 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
69539f13cef1a03ee2836211097406d2e18b15ef09cbe7dcfbf91e1bd7f3e54e
|
|
BLAKE2b-256 checksum How to use checksums |
a9d733ce45e089dca07b1f9406c45217927524e9b8a01d6014788d732b87c143
|
| 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.126-py3-none-any.whl
| Download URL | pictograph-1.69.126-py3-none-any.whl |
|---|---|
| Size | 918.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
da8e42bbfe6c1b2683fb7e59712a1779c1e53ab4569565f5438f0e57210ea409
|
|
BLAKE2b-256 checksum How to use checksums |
97a7e3b06fb487e3bbde4536a4ce53174583fe080eabebb681056e65032cbd7a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.2
|
Security for pictograph 1.69.126
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.
To learn more about protecting yourself from malicious actors, visit our package security documentation.
