142 lines
5.4 KiB
Markdown
142 lines
5.4 KiB
Markdown
# ChemistryHelp Bot
|
|
|
|
A Discord bot that helps students learn STEM subjects through daily and weekly AI-generated questions. Compete individually and in teams while earning points!
|
|
|
|
## Features
|
|
|
|
- **AI-Generated Questions**: Uses Google's Gemini 2.5-pro to generate unique STEM questions daily and weekly
|
|
- **Multiple Subjects**: Mathematics, Physics, Chemistry, Organic Chemistry, Biology, Computer Science, and Engineering
|
|
- **Points & Competition System**: Earn points for correct answers and compete on leaderboards
|
|
- **Team System**: Join teams and compete together with adjusted scoring for fairness
|
|
- **Automated Grading**: AI-powered answer grading using Ollama
|
|
- **Beautiful Rendering**: Mathematical equations and diagrams rendered using Typst
|
|
|
|
## Points System
|
|
|
|
### How Points Work
|
|
|
|
#### Earning Points
|
|
- **Daily Questions**: 2 points per correct answer (one per subject per day)
|
|
- **Weekly Questions**: 10 points per correct answer (one per subject per week)
|
|
- Users can answer multiple subjects each period to maximize points
|
|
- Points are added to both your personal score and your team's score
|
|
|
|
#### Personal Leaderboard
|
|
- Displays top users ranked by total points
|
|
- Shows: username, total points, daily completions, weekly completions, and team affiliation
|
|
- Updated in real-time as users answer questions
|
|
|
|
### Team System
|
|
|
|
#### Joining Teams
|
|
- Users can join a team anytime using `/jointeam <team_name>`
|
|
- No time restrictions for users joining teams
|
|
- Admins can change user teams during the first week of each month (1st-7th) using `/team change-user`
|
|
- When you join a team, your future points contribute to that team's total
|
|
|
|
#### Raw Points vs Adjusted Points
|
|
Teams have two point values to ensure fair competition between different team sizes:
|
|
|
|
**Raw Points**
|
|
- The sum of all points earned by team members
|
|
- Displayed to administrators only
|
|
- Used for internal tracking
|
|
|
|
**Adjusted Points** (Used for Team Leaderboard)
|
|
To level the playing field, smaller teams receive multipliers to their raw points:
|
|
|
|
| Team Size | Multiplier | Reasoning |
|
|
|-----------|-----------|-----------|
|
|
| 1-5 members | **1.5x** | Small teams need the biggest boost to compete |
|
|
| 6-10 members | **1.3x** | Medium-small teams get moderate bonus |
|
|
| 11-15 members | **1.1x** | Medium-large teams get small bonus |
|
|
| 16+ members | **1.0x** | Large teams have advantage through numbers |
|
|
|
|
**Example:**
|
|
- Team A has 5 members with 100 raw points → 150 adjusted points (1.5x)
|
|
- Team B has 20 members with 180 raw points → 180 adjusted points (1.0x)
|
|
- Team A ranks higher despite fewer total points!
|
|
|
|
This system ensures that:
|
|
- Small dedicated teams can compete with larger teams
|
|
- Individual contribution matters more in smaller teams
|
|
- Larger teams need consistent participation from all members
|
|
|
|
#### Team Leaderboard
|
|
- Ranks teams by **adjusted points only**
|
|
- Shows: team name, member count, and adjusted points
|
|
- Regular users only see adjusted points
|
|
- Admins see both raw and adjusted points for transparency
|
|
|
|
### Commands
|
|
|
|
#### User Commands
|
|
- `/daily <subject>` - Answer today's daily question
|
|
- `/weekly <subject>` - Answer this week's question
|
|
- `/leaderboard` - View top users
|
|
- `/stats` - View your personal statistics
|
|
- `/jointeam <team_name>` - Join a team anytime
|
|
|
|
#### Admin Commands
|
|
- `/serverstats` - View server-wide statistics
|
|
- `/team create <name> [description]` - Create a new team
|
|
- `/team change-user <user> <team>` - Change a user's team (first week of month only)
|
|
- `/team delete <team_name>` - Delete a team
|
|
- `/team leaderboard` - View team rankings
|
|
- `/regenerate daily|weekly <subject>` - Force regenerate a question
|
|
|
|
## Technical Details
|
|
|
|
### Technology Stack
|
|
- **Discord.js 14.25.1**: Discord bot framework
|
|
- **MongoDB + Mongoose 9.0.0**: Database for users, teams, questions, and submissions
|
|
- **LangChain 1.0.6**: Context-aware question generation
|
|
- **Google Generative AI (Gemini 2.5-pro)**: Question generation with historical context
|
|
- **Ollama (llama3.2)**: Answer grading
|
|
- **Typst CLI**: Mathematical typesetting for beautiful equations
|
|
|
|
### Database Collections
|
|
- **Users**: Stores userId, username, points, team affiliation, completion counts
|
|
- **Teams**: Stores team info, raw points, member count, adjusted points
|
|
- **Questions**: Stores all generated questions with topic, difficulty, typst source
|
|
- **ScheduledQuestions**: Caches daily/weekly questions to prevent regeneration
|
|
- **Submissions**: Tracks user answers with grading results
|
|
|
|
### Question Generation
|
|
- Questions are generated once per period (daily/weekly) per subject
|
|
- Gemini analyzes the last 30 questions to avoid repetition
|
|
- Enhanced Typst validation ensures proper mathematical formatting
|
|
- Maximum 2 parts per question for better learning focus
|
|
- Questions cached in MongoDB to ensure all users get the same question
|
|
|
|
### Answer Grading
|
|
- Ollama llama3.2 grades answers by comparing to reference answer
|
|
- Returns detailed feedback with score (0-10) and correctness (true/false)
|
|
- Score ≥ 7 counts as correct and awards points
|
|
- Submissions stored in MongoDB for tracking and analytics
|
|
|
|
## Setup
|
|
|
|
1. Install dependencies:
|
|
```bash
|
|
bun install
|
|
```
|
|
|
|
2. Configure environment variables in `.env`:
|
|
```
|
|
DISCORD_TOKEN=your_discord_bot_token
|
|
GOOGLE_API_KEY=your_gemini_api_key
|
|
MONGODB_URI=mongodb://your_mongodb_host:27017/chemhelp-bot
|
|
LOGS_CHANNEL_ID=your_logs_channel_id
|
|
OLLAMA_API=http://your_ollama_host:11434
|
|
```
|
|
|
|
4. Build and start:
|
|
```bash
|
|
bun run build
|
|
bun start
|
|
```
|
|
|
|
## Contributing
|
|
|
|
Feel free to open issues or submit pull requests for improvements! |