GmailAI Assistant — Commercial AI Desktop Email Platform

Privacy-First Hybrid AI Email Assistant for Windows

---

🌟 Executive Overview

GmailAI Assistant is a commercial-grade desktop application that triages, analyzes, and drafts intelligent responses for your Gmail inbox. It combines an on-device Local AI Engine (Ollama) with a Cloud AI Engine (Google Gemini & OpenAI) and a Heuristic Rule Engine with strict safety guardrails.

🔑 Key Features

• ⚡ 1-Click Google Sign-In: Authenticate securely in your default browser and auto-sync with zero configuration.
• 📥 Intelligence Inbox: Automatic multi-category classification across 11 standard enterprise categories (CLIENT, WORK, BANK, FINANCE, LEGAL, NEWSLETTER, PROMOTION, SOCIAL, ADVERTISEMENT, SPAM, PERSONAL).
• 🧠 Hybrid AI Router:
  • Queries Local AI (Ollama) for zero latency & complete on-device privacy.
  • If confidence is $< 85%$ or Ollama is offline, gracefully routes to Cloud AI (Google Gemini 2.5/3 or OpenAI GPT-4o-mini).
  • Falls back to a deterministic Heuristic Rule Engine with 40+ domain maps for $100%$ zero-crash reliability.
• 🎨 Light & Dark Themes: Choose between Clean Slate Light Mode (Default) and Obsidian Midnight Dark Mode (#060913).
• 🧹 Smart Cleanup: Batch-review and approve cleanup recommendations to archive newsletters and promotional spam in 1 click.
• 💬 AI Reply Assistant: Context-aware drafting in 6 distinct tones (Professional, Friendly, Short, Detailed, Apology, Follow-up) with automatic Gmail draft synchronization.
• 📋 Daily Briefings: Executive summaries, pending deadlines, and VIP requests aggregated into account-isolated daily briefings.
• 🛡️ Privacy & Safety Guardrails: Sensitive categories (Banking, Legal, Work VIPs) are protected from accidental modifications. Trashing and permanent deletions require explicit user confirmation.
• 💾 Local Encrypted Storage & Privacy: OAuth credentials and backup archives are encrypted with machine-salted AES-256. Email caches remain strictly on your local device.

---

🚀 Quickstart

Prerequisites

• Python 3.10+ (Python 3.12 recommended)
• (Optional) Ollama running locally with qwen2.5:latest or llama3.1:latest
• (Optional) Google Gemini API Key (Recommended, free tier available) or OpenAI API Key

Installation

# 1. Clone the repository
git clone https://github.com/hamidhussein/gmail_ai_agent.git
cd gmail_ai_agent

# 2. Create virtual environment
python -m venv venv
.\venv\Scripts\activate

# 3. Install dependencies
pip install -r requirements.txt

# 4. Launch the application
python run.py

---

🔐 Google Cloud OAuth 2.0 Setup Guide

To connect your real Gmail account with Google's official OAuth 2.0 flow:

1. Create a Google Cloud Project:

   • Go to Google Cloud Console and create a new project (e.g. Gmail AI Assistant).

2. Enable Gmail API:

   • In your project, go to APIs & Services → Library, search for Gmail API, and click Enable.

3. Configure OAuth Consent Screen:

   • Go to APIs & Services → OAuth consent screen.
   • Select External, fill in the App name (GmailAI) and your email address.
   • Important: Under Test users, click + ADD USERS and add your Gmail address (e.g., [email protected]).

4. Create OAuth Client ID:

   • Go to APIs & Services → Credentials → Create Credentials → OAuth Client ID.
   • Choose Desktop app as the Application type, name it GmailAI, and click Create.
   • Click Download JSON (⬇).

5. Connect in App:

   • In GmailAI, go to Settings & AI → Step 5: Paste credentials.json content, paste the JSON, and click Save Credentials & Connect Gmail!

Tip

Developer Testing vs Public Distribution:

• Private Testing Mode: In the Google Cloud Console, keeping the app in "Testing" mode allows you and up to 100 manually added Test Users to connect instantly without Google verification. If Google displays "Google hasn't verified this app", click Advanced → Go to Gmail AI Assistant (unsafe) → Continue.
• Public Distribution Mode: Distributing the app publicly to unlisted users requires completing the Google OAuth App Verification Process. See PUBLISHING_CHECKLIST.md for full compliance instructions.

---

📦 Building Standalone Windows Executable (.exe)

Compile the entire application into a standalone Windows .exe using PyInstaller:

python installer/build_exe.py

The compiled standalone executable will be generated in the dist/ directory:

dist/
└── GmailAI Assistant/
    └── GmailAI Assistant.exe

---

⚙️ Configuration & Architecture

gmail_ai_agent/
├── app/
│   ├── main.py                  # Flet application shell & navigation coordinator
│   ├── config.py                # Persistent user configuration
│   └── constants.py             # Enums: Categories, ActionTypes, Risk, Tones
├── core/
│   ├── logger.py                # Rotating structured audit logger
│   ├── security.py              # Cryptography (AES-GCM/Fernet) & Safety policies
│   ├── exceptions.py            # Typed domain exceptions
│   └── events.py                # Thread-safe bidirectional event bus
├── authentication/
│   ├── oauth_manager.py         # Google OAuth 2.0 background threaded flow
│   ├── token_manager.py         # Encrypted token persistence
│   └── credential_manager.py    # Google Cloud credentials parser & validator
├── gmail/
│   ├── client.py                # Gmail API client with retry backoff
│   ├── reader.py                # Batch message synchronizer & fetcher
│   ├── parser.py                # Multi-part MIME decoding & HTML entity sanitizer
│   └── actions.py               # Safe Gmail modifications & draft creator
├── ai/
│   ├── router.py                # Hybrid AI Router (Local -> Cloud -> Heuristic)
│   ├── local_model.py           # Fast-offline Ollama REST client
│   ├── cloud_model.py           # OpenAI API client
│   ├── classifier.py            # 11-category classifier & 40+ domain heuristic engine
│   ├── summarizer.py            # Email & thread summarizer
│   └── reply_generator.py       # Context-aware 6-tone reply assistant
├── database/
│   ├── models.py                # SQLAlchemy ORM models
│   ├── repository.py            # Thread-safe database repository
│   └── migrations.py            # Auto-migrations & demo dataset seeder
├── ui/
│   ├── dashboard.py             # Executive overview & real-time metrics
│   ├── inbox_view.py            # Intelligence Inbox with Markdown reader & avatars
│   ├── review_screen.py         # Smart cleanup batch review screen
│   ├── digests_view.py          # Daily executive morning briefings
│   ├── audit_view.py            # Complete security & action audit logs
│   ├── settings.py              # Settings, AI model switcher, & OAuth wizard
│   └── components/
│       ├── google_auth_modal.py # 1-Click Google Sign-In dialog
│       ├── reply_modal.py       # AI Reply assistant modal
│       └── stat_card.py         # Glassmorphic statistic cards
└── run.py                       # Modern Flet application runner

---

🛡️ Security & Privacy Architecture

1. Zero Data Telemetry: Your emails never leave your machine unless you explicitly enable Cloud AI.
2. Encrypted Token Vault: OAuth tokens are salted and encrypted on disk using machine-level AES-256 keys.
3. Double Verification Policy: Trashing and deletion actions are never automated.
4. Offline First: Runs completely offline using local Ollama models or heuristic classification when no internet connection is available.

---

📄 License

This project is licensed under the MIT License.