Update README.md

README.md

@@ -1,11 +1,377 @@
+# ✅ Final Deployment Checklist
+
+## 📦 Your Complete File Structure
+
+```
+your-hf-space/
+├── .gitignore              ← Create this
+├── .dockerignore           ← Create this  
+├── Dockerfile              ← Use the one I provided
+├── requirements.txt        ← Use the one I provided
+├── main.py                 ← Use the one I provided ⭐
+├── split.py               ← Your existing file
+├── query_service.py       ← Your existing file
+└── README.md              ← Optional
+```
+
+---
+
+## 📝 Files to Create/Copy
+
+### 1. `.gitignore`
+```gitignore
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+env/
+venv/
+*.egg-info/
+dist/
+build/
+*.log
+.DS_Store
+vectorstore/
+docstore/
+docs/
+*.pdf
+.venv/
+```
+
+### 2. `.dockerignore`
+```dockerignore
+__pycache__
+*.pyc
+*.pyo
+*.pyd
+.Python
+env/
+venv/
+.venv/
+vectorstore/
+docstore/
+docs/
+*.pdf
+.git/
+.gitignore
+README.md
+.DS_Store
+*.log
+```
+
+### 3. `requirements.txt`
+```txt
+fastapi==0.109.0
+uvicorn[standard]==0.27.0
+python-multipart==0.0.6
+requests==2.31.0
+langchain-community==0.0.20
+sentence-transformers==2.3.1
+faiss-cpu==1.7.4
+pypdf==3.17.4
+pdfplumber==0.10.3
+PyMuPDF==1.23.8
+Pillow==10.2.0
+```
+
+### 4. `Dockerfile`
+**Copy from the artifact:** "Dockerfile - Final Version (with main.py)"
+
+### 5. `main.py`
+**Copy from the artifact:** "main.py - Service Router"
+
+### 6. Your Existing Files
+- ✅ `split.py` (you already have this)
+- ✅ `query_service.py` (you already have this)
+
+---
+
+## 🚀 Deployment Steps
+
+### Step 1: Create Hugging Face Space
+1. Go to https://huggingface.co/spaces
+2. Click **"Create new Space"**
+3. Configure:
+   - **Name**: `multimodal-rag` (or your choice)
+   - **License**: Apache 2.0
+   - **Space SDK**: **Docker** ⚠️ (Important!)
+   - **Visibility**: Public or Private
+4. Click **"Create Space"**
+
+### Step 2: Clone Repository
+```bash
+git clone https://huggingface.co/spaces/YOUR_USERNAME/multimodal-rag
+cd multimodal-rag
+```
+
+### Step 3: Add All Files
+Copy these 7 files into the directory:
+- [ ] `.gitignore`
+- [ ] `.dockerignore`
+- [ ] `Dockerfile`
+- [ ] `requirements.txt`
+- [ ] `main.py`
+- [ ] `split.py`
+- [ ] `query_service.py`
+
+### Step 4: Push to Hugging Face
+```bash
+git add .
+git commit -m "Initial deployment with combined service"
+git push
+```
+
+### Step 5: Wait for Build
+- ⏱️ Build takes **5-10 minutes**
+- Watch the build logs in your Space settings
+- Look for: `✅ Ingestion service: READY` and `✅ Query service: READY`
+
+### Step 6: Test Your Deployment
+```bash
+# Set your URL
+export BASE_URL="https://YOUR_USERNAME-multimodal-rag.hf.space"
+
+# Test health
+curl $BASE_URL/health
+
+# Test home
+curl $BASE_URL/
+
+# Upload a PDF
+curl -X POST "$BASE_URL/ingest" \
+  -F "file=@sample.pdf"
+
+# Query
+curl -X POST "$BASE_URL/query?question=What%20is%20this%20about?&k=5"
+```
+
+---
+
+## 🎯 Your API Endpoints
+
+Once deployed at `https://YOUR_USERNAME-multimodal-rag.hf.space`:
+
+| Endpoint | Method | Purpose |
+|----------|--------|---------|
+| `/` | GET | Service info & documentation |
+| `/health` | GET | Health check |
+| `/docs` | GET | Interactive API docs (Swagger) |
+| `/ingest` | POST | Upload & process PDF |
+| `/ingest/stats` | GET | Ingestion statistics |
+| `/query` | POST | Query the RAG system |
+| `/query/details` | POST | Query with detailed info |
+| `/query/stats` | GET | Query statistics |
+| `/stats` | GET | Combined statistics |
+
+---
+
+## 🧪 Testing Examples
+
+### Using cURL
+
+```bash
+BASE_URL="https://YOUR_USERNAME-multimodal-rag.hf.space"
+
+# 1. Check if service is running
+curl $BASE_URL/health
+
+# 2. Upload a PDF
+curl -X POST "$BASE_URL/ingest" \
+  -F "file=@document.pdf"
+
+# 3. Check stats
+curl "$BASE_URL/stats"
+
+# 4. Query the system
+curl -X POST "$BASE_URL/query?question=Summarize%20the%20document&k=5"
+
+# 5. Detailed query
+curl -X POST "$BASE_URL/query/details?question=What%20are%20the%20key%20points?&k=3"
+```
+
+### Using Python
+
+```python
+import requests
+
+BASE_URL = "https://YOUR_USERNAME-multimodal-rag.hf.space"
+
+# 1. Health check
+response = requests.get(f"{BASE_URL}/health")
+print(response.json())
+
+# 2. Upload PDF
+with open("document.pdf", "rb") as f:
+    files = {"file": ("document.pdf", f, "application/pdf")}
+    response = requests.post(f"{BASE_URL}/ingest", files=files)
+    print(response.json())
+
+# 3. Query
+params = {"question": "What is the main topic?", "k": 5}
+response = requests.post(f"{BASE_URL}/query", params=params)
+print(response.json())
+```
+
+### Using JavaScript (Frontend)
+
+```javascript
+const BASE_URL = "https://YOUR_USERNAME-multimodal-rag.hf.space";
+
+// Upload PDF
+async function uploadPDF(file) {
+  const formData = new FormData();
+  formData.append('file', file);
+  
+  const response = await fetch(`${BASE_URL}/ingest`, {
+    method: 'POST',
+    body: formData
+  });
+  
+  return await response.json();
+}
+
+// Query
+async function queryRAG(question, k = 5) {
+  const response = await fetch(
+    `${BASE_URL}/query?question=${encodeURIComponent(question)}&k=${k}`,
+    { method: 'POST' }
+  );
+  
+  return await response.json();
+}
+
+// Usage
+const result = await queryRAG("What is this document about?");
+console.log(result.answer);
+```
+
+---
+
+## ⚠️ Important Notes
+
+### 1. **Persistent Storage** (Critical!)
+By default, Hugging Face Spaces are ephemeral. Your vectorstore will disappear on restart!
+
+**Solution Options:**
+- **Enable Persistent Storage** (in Space settings - paid feature)
+- **Use External Vector DB** (Pinecone, Weaviate, Qdrant)
+- **Rebuild on startup** (include sample docs in repo)
+
+### 2. **Memory Management**
+Free tier has limited RAM. If you get OOM errors:
+- Reduce `k` parameter in queries
+- Process smaller PDFs
+- Upgrade to paid tier
+
+### 3. **Build Time**
+First deployment takes longer. Subsequent deployments are faster (Docker layer caching).
+
 ---
-title: Multi Modal RAG
-emoji: 🏃
-colorFrom: purple
-colorTo: blue
-sdk: docker
-pinned: false
-license: apache-2.0
+
+## 🎉 What You Get
+
+With `main.py`, your service will:
+
+✅ Handle PDF ingestion (`/ingest`)  
+✅ Handle queries (`/query`)  
+✅ Provide statistics (`/stats`)  
+✅ Serve interactive API docs (`/docs`)  
+✅ Share vectorstore between services  
+✅ Run on a single endpoint  
+✅ Cost-effective (one space instead of two)  
+
+---
+
+## 🐛 Troubleshooting
+
+### Build Fails
+```bash
+# Check these:
+- Dockerfile CMD points to "main:app" ✓
+- All 7 files are present ✓
+- requirements.txt has no typos ✓
+```
+
+### Service Won't Start
+```bash
+# In Space logs, look for:
+✅ Loaded ingestion service (split.py)
+✅ Loaded query service (query_service.py)
+✅ Ingestion service: READY
+✅ Query service: READY
+
+# If you see errors, they'll show here
+```
+
+### No Documents Found
+```
+Problem: Query returns "No relevant documents found"
+Solution: 
+1. Check if you uploaded PDFs via /ingest
+2. Enable persistent storage
+3. Check /stats to see vectorstore_count
+```
+
+### Slow Responses
+```
+Problem: Queries take too long
+Solution:
+1. Reduce k parameter (try k=3 instead of k=5)
+2. Upgrade Space hardware
+3. Check external API endpoints (QWEN, BLIP) are fast
+```
+
+---
+
+## 📚 Additional Resources
+
+- [Hugging Face Spaces Docs](https://huggingface.co/docs/hub/spaces)
+- [FastAPI Documentation](https://fastapi.tiangolo.com/)
+- [Your API Docs](https://YOUR_USERNAME-multimodal-rag.hf.space/docs) (after deployment)
+
+---
+
+## ✅ Final Checklist
+
+Before pushing:
+- [ ] Created `.gitignore`
+- [ ] Created `.dockerignore`
+- [ ] Copied `Dockerfile`
+- [ ] Copied `requirements.txt`
+- [ ] Created `main.py` ⭐
+- [ ] Have `split.py`
+- [ ] Have `query_service.py`
+- [ ] Space SDK is set to **Docker**
+- [ ] Ready to `git push`
+
+After deployment:
+- [ ] Build completed successfully
+- [ ] `/health` endpoint responds
+- [ ] Can upload PDF via `/ingest`
+- [ ] Can query via `/query`
+- [ ] Considered enabling persistent storage
+
+---
+
+## 🎯 Quick Command Summary
+
+```bash
+# Clone
+git clone https://huggingface.co/spaces/YOUR_USERNAME/multimodal-rag
+cd multimodal-rag
+
+# Add files (copy all 7 files here)
+
+# Deploy
+git add .
+git commit -m "Deploy combined RAG service"
+git push
+
+# Test (after build completes)
+curl https://YOUR_USERNAME-multimodal-rag.hf.space/health
+```
+
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+**You're all set! 🚀** Once you push, wait ~10 minutes and your service will be live!