Intelligent teaching & research assistant combining course materials analysis with web research capabilities for comprehensive educational support.
TRA_demo.mp4
Multi-agent system built with LangGraph that intelligently routes queries through specialized agents:
- Router Agent → Analyzes queries and determines optimal agent selection
- RAG Path → Agents that search and analyze uploaded course materials (incl. query enhancement and document analysis)
- Web Path → Performs current web research via Gemini + Google Search (incl. query generation and reflection)
- Synthesis Agent → Combines insights from multiple sources with proper attribution
- OCR Processing: Nanonets OCR for multimodal document analysis
- Title Generation: Configurable models (default: Gemma 1B for efficiency)
- Local LLM: Ollama with support for various models (GPT-OSS, Qwen, etc.)
- Vector Search: ChromaDB with SentenceTransformers embeddings
✅ Smart Query Routing - Automatic selection of RAG, web research, or hybrid approach
✅ Document Management - Upload and manage PDFs, DOCX, PPTX, images (OCR)
✅ Real-time Streaming - Live response generation with status updates (SSE)
✅ Agent Modes & Privacy - Toggle Documents, Web Search, or Local-only per message
✅ User Roles & Dashboards - Student, Professor, and Admin views
✅ Ratings & Analytics - 1–5★ response ratings, comments, My Ratings, Admin analytics
✅ Citations & Sources Panel - Inline citations with per-message numbering and previews
✅ Research Timeline - Visual step-by-step process (routing → RAG/web → reflection → synthesis)
✅ Context & Personalization - Optional custom instructions and user role passed to the agent
✅ Auto Title Generation - Smart chat titles per session
✅ Math Rendering - KaTeX for clean formulas in answers
├── backend/ # FastAPI + LangGraph + MongoDB
│ ├── app/
│ │ ├── agents/ # Multi-agent system (router, RAG, web research, synthesis)
│ │ ├── routers/ # API endpoints (auth, chat, documents, ratings)
│ │ ├── core/ # Core utilities (auth, config, PDF processing)
│ │ ├── db/ # Database and vector store
│ │ └── models/ # Data models
│ └── .env(.example) # Backend configuration
├── frontend/ # React + TypeScript + MUI
│ ├── src/
│ │ ├── components/
│ │ ├── pages/
│ │ └── hooks/
│ └── package.json
├── reference/ # Reference implementation
├── Makefile # Build automation
├── package.json # NPM scripts
├── pyproject.toml # UV Python dependency management
└── uv.lock # UV lockfile
- UV (Python package manager)
- Node.js 16+
- Ollama with a model (e.g.,
ollama pull gpt-oss:20b) - LibreOffice (for PPTX/DOCX to PDF conversion)
- Gemini API Key (optional, for web research)
The system's hardware requirements depend on the chosen LLM models:
| Configuration | GPU RAM Required | Use Case |
|---|---|---|
| Recommended (GPT-OSS 20B + Gemma 1B + Nanonets OCR) | ~25GB | Best performance and accuracy |
| Balanced (Qwen3 8B + Gemma 1B + Nanonets OCR) | ~16GB | Good balance of performance/resources |
| Minimal (Qwen3 4B + lightweight models) | ~8GB | Basic functionality |
Note: For best results, avoid models below 4B parameters. The system can run locally on laptops/workstations with sufficient GPU memory.
# Option 1: Using Makefile (recommended)
make quickstart # Install all dependencies
make dev # Start both backend and frontend
# Option 2: Using NPM scripts
npm run setup # Install dependencies
npm run dev # Start development servers
# Option 3: Manual with UV
uv sync # Install backend deps
cd frontend && npm install # Install frontend depsIf you don't have sudo access and encounter errors with document conversions:
# 1. Install local LibreOffice (for PPTX/DOCX conversion)
bash scripts/install_local_libreoffice.sh
# 2. Install Python dependencies
uv sync
# 3. Install frontend dependencies
cd frontend && npm installThe scripts will:
- Install LibreOffice 25.2.5 locally in
~/.local/libreoffice-25.2.5/ - Automatically add environment variables to your
~/.bashrc
# Copy and configure environment
cp backend/.env.example backend/.env
# Add your GEMINI_API_KEY and other settingsKey environment variables in backend/.env:
# Models & runtime
OLLAMA_BASE_URL=http://localhost:11434
OLLAMA_MODEL=qwen3:8b # or gpt-oss:20b, etc.
OLLAMA_PRELOAD_MODELS= # optional: comma-separated list to warm-load
TITLE_GENERATION_MODEL=gemma3:1b
# Web research
GEMINI_API_KEY=your-api-key
# Database
DATABASE_TYPE=sqlite # sqlite or mongodb
SQLITE_PATH=./data/teaching_assistant.db
MONGODB_URL=mongodb://...
# Optional: LibreOffice path (for servers without sudo)
LIBREOFFICE_PATH=$HOME/.local/libreoffice-25.2.5/program/sofficemake backend # Backend only (FastAPI on :8000)
make frontend # Frontend only (React on :3000)
make test # Run tests- Frontend: http://localhost:3000
- Backend API: http://localhost:8000
- API Docs: http://localhost:8000/docs
Demo Accounts: [email protected] / admin1234, [email protected] / prof1234, [email protected] / student1234
- Rate any assistant response with 1–5★ and an optional comment.
- “My Ratings” page for users to review their feedback history.
- Admin Rating Dashboard with stats (avg score, distribution, comments, recent items) and edit/delete tools.
- Ratings capture transparency metadata (local model, web model, and agent mode used) to support evaluation.
Endpoints (prefix /api/ratings): create, update, delete, list with pagination, stats, and per-user ratings.
- Per-message mode toggle: Documents (RAG), Web Search, or both. “Local-only” forces no external calls.
- Live Research Timeline shows the full pipeline (routing → RAG enhancement → RAG/web → reflection → synthesis).
- Sources panel with inline citations and per-message numbering; click to preview documents or open web links.
- Streaming model info displays which local/web models contributed to the answer.
- Optional custom instructions (system message) when creating a chat session.
- The agent receives user context (name/description) and role (student/professor/admin) at each interaction to tailor responses.
- PDFs, DOCX, PPTX (via LibreOffice conversion), and images with OCR (Nanonets OCR) are supported.
- Chunked storage with page-level metadata for precise citations and previews.
- Student: chat, sources, ratings.
- Professor: document upload/management, course material exploration.
- Admin: user/ratings oversight and analytics.
| Component | Technology |
|---|---|
| Backend | Python: FastAPI + LangGraph + SQLite/MongoDB |
| Frontend | React + TypeScript + MUI |
| Package Management | UV (Python) + NPM (Node.js) |
| Local LLM | Ollama (gpt-oss:20b recommended) |
| Web Research | Google Gemini AI + Search API |
| Vector Store | ChromaDB + SentenceTransformers |
| Build Tools | Makefile + NPM scripts |
See the Configuration section above for the full list of key environment variables.
The Teaching & Research Assistant can be deployed in various environments:
- Laptop/Workstation: Requires GPU with sufficient VRAM (see Hardware Requirements)
- Development Server: Ideal for team collaboration and testing
- Production Server: For institutional deployment with proper GPU resources
Container-based deployment for easier scaling and management.
- Web research flow and reflection loop were inspired in part by Google’s Gemini Fullstack LangGraph Quickstart: https://github.com/google-gemini/gemini-fullstack-langgraph-quickstart
- Local LLM runtime powered by Ollama and the open‑source model ecosystem:
- Ollama: https://ollama.com/
- Ollama Models Library: https://ollama.com/library
- Example families used in this project: GPT‑OSS, Qwen3, and Gemma. See their cards in the Ollama Library for variants and sizes.
If you use this work in your research or educational projects, please cite:
@software{horstmann2025teaching_assistant,
title={Teaching & Research Assistant: Multi-Agent RAG System for Educational Support},
author={Horstmann, Tim},
year={2025},
url={https://github.com/TimLukaHorstmann/Teaching-Assistant},
note={Multi-agent system combining course materials analysis with web research}
}This project is licensed under the Creative Commons Attribution-NonCommercial 4.0 International License.
- ✅ Share and adapt for non-commercial use
- ✅ Attribution required when using or modifying
- ❌ No commercial use without explicit permission
Tim Horstmann
📧 [email protected]
🏛️ Hi! PARIS Research Center
Multi-Agent Teaching & Research Assistant - Intelligent educational support combining course materials with real-time web research