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!