agent-draw

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}")

{
  "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:

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:

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) │ │
│                         └──────────────┘      └───────────┘ │
│                                                              │
└───────────────────────────────────────────────────────────┘

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

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

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.