# Diagram

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

Short alias: `diag`

!!! note "Experimental"
    This pack is experimental. Behaviour and tool signatures may change between releases.

## Highlights

- Two-stage pipeline (generate source, then render) via Kroki
- Config-driven instructions, templates, and policy rules
- 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<string, object> | `{}` | Provider-specific guidance overrides. |
| `tools.diagram.templates` | object<string, object> | `{}` | Named template references. |

```yaml
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:

```yaml
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

```python
# 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:**

```python
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](https://kroki.io/#install):

```bash
# 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`:

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