Institutional AI Assistant — Powered by RAG + Local LLM
IMS AstroBot is a Retrieval-Augmented Generation (RAG) chatbot built for institutional use. It combines a React-based admin dashboard with a RAG pipeline to let students and faculty ask questions about institutional documents. Administrators get real-time analytics, document management, and AI configuration tools.
Latest Version: 2.0.0 | Status: Production-Ready | License: MIT
- 💬 Smart Q&A — Ask natural language questions about institutional documents
- ⚡ Real-time Streaming — Responses are delivered token-by-token via SSE for zero perceived latency
- 🎙️ Voice-to-Text — Ask questions via microphone (powered by OpenAI Whisper)
- 📚 Source Citations — Every response includes exact document references
- ⚡ Fast Search — Semantic vector search via ChromaDB (sub-second retrieval)
- 🔐 Role-Based Access — Faculty and student roles with login authentication
- 📄 Document Management — Upload, index, search, and delete documents (PDF, DOCX, TXT, XLSX, CSV, PPTX, HTML)
- 👥 User Management — Create users, enable/disable accounts, manage roles (admin/faculty/student)
- 📊 Usage Analytics — Dashboard with total queries, top users, response times, daily trends
- 📋 Query Logs — Inspect recent queries with full responses and source documents
- 💾 Conversation Memory — Intelligent semantic caching for instant responses to similar questions (⚡50-100ms)
- 🤖 AI Settings — Swap GGUF models, tune temperature/tokens, edit system prompts
- 🩺 System Health — Real-time status checks for SQLite, ChromaDB, LLM, embeddings, file storage
- A modular RAG pipeline (ingest → chunk → embed → retrieve → generate)
- Local/remote LLM provider integrations (Ollama, cloud providers)
- A React-based admin UI for document uploads, user management, and analytics
- FastAPI endpoints (REST + SSE) for chat and administration
- Examples for voice-to-text using Whisper and offline embedding setup
If you use this project in a product or research context, please follow the MIT license and attribution rules.
- Document ingestion for PDF, DOCX, CSV, XLSX, PPTX, HTML with structure-aware chunking
- Sentence-transformers embeddings stored in ChromaDB for fast semantic search
- Provider manager to route requests to a primary LLM with fallbacks
- Streaming responses (SSE) for low perceived latency in the chat UI
- Admin dashboard for uploads, user roles, and system health checks
- Conversation memory (semantic caching) to speed up repeated/frequent queries
Prerequisites: Python 3.10+, Node 16+, Java 17+ (for Spring Boot). See requirements.txt and react-frontend/package.json for exact versions.
- Create a Python virtual environment and install dependencies
python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt- Start the services
# Terminal 1 — FastAPI
python api_server.py
# Terminal 2 — Spring Boot
cd springboot-backend
.\mvnw.cmd spring-boot:run
# Terminal 3 — React
cd react-frontend
npm install
npm run dev- Open the frontend: http://localhost:3000 — admin credentials are defined in
.env(change immediately).
# 1. Copy environment file
cp .env.example .env
# 2. Start all services
docker-compose up -d
# 3. Access:
# Frontend: http://localhost:3000
# FastAPI: http://localhost:8000/docs
# Streamlit: http://localhost:8501Services started by docker-compose up:
| Service | Container | Port(s) | Description |
|---|---|---|---|
astrobot-api |
Python Backend | 8000 / 8501 |
FastAPI REST API + Streamlit UI |
astrobot-backend |
Spring Boot | 8080 |
Java proxy bridging frontend → API |
astrobot-frontend |
React + Nginx | 3000 |
Admin dashboard |
Persistent volumes: astrobot_data (SQLite, ChromaDB, uploads), astrobot_models (model caches).
| Image | Size | Notes |
|---|---|---|
astrobot-api |
~1–1.5 GB | Uses fastembed (ONNX runtime) instead of PyTorch — ~70% smaller than sentence-transformers |
astrobot-backend |
~250 MB | Eclipse Temurin JRE 17 + Spring Boot fat jar |
astrobot-frontend |
~60 MB | Multi-stage build: Node builder → Nginx static serve |
Total disk usage: ~1.3–1.8 GB for all images.
Why was the image shrunk? Replaced
sentence-transformers(PyTorch-based, ~2 GB) withfastembed(ONNX-based, ~50 MB). This cut the Python image from ~5 GB down to ~1.5 GB. No other functionality was lost — sameall-MiniLM-L6-v2model, same accuracy.
This project is community-friendly. Contributions are welcome:
- Issues: open bug reports or feature requests
- Pull Requests: fork, branch, add tests/documentation, and submit a PR
- Code Style: follow existing project conventions (PEP8 for Python, typical React patterns)
Before larger changes, open an issue to discuss design and compatibility.
astrobot/
├── app.py # Streamlit entry point
├── api_server.py # FastAPI REST API
├── config.py # Central configuration
├── requirements.txt
├── Dockerfile / docker-compose.yml
│
├── auth/ # Auth logic (login, session)
├── database/ # SQLite + institute DB layers
├── ingestion/ # Document parsing, chunking, embedding
├── middleware/ # Rate limiting, request tracking
├── rag/ # Retrieval, generation, providers, memory
├── views/ # Streamlit UI pages
├── log_config/ # Logging + Sentry setup
│
├── scripts/ # Utilities: launcher, verify, start/stop servers
├── tests/ # Standalone test scripts
├── testing/ # Test framework (pytest suite)
├── react-frontend/ # React admin dashboard
├── springboot-backend/ # Spring Boot proxy layer
│
├── docs/ # Architecture, guides, API reference
└── data/ # Runtime data (SQLite, ChromaDB, uploads)
This repository includes upload and storage code for documents and embeddings. Treat uploaded documents as potentially sensitive: do not store secrets in uploaded files and configure proper access controls when deploying.