docs: Add requirements documentation and restore requirements.txt

.gitignore

@@ -18,6 +18,7 @@ data/
 *.txt
 !requirements.txt
 !README.txt
+!GUVI_REQUIREMENTS.txt
 
 # Temp files
 .pytest_cache/

GUVI_CHALLENGE_DETAILS.md

@@ -0,0 +1,139 @@
+# Agentic Honey-Pot for Scam Detection & Intelligence Extraction
+
+## 1. Introduction
+Online scams such as bank fraud, UPI fraud, phishing, and fake offers are becoming increasingly adaptive. Scammers change their tactics based on user responses, making traditional detection systems ineffective.
+
+This challenge requires participants to build an Agentic Honey-Pot — an AI-powered system that detects scam intent and autonomously engages scammers to extract useful intelligence without revealing detection.
+
+## 2. Objective
+Design and deploy an AI-driven honeypot system that can:
+- Detect scam or fraudulent messages
+- Activate an autonomous AI Agent
+- Maintain a believable human-like persona
+- Handle multi-turn conversations
+- Extract scam-related intelligence
+- Return structured results via an API
+
+## 3. What You Need to Build
+Participants must deploy a public REST API that:
+- Accepts incoming message events
+- Detects scam intent
+- Hands control to an AI Agent
+- Engages scammers autonomously
+- Extracts actionable intelligence
+- Returns a structured JSON response
+- Secures access using an API key
+
+## 4. API Authentication
+- `x-api-key: YOUR_SECRET_API_KEY`
+- `Content-Type: application/json`
+
+## 5. Evaluation Flow
+1. Platform sends a suspected scam message
+2. Your system analyzes the message
+3. If scam intent is detected, the AI Agent is activated
+4. The Agent continues the conversation
+5. Intelligence is extracted and returned
+6. Performance is evaluated
+
+## 6. API Request Format (Input)
+Each API request represents one incoming message in a conversation.
+
+### 6.1 First Message (Start of Conversation)
+```json
+{
+  "sessionId": "wertyu-dfghj-ertyui",
+  "message": {
+    "sender": "scammer",
+    "text": "Your bank account will be blocked today. Verify immediately.",
+    "timestamp": 1770005528731
+  },
+  "conversationHistory": [],
+  "metadata": {
+    "channel": "SMS",
+    "language": "English",
+    "locale": "IN"
+  }
+}
+```
+
+### 6.2 Follow-Up Message
+```json
+{
+  "sessionId": "wertyu-dfghj-ertyui",
+  "message": {
+    "sender": "scammer",
+    "text": "Share your UPI ID to avoid account suspension.",
+    "timestamp": 1770005528731
+  },
+  "conversationHistory": [
+    {
+      "sender": "scammer",
+      "text": "Your bank account will be blocked today. Verify immediately.",
+      "timestamp": 1770005528731
+    },
+    {
+      "sender": "user",
+      "text": "Why will my account be blocked?",
+      "timestamp": 1770005528731
+    }
+  ],
+  "metadata": {
+    "channel": "SMS",
+    "language": "English",
+    "locale": "IN"
+  }
+}
+```
+
+## 7. Agent Behavior Expectations
+The AI Agent must:
+- Handle multi-turn conversations
+- Adapt responses dynamically
+- Avoid revealing scam detection
+- Behave like a real human
+- Perform self-correction if needed
+
+## 8. Agent output format
+```json
+{
+  "status": "success",
+  "reply": "Why is my account being suspended?"
+}
+```
+
+## 9. Evaluation Criteria
+- Scam detection accuracy
+- Quality of agentic engagement
+- Intelligence extraction
+- API stability and response time
+- Ethical behavior
+
+## 10. Constraints & Ethics
+- ❌ No impersonation of real individuals
+- ❌ No illegal instructions
+- ❌ No harassment
+- ✅ Responsible data handling
+
+## 11. Mandatory Final Result Callback
+Once the system detects scam intent and the AI Agent completes the engagement, participants must send the final extracted intelligence to the GUVI evaluation endpoint.
+
+### Callback Endpoint
+`POST https://hackathon.guvi.in/api/updateHoneyPotFinalResult`
+
+### Payload to Send
+```json
+{
+  "sessionId": "abc123-session-id",
+  "scamDetected": true,
+  "totalMessagesExchanged": 18,
+  "extractedIntelligence": {
+    "bankAccounts": ["XXXX-XXXX-XXXX"],
+    "upiIds": ["scammer@upi"],
+    "phishingLinks": ["http://malicious-link.example"],
+    "phoneNumbers": ["+91XXXXXXXXXX"],
+    "suspiciousKeywords": ["urgent", "verify now", "account blocked"]
+  },
+  "agentNotes": "Scammer used urgency tactics and payment redirection"
+}
+```

GUVI_REQUIREMENTS.txt

@@ -0,0 +1,84 @@
+AGENTIC HONEY-POT FOR SCAM DETECTION & INTELLIGENCE EXTRACTION - CHALLENGE REQUIREMENTS
+
+1. INTRODUCTION
+Online scams such as bank fraud, UPI fraud, phishing, and fake offers are becoming increasingly adaptive. Scammers change their tactics based on user responses, making traditional detection systems ineffective.
+This challenge requires participants to build an Agentic Honey-Pot — an AI-powered system that detects scam intent and autonomously engages scammers to extract useful intelligence without revealing detection.
+
+2. OBJECTIVE
+Design and deploy an AI-driven honeypot system that can:
+- Detect scam or fraudulent messages
+- Activate an autonomous AI Agent
+- Maintain a believable human-like persona
+- Handle multi-turn conversations
+- Extract scam-related intelligence
+- Return structured results via an API
+
+3. WHAT YOU NEED TO BUILD
+Participants must deploy a public REST API that:
+- Accepts incoming message events
+- Detects scam intent
+- Hands control to an AI Agent
+- Engages scammers autonomously
+- Extracts actionable intelligence
+- Returns a structured JSON response
+- Secures access using an API key
+
+4. API AUTHENTICATION
+x-api-key: YOUR_SECRET_API_KEY
+Content-Type: application/json
+
+5. EVALUATION FLOW
+- Platform sends a suspected scam message
+- Your system analyzes the message
+- If scam intent is detected, the AI Agent is activated
+- The Agent continues the conversation
+- Intelligence is extracted and returned
+- Performance is evaluated
+
+6. API REQUEST FORMAT (INPUT)
+{
+  "sessionId": "wertyu-dfghj-ertyui",
+  "message": {
+    "sender": "scammer",
+    "text": "Your bank account will be blocked today. Verify immediately.",
+    "timestamp": 1770005528731
+  },
+  "conversationHistory": [],
+  "metadata": {
+    "channel": "SMS",
+    "language": "English",
+    "locale": "IN"
+  }
+}
+
+7. AGENT BEHAVIOR EXPECTATIONS
+The AI Agent must:
+- Handle multi-turn conversations
+- Adapt responses dynamically
+- Avoid revealing scam detection
+- Behave like a real human
+- Perform self-correction if needed
+
+8. AGENT OUTPUT FORMAT
+{
+  "status": "success",
+  "reply": "Why is my account being suspended?"
+}
+
+11. MANDATORY FINAL RESULT CALLBACK
+Once the system detects scam intent and the AI Agent completes the engagement, participants must send the final extracted intelligence to the GUVI evaluation endpoint.
+POST https://hackathon.guvi.in/api/updateHoneyPotFinalResult
+Payload:
+{
+  "sessionId": "abc123-session-id",
+  "scamDetected": true,
+  "totalMessagesExchanged": 18,
+  "extractedIntelligence": {
+    "bankAccounts": ["XXXX-XXXX-XXXX"],
+    "upiIds": ["scammer@upi"],
+    "phishingLinks": ["http://malicious-link.example"],
+    "phoneNumbers": ["+91XXXXXXXXXX"],
+    "suspiciousKeywords": ["urgent", "verify now", "account blocked"]
+  },
+  "agentNotes": "Scammer used urgency tactics and payment redirection"
+}

requirements.txt

@@ -0,0 +1,15 @@
+fastapi==0.104.1
+uvicorn==0.24.0
+pydantic==2.5.2
+pydantic-settings==2.1.0
+httpx==0.25.2
+tenacity==8.2.3
+python-dotenv==1.0.0
+aiosqlite==0.19.0
+sqlalchemy==2.0.23
+pyyaml==6.0.1
+requests==2.31.0
+pytest==7.4.3
+pytest-asyncio==0.21.1
+jinja2==3.1.2
+python-multipart==0.0.6