{"id":51052354,"url":"https://github.com/snipeart007/student-buddy","last_synced_at":"2026-06-22T18:02:37.796Z","repository":{"id":361990281,"uuid":"1239443102","full_name":"snipeart007/student-buddy","owner":"snipeart007","description":"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.","archived":false,"fork":false,"pushed_at":"2026-06-02T04:52:15.000Z","size":704,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-06-02T06:23:57.918Z","etag":null,"topics":["fastapi","gemma","gemma-4","llama-cpp","local-llm","material-ui","mental-health","multi-agent","nextjs","student-buddy"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/snipeart007.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-15T05:14:45.000Z","updated_at":"2026-06-02T04:55:13.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/snipeart007/student-buddy","commit_stats":null,"previous_names":["snipeart007/student-buddy"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/snipeart007/student-buddy","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/snipeart007%2Fstudent-buddy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/snipeart007%2Fstudent-buddy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/snipeart007%2Fstudent-buddy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/snipeart007%2Fstudent-buddy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/snipeart007","download_url":"https://codeload.github.com/snipeart007/student-buddy/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/snipeart007%2Fstudent-buddy/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34659897,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-22T02:00:06.391Z","response_time":106,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["fastapi","gemma","gemma-4","llama-cpp","local-llm","material-ui","mental-health","multi-agent","nextjs","student-buddy"],"created_at":"2026-06-22T18:02:37.070Z","updated_at":"2026-06-22T18:02:37.784Z","avatar_url":"https://github.com/snipeart007.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Student Buddy: AI-Powered Academic \u0026 Well-being Advisor\n\nStudent 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.\n\n---\n\n## 🏗️ System Architecture\n\n```\n               +--------------------------------------+\n               |        Next.js + MUI Frontend        |\n               +--------------------------------------+\n                                  ^\n                                  | (HTTP / API Requests)\n                                  v\n+------------------+   +--------------------------------------+\n|  Encrypted JSON  |   |           FastAPI Backend            |\n|  Student State   | \u003c---\u003e (Includes mounted Gradio chat_api) |\n+------------------+   +--------------------------------------+\n                                  ^\n                                  | (Load / Query)\n                                  v\n         ================= Multi-Agent Orchestrator =================\n         |                                                          |\n         |                    +---------------+                     |\n         |                    | Policy Agent  |                     |\n         |                    +---------------+                     |\n         |                            |                             |\n         |                            v                             |\n         |                  [ Risk Level Check ]                    |\n         |                     /             \\                      |\n         |         (Low/Medium Risk)       (High/Critical Risk)     |\n         |               /                         \\                |\n         |              v                           v               |\n         |     +------------------+       +-------------------+     |\n         |     |   Fusion Agent   |       | Academic Advisor  |     |\n         |     |   (Base Model)   |       |       Agent       |     |\n         |     +------------------+       +---------+---------+     |\n         |              |                           |               |\n         |              |                           v               |\n         |              |                 +-------------------+     |\n         |              |                 |   Mental Health   |     |\n         |              |                 |   Advisor Agent   |     |\n         |              |                 +---------+---------+     |\n         |              |                           |               |\n         |              |                           v               |\n         |              |                 +-------------------+     |\n         |              |                 |   Fusion Agent    |     |\n         |              |                 | (Institution API) |     |\n         |              |                 +---------+---------+     |\n         |              |                           |               |\n         |              v                           v               |\n         |     +----------------------------------------------+     |\n         |     |          Stream Response to Frontend         |     |\n         |     +----------------------------------------------+     |\n         |                                                          |\n         ============================================================\n```\n\n### 1. Multi-Agent Routing \u0026 Orchestration\nWhen a message is received from the frontend:\n1. **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`.\n2. **Routing Decision**:\n   - **Low/Medium Risk**: The query and state are sent directly to the local model using the **Fusion** adapter to stream a unified response.\n   - **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.\n3. **Background State Update**: After sending the response, a background task analyzes the interaction and updates the persisted `StudentState`.\n\n### 2. Security \u0026 Local Persistence\n- All student data is stored locally on the user's computer inside the `data/` directory.\n- 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.\n\n---\n\n## ⚠️ Known Implementation Limitations\n\n\u003e [!WARNING]\n\u003e ### 1. Incomplete Frontend Chat Interface\n\u003e 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 `\u003ciframe\u003e` targeting `/advisor_chat`. \n\u003e \n\u003e *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\".\n\n\u003e [!WARNING]\n\u003e ### 2. Runtime LoRA Hot-Reloading Limitations\n\u003e 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. \n\u003e \n\u003e 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.\n\n---\n\n## 📁 Repository Directory Structure\n\n- [run.py](file:///home/snipeart007/repos/student-buddy/run.py) - Main entrypoint to launch both the backend server and frontend client.\n- [backend/](file:///home/snipeart007/repos/student-buddy/backend) - FastAPI + Gradio server handling state encryption, local inference, and orchestrating agents.\n- [frontend/](file:///home/snipeart007/repos/student-buddy/frontend) - Next.js + Material UI application providing the onboarding questionnaire and chat interfaces.\n- [initial_prompt.md](file:///home/snipeart007/repos/student-buddy/initial_prompt.md) \u0026 [main_prompt.md](file:///home/snipeart007/repos/student-buddy/main_prompt.md) - Original project specifications and system requirements.\n\n---\n\n## 🚀 Getting Started\n\n### Prerequisites\n- Python 3.10+\n- Node.js 18+\n- [uv](https://github.com/astral-sh/uv) (recommended for Python package management)\n\n### Running the Project\nThe project comes with a helper startup script [run.py](file:///home/snipeart007/repos/student-buddy/run.py) at the root level. To start:\n\n1. Install dependencies for the backend and frontend.\n2. Build/Export the frontend assets:\n   ```bash\n   cd frontend\n   npm install\n   npm run build\n   ```\n3. Run the main runner script from the root workspace directory:\n   ```bash\n   python run.py\n   ```\nThis command starts the Uvicorn-served backend and automatically opens `http://127.0.0.1:8000` in your default web browser.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsnipeart007%2Fstudent-buddy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsnipeart007%2Fstudent-buddy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsnipeart007%2Fstudent-buddy/lists"}