Initial Code

README.md

@@ -1,2 +1,142 @@
-# ChemistryHelpBot
+# 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!