README.md

---

title: Studyson
emoji: 📚
colorFrom: purple
colorTo: blue
sdk: docker
pinned: false
---


# Studyson - RAG Document QA & Summarization API

A full-stack Retrieval-Augmented Generation (RAG) system for intelligent document question-answering and summarization. Built with FastAPI, LlamaIndex, and Groq AI.

## Features

- **📄 PDF Document Processing**: Upload and index PDF documents with intelligent text extraction
- **🌐 Web Content Scraping**: Scrape and index content from URLs
- **💬 Interactive Q&A Chat**: Ask questions about your documents with streaming responses
- **📝 Smart Summarization**: Generate concise summaries of indexed documents
- **🔍 Source Citations**: Get verifiable citations with exact source snippets
- **⚡ Real-time Streaming**: Token-by-token streaming for responsive user experience
- **🎨 Modern UI**: Clean, responsive web interface with tabbed navigation
- **🐳 Docker Support**: Easy deployment with Docker and Docker Compose

## Tech Stack

### Backend
- **FastAPI**: Modern Python web framework
- **LlamaIndex**: RAG orchestration and document indexing
- **Groq**: Lightning-fast LLM inference (Llama 3.1)
- **FastEmbed**: Lightweight embeddings (BGE-small)
- **PyMuPDF**: Advanced PDF text extraction
- **BeautifulSoup**: HTML parsing and web scraping
- **Pydantic**: Data validation and settings management

### Frontend
- **HTML5/CSS3/JavaScript**: Vanilla web technologies
- **Server-Sent Events (SSE)**: Real-time streaming responses

## Architecture

### Ingestion Pipeline
1. User uploads PDF or provides URL
2. Content extraction (PyMuPDF for PDFs, BeautifulSoup for web)
3. Text chunking and embedding via LlamaIndex + FastEmbed
4. In-memory vector index creation

### Query Pipeline
1. Question embedding generation
2. Semantic similarity search for relevant chunks
3. Context + question sent to Groq LLM
4. Streaming response with source citations

## Installation

### Prerequisites
- Python 3.10 or higher
- Groq API key ([Get it free here](https://console.groq.com))

### Local Setup

1. **Clone the repository**
```bash

git clone <repository-url>

cd studyrag

```

2. **Create virtual environment**
```bash

python -m venv venv

source venv/bin/activate  # On Windows: venv\Scripts\activate

```

3. **Install dependencies**
```bash

pip install -r requirements.txt

```

4. **Set up environment variables**
```bash

cp .env.example .env

```

Edit `.env` and add your Groq API key:
```

GROQ_API_KEY=your_groq_api_key_here

PORT=7860

HOST=0.0.0.0

```

5. **Run the application**
```bash

uvicorn app.main:app --reload --port 7860

```

6. **Access the application**

Open your browser and navigate to: `http://localhost:7860`

### Docker Setup

1. **Set environment variables**
```bash

cp .env.example .env

# Edit .env with your Groq API key

```

2. **Build and run with Docker Compose**
```bash

docker-compose up --build

```

## API Endpoints

| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/` | Serves the web UI |
| POST | `/upload` | Upload PDF document |
| POST | `/scrape` | Scrape URL content |
| POST | `/stream_query` | Stream Q&A response |
| POST | `/query` | Get Q&A response |
| POST | `/summarize` | Generate summary |
| POST | `/reset` | Clear all documents |
| GET | `/status` | Get system status |

## Project Structure

```

studyrag/

├── app/

│   ├── __init__.py

│   ├── main.py              # FastAPI application

│   ├── config.py            # Configuration settings

│   ├── models/

│   │   └── schemas.py       # Pydantic models

│   ├── services/

│   │   └── rag_service.py   # RAG logic

│   └── utils/

│       └── document_processor.py

├── static/

│   ├── css/style.css

│   ├── js/app.js

│   └── index.html

├── .env.example

├── .gitignore

├── Dockerfile

├── docker-compose.yml

├── Procfile

├── requirements.txt

└── README.md

```

## Configuration

### Environment Variables

- `GROQ_API_KEY`: Your Groq API key (required, free tier available)
- `HOST`: Server host (default: 0.0.0.0)
- `PORT`: Server port (default: 7860)

### Application Settings

Edit `app/config.py` to modify:
- `upload_dir`: Upload directory path
- `max_file_size`: Maximum file size (default: 10MB)

## Deployment

### Deploy to Hugging Face Spaces (Recommended - Free)

1. Push code to GitHub
2. Go to [huggingface.co](https://huggingface.co) and create an account
3. Click your profile → **New Space**
4. Configure:
   - **Space name**: `studyson`
   - **SDK**: Select **Docker**
   - **Hardware**: CPU basic (free)
5. Under **Files** → Link to GitHub repo (or upload files)
6. Add secret: `GROQ_API_KEY` in Space Settings → Variables
7. The Space will auto-build and deploy!

**Your app will be live at:** `https://huggingface.co/spaces/YOUR_USERNAME/studyson`

## Features in Detail

### RAG Pipeline
- **Chunking**: Intelligent text splitting for optimal context windows
- **Embeddings**: FastEmbed BGE-small for semantic understanding (lightweight)
- **Retrieval**: Top-k similarity search with configurable parameters
- **Generation**: Groq Llama 3.1 for fast, accurate responses

### Streaming
- Server-Sent Events (SSE) for real-time token delivery
- Progressive rendering in the UI
- Graceful error handling

### Source Attribution
- Exact text snippets from source documents
- Similarity scores for transparency
- Multiple source support per answer

## Limitations

- In-memory vector storage (resets on restart)
- PDF-only document support (extensible to other formats)
- Single-user session management
- No authentication/authorization

## Troubleshooting

### Common Issues

**Import errors:**
```bash

pip install --upgrade -r requirements.txt

```

**API key errors:**
- Verify your `.env` file has the correct `GROQ_API_KEY`
- Check API key validity at [console.groq.com](https://console.groq.com)

**Port already in use:**
```bash

uvicorn app.main:app --port 8000

```

**File upload fails:**
- Check file size is under 10MB

## License

MIT License - feel free to use this project for learning and development.

## Acknowledgments

- [LlamaIndex](https://www.llamaindex.ai/) for RAG orchestration
- [Groq](https://groq.com/) for lightning-fast LLM inference
- [FastEmbed](https://github.com/qdrant/fastembed) for lightweight embeddings
- [FastAPI](https://fastapi.tiangolo.com/) for the web framework

---

Built with ❤️ using RAG technology