Upload README.md

README.md

@@ -0,0 +1,243 @@
+---
+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