README.md

metadata

title: SHADOW Kenyan Fraud Intelligence
emoji: 🛡️
colorFrom: red
colorTo: gray
sdk: streamlit
sdk_version: 1.35.0
app_file: app.py
pinned: false

SHADOW — Kenyan Fraud Intelligence System

AMD Developer Hackathon 2026 · Agentic AI Track

Project Overview

Shadow is an advanced OSINT + LLM Hybrid Agentic Pipeline designed specifically to detect, analyze, and neutralize Kenyan-specific mobile fraud vectors. The system mitigates the impact of localized scams such as M-Pesa reversal fraud, Fuliza exploitation, KRA impersonation, and betting-related phishing.

Shadow solves the "Data Cold Start" problem by employing a hybrid architecture: it merges deterministic Open Source Intelligence (OSINT) with an explainable, multi-agent Large Language Model (LLM) pipeline. This ensures highly accurate classification, context-aware reasoning, and actionable mitigation strategies tailored to the Kenyan demographic, including support for English, Swahili, and Sheng dialects.

Architecture Diagram

[ Incoming SMS / Message ]
           │
           ▼
┌──────────────────────────┐
│  OSINT Intelligence Layer│
│  (core/osint_dataset.py) │
│  - Deterministic Check   │
│  - Keyword Matching      │
│  - Scam Taxonomy Mapping │
└──────────┬───────────────┘
           │
           ▼
┌──────────────────────────┐
│  Agent Pipeline Engine   │
│  (agents/pipeline.py)    │
│                          │
│  1. Language Agent       │
│  2. Threat Agent         │
│  3. Risk Agent           │
│  4. Action Agent         │
└──────────┬───────────────┘
           │
           ▼
┌──────────────────────────┐
│  AMD vLLM / Qwen Bridge  │
│  (core/llm_client.py)    │
│  - Context Injection     │
│  - Reasoning Engine      │
└──────────┬───────────────┘
           │
           ▼
[ Explainable JSON Output & Execution Log ]
           │
           ▼
┌──────────────────────────┐
│  Streamlit Live Dashboard│
│  (app/main.py)           │
│  - Real-time Analysis UI │
│  - Execution Timeline    │
│  - Risk Scoring Display  │
└──────────────────────────┘

Agent Pipeline Flow

1. OSINT Pre-Analysis (Hybrid Intelligence Mode): Messages are instantly matched against known Kenyan scam topologies to provide a deterministic baseline.
2. Language Agent: Detects the dialect (English, Swahili, Sheng) and standardizes the context for subsequent analysis.
3. Threat Agent: Analyzes the intent of the message based on localized threat vectors.
4. Risk Agent: Computes a continuous risk score (0-100) and categorizes severity.
5. Action Agent: Determines the recommended user action (e.g., Block, Report to Safaricom, Ignore).

Features

• Kenyan Fraud Detection: Specialized in detecting hyper-local scams (e.g., M-Pesa, Fuliza, KRA, Hustler Fund).
• Sheng + Swahili Language Detection: Seamlessly processes colloquialisms and mixed-language SMS typical in East Africa.
• OSINT-Driven Classification: Fuses known deterministic scam indicators with probabilistic AI reasoning.
• Explainable AI Logs (execution_log): Glass-box observability that documents the exact reasoning step-by-step for full transparency.
• Streamlit Live Dashboard: Interactive real-time web UI for threat analysis and execution timeline visualization.
• AMD Hardware Optimized: Built to run on the AMD Developer Cloud utilizing vLLM and Qwen models, with a robust fallback mock mode for deterministic demos.

Quick Start

pip install -r requirements.txt
streamlit run app/main.py

How to Run

1. Install Dependencies

pip install -r requirements.txt

2. Configure Environment

# Copy the example environment file and add your AMD Cloud API key (optional — mock mode works without it)
cp .env.example .env

3. Launch the Streamlit Dashboard (Primary Interface)

streamlit run app/main.py

The dashboard runs at http://localhost:8501 and provides a full interactive UI for submitting messages, viewing risk scores, agent reasoning, and the step-by-step execution timeline.

4. Run Pipeline Smoke Tests (CLI)

python scripts/test_pipeline.py

Future Work

• AMD MI300X Deployment: Fully scale the vLLM integration on AMD MI300X infrastructure for enterprise-grade throughput.
• WhatsApp Bot Integration: Directly parse user-forwarded messages for instant fraud scoring.