# 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
```bash
# Install from PyPI
pip install badge-quest
# Or with uv (recommended)
uv pip install badge-quest
```
### Running the Server
```bash
# Initialize the database
badgequest init-db
# Start the Flask server
badgequest run-server --port 5000
```
### For Instructors
1. Extract the LMS form template:
```bash
badgequest extract-lms blackboard --output form.html
```
2. Generate progress reports:
```bash
badgequest generate-progress --students students.txt --course AI101 --output badges.csv
```
## Configuration
BadgeQuest supports course-specific configurations through environment variables:
```bash
# .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:
```python
"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
```bash
# 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](https://github.com/yourusername/badgequest/issues).
Raw data
{
"_id": null,
"home_page": null,
"name": "badge-quest",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "badges, blackboard, education, gamification, lms, reflection",
"author": null,
"author_email": "Michael <michael@example.com>",
"download_url": "https://files.pythonhosted.org/packages/25/19/655f302ec2b14b6f43b4343e71de876ec186796eab287fcb567d8918b79e/badge_quest-0.3.2.tar.gz",
"platform": null,
"description": "# BadgeQuest \ud83c\udfc6\n\n> Collect, learn, repeat.\n\nBadgeQuest is a gamified reflection system designed for Learning Management Systems (LMS). It transforms student reflections into meaningful achievements through an engaging badge progression system.\n\n## Features\n\n- **Weekly Reflection Tracking**: Students submit reflections that are validated for quality\n- **Smart Validation**: Checks word count, readability, sentiment, and uniqueness\n- **Similarity Detection**: Prevents resubmission of previous reflections with minor changes (80% threshold)\n- **Badge Progression**: Earn badges from \"Dabbler\" to \"Mastery\" based on consistent participation\n- **Micro-Credentials**: Theme-based achievements for focused reflection topics (e.g., AI Ethics Explorer, Innovation Champion)\n- **LMS Integration**: Ready-to-use HTML forms for Blackboard (Canvas and Moodle coming soon)\n- **Instructor Tools**: Generate progress reports for easy grade center uploads\n- **Privacy-First**: Only stores anonymized data with hashed reflections\n- **Configurable**: Support multiple courses with custom badge themes and micro-credentials\n\n## Quick Start\n\n### Installation\n\n```bash\n# Install from PyPI\npip install badge-quest\n\n# Or with uv (recommended)\nuv pip install badge-quest\n```\n\n### Running the Server\n\n```bash\n# Initialize the database\nbadgequest init-db\n\n# Start the Flask server\nbadgequest run-server --port 5000\n```\n\n### For Instructors\n\n1. Extract the LMS form template:\n```bash\nbadgequest extract-lms blackboard --output form.html\n```\n\n2. Generate progress reports:\n```bash\nbadgequest generate-progress --students students.txt --course AI101 --output badges.csv\n```\n\n## Configuration\n\nBadgeQuest supports course-specific configurations through environment variables:\n\n```bash\n# .env file\nSECRET_KEY=your-secret-key-here\nDATABASE_URL=sqlite:///reflections.db\nCORS_ORIGINS=https://your-lms.edu\n```\n\n## Badge Levels\n\nThe default badge progression:\n\n| Weeks | Badge | Title |\n|-------|-------|-------|\n| 1 | \ud83e\uddea | Dabbler |\n| 3 | \ud83e\udd7e | Explorer |\n| 5 | \ud83e\udde0 | Thinker |\n| 7 | \ud83d\udee1\ufe0f | Warrior |\n| 10 | \ud83d\udee0\ufe0f | Builder |\n| 12 | \ud83d\udde3\ufe0f | Explainer |\n| 14+ | \ud83c\udfc6 | Mastery |\n\n### Micro-Credentials\n\nStudents can earn theme-based micro-credentials by submitting reflections with specific themes. Example configuration:\n\n```python\n\"micro_credentials\": {\n \"ethics_explorer\": {\n \"name\": \"AI Ethics Explorer\",\n \"emoji\": \"\u2696\ufe0f\",\n \"description\": \"Demonstrated strong ethical analysis in AI reflections\",\n \"themes\": [\"ethics\", \"responsibility\"],\n \"min_submissions\": 2\n }\n}\n```\n\n## API Endpoints\n\n- `POST /stamp` - Submit a reflection (with optional theme_id)\n- `GET /progress/<student_id>` - View student progress including micro-credentials\n- `GET /verify/<code>` - Verify a reflection code\n- `GET /api/micro-credentials/<student_id>` - Get detailed micro-credentials information\n- `POST /api/progress/bulk` - Get progress for multiple students including micro-credentials\n\n## Development\n\n```bash\n# Clone the repository\ngit clone https://github.com/yourusername/badgequest.git\ncd badgequest\n\n# Install with development dependencies\nuv pip install -e \".[dev]\"\n\n# Run tests\npytest\n\n# Format code\nruff format .\n\n# Type check\nbasedpyright\n```\n\n## License\n\nMIT License - see LICENSE file for details.\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n## Support\n\nFor issues and feature requests, please use the [GitHub issue tracker](https://github.com/yourusername/badgequest/issues).",
"bugtrack_url": null,
"license": "MIT",
"summary": "Collect, learn, repeat. A reflection badge system for Learning Management Systems.",
"version": "0.3.2",
"project_urls": {
"Documentation": "https://github.com/michael-borck/badge-quest/tree/main/docs",
"Homepage": "https://github.com/michael-borck/badge-quest",
"Issues": "https://github.com/michael-borck/badge-quest/issues",
"Repository": "https://github.com/michael-borck/badge-quest"
},
"split_keywords": [
"badges",
" blackboard",
" education",
" gamification",
" lms",
" reflection"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "fd4247096fa7be2452d275b7cf8b514bccd1c57d39de2c2090322c566c651617",
"md5": "865c4b568a7bcc24bcf084576a8f4769",
"sha256": "dc90dba16212c35b0872bcc5dd75606dc2aba1266dad1336049e7b9513c6c57b"
},
"downloads": -1,
"filename": "badge_quest-0.3.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "865c4b568a7bcc24bcf084576a8f4769",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 20883,
"upload_time": "2025-07-20T12:37:21",
"upload_time_iso_8601": "2025-07-20T12:37:21.564731Z",
"url": "https://files.pythonhosted.org/packages/fd/42/47096fa7be2452d275b7cf8b514bccd1c57d39de2c2090322c566c651617/badge_quest-0.3.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "2519655f302ec2b14b6f43b4343e71de876ec186796eab287fcb567d8918b79e",
"md5": "1a55d85345d97c16441597df0122b652",
"sha256": "cf095d0d6494f8975475366151b1979f05d36b0d04d1b80e1b2c651ad1ee0f74"
},
"downloads": -1,
"filename": "badge_quest-0.3.2.tar.gz",
"has_sig": false,
"md5_digest": "1a55d85345d97c16441597df0122b652",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 54640,
"upload_time": "2025-07-20T12:37:23",
"upload_time_iso_8601": "2025-07-20T12:37:23.446532Z",
"url": "https://files.pythonhosted.org/packages/25/19/655f302ec2b14b6f43b4343e71de876ec186796eab287fcb567d8918b79e/badge_quest-0.3.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-20 12:37:23",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "michael-borck",
"github_project": "badge-quest",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "badge-quest"
}
JSON
