agent-draw 0.1.0

An open-source Python SDK for building executable learning experiences.

🎨 Agent Canvas

The executable DSL for AI-generated learning experiences

Write a lesson once in Python. Play it back anywhere — SVG, PNG, video, or your own renderer.

🚀 Quick Start • ✨ Why Agent Canvas • 🧩 Features • 📐 Architecture • 🗺️ Roadmap • 🤝 Contributing

⚡ TL;DR

Static slides and videos can't adapt to a learner. LLMs can generate great explanations — but there's no standard, executable format for what they generate. Agent Canvas is that format.

lesson.add(RectangleCommand(...)).add(TextCommand(...))
lesson.save("hello_lesson.json")  # portable, replayable, renderer-agnostic

One typed, validated JSON lesson → rendered as SVG today, video tomorrow, an interactive canvas next quarter — without touching your generation pipeline.

🧠 Why Agent Canvas

The old way	With Agent Canvas
❌ Static slides/videos that never adapt	✅ Lessons that replay, animate, and re-render on demand
❌ Every AI tutor invents its own ad-hoc output format	✅ One typed, Pydantic-validated schema LLMs can target reliably
❌ Content locked to a single output (a video file, a PDF)	✅ Write once, render to SVG, PNG, or video via pluggable renderers
❌ No safety net between "LLM output" and "on-screen"	✅ Full validation layer catches malformed lessons before render

Built for:

• 🎓 Educational platforms generating interactive lessons from AI tutors
• 📚 Content teams building animated tutorials programmatically
• 🤖 AI agent builders who need a structured way to draw, not just talk
• 📊 Docs teams creating executable diagrams and flowcharts that stay in sync with code

🧩 Features

🖊️ Core DSL Text, Line, Arrow, Circle, Rectangle, Scribble Highlight & Underline annotations Pointer and Laser tools Move / Fade animations with configurable easing Wait, Pause, Erase, Clear control flow 🔒 Type Safety Full Pydantic runtime validation 100% MyPy type hints Immutable models — no accidental mutation

📦 Serialization Clean, human-readable JSON output Lossless round-trip serialization Version-aware, forward/backward compatible 🔌 Renderer-Agnostic Pluggable renderer registry SVG, PNG, HTML5 Canvas (community renderers, in progress) 🎬 Timeline-Based Playback Frame-accurate timestamp control Layer-based rendering with z-index Configurable FPS & duration defaults

🚀 Quick Start

Ship your first lesson in under 2 minutes.

1. Install

# pip
pip install agent-canvas

# uv (recommended)
uv add agent-canvas

# editable install for contributors
git clone https://github.com/agent-canvas/agent-canvas.git
cd agent-canvas && pip install -e .

Requires Python 3.12+. Core deps: pydantic, rich, typer, loguru, networkx, python-dotenv.

2. Build a lesson

from agent_canvas import (
    Lesson,
    LessonMetadata,
    TextCommand,
    RectangleCommand,
    Point,
    Size,
    Bounds,
    Style,
    Color,
)

lesson = Lesson(
    metadata=LessonMetadata(
        title="Hello, Agent Canvas!",
        description="A quick introduction to the SDK",
        author="Your Name",
    ),
    timeline=[
        # Frame 1: draw a rectangle
        {
            "timestamp": 0.0,
            "command": RectangleCommand(
                bounds=Bounds(
                    position=Point(x=100, y=100),
                    size=Size(width=400, height=200),
                ),
                style=Style(color=Color(value="#3B82F6"), stroke_width=2),
            ),
        },
        # Frame 2: add text
        {
            "timestamp": 1.0,
            "command": TextCommand(
                position=Point(x=300, y=200),
                text="Welcome to Agent Canvas!",
                font_size=24,
                style=Style(color=Color(value="#1E293B")),
            ),
        },
    ],
)

3. Serialize, save, reload — anywhere

import json

json_output = lesson.model_dump_json(indent=2)

with open("hello_lesson.json", "w") as f:
    f.write(json_output)

with open("hello_lesson.json") as f:
    loaded = Lesson.model_validate_json(f.read())
    print(f"Loaded lesson: {loaded.metadata.title}")

See the resulting JSON

{
  "metadata": {
    "title": "Hello, Agent Canvas!",
    "description": "A quick introduction to the SDK",
    "author": "Your Name",
    "version": "0.1.0",
    "tags": []
  },
  "timeline": [
    {
      "timestamp": 0.0,
      "command": {
        "command": "rectangle",
        "bounds": {
          "position": { "x": 100, "y": 100 },
          "size": { "width": 400, "height": 200 }
        },
        "style": { "color": "#3B82F6", "stroke_width": 2 }
      }
    }
  ]
}

📐 Architecture

┌─────────────────────────────────────────────────────────────┐
│                     Agent Canvas SDK                        │
├─────────────────────────────────────────────────────────────┤
│                                                               │
│  ┌──────────────┐     ┌──────────────┐     ┌─────────────┐  │
│  │   Canvas     │     │   Playback   │     │  Renderer   │  │
│  │     DSL      │────▶│    Engine    │────▶│   Registry  │  │
│  │              │     │              │     │             │  │
│  │  - Models    │     │  - Timeline  │     │  - SVG      │  │
│  │  - Commands  │     │  - Player    │     │  - PNG      │  │
│  │  - Validator │     │  - Scheduler │     │  - Custom   │  │
│  └──────────────┘     └──────────────┘     └─────────────┘  │
│         │                                       │            │
│         ▼                                       ▼            │
│  ┌──────────────┐                       ┌─────────────┐      │
│  │ Serializer   │                       │   Output    │      │
│  │   (JSON)     │                       │   Files     │      │
│  └──────────────┘                       └─────────────┘      │
│                                                               │
└─────────────────────────────────────────────────────────────┘

Component	Description
Canvas DSL	Core data models and commands defining the lesson structure
Serializer	Converts lessons to/from JSON with validation
Playback Engine	Interprets timeline events for animation (planned)
Renderer Registry	Pluggable backend for different output formats
Validators	Ensures lessons conform to spec before rendering

📁 Repository Structure

agent-canvas/
├── src/agent_canvas/
│   ├── __init__.py          # Public API exports
│   ├── canvas/               # Core DSL implementation
│   │   ├── models.py         # Pydantic models (Point, Lesson, etc.)
│   │   ├── commands/         # Command implementations
│   │   ├── serializer.py     # JSON serialization
│   │   ├── validator.py      # Lesson validation
│   │   └── registry.py       # Renderer registry
│   ├── renderer/              # Rendering backends
│   ├── playback/              # Timeline playback (planned)
│   └── runtime/                # Runtime engine (planned)
├── tests/                     # Test suite (288 tests)
├── examples/                  # Usage examples
├── docs/                       # Documentation
├── SPEC.md                     # DSL specification
└── pyproject.toml              # Project configuration

🧪 Examples

Example	Description
hello_world.py	Minimal lesson creation
draw_text.py	Text rendering with various styles
draw_shapes.py	Rectangles, circles, lines, arrows
annotations.py	Highlights and underlines
timeline.py	Multi-frame animations
serialization.py	Save/load lessons from JSON
validation.py	Validate lessons before rendering
svg_export.py	Export lesson to SVG
png_export.py	Export lesson to PNG

python examples/hello_world.py

📚 Documentation

Document	Description
SPEC.md	Complete DSL specification
docs/ARCHITECTURE.md	High-level architecture
docs/CANVAS_DSL.md	DSL reference guide
docs/PLAYBACK.md	Playback engine documentation
docs/TIMELINE.md	Timeline and animation guide
docs/RUNTIME.md	Runtime engine docs
docs/ROADMAP.md	Future development plans

🗺️ Roadmap

v0.1.0 — Current ✅ Core Canvas DSL  ·  ✅ Pydantic models  ·  ✅ JSON serialization  ·  ✅ Validation  ·  ✅ Renderer registry  ·  ✅ Type safety  ·  ✅ 288-test suite

v0.2.0 — Next

• SVG renderer implementation
• PNG renderer implementation
• CLI tool for lesson preview
• Enhanced animation support
• Custom easing functions

v0.3.0

• HTML5 Canvas renderer
• Interactive playback mode
• Lesson composition utilities
• Performance optimizations

v1.0.0

• Stable public API
• Production-ready renderers
• Comprehensive documentation
• Integration examples

🤝 Contributing

Contributions make this project better — issues, PRs, and ideas are all welcome. See the Contributing Guide.

# Fork and clone
git clone https://github.com/YOUR_USERNAME/agent-canvas.git
cd agent-canvas

# Set up environment
uv sync --all-groups

# Run tests
pytest

# Lint and type check
ruff check .
mypy src

All PRs must pass CI (Ruff + MyPy + pytest) before merging.

💬 Support

Need help? Check the Support Guide for bug reports, feature requests, questions, and commercial support.

🙏 Acknowledgments

Agent Canvas draws inspiration from Manim, Pydantic, Rich, and Textual.

📄 License

Agent Canvas is licensed under the MIT License.

---

If Agent Canvas is useful to you, a ⭐ on GitHub goes a long way.

Built with ❤️ for educators and developers

Report Issue • Discussions • Changelog