DEV Community: Farhan

ScamShield: An AI Cyber Defense Tool Designed for My Dadi, Powered by Gemma

Farhan — Sun, 04 Oct 2026 13:43:00 +0000

This is a submission for the Hacktoberfest Weekend Challenge: Build for a Friend

What I Built

Here is a built-in sample text message from ScamShield's test suite:

"URGENT: Your SBI net banking account has been BLOCKED due to incomplete KYC. Click immediately to restore access: http://sbi-kyc-update.xyz/verify or call 9876543210."

Imagine receiving that at 7:00 AM on a basic smartphone. If you spent decades writing paper checks and visiting branch tellers, a text threatening to freeze your pension triggers immediate dread. The reflex is to tap the link or call the number before morning tea gets cold.

Who It's For

I built ScamShield around a clear design persona: my dadi (paternal grandmother).

To be transparent before the deadline: I did not have a real family member test this interface over the weekend, nor do I have real user quotes to share. I chose not to invent reactions or pretend someone tested this who did not. Instead, I treated my dadi as an anchor persona: someone who relies on WhatsApp and SMS to stay connected with family, has no interest in inspecting URL top-level domains, and needs plain, reassuring guidance in her own language when a message feels suspicious. The immediate next step is a real, sit-down handover with her before installing it on her phone.

The problem ScamShield addresses is simple: modern cyber fraud in India—from fake electricity disconnections to "digital arrest" intimidation calls—weaponizes artificial urgency. Older adults are targeted because they respect authority and fear penalties. When panic sets in, they do not need a twenty-page security guide; they need one place to drop a screenshot, paste a confusing message, or look up a strange number and receive a clear answer: Is this real, or is someone trying to trick me?

ScamShield groups its core protections into five headline features:

Multimodal Screenshot Vision Scanner: Users upload a screenshot of an SMS, WhatsApp chat, fake UPI QR code, or banking alert. Google's Gemma multimodal model analyzes layout, typography, sender cues, and manipulation tactics to assign a risk score from 0 to 100.
Text & Phishing URL Inspection: Direct analysis of raw message text and links, checking lookalike domains (homoglyphs), non-standard extensions (.xyz), IP hosts, and coercive phrasing.
Conversational AI Defense Assistant: A dedicated chat helper powered by Gemma where users ask questions in plain language ("A caller claiming to be police says a parcel has drugs in it; what do I do?") and receive calm, step-by-step guidance.
Golden Hour Victim Recovery Wizard & FIR Generator: When money has already been sent, the first few hours decide whether funds can be frozen before leaving the banking network. The wizard guides reporting to the 1930 National Cyber Crime helpline, provides direct emergency numbers for ten major Indian retail banks, and drafts a formal police FIR complaint letter.
Family Alert Center: One-click dispatch that posts formatted fraud alerts to a family Discord channel or generates copy-ready summaries for WhatsApp family groups.

Supporting features include a 15-question scam awareness quiz, an active threat intelligence feed backed by Ministry of Home Affairs advisories, an interactive 10-point security hygiene scorecard, a local phone carrier lookup tool, and a crowdsourced fraud reporting database.

Demo

Live Application: https://hacktoberfest-scamshield.vercel.app
GitHub Repository: https://github.com/YTxFSGAMERz/hacktoberfest-ScamShield

Try It in 30 Seconds

Open the live demo.
Under the header, click "SBI KYC Block" in the Fraudulent / Threats row.
The screenshot auto-loads into the scanner. Click "Analyze with Gemma 4".
Review the verdict card: notice the red SCAM badge (Risk Score 98/100), the summary, detected red flags, and the action checklist.
Click "Amazon OTP" under the Genuine / Legitimate row and click Analyze. Notice the green SAFE verdict (Risk Score 5/100) explaining why the message is benign.

The main vision scanner evaluating an urgent fake SBI KYC message, producing a clear risk verdict and immediate safety steps.

Text message analysis highlighting red flags: lack of an official 6-character TRAI sender header, deceptive top-level domain, and intimidation tactics.

Conversational safety assistant deconstructing the anatomy of a 'Digital Arrest' intimidation scheme.

Step-by-step crisis response wizard detailing immediate actions, bank contacts, and National Cyber Crime 1930 reporting.

Personal security posture audit evaluating UPI PIN habits, SIM swap risks, and remote desktop application hygiene.

Family alert center allowing users to broadcast an urgent warning to a family Discord channel or copy it for WhatsApp.

Code

YTxFSGAMERz / hacktoberfest-ScamShield

AI-powered scam detection using Gemma 4. Upload screenshots, get risk verdicts in English/Hindi/Gujarati. Built for Hacktoberfest 2026.

🛡️ ScamShield — Autonomous AI Cyber-Defense & Anti-Fraud Suite

ScamShield is an AI-powered cyber-threat defense, OSINT intelligence, and scam neutralization platform designed specifically to safeguard citizens from complex modern fraud vectors — from Digital Arrest psychological traps and UPI refund scams to malicious APK banking trojans, SIM swap attacks, and AI voice/deepfake clones.

Powered by Google Gemma 4 (via Gemini API & local Ollama failover), ScamShield delivers instant multi-dimensional risk scores, forensic explainability, victim recovery protocols, and community-driven threat intelligence across 25+ Indian regional & global languages.

🌐 Live Web Application: https://hacktoberfest-scamshield.vercel.app

📸 Visual Showcase & Feature Tour

🔍 Screenshot & Multimodal Scanner	💬 SMS & WhatsApp Text Analyzer

Gemma 4 Vision extracts OCR text, visual badges, and suspicious UI markers.	Instant semantic NLP analysis detects panic language, urgency, and fraud patterns.

🔗 Phishing & Domain Age Scanner	📞 Phone OSINT & QR Code Defense

Multi-layer

…

View on GitHub

The repository is open source under the MIT License.

One-Line Setup

git clone https://github.com/YTxFSGAMERz/hacktoberfest-ScamShield.git && cd hacktoberfest-ScamShield && pip install -r requirements.txt && python -m flask --app api/index.py run --port 5000

Copy .env.example to .env and configure GEMINI_API_KEY or connect a local Ollama instance running Gemma.

How I Built It

ScamShield pairs a Python Flask backend with a lightweight Single Page Application (vanilla HTML5, CSS3, and JavaScript) designed to load instantly on older mobile hardware.

[ Browser Client ]  <--->  [ Flask API (api/index.py) ]  <--->  [ AI Router (scamshield/llm.py) ]
  (Vanilla PWA)             (Rate Limiter, Validators)           |
                                                                 +--> Primary: Google Gemma 4 (API)
                                                                 +--> Failover: Ollama (gemma4:e4b Local)

Model Setup and Resilient Fallback Chain

For hosted deployment, ScamShield uses Google's gemma-4-26b-a4b-it model via the Google Generative Language API. Because fraud triage cannot tolerate server crashes during a crisis, scamshield/llm.py implements an automated fallback chain.

When LLM_PROVIDER is set to auto:

The app queries the Gemini API for structured JSON containing verdict, risk score, executive summary, detected flags, and guidance.
If the API errors out (400 Bad Request, quota limit, or timeout), scamshield/llm.py logs a warning and automatically fails over to a local Ollama instance running gemma4:e4b.
Gemma models often produce separate internal reasoning tokens (p.get("thought", False)). The extraction engine strips these so the client receives valid JSON.
If the model wraps JSON in markdown fences, _extract_json() uses multi-stage parsing (direct parse -> regex -> brace match -> fallback dictionary) to avoid crashes.

One Real Bug from Git History

During multi-language expansion, I hit an import cycle and startup crash (commit ed6883f: "fix: export SUPPORTED_LANGUAGES at top of i18n.py and add defensive import fallbacks").

api/index.py imported SUPPORTED_LANGUAGES from scamshield/i18n.py, but i18n.py defined it below helper functions with circular references. On Vercel, this threw ImportError: cannot import name 'SUPPORTED_LANGUAGES'. Hoisting the dictionary to the top of scamshield/i18n.py and adding defensive dictionary fallbacks in api/index.py resolved the crash.

Verification and Test Suite

To guarantee reliability, the codebase includes an automated test suite:

54 passed tests across 4 modules (test_analyzer.py, test_chat_intel.py, test_llm.py, test_new_features.py).
27.22 seconds execution time under pytest 8.3.4 on Python 3.13.

Why Does Open Innovation Matter?

Evaluating open models like Gemma against closed APIs highlights key architectural differences:

Can It Run on a Laptop with No Internet?

Yes. On an ordinary laptop (tested on AMD Ryzen 5 6600H, 16 GB RAM, NVIDIA GeForce RTX 3050 6GB Laptop GPU), the open gemma4:e4b model (6.6 GB) runs locally via Ollama with CUDA acceleration. The inference pipeline processes queries without an active network connection, keeping the scanner functional during connectivity outages.

Keep Data Off a Server I Don't Control?

This is critical for family privacy. When an older person receives a suspicious message, it often contains personal details: partial account numbers, their home address, or their phone number. With closed APIs, every screenshot and text snippet must be transmitted to an external corporate endpoint. In ScamShield's local mode, images are processed in memory on localhost and never leave the device.

Note on hosted demo vs local mode: The public Vercel demo connects to Google's API endpoint over HTTPS so anyone can try the tool without downloading 6 GB weights. However, local mode keeps all processing confined to the user's machine.

Swap Models, Fine-Tune, and Customize Behavior

With open weights, developers are never locked into vendor policy shifts or deprecation schedules. If a regional scam vector appears, Gemma can be fine-tuned on regional dialects (such as Gujarati or Marathi SMS patterns) and served on an edge device without requesting third-party permission.

Cost

Running Gemma locally costs $0.00 in API fees. For community initiatives, senior centers, or public libraries providing scam verification kiosks, operating without ongoing per-token billing makes continuous protection sustainable.

Empirical Label Agreement and Latency

I ran ScamShield's built-in synthetic test vectors through the Gemma pipeline to measure classification consistency and latency:

Test Sample	Category	Expected Verdict	Gemma Verdict	Risk Score	Latency	Agreement
`safe_login_otp.png`	Amazon 2FA Login	SAFE	SAFE	5 / 100	14.84s	✅ Yes
`safe_bank_alert.png`	HDFC Debit Alert	SAFE	SAFE	5 / 100	7.59s	✅ Yes
`kyc_scam.png`	SBI Account Block	SCAM	SCAM	98 / 100	6.98s	✅ Yes
`lottery_scam.png`	WhatsApp Lucky Draw	SCAM	SCAM	100 / 100	8.55s	✅ Yes

Across all tested samples, the model achieved 100% agreement with expected classifications, with a median latency of 8.07 seconds.

Where Open Beat Closed

Open technology won here because of resilience under failure. When closed APIs hit billing limits, experience regional outages, or block prompts with overly aggressive filters, closed applications break. With ScamShield's dual-tier architecture, if the cloud endpoint fails, the application falls back to a locally running Gemma instance without interrupting the user.

What It Can't Do Yet & What's Next

A Real Handover to Older Users: The immediate next step is sitting down with my dadi to watch her navigate the interface. Observing where she hesitates, which button labels confuse her, and whether the text size is comfortable will guide the next release.
Native Mobile App Wrapper: Right now ScamShield is a responsive Progressive Web App. Packaging it as an Android APK will let older users share screenshots directly via Android's native "Share" menu.
Automated Offline OCR: Currently, local vision analysis requires a multimodal model. Adding lightweight local Tesseract OCR as a pre-filter will enable instant text extraction on low-end phones before model inference.

Prize Categories

Best Use of Gemma

ScamShield competes in the Best Use of Gemma category:

Multimodal Vision Reasoning: Uses gemma-4-26b-a4b-it to analyze incoming screenshot artifacts, identifying coercive visual cues and deceptive sender branding.
Local Edge Capability: Supports offline execution via gemma4:e4b on Ollama, proving that advanced cyber protection can run on consumer laptop hardware without leaking private messages.
Thought Token Management & Extraction: Implements dedicated handling for Gemma's internal reasoning tokens to deliver clean, structured JSON verdicts and actionable emergency checklists.

Building Vidya: A Production-Grade Multi-Agent Voice Cyber-Tutor with Murf Falcon & LiveKit

Farhan — Fri, 14 Aug 2026 19:55:44 +0000

A complete engineering retrospective on building an ultra-low-latency voice AI tutor with specialist handoffs, vector RAG, SQLite memory, live tools, telephony, and real-time analytics for the Murf 10 Days Voice Agent Challenge (#VoiceForBharat).

1. The Problem: Voice-First Learning for Bharat

In many regions across Bharat (India), millions of students and adult learners face a dual barrier: digital literacy hurdles and fear of judgment when asking basic questions. Traditional screen-based interfaces require typing, navigating complex menus, and reading dense text — creating unnecessary friction. Moreover, classroom environments often intimidate students who struggle with foundational concepts like arithmetic, grammar, or digital safety (UPI payments, OTP scams, phishing).

Voice changes everything.

Conversational voice AI provides a zero-friction, patient, and infinitely encouraging tutor that meets students where they are. That was my mission for the Learning & Literacy track of the Murf 10 Days Voice Agent Challenge: to build Vidya, an intelligent Cyber-Tutor that speaks with a natural Indian accent, remembers learners across sessions, pulls verified facts from curriculum vector databases and live APIs, hands off complex math to a dedicated specialist, and even places proactive telephony practice calls.

2. System Architecture: How It All Works

Building a real-time conversational agent requires orchestrating four critical layers with sub-second latency:

flowchart TD
    subgraph ClientLayer["🖥️ Frontend Client (Next.js 16 + React 19)"]
        UI["Cyberpunk Matrix Grid Audio Visualizer (30x30)"]
        Dash["📊 Real-Time Call Telemetry Dashboard (/dashboard)"]
    end

    subgraph TransportLayer["⚡ Real-Time Transport (LiveKit WebRTC)"]
        LK["LiveKit Audio & Data Pipeline"]
    end

    subgraph AgentLayer["🧠 Multi-Agent Voice Pipeline"]
        VAD["Silero VAD + Turn Detector"]
        STT["Deepgram Nova-3 (en-IN)"]

        subgraph Agents["Specialist Handoff Engine"]
            Vidya["Primary Agent: Vidya\n(General & Literacy Tutor)\nMurf Voice: Anisha"]
            Kash["Specialist Agent: Kash\n(Advanced Mathematics)\nMurf Voice: en-US-matthew"]
            Vidya -.->|Dynamic Silent Handoff\nwith ChatContext| Kash
        end

        TTS["Murf Falcon Streaming TTS\n(55ms Latency)"]
    end

    subgraph Subsystems["💾 Knowledge, Memory & Tooling"]
        RAG["ChromaDB Vector Store\n(Curriculum RAG)"]
        MemDB["SQLite agent_memory.db\n(Student Profile & Analytics)"]
        Tools["Live Tools:\n• Wikipedia API\n• Dictionary API\n• ExchangeRate API\n• Discord Escalation\n• SIP Softphone"]
    end

    UI <-->|WebRTC Stream| LK
    LK <--> VAD
    VAD --> STT
    STT --> Vidya
    Vidya <--> RAG
    Vidya <--> MemDB
    Vidya <--> Tools
    Vidya --> TTS
    Kash --> TTS
    TTS --> LK
    MemDB -.->|Auto-sync| Dash

The Pipeline in Numbers

Streaming TTS: Murf Falcon with 55ms model latency and 130ms Time-to-First-Audio (TTFA).
STT: Deepgram Nova-3 optimized for en-IN (Indian English).
LLM: Local Ollama (gemma4:31b-cloud), Google Gemini (gemini-2.5-flash), or OpenAI (gpt-4o).
Transport: LiveKit WebRTC audio transport with Silero VAD and Multilingual Turn Detection.

3. Key Features Built Across the 10-Day Journey

1. Ultra-Low Latency Indian Voice with Murf Falcon

Using Murf Falcon's streaming TTS, Vidya speaks with Anisha — a warm, natural Indian English voice. To eliminate conversational pauses:

Tokenizer sentence threshold tuned to min_sentence_len=10.
text_pacing=False to strip synthetic delays.
Preemptive generation enabled on LiveKit sessions.

2. Multi-Agent Specialist Handoff (Vidya $\rightarrow$ Kash)

When a student asks for higher-level mathematics (calculus, trigonometry, algebra drills), Vidya dynamically executes a specialist handoff to Kash (voiced by Murf Falcon's en-US-matthew):

@function_tool(
    description="Transfer the user to the Mathematics Specialist. Call this ONLY when the user asks for advanced math practice or has a complex mathematical question."
)
async def transfer_to_maths_specialist(self, ctx: RunContext) -> Agent:
    logger.info("Transferring to Maths Specialist")
    # Propagate the full conversation context so the user doesn't repeat themselves!
    return MathsSpecialist(
        room=self.room,
        chat_ctx=ctx.session._chat_ctx
    )

3. Curriculum RAG with ChromaDB

To prevent hallucinations on syllabus topics (digital safety laws, grammar rules, arithmetic), curriculum markdown documents in backend/data/ are chunked and ingested into a local ChromaDB vector collection (syllabus). When queried, Vidya grounds her explanations in verified curriculum context.

4. Silent Long-Term Memory (SQLite)

Vidya tracks user facts, names, and interaction histories in agent_memory.db. When you reconnect, Vidya retrieves your profile before speaking:

"Hello Farhan, how are you? Welcome back to our English practice!"

5. Live Tool Integrations & Chaos Resilience

Wikipedia Encyclopedia API: Instant retrieval of historical and scientific facts.
Free Dictionary API: Word definitions, parts of speech, and pronunciation examples.
Real-Time FX Rates (api.exchangerate-api.com): Live currency math problems with date stamps and graceful offline fallback if network calls fail.

6. Human Escalation Support (Discord Webhook)

If a student gets severely frustrated or explicitly asks for a human teacher, Vidya confirms consent, generates a support reference ID (VIDYA-TKT-XXX), and pushes an alert directly to a Discord teacher channel.

7. Telephony (Inbound & Outbound SIP)

Inbound Agent: Answers phone calls via LiveKit SIP trunks, extracts caller ID, applies BVCTelephony noise cancellation, and allows warm human transfers.
Outbound Agent: Dials proactive practice calls, detects answering machines, and handles SIP error codes (486 Busy $\rightarrow$ 1h retry, 408 No Answer $\rightarrow$ 4h retry, 603 Declined $\rightarrow$ cancel & log to SQLite).

8. Cyberpunk Telemetry Dashboard (`/dashboard`)

A dedicated Next.js dashboard polls /analytics.json (auto-synced from SQLite) every 5 seconds to track total sessions, successful learning uplinks, and dropped calls in real time.

4. Engineering Challenges & How I Solved Them

Challenge 1: The Multi-Language STT Latency Trap

Problem: Initially, using multi-language STT (language="multi") caused noticeable speech-recognition lag, creating awkward conversational gaps.
Root Cause: Universal multilingual models are significantly heavier and require extra time to classify the language before transcribing.
Solution: Explicitly locked Deepgram STT to language="en-IN" with smart_format=True. STT latency dropped by over 40%, making turn-taking instantaneous.

Challenge 2: Context Wipe During Specialist Agent Handoff

Problem: When Vidya handed off to Kash, the math specialist started with a blank slate, asking the student to repeat what problem they were working on.
Solution: Passed chat_ctx=ctx.session._chat_ctx from the parent agent's RunContext directly into the MathsSpecialist constructor. Kash seamlessly picked up the exact sentence and numbers the student was discussing.

Challenge 3: Live API Hangs in Real-Time Voice Loops

Problem: External HTTP calls (like exchange rate APIs) can hang on flaky connections. A 10-second network delay in a voice agent feels like an eternity.
Solution: Wrapped external requests in strict 5-second socket timeouts with custom try/except error recovery blocks. Created chaos test scripts (break_api.py and fix_api.py) to verify that Vidya gracefully apologizes and steers the student to another topic instead of hanging.

5. Build Your Own Voice Agent: Step-by-Step Guide

Want to build your own real-time voice agent? Here is the exact blueprint.

1. Prerequisites

Python 3.10+ & uv
Node.js 18+ & pnpm
Accounts & API keys for:
- Murf Falcon (Streaming TTS)
- Deepgram (STT)
- LiveKit Cloud (WebRTC Transport)
- Google AI Studio or OpenAI (LLM)

2. Clone the Repository

git clone https://github.com/your-org/vidya-ai-tutor.git
cd vidya-ai-tutor

3. Configure Environment Variables

Create .env.local in backend/ and frontend/:

# LiveKit Credentials
LIVEKIT_URL=wss://your-project.livekit.cloud
LIVEKIT_API_KEY=your_livekit_api_key
LIVEKIT_API_SECRET=your_livekit_api_secret

# Voice & AI Keys
MURF_API_KEY=your_murf_api_key
DEEPGRAM_API_KEY=your_deepgram_api_key
GOOGLE_API_KEY=your_google_api_key

# Optional Integrations
DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/...

4. Ingest Knowledge & Download Models

cd backend
uv sync
uv run python src/rag_ingest.py              # Ingest curriculum into ChromaDB
uv run python src/agent.py download-files    # Download Silero VAD models

5. Launch All Services

Windows (with High-Performance CPU tuning):

  .\start_app.ps1

macOS / Linux:

  chmod +x start_app.sh
  ./start_app.sh

Open http://localhost:3000 in your browser, click INITIATE LEARNING MODULE, and speak into your microphone!

6. What's Next for Vidya?

Real-Time Video Screen Annotation: Adding LiveKit video input so Vidya can visually inspect handwritten math equations on a student's notebook.
Multilingual Vernacular Voices: Expanding into Hindi, Tamil, Telugu, and Bengali voice models using Murf Falcon's multilingual library.
Automated WhatsApp Progress Reports: Dispatching summary cards and practice reminders to parents after each voice tutoring session.

7. Links & Repository

GitHub Repository: https://github.com/your-org/vidya-ai-tutor
Murf Falcon TTS Docs: https://murf.ai/api/docs/text-to-speech/streaming
LiveKit Agents SDK: https://docs.livekit.io/agents

Built with passion during the #VoiceForBharat 10 Days Voice Agent Challenge powered by Murf AI.