Metadata-Version: 2.4
Name: agent-canvas
Version: 0.1.0
Summary: An open-source Python SDK for building executable learning experiences
Author: Agent Canvas Contributors
License: MIT
Project-URL: Homepage, https://github.com/agent-canvas/agent-canvas
Project-URL: Repository, https://github.com/agent-canvas/agent-canvas
Project-URL: Documentation, https://github.com/agent-canvas/agent-canvas#readme
Keywords: canvas,education,visualization,sdk,learning
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Education
Classifier: Topic :: Multimedia :: Graphics
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: loguru>=0.7.3
Requires-Dist: networkx>=3.6.1
Requires-Dist: pydantic>=2.13.4
Requires-Dist: python-dotenv>=1.2.2
Requires-Dist: rich>=15.0.0
Requires-Dist: typer>=0.27.0
Dynamic: license-file

# Agent Canvas

[![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-green)](https://github.com/agent-canvas/agent-canvas/actions)

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

Agent Canvas provides a renderer-agnostic DSL for creating educational content that can be serialized, played back, and rendered across multiple platforms. Build interactive lessons, tutorials, and visual explanations with a clean, type-safe API.

---

## Why Agent Canvas?

### The Problem

Educational content is often static—textbooks, slides, and videos can't adapt to individual learners. AI can generate content, but there's no standard format for *executable* lessons that can be played back, animated, or rendered across different platforms.

### The Vision

Agent Canvas defines a universal DSL for educational content:

- **Write once, render anywhere**: Lessons are platform-agnostic JSON
- **AI-friendly**: Structured output that LLMs can generate reliably
- **Type-safe**: Full Pydantic validation and MyPy support
- **Extensible**: Pluggable renderer architecture for SVG, PNG, video, or custom outputs

### Use Cases

- 🎓 **Educational Platforms**: Generate interactive lessons from AI tutors
- 📚 **Content Creation**: Build animated tutorials programmatically
- 🤖 **AI Agents**: Give LLMs a structured way to create visual explanations
- 📊 **Documentation**: Create executable diagrams and flowcharts

---

## Features

### Core DSL

- **Drawing Commands**: Text, Line, Arrow, Circle, Rectangle, Scribble
- **Annotations**: Highlight, Underline
- **Pointer Tools**: Pointer, Laser
- **Animations**: Move, Fade with configurable duration and easing
- **Control Flow**: Wait, Pause, Erase, Clear

### Type Safety

- Built on [Pydantic](https://docs.pydantic.dev/) for runtime validation
- Full [MyPy](https://mypy-lang.org/) type hints
- Immutable models prevent accidental mutations

### Serialization

- Lessons serialize to clean, human-readable JSON
- Round-trip serialization preserves all data
- Version-aware with forward/backward compatibility strategy

### Renderer Agnostic

- Define lessons once, render anywhere
- Built-in renderer registry for extensibility
- Community renderers: SVG, PNG, HTML5 Canvas (planned)

### Timeline-Based Playback

- Precise timestamp control for animations
- Layer-based rendering with z-index support
- Configurable FPS and duration defaults

---

## Installation

### Using pip

```bash
pip install agent-canvas
```

### Using uv (recommended)

```bash
uv add agent-canvas
```

### Editable Install (for development)

```bash
git clone https://github.com/agent-canvas/agent-canvas.git
cd agent-canvas
pip install -e .
```

### Requirements

- Python 3.12 or higher
- Dependencies: `pydantic`, `rich`, `typer`, `loguru`, `networkx`, `python-dotenv`

---

## Quick Start

Create your first lesson in under 2 minutes:

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

# Create a simple lesson
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")),
            ),
        },
    ],
)

# Serialize to JSON
import json
json_output = lesson.model_dump_json(indent=2)
print(json_output)

# Save to file
with open("hello_lesson.json", "w") as f:
    f.write(json_output)

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

### Output

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

### Components

| 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

Explore the [`examples/`](examples/) directory for complete working 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 |

Run any example:

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

---

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

---

## Roadmap

### v0.1.0 (Current)

- ✅ Core Canvas DSL
- ✅ Pydantic models
- ✅ JSON serialization
- ✅ Validation
- ✅ Renderer registry
- ✅ Type safety
- ✅ Test suite

### v0.2.0

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

We welcome contributions! See our [Contributing Guide](CONTRIBUTING.md) for details.

### Quick Start for Contributors

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

### Code Quality

- **Ruff** for linting and formatting
- **MyPy** for type checking
- **pytest** for testing

All PRs must pass CI checks before merging.

---

## License

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

---

## Acknowledgments

Agent Canvas draws inspiration from:

- [Manim](https://www.manim.community/) - Mathematical animation engine
- [Pydantic](https://docs.pydantic.dev/) - Data validation
- [Rich](https://github.com/Textualize/rich) - Terminal formatting
- [Textual](https://textual.textualize.io/) - TUI framework

---

## Support

Need help? See our [Support Guide](SUPPORT.md) for:

- Bug reports
- Feature requests
- Questions
- Commercial support

---

<div align="center">

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