Skip to content

Adapt Diagrams

Adapt Diagrams — mvp.adapt_diagrams

Cluster: Creative & Media | Type: component | MCP Tools: 40

Overview

Diagram generation block that produces Mermaid, Graphviz, ASCII, D3, Plotly, and SVG diagrams from structured node-edge descriptions, data arrays, or class/state/ER/Gantt specifications. It also exposes explicit advanced backend-native operations for Mermaid/DOT/PlantUML source and Plotly/D3 specs. Output can be plain text (diagram source), SVG markup, self-contained HTML, or base64 PNG depending on the requested format and available renderers. Persists diagrams and reusable templates in SQLite so generated artefacts can be retrieved and version-controlled by name.

Runtime renderer availability is discoverable through get_info and stats via curated_ops, advanced_ops, renderer_capabilities, dependencies, missing_dependencies, degraded_capabilities, and unsupported_backend_features. Renderer fallback is surfaced as degraded=True with a stable degradation_reason, warning_card, completion_state, and evidence metadata.

When to use:

  • Turning goal decomposition trees or pipeline graphs into Mermaid flowcharts for documentation
  • Generating sequence diagrams, ER diagrams, or Gantt charts from structured agent data
  • Producing D3 or Plotly charts from JSON datasets as part of a reporting workflow
  • Saving diagram templates for repeated use across multiple pipeline runs

Example:

from mvp.adapt_diagrams import AdaptDiagramsBlock, DiagramInput

block = AdaptDiagramsBlock(name="diagrams")
result = block.infer(DiagramInput(
    op="mermaid_flowchart",
    title="Data Pipeline",
    nodes=[{"id": "A", "label": "Ingest"}, {"id": "B", "label": "Transform"}, {"id": "C", "label": "Store"}],
    edges=[{"from": "A", "to": "B"}, {"from": "B", "to": "C"}],
    direction="LR",
))
# result.value.text → Mermaid flowchart source string

Works well with: adapt_visualisation, adapt_webpage, goal_engine

Launch Notes

  • Interactive D3 and Plotly output depends on CDN access unless DIAGRAMS_D3_CDN and DIAGRAMS_PLOTLY_CDN point to internal or local assets.
  • Graphviz image rendering still depends on optional Python and system Graphviz installs. When those renderers are unavailable, the component degrades to DOT text output with top-level degradation fields and warning metadata.
  • Advanced native operations are constrained adapter escape hatches, not arbitrary execution surfaces. D3 JavaScript passthrough and network-backed PlantUML rendering remain disabled unless separately safety-reviewed.
  • adapt_diagrams is a pragmatic diagram generator, not a polished visual design tool. It is best for workflow diagrams, architecture sketches, reporting charts, and structured documentation artefacts.
  • First-user onboarding should include known-good examples for each common diagram type. Non-technical users need reliable input shapes they can copy and adapt.

Public API

AdaptDiagramsBlock(AIBlock[DiagramInput, DiagramOutput, None])

Dispatch diagram generation to the appropriate backend.

Field Type Default
name str 'adapt_diagrams'
resource_bounds ResourceBounds \| None None
usage ResourceUsage field(default_factory=ResourceUsage)
max_input_bytes int 2 * 1024 * 1024

Methods:

infer(data: DiagramInput) -> Result[DiagramOutput]

DiagramInput(BaseModel)

Input for diagram generation operations.

Field Type Default
op str 'mermaid_flowchart'
title str ''
brief str ''
nodes list[dict[str, Any]] []
edges list[dict[str, Any]] []
direction str 'TD'
style str ''
template_name str ''
data_json str '[]'
source str ''
spec dict[str, Any] {}
spec_json str ''
x_field str ''
y_field str ''
fields list[str] []
classes list[dict[str, Any]] []
states list[dict[str, Any]] []
entities list[dict[str, Any]] []
tasks list[dict[str, Any]] []
network_data dict[str, Any] {}
svg_elements list[dict[str, Any]] []
dashboard_specs list[dict[str, Any]] []
output_format str 'text'
fail_on_error bool False
output_path str ''
diagram_id str ''
limit int 20

DiagramOutput(BaseModel)

Output from diagram generation operations.

Field Type Default
op str required
text str ''
svg str ''
html str ''
image_base64 str ''
output_path str ''
diagram_id str ''
format str ''
backend str ''
metadata dict[str, Any] {}
diagrams list[dict[str, Any]] []
templates list[dict[str, Any]] []
recommendation dict[str, Any] {}
agentic_evidence dict[str, Any] {}
degraded bool False
degradation_reason str \| None None

AdaptDiagramsMCPBlock(AIBlock[MCPDiagramInput, MCPDiagramOutput, dict])

31-op diagram MCP block with SQLite persistence.

Field Type Default
name str 'adapt_diagrams_mcp'
state dict field(default_factory=dict)
db_path str field(default_factory=lambda: os.environ.get('DIAGRAMS_DB_PATH', _DEFAULT_DB))
resource_bounds ResourceBounds field(default_factory=ResourceBounds)
usage ResourceUsage field(default_factory=ResourceUsage)

Methods:

infer(data: MCPDiagramInput) -> Result[MCPDiagramOutput]

MCPDiagramRecord(BaseModel)

A single metadata record returned from DiagramStore queries.

Field Type Default
id str required
record_type str required
name str required
content str required
tags str ''
timestamp str ''
metadata dict[str, Any] {}

MCPDiagramInput(BaseModel)

Input to AdaptDiagramsMCPBlock — 33 schema ops (31 exposed as MCP tools).

Field Type Default
op Literal['mermaid_flowchart', 'mermaid_sequence', 'mermaid_class', 'mermaid_state', 'mermaid_er', 'mermaid_gantt', 'graphviz_graph', 'graphviz_digraph', 'plantuml_activity', 'plantuml_sequence', 'plantuml_class', 'plantuml_component', 'ascii_box', 'ascii_tree', 'ascii_table', 'd3_bar', 'd3_network', 'd3_treemap', 'plotly_chart', 'plotly_3d', 'html_dashboard', 'svg_compose', 'diagram_save', 'diagram_get', 'diagram_list', 'diagram_delete', 'template_list', 'template_get', 'stats', 'get_info', 'recommend', 'auto', 'list_patterns', 'mermaid_render_source', 'graphviz_render_source', 'plantuml_render_source', 'plotly_render_spec', 'd3_render_spec', 'ops', 'help'] required
brief str ''
title str ''
nodes list[dict[str, Any]] []
edges list[dict[str, Any]] []
direction str 'TD'
style str ''
template_name str ''
data_json str '[]'
source str ''
spec dict[str, Any] {}
spec_json str ''
x_field str ''
y_field str ''
fields list[str] []
classes list[dict[str, Any]] []
states list[dict[str, Any]] []
entities list[dict[str, Any]] []
tasks list[dict[str, Any]] []
network_data dict[str, Any] {}
svg_elements list[dict[str, Any]] []
dashboard_specs list[dict[str, Any]] []
output_format str 'text'
output_path str ''
diagram_id str ''
name str ''
tags_csv str ''
limit int 20
fail_on_error bool False
content_text str ''
content_svg str ''
content_html str ''
source_op str ''
query str ''
top_k int 10

MCPDiagramOutput(BaseModel)

Output from AdaptDiagramsMCPBlock.

Field Type Default
op str required
text str ''
svg str ''
html str ''
image_base64 str ''
output_path str ''
diagram_id str ''
format str ''
backend str ''
metadata dict[str, Any] {}
diagrams list[dict[str, Any]] []
templates list[dict[str, Any]] []
records list[dict[str, Any]] []
recommendation dict[str, Any] {}
agentic_evidence dict[str, Any] {}
message str ''
found bool False
count int 0
degraded bool False
degradation_reason str \| None None

DiagramStore

SQLite-backed store for the adapt_diagrams MCP sub-package.

Constructor:

Parameter Type Default
db_path str ':memory:'

Methods:

save_diagram(op: str, text: str = '', svg: str = '', html: str = '', fmt: str = 'text', backend: str = '', name: str = '', tags: str = '', metadata: dict | None = None, diagram_id: str = '') -> str

Save a diagram. Returns the diagram id.

get_diagram(diagram_id: str) -> dict[str, Any] | None

Retrieve a diagram by id.

list_diagrams(tags: str = '', limit: int = 20) -> list[dict[str, Any]]

List diagrams, optionally filtered by tags.

delete_diagram(diagram_id: str) -> bool

Delete a diagram and its history by id. Returns True if deleted.

get_diagram_history(diagram_id: str, limit: int = 50) -> list[dict[str, Any]]

Return previous versions of a diagram, newest first.

save_template(name: str, op: str, spec: dict | None = None, description: str = '', tags: str = '') -> str

Save a template. Returns the template id.

get_template(name: str) -> dict[str, Any] | None

Retrieve a template by name.

list_templates(limit: int = 50) -> list[dict[str, Any]]

List all templates.

stats() -> dict[str, Any]

Return table counts and quota info.

vacuum() -> None

Run SQLite VACUUM to reclaim disk space after bulk deletions.

close() -> None

Close the database connection.

MCP Tools

Operation Source
mermaid_flowchart diagrams_mcp
mermaid_sequence diagrams_mcp
mermaid_class diagrams_mcp
mermaid_state diagrams_mcp
mermaid_er diagrams_mcp
mermaid_gantt diagrams_mcp
graphviz_graph diagrams_mcp
graphviz_digraph diagrams_mcp
plantuml_activity diagrams_mcp
plantuml_sequence diagrams_mcp
plantuml_class diagrams_mcp
plantuml_component diagrams_mcp
ascii_box diagrams_mcp
ascii_tree diagrams_mcp
ascii_table diagrams_mcp
d3_bar diagrams_mcp
d3_network diagrams_mcp
d3_treemap diagrams_mcp
plotly_chart diagrams_mcp
plotly_3d diagrams_mcp
html_dashboard diagrams_mcp
svg_compose diagrams_mcp
diagram_save diagrams_mcp
diagram_get diagrams_mcp
diagram_list diagrams_mcp
diagram_delete diagrams_mcp
template_list diagrams_mcp
template_get diagrams_mcp
stats diagrams_mcp
get_info diagrams_mcp
recommend diagrams_mcp
auto diagrams_mcp
list_patterns diagrams_mcp
mermaid_render_source diagrams_mcp
graphviz_render_source diagrams_mcp
plantuml_render_source diagrams_mcp
plotly_render_spec diagrams_mcp
d3_render_spec diagrams_mcp
ops diagrams_mcp
help diagrams_mcp