Collect, learn, repeat.
BadgeQuest is a gamified reflection system designed for Learning Management Systems (LMS). It transforms student reflections into meaningful achievements through an engaging badge progression system.
- Weekly Reflection Tracking: Students submit reflections that are validated for quality
- Smart Validation: Checks word count, readability, sentiment, and uniqueness
- Similarity Detection: Prevents resubmission of previous reflections with minor changes (80% threshold)
- Badge Progression: Earn badges from "Dabbler" to "Mastery" based on consistent participation
- Micro-Credentials: Theme-based achievements for focused reflection topics (e.g., AI Ethics Explorer, Innovation Champion)
- LMS Integration: Ready-to-use HTML forms for Blackboard (Canvas and Moodle coming soon)
- Instructor Tools: Generate progress reports for easy grade center uploads
- Privacy-First: Only stores anonymized data with hashed reflections
- Configurable: Support multiple courses with custom badge themes and micro-credentials
# Install from PyPI
pip install badge-quest
# Or with uv (recommended)
uv pip install badge-quest# Initialize the database
badgequest init-db
# Start the Flask server
badgequest run-server --port 5000- Extract the LMS form template:
badgequest extract-lms blackboard --output form.html- Generate progress reports:
badgequest generate-progress --students students.txt --course AI101 --output badges.csvBadgeQuest supports course-specific configurations through environment variables:
# .env file
SECRET_KEY=your-secret-key-here
DATABASE_URL=sqlite:///reflections.db
CORS_ORIGINS=https://your-lms.eduThe default badge progression:
| Weeks | Badge | Title |
|---|---|---|
| 1 | 🧪 | Dabbler |
| 3 | 🥾 | Explorer |
| 5 | 🧠 | Thinker |
| 7 | 🛡️ | Warrior |
| 10 | 🛠️ | Builder |
| 12 | 🗣️ | Explainer |
| 14+ | 🏆 | Mastery |
Students can earn theme-based micro-credentials by submitting reflections with specific themes. Example configuration:
"micro_credentials": {
"ethics_explorer": {
"name": "AI Ethics Explorer",
"emoji": "⚖️",
"description": "Demonstrated strong ethical analysis in AI reflections",
"themes": ["ethics", "responsibility"],
"min_submissions": 2
}
}POST /stamp- Submit a reflection (with optional theme_id)GET /progress/<student_id>- View student progress including micro-credentialsGET /verify/<code>- Verify a reflection codeGET /api/micro-credentials/<student_id>- Get detailed micro-credentials informationPOST /api/progress/bulk- Get progress for multiple students including micro-credentials
# Clone the repository
git clone https://github.com/yourusername/badgequest.git
cd badgequest
# Install with development dependencies
uv pip install -e ".[dev]"
# Run tests
pytest
# Format code
ruff format .
# Type check
basedpyrightMIT License - see LICENSE file for details.
Contributions are welcome! Please feel free to submit a Pull Request.
For issues and feature requests, please use the GitHub issue tracker.