SETUP_GUIDE.md

🚀 Quick Setup Guide

Prerequisites

• Python 3.10 or higher
• Anthropic API key

Installation (3 minutes)

Step 1: Extract and Navigate

unzip gig-market-mcp-app.zip
cd gig-market-mcp-app

Step 2: Install Dependencies

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

export ANTHROPIC_API_KEY=your_key_here

Or create .env file:

echo "ANTHROPIC_API_KEY=your_key_here" > .env

Step 4: Run the App

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

export ANTHROPIC_API_KEY=your_key_here

Error: "ModuleNotFoundError"

Solution: Install requirements again

pip install -r requirements.txt --upgrade

Error: "workers_data.json not found"

Solution: Generate the data

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
• HACKATHON.md - Project overview

Success Checklist

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

Ready to win the hackathon! 🏆🎉