Diagram¶

Generates and renders diagrams using Kroki as the unified backend, supporting Mermaid, PlantUML, D2, and 25+ other diagram types.

Short alias: diag

Experimental

This pack is experimental. Behaviour and tool signatures may change between releases.

Highlights¶

Two-stage pipeline (generate source, then render)
Config-driven instructions and templates
Policy rules for LLM guidance
Batch operations for self-hosted backends
Playground URL generation for debugging

Two-Stage Pipeline¶

Function	Description
`diagram.generate_source(source, provider, name)`	Save source for review
`diagram.render_diagram(source, provider, name)`	Render via Kroki
`diagram.get_render_status(task_id)`	Check async render progress

Batch Operations (Self-Hosted Only)¶

Function	Description
`diagram.batch_render(sources)`	Render multiple diagrams concurrently
`diagram.render_directory(directory)`	Render all source files in a directory

Configuration Tools¶

Function	Description
`diagram.get_diagram_policy()`	Get policy rules for diagram generation
`diagram.get_diagram_instructions(provider)`	Get provider-specific guidance
`diagram.get_output_config()`	Get output settings
`diagram.get_template(name)`	Load a named template
`diagram.list_providers(focus_only)`	List available providers

Utility Tools¶

Function	Description
`diagram.get_playground_url(source, provider)`	Get interactive editor URL

Focus Providers¶

Mermaid: Flowcharts, sequences, state diagrams, Gantt, mindmaps
PlantUML: UML diagrams, C4 architecture (via stdlib)
D2: Modern architecture diagrams with auto-layout

All 28+ Kroki providers are available for advanced use.

Key Parameters¶

Parameter	Type	Description
`source`	str	Diagram source code
`provider`	str	mermaid, plantuml, d2, graphviz, etc.
`output_format`	str	svg (default), png, pdf
`output_dir`	str	Override default output directory
`async_mode`	bool	Render in background thread, return task ID for status polling

Configuration¶

Required¶

No required tools.diagram settings.

Optional¶

Key	Type	Default	Description
`tools.diagram.backend.type`	`"kroki"`	`"kroki"`	Backend type. Only Kroki is currently supported.
`tools.diagram.backend.remote_url`	string	`https://kroki.io`	Remote Kroki base URL.
`tools.diagram.backend.self_hosted_url`	string	`http://localhost:8000`	Self-hosted Kroki base URL.
`tools.diagram.backend.prefer`	enum	`remote`	Backend preference: `remote`, `self_hosted`, or `auto`.
`tools.diagram.backend.timeout`	float	`30.0`	Backend request timeout in seconds.
`tools.diagram.policy.rules`	string	built-in policy text	Guidance returned by `diagram.get_diagram_policy()`.
`tools.diagram.policy.preferred_format`	enum	`svg`	Preferred output format: `svg`, `png`, or `pdf`.
`tools.diagram.policy.preferred_providers`	string[]	`["mermaid", "d2", "plantuml"]`	Provider preference order.
`tools.diagram.output.dir`	string	`diagrams`	Output directory for rendered files.
`tools.diagram.output.naming`	string	`{provider}_{name}_{timestamp}`	Filename template.
`tools.diagram.output.default_format`	enum	`svg`	Default output format.
`tools.diagram.output.save_source`	bool	`true`	Save source files alongside rendered output.
`tools.diagram.instructions`	object	`{}`	Provider-specific guidance overrides.
`tools.diagram.templates`	object	`{}`	Named template references.

tools:
  diagram:
    backend:
      prefer: remote
      timeout: 30.0
    output:
      dir: diagrams
      default_format: svg
    policy:
      preferred_providers: [mermaid, d2, plantuml]

Or use include: to load from a shared config file:

include:
  - config/diagram.yaml  # Falls back to global

Defaults¶

If tools.diagram is omitted, OneTool uses the built-in backend, policy, output, and template defaults shown above.

Examples¶

# Generate source for review
diagram.generate_source(
    source="graph TD\n  A --> B",
    provider="mermaid",
    name="flow"
)

# Render diagram
diagram.render_diagram(
    source="graph TD\n  A --> B",
    provider="mermaid",
    name="flow"
)

# Get playground URL for debugging
diagram.get_playground_url(source="graph TD\n  A --> B", provider="mermaid")

# List available providers
diagram.list_providers(focus_only=True)

Templates¶

OneTool includes built-in diagram templates for common patterns. Templates are installed to a diagram-templates/ directory inside your config directory during onetool init.

Available templates:

Name	Provider	Type	Description
`api-flow`	mermaid	sequence	REST API request/response flow
`microservices`	d2	architecture	Microservices architecture layout
`c4-context`	plantuml	c4	C4 system context diagram
`state-machine`	mermaid	state	State machine diagram
`class-diagram`	mermaid	class	Class/data model diagram
`project-gantt`	mermaid	gantt	Project timeline Gantt chart
`feature-mindmap`	mermaid	mindmap	Feature brainstorming mindmap

Load a template:

diagram.get_template(name="api-flow")

Templates can be customized by editing files in the diagram-templates/ directory inside your config directory.

Self-Hosted Setup¶

For batch operations or high-volume rendering, use the Kroki docker-compose from kroki.io:

# Download Kroki docker-compose
curl -LO https://raw.githubusercontent.com/yuzutech/kroki/main/docker-compose.yml

# Start Kroki
docker compose up -d

Then configure onetool.yaml:

tools:
  diagram:
    backend:
      prefer: self_hosted
      self_hosted_url: http://localhost:8000