Instructional Agents

An AI-powered instructional design system based on the ADDIE model for automated course creation and evaluation.

@misc{yao2025instructionalagentsllmagents,
  title={Instructional Agents: Reducing Teaching Faculty Workload through Multi-Agent Instructional Design},
  author={Yao, Huaiyuan and Xu, Wanpeng and Turnau, Justin and Kellam, Nadia and Wei, Hua},
  year={2025},
  eprint={2508.19611},
  archivePrefix={arXiv},
  primaryClass={cs.AI},
  url={https://arxiv.org/abs/2508.19611},
}

📰 News

[2026.1.6] Instructional Agents is accepted by EACL 2026 Main Conference!

📦 Releases

[2026.4.15] Released Claude Code Skills - invoke the pipeline directly from Claude Code: /plugin install DaRL-GenAI/instructional_agents-skills

[2026.4.13] Release v1.1.0 - Added LaTeX-to-PPTX conversion with pptxgenjs, Slide Masters, react-icons, and shadow effects

[2026.3.26] Published on PyPI - pip install instructional-agents

✨ Features

🎬 How It Works

🤖 Use via Claude Code

Invoke the full ADDIE pipeline and related tools directly from Claude Code — no Python boilerplate.

pip install instructional-agents
/plugin install DaRL-GenAI/instructional_agents-skills

Then ask Claude in natural language: "Generate a course on Reinforcement Learning", "Convert this Beamer .tex to an editable .pptx", "Evaluate these slides as a Program Chair". See the skills repo for all available commands.

🚀 Quick Start (Docker - Recommended)

This guide will walk you through the complete workflow from setup to viewing results.

# Clone the repository (if not already done)
git clone <repository-url>
cd instructional_agents

# Create environment variables file
cp .env.example .env

# Edit .env file and add your OPENAI_API_KEY
# OPENAI_API_KEY=your_api_key_here
# API_PORT=8000

# Option 1: Use the start script (recommended)
./start.sh

# Option 2: Start manually
docker-compose up -d

# Verify service is running
curl http://localhost:8000/health
# Should return: {"status":"healthy","version":"1.0.0",...}

# Open frontend/index.html directly in your browser
open frontend/index.html  # macOS
# or double-click frontend/index.html in your file manager

# Using Python
cd frontend
python -m http.server 8080
# Then open http://localhost:8080/index.html in your browser

# View container logs in real-time
docker-compose logs -f api

# View last 100 lines
docker-compose logs --tail=100 api

# View logs for a specific time range
docker-compose logs --since 30m api

# List all experiments
ls exp/

# View a specific experiment's structure
ls -R exp/your_experiment_name/

# Open in Finder (macOS)
open exp/your_experiment_name/

# Open in Explorer (Windows)
explorer exp\\your_experiment_name\\

# View course syllabus
cat exp/your_experiment_name/result_syllabus_design.md

# View generated slides PDF
open exp/your_experiment_name/chapter_1/slides.pdf

exp/{experiment_name}/
├── result_instructional_goals.md          # Learning objectives
├── result_resource_assessment.md          # Resource assessment
├── result_target_audience.md              # Target audience analysis
├── result_syllabus_design.md              # Course syllabus (⭐ important)
├── result_assessment_planning.md          # Assessment planning
├── result_final_exam_project.md           # Final project design
├── result_presentation_design.md          # Seventh foundation: course-wide presentation design
├── processed_chapters.json                # Chapter metadata
├── course_slide_style.json                # Validated course-wide frontend style
├── course_slide_style_source.md           # Exact selected style source snapshot
├── statistics_slide_style.json            # Style deliberation timing/tokens
├── statistics.json                        # Generation statistics
│
├── chapter_1/                             # Chapter 1 materials
│   ├── slides.tex                         # LaTeX source
│   ├── slides.pdf                         # Compiled PDF slides (⭐ ready to use)
│   ├── html/                              # Portable offline HTML bundle
│   │   ├── slides.html                    # Offline interactive HTML slides
│   │   └── assets/                        # Offline MathJax and selected fonts
│   ├── slides-html.pdf                    # PDF exported from the HTML deck
│   ├── slides-html.pptx                   # Static image-based HTML export
│   ├── frontend-slides-manifest.json      # Hashes, counts, warnings, artifacts
│   ├── slides.pptx                        # PowerPoint slides (⭐ editable)
│   ├── script.md                          # Presentation script
│   ├── assessment.md                      # Assessment materials
│   └── statistics_slides_chapter_1.json   # Chapter statistics
│
├── chapter_2/                             # Chapter 2 materials
│   └── ...
└── ...

📦 Install via PyPI

pip install instructional-agents

After installation, you can run the CLI directly:

# Set your OpenAI API key
export OPENAI_API_KEY=your_api_key_here

# Generate a course
instructional-agents "Introduction to Machine Learning"

🔧 Local Development Setup

For developers who want to run the system locally from source:

1. Prerequisites

• Python 3.11+
• pip
• LaTeX (for PDF generation)
  • macOS: brew install --cask mactex
  • Ubuntu: sudo apt-get install texlive-full
  • Windows: Install MiKTeX
• Node.js 18+ (for PPTX generation)
  • macOS: brew install node
  • Ubuntu: sudo apt-get install nodejs npm
  • Windows: Install from nodejs.org

2. Install Dependencies

# Python dependencies
pip install -r requirements.txt

# Or install in editable mode
pip install -e .

# Node.js dependencies (for PPTX generation)
npm install -g pptxgenjs

# Optional: install react-icons for slide icons (recommended)
npm install -g react-icons react react-dom sharp

Note: pptxgenjs is required for LaTeX-to-PPTX conversion. The react-icons + sharp packages are optional but recommended — they add topic-specific icons to each slide (e.g., 🤖 for agent topics, 🧠 for AI topics). Without them, slides will use simple geometric shapes instead.

3. Configuration

Option A: Using config.json

{
  "OPENAI_API_KEY": "your_openai_api_key_here"
}

Option B: Using environment variable

export OPENAI_API_KEY=your_api_key_here

4. Start API Server

# Start the API server
python api_server.py

# Or use uvicorn directly with auto-reload
uvicorn api_server:app --host 0.0.0.0 --port 8000 --reload

The API will be available at http://localhost:8000

• API Documentation: http://localhost:8000/docs
• Health Check: http://localhost:8000/health

🚀 Usage Methods

Method 1: Web Interface (Recommended)

The easiest way to use the system. See Step 2 above for detailed instructions.

Features:

• 📝 Visual course configuration form
• 📊 Real-time progress monitoring
• 📁 Result file browsing and download
• 📤 Catalog file upload and management
• 🔄 Real-time log streaming

Method 2: Command Line

Entry Point: run.py – Main workflow entry point

# Simple course generation
python run.py "Introduction to Machine Learning"

# With specific model
python run.py "Data Structures" --model gpt-4o-mini

# With experiment name
python run.py "Web Development" --exp web_dev_v1

# Interactive copilot mode
python run.py "Database Systems" --copilot

# Use catalog mode
python run.py "Software Engineering" --catalog

# Use specific catalog file
python run.py "AI Fundamentals" --catalog ai_catalog

# Combine catalog and copilot
python run.py "Educational Psychology" --copilot --catalog edu_psy

# Enable images with no numeric per-chapter cap
python run.py "Systems Thinking" --image-generation on --image-count on

# Opt in to Carbon-rendered code images
python run.py "Programming Languages" --code-images on

Minimal Working Example (generates a small 3-week course in ~5 min):

python run.py "Intro to Python" --catalog mwe_catalog --exp mwe_test --seed 42

Command Line Arguments:

python run.py <course_name> [OPTIONS]

Required:
  course_name              Name of the course to design

Options:
  --copilot                Enable interactive copilot mode
  --catalog [name]         Use structured data from catalog/ directory
                           (optional: specify catalog name without '.json')
  --model MODEL            OpenAI model to use (default: gpt-4o-mini)
  --exp EXP_NAME           Experiment name for saving output (default: exp1)
  --seed SEED              Random seed for reproducibility
  --temperature TEMP       Sampling temperature for LLM
  --image-generation {on,off,replace}
                           Enable, disable, or replace generated slide images
  --image-count {on,off}   Turn AI-selected image counts on or off; when on,
                           the count is always automatic
  --code-images {on,off}   Use Carbon code images or styled HTML code blocks
  --optimize STORAGE_ID    Optimize mode: provide storage_id of uploaded PDFs
  --requirements TEXT      User requirements for optimization (with --optimize)
  --chapter NAME           Specific chapter to optimize (with --optimize)

Dynamic slide images are off by default. When enabled, the presentation-design deliberation may still veto imagery. Use --image-count on to remove the fixed numeric budget and always let the placement AI choose the count. Use --image-count off to restore the experiment's stored fixed cap (3 by default). Omitting the flag preserves the current experiment setting. The placement AI may choose zero, five, six, or any other number up to the chapter's eligible slides while automatic counting is on. Generated images appear only in the HTML, HTML-derived PDF, and HTML-derived PPTX; the Beamer source and PDF are unchanged. See docs/BETTER_SLIDES_GENERATION.md for cache and replacement behavior.

Carbon code images are also off by default. --code-images on persists the choice in course_code_images.json and applies it to every chapter. The first enabled chapter that actually contains a lstlisting or verbatim block uses an existing carbon-now executable or runs npm install --global carbon-now-cli@2.1.0. This is an explicit global npm installation; Node.js and npm must already be installed and are never installed automatically. Missing prerequisites, installation failures, network failures, timeouts, or invalid Carbon output produce warnings and retain the styled editable <pre> block. Successful PNGs are cached by content, language, theme, pipeline, and Carbon version, then embedded directly in the self-contained HTML. They therefore appear in the HTML-derived PDF and PPTX, while slides.tex and the Beamer PDF remain unchanged. Use --code-images off to persistently return the course to <pre> rendering.

Method 3: Direct API Calls

API Server: api_server.py – RESTful API service

# Start API server first (if not using Docker)
python api_server.py

# Generate a course
curl -X POST http://localhost:8000/api/course/generate \
  -H "Content-Type: application/json" \
  -H "X-OpenAI-API-Key: your_api_key_here" \
  -d '{
    "course_name": "Introduction to Machine Learning",
    "model_name": "gpt-4o-mini",
    "exp_name": "ml_intro_v1"
  }'

# Check task status
curl http://localhost:8000/api/course/status/{task_id}

# Get result files
curl http://localhost:8000/api/course/results/{task_id}/files

# Download a file
curl http://localhost:8000/api/course/results/{task_id}/download/chapter_1/slides.pdf \
  --output slides.pdf

For complete API documentation, see API Documentation.

🔧 Core Modules

📚 Advanced Usage

Catalog Mode

Catalog files provide structured input data to guide the course generation process. They include:

• Student profiles and backgrounds
• Instructor preferences and teaching style
• Optional presentation style preferences, including visual direction, colors, typography, layout density, accessibility needs, and styles to avoid
• Course structure requirements
• Assessment design preferences
• Teaching constraints
• Institutional requirements

Using Catalogs:

# Use default catalog
python run.py "Software Engineering" --catalog

# Use a specific catalog file (without .json extension)
python run.py "AI Fundamentals" --catalog ai_catalog
# System looks for: catalog/ai_catalog.json

# Upload catalog via web interface
# In the web interface, select "上传 Catalog 文件" and upload your JSON file

See API Documentation for catalog format details.

presentation_style_preferences is advisory. The presentation-design agents consider every non-empty preference when comparing packaged styles, while accessibility, readability, course suitability, and rendering feasibility take priority when a preference conflicts with the available designs. The selected style remains frozen on resume; use a new experiment or --reselect-presentation-design with run.py to apply changed preferences.

Copilot Mode

Interactive mode that prompts for feedback after each phase of the ADDIE workflow:

• Analysis phase: Review and provide feedback on learning goals, resource assessment, target audience
• Design phase: Review and refine syllabus design, assessment planning, final project
• Development phase: Review and adjust chapter materials as they're generated

python run.py "Advanced Algorithms" --copilot --exp algo_course_v2

Automatic Evaluation

Entry Point: evaluate.py – Automatic assessment and scoring

# Evaluate a specific experiment
python evaluate.py --exp web_dev_v1

Evaluation results are saved in eval/{experiment_name}/ directory.

LaTeX-to-PPTX Conversion

Convert generated LaTeX Beamer slides to editable PowerPoint presentations with professional design:

# Convert a single chapter
python -c "
from src.latex_to_pptx import LaTeXToPPTXConverter
converter = LaTeXToPPTXConverter()
converter.convert('exp/my_course/chapter_1/slides.tex', 'exp/my_course/chapter_1/slides.pptx')
"

# Convert all chapters in a course
python -c "
from src.latex_to_pptx import LaTeXToPPTXConverter
converter = LaTeXToPPTXConverter()
converter.convert_directory('exp/my_course/')
"

PPTX Design Features:

• 🎨 Midnight Executive palette — navy/ice-blue/orange color scheme with Georgia/Calibri fonts
• 📐 Slide Masters — consistent layouts via CONTENT_MASTER, CONTENT_CODE, and DARK_MASTER
• 🌓 Dark/light sandwich — dark slides for title/conclusion, light for content
• 🔤 Smart icons — topic-aware icons from react-icons (robot, brain, code, etc.) in colored circles
• 🎭 Varied layouts — auto-detected: single-text, list-only, blocks, code, columns, mixed
• 💫 Visual polish — shadows on blocks/code, sidebar accent motif, decorative circles
• 📏 Typography — 36pt+ titles, 14-16pt body, auto-scaling for long titles

Architecture: LaTeX .tex → [Python LaTeXParser] → JSON → [Node.js pptxgenjs] → .pptx

Background Execution with Logging

For long-running tasks, run in the background:

# Run in background with log file
nohup python run.py "Advanced Machine Learning" --exp ml_advanced > logs/ml_course.log 2>&1 &

# Monitor progress
tail -f logs/ml_course.log

# Check process status
ps aux | grep "python run.py"

📚 Example Workflows

Complete Course Design

# Step 1: Generate course using catalog
python run.py "Python Fundamentals" \
  --catalog python_catalog \
  --model gpt-4o \
  --exp py_course_v1

# Step 2: Evaluate results
python evaluate.py --exp py_course_v1

# Step 3: Review generated materials
open exp/py_course_v1/result_syllabus_design.md
open exp/py_course_v1/chapter_1/slides.pdf

Interactive Development (Copilot)

python run.py "Advanced Algorithms" --copilot --exp algo_course_v2

# You'll be prompted for feedback after each phase:
# - Analysis → feedback on goals, resources, audience
# - Design → feedback on syllabus, assessments
# - Development → feedback on chapter materials

📖 Documentation

❓ FAQ

# macOS/Linux: Find and kill the process
lsof -i :8000
kill -9 <PID>

# Or change port in .env file
API_PORT=8001

📜 License

Instructional Agents is released under the MIT License.

Third-party attribution

The HTML slide style-selection assets in assets/slide_gen/skill are adapted from Frontend Slides by Zara Zhang. Frontend Slides is used under the MIT License; its original copyright notice and license terms are preserved in assets/slide_gen/skill/LICENSE.