README.md

metadata

title: AI Gmail Agent
emoji: 📧
colorFrom: indigo
colorTo: purple
sdk: docker
app_port: 7860
pinned: false

📧 AI Gmail Agent & Intelligent Assistant

An autonomous AI-powered assistant that reads your unread Gmail inbox, categorizes incoming emails using Groq (Llama 3), filters out noise/job alerts/automated replies, saves drafts for medium/low priority messages, and automatically replies to urgent/high-priority messages.

All of this is monitored via a sleek, interactive, glassmorphism telemetry dashboard!

---

🚀 Key Features

• Smart Email Categorization: Uses Groq LLM to categorize emails (e.g. Sales, Question, Support, Newsletter, Personal, etc.).
• Automated Replying: Instantly drafts and auto-sends personalized replies to urgent, high-priority emails.
• Drafting Engine: Crafts high-quality responses and saves them directly as drafts in your Gmail account for review.
• Intelligent Noise Filtering: Detects spam, automated no-reply mail, and job alert digests, archiving/marking them read automatically without wasting LLM resources.
• SQL Database Thread Tracking: Saves audit logs of every categorization, priority level, action taken, and timestamp in a local SQLite database.
• Vibrant Telemetry Dashboard: Modern, real-time glassmorphism web interface served directly from the FastAPI backend.

---

🔒 Security & Cloud Deployment (Hugging Face Secrets)

This agent is built to be cloud-native and secure. Do not upload your local token.json or .env files directly to the public repository. Instead, configure them as secure environment variables (Repository Secrets) in your Hugging Face Space settings:

Required Secrets

1. GROQ_API_KEY: Your Groq Console API key (e.g. gsk_...).
2. GMAIL_TOKEN_JSON: The exact contents of your local token.json file.
   • Run the agent locally first to complete the Google OAuth login.
   • Once successfully logged in, open the newly created token.json file in the root.
   • Copy the entire JSON content, and paste it into the GMAIL_TOKEN_JSON secret in Hugging Face.

Optional Config (Variables)

• POLL_INTERVAL: How often the worker checks Gmail for new unread mail (defaults to 60 seconds).

---

💻 Running Locally

1. Requirements & Setup

Ensure you have Python 3.10+ installed.

# Clone the repository
git clone <your-repo-url>
cd gmail-ai-agent

# Install dependencies
pip install -r requirements.txt

2. Configure Credentials

1. Obtain Google OAuth credentials.json from the Google Cloud Console (enabled for the Gmail API with https://www.googleapis.com/auth/gmail.modify scopes).
2. Create a .env file in the root directory:

   GROQ_API_KEY=your_groq_api_key
   

3. Start the Server

Run the FastAPI application locally:

uvicorn main:app --reload --port 7860

Upon running, your browser will open to complete the Google Gmail authorization flow and save your token.json. Once authorized, you can access the premium dashboard at http://localhost:7860.

---

🛠 Tech Stack

• Backend: Python 3.10, FastAPI, Uvicorn, SQLAlchemy (SQLite)
• LLM Engine: Groq SDK (Llama 3 / Mixtral)
• Gmail Engine: Google API Python Client & Google OAuth
• Frontend: HTML5, Vanilla CSS3 (Custom Glassmorphic HSL Design), JavaScript ES6 (Fetch Telemetry API), FontAwesome 6
• Deployment: Docker, Hugging Face Spaces