Sign in Get started

Overview

Drive Pictograph from Claude, OpenAI, or any framework that speaks JSON Schema. One registry, three integration paths.

View as Markdown

Every Pictograph operation is exposed as both a typed Python SDK call and an agent tool. The 37-tool registry feeds three integration paths.

Source: agents/_registry.py · agents/_toolkit.py

from pictograph.agents import create_toolkit

toolkit = create_toolkit()  # reads PICTOGRAPH_API_KEY

Three integration paths

Bundled adapters - Claude / OpenAI

For raw tool-use loops against the Anthropic or OpenAI SDKs, the adapters return ready-to-pass tool dicts. No extra dependencies.

from pictograph.agents import for_anthropic_messages, for_openai_responses

claude_tools = for_anthropic_messages(toolkit)   # → anthropic.messages.create(tools=...)
openai_tools = for_openai_responses(toolkit)     # → openai.responses.create(tools=...)

# Both paths dispatch results the same way:
result = toolkit.dispatch(
    name="list_datasets",
    args={"limit": 10},
)

For the framework SDKs (claude-agent-sdk, openai-agents) install the extra:

pip install 'pictograph[agents]'
from pictograph.agents import for_claude_agent_sdk, for_openai_agents

claude_sdk_tools = for_claude_agent_sdk(toolkit)   # @tool-decorated callables
openai_sdk_tools = for_openai_agents(toolkit)      # FunctionTool objects

Adapter source: agents/claude.py · agents/openai.py. Full cookbooks: Claude · OpenAI.

Bundled Claude Skill

The SDK ships a Claude Skill (pictograph-cv) with workflow recipes, reference docs, and bash-callable Python scripts. Install it once and Claude auto-discovers it:

pictograph agents install-skill --target claude-code   # → ~/.claude/skills/pictograph-cv/
pictograph agents install-skill --target claude-ai     # → ./pictograph-cv.zip (upload at claude.ai/skills)
pictograph agents install-skill --target both

Update the skill after upgrading the SDK by re-running the install command (it overwrites the existing directory).

Dynamic discovery - tools.json

For frameworks without a bundled adapter (Vercel AI SDK, LangChain, custom dispatchers), fetch the JSON Schema registry directly:

curl -H "X-API-Key: pk_live_..." https://api.pictograph.io/api/v1/developer/tools.json

Each entry has name, description, input_schema, plus metadata (required_role, cost_micro_usd, idempotent). Wire it into your dispatcher and route the model’s tool calls to the matching SDK method. See Dynamic discovery for end-to-end examples.

What’s in the registry

All 37 tools, grouped by category. Full JSON schemas at /docs/api-reference/tools.

Category Tools
Pipelines upload_dataset_from_directory, auto_annotate_dataset, augment_dataset, tile_dataset, train_pipeline
Datasets list_datasets, get_dataset, create_dataset, delete_dataset
Images upload_image, delete_image, review_image, set_image_split, rebalance_dataset_splits
Annotations get_annotations, save_annotations
Auto-annotate auto_annotate_point, auto_annotate_box, auto_annotate_text
Search search_by_tag, search_by_similarity
Exports create_export, list_exports, download_export
Training get_training_status, cancel_training
Models list_models, download_model
Deployments list_deployments, get_deployment, create_deployment, delete_deployment
Notifications list_notifications
Credits get_credit_balance, estimate_credit_cost
Connectors validate_connector, import_from_connector

Guardrails

Three guardrails apply to every dispatch, whichever integration path you use.

  • Role gate (required_role) - registry metadata, but the API re-checks the calling key’s role on every request. A viewer key gets 403 ForbiddenError on any write tool.
  • Credit gate (cost_micro_usd) - paid tools (auto_annotate_dataset, train_pipeline) carry a known cost. Pre-flight with get_credit_balance + estimate_credit_cost and refuse to start when the balance is short.
  • Response cap (max_response_tokens) - results over the cap (default 25k tokens) are truncated with a _truncated marker, so the agent re-calls with narrower filters. Override with create_toolkit(max_response_tokens=N).

These three rules keep agents safe and cheap. Drop them into your system prompt.

1. Before destructive actions (delete_dataset, delete_image,
   cancel_training), restate exactly what will be removed and ask
   for confirmation.

2. Before paid actions (auto_annotate_dataset, train_pipeline),
   call estimate_credit_cost first, then surface the cost and the
   remaining balance. Proceed only if sufficient.

3. For multi-step tasks, prefer the pipeline tools
   (upload_dataset_from_directory, auto_annotate_dataset, train_pipeline)
   over chaining individual resource tools. They handle short-circuit
   on failure and credit gating automatically. Run them as separate
   steps so each result can be checked before paying for the next.

See also

Copied to clipboard