5.4 KiB
5.4 KiB
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
- Install dependencies:
bun install
- 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
- Build and start:
bun run build
bun start
Contributing
Feel free to open issues or submit pull requests for improvements!