README.md

metadata

title: Email Rule Agent - AI-Powered Email Organization Assistant
emoji: 📧
colorFrom: blue
colorTo: purple
sdk: gradio
sdk_version: 4.44.0
app_file: app.py
pinned: false
tags:
  - agent-demo-track
  - gradio
  - ai-agents
  - mcp
  - email-management
license: mit

🤖 Email Rule Agent - AI-Powered Email Organization Assistant

Track 3: Agentic Demo Showcase submission for the Gradio Agents & MCP Hackathon 2025

🎥 Demo Video

Watch the demo video here

🌟 Overview

Email Rule Agent is an intelligent email management assistant that uses AI agents to help users organize their inbox through natural language commands. Simply describe what you want in plain English, and the AI agent will create smart rules to automatically organize your emails.

Key Innovation: Combines conversational AI with the Model Context Protocol (MCP) to provide a seamless, intelligent email management experience that learns from your preferences and adapts to your workflow.

✨ Key Features

🧠 AI-Powered Natural Language Understanding

• Conversational Rule Creation: Just say "Move all Uber receipts to my travel folder" or "Archive old newsletters"
• Context-Aware Processing: Understands references like "those emails" or "emails from last week"
• Smart Pattern Recognition: Analyzes your inbox to suggest organization rules

📋 Intelligent Rule Management

• Preview Before Apply: See exactly which emails will be affected before confirming
• Confidence Scoring: Each rule comes with a confidence level
• Rule Lifecycle: Accept, reject, archive, or reactivate rules as needed
• Batch Operations: Apply rules to multiple emails at once

🔄 Real-Time MCP Integration

• Client-Server Architecture: Uses MCP protocol for robust data management
• Session Isolation: Each user gets their own workspace
• Persistent Storage: Rules and preferences are saved
• Mock & Real Data: Demo mode with sample emails or connect your Gmail

🎨 Modern User Experience

• Three-Column Layout: Chat interface, rule management, and email preview
• Real-Time Updates: Toast notifications for all actions
• Streaming Responses: See AI thinking in real-time
• Interactive Demo: Built-in checklist guides new users

🚀 Try It Out

1. Start with the Demo: Click "Analyze my inbox" to see pattern detection in action
2. Create Natural Language Rules: Try commands like:
   • "Archive all marketing emails older than 30 days"
   • "Move receipts to my expenses folder"
   • "Label all work emails as important"
3. Preview and Apply: Review which emails match before applying rules
4. Manage Your Rules: Accept, reject, or modify rules as needed

🏗️ Architecture

┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
│                 │     │                  │     │                 │
│  Gradio UI      │────▶│  MCP Client      │────▶│  Modal Backend  │
│  (Frontend)     │     │  (Protocol)      │     │  (MCP Server)   │
│                 │     │                  │     │                 │
└─────────────────┘     └──────────────────┘     └─────────────────┘
        │                                                  │
        │                                                  │
        ▼                                                  ▼
┌─────────────────┐                              ┌─────────────────┐
│  AI Agent       │                              │  Email Provider │
│  (CrewAI +      │                              │  (Gmail/Mock)   │
│   OpenRouter)   │                              │                 │
└─────────────────┘                              └─────────────────┘

MCP Integration

• MCP Client: Handles all communication with the backend server
• Standardized Endpoints: /emails, /rules, /auth following MCP conventions
• Session Management: Automatic session handling for multi-user support
• Error Handling: Graceful fallbacks and user-friendly error messages

🛠️ Technical Stack

• Frontend: Gradio 4.0+ with custom components
• AI Agent: CrewAI with OpenRouter (supports multiple LLMs)
• Backend: Modal serverless platform
• Protocol: Model Context Protocol (MCP)
• Languages: Python 3.10+
• Key Libraries: pandas, httpx, python-dotenv

📦 Installation & Setup

Option 1: Use This Space

Simply use this Hugging Face Space - it's already configured and ready to go!

Option 2: Local Development

# Clone the repository
git clone https://huggingface.co/spaces/YOUR_USERNAME/email-rule-agent
cd email-rule-agent

# Install dependencies
pip install -r requirements.txt

# Set environment variables
export OPENROUTER_API_KEY="your-api-key"
export MODAL_BACKEND_URL="your-modal-url"  # or use --local flag

# Run the app
python app.py --local  # For local/mock mode
python app.py         # For production mode

Required Secrets (for HF Spaces)

• OPENROUTER_API_KEY: Your OpenRouter API key for AI capabilities
• MODAL_BACKEND_URL: Your Modal backend URL (optional, uses mock data if not set)

📸 Screenshots

Main Interface

The three-column layout provides an intuitive workflow:

• Left: Chat with the AI agent
• Center: Manage your rules
• Right: Preview affected emails

Natural Language Processing

Simply describe what you want in plain English, and the AI understands your intent.

Rule Preview

See exactly which emails will be affected before applying any rule.

🏆 Why This Matters

Email overload is a universal problem. This project demonstrates how AI agents can:

• Understand Intent: No need to learn complex filter syntax
• Learn Patterns: Automatically identify email categories
• Save Time: Automate repetitive organization tasks
• Stay in Control: Preview and approve all actions

🔮 Future Enhancements

• Multi-Provider Support: Outlook, Yahoo Mail integration
• Advanced Actions: Smart replies, calendar integration
• Team Features: Shared rules and collaborative filtering
• Mobile App: Native mobile experience

👥 Team

Created with ❤️ for the Gradio Agents & MCP Hackathon 2025

📄 License

MIT License - feel free to use and extend!

---

Note: This is a hackathon project demonstrating the potential of AI agents and MCP. For production use, ensure proper security measures and API rate limiting.