HF_DEPLOYMENT_CHECKLIST.md

# 🚀 HF Deployment Pre-Flight Checklist

**Target:** Hugging Face Spaces + GUVI Hackathon

---

## ✅ Required HF Secrets

Set these in HF Spaces → Settings → Secrets:

| Secret Name | Required | Description |
|-------------|----------|-------------|
| `GROQ_API_KEY` | ✅ YES | Groq API key for LLM calls |
| `GUVI_API_KEY` | ✅ YES | GUVI hackathon auth key |

**Optional (defaults work):**
- `ENV=production` (optional, defaults to production behavior)

---

## ✅ Pre-Deploy Verification Commands

Run these locally before pushing to HF:

```bash
# 1. All behavioral tests pass
py -m pytest scripts/fast_behavior_tests.py -v

# 2. Cache optimization tests pass  
py -m pytest scripts/test_prompt_caching.py -v -s -k "not Live"

# 3. Main app imports cleanly
py -c "from app.main import app; print('✅ OK')"

# 4. Quick smoke test (start server)
py -m uvicorn app.main:app --port 8000 --host 127.0.0.1
# Then test: curl http://localhost:8000/health
```

---

## ✅ Model Mapping (Cache-Optimized)

| Agent | Model | Cache Support |
|-------|-------|---------------|
| **Persona Replies** | `llama-3.1-8b-instant` | ❌ No |
| **Intelligence Extraction** | `openai/gpt-oss-20b` | ✅ Yes |
| **Safety Guard** | `openai/gpt-oss-safeguard-20b` | ✅ Yes |
| **Smart Reasoning** | `moonshotai/kimi-k2-instruct-0905` | ✅ Yes |

**Note:** Fast chat uses uncached model for speed. Heavy tasks use cached models for cost savings.

---

## ✅ Config Sanity Checklist

| Check | Status |
|-------|--------|
| `DEBUG = False` in config.py | ✅ |
| Mock callback URL commented out | ✅ |
| No hardcoded API keys | ✅ |
| No blocking `time.sleep()` | ✅ |
| All retries capped at 2-5 | ✅ |

---

## ✅ GUVI Callback Readiness

| Requirement | Status |
|-------------|--------|
| URL: `https://hackathon.guvi.in/api/updateHoneyPotFinalResult` | ✅ |
| Auth: `x-api-key` header | ✅ |
| Retry: 5x exponential backoff | ✅ |
| Dedup: `sys_callback_sent` flag | ✅ |
| Trigger: `scamDetected=True AND should_finalize=True` | ✅ |

---

## ✅ Budget Limits (Hardcoded)

| Limit | Value | Enforced |
|-------|-------|----------|
| Max LLM calls per turn | 4 | ✅ |
| Max LLM calls per session | 30 | ✅ |
| Max cascade retries | 2 | ✅ |

---

## 🧪 1-Command HF Sanity Test

After deploying to HF, run this:

```bash
curl -X POST "https://YOUR-SPACE.hf.space/api/v1/guvi/challenge" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_GUVI_API_KEY" \
  -d '{
    "sessionId": "test-123",
    "message": {"text": "Hello, your bank account is blocked", "sender": "scammer"}
  }'
```

**Expected Response:**
```json
{
  "status": "success",
  "reply": "..."
}
```

---

## 🏆 Final Deployment Commands

```bash
# 1. Commit all changes
git add .
git commit -m "Production-ready for GUVI + HF"

# 2. Push to HF
git push hf main
```

---

**Last Verified:** 2026-02-03  
**Score:** 53/53 (100%) Production Ready — All Critical Fixes Applied