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

# 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

pip install -r requirements.txt

1.3 Set up HF Token

Create a .env file:

# .env file content
HF_TOKEN=hf_your_token_here

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

1.4 Test locally

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)

# 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

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:

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:

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:

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