maf-sandbox-drawio

Experimental. Releases before 1.0 may change or remove APIs. Importing this package emits MafSandboxDrawioExperimentalWarning.

Create an editable diagram.drawio from model-supplied XML. The create_drawio(xml: str) tool validates draw.io cells, applies layout when needed and delivers the file through the host's OutputSink.

Requires Python 3.12–3.14.

pip install maf-sandbox-drawio

Attach the tool

from maf_sandbox_drawio import make_drawio_tools

tools = make_drawio_tools(
    router,
    agent_id="diagram-designer",
    context=context,
    sink=sink,
    image="drawio-sandbox:local",
    preserve_layout=True,
    direction="TB",
)

The host supplies the router, CallerContext and sink. The model supplies only XML; storage and layout settings belong to the host.

Use make_file_system_sink(output_directory, existing="replace") to replace the previous diagram, or a per-call sink to retain separate outputs. The result contains the sink's display reference after delivery.

Build the image from the repository root:

docker build -t drawio-sandbox:local images/drawio-sandbox

The image needs Python and Graphviz. The kind requires a POSIX backend with EXEC, FILES_IN and FILES_OUT. It uses closed network access and the host's isolation floor. Core disposes after each call by default.

For Docker, use await DockerSandboxBackend.create(config) so the backend declares POSIX. The plain constructor does not declare an OS family.

Model input

Accepts one uncompressed mxGraphModel or an mxfile containing uncompressed pages:

<mxGraphModel>
  <root>
    <mxCell id="0"/>
    <mxCell id="1" parent="0"/>
    <mxCell id="a" value="Start" vertex="1" parent="1"/>
    <mxCell id="b" value="Finish" vertex="1" parent="1"/>
    <mxCell id="edge" edge="1" source="a" target="b" parent="1"/>
  </root>
</mxGraphModel>

The output keeps native editable shapes, connectors, labels, styles, IDs, metadata and layers. It does not render a preview or fetch external resources. XML references remain in the artifact, so validation is not content sanitization.

Layout policy

Complete geometry needs positive width and height for each vertex. Missing x or y means zero. Overlapping vertices are accepted. Missing connector waypoints do not trigger layout; missing edge geometry receives standard relative geometry.

Automatic layout handles flat flowcharts and component graphs, including cycles and disconnected components. direction="TB" places the graph top to bottom; "LR" places it left to right.

Graphviz chooses positions and connector paths. Supplied dimensions and rotation are retained; missing dimensions use 160 by 80. Automatic layout replaces routing hints while keeping appearance styles.

Nested groups, relative ports, edge-label vertices, collapsed cells and detached edges require complete geometry with preservation enabled. They are refused when automatic layout is needed.

The tool provides no sequence, BPMN or ER-specific layout, automatic label fitting or guarantee against every overlap. Give large labels explicit dimensions. Preserved geometry keeps its values, not byte-for-byte XML formatting.

Validation and limits

Every page is checked before and after layout. Invalid IDs, parent cycles, broken endpoints, unsupported geometry and non-finite coordinates are refused. DTDs, entities and compressed pages are refused too.

A failure on any page prevents delivery of the entire artifact. create_drawio returns separate content items: trusted completion and verdict, any fixed explanation, and untrusted sink display text or converter diagnostics. The verdict is created after delivery and refused for rejected XML or unsupported layout requests. Invalid tool arguments, execution failures, missing output and delivery failures remain incomplete with no verdict. The host sets confidentiality and destination policy.

Verify all four layout-policy cases against Docker from a repository checkout:

uv run python scripts/check_drawio_docker.py --image drawio-sandbox:local --output out/drawio

See the kind guide for accepted geometry and labels, and the image definition for pinned dependencies.