# 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!