# Pictograph SDK

> Agent-native computer-vision annotation platform. Python SDK wraps a REST
> API exposing dataset upload, SAM3 auto-annotation, model training, and
> exports. The SDK ships a tool registry consumable by Claude / OpenAI /
> any agent stack via a JSON-schema endpoint.

## Documentation

### Agents

- [Agents](https://pictograph.io/docs/agents.md): Drive Pictograph from Claude, OpenAI, or any framework that speaks JSON Schema. One registry, three integration paths.
- [Claude](https://pictograph.io/docs/agents/claude.md): Drive Pictograph from Anthropic's SDK or the Claude Agent SDK. Both backed by the same registry.
- [OpenAI](https://pictograph.io/docs/agents/openai.md): Drive Pictograph from the OpenAI SDK or the openai-agents framework.
- [Dynamic discovery](https://pictograph.io/docs/agents/dynamic-discovery.md): Use `GET /api/v1/developer/tools.json` to wire Pictograph into any agent framework that speaks JSON Schema - no Pictograph-specific adapter required.
- [Agent cookbook](https://pictograph.io/docs/agents/cookbook.md): Recipe-style examples - credit-aware training, V7 import + re-annotate, batch SAM3 with progress, multi-class export pipelines.

### API Reference

- [API reference](https://pictograph.io/docs/api-reference.md): Every SDK resource, one page each. Each method maps 1:1 to a REST endpoint.
- [Datasets](https://pictograph.io/docs/api-reference/datasets.md): The full dataset lifecycle - list, fetch, create, update, archive, delete, insights, near-duplicates, bulk download, cold storage.
- [Images](https://pictograph.io/docs/api-reference/images.md): List a dataset's images, and upload, fetch, download, tag, review, split, or delete them.
- [Annotations](https://pictograph.io/docs/api-reference/annotations.md): Read, save, and delete annotations on individual images. Save is a full overwrite - pass the complete list every time.
- [Annotation comments](https://pictograph.io/docs/api-reference/annotation-comments.md): Review comments pinned to a single annotation - list, create, edit, resolve, delete. The programmatic side of annotation QA.
- [Auto-annotate](https://pictograph.io/docs/api-reference/auto-annotate.md): SAM3 point, box, and text prompts plus async batch jobs for AI-generated annotations.
- [Search](https://pictograph.io/docs/api-reference/search.md): Find images by visual similarity to a reference image, or by automatic content tags (objects / scenes / attributes).
- [Batch](https://pictograph.io/docs/api-reference/batch.md): Bulk move, copy, delete, and update across many images in one round-trip.
- [Exports](https://pictograph.io/docs/api-reference/exports.md): Build and download dataset exports in 12 formats, including COCO, YOLO, Pascal VOC, CVAT and canonical Pictograph JSON.
- [Training](https://pictograph.io/docs/api-reference/training.md): Spawn, poll, and cancel training runs against a completed export.
- [Models](https://pictograph.io/docs/api-reference/models.md): List trained CV models in your organization and download their ONNX weights.
- [Model evaluations](https://pictograph.io/docs/api-reference/model-evaluations.md): Score a trained detection or instance-segmentation model against an export's ground truth - precision, recall, F1, mAP, confusion matrix, worst images.
- [Deployments API](https://pictograph.io/docs/api-reference/deployments.md): Stand a trained model up as an always-on inference endpoint, billed by uptime, and call it directly.
- [Workflows API](https://pictograph.io/docs/api-reference/workflows.md): Run a node graph (source to model to filter to track to step to sink) over an image, a video, or a dataset. Create, run, poll, and read artifacts headlessly.
- [Webhooks](https://pictograph.io/docs/api-reference/webhooks.md): Register HTTPS endpoints that receive signed, retried event deliveries (such as workflow_run.completed). Verify the HMAC signature, inspect the delivery log, and replay failed deliveries.
- [Credits](https://pictograph.io/docs/api-reference/credits.md): USD-denominated compute credits - balance, ledger history, per-operation usage, and pre-flight cost estimation.
- [Connectors](https://pictograph.io/docs/api-reference/connectors.md): Import datasets from V7 (Darwin) and Roboflow into Pictograph. Annotations are converted to canonical Pictograph JSON automatically.
- [Video](https://pictograph.io/docs/api-reference/video.md): Upload videos, probe metadata, and extract frames as images into a dataset.
- [Organizations](https://pictograph.io/docs/api-reference/organizations.md): Read the active organization, manage members, and send or revoke invites. Admin or owner role required for mutations.
- [Notifications](https://pictograph.io/docs/api-reference/notifications.md): The organization event feed - poll for training complete, export ready, and batch job events instead of tracking every run id.
- [Directories](https://pictograph.io/docs/api-reference/directories.md): Inspect and edit a dataset's virtual directory tree - list, tree, stats, create, rename, delete.
- [Tasks](https://pictograph.io/docs/api-reference/tasks.md): Annotation tasks and the per-annotator contribution breakdown - who annotated how many images, active editing time, and annotations authored - exportable for audit and billing.
- [API keys](https://pictograph.io/docs/api-reference/api-keys.md): Programmatic API key management. Requires admin or owner role on the calling key.
- [Agent tool registry](https://pictograph.io/docs/api-reference/tools.md): Fetch the JSON Schema array of every agent-callable tool. The same registry the Python SDK exposes via Toolkit.as_json_schema().
- [Result models](https://pictograph.io/docs/api-reference/results.md): Every object the SDK returns, with its Pydantic definition and a link to the source. Generated from the shipped package, so it cannot drift.

### Reference

- [Error handling](https://pictograph.io/docs/error-handling.md): The exception hierarchy, when each error fires, and how to retry safely.
- [Pictograph annotation format](https://pictograph.io/docs/annotation-format.md): The canonical Pictograph JSON schema for bbox, polygon, polyline, keypoint (incl. multi-joint pose via `instance_id`) and oriented-box (rotated) annotations. Class labels go in `name` (not `class`); polygons use multi-ring `paths`.
- [CLI reference](https://pictograph.io/docs/cli.md): Every `pictograph` subcommand, mirroring the SDK 1:1. Install via `pip install 'pictograph[cli]'`.
- [Async client](https://pictograph.io/docs/async-client.md): pictograph.AsyncClient - the asyncio twin of Client. Same resources, same auth, every I/O method a coroutine, HTTP/2 connection pooling.
- [Rate limits](https://pictograph.io/docs/rate-limits.md): Per-tier request budgets, the response headers, and how the SDK handles 429s.

### Guides

- [Guides](https://pictograph.io/docs/guides.md): Task-shaped walkthroughs - get images in, label them, reshape the set, train a model, and serve it.
- [Upload a directory of images](https://pictograph.io/docs/guides/upload.md): Walk a local directory and upload every image to a dataset - parallel, idempotent, and directory-structure aware.
- [SAM3 Auto-Annotation](https://pictograph.io/docs/sam3-auto-annotation.md): Auto-annotate images with SAM3 using point, box, and text prompts - one image or a whole dataset, from the editor, SDK, or CLI.
- [Tile and augment a dataset](https://pictograph.io/docs/guides/augment.md): Reshape a dataset before training - slice images into a grid for small-object detection, or generate flipped, rotated and colour-jittered variants. Annotation geometry follows.
- [Train a model](https://pictograph.io/docs/guides/train.md): Create an export and train a model in one call - detection, segmentation, keypoint, or classification, on a managed GPU.
- [Deployments](https://pictograph.io/docs/deployments.md): Turn a trained model into an always-on inference endpoint - per-deployment bearer token, one /predict URL, billed by uptime. SDK, CLI, and REST.
- [Export & Format Conversion](https://pictograph.io/docs/export-conversion.md): Export a Pictograph dataset to any of 12 annotation formats, and convert COCO, YOLO and Pascal VOC annotations offline with no API call and no third-party library.

### Get Started

- [Documentation | Computer Vision SDK, CLI and REST API](https://pictograph.io/docs/index.md): Pictograph developer docs. Annotate images with SAM3, train detection and segmentation models, and deploy inference APIs from a typed Python SDK, CLI, and REST API.
- [Installation](https://pictograph.io/docs/installation.md): Install the Pictograph SDK and its optional extras (CLI, agents, local inference).
- [Quick start](https://pictograph.io/docs/quick-start.md): Install the Pictograph SDK, get an API key, and run your first end-to-end pipeline in five minutes.
- [Authentication](https://pictograph.io/docs/authentication.md): API key format, resolution order, and the role-based permission model.
- [Local inference](https://pictograph.io/docs/local-inference.md): Run your trained Pictograph models on your own hardware - PyTorch, ExecuTorch, ONNX Runtime or TensorRT, with the same typed result from every one - then score them, feed a PyTorch DataLoader, and draw the results.

## External resources

- [Bundled `tools.json`](https://api.pictograph.io/api/v1/developer/tools.json): Agent tool registry as JSON Schema (requires API key).
- [GitHub](https://github.com/pictograph-io/pictograph-sdk): SDK source.
- [PyPI](https://pypi.org/project/pictograph/): `pip install pictograph`.