Metadata-Version: 2.4
Name: agent-draw
Version: 0.1.0
Summary: An open-source Python SDK for building executable learning experiences.
Project-URL: Homepage, https://github.com/harshitgavita-07/agent-canvas
Project-URL: Repository, https://github.com/harshitgavita-07/agent-canvas
Project-URL: Documentation, https://github.com/harshitgavita-07/agent-canvas#readme
Project-URL: Issues, https://github.com/harshitgavita-07/agent-canvas/issues
Project-URL: Changelog, https://github.com/harshitgavita-07/agent-canvas/blob/main/CHANGELOG.md
Author: Harshit Gavita
Maintainer: Harshit Gavita
License-Expression: MIT
License-File: LICENSE
Keywords: agent,animation,canvas,diagram,education,learning,python,sdk,visualization,whiteboard
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Education
Classifier: Topic :: Multimedia :: Graphics
Classifier: Topic :: Scientific/Engineering :: Visualization
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.12
Requires-Dist: loguru>=0.7.3
Requires-Dist: networkx>=3.6
Requires-Dist: pydantic>=2.13
Requires-Dist: python-dotenv>=1.2
Requires-Dist: rich>=15.0
Requires-Dist: typer>=0.27
Description-Content-Type: text/markdown

<div align="center">

# 🎨 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.**

[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
[![Tests](https://img.shields.io/badge/tests-288%20passed-brightgreen)](https://github.com/agent-canvas/agent-canvas/actions)
[![PyPI](https://img.shields.io/badge/pip%20install-agent--canvas-blueviolet)](https://pypi.org/project/agent-canvas/)


[🚀 Quick Start](#-quick-start) • [✨ Why Agent Canvas](#-why-agent-canvas) • [🧩 Features](#-features) • [📐 Architecture](#-architecture) • [🗺️ Roadmap](#️-roadmap) • [🤝 Contributing](#-contributing)

<br/>

<!-- Replace with an actual demo GIF/screenshot before launch -->
<img src="docs/assets/demo.gif" alt="Agent Canvas demo — an AI-generated lesson animating on canvas" width="720"/>

</div>

<br/>

## ⚡ 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.**

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

<br/>

## 🧠 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

<br/>

## 🧩 Features

<table>
<tr>
<td width="50%" valign="top">

**🖊️ 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](https://docs.pydantic.dev/) runtime validation
- 100% [MyPy](https://mypy-lang.org/) type hints
- Immutable models — no accidental mutation

</td>
<td width="50%" valign="top">

**📦 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

</td>
</tr>
</table>

<br/>

## 🚀 Quick Start

Ship your first lesson in under 2 minutes.

### 1. Install

```bash
# 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

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

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

<details>
<summary><strong>See the resulting JSON</strong></summary>

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

</details>

<br/>

## 📐 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 |

<br/>

## 📁 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
```

<br/>

## 🧪 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 |

```bash
python examples/hello_world.py
```

<br/>

## 📚 Documentation

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

<br/>

## 🗺️ Roadmap

**v0.1.0 — Current**
✅ Core Canvas DSL &nbsp;·&nbsp; ✅ Pydantic models &nbsp;·&nbsp; ✅ JSON serialization &nbsp;·&nbsp; ✅ Validation &nbsp;·&nbsp; ✅ Renderer registry &nbsp;·&nbsp; ✅ Type safety &nbsp;·&nbsp; ✅ 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

<br/>

## 🤝 Contributing

Contributions make this project better — issues, PRs, and ideas are all welcome. See the [Contributing Guide](CONTRIBUTING.md).

```bash
# 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.

<br/>

## 💬 Support

Need help? Check the [Support Guide](SUPPORT.md) for bug reports, feature requests, questions, and commercial support.

<br/>

## 🙏 Acknowledgments

Agent Canvas draws inspiration from [Manim](https://www.manim.community/), [Pydantic](https://docs.pydantic.dev/), [Rich](https://github.com/Textualize/rich), and [Textual](https://textual.textualize.io/).

<br/>

## 📄 License

Agent Canvas is licensed under the [MIT License](LICENSE).

---

<div align="center">

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

**Built with ❤️ for educators and developers**

[Report Issue](https://github.com/agent-canvas/agent-canvas/issues) • [Discussions](https://github.com/agent-canvas/agent-canvas/discussions) • [Changelog](CHANGELOG.md)

</div>
