badge-quest 0.3.3

Collect, learn, repeat. A reflection badge system for Learning Management Systems.

BadgeQuest 🏆

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.

Features

• 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

Quick Start

Installation

# Install from PyPI
pip install badge-quest

# Or with uv (recommended)
uv pip install badge-quest

Running the Server

# Initialize the database
badgequest init-db

# Start the Flask server
badgequest run-server --port 5000

For Instructors

1. Extract the LMS form template:

badgequest extract-lms blackboard --output form.html

2. Generate progress reports:

badgequest generate-progress --students students.txt --course AI101 --output badges.csv

Configuration

BadgeQuest 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.edu

Badge Levels

The default badge progression:

Weeks	Badge	Title
1	🧪	Dabbler
3	🥾	Explorer
5	🧠	Thinker
7	🛡️	Warrior
10	🛠️	Builder
12	🗣️	Explainer
14+	🏆	Mastery

Micro-Credentials

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
    }
}

API Endpoints

• POST /stamp - Submit a reflection (with optional theme_id)
• GET /progress/<student_id> - View student progress including micro-credentials
• GET /verify/<code> - Verify a reflection code
• GET /api/micro-credentials/<student_id> - Get detailed micro-credentials information
• POST /api/progress/bulk - Get progress for multiple students including micro-credentials

Development

# 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
basedpyright

License

MIT License - see LICENSE file for details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Support

For issues and feature requests, please use the GitHub issue tracker.