| --- |
| title: Studyrag |
| emoji: 🏃 |
| colorFrom: blue |
| colorTo: green |
| sdk: docker |
| pinned: false |
| --- |
| |
| # Studyson — RAG Document QA & Summarization |
|
|
| A full-stack Retrieval-Augmented Generation (RAG) app for document Q&A, conversational chat, and summarization. Built with FastAPI, LlamaIndex, Groq, and a persistent Chroma vector store, with a React + Vite frontend. |
|
|
| ## Features |
|
|
| - **Multi-format ingestion** — PDF, DOCX, TXT, and Markdown files |
| - **Multi-file upload** — Drop several files at once; each tracks its own progress |
| - **Web scraping** — Index any HTML page (with timeout, size cap, and content-type guard) |
| - **Conversational chat** — Multi-turn Q&A with per-session memory |
| - **Persistent chat history** — Transcripts stored in SQLite; survives reloads and restarts |
| - **Document management** — List indexed documents and delete them individually |
| - **Persistent vector store** — Chroma on disk; index survives restarts |
| - **Smart summarization** — Length-controlled summaries across all indexed documents |
| - **Source citations** — Verifiable snippets with similarity scores |
| - **Real-time streaming** — Token-by-token Server-Sent Events, cancellable mid-answer |
| - **Dark mode** — Follows system preference, with a manual toggle |
| - **Markdown rendering** — Chat answers render with code blocks, lists, and headings |
|
|
| ## Tech Stack |
|
|
| | Layer | Library | |
| |-------|---------| |
| | Web framework | FastAPI `>=0.118` | |
| | RAG orchestration | LlamaIndex `>=0.14` | |
| | LLM | Groq `openai/gpt-oss-120b` | |
| | Embeddings | HuggingFace `BAAI/bge-small-en-v1.5` | |
| | Vector store | Chroma `>=0.6` (persistent) | |
| | Chat history | SQLite (stdlib `sqlite3`) | |
| | Document parsing | PyMuPDF · pypdf · python-docx | |
| | HTTP client | httpx (async, with timeouts) | |
| | Frontend | React 19 + Vite + TypeScript | |
|
|
| ## API Endpoints |
|
|
| | Method | Endpoint | Description | |
| |--------|----------|-------------| |
| | `GET` | `/` | Web UI (React SPA) | |
| | `POST` | `/upload` | Upload PDF, DOCX, TXT, or MD | |
| | `POST` | `/scrape_and_index` | Scrape and index a URL | |
| | `DELETE` | `/documents/{name}` | Remove one indexed document | |
| | `POST` | `/stream_query` | SSE streaming Q&A (per-session chat memory) | |
| | `POST` | `/query` | One-shot Q&A with source citations | |
| | `POST` | `/summarize` | Summarize all indexed content | |
| | `POST` | `/reset` | Drop the document index (chat history is kept) | |
| | `GET` | `/status` | System status, indexed docs, active model | |
| | `GET` | `/sessions` | List chat sessions, most recent first | |
| | `GET` | `/sessions/{id}/messages` | Full transcript for one session | |
| | `PATCH` | `/sessions/{id}` | Rename a session | |
| | `DELETE` | `/sessions/{id}` | Delete a session and its messages | |
|
|
| ## Configuration |
|
|
| Set via HF Space secrets or a `.env` file locally: |
|
|
| | Variable | Default | Purpose | |
| |----------|---------|---------| |
| | `GROQ_API_KEY` | *(required)* | Groq API key | |
| | `GROQ_MODEL` | `openai/gpt-oss-120b` | Groq chat model | |
| | `EMBED_MODEL` | `BAAI/bge-small-en-v1.5` | Embedding model | |
| | `MAX_FILE_SIZE` | `20971520` (20 MB) | Upload size limit | |
| | `MAX_SCRAPE_BYTES` | `5242880` (5 MB) | Scrape body cap | |
| | `SIMILARITY_TOP_K` | `4` | Retrieval top-k | |
| | `HISTORY_DB_NAME` | `history.db` | SQLite file inside `chroma_store/` | |
|
|
| ## Local Development |
|
|
| The frontend and backend run as two processes in development. Vite proxies API |
| calls to FastAPI, so the app uses same-origin relative paths in both dev and prod. |
|
|
| ```bash |
| git clone <repo-url> |
| cd Exam |
| python -m venv .venv && source .venv/Scripts/activate # Windows: .venv\Scripts\activate |
| pip install -r requirements-dev.txt |
| cp .env.example .env # add your GROQ_API_KEY |
| |
| # terminal 1 — backend |
| uvicorn app.main:app --reload --port 7860 |
| |
| # terminal 2 — frontend (http://localhost:5173) |
| cd frontend && npm install && npm run dev |
| ``` |
|
|
| To serve the built frontend directly from FastAPI (no Vite process), build it |
| into `static/` first: |
|
|
| ```bash |
| cd frontend && npm run build && cp -r dist/* ../static/ |
| ``` |
|
|
| > `static/` is a build artifact and is gitignored — it is always regenerated |
| > from `frontend/`, never edited by hand. |
|
|
| ### Tests |
|
|
| ```bash |
| pytest tests/ -v |
| ``` |
|
|
| Covers the document-delete and chat-history endpoints. These tests avoid the LLM |
| and embedding model entirely, so they need no network access or API key. |
|
|
| ## Docker |
|
|
| ```bash |
| docker compose up --build |
| ``` |
|
|
| The Dockerfile is a multi-stage build: a Node stage compiles the React app, and |
| the Python stage copies the output into `static/`. Volumes persist `uploads/`, |
| `chroma_store/` (which also holds `history.db`), and the HuggingFace model cache. |
|
|
| ## Deploying on Hugging Face Spaces |
|
|
| 1. Push this repo to GitHub |
| 2. Go to [huggingface.co](https://huggingface.co) → your profile → **New Space** |
| 3. Select **Docker** SDK, link your GitHub repo |
| 4. Add `GROQ_API_KEY` under **Settings → Variables and secrets** |
| 5. The Space auto-builds and serves on port 7860 |
|
|
| > **Note:** The Chroma store, chat history, and uploads persist within the Space |
| > filesystem but are wiped on a factory reset. |
|
|
| ## Performance Notes |
|
|
| - `/stream_query` retrieves citation sources with a **retrieval-only** call |
| rather than a second full LLM generation, saving roughly 0.6s and one wasted |
| LLM call per message. |
| - The embedding model is warmed at application startup (~6s), so the first user |
| request no longer pays the model-load cost. |
|
|
| ## Acknowledgments |
|
|
| - [LlamaIndex](https://www.llamaindex.ai/) |
| - [Groq](https://groq.com/) |
| - [Chroma](https://www.trychroma.com/) |
| - [FastAPI](https://fastapi.tiangolo.com/) |
| - [Vite](https://vite.dev/) |
|
|
