README.md

---
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.

```bash
# 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:
   ```env
   GROQ_API_KEY=your_groq_api_key
   ```

### 3. Start the Server
Run the FastAPI application locally:
```bash
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