A multi-agent AI system that designs university classroom activities from course readings.
Drop in a PDF of this week's reading. Watch five specialised AI agents debate, critique, and refine activity ideas in real time. Get a polished run sheet and interactive presentation pages ready to project in class.
You upload a course reading (PDF, TXT, or Markdown). The system:
- Analyses the reading — extracts key concepts, misconceptions, intellectual tensions, and catalogues every example from the text (so activities can test transfer, not just recognition)
- Five AI agents independently propose activities — each from a different perspective (content depth, social dynamics, cognitive science, engagement, practicality)
- Agents critique each other's work — rating proposals 1–10, flagging serious flaws, identifying what works
- Top proposals get revised based on the critiques
- Best complementary pair is selected — optimising for structural contrast, concept coverage, and quality
- Instructor run sheet is generated — a lean, printable document with hooks, social structures, and timing flows
- Interactive presentation pages are generated — full-screen, dark-themed activity controllers with AI-generated illustrations, designed to project in a 150-person lecture hall
The entire process streams live to your browser, so you can watch the agents think, argue, and converge.
University instructors running flipped classrooms where:
- Students have already done the reading before class
- Class time is for high-engagement activities, not lectures
- You need activities that work with ~150 students at tables of 8
- You want zero-materials, zero-prep activities that run on nothing but a compelling prompt and clever social structure
The system encodes 20 years of classroom experimentation and learning science research (ICAP framework, retrieval practice, productive failure, structured academic controversy, peer instruction) into its agent personas.
| Agent | Focus | What They Kill |
|---|---|---|
| Content Architect | Deep reading grounding, novel scenarios | Activities that replay textbook examples instead of testing transfer |
| Social Dynamics Engineer | Equitable participation, cross-table interaction | "Just discuss in your group" without explicit structure |
| Cognitive Scientist | ICAP framework, retrieval practice, productive failure | Activities rated Active when they could be Interactive |
| Engagement Designer | Irresistible hooks, dinner-party energy | Anything that sounds like a professional development workshop |
| Practical Auditor | Zero materials, 60-second setup, two moving parts max | Anything requiring handouts, named roles, or complex instructions |
Each activity gets an interactive presentation page — a full-screen "game board" projected in the lecture hall. Students can also follow along on their phones via QR code.
Features:
- Dark theme with UQ branding (purple/gold on black)
- Stage-by-stage navigation (click or arrow keys)
- AI-generated illustrations (via Google Gemini) displayed alongside scenarios
- Readable from the back of a 150-person room
- Mobile-responsive for phone viewing
- Self-contained HTML files (work offline, downloadable as ZIP)
- Python 3.11+
- Claude CLI — installed and authenticated (claude.ai/download). This uses your Claude subscription (e.g., Claude Max), not API credits.
- Google Gemini API key — for image generation on presentation pages (optional but recommended)
git clone https://github.com/jtangen/activity-planner.git
cd activity-planner
pip install -e .For AI-generated illustrations on presentation pages, set your Gemini API key:
export GEMINI_API_KEY="your-key-here"Get a free key from Google AI Studio. If you skip this, everything works — you just won't get illustrations on the presentation pages.
actplanThis starts a local web server at http://localhost:5050 and opens your browser.
- Drop a reading file (PDF, TXT, or Markdown) onto the upload screen
- Optionally add notes from past weeks and select a priority dimension
- Click Generate Run Sheet
- Watch the agents debate in real time (~3–5 minutes)
- Download the run sheet and presentation pages
Reading (PDF/TXT/MD)
│
▼
┌──────────────────┐
│ Phase 1: Analyse │ → Key concepts, do-not-replicate list, tensions
└────────┬─────────┘
▼
┌──────────────────────────────────────────────────┐
│ Phase 2: Propose (5 agents × 2 activities each) │ → 10 activity proposals
└────────┬─────────────────────────────────────────┘
▼
┌──────────────────────────────────────────────────┐
│ Phase 3: Critique (each agent rates all others) │ → Ratings, flaws, top picks
└────────┬─────────────────────────────────────────┘
▼
┌──────────────────────────────┐
│ Phase 4: Revise (top 4) │ → Improved proposals
└────────┬─────────────────────┘
▼
┌──────────────────────────────┐
│ Phase 5: Select best pair │ → Complementary pair
└────────┬─────────────────────┘
▼
┌──────────────────────────────┐
│ Phase 6: Run sheet │ → Instructor-facing HTML
└────────┬─────────────────────┘
▼
┌──────────────────────────────┐
│ Phase 7: Presentations │ → Student-facing HTML + images
└──────────────────────────────┘
Tech stack: Flask, vanilla JavaScript, Server-Sent Events (SSE), Pydantic, Jinja2, Claude CLI, Google Gemini API.
All LLM calls use structured JSON output via Pydantic schemas. Phases 2–4 run agent calls in parallel via ThreadPoolExecutor. The frontend receives events in real time via SSE with a replay buffer for late-connecting clients.
src/actplan/
├── __main__.py # Entry point — starts Flask on port 5050
├── server.py # Flask routes, SSE streaming, job management
├── pipeline.py # 7-phase pipeline orchestrator
├── agents.py # 5 agent personas + all prompt templates
├── models.py # Pydantic models for all 7 phases
├── llm.py # Claude CLI wrapper (structured JSON output)
├── image_gen.py # Gemini API wrapper (text-to-image)
├── pdf.py # PDF/TXT text extraction
├── runsheet.py # Run sheet HTML renderer
├── presentation.py # Presentation page HTML renderer
├── templates/
│ ├── index.html # Main web app (3-screen SPA)
│ ├── runsheet.html.j2 # Instructor run sheet template
│ └── presentation.html.j2 # Student presentation template
└── static/
├── app.js # Frontend logic (SSE, events, UI)
└── style.css # All styles
Run sheet — A compact, printable HTML page with:
- Activity titles, hooks, social structures, timing flows
- Screen cues (when to show/advance the presentation)
- Key concepts targeted and contingency notes
- Full agent debate log (collapsible) showing every proposal, critique, rating, and revision
Presentation pages — Self-contained HTML files per activity with:
- Stage-by-stage activity flow (instructor advances with click/keyboard)
- Scenarios, instructions, and AI-generated illustrations
- QR code for students to follow along on phones
- Works offline (all images embedded as base64)
Priority dimension — Give one agent's perspective extra weight:
- Balanced (default), Content Depth, Social Dynamics, Cognitive Rigour, Engagement, Practical
Past weeks notes — Freeform text injected into every agent's context:
"The debate worked brilliantly last week. Gallery walks have been falling flat. Students loved the speed-dating format in Week 3."
These notes persist across sessions via localStorage.
| Package | Purpose |
|---|---|
flask |
Web server + routing |
pydantic |
Structured data models for LLM output |
jinja2 |
HTML template rendering |
pymupdf |
PDF text extraction |
google-genai |
Gemini image generation |
pillow |
Image format conversion (PNG → JPEG) |
Plus the Claude CLI tool (not a pip package — install from claude.ai/download).
- Zero materials — Activities run on nothing but a prompt and a social structure. No handouts, no props, no printed anything.
- Dinner-party energy — The best activities feel like something students would do voluntarily. The room should be loud.
- Transfer, not recognition — Activities target reading concepts through novel scenarios, never replaying the textbook's own examples.
- Two moving parts max — One compelling thing to do + one clever structural move. If it takes more than 60 seconds to explain, it's too complicated.
- Transparent reasoning — The full agent debate is embedded in every run sheet, so you can see exactly why each activity was chosen and what was rejected.
MIT