# College AI Assistant

An MCP-powered AI assistant for students, built with **FastMCP** (tool server),
**CrewAI** + **Gemini** (agent/LLM), **FastAPI** (backend API), **SQLAlchemy**
(SQLite DB), and a vanilla **HTML/CSS/JS** chat UI.

Students can ask about: subjects, marks, average marks, performance reports
(strong/weak subjects + improvement suggestions), timetable, exam schedules,
previous papers (exam prep), fee dues, college events, upcoming holidays, and
assignments.

## Architecture

```
Browser (frontend/) --> FastAPI backend (/api/chat) --> CrewAI Agent (Gemini LLM)
                                                              |
                                                     MCP tools over HTTP
                                                              v
                                              FastMCP server (mcp_server/server.py)
                                                              |
                                                              v
                                                  SQLAlchemy models <-> SQLite DB
```

- `app/models.py` — SQLAlchemy tables (students, subjects, marks, timetable,
  exam schedule, previous papers, fees, events, holidays, assignments, chat
  history).
- `app/seed_data.py` — populates the DB with mock students/subjects/etc.
- `app/mcp_server/server.py` — FastMCP server exposing tools that query the DB.
- `app/agent/crew.py` — CrewAI agent that connects to the MCP server and uses
  Gemini as the LLM to answer each chat turn, capturing tool-call details.
- `app/backend/main.py` — FastAPI app: `/api/students`, `/api/chat`,
  `/api/chat/history/{id}`, and serves the frontend.
- `app/frontend/` — chat UI with a "Details" toggle under each AI response
  showing which tools were called, their arguments, and results.

## Setup

```bash
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
```

Copy `.env.example` to `.env` and fill in your own `GEMINI_API_KEY` (never
commit real keys).

> **Security note:** the API key that was included in the original prompt is
> considered exposed. Rotate it in Google AI Studio and put the new key only
> in your local `.env` (already gitignored).

> **Model name note:** `gemini/gemma-4-31b-it` (as given) does not match a
> published Gemini/Gemma model. If chat calls fail with a "model not found"
> error, change `GEMINI_MODEL` in `.env` to a real model such as
> `gemini/gemma-3-27b-it` or `gemini/gemini-2.0-flash`.

## Running

Seed the database (safe to re-run, it skips if already seeded):

```bash
python -m app.seed_data
```

Start the MCP tool server (terminal 1):

```bash
python -m app.mcp_server.server
```

Start the backend + frontend (terminal 2):

```bash
uvicorn app.backend.main:app --reload --port 8000
```

Open http://127.0.0.1:8000 and pick a student from the dropdown to start
chatting.

## Seeded test students

`CS21001` Aarav Sharma, `CS21002` Diya Patel, `CS21003` Rohan Mehta,
`CS21004` Isha Verma — all in Computer Science, semester 4, with mock marks,
timetable, exams, fees, assignments, events and holidays.