# 🛡️ Sentinel Scam Honeypot - GUVI Submission

## Quick Start
```bash
# Install dependencies
pip install -r requirements.txt

# Set API key
export GROQ_API_KEY="your-key-here"

# Run server
uvicorn app.main:app --host 0.0.0.0 --port 7860
```

## API Endpoint
```
POST /api/guvi/analyze
Header: x-api-key: GUVI_HACKATHON_V2
```

## Features
| Feature | Status |
|---------|--------|
| Scam Detection | ✅ Regex + LLM |
| Multi-turn Conversations | ✅ Session-based |
| Human-like Personas | ✅ 5 Indian personas |
| Intelligence Extraction | ✅ Regex-primary (UPI, Phone, Bank, etc.) |
| GUVI Callback | ✅ Automatic on completion |
| Key Rotation | ✅ Multi-key support |
| Static Fallbacks | ✅ Budget exhaustion safety |
| Rate Limit Handling | ✅ Proactive cooldowns |

## Architecture
```
app/
├── main.py              # FastAPI entry point
├── agents/
│   ├── orchestrator.py  # Main pipeline
│   ├── persona_engine.py # Human-like responses
│   └── scam_detector.py  # Detection logic
├── core/
│   ├── llm_client.py    # Groq with rotation
│   └── personas.py      # Persona definitions
└── utils/
    ├── guvi_handler.py  # GUVI API adapter
    └── extractors.py    # Regex intelligence
```

## Personas
- **Sharma Uncle** (65, Delhi) - Elderly, trusting
- **Rahul Kumar** (24, Bihar) - Desperate jobseeker
- **Meena Patel** (45, Gujarat) - Worried housewife
- **Shyam Sharma** (52) - Scared citizen
- **Curious Investor** (35) - Analytical, cautious

## Response Format
```json
{
  "status": "success",
  "scamDetected": true,
  "scamConfidence": 0.95,
  "reply": "Arre yaar, UPI se kaise bhejun?",
  "extractedIntelligence": {
    "upiIds": ["scammer@upi"],
    "phoneNumbers": ["+919876543210"]
  },
  "agentNotes": "[HIGH RISK] Banking fraud detected"
}
```

## GUVI Callback
Automatically sent when:
- High-value intel captured (UPI/Bank) + 2 turns
- Medium intel + 3 turns
- 6 turn hard cap
- Budget exhausted

---
**Team:** AvinashAnalytics  
**Project:** Sentinel Scam Honeypot