agent-draw 0.1.1

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

🎨 Agent Canvas

Executable visual lessons for AI-native education.

Agent Canvas is a typed Python DSL for describing visual lessons — text, shapes, annotations, and timelines — as structured, validated data instead of one-off scripts or static media. Write a lesson once, serialize it to JSON, and render it anywhere a renderer exists.

Installation • Quick Example • Why Agent Canvas • Features • Architecture • Roadmap

---

Installation

# pip
pip install agent-draw

# uv (recommended)
uv add agent-draw

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

For contributors, an editable install:

git clone https://github.com/harshitgavita-07/agent-canvas.git
cd agent-canvas
uv sync --all-groups

The PyPI distribution is named agent-draw; the importable module remains agent_canvas:

from agent_canvas import Lesson, LessonMetadata, TextCommand, RectangleCommand

Repository: github.com/harshitgavita-07/agent-canvas

---

Quick Example

1. Define a lesson as typed Python objects.

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=[
        {
            "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),
            ),
        },
        {
            "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")),
            ),
        },
    ],
)

2. Serialize it to JSON. Every model is Pydantic-backed, so the output is validated and lossless.

with open("hello_lesson.json", "w") as f:
    f.write(lesson.model_dump_json(indent=2))

3. Reload and validate it later, from anywhere.

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

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 }
      }
    }
  ]
}

Today, that JSON is the portable artifact: it can be validated, diffed, stored, and handed to a renderer once one exists for your target format. That's the contract Agent Canvas is building around.

---

Why Agent Canvas

Large language models are good at explaining things, but there's no standard way for them to draw an explanation. Every AI tutor or content pipeline ends up inventing its own ad-hoc drawing format, tightly coupled to whatever renderer it started with.

Agent Canvas separates what a lesson contains from how it gets rendered:

Problem	Agent Canvas's approach
Every AI tutor invents its own output format	One typed, Pydantic-validated schema LLMs can target
Lesson content is locked to a single output (a video file, a PDF)	Lessons serialize to plain JSON, independent of any renderer
No safety net between "LLM output" and "on-screen"	Full validation layer catches malformed lessons before rendering
Static slides and videos can't be replayed, edited, or re-targeted	Lessons are data — diffable, versionable, re-renderable

Built for:

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

Note: Agent Canvas today is a DSL and validation layer, not a rendering engine. Rendering backends (SVG, PNG, playback) are on the roadmap — see Current Capabilities below for exactly what's implemented now.

---

Features

Available Today

• Typed DSL — Text, Line, Arrow, Circle, Rectangle, and Scribble commands, plus Highlight/Underline annotations and Pointer/Laser tool primitives
• Pydantic models — full runtime validation, 100% MyPy type hints, immutable models with no accidental mutation
• JSON serialization — clean, human-readable, lossless round-trip serialization
• Validation layer — catches malformed lessons before they reach a renderer
• Renderer registry — a pluggable interface for registering renderer backends
• Timeline model — frame-accurate timestamps, layer-based ordering with z-index, configurable FPS and duration defaults
• 288-test suite covering models, serialization, and validation

Coming Soon

• SVG renderer implementation
• PNG renderer implementation
• CLI tool for lesson preview
• Playback / animation engine (move, fade, easing)
• HTML5 Canvas renderer
• Interactive playback mode

---

Current Capabilities

To be precise about where the project stands:

Layer	Status
Canvas DSL (models, commands)	✅ Implemented
Serialization (JSON)	✅ Implemented
Validation	✅ Implemented
Renderer registry (interface)	✅ Implemented
SVG / PNG renderers	🚧 Planned, not yet implemented
Playback / animation engine	🚧 Planned, not yet implemented
Runtime engine	🚧 Planned, not yet implemented

If your use case needs an actual rendered image or video today, Agent Canvas is not yet there — it currently produces validated, structured lesson data. If you need a reliable schema to generate and store AI-authored visual lessons, that part is ready now.

---

Project Architecture

┌───────────────────────────────────────────────────────────┐
│                      Agent Canvas SDK                      │
├───────────────────────────────────────────────────────────┤
│                                                              │
│   ┌─────────────┐      ┌──────────────┐      ┌───────────┐ │
│   │  Canvas DSL │─────▶│  Serializer  │─────▶│  Output   │ │
│   │             │      │   (JSON)     │      │  (JSON)   │ │
│   │ - Models    │      └──────────────┘      └───────────┘ │
│   │ - Commands  │                                           │
│   │ - Validator │      ┌──────────────┐      ┌───────────┐ │
│   │             │─────▶│   Renderer   │─────▶│ SVG / PNG │ │
│   └─────────────┘      │   Registry   │      │ (planned) │ │
│                         └──────────────┘      └───────────┘ │
│                                                              │
└───────────────────────────────────────────────────────────┘

Component	Description	Status
Canvas DSL	Core data models and commands defining lesson structure	✅ Implemented
Serializer	Converts lessons to/from JSON with validation	✅ Implemented
Validator	Ensures lessons conform to spec before rendering	✅ Implemented
Renderer Registry	Pluggable backend interface for output formats	✅ Implemented
Playback Engine	Interprets timeline events for animation	🚧 Planned
Runtime	End-to-end execution engine	🚧 Planned

---

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 (in progress)
│   ├── 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 lesson timelines
serialization.py	Save/load lessons from JSON
validation.py	Validate lessons before rendering

python examples/hello_world.py

---

Roadmap

v0.1 — Completed

Core Canvas DSL · Pydantic models · JSON serialization · Validation · Renderer registry · Type safety · 288-test suite

v0.2 — In Progress

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

v0.5 — Planned

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

v1.0 — Production Ready

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

---

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 (planned feature)
docs/TIMELINE.md	Timeline and animation guide
docs/RUNTIME.md	Runtime engine docs (planned feature)
docs/ROADMAP.md	Future development plans

---

Contributing

Issues, PRs, and design discussion are 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 pull requests must pass CI (Ruff + MyPy + pytest) before merging.

---

Support

Need help? See 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.

Built for educators and developers.

Report an Issue • Discussions • Changelog