Metadata-Version: 2.4
Name: badge-quest
Version: 0.3.2
Summary: Collect, learn, repeat. A reflection badge system for Learning Management Systems.
Project-URL: Homepage, https://github.com/michael-borck/badge-quest
Project-URL: Documentation, https://github.com/michael-borck/badge-quest/tree/main/docs
Project-URL: Repository, https://github.com/michael-borck/badge-quest
Project-URL: Issues, https://github.com/michael-borck/badge-quest/issues
Author-email: Michael <michael@example.com>
License: MIT
License-File: LICENSE
Keywords: badges,blackboard,education,gamification,lms,reflection
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: Flask
Classifier: Intended Audience :: Education
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Education
Requires-Python: >=3.10
Requires-Dist: click>=8.1.0
Requires-Dist: flask-cors>=4.0.0
Requires-Dist: flask>=3.0.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: python-levenshtein>=0.20.0
Requires-Dist: requests>=2.31.0
Requires-Dist: textblob>=0.17.1
Requires-Dist: textstat>=0.7.3
Provides-Extra: dev
Requires-Dist: basedpyright>=1.0.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
Requires-Dist: pytest>=7.4.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Description-Content-Type: text/markdown

# 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).