`ROBOFLOW_SETUP.md`

129 lines

# 🔑 Roboflow API Key Setup Guide

## Quick Setup (5 minutes)

The Wine Tracker uses Roboflow's free wine label detection API for advanced authentication. Follow these steps to enable it:

### Step 1: Sign Up for Free Roboflow Account

1. Visit: **https://roboflow.com/**
2. Click **"Sign Up"** or **"Get Started"**
3. Choose free account tier (includes 1,000 API calls/month free)
4. Complete registration with email or Google/GitHub

### Step 2: Get Your API Key

1. After signing up, you'll be redirected to your workspace
2. Click your profile icon (top right)
3. Select **"Settings"**
4. Navigate to **"API"** section
5. Copy your **Private API Key** (starts with letters/numbers)

### Step 3: Add API Key to Wine Tracker

**Option A: Using Environment Variable**
```bash
cd /root/WebsitesMisc/WineFinder
echo "ROBOFLOW_API_KEY=your_api_key_here" >> .env
pm2 restart wine-tracker
```

**Option B: Direct Edit**
1. Open `.env` file in the WineFinder directory
2. Add this line: `ROBOFLOW_API_KEY=your_api_key_here`
3. Replace `your_api_key_here` with your actual key
4. Save and restart: `pm2 restart wine-tracker`

### Step 4: Verify It Works

Test the verification endpoint:
```bash
curl http://localhost:9222/api/verification/test
```

You should see: `"roboflowConfigured": true`

---

## What This Enables

With Roboflow API key configured:

✅ **AI-Powered Wine Label Detection**
- Recognizes 5,464 different wine labels
- 95%+ accuracy on known wines
- Real-time image analysis

✅ **Advanced Features**
- Detects counterfeit labels
- Extracts wine information from photos
- Cross-references database for authenticity

✅ **Free Tier Includes**
- 1,000 API calls/month
- Unlimited projects
- Access to pre-trained models
- Basic analytics

---

## Without API Key

The Wine Tracker still works without a Roboflow API key using:

- **Local pattern matching** - Extracts text and identifies common wine label patterns
- **Database cross-checking** - Matches against known wines in the database
- **Basic verification** - Returns "likely authentic" or "unknown" status

---

## Upgrading (Optional)

Need more than 1,000 verifications/month?

| Tier | API Calls | Cost |
|------|-----------|------|
| Free | 1,000/mo | $0 |
| Starter | 10,000/mo | $49/mo |
| Professional | 100,000/mo | $249/mo |

---

## Alternative: Public Model (No API Key)

The Puppeteer script created a public model configuration at:
`/root/WebsitesMisc/WineFinder/roboflow-public.json`

This can be used for testing without an API key, but has rate limits.

---

## Troubleshooting

**Problem**: Test endpoint shows `"roboflowConfigured": false`

**Solution**:
1. Check `.env` file has `ROBOFLOW_API_KEY=...` line
2. Ensure no extra spaces around the equals sign
3. Restart server: `pm2 restart wine-tracker`
4. Check logs: `pm2 logs wine-tracker --lines 20`

**Problem**: API calls return 401 Unauthorized

**Solution**:
1. Verify API key is correct in `.env`
2. Check key hasn't expired in Roboflow dashboard
3. Ensure you're using the **Private API Key**, not the Public key

---

## Questions?

- Roboflow Docs: https://docs.roboflow.com/
- Wine Label Model: https://universe.roboflow.com/wine-label/wine-label-detection
- Email: steve@designerwallcoverings.com

---

**Last Updated**: November 2025