---
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
```bash
# 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