Docs/FINAL_IMPLEMENTATION_SPEC.md

# ScamShield AI: Agentic Honeypot System - FINAL IMPLEMENTATION SPECIFICATION
## India AI Impact Buildathon 2026 - Challenge 2
## Target: TOP 10 from 40,000 Participants

**Author/Team Lead:** Shivam Bhuva (@shivambhuva8866)  
**Date:** January 26, 2026  
**Submission Deadline:** February 5, 2026, 11:59 PM  
**Challenge:** Agentic Honey-Pot for Scam Detection & Intelligence Extraction  
**Testing Mode:** API Endpoint Submission (Mock Scammer API Integration)

---

## EXECUTIVE SUMMARY

This document provides the **production-ready implementation specification** for ScamShield AI's Agentic Honeypot System. Built exclusively for Challenge 2 of the India AI Impact Buildathon 2026, this system autonomously detects scam messages, engages scammers with believable AI personas, and extracts actionable intelligence (bank accounts, UPI IDs, phishing links).

**Key Differentiators:**
- ✅ **100% FREE TIER** - Zero paid APIs or services
- ✅ **Phased Implementation** - Text-first (Phase 1), Audio-later (Phase 2)
- ✅ **API-First Design** - Direct Mock Scammer API integration
- ✅ **Bilingual Focus** - English + Hindi only (high accuracy)
- ✅ **Structured JSON Outputs** - Competition-ready response format
- ✅ **Production-Grade** - LangGraph ReAct agents with state persistence

**AI Usage:** 90% (detection, agentic engagement, extraction)  
**Non-AI:** 10% (API wrappers, data preprocessing)

---

## PROBLEM STATEMENT (Official Challenge 2 Requirements)

**Objective:** Design an autonomous AI honeypot system that:
1. Detects scam messages accurately
2. Actively engages scammers using believable personas
3. Extracts intelligence: bank accounts, UPI IDs, phishing links
4. Integrates with Mock Scammer API for testing
5. Returns structured JSON outputs

**India's Scam Crisis Context:**
- 500,000+ scam calls/messages daily (TRAI 2025)
- ₹60+ crore daily losses
- 3+ spam messages per citizen
- Predominant scams: UPI fraud, fake loans, police/bank impersonation
- 47% Indians affected by or know victims of scam fraud

---

## IMPLEMENTATION ARCHITECTURE

### **PHASE 1: TEXT-BASED HONEYPOT (Priority for Feb 5 Submission)**

```

┌─────────────────────────────────────────────────────────────────┐

│                      INPUT LAYER                                │

│  Mock Scammer API → JSON Message → ScamShield API Endpoint     │

└─────────────────────────────────────────────────────────────────┘

                              ↓

┌─────────────────────────────────────────────────────────────────┐

│                   DETECTION MODULE                              │

│  • IndicBERT (ai4bharat/indic-bert) - Scam Classification      │

│  • Keyword Matching (UPI, OTP, bank, police, arrest)           │

│  • Language Detection (langdetect) - English/Hindi             │

│  • Confidence Scoring (>0.7 = scam trigger)                    │

└─────────────────────────────────────────────────────────────────┘

                              ↓

┌─────────────────────────────────────────────────────────────────┐

│                  HAND-OFF DECISION                              │

│  IF scam_confidence > 0.7:                                      │

│     → Trigger Honeypot Engagement                              │

│  ELSE:                                                          │

│     → Return "not_scam" response                               │

└─────────────────────────────────────────────────────────────────┘

                              ↓

┌─────────────────────────────────────────────────────────────────┐

│               AGENTIC ENGAGEMENT MODULE                         │

│  Framework: LangGraph + ReAct Loop                             │

│  LLM: Groq Llama 3.1 70B (FREE API, 30 req/min)               │

│                                                                 │

│  Agent Components:                                              │

│  ├─ Persona Generator (elderly/gullible/confused)              │

│  ├─ Response Planner (stalling tactics, probing questions)     │

│  ├─ Context Tracker (conversation state in ChromaDB)           │

│  ├─ Safety Monitor (avoid escalation)                          │

│  └─ Termination Logic (max 20 turns or intel extracted)        │

│                                                                 │

│  Engagement Strategy:                                           │

│  • Turn 1-5: Show interest, ask clarifying questions           │

│  • Turn 6-12: Express confusion, request details repeatedly    │

│  • Turn 13-20: Probe for bank/UPI/links with urgency          │

└─────────────────────────────────────────────────────────────────┘

                              ↓

┌─────────────────────────────────────────────────────────────────┐

│            INTELLIGENCE EXTRACTION MODULE                       │

│  • NER: spaCy (en_core_web_sm) for entities                    │

│  • Regex Patterns:                                              │

│    - UPI: [a-zA-Z0-9._]+@[a-zA-Z]+                            │

│    - Bank Account: \d{9,18}                                    │

│    - IFSC: [A-Z]{4}0[A-Z0-9]{6}                               │

│    - Phone: \+91[\s-]?\d{10}|\d{10}                           │

│    - URLs: https?://[^\s]+                                     │

│  • Confidence Scoring per entity (0.0-1.0)                     │

│  • Validation: Check format correctness                        │

└─────────────────────────────────────────────────────────────────┘

                              ↓

┌─────────────────────────────────────────────────────────────────┐

│                  OUTPUT LAYER (JSON)                            │

│  {                                                              │

│    "scam_detected": true,                                       │

│    "confidence": 0.95,                                          │

│    "language": "hindi",                                         │

│    "conversation_transcript": [...],                            │

│    "extracted_intelligence": {                                  │

│      "upi_ids": ["scammer@paytm"],                             │

│      "bank_accounts": ["1234567890"],                          │

│      "ifsc_codes": ["SBIN0001234"],                            │

│      "phone_numbers": ["+919876543210"],                       │

│      "phishing_links": ["http://fake-bank.com"]                │

│    },                                                           │

│    "engagement_turns": 15,                                      │

│    "extraction_confidence": 0.87                                │

│  }                                                              │

└─────────────────────────────────────────────────────────────────┘

```

---

## TECH STACK (100% FREE TIER)

### **1. Core AI/ML Models**

| Component | Model/Library | Source | Free Tier Limits | Why Chosen |
|-----------|--------------|--------|------------------|------------|
| **LLM (Agentic Core)** | Groq Llama 3.1 70B | Groq Cloud API | 30 req/min, 6000/day | Fastest inference (280 tokens/sec), excellent Hindi support |
| **Scam Detection** | ai4bharat/indic-bert | Hugging Face | Unlimited (local) | Best for Hindi-English code-mixed text |
| **NER Extraction** | en_core_web_sm | spaCy | Unlimited (local) | Fast, accurate entity recognition |

| **Language Detection** | langdetect | PyPI | Unlimited (local) | 99%+ accuracy for Hindi/English |

| **Embeddings** | sentence-transformers/all-MiniLM-L6-v2 | Hugging Face | Unlimited (local) | Lightweight, 384-dim embeddings |



### **2. Agentic AI Framework**



```python

# LangGraph + LangChain (Open Source)

langgraph==0.0.20        # State graph orchestration

langchain==0.1.0         # ReAct agent framework

langchain-groq==0.0.1    # Groq LLM integration

```



**Why LangGraph:**

- Built-in state persistence (conversation memory)

- ReAct loop support (Reason → Act → Observe)

- Conditional branching for dynamic engagement

- Multi-turn conversation handling

- Free and open-source



### **3. Vector Database & Storage**



| Component | Tool | Free Tier | Purpose |

|-----------|------|-----------|---------|

| **Vector DB** | ChromaDB | Unlimited (local) | Store conversation embeddings, scam patterns |

| **Relational DB** | PostgreSQL | 1GB (Supabase free) | Conversation logs, scammer profiles |

| **Cache** | Redis | 30MB (Redis Cloud free) | Real-time state, session management |



### **4. API Framework**



```python

# FastAPI + Production Tools

fastapi==0.104.1         # High-performance API

uvicorn==0.24.0          # ASGI server

pydantic==2.5.0          # Data validation

```



### **5. Supporting Libraries**



```python

# NLP & Text Processing

spacy==3.7.2

transformers==4.35.0

torch==2.1.0

sentence-transformers==2.2.2

langdetect==1.0.9



# Vector & Data Storage

chromadb==0.4.18

psycopg2-binary==2.9.9

redis==5.0.1

sqlalchemy==2.0.23



# Utils

python-dotenv==1.0.0

requests==2.31.0

numpy==1.24.3

pandas==2.0.3

```



---



## API ENDPOINT SPECIFICATION



### **1. Competition Submission Endpoint**



**Base URL:** `https://your-api-domain.com/api/v1`



**Endpoint:** `POST /honeypot/engage`



**Request Format:**

```json

{

  "message": "आप जीत गए हैं 10 लाख रुपये! अपना OTP शेयर करें।",

  "session_id": "optional-session-123",
  "language": "auto"
}
```



**Response Format (Scam Detected):**

```json

{

  "status": "success",

  "scam_detected": true,

  "confidence": 0.92,

  "language_detected": "hindi",

  "session_id": "session-123",

  "engagement": {

    "agent_response": "वाह! बहुत अच्छी खबर है। मुझे OTP कहाँ भेजना है?",

    "turn_count": 1,

    "max_turns_reached": false,

    "strategy": "show_interest"

  },

  "extracted_intelligence": {

    "upi_ids": [],

    "bank_accounts": [],

    "ifsc_codes": [],

    "phone_numbers": [],

    "phishing_links": [],

    "extraction_confidence": 0.0

  },

  "conversation_history": [

    {

      "turn": 1,

      "sender": "scammer",

      "message": "आप जीत गए हैं 10 लाख रुपये! अपना OTP शेयर करें।",

      "timestamp": "2026-01-26T10:30:00Z"

    },

    {

      "turn": 1,

      "sender": "agent",

      "message": "वाह! बहुत अच्छी खबर है। मुझे OTP कहाँ भेजना है?",

      "timestamp": "2026-01-26T10:30:02Z"

    }

  ],

  "metadata": {

    "processing_time_ms": 850,

    "model_version": "v1.0.0",

    "detection_model": "indic-bert",

    "engagement_model": "groq-llama-3.1-70b"

  }

}

```

**Response Format (Not Scam):**
```json

{

  "status": "success",

  "scam_detected": false,

  "confidence": 0.15,

  "language_detected": "english",

  "session_id": "session-456",

  "message": "No scam detected. Message appears legitimate."

}

```

### **2. Mock Scammer API Integration**

**How Competition Testing Works:**
1. Competition provides Mock Scammer API endpoint
2. Your system detects scam → sends engagement response
3. Mock Scammer API replies → your system continues conversation
4. Loop continues until intelligence extracted or max turns
5. Your API returns final JSON with extracted data

**Integration Architecture:**
```python

# Your API receives initial message

POST /honeypot/engage

{

  "message": "Send money to UPI: scammer@paytm",

  "mock_scammer_callback": "https://competition-api.com/scammer/reply"

}



# Your system detects scam, engages

# For each turn, call Mock Scammer API:

POST https://competition-api.com/scammer/reply

{

  "session_id": "xyz",

  "agent_message": "Which UPI ID should I use?"

}



# Mock Scammer responds

{

  "scammer_reply": "Use scammer@paytm and send 5000 rupees"

}



# Your system extracts: upi_ids=["scammer@paytm"], continues or terminates

```

### **3. Additional Testing Endpoints**

```python

# Health Check

GET /health

Response: {"status": "healthy", "version": "1.0.0"}



# Batch Processing (if needed)

POST /honeypot/batch

{

  "messages": [

    {"id": "1", "message": "..."},

    {"id": "2", "message": "..."}

  ]

}



# Get Conversation History

GET /honeypot/session/{session_id}

Response: {conversation history JSON}

```

---

## MULTILINGUAL SUPPORT (ENGLISH + HINDI)

### **Language Detection Pipeline**

```python

# Step 1: Detect language

import langdetect

detected_lang = langdetect.detect(message)  # 'en' or 'hi'



# Step 2: Route to appropriate processing

if detected_lang == 'hi':

    # Use IndicBERT for detection

    # Use Hindi persona prompts for engagement

    # Apply Hindi regex patterns

elif detected_lang == 'en':

    # Use IndicBERT (supports English too)

    # Use English persona prompts

    # Apply English regex patterns

```

### **Hindi Support Specifications**

**Models:**
- **Detection:** `ai4bharat/indic-bert` (pre-trained on 12 Indic languages)
- **LLM:** Groq Llama 3.1 70B (strong Hindi capabilities)
- **Alternative:** Gemma-2-9B-it (good Hindi, can run locally)

**Hindi Regex Patterns:**
```python

# Hindi text patterns

HINDI_UPI_KEYWORDS = ['भेजें', 'ट्रांसफर', 'पैसे', 'यूपीआई', 'खाता']

HINDI_SCAM_KEYWORDS = ['जीत', 'ईनाम', 'लॉटरी', 'ओटीपी', 'पुलिस', 'गिरफ्तार']



# Numeric patterns work same (0-9 digits in Hindi text)

UPI_PATTERN = r'[a-zA-Z0-9._]+@[a-zA-Z]+'

ACCOUNT_PATTERN = r'\d{9,18}'

```

**Hindi Persona Examples:**
```

Persona 1 (Elderly):

"अरे वाह! बहुत अच्छा है। लेकिन मुझे समझ नहीं आ रहा, कैसे करूँ?"



Persona 2 (Confused):

"जी हाँ, मैं पैसे भेज दूंगा। पर कौन सा बटन दबाऊं?"



Persona 3 (Eager):

"हाँ हाँ, मुझे पैसे चाहिए। आप कहाँ भेजूं?"

```

### **English Support Specifications**

**Models:**
- Same as Hindi (IndicBERT is multilingual)
- Groq Llama 3.1 70B (native English)

**English Persona Examples:**
```

Persona 1 (Elderly):

"Oh wonderful! But I'm not very good with technology. Can you help me?"



Persona 2 (Confused):

"I want to claim my prize. Where do I send the money again?"



Persona 3 (Eager):

"Yes, I'm ready to transfer. What's your account number?"

```

### **Code-Mixed (Hinglish) Support**

Many Indian scams use code-mixed Hindi-English. IndicBERT handles this well:

```

Input: "Aapne jeeta 10 lakh rupees! Send OTP to claim prize"

Language: hinglish (auto-detected as 'hi' or 'en')

Processing: IndicBERT detects scam patterns in mixed text

Engagement: Respond in same mixing pattern

```

---

## AGENTIC ENGAGEMENT STRATEGY

### **LangGraph ReAct Agent Architecture**

```python

from langgraph.graph import StateGraph, END

from langchain_groq import ChatGroq



# State Definition

class HoneypotState(TypedDict):

    messages: List[dict]

    scam_confidence: float

    turn_count: int

    extracted_intel: dict

    strategy: str

    language: str



# Agent Nodes

def detect_scam(state):

    """Classify if message is scam"""

    # IndicBERT classification

    # Return updated state with confidence



def plan_response(state):

    """Decide engagement strategy"""

    if state['turn_count'] < 5:

        strategy = "show_interest"

    elif state['turn_count'] < 12:

        strategy = "express_confusion"

    else:

        strategy = "probe_details"

    return {"strategy": strategy}



def generate_response(state):

    """LLM generates believable reply"""

    # Groq Llama 3.1 with persona prompt

    # Returns agent message



def extract_intelligence(state):

    """Extract financial details"""

    # spaCy NER + Regex

    # Update extracted_intel



def should_continue(state):

    """Termination logic"""

    if state['turn_count'] >= 20:

        return "end"

    if len(state['extracted_intel']['upi_ids']) > 0:

        return "end"

    return "continue"



# Build Graph

workflow = StateGraph(HoneypotState)

workflow.add_node("detect", detect_scam)

workflow.add_node("plan", plan_response)

workflow.add_node("generate", generate_response)

workflow.add_node("extract", extract_intelligence)



workflow.add_edge("detect", "plan")

workflow.add_edge("plan", "generate")

workflow.add_edge("generate", "extract")

workflow.add_conditional_edges(

    "extract",

    should_continue,

    {

        "continue": "plan",

        "end": END

    }

)



workflow.set_entry_point("detect")

agent = workflow.compile()

```

### **Persona Management**

**Persona Types:**
1. **Elderly Person (60+ years)**
   - Slow to understand technology
   - Trusting and polite
   - Asks basic questions
   - Expresses confusion often

2. **Middle-Aged Eager Victim**
   - Excited about prizes/offers
   - Willing to comply
   - Asks for step-by-step instructions
   - Shows urgency

3. **Young Confused User**
   - Familiar with tech but cautious
   - Asks verification questions
   - Requests proof/links
   - Seeks reassurance

**Persona Selection Logic:**
```python

def select_persona(language, scam_type):

    if "prize" in scam_type or "lottery" in scam_type:

        return "eager_victim"

    elif "police" in scam_type or "arrest" in scam_type:

        return "elderly_fearful"

    else:

        return "confused_user"

```

### **Stalling Tactics**

**Goal:** Keep scammer engaged to extract more information

**Tactics:**
1. **Repeated Clarification:** "I didn't understand, can you repeat?"
2. **Technical Confusion:** "Which button do I press? My phone is old."
3. **Fake Delays:** "Let me find my card. Hold on..."
4. **Partial Compliance:** "I sent something, did you receive?"
5. **Request Verification:** "Can you send me official proof?"

**Turn-by-Turn Strategy:**
```python

ENGAGEMENT_STRATEGY = {

    "turns_1_5": {

        "goal": "Build trust, show interest",

        "tactics": ["express_excitement", "ask_basic_questions"],

        "example": "Really? I won? How do I claim it?"

    },

    "turns_6_12": {

        "goal": "Extract contact/payment info",

        "tactics": ["request_details", "express_confusion"],

        "example": "Should I send money to your account? What's the number?"

    },

    "turns_13_20": {

        "goal": "Force reveal of bank/UPI/links",

        "tactics": ["fake_compliance", "probe_urgently"],

        "example": "I'm ready to transfer. Send me your UPI ID again?"

    }

}

```

---

## INTELLIGENCE EXTRACTION

### **Extraction Targets (Competition Requirements)**

1. **UPI IDs:** `user@paytm`, `9876543210@ybl`, etc.
2. **Bank Account Numbers:** 9-18 digit sequences
3. **IFSC Codes:** 11-character bank codes
4. **Phone Numbers:** +91 or 10-digit Indian numbers
5. **Phishing Links:** URLs to fake websites

### **Extraction Pipeline**

```python

import spacy

import re



nlp = spacy.load("en_core_web_sm")



def extract_intelligence(text):

    intel = {

        "upi_ids": [],

        "bank_accounts": [],

        "ifsc_codes": [],

        "phone_numbers": [],

        "phishing_links": []

    }

    

    # UPI IDs

    upi_pattern = r'\b[a-zA-Z0-9._-]+@[a-zA-Z]+\b'

    intel['upi_ids'] = re.findall(upi_pattern, text)

    

    # Bank Accounts (9-18 digits, with validation)

    account_pattern = r'\b\d{9,18}\b'

    accounts = re.findall(account_pattern, text)

    intel['bank_accounts'] = [acc for acc in accounts if validate_account(acc)]

    

    # IFSC Codes

    ifsc_pattern = r'\b[A-Z]{4}0[A-Z0-9]{6}\b'

    intel['ifsc_codes'] = re.findall(ifsc_pattern, text)

    

    # Phone Numbers

    phone_pattern = r'(?:\+91[\s-]?)?[6-9]\d{9}\b'

    intel['phone_numbers'] = re.findall(phone_pattern, text)

    

    # Phishing Links

    url_pattern = r'https?://[^\s<>"{}|\\^`\[\]]+'

    intel['phishing_links'] = re.findall(url_pattern, text)

    

    # SpaCy NER for additional entities

    doc = nlp(text)

    for ent in doc.ents:

        if ent.label_ == "CARDINAL" and len(ent.text) >= 9:

            # Possible account number

            if ent.text not in intel['bank_accounts']:

                intel['bank_accounts'].append(ent.text)

    

    # Calculate confidence

    confidence = calculate_extraction_confidence(intel)

    

    return intel, confidence



def validate_account(account_number):

    """Basic validation for bank account"""

    if len(account_number) < 9 or len(account_number) > 18:

        return False

    # Add checksum validation if needed

    return True



def calculate_extraction_confidence(intel):

    """Score based on number and quality of extractions"""

    score = 0

    weights = {

        'upi_ids': 0.3,

        'bank_accounts': 0.3,

        'ifsc_codes': 0.2,

        'phone_numbers': 0.1,

        'phishing_links': 0.1

    }

    

    for key, weight in weights.items():

        if len(intel[key]) > 0:

            score += weight

    

    return min(score, 1.0)

```

### **Hindi Text Extraction Challenges**

**Challenge:** Numbers in Hindi text (Devanagari script: ०१२३...)
**Solution:** Devanagari digits to ASCII conversion

```python

def convert_devanagari_to_ascii(text):

    """Convert Devanagari digits to ASCII"""

    devanagari_to_ascii = {

        '०': '0', '१': '1', '२': '2', '३': '3', '४': '4',

        '५': '5', '६': '6', '७': '7', '८': '8', '९': '9'

    }

    for dev, asc in devanagari_to_ascii.items():

        text = text.replace(dev, asc)

    return text



# Apply before extraction

text = convert_devanagari_to_ascii(hindi_text)

intel = extract_intelligence(text)

```

---

## DATABASE & STATE MANAGEMENT

### **PostgreSQL Schema**

```sql

-- Conversations Table

CREATE TABLE conversations (

    id SERIAL PRIMARY KEY,

    session_id VARCHAR(255) UNIQUE NOT NULL,

    language VARCHAR(10) NOT NULL,

    scam_detected BOOLEAN DEFAULT FALSE,

    confidence FLOAT,

    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,

    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP

);



-- Messages Table

CREATE TABLE messages (

    id SERIAL PRIMARY KEY,

    conversation_id INTEGER REFERENCES conversations(id),

    turn_number INTEGER NOT NULL,

    sender VARCHAR(50) NOT NULL, -- 'scammer' or 'agent'

    message TEXT NOT NULL,

    timestamp TIMESTAMP DEFAULT CURRENT_TIMESTAMP

);



-- Extracted Intelligence Table

CREATE TABLE extracted_intelligence (

    id SERIAL PRIMARY KEY,

    conversation_id INTEGER REFERENCES conversations(id),

    upi_ids TEXT[], -- PostgreSQL array

    bank_accounts TEXT[],

    ifsc_codes TEXT[],

    phone_numbers TEXT[],

    phishing_links TEXT[],

    extraction_confidence FLOAT,

    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP

);



-- Scammer Profiles (for analytics)

CREATE TABLE scammer_profiles (

    id SERIAL PRIMARY KEY,

    phone_hash VARCHAR(64), -- Hashed for privacy

    scam_tactics TEXT[],

    languages_used TEXT[],

    total_conversations INTEGER DEFAULT 1,

    first_seen TIMESTAMP DEFAULT CURRENT_TIMESTAMP,

    last_seen TIMESTAMP DEFAULT CURRENT_TIMESTAMP

);

```

### **ChromaDB for Vector Storage**

```python

import chromadb

from sentence_transformers import SentenceTransformer



# Initialize

client = chromadb.Client()

collection = client.create_collection("scam_conversations")

embedder = SentenceTransformer('all-MiniLM-L6-v2')



# Store conversation embeddings

def store_conversation(session_id, messages):

    # Combine messages into single text

    full_text = " ".join([msg['message'] for msg in messages])

    

    # Generate embedding

    embedding = embedder.encode(full_text)

    

    # Store in ChromaDB

    collection.add(

        embeddings=[embedding.tolist()],

        documents=[full_text],

        ids=[session_id],

        metadatas=[{

            "session_id": session_id,

            "turn_count": len(messages),

            "language": messages[0].get('language', 'unknown')

        }]

    )



# Query similar conversations (for learning)

def find_similar_scams(query_text, n_results=5):

    query_embedding = embedder.encode(query_text)

    results = collection.query(

        query_embeddings=[query_embedding.tolist()],

        n_results=n_results

    )

    return results

```

### **Redis for Session State**

```python

import redis

import json



# Initialize Redis

redis_client = redis.Redis(

    host='redis-free-tier.cloud.redislabs.com',

    port=12345,

    password='your-password',

    decode_responses=True

)



# Store session state

def save_session_state(session_id, state):

    redis_client.setex(

        f"session:{session_id}",

        3600,  # 1 hour expiry

        json.dumps(state)

    )



# Retrieve session state

def get_session_state(session_id):

    data = redis_client.get(f"session:{session_id}")

    return json.loads(data) if data else None



# Update turn count

def increment_turn(session_id):

    redis_client.incr(f"session:{session_id}:turns")

```

---

## DEPLOYMENT ARCHITECTURE

### **Free Tier Hosting Options**

| Service | Free Tier | Best For | Limits |
|---------|-----------|----------|--------|
| **Render** | 750 hours/month | FastAPI deployment | Sleep after 15min inactivity |
| **Railway** | $5 credit/month | PostgreSQL + API | 500 hours |
| **Fly.io** | 3 shared VMs | Low-latency API | 160GB transfer/month |
| **Supabase** | 500MB PostgreSQL | Database | 2GB transfer/month |
| **Redis Cloud** | 30MB Redis | Cache/sessions | 30 connections |

### **Recommended Stack for Competition**

```

API Server: Render (or Railway)

├─ FastAPI application

├─ Uvicorn ASGI server

├─ 512MB RAM, 0.1 CPU

└─ Environment: Python 3.11



Database: Supabase PostgreSQL

├─ 500MB storage

├─ 2GB transfer/month

└─ Connection pooling



Cache: Redis Cloud

├─ 30MB storage

├─ Session state management

└─ 30 concurrent connections



Vector DB: ChromaDB (Local)

├─ Embedded in API server

├─ Persistent storage in Docker volume

└─ No external service needed



Model Hosting: Hugging Face (Local)

├─ IndicBERT loaded at startup

├─ spaCy models bundled

└─ 2GB disk space for models



LLM API: Groq Cloud

├─ 30 requests/minute

├─ 6000 requests/day

└─ Zero cost

```

### **Docker Configuration**

```dockerfile

# Dockerfile

FROM python:3.11-slim



WORKDIR /app



# Install system dependencies

RUN apt-get update && apt-get install -y \

    build-essential \

    && rm -rf /var/lib/apt/lists/*



# Copy requirements

COPY requirements.txt .

RUN pip install --no-cache-dir -r requirements.txt



# Download models at build time

RUN python -c "from transformers import AutoModel, AutoTokenizer; \

    AutoModel.from_pretrained('ai4bharat/indic-bert'); \

    AutoTokenizer.from_pretrained('ai4bharat/indic-bert')"

RUN python -m spacy download en_core_web_sm



# Copy application code

COPY . .



# Expose port

EXPOSE 8000



# Run application

CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]

```

```yaml

# docker-compose.yml (for local testing)

version: '3.8'



services:

  api:

    build: .

    ports:

      - "8000:8000"

    environment:

      - GROQ_API_KEY=${GROQ_API_KEY}

      - POSTGRES_URL=${POSTGRES_URL}

      - REDIS_URL=${REDIS_URL}

    volumes:

      - chromadb_data:/app/chromadb

    depends_on:

      - postgres

      - redis



  postgres:

    image: postgres:15

    environment:

      - POSTGRES_DB=scamshield

      - POSTGRES_USER=admin

      - POSTGRES_PASSWORD=securepass

    volumes:

      - postgres_data:/var/lib/postgresql/data



  redis:

    image: redis:7-alpine

    volumes:

      - redis_data:/data



volumes:

  chromadb_data:

  postgres_data:

  redis_data:

```

---

## GROQ API INTEGRATION

### **Setup & Configuration**

```python

# .env file

GROQ_API_KEY=gsk_your_free_api_key_here

GROQ_MODEL=llama-3.1-70b-versatile



# config.py

import os

from dotenv import load_dotenv



load_dotenv()



GROQ_API_KEY = os.getenv("GROQ_API_KEY")

GROQ_MODEL = os.getenv("GROQ_MODEL", "llama-3.1-70b-versatile")

GROQ_TEMPERATURE = 0.7

GROQ_MAX_TOKENS = 500

GROQ_TIMEOUT = 30

```

### **LangChain Integration**

```python

from langchain_groq import ChatGroq

from langchain.prompts import ChatPromptTemplate



# Initialize Groq LLM

llm = ChatGroq(

    model=GROQ_MODEL,

    api_key=GROQ_API_KEY,

    temperature=GROQ_TEMPERATURE,

    max_tokens=GROQ_MAX_TOKENS

)



# Persona Prompts

ELDERLY_HINDI_PROMPT = """

आप एक 65 वर्षीय व्यक्ति हैं जो टेक्नोलॉजी में बहुत अच्छे नहीं हैं।

आप विनम्र और भरोसेमंद हैं। आप अक्सर सवाल पूछते हैं और भ्रमित होते हैं।



आपका लक्ष्य: घोटालेबाज से बैंक डिटेल्स, UPI ID, या लिंक निकालना, लेकिन 

असली व्यक्ति की तरह व्यवहार करना।



बातचीत का इतिहास:

{conversation_history}



घोटालेबाज का संदेश: {scammer_message}



आपका जवाब (केवल एक संदेश, 1-2 वाक्य):

"""



ELDERLY_ENGLISH_PROMPT = """

You are a 65-year-old person who is not tech-savvy.

You are polite, trusting, and often confused about technology.



Your goal: Extract bank details, UPI IDs, or phishing links from the scammer

while acting like a real elderly person.



Conversation history:

{conversation_history}



Scammer's message: {scammer_message}



Your response (only one message, 1-2 sentences):

"""



# Generate response

def generate_agent_response(language, persona, conversation_history, scammer_message):

    if language == "hindi":

        prompt_template = ELDERLY_HINDI_PROMPT

    else:

        prompt_template = ELDERLY_ENGLISH_PROMPT

    

    prompt = ChatPromptTemplate.from_template(prompt_template)

    chain = prompt | llm

    

    response = chain.invoke({

        "conversation_history": format_conversation(conversation_history),

        "scammer_message": scammer_message

    })

    

    return response.content



def format_conversation(history):

    """Format conversation for prompt"""

    formatted = []

    for msg in history[-5:]:  # Last 5 turns for context

        sender = "Scammer" if msg['sender'] == 'scammer' else "You"

        formatted.append(f"{sender}: {msg['message']}")

    return "\n".join(formatted)

```

### **Rate Limiting & Retry Logic**

```python

import time

from functools import wraps



def rate_limited_groq_call(max_retries=3, backoff=2):

    """Decorator for handling Groq rate limits"""

    def decorator(func):

        @wraps(func)

        def wrapper(*args, **kwargs):

            for attempt in range(max_retries):

                try:

                    return func(*args, **kwargs)

                except Exception as e:

                    if "rate_limit" in str(e).lower():

                        wait_time = backoff ** attempt

                        print(f"Rate limited. Waiting {wait_time}s...")

                        time.sleep(wait_time)

                    else:

                        raise e

            raise Exception("Max retries exceeded")

        return wrapper

    return decorator



@rate_limited_groq_call(max_retries=3)

def call_groq_api(messages):

    """Safe Groq API call with retry"""

    return llm.invoke(messages)

```

---

## EVALUATION METRICS

### **Competition Judging Criteria (Predicted)**

Based on Challenge 2 requirements, judges will likely evaluate:

1. **Scam Detection Accuracy (25%)**
   - True Positive Rate (detecting actual scams)
   - False Positive Rate (avoiding false alarms)
   - Target: >90% accuracy

2. **Engagement Quality (25%)**
   - Naturalness of conversation (believable persona)
   - Number of turns sustained
   - Avoidance of detection by scammer
   - Target: >10 turns average

3. **Intelligence Extraction (30%)**
   - UPI IDs extracted correctly
   - Bank accounts extracted correctly
   - Phishing links identified
   - Extraction accuracy (no false positives)
   - Target: >85% precision, >80% recall

4. **Response Time (10%)**
   - API latency
   - Time to extract intelligence
   - Target: <2s per response

5. **System Robustness (10%)**
   - Handle edge cases (empty messages, very long texts)
   - Error handling
   - API availability

### **Testing Framework**

```python

# test_metrics.py

import pytest

from app.honeypot import HoneypotAgent



def test_scam_detection_accuracy():

    """Test detection accuracy on known scam messages"""

    test_cases = [

        {

            "message": "You won 10 lakh! Send OTP to claim.",

            "expected_scam": True,

            "expected_confidence": 0.9

        },

        {

            "message": "Hi, how are you doing today?",

            "expected_scam": False,

            "expected_confidence": 0.1

        },

        # Add 100+ test cases

    ]

    

    agent = HoneypotAgent()

    correct = 0

    

    for case in test_cases:

        result = agent.detect_scam(case["message"])

        if result["scam_detected"] == case["expected_scam"]:

            correct += 1

    

    accuracy = correct / len(test_cases)

    assert accuracy >= 0.90, f"Accuracy {accuracy} below 90% threshold"



def test_intelligence_extraction():

    """Test extraction accuracy"""

    test_text = """

    Please send 5000 rupees to my UPI: scammer@paytm

    My bank account is 1234567890123 with IFSC SBIN0001234

    Call me at +919876543210 or visit http://fake-bank.com

    """

    

    agent = HoneypotAgent()

    result = agent.extract_intelligence(test_text)

    

    assert "scammer@paytm" in result["upi_ids"]

    assert "1234567890123" in result["bank_accounts"]

    assert "SBIN0001234" in result["ifsc_codes"]

    assert "+919876543210" in result["phone_numbers"]

    assert "http://fake-bank.com" in result["phishing_links"]



def test_response_latency():

    """Test API response time"""

    import time

    agent = HoneypotAgent()

    

    start = time.time()

    result = agent.engage("Send money to win prize!")

    latency = time.time() - start

    

    assert latency < 2.0, f"Latency {latency}s exceeds 2s threshold"

```

### **Monitoring Dashboard**

```python

# metrics.py

from prometheus_client import Counter, Histogram, Gauge



# Define metrics

scam_detection_total = Counter(

    'scam_detection_total',

    'Total number of scam detections',

    ['language', 'result']

)



intelligence_extracted = Counter(

    'intelligence_extracted_total',

    'Total pieces of intelligence extracted',

    ['type']  # upi, bank_account, etc.

)



response_time = Histogram(

    'response_time_seconds',

    'Response time in seconds',

    buckets=[0.1, 0.5, 1.0, 2.0, 5.0]

)



active_sessions = Gauge(

    'active_honeypot_sessions',

    'Number of active honeypot sessions'

)



# Use in code

scam_detection_total.labels(language='hindi', result='scam').inc()

intelligence_extracted.labels(type='upi_id').inc()

response_time.observe(1.2)

```

---

## PHASE 2: AUDIO INTEGRATION (POST-TEXT IMPLEMENTATION)

**Note:** Only proceed with Phase 2 after Phase 1 is fully tested and working.

### **Phase 2 Additions**

```python

# Additional requirements for Phase 2

openai-whisper==20231117   # ASR for audio transcription

torchaudio==2.1.0          # Audio processing

librosa==0.10.1            # Audio features

soundfile==0.12.1          # Audio I/O

pydub==0.25.1              # Audio format conversion

```

### **Audio Endpoint**

```python

# POST /honeypot/engage-audio

# Accept: multipart/form-data or JSON with base64 audio



@app.post("/honeypot/engage-audio")

async def engage_audio(audio_file: UploadFile):

    # Step 1: Save audio temporarily

    temp_path = f"/tmp/{audio_file.filename}"

    with open(temp_path, "wb") as f:

        f.write(await audio_file.read())

    

    # Step 2: Transcribe with Whisper

    import whisper

    model = whisper.load_model("base")

    result = model.transcribe(temp_path, language="hi")  # or "en"

    transcribed_text = result["text"]

    detected_language = result["language"]

    

    # Step 3: Process as text (reuse Phase 1 pipeline)

    response = await engage_text({

        "message": transcribed_text,

        "language": detected_language,

        "source": "audio"

    })

    

    # Step 4: Add audio-specific metadata

    response["audio_metadata"] = {

        "original_filename": audio_file.filename,

        "transcription": transcribed_text,

        "detected_language": detected_language,

        "transcription_confidence": result.get("confidence", 1.0)

    }

    

    return response

```

### **Audio-Specific Scam Detection**

```python

# Voice deepfake detection (Phase 2 only)

from resemblyzer import preprocess_wav, VoiceEncoder



encoder = VoiceEncoder()



def detect_synthetic_voice(audio_path):

    """Detect if voice is AI-generated"""

    wav = preprocess_wav(audio_path)

    embed = encoder.embed_utterance(wav)

    

    # Compare against known synthetic voice embeddings

    # Return confidence score

    

    return {

        "is_synthetic": False,  # Placeholder

        "confidence": 0.95

    }

```

---

## RESPONSIBLE AI & COMPLIANCE

### **Privacy & Data Protection**

**DPDP Act 2023 Compliance:**
1. **Consent:** User must opt-in to honeypot engagement
2. **Data Minimization:** Store only essential data
3. **Anonymization:** Hash PII (phone numbers, etc.)
4. **Retention:** Delete logs after 30 days
5. **Right to Erasure:** Provide deletion API

```python

import hashlib



def anonymize_phone(phone_number):

    """Hash phone numbers for privacy"""

    return hashlib.sha256(phone_number.encode()).hexdigest()



def schedule_data_deletion(session_id, days=30):

    """Schedule automatic data deletion"""

    deletion_date = datetime.now() + timedelta(days=days)

    # Store in deletion_queue table

    db.execute("""

        INSERT INTO deletion_queue (session_id, deletion_date)

        VALUES (%s, %s)

    """, (session_id, deletion_date))

```

### **Safety Guidelines**

**Agent Behavior Rules:**
1. **No Escalation:** Never threaten or provoke scammer
2. **No Personal Info:** Never share real personal details
3. **No Financial Transactions:** Never actually transfer money
4. **Termination:** End conversation if scammer becomes violent
5. **Legal Compliance:** Ensure honeynet operations are legal

```python

def safety_check(agent_message):

    """Ensure agent response is safe"""

    unsafe_patterns = [

        r'I will kill',

        r'real address',

        r'my actual bank',

        # Add more unsafe patterns

    ]

    

    for pattern in unsafe_patterns:

        if re.search(pattern, agent_message, re.IGNORECASE):

            return False, "Unsafe content detected"

    

    return True, "Safe"

```

### **Bias Mitigation**

**Addressing Potential Biases:**
1. **Language Bias:** Equal performance for Hindi and English
2. **Dialect Bias:** Test on multiple Indian accents
3. **Age Bias:** Personas represent diverse age groups
4. **Regional Bias:** Test on North and South Indian scam patterns

```python

def test_language_fairness():

    """Ensure equal accuracy across languages"""

    hindi_accuracy = evaluate_on_dataset("hindi_test_set")

    english_accuracy = evaluate_on_dataset("english_test_set")

    

    difference = abs(hindi_accuracy - english_accuracy)

    assert difference < 0.05, "Language bias detected"

```

---

## WINNING STRATEGY

### **What Makes This Solution Top 10 Material**

1. **Technical Excellence (40%)**
   - ✅ Production-grade LangGraph architecture
   - ✅ State-of-the-art models (IndicBERT, Llama 3.1)
   - ✅ Robust state management (PostgreSQL + Redis + ChromaDB)
   - ✅ Free tier deployment (cost-effective)

2. **Innovation (30%)**
   - ✅ Multi-turn agentic engagement (beyond simple detection)
   - ✅ Dynamic persona adaptation
   - ✅ Intelligent stalling tactics
   - ✅ Real-time intelligence extraction

3. **India-Specific (20%)**
   - ✅ Hindi + English bilingual support
   - ✅ UPI/IFSC/Indian bank patterns
   - ✅ Local scam tactics knowledge
   - ✅ Cultural context in personas

4. **Execution Quality (10%)**
   - ✅ Clean API design
   - ✅ Comprehensive documentation
   - ✅ Testing framework
   - ✅ Production deployment

### **Competition Day Checklist**

**Before Submission (Feb 4):**
- [ ] API deployed and publicly accessible
- [ ] Health check endpoint working
- [ ] Test with 100+ sample scam messages
- [ ] Verify JSON response format matches requirements
- [ ] Check response latency (<2s average)
- [ ] Ensure Groq API key has remaining credits
- [ ] Database backups configured
- [ ] Monitoring dashboard active
- [ ] Documentation complete
- [ ] Demo video recorded (if required)

**Submission Day (Feb 5):**
- [ ] Submit API endpoint URL
- [ ] Verify endpoint is reachable from external networks
- [ ] Monitor logs for incoming test requests
- [ ] Have fallback plan (backup deployment)
- [ ] Team available for support
- [ ] Response to any judge queries within 2 hours

### **Differentiation from Competitors**

Most participants will likely build:
- Simple rule-based detection (keyword matching only)
- Single-turn response (no multi-turn engagement)
- Basic regex extraction (no NER)
- No state management (stateless API)

**Your Edge:**
- ✅ **Agentic AI** with LangGraph (complex, adaptive)
- ✅ **Multi-turn engagement** (up to 20 turns)
- ✅ **State persistence** (remembers conversation)
- ✅ **Dynamic personas** (believable, adaptive)
- ✅ **Hybrid extraction** (NER + regex + validation)
- ✅ **Production architecture** (scalable, monitored)

---

## PROJECT STRUCTURE

```

scamshield-ai/

├── README.md

├── requirements.txt

├── Dockerfile

├── docker-compose.yml

├── .env.example

├── .gitignore

│

├── app/

│   ├── __init__.py

│   ├── main.py                    # FastAPI app

│   ├── config.py                  # Configuration

│   │

│   ├── api/

│   │   ├── __init__.py

│   │   ├── endpoints.py           # API routes

│   │   └── schemas.py             # Pydantic models

│   │

│   ├── models/

│   │   ├── __init__.py

│   │   ├── detector.py            # IndicBERT scam detection

│   │   ├── extractor.py           # Intelligence extraction

│   │   └── language.py            # Language detection

│   │

│   ├── agent/

│   │   ├── __init__.py

│   │   ├── honeypot.py            # LangGraph agent

│   │   ├── personas.py            # Persona definitions

│   │   ├── prompts.py             # LLM prompts

│   │   └── strategies.py          # Engagement strategies

│   │

│   ├── database/

│   │   ├── __init__.py

│   │   ├── postgres.py            # PostgreSQL connection

│   │   ├── redis_client.py        # Redis connection

│   │   ├── chromadb_client.py     # ChromaDB connection

│   │   └── models.py              # SQLAlchemy models

│   │

│   └── utils/

│       ├── __init__.py

│       ├── preprocessing.py       # Text preprocessing

│       ├── validation.py          # Input validation

│       ├── metrics.py             # Prometheus metrics

│       └── logger.py              # Logging configuration

│

├── tests/

│   ├── __init__.py

│   ├── test_detection.py

│   ├── test_extraction.py

│   ├── test_engagement.py

│   └── test_api.py

│

├── scripts/

│   ├── setup_models.py            # Download ML models

│   ├── init_database.py           # Initialize DB schema

│   └── test_deployment.py         # Deployment smoke tests

│

├── data/

│   ├── test_scam_messages.json    # Test dataset

│   ├── personas.json              # Persona definitions

│   └── scam_patterns.json         # Known scam patterns

│

└── docs/

    ├── API_DOCUMENTATION.md

    ├── DEPLOYMENT_GUIDE.md

    └── TESTING_GUIDE.md

```

---

## IMPLEMENTATION TIMELINE

### **Week 1 (Jan 26 - Feb 1): Core Development**

**Day 1-2: Project Setup**
- Initialize repository
- Setup virtual environment
- Install dependencies
- Configure PostgreSQL, Redis, ChromaDB
- Obtain Groq API key

**Day 3-4: Detection Module**
- Implement IndicBERT integration
- Build language detection
- Create keyword matching
- Test on sample messages

**Day 5-6: Agentic Module**
- Build LangGraph workflow
- Integrate Groq Llama 3.1
- Implement persona system
- Test engagement loop

**Day 7: Extraction Module**
- Implement spaCy NER
- Build regex patterns
- Create validation logic
- Test on sample extractions

### **Week 2 (Feb 2 - Feb 5): Testing & Deployment**

**Day 8: Integration**
- Connect all modules
- Build FastAPI endpoints
- Implement database operations
- End-to-end testing

**Day 9: Testing**
- Unit tests (80%+ coverage)
- Integration tests
- Load testing (100 req/min)
- Fix bugs

**Day 10: Deployment**
- Deploy to Render/Railway
- Configure environment variables
- Setup monitoring
- Test production endpoint

**Day 11: Buffer & Submission**
- Final testing
- Documentation review
- Submit API endpoint
- Monitor for test requests

---

## SUCCESS METRICS

### **Minimum Viable Product (MVP) Criteria**

**Must Have:**
- [x] Scam detection with >85% accuracy
- [x] Multi-turn engagement (at least 10 turns)
- [x] Extract at least 1 UPI ID or bank account
- [x] API response time <3s
- [x] Handle Hindi and English
- [x] Structured JSON output

**Should Have:**
- [x] >90% detection accuracy
- [x] 15+ turn average engagement
- [x] Extract 2+ intelligence types per conversation
- [x] API response time <2s
- [x] State persistence across sessions
- [x] Monitoring and metrics

**Nice to Have:**
- [ ] >95% detection accuracy
- [ ] 20 turn max engagement
- [ ] Extract all 5 intelligence types
- [ ] API response time <1s
- [ ] Advanced persona adaptation
- [ ] Voice deepfake detection (Phase 2)

---

## RISK MITIGATION

| Risk | Probability | Impact | Mitigation |
|------|-------------|--------|------------|
| **Groq API rate limits** | High | High | Implement retry logic, use backoff, cache responses |
| **Model loading time** | Medium | Medium | Load models at startup, not per request |
| **Database connection loss** | Low | High | Connection pooling, auto-reconnect, fallback to local storage |
| **Competition API changes** | Medium | High | Flexible schema design, comprehensive testing |
| **Deployment downtime** | Low | Critical | Multiple hosting options, health checks, auto-restart |
| **Hindi detection accuracy** | Medium | Medium | Extensive testing, fallback to English, hybrid approach |

---

## CONCLUSION

This specification provides a **complete, production-ready blueprint** for building a winning Agentic Honeypot System for the India AI Impact Buildathon 2026.

**Key Strengths:**
1. ✅ **100% Free Tier** - No cost barriers
2. ✅ **Phased Approach** - Text first, audio later
3. ✅ **Production Architecture** - Scalable, monitored, robust
4. ✅ **India-Specific** - Hindi support, local scam patterns
5. ✅ **Competition-Ready** - API-first, JSON outputs
6. ✅ **Technically Superior** - LangGraph, state management, multi-turn
7. ✅ **Well-Documented** - Clear implementation path

**Expected Ranking:** TOP 10 from 40,000 participants

**Next Steps:**
1. Begin implementation following project structure
2. Test continuously against test dataset
3. Deploy early to identify issues
4. Iterate based on testing feedback
5. Submit before deadline with confidence

**Team Focus:**
- Speed of execution (10 days remaining)
- Quality over features (MVP first)
- Testing, testing, testing
- Documentation for judges
- Monitoring for competition day

---

## APPENDIX

### **A. Sample API Requests/Responses**

See API ENDPOINT SPECIFICATION section above.

### **B. Groq API Key Setup**

1. Visit: https://console.groq.com/
2. Sign up with email
3. Navigate to API Keys section
4. Generate new API key
5. Free tier: 30 requests/minute, 6000/day

### **C. Supabase PostgreSQL Setup**

1. Visit: https://supabase.com/
2. Create account
3. New project → Select free tier
4. Copy connection string
5. Use in DATABASE_URL environment variable



### **D. Redis Cloud Setup**



1. Visit: https://redis.com/try-free/

2. Create account

3. New database → Free 30MB

4. Copy connection details

5. Use in REDIS_URL environment variable

### **E. Testing Commands**

```bash

# Run all tests

pytest tests/ -v



# Run specific test

pytest tests/test_detection.py::test_hindi_scam_detection



# Test API locally

curl -X POST http://localhost:8000/honeypot/engage \

  -H "Content-Type: application/json" \

  -d '{"message": "You won 10 lakh rupees!"}'



# Load test

locust -f tests/load_test.py --host http://localhost:8000

```

### **F. Deployment Commands**

```bash

# Build Docker image

docker build -t scamshield-ai .



# Run locally

docker-compose up



# Deploy to Render

git push render main



# Check logs

render logs --tail 100

```

---

**Document Version:** 1.0  
**Last Updated:** January 26, 2026  
**Status:** Ready for Implementation  
**Approved By:** Shivam Bhuva (Team Lead)

**For Questions/Support:**
- GitHub Issues: [Your Repo]
- Email: shivambhuva8866@gmail.com
- Team Channel: [Your Communication Channel]

---

**END OF DOCUMENT**