Open-source, privacy-first, language-model-assisted teaching platform for educators.
QuizWeaver helps teachers generate curriculum-aligned quizzes, study materials, rubrics, and scaffolded variants — all from their actual lesson content. It uses language models (LLMs) to produce draft content, constrained by deterministic, rule-based systems that teachers control. The language model writes; the rules verify; the teacher decides.
QuizWeaver is teacher-facing only. Student work never touches language model providers. Teachers generate; students receive.
The industry calls tools like this "AI-powered." We think that term overpromises and under-explains. Here's what QuizWeaver actually does:
- Language models (like Google Gemini, Anthropic Claude, OpenAI GPT, or local models via Ollama) generate draft text — quiz questions, study materials, lesson plans. This is statistical text generation, not understanding or reasoning.
- Deterministic, rule-based systems handle everything that needs to be reliable: standards alignment, cognitive frameworks (Bloom's Taxonomy, Webb's DOK), reading-level bands, and assessment blueprints. These are lookup tables, formulas, and constraints — not language models.
- Teachers review, edit, and approve all output before it reaches students. The language model is a drafting tool, not an authority.
We use the term "AI" in this documentation where it refers to the established academic field (AI Literacy, Responsible AI) and for discoverability, but we want to be clear: QuizWeaver is a language-model-assisted tool with deterministic constraints and human oversight, not an autonomous system.
QuizWeaver is built on research-backed principles for responsible use of language models in education:
-
Human-in-the-Loop -- Teachers review and approve all LLM-generated content before it reaches students. The language model assists; teachers decide. (U.S. Dept. of Education, 2023; UNESCO, 2024)
-
Glass Box, Not Black Box -- Teachers see which lessons informed a quiz, what cognitive levels were targeted, and how questions were generated. No hidden algorithms. (Khosravi et al., 2022)
-
Deterministic Layers -- Standards alignment, cognitive frameworks (Bloom's, DOK), and rubric criteria are rule-based, not generated by language models. The LLM operates within teacher-defined constraints. (ISTE Standards, 2024)
-
Verification Over Trust -- LLM output is a draft, not a deliverable. The UI encourages editing, regeneration, and critical review at every step. (Digital Promise, 2024)
-
Privacy by Design -- Local-first architecture (SQLite). No cloud dependencies for core functionality. No student PII in LLM prompts. (UNESCO, 2024)
-
Student Data Protection -- Student work (essays, answers, writing samples) is NEVER sent to language model providers. No feature creates a path -- even an accidental one -- for student content to reach third-party APIs. (FERPA, 20 U.S.C. 1232g)
-
Cost Transparency -- Teachers see exactly what LLM calls cost and can control spending. Mock mode enables full exploration at zero cost. (Digital Promise, 2024)
-
Equity & Access -- Works with any LLM provider including free/local models (Ollama). Reading-level variants and scaffolded content support diverse learners. (ISTE, 2024; UNESCO, 2024)
- UNESCO (2024). AI Competency Framework for Teachers
- U.S. Dept. of Education (2023). AI and the Future of Teaching and Learning
- ISTE (2024). Standards for Educators
- Digital Promise (2024). AI Literacy Framework
- Khosravi et al. (2022). Explainable AI in Education
- Quiz Generation -- Multi-agent LLM pipeline (Generator + Critic) produces draft questions aligned to your taught content
- 10 Question Types -- Multiple choice, true/false, short answer, fill-in-blank, ordering, matching, essay, multiple-answer (select all that apply), stimulus/passage-based question groups, and cloze (fill-in-multiple-blanks)
- Cognitive Frameworks -- Bloom's Taxonomy and Webb's DOK with configurable distribution across cognitive levels (question types are independent of Bloom's levels)
- Standards Alignment -- Multi-state standards (SOL, CCSS ELA, CCSS Math, NGSS, TEKS) with searchable picker
- Topic-Based Generation -- Generate quizzes from topics or pasted content (enduring understandings, objectives) without a source quiz
- Exit Tickets -- Quick 1-5 question formative assessments for end-of-class checks
- Question Bank -- Save and reuse favorite questions across quizzes
- Flashcards -- LLM-generated drafts with inline editing, Anki-compatible TSV export
- Study Guides -- Comprehensive review materials from lesson content
- Vocabulary Lists -- Key terms with definitions and context
- Review Sheets -- Quick-reference summaries for test preparation
- Reading-Level Variants -- ELL, below grade, on grade, and advanced versions of any quiz
- Rubric Generation -- Standards-aligned rubrics with proficiency levels (Beginning through Advanced)
- Scaffolded Content -- Adjusted complexity while maintaining assessment rigor
- Word Bank -- Fill-in-blank questions include a word bank for supported guessing
- Assessment Blueprints -- 5 built-in templates (quick check, unit test, midterm, final, standardized practice) with Lexile and Flesch-Kincaid readability metrics
- Gap Analysis -- Compare assumed knowledge (from lessons) to actual performance
- Standards Mastery -- Track progress toward curriculum standards
- Trend Analysis -- Visualize performance over time
- Re-teach Suggestions -- LLM-generated recommendations based on identified gaps
- PDF -- Print-ready quizzes and study materials with text wrapping
- DOCX -- Editable Word documents with answer keys
- CSV -- Spreadsheet-compatible data export
- GIFT -- Moodle-compatible quiz import format (including native cloze support)
- QTI -- Canvas-compatible import packages (matching, ordering, short answer, multiple-answer, stimulus, cloze)
- Quizizz CSV -- Direct import to Quizizz for gamified review
- TSV -- Anki-compatible flashcard export
- Student-Facing Mode -- Export PDF, DOCX, or CSV without answers, Bloom's levels, or provider info; A/B/C/D lettering; answer key on a separate page
- Lesson Plan Generator -- 10-section plans with differentiation, teach-assess loop, and formative checkpoints
- Export -- PDF and DOCX export for lesson plans
- Class Sections & Organization -- Separate lesson histories, quizzes, and analytics per class/block
- Lesson Tracking -- Log lessons with automatic topic extraction and knowledge depth tracking
- Template Export/Import -- Save and share quiz templates as JSON files
- Cost Tracking -- Per-action and per-provider cost breakdowns with budget thresholds
- Dark Mode -- Full dark theme with WCAG AA compliant contrast
- Keyboard Shortcuts -- Chord-based navigation (press
?for help)
- Dyslexia-Friendly Font -- OpenDyslexic toggle with enhanced spacing options
- Color Blind Safe Mode -- Wong palette with text-based indicators alongside color cues
- Screen Reader Support -- Skip navigation, ARIA landmarks, and semantic markup
- Text-to-Speech -- Client-side Web Speech API for quiz question read-aloud
- Mobile Responsive -- Touch-friendly (44px targets), 4 breakpoints, responsive tables
- Prompt Summary -- After generation, teachers can see exactly what prompt was sent to the language model and what context was included
- Critic Feedback -- When the quality critic rejects questions, rejection reasons are shown so teachers understand why
- Per-Quiz Cost Display -- Token usage and estimated cost shown on each quiz's detail page
- Pre-Generation Estimate -- Before generating, the form shows an estimated cost based on the selected provider and question count
- Contextual Tooltips -- Inline explanations of language model concepts throughout the UI
- Confidence Banners -- Every LLM-generated output is labeled as a draft requiring review
- Privacy Notices -- Clear disclosure of what data is sent to language model providers
- Help Section -- Dedicated section on understanding language models, with cited educational research
- Install Python 3.9+ (check "Add Python to PATH" on Windows)
- Download and extract QuizWeaver
- Windows: Double-click
run.bat - macOS / Linux: Open a terminal and run
chmod +x run.sh && ./run.sh
The launcher installs dependencies, creates the database, and opens your browser automatically. See docs/INSTALLATION.md for detailed step-by-step instructions.
pip install -r requirements.txt
python -c "
import yaml
with open('config.yaml') as f:
config = yaml.safe_load(f)
from src.web.app import create_app
app = create_app(config)
app.run(host='127.0.0.1', port=5000)
"Open http://localhost:5000 -- the onboarding wizard will guide you through creating your first class.
python -m pytest # 2261 tests, all passingdocker compose upQuizWeaver is LLM-agnostic. Choose the provider that fits your needs and budget:
| Provider | Cost | Privacy | Setup |
|---|---|---|---|
| Mock (default) | Free | No data sent anywhere | None -- works out of the box |
| Ollama (local) | Free | Data stays on your machine | Install Ollama, pull a model |
| Google Gemini | Pay-per-use (free tier) | Data sent to Google | Get API key |
| Anthropic Claude | Pay-per-use | Data sent to Anthropic | Get API key |
| OpenAI | Pay-per-use | Data sent to OpenAI | Get API key |
| Google Vertex AI | Pay-per-use | Data stays in GCP | GCP project + gcloud auth |
| Any OpenAI-compatible API | Varies | Varies | Configure base URL + key |
The built-in Provider Setup Wizard (Settings > Setup Wizard) walks you through configuration step by step, including cost implications and privacy considerations.
# config.yaml
llm:
provider: "mock"Mock mode produces placeholder content for exploring all features at zero cost. No API key needed.
Web Dashboard (Flask) / CLI (main.py)
|
+---------+---------+
| | |
Classroom Lesson Standards
Manager Tracker Database
| | |
+----+----+---------+
|
Quiz Generator / Study Generator / Exit Ticket / Variant Generator / Rubric Generator
|
Agentic Pipeline (Generator + Critic)
|
LLM Provider (Mock | Gemini | Anthropic | OpenAI | Ollama | Vertex AI)
|
Cost Tracking (per-action, per-provider, budget thresholds)
|
Export (PDF | DOCX | CSV | GIFT | QTI | Quizizz | TSV)
See docs/ARCHITECTURE.md for the full system diagram.
QuizWeaver/
├── run.bat # Windows launcher (double-click to start)
├── run.sh # macOS/Linux launcher
├── main.py # CLI entry point
├── config.yaml # Application configuration
├── requirements.txt # Python dependencies
├── .env.example # Environment variable template
│
├── src/
│ ├── classroom.py # Class sections CRUD (create, list, update, delete)
│ ├── lesson_tracker.py # Lesson logging, topic extraction, knowledge tracking
│ ├── quiz_generator.py # Quiz generation orchestration
│ ├── study_generator.py # Flashcards, study guides, vocabulary, review sheets
│ ├── variant_generator.py # Reading-level variants (ELL, below/on/advanced)
│ ├── rubric_generator.py # Standards-aligned rubric generation
│ ├── topic_generator.py # Topic-based generation (no source quiz needed)
│ ├── question_regenerator.py # Individual question regeneration
│ ├── agents.py # Agentic pipeline (Generator, Critic, Orchestrator)
│ ├── cognitive_frameworks.py # Bloom's, DOK, question type definitions
│ ├── standards.py # Standards database CRUD and search
│ ├── cost_tracking.py # API cost logging, rate limits, budget thresholds
│ ├── performance_import.py # CSV upload and quiz score entry
│ ├── performance_analytics.py # Gap analysis, trends, mastery tracking
│ ├── reteach_generator.py # LLM-generated re-teach suggestions
│ ├── exit_ticket_generator.py # Quick formative assessments (1-5 questions)
│ ├── critic_validation.py # Structured validation rules for critic agent
│ ├── export.py # CSV, DOCX, GIFT, PDF, QTI, Quizizz export
│ ├── study_export.py # Flashcard TSV/CSV, study material PDF/DOCX
│ ├── rubric_export.py # Rubric CSV, DOCX, PDF
│ ├── database.py # SQLAlchemy ORM models
│ ├── migrations.py # Idempotent database migration runner
│ ├── llm_provider.py # LLM abstraction (Mock, Gemini, Anthropic, OpenAI, Vertex)
│ ├── mock_responses.py # Fabricated LLM responses for development
│ └── web/
│ ├── app.py # Flask application factory
│ ├── routes.py # Thin shim (delegates to blueprints)
│ ├── auth.py # User authentication
│ ├── config_utils.py # Configuration save helper
│ ├── tooltip_data.py # LLM literacy tooltip content
│ └── blueprints/ # 8 Flask blueprints (69+ routes)
│ ├── auth.py # Login, logout, setup (5 routes)
│ ├── main.py # Dashboard, onboarding, help (5 routes)
│ ├── classes.py # Class CRUD, lessons (8 routes)
│ ├── quizzes.py # Quiz list/detail/export/generate, costs (13 routes)
│ ├── study.py # Study materials, exit tickets (8+ routes)
│ ├── analytics.py # Performance analytics, import (10 routes)
│ ├── settings.py # Provider config, standards (8 routes)
│ └── content.py # Variants, rubrics, lesson plans, templates (12 routes)
│
├── tests/ # 2261 tests (pytest)
├── templates/ # Jinja2 HTML templates
├── static/ # CSS, JavaScript, static assets
├── migrations/ # SQL migration scripts (001-010)
├── data/ # Standards database (sol_standards.json)
├── prompts/ # Agent system prompts
├── docs/
│ ├── ARCHITECTURE.md # System architecture
│ ├── BACKLOG.md # Feature backlog with principles
│ ├── COMPETITIVE_ANALYSIS.md # EdTech landscape research
│ ├── COST_STRATEGY.md # Cost control approach
│ ├── INSTALLATION.md # Step-by-step setup guide for teachers
│ ├── USER_GUIDE.md # Feature walkthrough for teachers
│ ├── API_REFERENCE.md # API endpoint documentation
│ ├── SECURITY_AUDIT.md # Security findings and remediations
│ ├── DEMO_SCRIPT.md # Demo walkthrough script
│ ├── DEMO_VIDEO_SCRIPT.md # Demo video narration
│ ├── WORKSHOP_SLIDES.md # Workshop presentation outline
│ └── ROADMAP.md # Development roadmap
└── archive/ # Historical planning artifacts
├── openspec/ # OpenSpec change specs (completed)
├── Project_Planning/ # Original architecture planning docs
└── agent_prompts/ # Multi-agent workshop prompts
| Route | Description |
|---|---|
/dashboard |
Tool-oriented landing page with classes, activity feed |
/classes |
List all classes with lesson/quiz stats |
/classes/<id> |
Class detail with knowledge depth, lessons, quizzes |
/generate |
Generate a quiz for a class |
/generate/topics |
Generate from specific topics |
/quizzes |
Browse all quizzes with search and filtering |
/quizzes/<id> |
Quiz detail with inline editing |
/study/generate |
Generate study materials (flashcards, guides, vocabulary, review sheets) |
/study |
Browse study materials |
/exit-ticket/generate |
Generate quick formative assessments (1-5 questions) |
/question-bank |
Save, browse, and search favorite questions |
/standards |
Browse and search standards database |
/analytics |
Performance analytics and gap analysis |
/lesson-plans |
Browse and generate lesson plans |
/quiz-templates |
Import and export quiz templates |
/costs |
API cost tracking with budget thresholds |
/settings |
LLM provider configuration and testing |
/settings/wizard |
Guided provider setup with LLM literacy context |
/help |
User guide with language model literacy section |
- Always use MockLLMProvider during development (
llm.provider: "mock") - Never send student work to language model providers -- QuizWeaver is teacher-facing only
- Test-Driven Development -- Write tests before implementation
- Local-First -- SQLite + file-based config, no cloud dependencies
- Teacher-in-Control -- All LLM outputs are drafts requiring teacher approval
10 migration scripts, idempotent (safe to run multiple times):
| Table | Purpose |
|---|---|
classes |
Teacher classes/blocks |
lesson_logs |
Lessons taught per class |
quizzes |
Generated quizzes (with variant/parent tracking, generation metadata for Glass Box) |
questions |
Individual quiz questions |
rubrics / rubric_criteria |
Standards-aligned rubrics |
performance_data |
Anonymized student performance |
standards |
Curriculum standards database |
question_bank |
Saved/favorite questions |
users |
Teacher authentication |
QuizWeaver follows strict principles for responsible use of language models in education. Before contributing, please read:
- CLAUDE.md -- Development principles and guidelines
- docs/BACKLOG.md -- Feature backlog with Student Data Protection principle
- docs/COMPETITIVE_ANALYSIS.md -- EdTech landscape research
Key contribution guidelines:
- All LLM-generated content must be labeled as drafts requiring teacher review
- No feature may send student work to cloud language model providers
- New LLM features must work with MockLLMProvider at zero cost
- Test coverage is required (2261 tests currently passing)
This project is licensed under the MIT License. See LICENSE for details.