add all file

.dockerignore

@@ -0,0 +1,11 @@
+__pycache__
+*.pyc
+*.pyo
+*.pyd
+.env
+venv/
+.env.*
+.git
+.gitignore
+class_data.db
+main.json

.env.example

@@ -0,0 +1,5 @@
+DISCORD_TOKEN=your_bot_token_here
+CR_USER_ID=123456789012345678
+CR_ROLE_NAME=Class Representative
+MISTRAL_API_KEY=your_mistral_key
+ANNOUNCEMENT_CHANNEL_ID=123456789012345678s

.gitignore

@@ -0,0 +1,26 @@
+# Environment variables
+.env
+
+# Python
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+.Python
+env/
+venv/
+.venv/
+
+# Database (will be recreated)
+# class_data.db
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*~
+
+# DisCloud
+.discloud/
+*.db
+*.log

Dockerfile

@@ -0,0 +1,35 @@
+# Use official Python image
+FROM python:3.11-slim
+
+# Set a working directory
+WORKDIR /app
+
+# Install system deps (if any)
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    build-essential \
+    && rm -rf /var/lib/apt/lists/*
+
+# Copy requirements and install
+COPY requirements.txt /app/requirements.txt
+RUN pip install --no-cache-dir -r /app/requirements.txt
+
+# Copy source
+COPY . /app
+
+# Make start script executable
+RUN chmod +x /app/scripts/start.sh
+
+# Create a non-root user with UID 1000 (standard for HF Spaces)
+RUN useradd -m -u 1000 appuser
+
+# Switch to the new user
+USER appuser
+
+# Set home to the user's home directory
+ENV HOME=/home/appuser \
+    PATH=/home/appuser/.local/bin:$PATH
+
+
+
+# Default command
+CMD ["/app/scripts/start.sh"]

README.md

@@ -0,0 +1,148 @@
+---
+title: Class Assistant Bot
+emoji: 🤖
+colorFrom: blue
+colorTo: purple
+sdk: docker
+pinned: false
+
+---
+
+# Class Assistant Bot
+
+A Discord bot to manage class schedules, assignments, notes, and shared materials — with optional AI-powered answers.
+
+This repository contains the Class Assistant Bot used to fetch and present schedules, manage assignments and materials, and provide quick study help via an AI assistant. It supports local development with SQLite and production deployment using PostgreSQL (Supabase) and Hugging Face Spaces (Docker).
+
+## Quick highlights
+- Run locally: `python3 src/main.py`
+- Run and force import schedule from `main.json`: `python3 src/main.py --override`
+- Logs: `bot.log` (contains INFO/DEBUG logs and message-level logs like `message to bot` / `message by bot`)
+- Config: environment variables (see below)
+
+## Table of contents
+- [Requirements](#requirements)
+- [Configuration](#configuration)
+- [Running locally](#running-locally)
+- [CLI flags](#cli-flags)
+- [Commands overview](#commands-overview)
+- [Deployment (Hugging Face Spaces + Supabase)](#deployment-hugging-face-spaces--supabase)
+- [Troubleshooting](#troubleshooting)
+- [Contributing](#contributing)
+
+## Requirements
+- Python 3.11+ (project uses 3.11 in Dockerfile)
+- Install dependencies:
+
+```bash
+pip install -r requirements.txt
+```
+
+## Configuration
+Create a `.env` file at the project root or set these environment variables in your deployment environment.
+
+Required environment variables
+- `DISCORD_TOKEN` — Your Discord bot token (required)
+
+Optional/Recommended
+- `DATABASE_URL` — PostgreSQL connection URI (when provided, the bot uses PostgreSQL; otherwise it falls back to SQLite)
+- `MISTRAL_API_KEY` — API key for the AI assistant integration
+- `CR_USER_ID` — (optional) numeric Discord user ID of the Class Representative (CR) — grants CR-only commands
+- `CR_ROLE_NAME` — (optional) role name used to mark CRs (default: "Class Representative")
+- `ANNOUNCEMENT_CHANNEL_ID` — (optional) channel id for scheduled announcements
+
+Example `.env` (do NOT commit this file):
+
+```env
+DISCORD_TOKEN=your_discord_token_here
+DATABASE_URL=postgresql://postgres:password@db.supabase.co:5432/postgres
+MISTRAL_API_KEY=sk-xxxx
+CR_USER_ID=123456789012345678
+CR_ROLE_NAME=CR
+ANNOUNCEMENT_CHANNEL_ID=987654321012345678
+```
+
+The config loader is `src/configuration/config.py` which uses `python-dotenv` to read `.env`.
+
+## Running locally
+
+1. Install dependencies: `pip install -r requirements.txt`
+2. Create `.env` with at least `DISCORD_TOKEN` set.
+3. Run the bot:
+
+```bash
+python3 src/main.py
+```
+
+If you want the bot to import the schedule from `main.json` and overwrite any existing schedule in the database, run:
+
+```bash
+python3 src/main.py --override
+```
+
+Notes
+- The bot writes logs to `bot.log` in the project root. Check this file for detailed debug info.
+- For development the bot will fall back to SQLite if `DATABASE_URL` is not set.
+
+## CLI flags
+- `--override` — Force import of `main.json` into the database (clears existing schedule rows first). If you omit `--override` and the database already has schedule entries the import will be skipped to avoid accidental overwrites.
+
+## Commands overview (quick)
+Type `!bothelp` in Discord to get the dynamic help menu. Example commonly used commands:
+
+- `!schedule today` — Today's classes
+- `!schedule tomorrow` — Tomorrow's classes
+- `!schedule day <day>` — That day's classes
+- `!schedule week` — Full week schedule
+- `!assignment add Subject="Math" Topic="Algebra" Due="2025-12-01"` — Add assignment
+- `!assignment list` — List pending assignments
+- `!materials all` — List uploaded materials
+- `!materials add Subject="Math" Link="https://..."` — (CR-only) add material
+- `!materials delete Subject="Math" Link="https://..."` — (CR-only) delete material
+- `!notes <Subject>` — View study notes
+- `!ask <question>` — Ask the AI assistant
+
+The bot also supports grouped commands (e.g., `!assignment add/list/delete`) — use `!bothelp <category>` or `!bothelp <command>` for detailed usage.
+
+## Deployment (Hugging Face Spaces + Supabase)
+
+1. Create a Supabase project and get your PostgreSQL connection string (set it to `DATABASE_URL` in HF Spaces).
+2. Create a new Space on Hugging Face, select **Docker** as the SDK.
+3. Add the necessary environment variables (Secrets) in the Space settings:
+   - `DISCORD_TOKEN`
+   - `DATABASE_URL`
+   - `MISTRAL_API_KEY`
+   - `CR_USER_ID`
+   - `CR_ROLE_NAME`
+   - `ANNOUNCEMENT_CHANNEL_ID`
+4. The Space will build using the `Dockerfile` and start the bot.
+
+
+
+
+Notes about persistence
+- Use Supabase (PostgreSQL) in production for reliable persistence. If no `DATABASE_URL` is configured the bot will use SQLite for local testing only.
+
+## Logging
+- Console: INFO and above
+- File: `bot.log` (DEBUG and above)
+
+The bot logs message-level events such as `message to bot: ...` and `message by bot: ...` which helps debug command usage and AI responses.
+
+## Troubleshooting
+
+- Bot fails to start / `ModuleNotFoundError: No module named 'discord'` — ensure you installed the dependencies in the right Python environment (virtualenv/venv).
+- `Improper token` or bot offline — verify `DISCORD_TOKEN` value.
+- Schedule import overwritten unexpectedly — run without `--override` to preserve DB; use `--override` only when intentional.
+- Database connection issues — verify `DATABASE_URL` and check Supabase project and Space secrets.
+
+## Contributing
+- Bug reports and PRs are welcome. Please open issues for feature requests or share deployment notes.
+
+## Useful files
+- `src/` — bot source
+- `src/cogs/` — command groups (schedule, assignments, AI, etc.)
+- `main.json` — main schedule file used for bulk import
+- `requirements.txt` — pip deps
+- `Dockerfile`, `scripts/start.sh` — deployment helpers
+- `guides/` — deployment and DB setup guides

configuration/config.py

@@ -0,0 +1,13 @@
+import os
+from dotenv import load_dotenv
+
+# Ensure we load .env from the project root
+ROOT = os.path.abspath(os.path.join(os.path.dirname(__file__), '..'))
+DOTENV_PATH = os.path.join(ROOT, '.env')
+load_dotenv(DOTENV_PATH)
+
+TOKEN = os.getenv("DISCORD_TOKEN")
+CR_USER_ID = int(os.getenv("CR_USER_ID", "0"))
+CR_ROLE_NAME = os.getenv("CR_ROLE_NAME", "Class Representative")
+MISTRAL_API_KEY = os.getenv("MISTRAL_API_KEY")
+CHANNEL_ID = int(os.getenv("ANNOUNCEMENT_CHANNEL_ID", "0"))

database/__init__.py

@@ -0,0 +1 @@
+from .database import init_db, get_db

database/database.py

@@ -0,0 +1,60 @@
+import os
+from sqlalchemy import create_engine, text
+from sqlalchemy.orm import sessionmaker, scoped_session
+from .models import Base
+
+# Load .env file to ensure DATABASE_URL is available
+from dotenv import load_dotenv
+load_dotenv()
+
+# Database URL configuration
+# Priority: DATABASE_URL env var (PostgreSQL) > SQLite fallback
+DATABASE_URL = os.getenv('DATABASE_URL')
+
+if DATABASE_URL:
+    # Production: Use PostgreSQL from environment variable
+    # Handle postgres:// vs postgresql:// (some providers use old format)
+    if DATABASE_URL.startswith('postgres://'):
+        DATABASE_URL = DATABASE_URL.replace('postgres://', 'postgresql://', 1)
+    
+    engine = create_engine(DATABASE_URL)
+else:
+    # Local development: Use SQLite
+    # Store DB file in /data if available (writable volume), or project root locally
+    if os.path.exists('/data') and os.access('/data', os.W_OK):
+        DB_NAME = '/data/class_data.db'
+    else:
+        ROOT = os.path.abspath(os.path.join(os.path.dirname(__file__), '..'))
+        DB_NAME = os.path.join(ROOT, 'class_data.db')
+    
+    DATABASE_URL = f"sqlite:///{DB_NAME}"
+    engine = create_engine(DATABASE_URL, connect_args={"check_same_thread": False})
+
+SessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=engine)
+ScopedSession = scoped_session(SessionLocal)
+
+def init_db():
+    """Initialize the database by creating all tables defined in models.py."""
+    Base.metadata.create_all(bind=engine)
+    
+    # SQLite-specific migration: Add new columns if they don't exist
+    # Only run this for SQLite databases
+    if 'sqlite' in str(engine.url):
+        with engine.connect() as conn:
+            # Check schedule table columns
+            result = conn.execute(text("PRAGMA table_info(schedule)"))
+            columns = [row.name for row in result]
+            
+            if 'instructor' not in columns:
+                conn.execute(text("ALTER TABLE schedule ADD COLUMN instructor TEXT"))
+            if 'note' not in columns:
+                conn.execute(text("ALTER TABLE schedule ADD COLUMN note TEXT"))
+            conn.commit()
+
+def get_db():
+    """Provide a transactional scope around a series of operations."""
+    db = SessionLocal()
+    try:
+        return db
+    finally:
+        db.close()

database/models.py

@@ -0,0 +1,42 @@
+from sqlalchemy import Column, Integer, String
+from sqlalchemy.orm import declarative_base
+
+Base = declarative_base()
+
+class Schedule(Base):
+    __tablename__ = "schedule"
+    id = Column(Integer, primary_key=True, autoincrement=True)
+    day = Column(String)
+    time = Column(String)
+    subject = Column(String)
+    group_name = Column(String)
+    room = Column(String)
+    instructor = Column(String)
+    note = Column(String)
+
+class Assignment(Base):
+    __tablename__ = "assignments"
+    id = Column(Integer, primary_key=True, autoincrement=True)
+    subject = Column(String)
+    topic = Column(String)
+    due_date = Column(String)
+
+class Note(Base):
+    __tablename__ = "notes"
+    id = Column(Integer, primary_key=True, autoincrement=True)
+    subject = Column(String)
+    link = Column(String)
+
+class Material(Base):
+    __tablename__ = "materials"
+    id = Column(Integer, primary_key=True, autoincrement=True)
+    subject = Column(String)
+    drive_link = Column(String)
+
+class Assessment(Base):
+    __tablename__ = "assessments"
+    id = Column(Integer, primary_key=True, autoincrement=True)
+    subject = Column(String)
+    date = Column(String)
+    time = Column(String)
+    description = Column(String)

guides/HUGGINGFACE_DEPLOYMENT_GUIDE.md

@@ -0,0 +1,67 @@
+# Deploying Class Assistant Bot on Hugging Face Spaces
+
+This guide explains how to deploy your Discord bot to [Hugging Face Spaces](https://huggingface.co/spaces) using Docker.
+
+## Why Hugging Face Spaces?
+Hugging Face Spaces offers a simple way to host machine learning demos and apps. By using the Docker SDK, we can deploy our custom Discord bot environment. The free tier is generous and suitable for many bot applications.
+
+## Prerequisites
+1.  A [Hugging Face](https://huggingface.co) account.
+2.  A [GitHub](https://github.com) account with this code pushed to a repository (optional, but recommended for syncing).
+
+## Deployment Steps
+
+### 1. Create a New Space
+1.  Log in to Hugging Face.
+2.  Click on your profile picture and select **New Space**.
+3.  **Space Name**: `class-assistant-bot` (or any name you prefer).
+4.  **License**: MIT (or your choice).
+5.  **SDK**: Select **Docker**.
+6.  **Space Hardware**: **CPU Basic (Free)** is usually sufficient.
+7.  **Visibility**: Public or Private (Private is recommended if you want to hide your source code/logs, but Public is fine if you don't mind).
+
+### 2. Configure the Space
+After creating the Space, you'll see a "Building" status. It might fail initially if environment variables aren't set.
+
+1.  Go to the **Settings** tab of your Space.
+2.  Scroll down to the **Variables and secrets** section.
+3.  Click **New secret** to add your sensitive environment variables.
+
+### 3. Set Environment Variables (Secrets)
+Add the following secrets. You can find these values in your local `.env` file.
+
+| Key | Value Description |
+| :--- | :--- |
+| `DATABASE_URL` | **Required**: Your PostgreSQL connection string from Supabase. See [SUPABASE_SETUP.md](SUPABASE_SETUP.md) for setup instructions. |
+| `DISCORD_TOKEN` | Your Discord Bot Token. |
+| `MISTRAL_API_KEY` | Your Mistral AI API Key. |
+| `CR_USER_ID` | (Optional) The Discord User ID of the Class Representative. |
+| `CR_ROLE_NAME` | (Optional) The role name for CR permissions (e.g., "CR"). |
+| `ANNOUNCEMENT_CHANNEL_ID` | (Optional) Channel ID for daily reminders. |
+
+> **Note**: Hugging Face Spaces exposes port `7860` by default. The `Dockerfile` in this repo is configured to expose this port and the bot's keep-alive server listens on it.
+
+### 4. Sync with GitHub (Optional but Recommended)
+If you want to push code from your local machine/GitHub to the Space:
+1.  In the Space **Settings**, look for "Git" or "Repository".
+2.  You can add your GitHub repository as a remote or use GitHub Actions to push to the Space.
+3.  Alternatively, you can manually upload files via the "Files" tab, but using Git is better.
+
+### 5. Verify Deployment
+1.  Go to the **App** tab.
+2.  You should see "Running" status.
+3.  The app preview might show a JSON response `{"status": "ok", "service": "class-assistant-bot"}`. This means the keep-alive server is running.
+4.  Check your Discord server; the bot should be online!
+
+## Troubleshooting
+
+*   **Build Failed**: Check the "Logs" tab. Ensure `requirements.txt` is correct and the Dockerfile build process finishes without errors.
+*   **Runtime Error**: If the build succeeds but the app crashes, check the "Logs".
+*   **Port Issues**: If the app is "Running" but the health check fails or the bot doesn't stay online, ensure the `PORT` environment variable is effectively being used (defaults to 7860 in Dockerfile).
+*   **Database**: Ensure `DATABASE_URL` is correct. The bot relies on Supabase for persistence. Local SQLite files in the Space will be lost when the Space restarts.
+
+## Important Notes
+
+### Persistence
+*   **PostgreSQL (Supabase)**: Highly recommended. Data is stored externally and persists across restarts.
+*   **Local Storage**: Hugging Face Spaces are ephemeral. Any files written to the disk (like a local SQLite DB) will be lost when the Space restarts or rebuilds. **Always use Supabase for production.**

guides/SUPABASE_SETUP.md

@@ -0,0 +1,87 @@
+# Supabase PostgreSQL Setup Guide
+
+This guide shows you how to set up a **free PostgreSQL database** on Supabase for your Discord bot.
+
+## Why Supabase?
+- **Free tier**: 500MB database storage
+- **Always online**: Database never sleeps
+- **PostgreSQL**: Industry-standard, reliable database
+- **Easy setup**: Takes less than 5 minutes
+
+## Step 1: Create a Supabase Account
+
+1. Go to [supabase.com](https://supabase.com)
+2. Click **Start your project**
+3. Sign up with GitHub (recommended) or email
+
+## Step 2: Create a New Project
+
+1. Click **New Project**
+2. Fill in the details:
+   - **Name**: `class-assistant-bot` (or any name)
+   - **Database Password**: Create a strong password (save this!)
+   - **Region**: Choose closest to you (e.g., Singapore, Mumbai)
+   - **Pricing Plan**: Free
+3. Click **Create new project**
+4. Wait 1-2 minutes for the database to be provisioned
+
+## Step 3: Get Your Database Connection String
+
+1. In your Supabase project dashboard, click **Settings** (gear icon in sidebar)
+2. Click **Database** in the left menu
+3. Scroll down to **Connection string**
+4. Select **URI** tab
+5. Copy the connection string. It looks like:
+   ```
+   postgresql://postgres:[YOUR-PASSWORD]@db.xxxxxxxxxxxxx.supabase.co:5432/postgres
+   ```
+6. **Important**: Replace `[YOUR-PASSWORD]` with the actual password you created in Step 2
+
+## Step 4: Add to Hugging Face Spaces Environment Variables
+
+1. Go to your Hugging Face Space settings.
+2. Scroll to **Variables and secrets**.
+3. Click **New secret**.
+4. Add:
+   - **Key**: `DATABASE_URL`
+   - **Value**: Paste your connection string from Step 3
+5. Click **Save**.
+
+Hugging Face will automatically rebuild your Space with the new database connection.
+
+## Step 5: Verify It's Working
+
+1. Wait for the Space to finish building.
+2. Check the logs in the Space dashboard.
+3. You should see "Service is live" (or similar startup logs) and no database errors.
+4. Test your bot in Discord - try adding an assignment or schedule.
+
+## Troubleshooting
+
+**Connection Error**: 
+- Double-check the password in your connection string
+- Make sure there are no extra spaces
+
+**Tables Not Created**:
+- The bot automatically creates tables on first startup
+- Check Space logs for any errors
+
+**Data Not Persisting**:
+- Verify `DATABASE_URL` is set correctly in Space secrets
+- Check Supabase dashboard → Table Editor to see your data
+
+## Managing Your Database
+
+You can view and manage your data directly in Supabase:
+1. Go to your Supabase project
+2. Click **Table Editor** in the sidebar
+3. You'll see all your tables: `schedule`, `assignments`, `notes`, etc.
+4. You can view, edit, or delete data directly here
+
+## Free Tier Limits
+
+- **Storage**: 500MB (plenty for a Discord bot)
+- **Bandwidth**: 2GB/month
+- **API Requests**: Unlimited
+
+Your bot will likely use less than 10MB of storage, so you're well within limits!

main.json

@@ -0,0 +1,350 @@
+{
+  "metadata": {
+    "program": "Electronics, Communication and Information Engineering (BEI)",
+    "year_part": "II/I",
+    "class_start": "2082-08-15",
+    "class_end": "2082-12-03",
+    "default_lecture_room": "Lecture Room 4",
+    "note": "All other days begin at 10:15."
+  },
+  "GroupA": {
+    "sunday": [
+      {
+        "time": "10:15\u201311:55",
+        "subject": "Control System [L+R]",
+        "instructor": "SKR",
+        "room": "Lecture Room 4"
+      },
+      {
+        "time": "11:55\u20131:35",
+        "subject": "Advanced Electronics [L]",
+        "instructor": "JKM",
+        "room": "Lecture Room 4"
+      },
+      {
+        "time": "1:35\u20132:25",
+        "subject": "BREAK",
+        "instructor": "None",
+        "room": "Lecture Room 4"
+      },
+      {
+        "time": "2:25\u20134:55",
+        "subject": "Microprocessor[Practical] A",
+        "instructor": "Dr. RKS + KN",
+        "room": "Electronics Lab 4"
+      }
+    ],
+    "monday": [
+      {
+        "time": "10:15\u201311:55",
+        "subject": "Microprocessor [L]",
+        "instructor": "Dr. RKS",
+        "room": "Lecture Room 4"
+      },
+      {
+        "time": "11:55\u20131:35",
+        "subject": "English",
+        "instructor": "None",
+        "room": "Lecture Room 4"
+      },
+      {
+        "time": "1:35\u20132:25",
+        "subject": "English Lab Group A",
+        "instructor": "None",
+        "room": "Lecture Room 4"
+      },
+      {
+        "time": "3:15\u20134:05",
+        "subject": "English(T)",
+        "instructor": "None",
+        "room": "Lecture Room 4"
+      }
+    ],
+    "tuesday": [
+      {
+        "time": "7:15\u20139:30",
+        "subject": "Control System [P] ALT WEEK GROUP A/B ALT WEEK",
+        "instructor": "YA + AD + AP",
+        "room": "Lecture Room 4"
+      },
+      {
+        "time": "9:30\u201310:15",
+        "subject": "BREAK",
+        "instructor": "None",
+        "room": "Lecture Room 4"
+      },
+      {
+        "time": "10:15\u201311:55",
+        "subject": "Computer Graphics and Visualization [L+T]",
+        "instructor": "JM",
+        "room": "Lecture Room 4"
+      },
+      {
+        "time": "11:55\u20131:35",
+        "subject": "Microprocessor[L+T]",
+        "instructor": "Dr. RKS",
+        "room": "Lecture Room 4"
+      },
+      {
+        "time": "1:35\u20132:25",
+        "subject": "BREAK",
+        "instructor": "None",
+        "room": "Lecture Room 4"
+      },
+      {
+        "time": "2:25\u20133:15",
+        "subject": "None",
+        "instructor": "None",
+        "room": "Lecture Room 4"
+      },
+      {
+        "time": "3:15\u20134:55",
+        "subject": "Math III [L]",
+        "instructor": "AKB",
+        "room": "Lecture Room 4"
+      }
+    ],
+    "wednesday": [
+      {
+        "time": "10:15\u201311:55",
+        "subject": "Control System [L]",
+        "instructor": "SKR",
+        "room": "Lecture Room 4"
+      },
+      {
+        "time": "11:55\u20131:35",
+        "subject": "Computer Graphics and Visualization [L+T]",
+        "instructor": "JM",
+        "room": "Lecture Room 4"
+      },
+      {
+        "time": "1:35\u20132:25",
+        "subject": "BREAK",
+        "instructor": "None",
+        "room": "Lecture Room 4"
+      },
+      {
+        "time": "2:25\u20134:55",
+        "subject": "Computer Graphics and Visualization [Practical] Group A",
+        "instructor": "JM + SST",
+        "room": "Computer Lab 6"
+      }
+    ],
+    "thursday": [
+      {
+        "time": "12:45\u20131:35",
+        "subject": "Math III [L]",
+        "instructor": "VP",
+        "room": "Lecture Room 4"
+      },
+      {
+        "time": "1:35\u20132:25",
+        "subject": "BREAK",
+        "instructor": "None",
+        "room": "Lecture Room 4"
+      },
+      {
+        "time": "2:25\u20134:55",
+        "subject": "Advance Electronics [P] GROUP A/B ALT WEEK",
+        "instructor": "JKM + SJ",
+        "room": "Electronics Lab 3"
+      }
+    ],
+    "friday": [
+      {
+        "time": "10:15\u201311:55",
+        "subject": "Advanced Electronics [L]",
+        "instructor": "NA",
+        "room": "Lecture Room 4"
+      },
+      {
+        "time": "11:55\u201312:45",
+        "subject": "MATH III [T]",
+        "instructor": "GBJ",
+        "room": "Lecture Room 4"
+      },
+      {
+        "time": "12:45\u20131:35",
+        "subject": "Math III [L]",
+        "instructor": "SG",
+        "room": "Lecture Room 4"
+      },
+      {
+        "time": "1:35\u20132:25",
+        "subject": "BREAK",
+        "instructor": "None",
+        "room": "Lecture Room 4"
+      }
+    ]
+  },
+  "GroupB": {
+    "sunday": [
+      {
+        "time": "10:15\u201311:55",
+        "subject": "Control System [L+R]",
+        "instructor": "SKR",
+        "room": "Lecture Room 4"
+      },
+      {
+        "time": "11:55\u20131:35",
+        "subject": "Advanced Electronics [L]",
+        "instructor": "JKM",
+        "room": "Lecture Room 4"
+      },
+      {
+        "time": "1:35\u20132:25",
+        "subject": "BREAK",
+        "instructor": "None",
+        "room": "Lecture Room 4"
+      }
+    ],
+    "monday": [
+      {
+        "time": "10:15\u201311:55",
+        "subject": "Microprocessor [L]",
+        "instructor": "Dr. RKS",
+        "room": "Lecture Room 4"
+      },
+      {
+        "time": "11:55\u20131:35",
+        "subject": "English",
+        "instructor": "None",
+        "room": "Lecture Room 4"
+      },
+      {
+        "time": "2:25\u20133:15",
+        "subject": "English Lab Group B",
+        "instructor": "None",
+        "room": "Lecture Room 4"
+      },
+      {
+        "time": "3:15\u20134:05",
+        "subject": "English(T)",
+        "instructor": "None",
+        "room": "Lecture Room 4"
+      }
+    ],
+    "tuesday": [
+      {
+        "time": "7:15\u20139:30",
+        "subject": "Control System [P] ALT WEEK GROUP A/B ALT WEEK",
+        "instructor": "YA + AD + AP",
+        "room": "Lecture Room 4"
+      },
+      {
+        "time": "9:30\u201310:15",
+        "subject": "BREAK",
+        "instructor": "None",
+        "room": "Lecture Room 4"
+      },
+      {
+        "time": "10:15\u201311:55",
+        "subject": "Computer Graphics and Visualization [L+T]",
+        "instructor": "JM",
+        "room": "Lecture Room 4"
+      },
+      {
+        "time": "11:55\u20131:35",
+        "subject": "Microprocessor[L+T]",
+        "instructor": "Dr. RKS",
+        "room": "Lecture Room 4"
+      },
+      {
+        "time": "1:35\u20132:25",
+        "subject": "BREAK",
+        "instructor": "None",
+        "room": "Lecture Room 4"
+      },
+      {
+        "time": "2:25\u20133:15",
+        "subject": "None",
+        "instructor": "None",
+        "room": "Lecture Room 4"
+      },
+      {
+        "time": "3:15\u20134:55",
+        "subject": "Math III [L]",
+        "instructor": "AKB",
+        "room": "Lecture Room 4"
+      }
+    ],
+    "wednesday": [
+      {
+        "time": "10:15\u201311:55",
+        "subject": "Control System [L]",
+        "instructor": "SKR",
+        "room": "Lecture Room 4"
+      },
+      {
+        "time": "11:55\u20131:35",
+        "subject": "Computer Graphics and Visualization [L+T]",
+        "instructor": "JM",
+        "room": "Lecture Room 4"
+      },
+      {
+        "time": "1:35\u20132:25",
+        "subject": "BREAK",
+        "instructor": "None",
+        "room": "Lecture Room 4"
+      }
+    ],
+    "thursday": [
+      {
+        "time": "10:15\u201312:45",
+        "subject": "Computer Graphics and Visualization [Practical] Group B",
+        "instructor": "JM + SST",
+        "room": "Computer Lab 5"
+      },
+      {
+        "time": "12:45\u20131:35",
+        "subject": "Math III [L]",
+        "instructor": "VP",
+        "room": "Lecture Room 4"
+      },
+      {
+        "time": "1:35\u20132:25",
+        "subject": "BREAK",
+        "instructor": "None",
+        "room": "Lecture Room 4"
+      },
+      {
+        "time": "2:25\u20134:55",
+        "subject": "Advance Electronics [P] GROUP A/B ALT WEEK",
+        "instructor": "JKM + SJ",
+        "room": "Electronics Lab 3"
+      }
+    ],
+    "friday": [
+      {
+        "time": "10:15\u201311:55",
+        "subject": "Advanced Electronics [L]",
+        "instructor": "NA",
+        "room": "Lecture Room 4"
+      },
+      {
+        "time": "11:55\u201312:45",
+        "subject": "MATH III [T]",
+        "instructor": "GBJ",
+        "room": "Lecture Room 4"
+      },
+      {
+        "time": "12:45\u20131:35",
+        "subject": "Math III [L]",
+        "instructor": "SG",
+        "room": "Lecture Room 4"
+      },
+      {
+        "time": "1:35\u20132:25",
+        "subject": "BREAK",
+        "instructor": "None",
+        "room": "Lecture Room 4"
+      },
+      {
+        "time": "2:25\u20134:55",
+        "subject": "Microprocessor[Practical] B",
+        "instructor": "Dr. RKS + KN",
+        "room": "Electronics Lab 4"
+      }
+    ]
+  }
+}

requirements.txt

@@ -0,0 +1,10 @@
+discord.py>=2.3.0
+python-dotenv>=1.0.0
+sqlalchemy>=2.0.0
+aiohttp>=3.9.0
+mistralai>=0.1.0
+asyncio
+requests
+flask
+psycopg2-binary
+APScheduler==3.10.4

scripts/start.sh

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Run from project root (/app) and ensure Python path includes both project root and src
+cd "$(dirname "$0")/.."
+export PYTHONPATH="/app:/app/src"
+cd /app/src
+exec python main.py

src/cogs/ai.py

@@ -0,0 +1,35 @@
+import discord
+from discord.ext import commands
+from database.database import get_db
+from database.models import Assessment
+from mistral_client import ask_mistral
+
+class AI(commands.Cog):
+    def __init__(self, bot):
+        self.bot = bot
+
+    #==============================================================================================================
+    #===============================================>AI ASK<=======================================================
+    #==============================================================================================================
+    @commands.command()
+    async def ask(self, ctx, *, question: str = None):
+        # Try local DB first
+        if not question:
+            await ctx.send('Usage: `!ask <question>`')
+            return
+        db = get_db()
+        try:
+            exams = db.query(Assessment).order_by(Assessment.date).all()
+            context = "Upcoming exams: " + "; ".join([f"{e.subject} on {e.date}" for e in exams[:5]])
+        finally:
+            db.close()
+
+        # Try Mistral
+        ai_answer = await ask_mistral(question, context)
+        if ai_answer:
+            await ctx.send(f"🤖 **AI Answer:**\n{ai_answer}")
+        else:
+            await ctx.send("I couldn't find an answer. Try asking the CR or teacher!")
+
+async def setup(bot):
+    await bot.add_cog(AI(bot))

src/cogs/assignments.py

@@ -0,0 +1,249 @@
+import discord
+import io
+from discord.ext import commands
+import re
+from database.database import get_db
+from database.models import Assignment, Note, Material
+from utils import is_cr
+
+class Assignments(commands.Cog):
+    def __init__(self, bot):
+        self.bot = bot
+
+    #==============================================================================================================
+    #============================================>ASSIGNMENTS<=====================================================
+    #==============================================================================================================
+    @commands.group(invoke_without_command=True)
+    async def assignment(self, ctx):
+        await ctx.send("Usage: `!assignment add/list/delete`")
+
+    @assignment.command()
+    async def add(self, ctx, *, args: str = None):
+        try:
+            if not args:
+                await ctx.send('Usage: `!assignment add Subject="Math" Topic="Algebra" Due="2025-12-01"`')
+                return
+            # Robust parsing with regex: Captures Key="Value" or Key='Value'
+            matches = re.findall(r'(\w+)="([^\"]*)"|(\w+)=\'([^\']*)\'', args)
+            parts = {}
+            for match in matches:
+                key = match[0] or match[2]
+                value = match[1] or match[3]
+                parts[key] = value
+            
+            subject = parts.get("Subject", "").strip()
+            topic = parts.get("Topic", "").strip()
+            due = parts.get("Due", "").strip()
+            
+            if not all([subject, topic, due]):
+                raise ValueError("Missing fields")
+            
+            db = get_db()
+            try:
+                new_assignment = Assignment(subject=subject.title(), topic=topic, due_date=due)
+                db.add(new_assignment)
+                db.commit()
+                await ctx.send(f"Assignment added: **{topic}** for **{subject.title()}**, due **{due}**")
+            finally:
+                db.close()
+        except:
+            await ctx.send('Usage: `!assignment add Subject="Math" Topic="Algebra" Due="2025-12-01"`\n\n**Examples that now work:**\n- `Subject="Control system" Topic="Chapter 1" Due="2025-12-01"`\n- `Subject="Math" Topic="Algebra" Due="2025-12-01" `')
+
+    @assignment.command()
+    async def list(self, ctx):
+        db = get_db()
+        try:
+            assignments = db.query(Assignment).order_by(Assignment.due_date).all()
+            
+            if not assignments:
+                await ctx.send("No assignments pending.")
+                return
+
+            msg = "**Pending Assignments**\n"
+            for a in assignments:
+                msg += f"{a.id}. **{a.subject}** - {a.topic} (Due: {a.due_date})\n"
+            await ctx.send(msg)
+        finally:
+            db.close()
+
+    @assignment.command()
+    @is_cr()
+    async def delete(self, ctx, index: int):
+        db = get_db()
+        try:
+            assignment = db.query(Assignment).filter(Assignment.id == index).first()
+            if assignment:
+                db.delete(assignment)
+                db.commit()
+                await ctx.send(f"Deleted assignment: {assignment.topic} ({assignment.subject})")
+            else:
+                await ctx.send("Assignment not found.")
+        finally:
+            db.close()
+
+    # NOTES (view-only) & MATERIALS (Similar structure)
+    @commands.group(invoke_without_command=True)
+    async def notes(self, ctx, subject=None):
+        """View study notes for a subject. Adding/removing notes is disabled.
+    
+        Usage: `!notes <Subject>`
+        """
+        if subject:
+            db = get_db()
+            try:
+                links = db.query(Note).filter(Note.subject == subject.title()).all()
+                if links:
+                    msg = f"**Study Notes for {subject.title()}**\n"
+                    for l in links:
+                        msg += f"• {l.link}\n"
+                    await ctx.send(msg)
+                else:
+                    await ctx.send(f"No notes found for **{subject.title()}**")
+            finally:
+                db.close()
+        else:
+            await ctx.send("Usage: `!notes <Subject>`")
+
+    # MATERIALS (Google Drive)
+    @commands.group(invoke_without_command=True)
+    async def materials(self, ctx):
+        if ctx.invoked_subcommand is None:
+            await ctx.send("Usage: `!materials [subject]/all/add/delete`\nNote: `add` and `delete` are CR-only commands.")
+
+    @materials.command()
+    async def all(self, ctx):
+        db = get_db()
+        try:
+            items = db.query(Material).all()
+        except Exception:
+            db.close()
+            await ctx.send("❌ Failed to read materials from the database.")
+            return
+
+        try:
+            if not items:
+                await ctx.send("No materials uploaded yet.")
+                return
+
+            header = "**All Google Drive Materials**\n"
+            # Build messages under Discord's 2000 char limit (leave some headroom)
+            max_len = 1900
+            current = header
+            for i in items:
+                line = f"• **{i.subject}**: {i.drive_link}\n"
+                if len(current) + len(line) > max_len:
+                    try:
+                        await ctx.send(current)
+                    except Exception:
+                        # fallback: send as file (use BytesIO)
+                        try:
+                            bio = io.BytesIO(current.encode('utf-8'))
+                            bio.seek(0)
+                            await ctx.send(file=discord.File(bio, filename='materials.txt'))
+                        except Exception:
+                            await ctx.send("❌ Failed to send materials list (message too large).")
+                            return
+                    current = header + line
+                else:
+                    current += line
+
+            # send remaining
+            try:
+                await ctx.send(current)
+            except Exception:
+                try:
+                    bio = io.BytesIO(current.encode('utf-8'))
+                    bio.seek(0)
+                    await ctx.send(file=discord.File(bio, filename='materials.txt'))
+                except Exception:
+                    await ctx.send("❌ Failed to send materials list.")
+        finally:
+            db.close()
+
+
+    @materials.command()
+    @is_cr()
+    async def add(self, ctx, *, args: str = None):
+        """Add a Google Drive material link. CR-only.
+    
+        Expected format: Subject="SubjectName" Link="https://drive.link/..."
+        """
+        if not args:
+            await ctx.send('Usage: `!materials add Subject="Math" Link="https://..."`')
+            return
+        try:
+            matches = re.findall(r'(\w+)="([^"]*)"|(\w+)=\'([^\']*)\'', args)
+            parts = {}
+            for match in matches:
+                key = match[0] or match[2]
+                value = match[1] or match[3]
+                parts[key] = value
+
+            subject = parts.get("Subject", "").strip()
+            link = parts.get("Link", "").strip()
+            if not subject or not link:
+                raise ValueError("Missing Subject or Link")
+
+            db = get_db()
+            try:
+                new_material = Material(subject=subject.title(), drive_link=link)
+                db.add(new_material)
+                db.commit()
+                await ctx.send(f"✅ Material added for **{subject.title()}**: {link}")
+            finally:
+                db.close()
+        except ValueError as ve:
+            await ctx.send(f"❌ {ve}. Usage: `!materials add Subject=\"Math\" Link=\"https://...\"`")
+        except Exception:
+            await ctx.send("❌ Failed to add material. Ensure command format is correct.")
+
+
+    @materials.command()
+    @is_cr()
+    async def delete(self, ctx, *, args: str = None):
+        """Delete a material by subject+link. CR-only.
+    
+        Expected: Subject="Math" Link="https://..."
+        """
+        # If user didn't provide args, show usage instead of raising a framework error
+        if not args:
+            await ctx.send('Usage: `!materials delete Subject="Math" Link="https://..."`')
+            return
+        try:
+            matches = re.findall(r'(\w+)="([^"]*)"|(\w+)=\'([^\']*)\'', args)
+            parts = {}
+            for match in matches:
+                key = match[0] or match[2]
+                value = match[1] or match[3]
+                parts[key] = value
+
+            subject = parts.get("Subject", "").strip()
+            link = parts.get("Link", "").strip()
+            if not subject or not link:
+                raise ValueError("Missing Subject or Link")
+
+            db = get_db()
+            try:
+                # Find and delete
+                # Note: This deletes ALL matching entries.
+                rows = db.query(Material).filter(
+                    Material.subject == subject.title(),
+                    Material.drive_link == link
+                ).all()
+                
+                if rows:
+                    for row in rows:
+                        db.delete(row)
+                    db.commit()
+                    await ctx.send(f"✅ Material deleted for **{subject.title()}**")
+                else:
+                    await ctx.send("⚠️ No matching material found to delete.")
+            finally:
+                db.close()
+        except ValueError as ve:
+            await ctx.send(f"❌ {ve}. Usage: `!materials delete Subject=\"Math\" Link=\"https://...\"`")
+        except Exception:
+            await ctx.send("❌ Failed to delete material. Ensure the format is correct and the material exists.")
+
+async def setup(bot):
+    await bot.add_cog(Assignments(bot))

src/cogs/general.py

@@ -0,0 +1,82 @@
+import discord
+from discord.ext import commands
+
+class General(commands.Cog):
+    def __init__(self, bot):
+        self.bot = bot
+
+    #==============================================================================================================
+    #===============================================>HELP<=========================================================
+    #==============================================================================================================
+    @commands.command(name="bothelp", aliases=["commands"])
+    async def bothelp(self, ctx, *, topic: str = None):
+        """Show bot help. Without args lists categories and top-level commands.
+        Provide a topic (cog name or command) to see detailed commands.
+        """
+        # Collect top-level commands (ignore hidden)
+        top_cmds = [c for c in self.bot.commands if not getattr(c, "parent", None) and not c.hidden]
+
+        # Group by cog name
+        cogs = {}
+        for cmd in top_cmds:
+            cog_name = cmd.cog_name or "General"
+            cogs.setdefault(cog_name, []).append(cmd)
+
+        if not topic:
+            # Build summary message
+            msg_lines = ["**Class Assistant Bot - Available command categories**\n"]
+            for cog_name, cmds in sorted(cogs.items()):
+                # show cog header and top-level command names
+                cmd_list = ", ".join([f"`!{c.name}`" for c in cmds])
+                msg_lines.append(f"**{cog_name}:** {cmd_list}")
+
+            msg_lines.append("\nType `!bothelp <category>` or `!bothelp <command>` for details. Example: `!bothelp schedule`")
+            await ctx.send("\n".join(msg_lines))
+            return
+
+        # Topic provided -> try to match a cog name first
+        topic_lower = topic.strip().lower()
+
+        # Match cog
+        for cog_name, cmds in cogs.items():
+            if cog_name.lower() == topic_lower:
+                lines = [f"**{cog_name} commands:**\n"]
+                for cmd in sorted(cmds, key=lambda x: x.name):
+                    if hasattr(cmd, "commands") and cmd.commands:
+                        # it's a Group; list its subcommands
+                        lines.append(f"`!{cmd.name}` - {cmd.help or 'Group of related commands.'}")
+                        for sc in cmd.commands:
+                            if sc.hidden:
+                                continue
+                            usage = f"!{sc.qualified_name} {sc.signature}".strip()
+                            lines.append(f"    • `{usage}` - {sc.help or ''}")
+                    else:
+                        usage = f"!{cmd.qualified_name} {cmd.signature}".strip()
+                        lines.append(f"`{usage}` - {cmd.help or ''}")
+
+                await ctx.send("\n".join(lines))
+                return
+
+        # Match a top-level command name
+        for cmd in top_cmds:
+            if cmd.name.lower() == topic_lower:
+                # If it's a group, show subcommands
+                if hasattr(cmd, "commands") and cmd.commands:
+                    lines = [f"**{cmd.name} (group) commands:**\n", f"{cmd.help or 'Group of related commands.'}"]
+                    for sc in cmd.commands:
+                        if sc.hidden:
+                            continue
+                        usage = f"!{sc.qualified_name} {sc.signature}".strip()
+                        lines.append(f"• `{usage}` - {sc.help or ''}")
+                    await ctx.send("\n".join(lines))
+                    return
+                else:
+                    usage = f"!{cmd.qualified_name} {cmd.signature}".strip()
+                    await ctx.send(f"`{usage}` - {cmd.help or 'No description available.'}")
+                    return
+
+        # No match found
+        await ctx.send("I couldn't find that category or command. Try `!bothelp` to see categories.")
+
+async def setup(bot):
+    await bot.add_cog(General(bot))

src/cogs/schedule.py

@@ -0,0 +1,379 @@
+import discord
+from discord.ext import commands
+from datetime import datetime, timedelta
+from database.database import get_db
+from database.models import Schedule as ScheduleModel
+from utils import (
+    is_cr, get_week_key, load_main_schedule_from_file, save_main_schedule_to_file,
+    apply_temp_replacement, apply_temp_cancellation, merge_schedule_for_week,
+    apply_temp_changes_to_db_rows, _parse_edit_cancel_args, _normalize_time,
+    _normalize_subject, MAIN_SCHEDULE, TEMP_CHANGES
+)
+import utils
+
+class Schedule(commands.Cog):
+    def __init__(self, bot):
+        self.bot = bot
+
+    def _format_schedule_entry(self, e):
+        """Helper to format a single schedule entry."""
+        subject = e.get('subject', 'Unknown')
+        time = e.get('time', 'Unknown')
+        room = e.get('room', '')
+        instructor = e.get('instructor', '')
+        note = e.get('note', '')
+        
+        # Parse Type from Subject
+        type_str = "Unknown"
+        if "(L)" in subject:
+            type_str = "Lecture"
+        elif "(T)" in subject:
+            type_str = "Tutorial"
+        elif "(P)" in subject or "Lab" in subject or "Practical" in subject:
+            type_str = "Lab"
+        elif "(L+T)" in subject:
+            type_str = "Lecture + Tutorial"
+            
+        # Parse Alternate from Note
+        alternate = "False"
+        if "Alt. week" in note or "Alternate" in note:
+            alternate = "True"
+
+        entry_str = f"Subject: {subject}\n"
+        entry_str += f"    - time : {time}\n"
+        if instructor:
+            entry_str += f"    - instructor : {instructor}\n"
+        if room:
+            entry_str += f"    - room : {room}\n"
+        entry_str += f"    - type : {type_str}\n"
+        entry_str += f"    - alternate : {alternate}\n"
+        entry_str += "-------------------------------------------------------"
+        
+        return entry_str
+
+    @commands.group(invoke_without_command=True)
+    async def schedule(self, ctx):
+        await ctx.send("Usage: `!schedule add/delete/today/week`")
+
+    @schedule.command()
+    async def today(self, ctx):
+        weekday = datetime.now().strftime("%A")
+        day_l = weekday.lower()
+        
+        db = get_db()
+        try:
+            rows = db.query(ScheduleModel).filter(ScheduleModel.day.ilike(day_l)).all()
+            
+            week_key = get_week_key()
+            merged = apply_temp_changes_to_db_rows(rows, week_key)
+
+            if not merged:
+                await ctx.send(f"No classes scheduled for **{weekday}**.")
+                return
+
+            msg = f"**{weekday}:**\n"
+            msg += "--------------------------------------------------------\n"
+            
+            grouped = {}
+            for e in merged:
+                grp = e.get('group_name', 'General')
+                if grp not in grouped:
+                    grouped[grp] = []
+                grouped[grp].append(e)
+            
+            for grp, entries in grouped.items():
+                msg += f"**{grp}:**\n"
+                msg += "--------------------------------------------------------\n"
+                for e in sorted(entries, key=lambda x: x['time']):
+                    msg += self._format_schedule_entry(e) + "\n"
+
+            await ctx.send(msg)
+        finally:
+            db.close()
+
+    @schedule.command()
+    async def tomorrow(self, ctx):
+        tomorrow_date = datetime.now() + timedelta(days=1)
+        weekday = tomorrow_date.strftime("%A")
+        day_l = weekday.lower()
+        
+        db = get_db()
+        try:
+            rows = db.query(ScheduleModel).filter(ScheduleModel.day.ilike(day_l)).all()
+            
+            week_key = get_week_key()
+            merged = apply_temp_changes_to_db_rows(rows, week_key)
+
+            if not merged:
+                await ctx.send(f"No classes scheduled for **{weekday}**.")
+                return
+
+            msg = f"**{weekday}:**\n"
+            msg += "--------------------------------------------------------\n"
+            
+            grouped = {}
+            for e in merged:
+                grp = e.get('group_name', 'General')
+                if grp not in grouped:
+                    grouped[grp] = []
+                grouped[grp].append(e)
+            
+            for grp, entries in grouped.items():
+                msg += f"**{grp}:**\n"
+                msg += "--------------------------------------------------------\n"
+                for e in sorted(entries, key=lambda x: x['time']):
+                    msg += self._format_schedule_entry(e) + "\n"
+
+            await ctx.send(msg)
+        finally:
+            db.close()
+
+    @schedule.command()
+    async def day(self, ctx, day_name: str):
+        day_name = day_name.lower()
+        valid_days = ['monday', 'tuesday', 'wednesday', 'thursday', 'friday', 'saturday', 'sunday']
+        if day_name not in valid_days:
+            await ctx.send("Please provide a valid day of the week (e.g., monday, tuesday, etc.).")
+            return
+        
+        db = get_db()
+        try:
+            rows = db.query(ScheduleModel).filter(ScheduleModel.day.ilike(day_name)).all()
+            
+            week_key = get_week_key()
+            merged = apply_temp_changes_to_db_rows(rows, week_key)
+
+            if not merged:
+                await ctx.send(f"No classes scheduled for **{day_name.capitalize()}**.")
+                return
+
+            msg = f"**{day_name.capitalize()}:**\n"
+            msg += "--------------------------------------------------------\n"
+            
+            grouped = {}
+            for e in merged:
+                grp = e.get('group_name', 'General')
+                if grp not in grouped:
+                    grouped[grp] = []
+                grouped[grp].append(e)
+            
+            for grp, entries in grouped.items():
+                msg += f"**{grp}:**\n"
+                msg += "--------------------------------------------------------\n"
+                for e in sorted(entries, key=lambda x: x['time']):
+                    msg += self._format_schedule_entry(e) + "\n"
+
+            await ctx.send(msg)
+        finally:
+            db.close()
+
+    @schedule.command()
+    async def week(self, ctx):
+        days = ["sunday", "monday", "tuesday", "wednesday", "thursday", "friday", "saturday"]
+        week_key = get_week_key()
+        
+        db = get_db()
+        try:
+            msg = ""
+            any_entry = False
+            for d in days:
+                rows = db.query(ScheduleModel).filter(ScheduleModel.day.ilike(d)).all()
+                merged = apply_temp_changes_to_db_rows(rows, week_key)
+                if merged:
+                    any_entry = True
+                    day_msg = f"**{d.title()}:**\n"
+                    day_msg += "--------------------------------------------------------\n"
+                    
+                    grouped = {}
+                    for e in merged:
+                        grp = e.get('group_name', 'General')
+                        if grp not in grouped:
+                            grouped[grp] = []
+                        grouped[grp].append(e)
+                    
+                    for grp, entries in grouped.items():
+                        day_msg += f"**{grp}:**\n"
+                        day_msg += "--------------------------------------------------------\n"
+                        for e in sorted(entries, key=lambda x: x['time']):
+                            day_msg += self._format_schedule_entry(e) + "\n"
+                    
+                    if len(msg) + len(day_msg) > 1900:
+                        await ctx.send(msg)
+                        msg = day_msg
+                    else:
+                        msg += day_msg
+            
+            if not any_entry:
+                await ctx.send("No schedule set yet.")
+                return
+            
+            if msg:
+                await ctx.send(msg)
+        finally:
+            db.close()
+
+    @schedule.command()
+    @is_cr()
+    async def delete(self, ctx, day: str, time: str, *, subject: str):
+        db = get_db()
+        try:
+            rows = db.query(ScheduleModel).filter(
+                ScheduleModel.day == day.title(),
+                ScheduleModel.time == time,
+                ScheduleModel.subject == subject.title()
+            ).all()
+            
+            if rows:
+                for row in rows:
+                    db.delete(row)
+                db.commit()
+                await ctx.send(f"Deleted: {subject.title()} on {day.title()} at {time}")
+            else:
+                await ctx.send("No matching class found.")
+        finally:
+            db.close()
+
+    @schedule.command(name='main')
+    @is_cr()
+    async def schedule_main(self, ctx, subcmd: str, *, filename: str):
+        if subcmd.lower() != 'routine':
+            await ctx.send("Usage: `!schedule main routine \"assets/main.json\"`")
+            return
+        filename = filename.strip('"').strip("'")
+        try:
+            schedule_data = load_main_schedule_from_file(filename)
+            
+            db = get_db()
+            try:
+                db.query(ScheduleModel).delete()
+                
+                for group, days in schedule_data.items():
+                    for day, entries in days.items():
+                        for e in entries:
+                            new_entry = ScheduleModel(
+                                day=day.title(),
+                                time=e.get('time'),
+                                subject=e.get('subject'),
+                                group_name=group,
+                                room=e.get('room', ''),
+                                instructor=e.get('instructor', ''),
+                                note=e.get('note', '')
+                            )
+                            db.add(new_entry)
+                db.commit()
+                await ctx.send(f"✅ Main schedule loaded successfully from `{filename}` and written to database.")
+            finally:
+                db.close()
+        except FileNotFoundError:
+            await ctx.send(f"❌ File not found: `{filename}`")
+        except Exception as e:
+            await ctx.send(f"❌ Failed to load schedule: {e}")
+
+    @schedule.command()
+    @is_cr()
+    async def edit(self, ctx, *, args: str = None):
+        """Edit a class time/subject. Usage:
+        !schedule edit GroupA monday 9:00 AM Math 10:00 AM Math permanent|temporary
+        """
+        if not args:
+            await ctx.send("❌ Invalid format. Usage: `!schedule edit GroupA monday 9:00 AM Math 10:00 AM Math permanent` (use 'temporary' or 'permanent')")
+            return
+        parsed = _parse_edit_cancel_args(args)
+        if not parsed or 'new_time' not in parsed:
+            await ctx.send("❌ Invalid format. Usage: `!schedule edit GroupA monday 9:00 AM Math 10:00 AM Math permanent` (use 'temporary' or 'permanent')")
+            return
+
+        group = parsed['group']
+        day = parsed['day']
+        orig_time = parsed['orig_time']
+        orig_subject = parsed['orig_subject']
+        new_time = parsed['new_time']
+        new_subject = parsed['new_subject']
+        permanent = parsed['permanent']
+
+        if not utils.MAIN_SCHEDULE:
+            await ctx.send("❌ No main schedule loaded. Use `!schedule main routine \"main.json\"` first.")
+            return
+
+        if permanent:
+            group_data = utils.MAIN_SCHEDULE.get(group)
+            if not group_data or day not in group_data:
+                await ctx.send("⚠️ Group or day not found in main schedule.")
+                return
+            entries = group_data[day]
+            for e in entries:
+                if _normalize_time(e.get('time')) == _normalize_time(orig_time) and _normalize_subject(e.get('subject')) == _normalize_subject(orig_subject):
+                    e['time'] = new_time
+                    e['subject'] = new_subject
+                    try:
+                        save_main_schedule_to_file()
+                        await ctx.send(f"✅ Schedule for {group} on {day.title()} updated permanently: {orig_time} {orig_subject} -> {new_time} {new_subject}")
+                    except Exception as ex:
+                        await ctx.send(f"❌ Failed to save main schedule: {ex}")
+                    return
+            await ctx.send("⚠️ Matching class not found in main schedule.")
+        else:
+            wk = get_week_key()
+            apply_temp_replacement(wk, group, day, orig_time, orig_subject, {'time': new_time, 'subject': new_subject, 'room': ''})
+            await ctx.send(f"✅ Schedule for {group} on {day.title()} {orig_time} {orig_subject} has been temporarily changed to {new_time} {new_subject} for this week.")
+
+    @schedule.command()
+    @is_cr()
+    async def cancel(self, ctx, *, args: str = None):
+        """Cancel a class. Usage: !schedule cancel GroupA monday 9:00 AM Math permanent|temporary"""
+        if not args:
+            await ctx.send("❌ Invalid format. Usage: `!schedule cancel GroupA monday 9:00 AM Math permanent`")
+            return
+        parsed = _parse_edit_cancel_args(args)
+        if not parsed:
+            await ctx.send("❌ Invalid format. Usage: `!schedule cancel GroupA monday 9:00 AM Math permanent`")
+            return
+
+        group = parsed['group']
+        day = parsed['day']
+        orig_time = parsed['orig_time']
+        orig_subject = parsed['orig_subject']
+        permanent = parsed.get('permanent', False)
+
+        if permanent:
+            if not utils.MAIN_SCHEDULE:
+                await ctx.send("❌ No main schedule loaded.")
+                return
+            group_data = utils.MAIN_SCHEDULE.get(group)
+            if not group_data or day not in group_data:
+                await ctx.send("⚠️ Group or day not found in main schedule.")
+                return
+            entries = group_data[day]
+            for i, e in enumerate(entries):
+                if _normalize_time(e.get('time')) == _normalize_time(orig_time) and _normalize_subject(e.get('subject')) == _normalize_subject(orig_subject):
+                    entries.pop(i)
+                    try:
+                        save_main_schedule_to_file()
+                        await ctx.send(f"✅ {orig_subject} on {day.title()} at {orig_time} permanently cancelled for {group}.")
+                    except Exception as ex:
+                        await ctx.send(f"❌ Failed to save main schedule: {ex}")
+                    return
+            await ctx.send("⚠️ Matching class not found in main schedule.")
+        else:
+            wk = get_week_key()
+            apply_temp_cancellation(wk, group, day, orig_time, orig_subject)
+            await ctx.send(f"✅ {orig_subject} on {day.title()} at {orig_time} temporarily cancelled for {group} this week.")
+
+    @schedule.command()
+    async def view(self, ctx, group: str, day: str):
+        if not utils.MAIN_SCHEDULE:
+            await ctx.send("❌ No main schedule loaded. Use `!schedule main routine \"main.json\"` first.")
+            return
+        day_l = day.lower()
+        week_key = get_week_key()
+        merged = merge_schedule_for_week(group, day_l, week_key)
+        if not merged:
+            await ctx.send(f"No schedule found for **{group}** on **{day.title()}**")
+            return
+        msg = f"**{group} schedule for {day.title()} (week {week_key[1]})**\n"
+        for e in merged:
+            msg += self._format_schedule_entry(e) + "\n"
+        await ctx.send(msg)
+
+async def setup(bot):
+    await bot.add_cog(Schedule(bot))

src/cogs/tasks.py

@@ -0,0 +1,40 @@
+import discord
+from discord.ext import commands
+from datetime import datetime
+from apscheduler.schedulers.asyncio import AsyncIOScheduler
+from database.database import get_db
+from database.models import Assessment
+from configuration.config import CHANNEL_ID
+
+class Tasks(commands.Cog):
+    def __init__(self, bot):
+        self.bot = bot
+        self.scheduler = AsyncIOScheduler()
+        self.scheduler.start()
+        # Add job if not already present (though in a cog, we usually just add it on load)
+        if not self.scheduler.get_job("daily_reminder"):
+            self.scheduler.add_job(self.daily_assessment_reminder, 'cron', hour=18, minute=0, id="daily_reminder")
+
+    async def daily_assessment_reminder(self):
+        today = datetime.now().strftime("%Y-%m-%d")
+        db = get_db()
+        try:
+            assessments = db.query(Assessment).filter(Assessment.date == today).all()
+            
+            if assessments and CHANNEL_ID:
+                channel = self.bot.get_channel(CHANNEL_ID)
+                if channel:
+                    msg = "**🔔 Today's Assessments Reminder**\n\n"
+                    for a in assessments:
+                        time = a.time or "Time not set"
+                        desc = a.description or "No description"
+                        msg += f"• **{a.subject}**: {desc} at {time}\n"
+                    await channel.send("@Class\n" + msg)
+        finally:
+            db.close()
+
+    def cog_unload(self):
+        self.scheduler.shutdown()
+
+async def setup(bot):
+    await bot.add_cog(Tasks(bot))

src/main.py

@@ -0,0 +1,223 @@
+#!/usr/bin/env python3
+"""Bot entrypoint.
+
+Supports optional --override flag to control whether schedule import from main.json
+overwrites the database.
+
+Also configures logging and logs incoming messages ("message to bot") and messages
+sent by the bot ("message by bot").
+"""
+import argparse
+import logging
+import os
+import sys
+import asyncio
+import discord
+from discord.ext import commands
+
+# Ensure project root is on sys.path so packages at repo root (e.g., database, configuration)
+# can be imported when running this file as a script: `python src/main.py`.
+PROJECT_ROOT = os.path.abspath(os.path.join(os.path.dirname(__file__), '..'))
+if PROJECT_ROOT not in sys.path:
+    sys.path.insert(0, PROJECT_ROOT)
+
+from database.database import init_db, get_db
+from database.models import Schedule as ScheduleModel
+from configuration.config import TOKEN
+from utils import load_main_schedule_from_file
+
+
+# ----- Logging setup -----------------------------------------------------
+logger = logging.getLogger('discord_bot')
+logger.setLevel(logging.DEBUG)
+fmt = logging.Formatter('%(asctime)s %(levelname)s %(message)s')
+ch = logging.StreamHandler()
+ch.setLevel(logging.INFO)
+ch.setFormatter(fmt)
+fh = logging.FileHandler('/tmp/bot.log', encoding='utf-8')
+fh.setLevel(logging.DEBUG)
+fh.setFormatter(fmt)
+logger.addHandler(ch)
+logger.addHandler(fh)
+
+
+# ----- Bot setup ---------------------------------------------------------
+intents = discord.Intents.default()
+intents.message_content = True
+bot = commands.Bot(command_prefix="!", intents=intents)
+
+
+# Initialize database
+
+
+
+def auto_import_schedule(override: bool = False):
+    """Import schedule from main.json.
+
+    If override is False, do not import when Schedule table already has rows.
+    If override is True, clear existing schedule entries and import.
+    """
+    try:
+        # Try multiple possible locations for main.json
+        possible_paths = [
+            os.path.join(PROJECT_ROOT, 'main.json'),
+            os.path.join(os.path.dirname(__file__), '..', 'main.json'),
+            '/app/main.json',
+            'main.json',
+        ]
+
+        logger.debug("🔍 Looking for main.json...")
+        logger.debug(f"   PROJECT_ROOT: {PROJECT_ROOT}")
+        logger.debug(f"   Current dir: {os.getcwd()}")
+
+        main_json_path = None
+        for path in possible_paths:
+            abs_path = os.path.abspath(path)
+            logger.debug(f"   Checking: {abs_path}")
+            if os.path.exists(abs_path):
+                main_json_path = abs_path
+                logger.info(f"   ✅ Found at: {abs_path}")
+                break
+
+        if not main_json_path:
+            logger.warning("❌ main.json not found in any of these locations:")
+            for path in possible_paths:
+                logger.warning(f"   - {os.path.abspath(path)}")
+            return
+
+        logger.info(f"📅 Importing schedule from {main_json_path}...")
+        schedule_data = load_main_schedule_from_file(main_json_path)
+
+        db = get_db()
+        try:
+            # If not overriding, and DB already has schedule rows, skip import
+            if not override:
+                existing = db.query(ScheduleModel).count()
+                if existing > 0:
+                    logger.info(f"Found {existing} existing schedule entries in DB; skipping import (use --override to replace).")
+                    return
+
+            # Clear existing schedule data (when override True or DB empty)
+            deleted_count = db.query(ScheduleModel).delete()
+            logger.info(f"🗑️ Cleared {deleted_count} existing schedule entries")
+
+            # Insert new data from main.json
+            entry_count = 0
+            for group, days in schedule_data.items():
+                # skip any top-level keys that are not schedule groups (e.g., metadata)
+                if not isinstance(days, dict):
+                    continue
+                for day, entries in days.items():
+                    # entries should be a list of dicts; skip otherwise
+                    if not isinstance(entries, list):
+                        continue
+                    for e in entries:
+                        if not isinstance(e, dict):
+                            continue
+                        new_entry = ScheduleModel(
+                            day=day.title(),
+                            time=e.get('time'),
+                            subject=e.get('subject'),
+                            group_name=group,
+                            room=e.get('room', ''),
+                            instructor=e.get('instructor', ''),
+                            note=e.get('note', ''),
+                        )
+                        db.add(new_entry)
+                        entry_count += 1
+            db.commit()
+            logger.info(f"✅ Schedule imported successfully! ({entry_count} entries)")
+        finally:
+            db.close()
+    except Exception as e:
+        logger.exception(f"❌ Error auto-importing schedule: {e}")
+
+
+@bot.event
+async def on_ready():
+    logger.info(f"{bot.user} is online!")
+
+
+@bot.event
+async def on_command_error(ctx, error):
+    # Global handler for command errors to ensure they are logged and user is notified
+    try:
+        # Handle missing required argument gracefully
+        if isinstance(error, commands.MissingRequiredArgument):
+            param = error.param.name if hasattr(error, 'param') else 'argument'
+            usage = ''
+            if ctx.command:
+                usage = f" Usage: `!{ctx.command.qualified_name} {ctx.command.signature}`"
+            await ctx.send(f"❌ Missing required argument: `{param}`.{usage}")
+            logger.warning(f"Missing argument in command {ctx.command}: {param}")
+            return
+
+        logger.exception(f"Error in command '{getattr(ctx, 'command', None)}': {error}")
+        # Friendly message to channel
+        await ctx.send("❌ An error occurred while processing your command. The error has been logged.")
+    except Exception:
+        logger.exception("Failed in on_command_error handler")
+
+
+@bot.event
+async def on_message(message: discord.Message):
+    try:
+        # Ignore webhooks
+        if getattr(message, 'webhook_id', None) is not None:
+            return
+
+        if message.author == bot.user:
+            # message by bot
+            logger.info(f"message by bot: channel={getattr(message.channel, 'name', message.channel.id)} content={message.content}")
+        else:
+            # message to bot
+            logger.info(f"message to bot: author={message.author} channel={getattr(message.channel, 'name', message.channel.id)} content={message.content}")
+
+        # ensure commands still processed
+        await bot.process_commands(message)
+    except Exception:
+        logger.exception("Error in on_message handler")
+
+
+async def load_extensions():
+    # Load all cogs from the cogs directory
+    cogs_dir = os.path.join(os.path.dirname(__file__), 'cogs')
+    for filename in os.listdir(cogs_dir):
+        if filename.endswith('.py') and filename != '__init__.py':
+            await bot.load_extension(f'cogs.{filename[:-3]}')
+
+
+async def main(argv=None):
+    parser = argparse.ArgumentParser(description='Start the Discord bot')
+    parser.add_argument('--override', action='store_true', help='Override existing schedule data in DB with main.json')
+    args = parser.parse_args(argv)
+
+    # Initialize database
+    try:
+        init_db()
+    except Exception as e:
+        logger.error(f"❌ Database initialization failed: {e}")
+        logger.error("   Check your DATABASE_URL in .env or Supabase credentials.")
+        sys.exit(1)
+
+    # Import schedule according to flag
+    try:
+        auto_import_schedule(override=args.override)
+    except Exception:
+        logger.exception('Auto-import schedule failed')
+
+    # Start bot
+    async with bot:
+        await load_extensions()
+        await bot.start(TOKEN)
+
+
+if __name__ == '__main__':
+    try:
+        asyncio.run(main())
+    except KeyboardInterrupt:
+        # Handle Ctrl+C gracefully
+        logger.info('Shutting down (KeyboardInterrupt)')
+    except Exception:
+        logger.exception('Fatal error in main')
+    

src/mistral_client.py

@@ -0,0 +1,35 @@
+# mistral_client.py
+import aiohttp
+import json
+import os
+
+async def ask_mistral(question, context=""):
+    api_key = os.getenv("MISTRAL_API_KEY")
+    if not api_key:
+        return None
+
+    url = "https://api.mistral.ai/v1/chat/completions"
+    headers = {
+        "Authorization": f"Bearer {api_key}",
+        "Content-Type": "application/json"
+    }
+    payload = {
+        "model": "mistral-small-latest",
+        "messages": [
+            {"role": "system", "content": f"You are a helpful class assistant. Use this context if relevant: {context}"},
+            {"role": "user", "content": question}
+        ],
+        "temperature": 0.5,
+        "max_tokens": 300
+    }
+
+    try:
+        async with aiohttp.ClientSession() as session:
+            async with session.post(url, headers=headers, json=payload, timeout=10) as response:
+                if response.status == 200:
+                    data = await response.json()
+                    return data["choices"][0]["message"]["content"]
+    except Exception as e:
+        print(f"Mistral API Error: {e}")
+        pass
+    return None

src/utils.py

@@ -0,0 +1,307 @@
+import os
+import json
+import re
+from datetime import datetime
+from discord.ext import commands
+from configuration.config import CR_USER_ID, CR_ROLE_NAME
+
+# Global State
+MAIN_SCHEDULE = {}
+MAIN_SCHEDULE_FILE = None
+TEMP_CHANGES = {}
+
+# Ensure project root is on sys.path so packages at repo root (e.g., database, configuration)
+# can be imported when running this file as a script: `python src/main.py`.
+PROJECT_ROOT = os.path.abspath(os.path.join(os.path.dirname(__file__), '..'))
+
+def is_cr():
+    async def predicate(ctx):
+        if CR_USER_ID and ctx.author.id == CR_USER_ID:
+            return True
+        if any(role.name == CR_ROLE_NAME for role in ctx.author.roles):
+            return True
+        await ctx.send("❌ You don't have permission to use this command.")
+        return False
+    return commands.check(predicate)
+
+def get_week_key(dt=None):
+    d = dt or datetime.now()
+    iso = d.isocalendar()
+    return (iso.year, iso.week)
+
+def load_main_schedule_from_file(path):
+    global MAIN_SCHEDULE, MAIN_SCHEDULE_FILE
+    # Resolve path: allow passing a filename relative to project root (where main.json usually lives)
+    candidate_paths = []
+    # expand user + absolute
+    p = os.path.expanduser(path)
+    if not os.path.isabs(p):
+        p = os.path.abspath(p)
+    candidate_paths.append(p)
+    # also try relative to project root (one level up from src)
+    try:
+        pr = PROJECT_ROOT
+    except NameError:
+        pr = os.path.abspath(os.path.join(os.path.dirname(__file__), '..'))
+    candidate_paths.append(os.path.join(pr, path))
+    candidate_paths.append(os.path.join(pr, 'assets', path))
+    candidate_paths.append(os.path.join(pr, 'assets', os.path.basename(path)))
+    candidate_paths.append(os.path.abspath(os.path.join(os.path.dirname(__file__), path)))
+
+    found = None
+    for cp in candidate_paths:
+        if os.path.isfile(cp):
+            found = cp
+            break
+    if not found:
+        raise FileNotFoundError(f"Schedule file not found: {path}. Tried: {', '.join(candidate_paths)}")
+    with open(found, 'r', encoding='utf-8') as f:
+        data = json.load(f)
+    # Normalize day keys to lowercase
+    normalized = {}
+    for group, days in data.items():
+        normalized[group] = {}
+        for day, entries in days.items():
+            normalized[group][day.lower()] = entries
+    MAIN_SCHEDULE = normalized
+    MAIN_SCHEDULE_FILE = found
+    return MAIN_SCHEDULE
+
+def save_main_schedule_to_file(path=None):
+    global MAIN_SCHEDULE, MAIN_SCHEDULE_FILE
+    if path is None:
+        path = MAIN_SCHEDULE_FILE
+    if not path:
+        raise ValueError("No main schedule file set")
+    # We will write days as they are in MAIN_SCHEDULE (lowercase days)
+    with open(path, 'w', encoding='utf-8') as f:
+        json.dump(MAIN_SCHEDULE, f, indent=2, ensure_ascii=False)
+
+def _normalize_time(t):
+    if not t:
+        return ''
+    s = str(t).strip()
+    # Ensure there's a space before AM/PM if present (e.g., '9:00AM' -> '9:00 AM')
+    s = re.sub(r'\s*([AaPp][Mm])$', r' \1', s)
+    # Normalize spacing and AM/PM case
+    s = re.sub(r'\s+', ' ', s).strip()
+    s = re.sub(r'([AaPp][Mm])', lambda m: m.group(1).upper(), s)
+    return s
+
+def _normalize_subject(sub):
+    if not sub:
+        return ''
+    return str(sub).strip().lower()
+
+def apply_temp_replacement(week_key, group, day, orig_time, orig_subject, new_entry):
+    # store normalized keys for robust matching
+    ot = _normalize_time(orig_time)
+    osub = _normalize_subject(orig_subject)
+    # normalize new_entry time/subject for consistency
+    new_e = dict(new_entry)
+    if 'time' in new_e:
+        new_e['time'] = _normalize_time(new_e['time'])
+    if 'subject' in new_e:
+        new_e['subject'] = new_e['subject'].strip()
+    TEMP_CHANGES.setdefault(week_key, {}).setdefault(group, {}).setdefault(day, {}).setdefault('replacements', []).append(((ot, osub), new_e))
+
+def apply_temp_cancellation(week_key, group, day, orig_time, orig_subject):
+    ot = _normalize_time(orig_time)
+    osub = _normalize_subject(orig_subject)
+    TEMP_CHANGES.setdefault(week_key, {}).setdefault(group, {}).setdefault(day, {}).setdefault('cancellations', []).append((ot, osub))
+
+def merge_schedule_for_week(group, day, week_key=None):
+    """Return a list of schedule entries for the given group and day, applying temporary changes for the week_key if present."""
+    week_key = week_key or get_week_key()
+    base = []
+    if group in MAIN_SCHEDULE and day in MAIN_SCHEDULE[group]:
+        # clone base entries
+        base = [dict(e) for e in MAIN_SCHEDULE[group][day]]
+    # Apply temporary changes if any
+    wk = TEMP_CHANGES.get(week_key, {})
+    grp = wk.get(group, {})
+    day_changes = grp.get(day, {})
+    cancels = set(day_changes.get('cancellations', []))
+    replacements = {k: v for (k, v) in day_changes.get('replacements', [])}
+
+    merged = []
+    handled_orig_keys = set()
+
+    for e in base:
+        key = (_normalize_time(e.get('time')), _normalize_subject(e.get('subject')))
+        # If original time+subject canceled directly, skip
+        if key in cancels:
+            handled_orig_keys.add(key)
+            continue
+
+        # If there is a replacement mapping for this original, check if the replacement itself is canceled
+        if key in replacements:
+            new_e = replacements[key]
+            new_key = (_normalize_time(new_e.get('time')), _normalize_subject(new_e.get('subject')))
+            # If replacement is canceled explicitly, skip (neither original nor replacement)
+            if new_key in cancels:
+                handled_orig_keys.add(key)
+                continue
+            merged.append({
+                'time': new_e.get('time'),
+                'subject': new_e.get('subject'),
+                'room': new_e.get('room', ''),
+                'instructor': new_e.get('instructor', ''),
+                'note': new_e.get('note', '')
+            })
+            handled_orig_keys.add(key)
+        else:
+            # keep original (normalize time for consistent display)
+            merged.append({
+                'time': _normalize_time(e.get('time')),
+                'subject': e.get('subject'),
+                'room': e.get('room', ''),
+                'instructor': e.get('instructor', ''),
+                'note': e.get('note', '')
+            })
+
+    # Add any replacement entries that did not map to an existing original (standalone adds)
+    for (orig_k, new_e) in day_changes.get('replacements', []):
+        if orig_k not in handled_orig_keys:
+            new_key = (_normalize_time(new_e.get('time')), _normalize_subject(new_e.get('subject')))
+            if new_key in cancels:
+                # this standalone replacement was later canceled
+                continue
+            merged.append({
+                'time': new_e.get('time'),
+                'subject': new_e.get('subject'),
+                'room': new_e.get('room', ''),
+                'instructor': new_e.get('instructor', ''),
+                'note': new_e.get('note', '')
+            })
+
+    return merged
+
+def apply_temp_changes_to_db_rows(rows, week_key):
+    """Given a list of sqlite Row-like dicts with keys day,time,subject,group_name,room,
+    apply temporary changes from TEMP_CHANGES for week_key and return merged list.
+    """
+    # build mapping of replacements and cancellations for groups/days
+    result = []
+    if not rows:
+        return []
+
+    def _rget(r, key, default=None):
+        try:
+            # SQLAlchemy object access
+            if hasattr(r, key):
+                return getattr(r, key)
+            # Dictionary access
+            elif hasattr(r, 'get'):
+                return r.get(key, default)
+            else:
+                return r[key]
+        except Exception:
+            return default
+
+    # Group rows by (group, day) so we can apply replacements/cancellations per group/day
+    grouped = {}
+    for r in rows:
+        group = _rget(r, 'group_name') or _rget(r, 'group') or ''
+        day = (_rget(r, 'day') or '').lower()
+        grouped.setdefault((group, day), []).append(r)
+
+    wk = TEMP_CHANGES.get(week_key, {})
+
+    # Process each group/day present in DB rows
+    for (group, day), rlist in grouped.items():
+        # get changes for this group/day
+        grp = wk.get(group, {})
+        day_changes = grp.get(day, {})
+        cancels = set(day_changes.get('cancellations', []))
+        replacements = {k: v for (k, v) in day_changes.get('replacements', [])}
+
+        handled_orig_keys = set()
+
+        for r in rlist:
+            time = _rget(r, 'time')
+            subject = _rget(r, 'subject')
+            key = (_normalize_time(time), _normalize_subject(subject))
+
+            if key in cancels:
+                # skip cancelled original
+                handled_orig_keys.add(key)
+                continue
+
+            if key in replacements:
+                new_e = replacements[key]
+                handled_orig_keys.add(key)
+                merged_entry = {
+                    'time': new_e.get('time'),
+                    'subject': new_e.get('subject'),
+                    'room': new_e.get('room', _rget(r, 'room', '')),
+                    'group_name': group
+                }
+                result.append(merged_entry)
+            else:
+                # keep original (normalize time for consistent display)
+                result.append({'time': _normalize_time(time), 'subject': subject, 'room': _rget(r, 'room', ''), 'group_name': group})
+
+        # Add any replacement entries that did not map to an existing original (standalone adds)
+        for (orig_k, new_e) in day_changes.get('replacements', []):
+            if orig_k not in handled_orig_keys:
+                # This replacement did not correspond to any existing row - append as new
+                result.append({'time': new_e.get('time'), 'subject': new_e.get('subject'), 'room': new_e.get('room', ''), 'group_name': group})
+
+    # Also process any TEMP_CHANGES for groups/days not present in DB rows (pure adds)
+    for grp_name, groups in wk.items():
+        for dname, dchanges in groups.items():
+            if (grp_name, dname) in grouped:
+                continue
+            # no DB rows for this group/day; add all replacements that are not cancellations
+            for (orig_k, new_e) in dchanges.get('replacements', []):
+                result.append({'time': new_e.get('time'), 'subject': new_e.get('subject'), 'room': new_e.get('room',''), 'group_name': grp_name})
+
+    return result
+
+def _find_time_tokens(tokens, start=0):
+    """Find a time token starting at or after start. Returns (time_string, start_index, end_index).
+    Supports formats like '9:00', '9:00 AM', '09:00', '9:00PM' etc.
+    """
+    ampm = set(['AM', 'PM', 'am', 'pm'])
+    time_re = re.compile(r'^\d{1,2}:\d{2}([AaPp][Mm])?$')
+    for i in range(start, len(tokens)):
+        t = tokens[i]
+        # token like 9:00 or 9:00AM
+        if time_re.match(t):
+            return (t, i, i)
+        # token like 9:00 and next token AM/PM
+        if i + 1 < len(tokens) and re.match(r'^\d{1,2}:\d{2}$', t) and tokens[i+1] in ampm:
+            return (f"{t} {tokens[i+1]}", i, i+1)
+    return (None, -1, -1)
+
+def _parse_edit_cancel_args(args):
+    tokens = args.split()
+    if len(tokens) < 4:
+        return None
+    group = tokens[0]
+    day = tokens[1].lower()
+    # find first time token
+    t1, t1s, t1e = _find_time_tokens(tokens, 2)
+    if not t1:
+        return None
+    # find second time token after t1e+1 (for edit). For cancel, second time may not exist.
+    t2, t2s, t2e = _find_time_tokens(tokens, t1e+1)
+    # mode is last token if it's 'permanent' or 'temporary'
+    mode = tokens[-1].lower() if tokens[-1].lower() in ('permanent', 'temporary') else 'temporary'
+
+    if t2:
+        # edit: subject is between t1e+1 and t2s-1; new_subject is between t2e+1 and -1 (mode)
+        orig_subject = ' '.join(tokens[t1e+1:t2s]).strip()
+        new_time = t2
+        new_subject = ' '.join(tokens[t2e+1:-1]).strip()
+        return {
+            'group': group, 'day': day, 'orig_time': t1, 'orig_subject': orig_subject,
+            'new_time': new_time, 'new_subject': new_subject, 'permanent': (mode == 'permanent')
+        }
+    else:
+        # cancel: subject is remaining tokens after t1e
+        orig_subject = ' '.join(tokens[t1e+1: -1]).strip() if mode in ('permanent', 'temporary') else ' '.join(tokens[t1e+1:]).strip()
+        return {
+            'group': group, 'day': day, 'orig_time': t1, 'orig_subject': orig_subject, 'permanent': (mode == 'permanent')
+        }