# 🚀 PaperChat - Complete Deployment Guide

## 📋 Quick Checklist

- [ ] All files created
- [ ] HF account ready
- [ ] HF Token obtained
- [ ] Space created
- [ ] Files uploaded
- [ ] App running

---

## 📁 Project Structure

Create a folder called `paperchat` with these files:

```
paperchat/
├── app.py                 # Main Streamlit application
├── requirements.txt       # Python dependencies
├── README.md             # Hugging Face Spaces config
└── .env                  # Local environment variables (don't upload this!)
```

---

## 🔧 Step 1: Local Setup & Testing (Optional but Recommended)

### 1.1 Create virtual environment

```bash
# Create project folder
mkdir paperchat
cd paperchat

# Create virtual environment
python -m venv venv

# Activate it
# On Windows:
venv\Scripts\activate
# On Mac/Linux:
source venv/bin/activate
```

### 1.2 Install dependencies

```bash
pip install -r requirements.txt
```

### 1.3 Set up HF Token

Create a `.env` file:

```bash
# .env file content
HF_TOKEN=hf_your_token_here
```

**Get your token**: https://huggingface.co/settings/tokens

### 1.4 Test locally

```bash
streamlit run app.py
```

Open http://localhost:8501 and test with a sample PDF!

---

## 🌐 Step 2: Deploy to Hugging Face Spaces

### 2.1 Create a new Space

1. Go to https://huggingface.co/spaces
2. Click **"Create new Space"**
3. Fill in:
   - **Space name**: `paperchat` (or your preferred name)
   - **License**: MIT
   - **Select SDK**: Streamlit
   - **Hardware**: CPU (free tier is fine!)
   - **Visibility**: Public

### 2.2 Upload files

**Option A: Via Web Interface**
1. Click "Files" tab in your Space
2. Click "Add file" → "Upload files"
3. Upload: `app.py`, `requirements.txt`, `README.md`
4. Commit changes

**Option B: Via Git (Recommended)**

```bash
# Clone your space
git clone https://huggingface.co/spaces/YOUR_USERNAME/paperchat
cd paperchat

# Copy your files
cp /path/to/app.py .
cp /path/to/requirements.txt .
cp /path/to/README.md .

# Commit and push
git add .
git commit -m "Initial commit"
git push
```

### 2.3 Add HF Token to Secrets

1. Go to your Space settings
2. Click "Settings" → "Repository secrets"
3. Click "Add a secret"
4. Name: `HF_TOKEN`
5. Value: Your Hugging Face token
6. Save

### 2.4 Wait for build

The Space will automatically build and deploy. Watch the logs:
- ⏳ Building... (1-2 minutes)
- ✅ Running! 

---

## ✅ Step 3: Verify Deployment

1. Visit your Space URL: `https://huggingface.co/spaces/YOUR_USERNAME/paperchat`
2. Upload a test PDF (try a short research paper)
3. Ask a question
4. Verify you get an answer

---

## 🐛 Common Issues & Fixes

### Issue 1: "Module not found" error

**Fix**: Check `requirements.txt` has all dependencies

```txt
smolagents
streamlit
pypdf
langchain
langchain-community
sentence-transformers
python-dotenv
rank_bm25
```

### Issue 2: "HF_TOKEN not found"

**Fix**: Add token to Space secrets (Step 2.3)

### Issue 3: App crashes on PDF upload

**Fix**: Usually a memory issue. Try:
- Smaller PDF (< 10 MB)
- Reduce `chunk_size` in app.py to 300

### Issue 4: Slow response times

**Fix**: This is normal for free tier. Upgrade to better hardware in Space settings if needed.

---

## 🎨 Step 4: Customization (Optional)

### Change the model

In `app.py`, modify the agent creation:

```python
agent = CodeAgent(
    tools=[retriever_tool],
    model=InferenceClientModel(model_id="meta-llama/Llama-3.3-70B-Instruct"),
    max_steps=4,
    verbosity_level=0,
)
```

### Change colors/theme

Update `README.md` header:

```yaml
colorFrom: red
colorTo: yellow
```

### Add example papers

Pre-load famous papers in the sidebar for quick demos.

---

## 📊 Step 5: Monitor & Improve

### Track usage

- Check Space analytics in HF dashboard
- Monitor error logs

### Collect feedback

Add a feedback button:

```python
if st.button("👍 Helpful"):
    st.success("Thanks for your feedback!")
```

### Add features

Ideas:
- Multiple paper comparison
- Export chat as PDF
- Highlight relevant sections
- Paper summarization mode

---

## 🎓 Step 6: Add to Resume/Portfolio

### Resume bullet point

```
• Built PaperChat, an AI-powered research paper Q&A tool using Agentic RAG,
  deployed on Hugging Face Spaces with 100+ users
• Implemented retrieval-augmented generation with BM25 + LLM agents for
  accurate question answering with source citations
```

### Portfolio description

```
PaperChat - Research Paper Q&A Assistant

An intelligent document assistant that helps researchers quickly understand
and extract information from academic papers. Built with smolagents and
deployed on Hugging Face Spaces.

Tech: Python, Streamlit, LangChain, RAG, BM25, LLM Agents
Live Demo: [your-space-url]
```

---

## 🎉 You're Done!

Your app is now:
- ✅ Live on the internet
- ✅ Accessible to anyone
- ✅ Resume-ready
- ✅ Portfolio-worthy

Share your Space URL with friends, on LinkedIn, or in your resume!

---

## 🆘 Need Help?

- **Hugging Face Docs**: https://huggingface.co/docs/hub/spaces
- **Streamlit Docs**: https://docs.streamlit.io
- **smolagents Docs**: https://github.com/huggingface/smolagents

---

**Pro Tip**: Record a 30-second demo video showing:
1. Upload a paper
2. Ask a question
3. Get an answer

Use this video in your portfolio or LinkedIn post! 🎬