https://github.com/snipeart007/student-buddy
A privacy-focused, local AI assistant that helps students balance their academic workloads with mental health. Implements a multi-agent orchestration workflow running Gemma 2B locally using llama.cpp, encrypted local state management, and an onboarding questionnaire.
https://github.com/snipeart007/student-buddy
fastapi gemma gemma-4 llama-cpp local-llm material-ui mental-health multi-agent nextjs student-buddy
Last synced: 7 days ago
JSON representation
A privacy-focused, local AI assistant that helps students balance their academic workloads with mental health. Implements a multi-agent orchestration workflow running Gemma 2B locally using llama.cpp, encrypted local state management, and an onboarding questionnaire.
- Host: GitHub
- URL: https://github.com/snipeart007/student-buddy
- Owner: snipeart007
- Created: 2026-05-15T05:14:45.000Z (about 2 months ago)
- Default Branch: master
- Last Pushed: 2026-06-02T04:52:15.000Z (27 days ago)
- Last Synced: 2026-06-02T06:23:57.918Z (27 days ago)
- Topics: fastapi, gemma, gemma-4, llama-cpp, local-llm, material-ui, mental-health, multi-agent, nextjs, student-buddy
- Language: Python
- Homepage:
- Size: 688 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Student Buddy: AI-Powered Academic & Well-being Advisor
Student Buddy is a local, privacy-first desktop assistant designed to help students balance academic workloads with mental health. By utilizing a local Large Language Model via `llama.cpp` and secure local state management, the application guarantees user privacy while offering tailored educational and well-being advice.
---
## 🏗️ System Architecture
```
+--------------------------------------+
| Next.js + MUI Frontend |
+--------------------------------------+
^
| (HTTP / API Requests)
v
+------------------+ +--------------------------------------+
| Encrypted JSON | | FastAPI Backend |
| Student State | <---> (Includes mounted Gradio chat_api) |
+------------------+ +--------------------------------------+
^
| (Load / Query)
v
================= Multi-Agent Orchestrator =================
| |
| +---------------+ |
| | Policy Agent | |
| +---------------+ |
| | |
| v |
| [ Risk Level Check ] |
| / \ |
| (Low/Medium Risk) (High/Critical Risk) |
| / \ |
| v v |
| +------------------+ +-------------------+ |
| | Fusion Agent | | Academic Advisor | |
| | (Base Model) | | Agent | |
| +------------------+ +---------+---------+ |
| | | |
| | v |
| | +-------------------+ |
| | | Mental Health | |
| | | Advisor Agent | |
| | +---------+---------+ |
| | | |
| | v |
| | +-------------------+ |
| | | Fusion Agent | |
| | | (Institution API) | |
| | +---------+---------+ |
| | | |
| v v |
| +----------------------------------------------+ |
| | Stream Response to Frontend | |
| +----------------------------------------------+ |
| |
============================================================
```
### 1. Multi-Agent Routing & Orchestration
When a message is received from the frontend:
1. **Policy Agent**: Analyzes the query and current `StudentState`. It assigns weights to mental and academic components (`mental_weight` and `academic_weight`), sets a mode (e.g., `emotional_recovery`), and evaluates the `risk_level`.
2. **Routing Decision**:
- **Low/Medium Risk**: The query and state are sent directly to the local model using the **Fusion** adapter to stream a unified response.
- **High/Critical Risk**: The query is routed to two separate agents: **Academic Advisor Agent** and **Mental Health Advisor Agent** (represented by specialized adapters/prompts). Their responses are combined via the **Fusion Agent** to generate the final output.
3. **Background State Update**: After sending the response, a background task analyzes the interaction and updates the persisted `StudentState`.
### 2. Security & Local Persistence
- All student data is stored locally on the user's computer inside the `data/` directory.
- The state is serialized to JSON and encrypted using AES-128 in CBC mode with HMAC-SHA256 (via the Python `cryptography` Fernet library) to maintain data privacy.
---
## ⚠️ Known Implementation Limitations
> [!WARNING]
> ### 1. Incomplete Frontend Chat Interface
> The current chat UI inside the frontend ([Chat.tsx](file:///home/snipeart007/repos/student-buddy/frontend/src/components/Chat.tsx)) is incomplete. Instead of rendering messages natively via Material UI (MUI) components using the `@gradio/client` API client, the frontend currently displays the raw Gradio interface using an `` targeting `/advisor_chat`.
>
> *Planned fix*: Re-implement the Chat component using native React components, querying a headless Gradio API via the `@gradio/client` package, displaying distinct streaming blocks for both "Thinking Process/Routing" and "Final Response".
> [!WARNING]
> ### 2. Runtime LoRA Hot-Reloading Limitations
> The underlying engine `llama.cpp` (and the `llama-cpp-python` bindings) does not support dynamic runtime hot-reloading or applying multiple LoRA adapters on-the-fly to a single loaded base model instance.
>
> As a workaround, the backend ([llm_handler.py](file:///home/snipeart007/repos/student-buddy/backend/llm_handler.py)) instantiates separate, independent `Llama` instances for each role (`policy`, `academic`, `mental`, `fusion`). This duplicates the base model weights in memory for each adapter, which is highly inefficient and can lead to Out-Of-Memory (OOM) errors on systems with limited memory/VRAM.
---
## 📁 Repository Directory Structure
- [run.py](file:///home/snipeart007/repos/student-buddy/run.py) - Main entrypoint to launch both the backend server and frontend client.
- [backend/](file:///home/snipeart007/repos/student-buddy/backend) - FastAPI + Gradio server handling state encryption, local inference, and orchestrating agents.
- [frontend/](file:///home/snipeart007/repos/student-buddy/frontend) - Next.js + Material UI application providing the onboarding questionnaire and chat interfaces.
- [initial_prompt.md](file:///home/snipeart007/repos/student-buddy/initial_prompt.md) & [main_prompt.md](file:///home/snipeart007/repos/student-buddy/main_prompt.md) - Original project specifications and system requirements.
---
## 🚀 Getting Started
### Prerequisites
- Python 3.10+
- Node.js 18+
- [uv](https://github.com/astral-sh/uv) (recommended for Python package management)
### Running the Project
The project comes with a helper startup script [run.py](file:///home/snipeart007/repos/student-buddy/run.py) at the root level. To start:
1. Install dependencies for the backend and frontend.
2. Build/Export the frontend assets:
```bash
cd frontend
npm install
npm run build
```
3. Run the main runner script from the root workspace directory:
```bash
python run.py
```
This command starts the Uvicorn-served backend and automatically opens `http://127.0.0.1:8000` in your default web browser.