README.md

metadata

title: ScamVerifierV3
emoji: 💻
colorFrom: pink
colorTo: indigo
sdk: gradio
sdk_version: 5.42.0
app_file: app.py
pinned: false
license: mit
short_description: '"Instantly detect and flag potential online scams"'

🛡️ Scam-Signal Verifier

A sophisticated AI-powered tool designed to protect students, elderly users, and everyone else from phishing attacks and fraudulent advertisements. This multi-agent system analyzes suspicious messages, URLs, and claims to provide risk assessments and actionable recommendations.

🎯 Problem Statement

Students and elderly individuals are particularly vulnerable to:

• Phishing emails and text messages
• Fake seller advertisements
• Investment scams
• Social media fraud
• Suspicious URLs and links

💡 Solution

The Scam-Signal Verifier uses a multi-agent AI system to:

1. Extract Claims & Information - Parse text/URLs to identify key claims, contact info, and red flags
2. Verify & Fact-Check - Cross-reference claims against known scam patterns and analyze URLs
3. Generate Human-Friendly Guidance - Provide clear explanations and next steps

🤖 Multi-Agent Architecture

Agent 1: Extractor

• Parses input text and URLs
• Identifies key claims and promises
• Extracts contact information
• Flags urgency indicators and suspicious language
• Categorizes the main topic/context

Agent 2: Verifier

• Analyzes URLs for suspicious characteristics
• Fact-checks claims using AI knowledge
• Checks for common scam patterns
• Calculates overall risk score (0-100)

Agent 3: Explainer

• Generates user-friendly explanations
• Provides specific recommendations
• Suggests next steps (report, block, verify)
• Offers general safety tips

🚀 Features

• Real-time Analysis - Instant scam detection and risk assessment
• Multi-format Support - Analyze text messages, emails, URLs, and social media posts
• Risk Scoring - Clear 0-100 risk score with color-coded indicators
• Detailed Explanations - Non-technical, actionable guidance
• Technical Details - Advanced users can view detailed analysis
• Responsive Design - Clean, professional UI that works on all devices

📊 Risk Assessment Levels

• 🚨 HIGH RISK (70-100) - Likely scam, avoid immediately
• ⚠️ MEDIUM RISK (40-69) - Be cautious, verify before acting
• ✅ LOW RISK (0-39) - Appears safe, but stay vigilant

🛠️ Technical Implementation

Technologies Used

• Backend: Python with OpenAI GPT-4o-mini
• Frontend: Gradio for clean, responsive UI
• API: OpenAI API for multi-agent reasoning
• Deployment: Hugging Face Spaces

Key Components

• Multi-agent orchestration for specialized analysis tasks
• Heuristic rule engine combined with LLM reasoning
• URL analysis for link safety verification
• Pattern matching for common scam indicators
• Risk scoring algorithm based on multiple factors

🔧 Installation & Setup

Prerequisites

• Python 3.8+
• OpenAI API key

Local Development

# Clone the repository
git clone <your-repo-url>
cd scam-signal-verifier

# Install dependencies
pip install -r requirements.txt

# Set your OpenAI API key
export OPENAI_API_KEY="your-api-key-here"

# Run the application
python app.py

Hugging Face Deployment

1. Create a new Space on Hugging Face
2. Upload app.py and requirements.txt
3. Set OPENAI_API_KEY as a secret in your Space settings
4. The app will automatically deploy

📝 Usage Examples

Example 1: Phishing Email

Input: "URGENT: Your PayPal account will be suspended in 24 hours. Click here to verify: http://paypal-security-check.suspicious-domain.com"

Output:

• Risk Score: 85/100 (HIGH RISK)
• Key issues: Urgency tactics, suspicious URL, impersonation
• Recommendation: Block sender, report to PayPal

Example 2: Investment Scam

Input: "Make $5000/week working from home! No experience needed. Limited time offer! Text 'START' to 555-SCAM"

Output:

• Risk Score: 78/100 (HIGH RISK)
• Key issues: Unrealistic income promises, urgency, vague details
• Recommendation: Ignore and block number

Example 3: Legitimate Message

Input: "Hi, this is Amazon confirming your order #123456789. Your package will arrive tomorrow."

Output:

• Risk Score: 15/100 (LOW RISK)
• Key issues: None significant
• Recommendation: Verify order number in your Amazon account

🎓 Educational Value

This project demonstrates:

• AI/ML Concepts: Multi-agent systems, prompt engineering, risk assessment
• Cybersecurity: Phishing detection, URL analysis, social engineering awareness
• Social Impact: Protecting vulnerable populations from fraud
• Software Engineering: Clean architecture, user experience design, API integration

🔒 Privacy & Security

• No Data Storage: Messages are processed in real-time and not stored
• API Security: OpenAI API calls are made securely with proper authentication
• Privacy First: No personal information is collected or retained
• Open Source: Code is transparent and auditable

🚀 Future Enhancements

• Multi-language Support - Analyze scams in different languages
• Image Analysis - Detect fraudulent images and fake screenshots
• Browser Extension - Real-time protection while browsing
• Community Reports - Crowdsourced scam database
• Mobile App - Native iOS/Android applications
• Advanced ML - Custom-trained models for scam detection

🤝 Contributing

Contributions are welcome! This project has significant potential for impact in cybersecurity education and fraud prevention.

Areas for Contribution:

• Additional scam pattern detection
• UI/UX improvements
• Performance optimizations
• Multi-language support
• Testing and validation

📄 License

This project is open source and available under the MIT License.

🙏 Acknowledgments

• Built for educational purposes and social good
• Designed to protect vulnerable populations from online fraud
• Demonstrates practical application of AI for cybersecurity

---

⚠️ Disclaimer: This tool provides guidance but cannot guarantee 100% accuracy. Always use your judgment and consult official sources when in doubt. If you believe you've encountered a scam, report it to local authorities and relevant platforms.

Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference