Gmail Intelligent Email Classification System

An automated, intelligent email processing system that fetches emails from Gmail, classifies them using a Large Language Model (LLM), and organizes them into specific labels (folders) automatically.

🚀 Features

• Intelligent Classification: Uses advanced LLMs (via OpenRouter/OpenAI SDK) to analyze email content and intent.
• Automated Labeling: Automatically applies labels like "Promotions & Sales", "Account Security Alerts", "Order Confirmations", etc.
• Inbox Cleanup: Archives processed emails from the Inbox to keep your workspace clutter-free.
• Idempotency: Local SQLite database tracks processed emails to prevent duplicate processing.
• Robust Logging: Detailed logging of every step, from API calls to LLM reasoning.
• Visual Reporting: Includes a utility script view_emails.py to inspect processed email history in a readable table.
• Secure: Uses OAuth2 for Gmail API access; credentials stay local.

📋 Prerequisites

• Python 3.10 or higher
• A Google Cloud Project with the Gmail API enabled
• credentials.json for OAuth Client ID from Google Cloud
• An API Key for an LLM provider (OpenRouter, OpenAI, etc.)

🛠️ Installation

1. Clone the repository:

   git clone <repository_url>
   cd <repository_directory>

2. Install dependencies:

   pip install -r requirements.txt

3. Setup Google Credentials:

   • Place your credentials.json file (downloaded from Google Cloud Console) in the project root.
   • Ensure your email is added as a "Test User" in the OAuth Consent Screen configuration.

4. Configure Environment:

   • Create a .env file in the project root:

     LLM_API_KEY=your_api_key_here

   • (Optional) Adjust settings in src/config.py to change the model (default: openai/gpt-4o-mini) or polling intervals.

▶️ Usage

Start the Classifier

Run the main application loop:

python3 run.py

On the first run, it will open a browser window for you to authenticate with your Google account.

View Processed Emails

To see a log of what has been classified:

python3 view_emails.py

📂 Project Structure

├── run.py                 # Application entry point
├── view_emails.py         # Utility to view database records
├── requirements.txt       # Python dependencies
├── credentials.json       # (User provided) Google OAuth credentials
├── .env                   # (User provided) API keys
├── src/
│   ├── __init__.py
│   ├── config.py          # Configuration & Settings
│   ├── main.py            # Orchestrator logic
│   ├── gmail_client.py    # Gmail API Wrapper
│   ├── llm_engine.py      # LLM Integration logic
│   ├── processor.py       # Email parsing & cleaning
│   ├── storage.py         # SQLite database handler
│   └── logger.py          # Logging configuration
└── processed_emails.db    # Local SQLite database (auto-generated)

⚙️ Configuration

You can tweak the system behavior in src/config.py:

• POLL_INTERVAL: Seconds to wait between batch fetches (default: 60).
• MAX_EMAILS_PER_BATCH: Number of emails to process per cycle.
• LLM_MODEL_NAME: The model ID to use (e.g., openai/gpt-4o-mini, google/gemini-pro-1.5).

🛡️ Troubleshooting

• 403 Access Denied: Ensure your email is added to the "Test Users" list in Google Cloud Console.
• Model 404 Errors: Verify the LLM_MODEL_NAME in src/config.py exists on your LLM provider's platform.
• "App locked": If the script crashed, delete the app.lock file manually.