Metadata-Version: 2.4
Name: diagramdsl
Version: 3.0.0
Summary: Step-based diagram renderer for AI agents — Python server and client.
Author-email: Mutiibwa Grace Peter <gracepetermutiibwa@gmail.com>
License: MIT
Project-URL: Homepage, https://diagramdsl.dev
Project-URL: Documentation, https://docs.diagramdsl.dev
Project-URL: Repository, https://github.com/yourorg/diagramdsl-python
Project-URL: Bug Tracker, https://github.com/yourorg/diagramdsl-python/issues
Keywords: diagram,ai,agent,renderer,visualization,flowchart,architecture,headless
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Visualization
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: fastapi>=0.111.0
Requires-Dist: uvicorn[standard]>=0.29.0
Requires-Dist: playwright>=1.44.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: httpx>=0.27.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Requires-Dist: pytest-cov>=5.0; extra == "dev"
Requires-Dist: respx>=0.21; extra == "dev"
Requires-Dist: ruff>=0.4; extra == "dev"
Requires-Dist: mypy>=1.10; extra == "dev"

# 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

```bash
pip install diagramdsl
playwright install chromium
```

## Quickstart

### 1. Generate an auth token

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

Store it in an environment variable:

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

### 2. Start the server

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

```bash
diagramdsl serve --port 8421
```

### 3. Render a diagram

```python
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](https://docs.diagramdsl.dev).

## License

MIT
