README.md

metadata

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)

Local Setup

1. Clone the repository

git clone <repository-url>
cd studyrag

2. Create virtual environment

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

3. Install dependencies

pip install -r requirements.txt

4. Set up environment variables

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

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

cp .env.example .env
# Edit .env with your Groq API key

2. Build and run with Docker Compose

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 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:

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

Port already in use:

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 for RAG orchestration
• Groq for lightning-fast LLM inference
• FastEmbed for lightweight embeddings
• FastAPI for the web framework

---

Built with ❤️ using RAG technology