diagramdsl 3.0.0

Step-based diagram renderer for AI agents — Python server and client.

diagramdsl

Step-based diagram renderer for AI agents — Python server and client.

DiagramDSL lets AI agents construct diagrams incrementally by emitting structured JSON. The Python package wraps the JavaScript renderer in a Playwright-powered headless server, exposing two HTTP endpoints that any agent or application can call.

Install

pip install diagramdsl
playwright install chromium

Quickstart

1. Generate an auth token

diagramdsl token
# f47ac10b-58cc-4372-a567-0e02b2c3d479

Store it in an environment variable:

export DIAGRAMDSL_AUTH_TOKEN=f47ac10b-58cc-4372-a567-0e02b2c3d479

2. Start the server

import os
from diagramdsl import DiagramDSLServer

server = DiagramDSLServer(
    port=8421,
    host="127.0.0.1",
    auth=os.environ["DIAGRAMDSL_AUTH_TOKEN"],
)
server.start()

Or via CLI:

diagramdsl serve --port 8421

3. Render a diagram

import os
from diagramdsl import DiagramDSL

class FileTool(DiagramDSL):
    def save(self, png_bytes: bytes) -> str:
        path = "/tmp/diagram.png"
        with open(path, "wb") as f:
            f.write(png_bytes)
        return path

tool = FileTool(host="http://localhost:8421", auth=os.environ["DIAGRAMDSL_AUTH_TOKEN"])

path = tool.render({
    "1": { "node": "circle", "label": "Start", "attributes": { "background": "#fff7ed" } },
    "2": { "node": "box",    "label": "Process", "connect": { "from": "1", "direction": "right" } },
    "3": { "node": "circle", "label": "End",   "connect": { "from": "2", "direction": "right" } },
})

print(path)  # /tmp/diagram.png

Endpoints

Method	Path	Description
GET	/info	DSL rules and schema — inject into agent system prompts
POST	/render	Render a steps object → PNG image
GET	/docs/{type}	Schema for a specific shape, edge, or direction
GET	/health	Health check (no auth required)

All endpoints except /health require Authorization: Bearer <token>.

Documentation

Full documentation at docs.diagramdsl.dev.

License

MIT