Metadata-Version: 2.4
Name: agent-draw
Version: 0.1.1
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

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

[![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/harshitgavita-07/agent-canvas/actions)
[![PyPI](https://img.shields.io/badge/pip%20install-agent--draw-blueviolet)](https://pypi.org/project/agent-draw/)

[Installation](#installation) • [Quick Example](#quick-example) • [Why Agent Canvas](#why-agent-canvas) • [Features](#features) • [Architecture](#project-architecture) • [Roadmap](#roadmap)

</div>

---

## Installation

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

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

```python
from agent_canvas import Lesson, LessonMetadata, TextCommand, RectangleCommand
```

Repository: [github.com/harshitgavita-07/agent-canvas](https://github.com/harshitgavita-07/agent-canvas)

---

## Quick Example

**1. Define a lesson as typed Python objects.**

```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=[
        {
            "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.

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

**3. Reload and validate it later, from anywhere.**

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

<details>
<summary><strong>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>

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](#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 |

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

---

## Contributing

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

---

## Support

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

---

## 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/).

---

## License

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

<div align="center">

**Built for educators and developers.**

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

</div>
