SETUP_GUIDE.md

# 🚀 Quick Setup Guide

## Prerequisites
- Python 3.10 or higher
- Anthropic API key

## Installation (3 minutes)

### Step 1: Extract and Navigate
```bash
unzip gig-market-mcp-app.zip
cd gig-market-mcp-app
```

### Step 2: Install Dependencies
```bash
pip install -r requirements.txt
```

**What gets installed:**
- Gradio (UI framework)
- Anthropic (Claude AI)
- LlamaIndex (RAG framework) 🦙
- HuggingFace Embeddings 🤗
- ChromaDB (vector database)
- MCP (Model Context Protocol)

**Installation time:** ~2-3 minutes

### Step 3: Set API Key
```bash
export ANTHROPIC_API_KEY=your_key_here
```

Or create `.env` file:
```bash
echo "ANTHROPIC_API_KEY=your_key_here" > .env
```

### Step 4: Run the App
```bash
python app.py
```

**First run:** Will take ~30 seconds to:
- Load embedding model (100MB)
- Index 50 workers + 50 gigs
- Create vector database

**Expected output:**
```
🔄 Loading embedding model...
✅ Vector database ready!
🔄 Loading and indexing data...
✅ Indexed 50 workers and 50 gigs
✅ Data loaded and indexed!
Running on local URL:  http://127.0.0.1:7860
Running on public URL: https://xxxxx.gradio.live
```

## Testing (2 minutes)

### Test 1: Find Gigs for Worker
1. Click "Find Gigs for Me" tab
2. Enter:
   ```
   I'm a handyman with 10 years experience. I do plumbing, electrical 
   work, and carpentry. Based in Rome, available weekdays, charge €25/hour
   ```
3. Click "Create Profile & Find Gigs (RAG)"
4. **Expected:** Profile + 5 matching gigs with semantic similarity scores

### Test 2: Find Workers for Gig
1. Click "Find Workers for My Gig" tab
2. Enter:
   ```
   Need someone to paint a jungle mural in my kid's bedroom. 
   Wall is 3x4 meters. Madrid area, budget around €400
   ```
3. Click "Create Post & Find Workers (RAG)"
4. **Expected:** Gig post + 5 matching workers with similarity scores

## Troubleshooting

### Error: "ANTHROPIC_API_KEY not found"
**Solution:** Set the environment variable
```bash
export ANTHROPIC_API_KEY=your_key_here
```

### Error: "ModuleNotFoundError"
**Solution:** Install requirements again
```bash
pip install -r requirements.txt --upgrade
```

### Error: "workers_data.json not found"
**Solution:** Generate the data
```bash
python generate_data.py
```

### Slow first query?
**Normal!** First query loads the embedding model (~100MB). Subsequent queries are fast (~100ms).

## What to Expect

### First Query (30-60 seconds)
- Loading embedding model
- Creating vectors
- Building index

### Subsequent Queries (2-5 seconds)
- Profile/post creation: ~2 seconds (Claude API)
- Semantic search: ~100ms (local vector DB)
- Result formatting: ~1 second (Claude API)

## Features to Demo

### 1. Semantic Search
Show that it finds relevant matches even without exact keyword overlap:
- Query: "fix leaking pipes" → Finds "plumber"
- Query: "outdoor work" → Finds "gardener"

### 2. Vector Similarity Scores
Point out the semantic similarity scores in results

### 3. Large Database
Mention "searching through 50 workers/gigs" in real-time

### 4. Sponsor Integration
Highlight "Powered by LlamaIndex 🦙 + HuggingFace 🤗"

## File Structure

```
gig-market-mcp-app/
├── app.py                    # Main application with RAG
├── generate_data.py          # Data generation script
├── workers_data.json         # 50 synthetic workers
├── gigs_data.json           # 50 synthetic gigs
├── requirements.txt          # Python dependencies
├── README.md                 # Main documentation
├── RAG_ARCHITECTURE.md       # Technical deep-dive
├── HACKATHON.md             # Submission info
├── SETUP_GUIDE.md           # This file
├── .env.example             # Environment template
├── .gitignore               # Git ignore rules
└── LICENSE                   # MIT license
```

## Resource Usage

**Memory:**
- Embedding model: ~100MB
- Vector database: ~50MB
- ChromaDB: ~50MB
- **Total:** ~200MB

**Disk:**
- Installed packages: ~500MB
- App + data: ~30KB
- **Total:** ~500MB

**CPU:**
- Embedding: Light (CPU-only model)
- Vector search: Minimal
- **Recommended:** 2+ CPU cores

## Next Steps

After successful setup:

1. **Read RAG_ARCHITECTURE.md** - Understand the tech
2. **Read HACKATHON.md** - See submission details
3. **Test both flows** - Worker + Employer
4. **Check vector scores** - See semantic matching in action
5. **Deploy to HF Spaces** - Share your demo!

## Support

Questions? Check:
- `README.md` - Full documentation
- `RAG_ARCHITECTURE.md` - Technical details

## Success Checklist

- [x] Python 3.10+ installed
- [x] Dependencies installed (`pip install -r requirements.txt`)
- [x] API key configured
- [x] App running (`python app.py`)
- [x] Both tabs tested
- [x] Results showing semantic similarity scores
- [x] Happy with the matches!

**Ready to win the hackathon!** 🏆🎉