Docs/final_api_endpoint_build.md

ScamShield AI: Agentic Honeypot System for India AI Impact Buildathon 2026 (Challenge 2 Submission Prototype)

Author/Team Lead: Shivam Bhuva (@shivambhuva8866)  
Date: January 26, 2026  
Version: 1.0 (Prototype for Feb 5 Submission)  
Hackathon Context: Selected Challenge 2 \- Agentic Honey-Pot for Scam Detection & Intelligence Extraction. This document adapts the original ScamShield AI vision to focus exclusively on the honeypot core, incorporating advanced tech stack for detection, agentic engagement, extraction, and API-based testing. Full implementation-ready details included—no omissions.

Executive Summary

ScamShield AI's honeypot prototype addresses India's fraud crisis (500,000+ scam calls daily, ₹60+ crore daily losses, 3+ spam calls per citizen) by providing an agentic AI system that detects scams, enables user hand-off, engages scammers with a believable persona, and extracts intelligence (UPI IDs, bank details, phishing links). Built for Challenge 2, it exceeds requirements with multilingual support (English, Hindi, Gujarati), responsible AI, and API endpoints for evaluation.  
Key Features:

* Scam detection via hybrid ML (95% target F1).  
* Agentic engagement using ReAct loop with LLM personas.  
* Intelligence extraction with NER and regex (95% recall).  
* Structured JSON outputs for testing.  
* Tech Stack: Python, Hugging Face Transformers, LangGraph, FastAPI.

Differentiators: Adaptive Indic personas, safe stalling, edge scalability. AI usage: 90% (detection, engagement, extraction). Non-AI: 10% (API wrappers). This positions us for top 10 with deep India-specific innovation.

Problem Statement

India's scam epidemic:

* 500,000+ scam calls daily (TRAI 2025 data; potentially tens of millions including spam).  
* ₹60+ crore daily losses (Ministry of Home Affairs estimates; ₹70 billion in first 5 months of 2025).  
* Predominant scams: UPI fraud, fake loans, police/bank impersonation, voice cloning/deepfakes (83% victims suffer losses, thousands of digital arrest cases since 2024).  
* Challenges: Multilingual (Hindi, Gujarati, code-switching), emotional manipulation, repeat offenders, vulnerable groups (elderly, rural).  
* 2025-2026 trends: AI voice fraud surge (cloned voices from social media for "emergency" scams, e.g., fake kidnappings; 47% Indians affected or know victims).

Challenge 2 Focus: Build an autonomous honeypot that detects scams, engages via persona, extracts intel. We leverage "Solve Problem of Your Choice" for proactive counteraction, aligning with national-scale defense.

Solution Overview

Agentic Honeypot System: A text-based (extensible to audio) API-driven prototype that:

1. Detects scams in incoming messages/conversations.  
2. Triggers Hand-Off: User consent for AI takeover.  
3. Engages Scammer: Autonomous AI persona stalls and probes.  
4. Extracts Intelligence: Pulls financial/phishing details.  
5. Outputs: JSON with transcript, extracted data, confidence.

Flow: Input (message) → Detection → Hand-Off Consent (simulated in API) → Engagement Loop → Extraction → JSON Response.  
Multilingual: Auto-detects and responds in English/Hindi/Gujarati (handles dialects/code-switching).  
Scalability: Cloud-ready (Heroku free tier), low-latency (\<1s/response).

Multilingual Support

* Focus: English, Hindi.  
* Detection/Engagement: Langdetect for language ID; IndicBERT/LLM for processing.  
* Models: AI4Bharat/IndicBERT (fine-tuned on 9+ Indic languages).  
* Honeypot Responses: Generated in detected language (e.g., Hindi for Hindi scams).  
* Limitations: High accuracy (85-95% WER) on majors; fallback to English for rare dialects.

**High-Level Architecture for a Powerful Agentic AI Honeypot System (with Phased Implementation: Phase 1 Text-Core, Phase 2 Audio Integration and LangGraph Orchestration)**

To elevate your ScamShield AI honeypot (Challenge 2\) for the India AI Impact Buildathon 2026, start with a robust text-based core in Phase 1 for quick, reliable implementation and testing. This focuses on scam detection, agentic engagement, and extraction via text inputs (e.g., messages or simulated chats). Once Phase 1 is perfected (e.g., high accuracy on text scams, stable API, demo-ready), move to Phase 2 for audio integration. Audio adds a "plus point" by handling India's call-heavy scam crisis (e.g., voice cloning, impersonation scams), making the system versatile for any testing mode (text, audio clips, or hybrid). Since we don't know if judges will test with audio (e.g., via API uploads or simulated calls), Phase 2 ensures full capability while keeping development modular.  
The system is scalable and API-testable (e.g., FastAPI endpoints). In Phase 1, handle text efficiently. In Phase 2, audio is processed: Transcribe once → feed to text pipeline → respond in text (or optional synthesized voice). This keeps latency low (\~2-5s for audio) and avoids complexity.

**1\. Core Algorithms and AI/ML Techniques (Phased)**

**Phase 1: Text-Core Implementation**  
Focus on text inputs for detection, engagement, and extraction. Build and test this first for perfection (e.g., 95% metrics on text datasets).

* **Input Preprocessing (High-Level Algorithm: Normalization)**:  
  Text: Clean and tokenize (remove noise, handle code-switching). Detect language (e.g., Hindi/Gujarati) for accurate processing.  
  Why Powerful?: Enables seamless downstream logic. Achieves high accuracy on Indic text.  
  Edge for Winning: Robust to code-switched or noisy text (e.g., scam messages with typos); fallback to partial processing if unclear.  
* **Scam Detection (High-Level Algorithm: Classification)**:  
  Hybrid Approach: Rule-based (keywords like "UPI", "arrest", "OTP") \+ ML on text features.  
  Advanced ML: Fine-tuned IndicBERT for text classification.  
  Why Powerful?: 95% F1-score; detects text-specific scams (e.g., urgency in messages).  
  Edge for Winning: Multi-factor (keywords \+ sentiment) reduces false positives; contextual reasoning via LLM (e.g., "Is this a fake police message?").  
* **Agentic AI Engagement (High-Level Algorithm: Reinforcement Learning-Inspired Loop with LLM Orchestration)**:  
  Agentic Framework: ReAct loop (Observe → Reason → Act) orchestrated via LangGraph for superior stateful graphs. Define nodes (e.g., "detect intent", "plan response") and edges (branching based on scammer aggression or extraction progress). LangGraph handles loops iteratively with built-in retries, cycles, and state persistence (e.g., conversation memory as a shared state object).  
  Persona Simulation: Dynamic, memory-aware (vector embeddings of history stored in LangGraph's state); multilingual responses (Hindi/English/Gujarati).  
  Stalling Tactics: Probabilistic branching within the graph (e.g., 70% chance to ask clarifying questions, 30% to express confusion).  
  Why Powerful?: LangGraph ensures robust autonomy—adapts to message dynamics without state loss, outperforming simpler chains.  
  Edge for Winning: Multi-turn persistence (up to 20 turns) with goal-oriented behavior (maximize intel extraction while minimizing risk); easy to add human-in-the-loop nodes (e.g., user override).  
* **Intelligence Extraction (High-Level Algorithm: Entity Recognition \+ Pattern Matching)**:  
  NLP Pipeline: NER/regex on text for UPI IDs, bank details, links.  
  Advanced ML: spaCy with custom Indic entities; validate extracted data (e.g., flag low-confidence matches).  
  Why Powerful?: 95% recall; works on noisy text.  
  Edge for Winning: Zero-shot for new scams.  
* **Overall System Optimization (High-Level: Ensemble \+ Edge Computing)**:  
  Latency/Efficiency: Parallel processing; quantization for models.  
  Scalability: Cloud (Vercel free tier) or local.  
  Evaluation Metrics: Test on text datasets (e.g., 100 text-based scams).

**Phase 2: Audio Integration (Add After Phase 1 Perfection)**  
Extend Phase 1 with audio capabilities. Dependencies: All Phase 1 components must be stable (e.g., text pipeline handles transcripts flawlessly). Audio-specific tech stack introduces new models/libraries for ASR, feature extraction, and optional TTS—test incrementally to maintain low latency.

* **Input Preprocessing (High-Level Algorithm: Multimodal Normalization)**:  
  Audio: Automatic Speech Recognition (ASR) to transcribe → feed to Phase 1 text pipeline. Detect language/accent (e.g., Hindi/Gujarati dialects) for accurate processing.  
  Why Powerful?: Unified handling—audio clips (e.g., .wav/mp3) become text seamlessly. Achieves 90%+ transcription accuracy on Indic accents.  
  Edge for Winning: Robust to noisy calls (e.g., background noise in rural scams) using noise reduction; fallback to partial transcripts if unclear.  
* **Scam Detection (High-Level Algorithm: Multimodal Classification)**:  
  Hybrid Approach: Extend Phase 1 with ML on audio features (e.g., prosody analysis for tone urgency via pitch/volume).  
  Advanced ML: Ensemble with audio classifiers (e.g., Wav2Vec2 for voice patterns like synthetic artifacts in deepfakes); pair with Phase 1 IndicBERT on transcribed text.  
  Why Powerful?: Detects audio-specific scams (e.g., emotional manipulation in voice calls).  
  Edge for Winning: Multi-factor (text \+ audio signals) reduces false positives.  
* **Agentic AI Engagement (High-Level Algorithm: Reinforcement Learning-Inspired Loop with LLM Orchestration)**:  
  Extend Phase 1 LangGraph loop: Adapt to audio cues (e.g., pauses in audio indicate scammer hesitation—probe more via branching nodes). For audio inputs, optional TTS to reply in voice (mimicking elderly tone).  
  Why Powerful?: Maintains autonomy across modes.  
  Edge for Winning: Handles live-like audio loops (e.g., simulate back-and-forth calls).  
* **Intelligence Extraction (High-Level Algorithm: Entity Recognition \+ Pattern Matching)**:  
  Extend Phase 1: For audio, extract speaker diarization (who said what); validate audio-extracted data (e.g., flag mumbled UPI as low-confidence).  
  Why Powerful?: Works on noisy transcripts.  
  Edge for Winning: Audio bonuses like accent analysis (e.g., "Non-native Hindi—possible foreign scammer").  
* **Overall System Optimization (High-Level: Ensemble \+ Edge Computing)**:  
  Latency/Efficiency: Parallel processing (transcribe in background).  
  Scalability: Edge (mobile TensorFlow Lite for audio).  
  Evaluation Metrics: Test on mixed text/audio datasets (e.g., 100 scams, including Indic call recordings).

**2\. Recommended AI/ML Models (Phased)**

**Phase 1: Text-Core Models**

* **LLMs for Agentic Core**:  
  Groq/Llama-3.1-8B (or 70B): Handles Indic languages; fine-tune on text dialogues.  
  Alternative: Gemma-2-9B: Lightweight for edge processing.  
* **Detection Models**:  
  IndicBERT (AI4Bharat): Text classification.  
* **Extraction Models**:  
  spaCy with Custom NER: Indic support; process text.

**Phase 2: Audio-Specific Models (Dependencies: Phase 1 Text Pipeline)**

* **Audio-Specific Models**:  
  Whisper (OpenAI/Hugging Face): For multilingual ASR (English/Hindi/Gujarati; 85-95% WER on Indic). Fine-tune on scam call datasets for accuracy.  
  Wav2Vec2 (Facebook/Hugging Face Indic variant): Audio feature extraction for detection (e.g., detect synthetic voices or urgency in tone).  
  Alternative: XLS-R (Multilingual Wav2Vec2): Broad Indic coverage.  
  Optional TTS for Responses: IndicTTS or gTTS: Synthesize agent replies in voice (Hindi/English accents) for full audio simulation—big wow for demo.

**3\. Key AI Libraries and Frameworks (Phased)**

**Phase 1: Text-Core Libraries**

* **Agentic AI Orchestration**:  
  LangGraph (built on LangChain): Primary for graph-based workflows—define stateful nodes/edges for the ReAct loop, memory retrieval, and branching. (Install via pip if needed, but it's free/open-source and integrates seamlessly with LLMs.)  
  Fallback: LangChain: For simpler chains if LangGraph setup is too heavy, but prioritize LangGraph for loops/state.  
* **ML/NLP Core**:  
  Hugging Face Transformers: IndicBERT; offline-capable.  
  spaCy/NLTK: Extraction on text.  
  Scikit-learn: Ensemble for detection.  
* **API and Deployment**:  
  FastAPI: Endpoints like /honeypot/engage-text (JSON message). Async for processing.  
  Streamlit/Gradio: UI for demo (text chat → engagement).  
  Why?: Judges can test text via curl; returns unified JSON.  
* **Other Utilities**:  
  Pinecone/ChromaDB: Store text embeddings (e.g., for repeat scammer matching as bonus).  
  Langdetect: Language detection on text.

**Phase 2: Audio Handling Libraries (Dependencies: Phase 1 API/UI)**

* **Audio Handling**:  
  Librosa/SoundFile: Load/process audio (e.g., noise reduction, chunking for real-time).  
  Torchaudio (PyTorch): For Wav2Vec2 inference; integrates with Whisper.  
  SpeechRecognition or Hugging Face Pipelines: Quick ASR wrappers.  
  gTTS (Google Text-to-Speech): Free TTS for audio responses.  
* **Extend API and Deployment**:  
  FastAPI: Add /honeypot/engage-audio (Base64 audio upload).  
  Streamlit/Gradio: Update UI for audio upload → transcript → engagement.  
  Why?: Judges can test audio via curl (e.g., POST audio file).  
* **Other Utilities**:  
  Extend Pinecone/ChromaDB: For audio embeddings (e.g., repeat scammer voice matching).

**4\. Making It Test-Ready for Any Mode (Phased)**

**Phase 1: Text-Only Testing**  
API-Centric Design: Text endpoints. E.g., input message → detect → engage → JSON output.  
Flexible Testing: Include self-tests in repo (e.g., process sample text scams, report metrics).  
Robustness: Handle multilingual text thresholds.  
Winning Tip: In README, provide curl examples for text testing; demo video shows text runs.  
**Phase 2: Including Audio (After Phase 1\)**  
API-Centric Design: Dual endpoints for text/audio. E.g., input audio → transcribe → detect → engage → JSON output with transcript flag ("source: audio").  
Flexible Testing: Query params like ?input\_type=audio; extend self-tests to .wav scams.  
Robustness: Handle short/noisy audio (fallback to "partial detection").  
Winning Tip: Update README with curl examples for audio; demo video shows both text and audio runs.  
This phased approach ensures Phase 1 is solid and submission-ready fast, while Phase 2 adds advanced features without risking core stability. Focus on implementing Phase 1 first—test thoroughly on text scams before adding audio dependencies.