Deployment_Guide.md

# 🚀 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! 🎬