TeachCraft

LLM-based lesson generation system that transforms heterogeneous educational materials into structured instructional content.

Features

• Multi-source Document Processing: Handles PDFs, videos, URLs, and plain text documents
• Agentic Exploration: Intent parsing and document exploration for comprehensive content understanding
• Three-Stage Generation Pipeline:
  1. Lesson Plan generation
  2. Content Outline creation
  3. Canvas/Quiz component generation
• LessonBench Format Output: Generates slides (PNG), scripts (markdown), and quizzes (JSON)
• Multi-Provider LLM Support: Works with OpenAI, Anthropic, Google Gemini, and more

Quick Start

1. Install dependencies

# Install uv (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install Python dependencies
uv sync

# Install Playwright browser
playwright install chromium

2. Configure LLM providers

Copy and edit the configuration file:

cp config/llm_providers.example.json config/llm_providers.json
# Edit config/llm_providers.json and add your API keys

Example configuration:

{
  "openai": {
    "api_key": "YOUR_OPENAI_API_KEY",
    "base_url": "https://api.openai.com/v1",
    "prefix": "openai/"
  },
  "anthropic": {
    "api_key": "YOUR_ANTHROPIC_API_KEY",
    "base_url": "https://api.anthropic.com",
    "prefix": ""
  },
  "gemini": {
    "api_key": "YOUR_GEMINI_API_KEY",
    "base_url": "https://generativelanguage.googleapis.com/v1beta",
    "prefix": "gemini/"
  }
}

Alternative: Use environment variables in .env file:

OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
GOOGLE_API_KEY=...

3. Set up LessonBench dataset

Set the environment variable to point to your LessonBench dataset:

export LESSON_BENCH_DIR=/path/to/lesson_bench

4. Run lesson generation

Single case:

uv run python run_teachcraft.py --case algebra --model gemini-2.5-pro

CLI Usage

TeachCraft provides a unified CLI for evaluation and generation:

# Run full evaluation pipeline
uv run python -m cli.eval run

# Generate for specific cases
uv run python -m cli.eval generate algebra --system teachcraft

# Evaluate existing outputs
uv run python -m cli.eval evaluate -c algebra -c probability

# List available cases
uv run python -m cli.eval list-cases

# List available systems
uv run python -m cli.eval list-systems

Evaluation Options

# Compare specific systems
uv run python -m cli.eval evaluate -s teachcraft -s dp_gemini -s ia

# Use specific judge models
uv run python -m cli.eval evaluate --judge claude-sonnet-4-5

# Run with Bloom taxonomy analysis
uv run python -m cli.eval evaluate --bloom

Project Structure

TeachCraft/
├── run_teachcraft.py           # Main entry point
├── cli/                        # Command-line interface
│   └── eval.py                 # Evaluation CLI
│
├── generator/                  # Three-stage generation pipeline
│   ├── pipeline.py             # Main pipeline orchestrator
│   ├── canvas_generator.py     # Canvas JSON generation
│   ├── quiz_generator.py       # Quiz generation
│   └── llm_client.py           # Multi-provider LLM wrapper
│
├── exploration/                # Agentic exploration
│   ├── intent_parser.py        # User intent parsing
│   └── document_explorer.py    # Document exploration agent
│
├── knowledge/                  # Knowledge processing
│   ├── processor.py            # Document processing (Docling)
│   ├── video_processor.py      # Video transcription (Whisper)
│   └── cache.py                # Document cache management
│
├── models/                     # Data schemas
│   ├── canvas_schema.py        # Canvas element types (Pydantic)
│   └── lesson_schema.py        # Lesson plan schemas
│
├── renderer/                   # Canvas rendering
│   ├── playwright_renderer.py  # PNG rendering engine
│   └── static/                 # Frontend rendering assets
│
├── exporter/                   # Export utilities
│   └── pptx_exporter.py        # Canvas to PPTX converter
│
├── evaluation/                 # Evaluation framework
│   ├── config.py               # Evaluation configuration
│   ├── executor.py             # Pipeline executor
│   ├── runner.py               # Pairwise comparison runner
│   └── metrics.py              # Metrics tracking
│
├── baselines/                  # Baseline implementations
│   ├── direct_prompt/          # Direct prompt baseline
│   └── instructional_agents/   # ADDIE-based multi-agent baseline
│
├── data/                       # Data utilities
│   └── loader.py               # LessonBench case loader
│
├── config/                     # Configuration
│   ├── llm_providers.json      # API keys (gitignored)
│   └── llm_providers.example.json
│
└── prompts/                    # System prompts
    └── *.md                    # LLM prompt templates

Systems

Main Systems

System	Description
teachcraft	Full TeachCraft pipeline
dp_gemini	Direct prompt baseline (Gemini)
ia	Instructional Agents baseline

Ablation Systems

System	Description
teachcraft_no_exp	Skip agentic exploration
teachcraft_no_plan	Skip hierarchical planning
teachcraft_no_schema	LaTeX Beamer output (no Canvas schema)

Output Format

TeachCraft generates lessons in LessonBench format:

output_dir/
└── lessonbench/
    ├── 00_slide.png      # Slide image
    ├── 00_script.md      # Speaker script
    ├── 01_slide.png
    ├── 01_script.md
    ├── ...
    └── XX_quiz.json      # Quiz questions

Dependencies

Core dependencies:

• litellm: Unified LLM API wrapper
• playwright: Canvas rendering
• docling: Document processing
• openai-whisper: Video transcription
• pydantic: Data validation
• python-pptx: PPTX export

See pyproject.toml for full dependency list.

Supported LLM Providers

Provider	Prefix	Example Models
OpenAI	openai/	gpt-4o, gpt-5
Anthropic	``	claude-sonnet-4-5, claude-opus-4
Google Gemini	gemini/	gemini-2.5-pro

Troubleshooting

Playwright installation issues:

playwright install --force chromium

Document processing issues:

# Preprocess documents to cache
uv run python -m cli.eval preprocess

Memory issues:

The renderer auto-restarts after 100 renders to prevent memory leaks.

License

MIT License