docs/setup-guide.md

Setup Guide

Complete step-by-step guide to get the system running.

Prerequisites

• Node.js 18+ (recommended: 20 LTS)
• Python 3.11+
• npm 9+
• Git

Step 1: API Keys

Create accounts and get keys from these services (all FREE):

1.1 NVIDIA NIM (LLM — MiniMax + LLaMA)

1. Go to https://build.nvidia.com
2. Sign up / login
3. Click any model → "Get API Key"
4. Copy key (starts with nvapi-)
5. Free: 1000+ requests/day

1.2 Serper.dev (Google Search)

1. Go to https://serper.dev
2. Sign up with Google
3. Dashboard → copy API key
4. Free: 2,500 searches/month

1.3 Hunter.io (Email Finding)

1. Go to https://hunter.io
2. Sign up → Dashboard → API
3. Copy API key
4. Free: 25 searches/month

1.4 Reoon (Email Verification)

1. Go to https://emailverifier.reoon.com
2. Sign up → Dashboard → API
3. Copy API key
4. Free: 20 verifications/day
5. NOTE: System optimizes usage (SMTP probe first, Reoon fallback)

1.5 Supabase (Database)

1. Go to https://supabase.com
2. Create project
3. Project Settings → API
4. Copy Project URL and service_role key (not anon key!)
5. Free: 500MB database

1.6 Slack Bot

1. Go to https://api.slack.com/apps → Create New App
2. Name: "Lead Finder"
3. OAuth & Permissions → Add scopes: chat:write, commands, channels:read
4. Install to Workspace → copy Bot Token (xoxb-...)
5. Basic Information → copy Signing Secret
6. Create 2 channels: #leads and #review
7. Get channel IDs: right-click channel → View details → copy ID

1.7 Trigger.dev (Job Orchestration)

1. Go to https://trigger.dev → Sign up
2. Create project
3. Dashboard → API Keys → copy
4. Project ID from URL: trigger.dev/orgs/.../projects/[PROJECT_ID]
5. Free: 50,000 runs/month

Step 2: Environment Setup

cp .env.example .env

Edit .env and fill in all keys from Step 1.

Step 3: Database Migration

Option A — Supabase Dashboard:

1. Open Supabase → SQL Editor
2. Paste contents of supabase/migrations/001_initial_schema.sql → Run
3. Paste contents of supabase/migrations/002_phase1_enhancements.sql → Run

Option B — Supabase CLI:

npx supabase migration up

Step 4: Install & Run

# Install Node.js dependencies
npm install

# Install Python dependencies
cd src/profiling/python-service
pip install -r requirements.txt
cd ../../..

# Terminal 1: Start Trigger.dev
npm run trigger:dev

# Terminal 2: Start Python AI service
cd src/profiling/python-service
python main.py

Step 5: Verify

The system runs automatically at 9 AM PKT daily. To test manually:

• Use Slack /discover command
• Or trigger from Trigger.dev dashboard

Troubleshooting

Issue	Solution
NVIDIA_API_KEY error	Check key starts with nvapi-
MiniMax 429 rate limit	System auto-retries after wait
Hunter returns empty	Free tier: 25/month limit reached
SMTP verification fails	Some mail servers block port 25
Supabase connection error	Check SUPABASE_URL has https://