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:
- Detects scam messages accurately
- Actively engages scammers using believable personas
- Extracts intelligence: bank accounts, UPI IDs, phishing links
- Integrates with Mock Scammer API for testing
- 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
# 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
# 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
# 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:
{
"message": "आप जीत गए हैं 10 लाख रुपये! अपना OTP शेयर करें।",
"session_id": "optional-session-123",
"language": "auto"
}
Response Format (Scam Detected):
{
"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):
{
"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:
- Competition provides Mock Scammer API endpoint
- Your system detects scam → sends engagement response
- Mock Scammer API replies → your system continues conversation
- Loop continues until intelligence extracted or max turns
- Your API returns final JSON with extracted data
Integration Architecture:
# 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
# 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
# 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:
# 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
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:
Elderly Person (60+ years)
- Slow to understand technology
- Trusting and polite
- Asks basic questions
- Expresses confusion often
Middle-Aged Eager Victim
- Excited about prizes/offers
- Willing to comply
- Asks for step-by-step instructions
- Shows urgency
Young Confused User
- Familiar with tech but cautious
- Asks verification questions
- Requests proof/links
- Seeks reassurance
Persona Selection Logic:
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:
- Repeated Clarification: "I didn't understand, can you repeat?"
- Technical Confusion: "Which button do I press? My phone is old."
- Fake Delays: "Let me find my card. Hold on..."
- Partial Compliance: "I sent something, did you receive?"
- Request Verification: "Can you send me official proof?"
Turn-by-Turn Strategy:
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)
- UPI IDs:
user@paytm,9876543210@ybl, etc. - Bank Account Numbers: 9-18 digit sequences
- IFSC Codes: 11-character bank codes
- Phone Numbers: +91 or 10-digit Indian numbers
- Phishing Links: URLs to fake websites
Extraction Pipeline
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
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
-- 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
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
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
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"]
# 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
# .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
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
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:
Scam Detection Accuracy (25%)
- True Positive Rate (detecting actual scams)
- False Positive Rate (avoiding false alarms)
- Target: >90% accuracy
Engagement Quality (25%)
- Naturalness of conversation (believable persona)
- Number of turns sustained
- Avoidance of detection by scammer
- Target: >10 turns average
Intelligence Extraction (30%)
- UPI IDs extracted correctly
- Bank accounts extracted correctly
- Phishing links identified
- Extraction accuracy (no false positives)
- Target: >85% precision, >80% recall
Response Time (10%)
- API latency
- Time to extract intelligence
- Target: <2s per response
System Robustness (10%)
- Handle edge cases (empty messages, very long texts)
- Error handling
- API availability
Testing Framework
# 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
# 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
# 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
# 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
# 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:
- Consent: User must opt-in to honeypot engagement
- Data Minimization: Store only essential data
- Anonymization: Hash PII (phone numbers, etc.)
- Retention: Delete logs after 30 days
- Right to Erasure: Provide deletion API
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:
- No Escalation: Never threaten or provoke scammer
- No Personal Info: Never share real personal details
- No Financial Transactions: Never actually transfer money
- Termination: End conversation if scammer becomes violent
- Legal Compliance: Ensure honeynet operations are legal
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:
- Language Bias: Equal performance for Hindi and English
- Dialect Bias: Test on multiple Indian accents
- Age Bias: Personas represent diverse age groups
- Regional Bias: Test on North and South Indian scam patterns
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
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)
Innovation (30%)
- ✅ Multi-turn agentic engagement (beyond simple detection)
- ✅ Dynamic persona adaptation
- ✅ Intelligent stalling tactics
- ✅ Real-time intelligence extraction
India-Specific (20%)
- ✅ Hindi + English bilingual support
- ✅ UPI/IFSC/Indian bank patterns
- ✅ Local scam tactics knowledge
- ✅ Cultural context in personas
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:
- Scam detection with >85% accuracy
- Multi-turn engagement (at least 10 turns)
- Extract at least 1 UPI ID or bank account
- API response time <3s
- Handle Hindi and English
- Structured JSON output
Should Have:
-
90% detection accuracy
- 15+ turn average engagement
- Extract 2+ intelligence types per conversation
- API response time <2s
- State persistence across sessions
- 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:
- ✅ 100% Free Tier - No cost barriers
- ✅ Phased Approach - Text first, audio later
- ✅ Production Architecture - Scalable, monitored, robust
- ✅ India-Specific - Hindi support, local scam patterns
- ✅ Competition-Ready - API-first, JSON outputs
- ✅ Technically Superior - LangGraph, state management, multi-turn
- ✅ Well-Documented - Clear implementation path
Expected Ranking: TOP 10 from 40,000 participants
Next Steps:
- Begin implementation following project structure
- Test continuously against test dataset
- Deploy early to identify issues
- Iterate based on testing feedback
- 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
- Visit: https://console.groq.com/
- Sign up with email
- Navigate to API Keys section
- Generate new API key
- Free tier: 30 requests/minute, 6000/day
C. Supabase PostgreSQL Setup
- Visit: https://supabase.com/
- Create account
- New project → Select free tier
- Copy connection string
- Use in DATABASE_URL environment variable
D. Redis Cloud Setup
- Visit: https://redis.com/try-free/
- Create account
- New database → Free 30MB
- Copy connection details
- Use in REDIS_URL environment variable
E. Testing Commands
# 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
# 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