AcadBot — AI-Powered Student Academic Advisory Chatbot

A token-aware, RAG-based AI chatbot for institutional academic advisory. Built with FastAPI, MongoDB, ChromaDB, and Groq (Llama 3.1). Features JWT authentication, rolling summarization, and a futuristic dark UI.

---

Tech Stack

Layer	Technology
Backend API	FastAPI (async)
AI Model	Groq API — Llama 3.1 8b Instant
Database	MongoDB via Motor (async driver)
Vector DB	ChromaDB (RAG for college documents)
Authentication	JWT — python-jose + bcrypt
Frontend	HTML / CSS / Vanilla JS

To switch from Groq to OpenAI, see the Switching to OpenAI section.

---

Project Structure

acadbot/
├── main.py                      # FastAPI app — registers routes, serves frontend
├── config.py                    # Reads settings from .env
├── database.py                  # MongoDB Motor client
├── auth.py                      # JWT creation/verification, password hashing
├── agent.py                     # Groq AI calls + rolling summarization
├── rag.py                       # ChromaDB document indexing and retrieval
│
├── app/
│   └── routes/
│       ├── auth_routes.py       # POST /auth/login
│       ├── chat_routes.py       # POST /chat  |  GET /chat/history  |  DELETE /chat/history
│       └── student_routes.py    # GET /students/me
│
├── data/
│   ├── college_data.json        # ← All institution data lives here (see Data Guide below)
│   └── seed.py                  # One-time script: loads data into MongoDB + ChromaDB
│
├── frontend/
│   ├── index.html               # Chat UI
│   ├── style.css                # Futuristic dark theme
│   └── app.js                   # API calls, canvas animation, chat logic
│
├── .env.example                 # Environment variable template (safe to commit)
├── .env                         # Your actual keys — NEVER commit this
├── .gitignore
├── requirements.txt
└── README.md

---

What Gets Committed to GitHub

✅ Committed                      ❌ Not committed
──────────────────────────────    ──────────────────────────────
All .py files                     .env  (contains real API keys)
frontend/                         chroma_db/  (auto-generated)
data/college_data.json            __pycache__/
data/seed.py                      venv/
requirements.txt
.env.example
.gitignore
README.md

college_data.json is committed intentionally — it acts as a data template so any institution can see the exact format needed and replace it with their real data.

---

Setup

1. Clone the repo

git clone https://github.com/your-username/acadbot.git
cd acadbot

2. Install dependencies

pip install -r requirements.txt

3. Create your .env file

cp .env.example .env

Open .env and fill in your values:

GROQ_API_KEY=your_groq_api_key_here
MONGODB_URL=mongodb://localhost:27017
DB_NAME=acadbot
JWT_SECRET=any_long_random_string
JWT_EXPIRE_MINUTES=480

4. Start MongoDB

• Local: Install MongoDB Community from mongodb.com and start the service
• Cloud: Use MongoDB Atlas free tier — paste the connection string as MONGODB_URL

5. Seed the database

python data/seed.py

This reads college_data.json and:

• Loads all students into MongoDB (passwords are hashed with bcrypt)
• Indexes college policies and course info into ChromaDB for RAG

6. Run the server

uvicorn main:app --reload

Open http://localhost:8000 in your browser.

---

Data Guide — How to Feed and Modify Data

All institution data lives in one file: data/college_data.json

After any change to this file, re-run:

python data/seed.py

---

College Info

Edit the college block to match your institution:

"college": {
  "name": "Your Institution Name",
  "location": "City, State",
  "affiliated_to": "Your University",
  "working_hours": "9:00 AM to 5:00 PM, Monday to Saturday",
  "exam_policy": "Describe attendance rules here.",
  "grading_policy": "Describe your grading scale here.",
  "backlog_policy": "Describe backlog rules here.",
  "internship_policy": "Describe internship eligibility here.",
  "library_timings": "8:30 AM to 6:00 PM on weekdays",
  "fee_payment_deadline": "Describe fee deadlines here.",
  "contact_email": "info@yourinstitution.edu",
  "contact_phone": "+91-XXXXXXXXXX"
}

All these fields are automatically indexed into ChromaDB — the AI will answer policy questions using this text directly.

---

Adding or Updating Courses

Add a new entry to the courses.CS array:

{
  "code": "CS604",
  "name": "Natural Language Processing",
  "credits": 4,
  "semester": 6,
  "incharge": "Dr. Your Faculty Name"
}

To add courses for other departments, add a new key alongside CS:

"courses": {
  "CS": [ ... ],
  "EC": [ ... ],
  "ME": [ ... ]
}

---

Adding Students

Add a new object to the students array:

{
  "name": "Student Full Name",
  "usn": "1KS24CS001",
  "password": "initialpassword",
  "department": "Computer Science",
  "current_semester": 2,
  "gpa": 8.0,
  "attendance": 88,
  "completed_courses": [],
  "current_courses": ["CS101", "CS102"],
  "backlogs": [],
  "internship_status": "Not eligible yet",
  "fee_status": "Paid"
}

Passwords in college_data.json are plain text. seed.py automatically hashes them with bcrypt before storing in MongoDB. Never store real production passwords in this file — use a proper admin interface for real deployments.

---

Updating an Existing Student

Option A — Edit and re-seed (for bulk updates):

1. Edit college_data.json
2. Run python data/seed.py — seed uses upsert so existing records are updated

Option B — Directly in MongoDB (for single student changes):

mongosh
use acadbot
db.students.updateOne(
  { usn: "1KS22CS090" },
  { $set: { gpa: 8.7, attendance: 85 } }
)

---

Updating College Policies

1. Edit the relevant field in college_data.json
2. Re-run seed:

python data/seed.py

The seed script uses get_or_create_collection — existing ChromaDB entries with the same ID are automatically updated.

---

API Endpoints

Method	Endpoint	Auth Required	Description
POST	/auth/login	No	Login with USN + password, returns JWT token
POST	/chat	Yes	Send a message, get AI reply
GET	/chat/history	Yes	Retrieve full chat history
DELETE	/chat/history	Yes	Clear chat history
GET	/students/me	Yes	Get your own student profile
GET	/health	No	Server health check

Auth header format:

Authorization: Bearer <your_jwt_token>

---

Default Login Credentials (Sample Data)

Name	USN	Password
Naresh Kumar N	1KS22CS090	naresh123
Riya Sharma	1KS22CS045	riya123
Aditya Rao	1KS22CS012	aditya123
Sneha Patil	1KS21CS078	sneha123
Mohammed Faisal	1KS22CS033	faisal123

---

Switching to OpenAI

In agent.py, replace the client setup:

# Remove this:
from groq import Groq
client = Groq(api_key=settings.GROQ_API_KEY)
MODEL = "llama-3.1-8b-instant"

# Add this:
from openai import OpenAI
client = OpenAI(api_key=settings.OPENAI_API_KEY)
MODEL = "gpt-4o-mini"

In config.py, add:

OPENAI_API_KEY: str

In .env, replace GROQ_API_KEY with:

OPENAI_API_KEY=your_openai_api_key

No other changes needed — the rest of the codebase is model-agnostic.

---

How It Works (Brief)

1. Login — USN + password verified against MongoDB. JWT token returned.
2. Chat — Each message triggers:
   • Student profile loaded from MongoDB
   • ChromaDB finds top 3 relevant policy/course chunks (RAG)
   • Groq builds a prompt: system instructions + profile + RAG chunks + chat history
   • Rolling summarization kicks in if history exceeds 10 turns
   • Reply saved to MongoDB, returned to browser
3. RAG — College policies and courses are stored as vectors in ChromaDB. Only relevant chunks are injected per query, keeping token usage low.

---

Contributing

1. Fork the repo
2. Create a feature branch: git checkout -b feature/your-feature
3. Commit your changes: git commit -m "add your feature"
4. Push and open a pull request

---

License

MIT