feat: Cloud-ready release of AI Gmail Agent with premium glassmorphism telemetry dashboard and Dockerfile

.dockerignore

@@ -0,0 +1,14 @@
+__pycache__/
+*.py[cod]
+.git/
+.env
+.env.*
+env/
+venv/
+emails.db
+logs/
+*.log
+credentials.json
+token.json
+.DS_Store
+README.md

.gitignore

@@ -0,0 +1,26 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Environments
+.env
+.env.*
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# SQLite Databases & logs
+emails.db
+logs/
+*.log
+
+# Sensitive Google Credentials
+credentials.json
+token.json
+
+# OS specific files
+.DS_Store
+Thumbs.db

Dockerfile

@@ -0,0 +1,39 @@
+# Use an official lightweight Python base image
+FROM python:3.10-slim
+
+# Set environment variables
+ENV PYTHONDONTWRITEBYTECODE=1
+ENV PYTHONUNBUFFERED=1
+ENV PORT=7860
+
+# Set working directory
+WORKDIR /code
+
+# Install system dependencies if any are needed
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    build-essential \
+    && rm -rf /var/lib/apt/lists/*
+
+# Copy requirements and install dependencies
+COPY requirements.txt /code/
+RUN pip install --no-cache-dir --upgrade -r requirements.txt
+
+# Create directories and files with write access for Hugging Face non-root user (UID 1000)
+RUN mkdir -p /code/logs && \
+    touch /code/emails.db && \
+    chmod -R 777 /code
+
+# Copy the rest of the application code
+COPY . /code/
+
+# Set ownership of the application directory to the non-root user (UID 1000)
+RUN chown -R 1000:1000 /code
+
+# Switch to the non-root user (Hugging Face standard)
+USER 1000
+
+# Expose port 7860 (Hugging Face standard port)
+EXPOSE 7860
+
+# Command to run the FastAPI app
+CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "7860"]

README.md

@@ -0,0 +1,82 @@
+---
+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

app/ai/groq_client.py

@@ -0,0 +1,34 @@
+from groq import Groq
+from config import GROQ_API_KEY
+
+client = Groq(api_key=GROQ_API_KEY)
+
+SYSTEM_PROMPT = """
+You are a professional AI email assistant.
+
+Rules:
+- Reply professionally
+- Keep responses concise
+- Avoid hallucinations
+- Never promise unavailable actions
+"""
+
+def generate_ai_reply(email_text: str):
+
+    completion = client.chat.completions.create(
+        model="llama-3.3-70b-versatile",
+        messages=[
+            {
+                "role": "system",
+                "content": SYSTEM_PROMPT
+            },
+            {
+                "role": "user",
+                "content": email_text
+            }
+        ],
+        temperature=0.6,
+        max_tokens=300
+    )
+
+    return completion.choices[0].message.content.strip()

app/gmail/auth.py

@@ -0,0 +1,92 @@
+from google.auth.transport.requests import Request
+from google.oauth2.credentials import Credentials
+from google_auth_oauthlib.flow import InstalledAppFlow
+import os
+import json
+from loguru import logger
+from config import GMAIL_TOKEN_JSON, GMAIL_CREDENTIALS_JSON, GMAIL_TOKEN_FILE, GMAIL_CREDENTIALS_FILE
+
+SCOPES = ["https://www.googleapis.com/auth/gmail.modify"]
+
+def authenticate():
+    creds = None
+
+    # 1. Try loading authorized user token from environment variable
+    if GMAIL_TOKEN_JSON:
+        try:
+            logger.info("🔑 Loading Gmail token from GMAIL_TOKEN_JSON environment variable...")
+            info = json.loads(GMAIL_TOKEN_JSON)
+            creds = Credentials.from_authorized_user_info(info, SCOPES)
+            logger.info("✅ Gmail token successfully loaded from environment variable")
+        except Exception as e:
+            logger.error(f"❌ Failed to load token from GMAIL_TOKEN_JSON environment variable: {e}")
+            creds = None
+
+    # 2. Try loading from local token file
+    if not creds and os.path.exists(GMAIL_TOKEN_FILE):
+        try:
+            logger.info(f"🔑 Loading Gmail token from file: {GMAIL_TOKEN_FILE}...")
+            creds = Credentials.from_authorized_user_file(GMAIL_TOKEN_FILE, SCOPES)
+            logger.info("✅ Gmail token successfully loaded from file")
+        except Exception as e:
+            logger.error(f"❌ Failed to load token from file {GMAIL_TOKEN_FILE}: {e}")
+            creds = None
+
+    # 3. If credentials don't exist or are invalid, handle renewal/flow
+    if not creds or not creds.valid:
+        if creds and creds.expired and creds.refresh_token:
+            try:
+                logger.info("🔄 Gmail access token expired. Refreshing token...")
+                creds.refresh(Request())
+                logger.info("✅ Gmail token successfully refreshed")
+                # If we're local and loaded from file, update the file
+                if os.path.exists(GMAIL_TOKEN_FILE):
+                    try:
+                        with open(GMAIL_TOKEN_FILE, "w") as f:
+                            f.write(creds.to_json())
+                    except Exception as e:
+                        logger.warning(f"Could not save refreshed token to file: {e}")
+            except Exception as e:
+                logger.error(f"❌ Failed to refresh Gmail token: {e}")
+                creds = None
+
+        if not creds:
+            # Check if we are running in a headless environment (like HF Spaces)
+            is_headless = os.getenv("SPACE_ID") is not None or os.getenv("PORT") is not None
+            
+            if is_headless:
+                logger.error("❌ Gmail authorization is missing. In headless/cloud environments, please set GMAIL_TOKEN_JSON environment variable with your token.json contents!")
+                raise RuntimeError("Gmail credentials are not configured. Please set GMAIL_TOKEN_JSON environment variable in Hugging Face Secrets.")
+
+            logger.info("🌐 Authenticating via local browser flow...")
+            
+            # Determine how to load client secrets
+            if GMAIL_CREDENTIALS_JSON:
+                try:
+                    secrets_info = json.loads(GMAIL_CREDENTIALS_JSON)
+                    flow = InstalledAppFlow.from_client_config(secrets_info, SCOPES)
+                except Exception as e:
+                    logger.error(f"❌ Failed to parse client secrets from GMAIL_CREDENTIALS_JSON: {e}")
+                    raise
+            elif os.path.exists(GMAIL_CREDENTIALS_FILE):
+                flow = InstalledAppFlow.from_client_secrets_file(GMAIL_CREDENTIALS_FILE, SCOPES)
+            else:
+                logger.error(f"❌ Missing client credentials. GMAIL_CREDENTIALS_FILE ({GMAIL_CREDENTIALS_FILE}) not found!")
+                raise FileNotFoundError(f"Missing {GMAIL_CREDENTIALS_FILE} or GMAIL_CREDENTIALS_JSON environment variable.")
+
+            try:
+                creds = flow.run_local_server(
+                    port=8080,
+                    prompt="consent",
+                    access_type="offline",
+                    open_browser=True
+                )
+                
+                with open(GMAIL_TOKEN_FILE, "w") as f:
+                    f.write(creds.to_json())
+                logger.info(f"✅ Authorization successful! token saved to {GMAIL_TOKEN_FILE}")
+            except Exception as e:
+                logger.error(f"❌ Authorization flow failed: {e}")
+                raise
+
+    return creds

app/gmail/parser.py

@@ -0,0 +1,38 @@
+import base64
+from bs4 import BeautifulSoup
+
+def extract_email_body(payload):
+
+    if "parts" in payload:
+
+        for part in payload["parts"]:
+
+            data = part["body"].get("data")
+
+            if not data:
+                continue
+
+            decoded = base64.urlsafe_b64decode(
+                data
+            ).decode(errors="ignore")
+
+            mime = part.get("mimeType")
+
+            if mime == "text/html":
+                return BeautifulSoup(
+                    decoded,
+                    "html.parser"
+                ).get_text()
+
+            return decoded
+
+    else:
+
+        data = payload["body"].get("data")
+
+        if data:
+            return base64.urlsafe_b64decode(
+                data
+            ).decode(errors="ignore")
+
+    return ""

app/gmail/service.py

@@ -0,0 +1,171 @@
+import base64
+import re
+from email.mime.text import MIMEText
+from email.mime.multipart import MIMEMultipart
+from google.oauth2.credentials import Credentials
+from google_auth_oauthlib.flow import InstalledAppFlow
+from google.auth.transport.requests import Request
+from googleapiclient.discovery import build
+import os
+import pickle
+from loguru import logger
+from config import GMAIL_CREDENTIALS_FILE, GMAIL_TOKEN_FILE
+
+SCOPES = [
+    "https://www.googleapis.com/auth/gmail.readonly",
+    "https://www.googleapis.com/auth/gmail.send",
+    "https://www.googleapis.com/auth/gmail.modify",
+]
+
+# ── Patterns that indicate no-reply / automated senders ──────────────────────
+NO_REPLY_PATTERNS = [
+    r"no.?reply",
+    r"do.?not.?reply",
+    r"noreply",
+    r"donotreply",
+    r"mailer.?daemon",
+    r"notifications?@",
+    r"alerts?@",
+    r"updates?@",
+    r"newsletter@",
+    r"automated@",
+    r"system@",
+    r"bounce@",
+]
+
+# ── Known job-alert domains / senders ────────────────────────────────────────
+JOB_ALERT_PATTERNS = [
+    r"naukri\.com",
+    r"linkedin\.com",
+    r"indeed\.com",
+    r"monster\.com",
+    r"shine\.com",
+    r"foundit\.in",
+    r"internshala\.com",
+    r"wellfound\.com",
+    r"angellist\.com",
+    r"jobs\.google\.com",
+    r"glassdoor\.com",
+]
+
+
+def get_gmail_service():
+    creds = None
+    if os.path.exists(GMAIL_TOKEN_FILE):
+        with open(GMAIL_TOKEN_FILE, "rb") as token:
+            creds = pickle.load(token)
+
+    if not creds or not creds.valid:
+        if creds and creds.expired and creds.refresh_token:
+            creds.refresh(Request())
+        else:
+            flow = InstalledAppFlow.from_client_secrets_file(GMAIL_CREDENTIALS_FILE, SCOPES)
+            creds = flow.run_local_server(port=0)
+        with open(GMAIL_TOKEN_FILE, "wb") as token:
+            pickle.dump(creds, token)
+
+    return build("gmail", "v1", credentials=creds)
+
+
+def fetch_unread_emails(service, max_results: int = 10) -> list[dict]:
+    """Fetch unread emails from inbox (excludes promotions/spam labels)."""
+    results = service.users().messages().list(
+        userId="me",
+        labelIds=["INBOX", "UNREAD"],
+        maxResults=max_results,
+        q="-label:SPAM -label:CATEGORY_PROMOTIONS"
+    ).execute()
+
+    messages = results.get("messages", [])
+    emails = []
+
+    for msg in messages:
+        detail = service.users().messages().get(
+            userId="me", id=msg["id"], format="full"
+        ).execute()
+        emails.append(parse_email(detail))
+
+    return emails
+
+
+def parse_email(raw_message: dict) -> dict:
+    headers = {h["name"]: h["value"] for h in raw_message["payload"]["headers"]}
+    body = extract_body(raw_message["payload"])
+    gmail_labels = raw_message.get("labelIds", [])
+
+    return {
+        "id":         raw_message["id"],
+        "sender":     headers.get("From", ""),
+        "subject":    headers.get("Subject", "(No Subject)"),
+        "body":       body[:3000],           # limit to 3k chars for LLM
+        "labels":     gmail_labels,
+        "is_spam":    "SPAM" in gmail_labels or "CATEGORY_PROMOTIONS" in gmail_labels,
+    }
+
+
+def extract_body(payload: dict) -> str:
+    body = ""
+    if "parts" in payload:
+        for part in payload["parts"]:
+            if part["mimeType"] == "text/plain" and "data" in part.get("body", {}):
+                body += base64.urlsafe_b64decode(part["body"]["data"]).decode("utf-8", errors="ignore")
+    elif "body" in payload and "data" in payload["body"]:
+        body = base64.urlsafe_b64decode(payload["body"]["data"]).decode("utf-8", errors="ignore")
+    return body.strip()
+
+
+def is_no_reply_sender(sender: str) -> bool:
+    sender_lower = sender.lower()
+    return any(re.search(p, sender_lower) for p in NO_REPLY_PATTERNS)
+
+
+def is_job_alert_email(sender: str, subject: str) -> bool:
+    text = (sender + " " + subject).lower()
+    return any(re.search(p, text) for p in JOB_ALERT_PATTERNS)
+
+
+def send_email(service, to: str, subject: str, body: str) -> bool:
+    try:
+        message = MIMEMultipart()
+        message["to"] = to
+        message["subject"] = f"Re: {subject}"
+        message.attach(MIMEText(body, "plain"))
+
+        raw = base64.urlsafe_b64encode(message.as_bytes()).decode()
+        service.users().messages().send(
+            userId="me", body={"raw": raw}
+        ).execute()
+        logger.success(f"✅ Auto-reply sent to {to}")
+        return True
+    except Exception as e:
+        logger.error(f"❌ Failed to send email to {to}: {e}")
+        return False
+
+
+def save_draft(service, to: str, subject: str, body: str) -> bool:
+    try:
+        message = MIMEMultipart()
+        message["to"] = to
+        message["subject"] = f"Re: {subject}"
+        message.attach(MIMEText(body, "plain"))
+
+        raw = base64.urlsafe_b64encode(message.as_bytes()).decode()
+        service.users().drafts().create(
+            userId="me", body={"message": {"raw": raw}}
+        ).execute()
+        logger.info(f"📝 Draft saved for {to}")
+        return True
+    except Exception as e:
+        logger.error(f"❌ Failed to save draft for {to}: {e}")
+        return False
+
+
+def mark_as_read(service, email_id: str):
+    try:
+        service.users().messages().modify(
+            userId="me",
+            id=email_id,
+            body={"removeLabelIds": ["UNREAD"]}
+        ).execute()
+    except Exception as e:
+        logger.warning(f"Could not mark email {email_id} as read: {e}")

app/models/database.py

@@ -0,0 +1,35 @@
+from sqlalchemy import create_engine, Column, String, DateTime, Boolean, Text
+from sqlalchemy.ext.declarative import declarative_base
+from sqlalchemy.orm import sessionmaker
+from datetime import datetime
+from config import DATABASE_URL
+
+engine = create_engine(DATABASE_URL, connect_args={"check_same_thread": False})
+SessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=engine)
+Base = declarative_base()
+
+
+class ProcessedEmail(Base):
+    __tablename__ = "processed_emails"
+
+    email_id        = Column(String, primary_key=True, index=True)
+    sender          = Column(String)
+    subject         = Column(String)
+    category        = Column(String)          # Recruiter, Client, Spam, etc.
+    priority        = Column(String)          # High, Medium, Low
+    action_taken    = Column(String)          # auto_sent, draft_saved, skipped
+    reply_sent      = Column(Boolean, default=False)
+    processed_at    = Column(DateTime, default=datetime.utcnow)
+    notes           = Column(Text, nullable=True)
+
+
+def init_db():
+    Base.metadata.create_all(bind=engine)
+
+
+def get_db():
+    db = SessionLocal()
+    try:
+        yield db
+    finally:
+        db.close()

app/routes/health.py

@@ -0,0 +1,59 @@
+from fastapi import APIRouter, Depends
+from sqlalchemy.orm import Session
+from sqlalchemy import func
+from app.models.database import get_db, ProcessedEmail
+
+router = APIRouter(prefix="/api", tags=["health"])
+
+
+@router.get("/health")
+async def health():
+    return {"status": "ok", "service": "AI Gmail Agent"}
+
+
+@router.get("/stats")
+async def stats(db: Session = Depends(get_db)):
+    total      = db.query(ProcessedEmail).count()
+    sent       = db.query(ProcessedEmail).filter(ProcessedEmail.action_taken == "auto_sent").count()
+    drafted    = db.query(ProcessedEmail).filter(ProcessedEmail.action_taken == "draft_saved").count()
+    skipped    = db.query(ProcessedEmail).filter(ProcessedEmail.action_taken == "skipped").count()
+    high_pri   = db.query(ProcessedEmail).filter(ProcessedEmail.priority == "High").count()
+
+    by_category = (
+        db.query(ProcessedEmail.category, func.count(ProcessedEmail.email_id))
+        .group_by(ProcessedEmail.category)
+        .all()
+    )
+
+    return {
+        "total_processed": total,
+        "auto_sent":       sent,
+        "drafts_saved":    drafted,
+        "skipped":         skipped,
+        "high_priority":   high_pri,
+        "by_category":     {cat: count for cat, count in by_category},
+    }
+
+
+@router.get("/logs")
+async def recent_logs(limit: int = 20, db: Session = Depends(get_db)):
+    records = (
+        db.query(ProcessedEmail)
+        .order_by(ProcessedEmail.processed_at.desc())
+        .limit(limit)
+        .all()
+    )
+    return [
+        {
+            "email_id":     r.email_id,
+            "sender":       r.sender,
+            "subject":      r.subject,
+            "category":     r.category,
+            "priority":     r.priority,
+            "action_taken": r.action_taken,
+            "reply_sent":   r.reply_sent,
+            "processed_at": r.processed_at,
+            "notes":        r.notes,
+        }
+        for r in records
+    ]

app/services/ai_servise.py

@@ -0,0 +1,93 @@
+import json
+import re
+from groq import Groq
+from loguru import logger
+from config import GROQ_API_KEY
+
+client = Groq(api_key=GROQ_API_KEY)
+MODEL = "llama3-70b-8192"
+
+
+ANALYSIS_PROMPT = """You are an intelligent email assistant. Analyze the email below and respond ONLY with a valid JSON object. No explanation, no markdown.
+
+Email:
+From: {sender}
+Subject: {subject}
+Body:
+{body}
+
+Respond with this exact JSON structure:
+{{
+  "category": "Recruiter | Client | Support | Personal | Spam | Promotional | Other",
+  "priority": "High | Medium | Low",
+  "requires_reply": true or false,
+  "is_spam": true or false,
+  "reason": "one line explanation"
+}}
+
+Rules:
+- priority=High if it's a recruiter reaching out personally, a client with an urgent issue, or important personal matter
+- requires_reply=false for newsletters, job alerts, noreply senders, automated digests
+- is_spam=true if it looks like unsolicited bulk email
+"""
+
+REPLY_PROMPT = """You are a professional email assistant. Write a polite, concise reply to this email.
+
+From: {sender}
+Subject: {subject}
+Body:
+{body}
+
+Instructions:
+- Keep it under 100 words
+- Be professional but warm
+- Do not include subject line, just the body
+- End with: "Best regards"
+- If it's a recruiter, express interest and mention you are available to discuss further
+"""
+
+
+def analyze_email(sender: str, subject: str, body: str) -> dict:
+    try:
+        prompt = ANALYSIS_PROMPT.format(sender=sender, subject=subject, body=body[:2000])
+        response = client.chat.completions.create(
+            model=MODEL,
+            messages=[{"role": "user", "content": prompt}],
+            temperature=0.1,
+            max_tokens=300,
+        )
+        raw = response.choices[0].message.content.strip()
+
+        # Strip markdown fences if present
+        raw = re.sub(r"```json|```", "", raw).strip()
+        result = json.loads(raw)
+        logger.info(f"📊 Analysis for '{subject}': {result}")
+        return result
+
+    except Exception as e:
+        logger.error(f"❌ AI analysis failed: {e}")
+        return {
+            "category": "Other",
+            "priority": "Low",
+            "requires_reply": False,
+            "is_spam": False,
+            "reason": "Analysis failed"
+        }
+
+
+def generate_reply(sender: str, subject: str, body: str) -> str:
+    try:
+        prompt = REPLY_PROMPT.format(sender=sender, subject=subject, body=body[:2000])
+        response = client.chat.completions.create(
+            model=MODEL,
+            messages=[{"role": "user", "content": prompt}],
+            temperature=0.7,
+            max_tokens=200,
+        )
+        reply = response.choices[0].message.content.strip()
+        logger.info(f"✍️  Reply generated for '{subject}'")
+        return reply
+
+    except Exception as e:
+        logger.error(f"❌ Reply generation failed: {e}")
+        return ""

app/services/gmail_servise.py

@@ -0,0 +1,186 @@
+import base64
+import re
+from email.mime.text import MIMEText
+from email.mime.multipart import MIMEMultipart
+from google.oauth2.credentials import Credentials
+from google_auth_oauthlib.flow import InstalledAppFlow
+from google.auth.transport.requests import Request
+from googleapiclient.discovery import build
+import os
+import pickle
+from loguru import logger
+from config import GMAIL_CREDENTIALS_FILE, GMAIL_TOKEN_FILE
+
+SCOPES = [
+    "https://www.googleapis.com/auth/gmail.modify",
+]
+
+
+# ── Patterns that indicate no-reply / automated senders ──────────────────────
+NO_REPLY_PATTERNS = [
+    r"no.?reply",
+    r"do.?not.?reply",
+    r"noreply",
+    r"donotreply",
+    r"mailer.?daemon",
+    r"notifications?@",
+    r"alerts?@",
+    r"updates?@",
+    r"newsletter@",
+    r"automated@",
+    r"system@",
+    r"bounce@",
+]
+
+# ── Known job-alert domains / senders ────────────────────────────────────────
+JOB_ALERT_PATTERNS = [
+    r"naukri\.com",
+    r"linkedin\.com",
+    r"indeed\.com",
+    r"monster\.com",
+    r"shine\.com",
+    r"foundit\.in",
+    r"internshala\.com",
+    r"wellfound\.com",
+    r"angellist\.com",
+    r"jobs\.google\.com",
+    r"glassdoor\.com",
+]
+
+
+def get_gmail_service():
+    creds = None
+    if os.path.exists(GMAIL_TOKEN_FILE):
+        try:
+            if GMAIL_TOKEN_FILE.endswith(".json"):
+                creds = Credentials.from_authorized_user_file(GMAIL_TOKEN_FILE, SCOPES)
+            else:
+                with open(GMAIL_TOKEN_FILE, "rb") as token:
+                    creds = pickle.load(token)
+        except Exception as e:
+            logger.warning(f"Failed to load credentials from file {GMAIL_TOKEN_FILE}: {e}. Retrying OAuth flow.")
+            creds = None
+
+    if not creds or not creds.valid:
+        if creds and creds.expired and creds.refresh_token:
+            creds.refresh(Request())
+        else:
+            flow = InstalledAppFlow.from_client_secrets_file(GMAIL_CREDENTIALS_FILE, SCOPES)
+            creds = flow.run_local_server(port=0)
+        
+        try:
+            if GMAIL_TOKEN_FILE.endswith(".json"):
+                with open(GMAIL_TOKEN_FILE, "w") as token:
+                    token.write(creds.to_json())
+            else:
+                with open(GMAIL_TOKEN_FILE, "wb") as token:
+                    pickle.dump(creds, token)
+        except Exception as e:
+            logger.error(f"Failed to save credentials to {GMAIL_TOKEN_FILE}: {e}")
+
+    return build("gmail", "v1", credentials=creds)
+
+
+
+def fetch_unread_emails(service, max_results: int = 10) -> list[dict]:
+    """Fetch unread emails from inbox (excludes promotions/spam labels)."""
+    results = service.users().messages().list(
+        userId="me",
+        labelIds=["INBOX", "UNREAD"],
+        maxResults=max_results,
+        q="-label:SPAM -label:CATEGORY_PROMOTIONS"
+    ).execute()
+
+    messages = results.get("messages", [])
+    emails = []
+
+    for msg in messages:
+        detail = service.users().messages().get(
+            userId="me", id=msg["id"], format="full"
+        ).execute()
+        emails.append(parse_email(detail))
+
+    return emails
+
+
+def parse_email(raw_message: dict) -> dict:
+    headers = {h["name"]: h["value"] for h in raw_message["payload"]["headers"]}
+    body = extract_body(raw_message["payload"])
+    gmail_labels = raw_message.get("labelIds", [])
+
+    return {
+        "id":         raw_message["id"],
+        "sender":     headers.get("From", ""),
+        "subject":    headers.get("Subject", "(No Subject)"),
+        "body":       body[:3000],           # limit to 3k chars for LLM
+        "labels":     gmail_labels,
+        "is_spam":    "SPAM" in gmail_labels or "CATEGORY_PROMOTIONS" in gmail_labels,
+    }
+
+
+def extract_body(payload: dict) -> str:
+    body = ""
+    if "parts" in payload:
+        for part in payload["parts"]:
+            if part["mimeType"] == "text/plain" and "data" in part.get("body", {}):
+                body += base64.urlsafe_b64decode(part["body"]["data"]).decode("utf-8", errors="ignore")
+    elif "body" in payload and "data" in payload["body"]:
+        body = base64.urlsafe_b64decode(payload["body"]["data"]).decode("utf-8", errors="ignore")
+    return body.strip()
+
+
+def is_no_reply_sender(sender: str) -> bool:
+    sender_lower = sender.lower()
+    return any(re.search(p, sender_lower) for p in NO_REPLY_PATTERNS)
+
+
+def is_job_alert_email(sender: str, subject: str) -> bool:
+    text = (sender + " " + subject).lower()
+    return any(re.search(p, text) for p in JOB_ALERT_PATTERNS)
+
+
+def send_email(service, to: str, subject: str, body: str) -> bool:
+    try:
+        message = MIMEMultipart()
+        message["to"] = to
+        message["subject"] = f"Re: {subject}"
+        message.attach(MIMEText(body, "plain"))
+
+        raw = base64.urlsafe_b64encode(message.as_bytes()).decode()
+        service.users().messages().send(
+            userId="me", body={"raw": raw}
+        ).execute()
+        logger.success(f"✅ Auto-reply sent to {to}")
+        return True
+    except Exception as e:
+        logger.error(f"❌ Failed to send email to {to}: {e}")
+        return False
+
+
+def save_draft(service, to: str, subject: str, body: str) -> bool:
+    try:
+        message = MIMEMultipart()
+        message["to"] = to
+        message["subject"] = f"Re: {subject}"
+        message.attach(MIMEText(body, "plain"))
+
+        raw = base64.urlsafe_b64encode(message.as_bytes()).decode()
+        service.users().drafts().create(
+            userId="me", body={"message": {"raw": raw}}
+        ).execute()
+        logger.info(f"📝 Draft saved for {to}")
+        return True
+    except Exception as e:
+        logger.error(f"❌ Failed to save draft for {to}: {e}")
+        return False
+
+
+def mark_as_read(service, email_id: str):
+    try:
+        service.users().messages().modify(
+            userId="me",
+            id=email_id,
+            body={"removeLabelIds": ["UNREAD"]}
+        ).execute()
+    except Exception as e:
+        logger.warning(f"Could not mark email {email_id} as read: {e}")

app/workers/email_worker.py

@@ -0,0 +1,139 @@
+import asyncio
+from loguru import logger
+from sqlalchemy.orm import Session
+
+from app.models.database import SessionLocal, ProcessedEmail
+from app.services.gmail_servise import (
+    get_gmail_service,
+    fetch_unread_emails,
+    is_no_reply_sender,
+    is_job_alert_email,
+    send_email,
+    save_draft,
+    mark_as_read,
+)
+from app.services.ai_servise import analyze_email, generate_reply
+from config import POLL_INTERVAL
+
+
+def already_processed(db: Session, email_id: str) -> bool:
+    return db.query(ProcessedEmail).filter(ProcessedEmail.email_id == email_id).first() is not None
+
+
+def save_to_db(db: Session, email: dict, analysis: dict, action: str, reply_sent: bool, notes: str = ""):
+    record = ProcessedEmail(
+        email_id     = email["id"],
+        sender       = email["sender"],
+        subject      = email["subject"],
+        category     = analysis.get("category", "Other"),
+        priority     = analysis.get("priority", "Low"),
+        action_taken = action,
+        reply_sent   = reply_sent,
+        notes        = notes,
+    )
+    db.add(record)
+    db.commit()
+
+
+def decide_and_act(service, db: Session, email: dict):
+    """
+    Core decision engine:
+
+    SKIP if:
+      - already processed
+      - Gmail flagged as spam/promo
+      - sender is noreply/automated
+      - email is a job alert/digest
+
+    ANALYZE with AI:
+      - If AI says spam → skip
+      - If AI says no reply needed → skip
+      - If HIGH priority → auto send reply
+      - Otherwise → save as draft
+    """
+    email_id = email["id"]
+    sender   = email["sender"]
+    subject  = email["subject"]
+
+    # ── Guard 1: Already processed ────────────────────────────────────────────
+    if already_processed(db, email_id):
+        logger.debug(f"⏭  Already processed: {subject}")
+        return
+
+    # ── Guard 2: Gmail spam/promo label ──────────────────────────────────────
+    if email["is_spam"]:
+        logger.info(f"🚫 Gmail flagged as spam/promo: {subject}")
+        save_to_db(db, email, {"category": "Spam", "priority": "Low"}, "skipped", False, "Gmail spam/promo label")
+        mark_as_read(service, email_id)
+        return
+
+    # ── Guard 3: No-reply sender ──────────────────────────────────────────────
+    if is_no_reply_sender(sender):
+        logger.info(f"🚫 No-reply sender detected: {sender}")
+        save_to_db(db, email, {"category": "Automated", "priority": "Low"}, "skipped", False, "No-reply sender")
+        mark_as_read(service, email_id)
+        return
+
+    # ── Guard 4: Job alert / digest ───────────────────────────────────────────
+    if is_job_alert_email(sender, subject):
+        logger.info(f"📋 Job alert email, skipping reply: {subject}")
+        save_to_db(db, email, {"category": "Job Alert", "priority": "Low"}, "skipped", False, "Job alert digest")
+        mark_as_read(service, email_id)
+        return
+
+    # ── AI Analysis ───────────────────────────────────────────────────────────
+    analysis = analyze_email(sender, subject, email["body"])
+
+    if analysis.get("is_spam"):
+        logger.info(f"🤖 AI flagged as spam: {subject}")
+        save_to_db(db, email, analysis, "skipped", False, "AI detected spam")
+        mark_as_read(service, email_id)
+        return
+
+    if not analysis.get("requires_reply", False):
+        logger.info(f"📭 No reply needed: {subject} ({analysis.get('reason', '')})")
+        save_to_db(db, email, analysis, "skipped", False, analysis.get("reason", ""))
+        mark_as_read(service, email_id)
+        return
+
+    # ── Generate reply ────────────────────────────────────────────────────────
+    reply_body = generate_reply(sender, subject, email["body"])
+    if not reply_body:
+        logger.warning(f"⚠️  Could not generate reply for: {subject}")
+        save_to_db(db, email, analysis, "skipped", False, "Reply generation failed")
+        return
+
+    # ── HIGH priority → Auto send ─────────────────────────────────────────────
+    if analysis.get("priority") == "High":
+        sent = send_email(service, sender, subject, reply_body)
+        action = "auto_sent" if sent else "send_failed"
+        save_to_db(db, email, analysis, action, sent, "Auto-sent: high priority")
+        mark_as_read(service, email_id)
+
+    # ── Medium/Low → Save as draft ──────────���─────────────────────────────────
+    else:
+        save_draft(service, sender, subject, reply_body)
+        save_to_db(db, email, analysis, "draft_saved", False, "Draft saved: medium/low priority")
+        mark_as_read(service, email_id)
+
+
+async def email_loop():
+    logger.info("🚀 Email worker started")
+    service = get_gmail_service()
+
+    while True:
+        try:
+            logger.info("📬 Checking Gmail for new emails...")
+            db = SessionLocal()
+            emails = fetch_unread_emails(service, max_results=10)
+            logger.info(f"📩 Found {len(emails)} unread emails")
+
+            for email in emails:
+                decide_and_act(service, db, email)
+
+            db.close()
+
+        except Exception as e:
+            logger.error(f"💥 Worker error: {e}")
+
+        await asyncio.sleep(POLL_INTERVAL)

config.py

@@ -0,0 +1,13 @@
+from dotenv import load_dotenv
+import os
+
+load_dotenv()
+
+DATABASE_URL = os.getenv("DATABASE_URL", "sqlite:///./emails.db")
+GROQ_API_KEY = os.getenv("GROQ_API_KEY")
+POLL_INTERVAL = int(os.getenv("POLL_INTERVAL", 60))
+GMAIL_CREDENTIALS_FILE = os.getenv("GMAIL_CREDENTIALS_FILE", "credentials.json")
+GMAIL_TOKEN_FILE = os.getenv("GMAIL_TOKEN_FILE", "token.json")
+GMAIL_TOKEN_JSON = os.getenv("GMAIL_TOKEN_JSON")
+GMAIL_CREDENTIALS_JSON = os.getenv("GMAIL_CREDENTIALS_JSON")
+

index.html

@@ -0,0 +1,808 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>AI Gmail Agent - Dashboard</title>
+    <!-- Premium Google Fonts: Inter & Outfit -->
+    <link rel="preconnect" href="https://fonts.googleapis.com">
+    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+    <link href="https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700&family=Outfit:wght@400;500;600;700;800&display=swap" rel="stylesheet">
+    <!-- FontAwesome for Premium Icons -->
+    <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.4.0/css/all.min.css">
+    
+    <style>
+        /* Modern CSS Custom Properties with harmonious HSL colors */
+        :root {
+            --bg-base: hsl(224, 71%, 4%);
+            --bg-canvas: hsl(224, 71%, 6%);
+            --glass-bg: hsla(224, 71%, 10%, 0.45);
+            --glass-border: hsla(224, 71%, 20%, 0.4);
+            --glass-highlight: hsla(224, 71%, 30%, 0.15);
+            
+            --text-primary: hsl(210, 40%, 98%);
+            --text-secondary: hsl(215, 20%, 65%);
+            --text-muted: hsl(215, 16%, 47%);
+            
+            --primary: hsl(263, 90%, 62%);
+            --primary-glow: hsla(263, 90%, 62%, 0.5);
+            --secondary: hsl(190, 95%, 50%);
+            --secondary-glow: hsla(190, 95%, 50%, 0.5);
+            
+            --priority-high: hsl(346, 84%, 61%);
+            --priority-high-glow: hsla(346, 84%, 61%, 0.25);
+            --priority-medium: hsl(40, 96%, 53%);
+            --priority-medium-glow: hsla(40, 96%, 53%, 0.25);
+            --priority-low: hsl(142, 70%, 45%);
+            --priority-low-glow: hsla(142, 70%, 45%, 0.25);
+            
+            --action-sent: hsl(263, 90%, 62%);
+            --action-draft: hsl(190, 95%, 50%);
+            --action-skipped: hsl(215, 16%, 47%);
+        }
+
+        * {
+            box-sizing: border-box;
+            margin: 0;
+            padding: 0;
+            scrollbar-width: thin;
+            scrollbar-color: var(--glass-border) transparent;
+        }
+
+        body {
+            font-family: 'Inter', sans-serif;
+            background-color: var(--bg-base);
+            background-image: 
+                radial-gradient(at 0% 0%, hsla(263, 90%, 15%, 0.3) 0px, transparent 50%),
+                radial-gradient(at 100% 100%, hsla(190, 95%, 15%, 0.2) 0px, transparent 50%),
+                radial-gradient(at 50% 50%, hsla(224, 71%, 4%, 1) 0%, hsla(224, 71%, 6%, 0.9) 100%);
+            background-attachment: fixed;
+            color: var(--text-primary);
+            min-height: 100vh;
+            padding: 2.5rem 1.5rem;
+            display: flex;
+            justify-content: center;
+            align-items: flex-start;
+        }
+
+        /* Container Layout */
+        .dashboard-container {
+            width: 100%;
+            max-width: 1200px;
+            display: flex;
+            flex-direction: column;
+            gap: 2rem;
+        }
+
+        /* Breathtaking Glowing Header */
+        header {
+            display: flex;
+            justify-content: space-between;
+            align-items: center;
+            padding: 1.5rem 2rem;
+            background: var(--glass-bg);
+            border: 1px solid var(--glass-border);
+            backdrop-filter: blur(16px);
+            -webkit-backdrop-filter: blur(16px);
+            border-radius: 16px;
+            box-shadow: 0 8px 32px 0 rgba(0, 0, 0, 0.37);
+            position: relative;
+            overflow: hidden;
+        }
+
+        header::before {
+            content: '';
+            position: absolute;
+            top: 0;
+            left: 0;
+            width: 100%;
+            height: 2px;
+            background: linear-gradient(90deg, transparent, var(--primary), var(--secondary), transparent);
+        }
+
+        .logo-section {
+            display: flex;
+            align-items: center;
+            gap: 1rem;
+        }
+
+        .logo-icon {
+            font-size: 2rem;
+            background: linear-gradient(135deg, var(--primary), var(--secondary));
+            -webkit-background-clip: text;
+            -webkit-text-fill-color: transparent;
+            filter: drop-shadow(0 0 10px var(--primary-glow));
+            animation: pulse-glow 3s infinite ease-in-out;
+        }
+
+        h1 {
+            font-family: 'Outfit', sans-serif;
+            font-size: 1.75rem;
+            font-weight: 700;
+            letter-spacing: -0.02em;
+            background: linear-gradient(to right, var(--text-primary), var(--text-secondary));
+            -webkit-background-clip: text;
+            -webkit-text-fill-color: transparent;
+        }
+
+        .status-badge {
+            display: flex;
+            align-items: center;
+            gap: 0.75rem;
+            background: rgba(16, 185, 129, 0.1);
+            border: 1px solid rgba(16, 185, 129, 0.2);
+            color: hsl(142, 70%, 55%);
+            padding: 0.5rem 1rem;
+            border-radius: 9999px;
+            font-size: 0.875rem;
+            font-weight: 500;
+            box-shadow: 0 0 15px rgba(16, 185, 129, 0.1);
+        }
+
+        .status-dot {
+            width: 8px;
+            height: 8px;
+            background-color: hsl(142, 70%, 50%);
+            border-radius: 50%;
+            position: relative;
+            animation: blink 1.5s infinite ease-in-out;
+        }
+
+        .status-dot::after {
+            content: '';
+            position: absolute;
+            top: -4px;
+            left: -4px;
+            width: 16px;
+            height: 16px;
+            border: 2px solid hsl(142, 70%, 50%);
+            border-radius: 50%;
+            animation: ripple 1.5s infinite ease-in-out;
+        }
+
+        /* Stats Grid Section */
+        .stats-grid {
+            display: grid;
+            grid-template-columns: repeat(auto-fit, minmax(240px, 1fr));
+            gap: 1.5rem;
+        }
+
+        .stat-card {
+            background: var(--glass-bg);
+            border: 1px solid var(--glass-border);
+            backdrop-filter: blur(16px);
+            -webkit-backdrop-filter: blur(16px);
+            border-radius: 16px;
+            padding: 1.5rem;
+            display: flex;
+            align-items: center;
+            gap: 1.25rem;
+            transition: all 0.3s cubic-bezier(0.25, 0.8, 0.25, 1);
+            position: relative;
+            overflow: hidden;
+            box-shadow: 0 4px 20px rgba(0, 0, 0, 0.15);
+        }
+
+        .stat-card::after {
+            content: '';
+            position: absolute;
+            bottom: 0;
+            left: 0;
+            width: 100%;
+            height: 3px;
+            background: transparent;
+            transition: background 0.3s ease;
+        }
+
+        .stat-card:hover {
+            transform: translateY(-5px);
+            border-color: var(--glass-highlight);
+            box-shadow: 0 8px 30px rgba(0, 0, 0, 0.25);
+        }
+
+        .stat-card.total:hover::after { background: linear-gradient(90deg, var(--primary), var(--secondary)); }
+        .stat-card.sent:hover::after { background: var(--priority-low); }
+        .stat-card.draft:hover::after { background: var(--secondary); }
+        .stat-card.skipped:hover::after { background: var(--text-muted); }
+
+        .stat-icon {
+            width: 50px;
+            height: 50px;
+            border-radius: 12px;
+            display: flex;
+            align-items: center;
+            justify-content: center;
+            font-size: 1.5rem;
+            background: var(--glass-highlight);
+            border: 1px solid var(--glass-border);
+            color: var(--text-primary);
+            transition: all 0.3s ease;
+        }
+
+        .stat-card:hover .stat-icon {
+            transform: scale(1.1);
+        }
+
+        .stat-card.total .stat-icon { color: var(--primary); background: hsla(263, 90%, 62%, 0.1); border-color: hsla(263, 90%, 62%, 0.2); }
+        .stat-card.sent .stat-icon { color: var(--priority-low); background: hsla(142, 70%, 45%, 0.1); border-color: hsla(142, 70%, 45%, 0.2); }
+        .stat-card.draft .stat-icon { color: var(--secondary); background: hsla(190, 95%, 50%, 0.1); border-color: hsla(190, 95%, 50%, 0.2); }
+        .stat-card.skipped .stat-icon { color: var(--text-muted); background: hsla(215, 16%, 47%, 0.1); border-color: hsla(215, 16%, 47%, 0.2); }
+
+        .stat-info {
+            display: flex;
+            flex-direction: column;
+            gap: 0.25rem;
+        }
+
+        .stat-label {
+            font-size: 0.875rem;
+            color: var(--text-secondary);
+            font-weight: 500;
+        }
+
+        .stat-value {
+            font-family: 'Outfit', sans-serif;
+            font-size: 1.85rem;
+            font-weight: 700;
+        }
+
+        /* Logs Dashboard Table Section */
+        .logs-section {
+            background: var(--glass-bg);
+            border: 1px solid var(--glass-border);
+            backdrop-filter: blur(16px);
+            -webkit-backdrop-filter: blur(16px);
+            border-radius: 16px;
+            padding: 2rem;
+            box-shadow: 0 8px 32px 0 rgba(0, 0, 0, 0.25);
+            display: flex;
+            flex-direction: column;
+            gap: 1.5rem;
+        }
+
+        .logs-header {
+            display: flex;
+            justify-content: space-between;
+            align-items: center;
+        }
+
+        .logs-title {
+            display: flex;
+            align-items: center;
+            gap: 0.75rem;
+            font-family: 'Outfit', sans-serif;
+            font-size: 1.25rem;
+            font-weight: 600;
+        }
+
+        .logs-title i {
+            color: var(--primary);
+        }
+
+        .refresh-btn {
+            background: var(--glass-highlight);
+            border: 1px solid var(--glass-border);
+            color: var(--text-primary);
+            padding: 0.5rem 1rem;
+            border-radius: 8px;
+            font-size: 0.875rem;
+            font-weight: 500;
+            cursor: pointer;
+            display: flex;
+            align-items: center;
+            gap: 0.5rem;
+            transition: all 0.2s ease;
+        }
+
+        .refresh-btn:hover {
+            background: var(--glass-border);
+            border-color: var(--text-muted);
+        }
+
+        .refresh-btn:active {
+            transform: scale(0.95);
+        }
+
+        /* Live Table Styling */
+        .table-wrapper {
+            width: 100%;
+            overflow-x: auto;
+            border-radius: 12px;
+            border: 1px solid var(--glass-border);
+        }
+
+        table {
+            width: 100%;
+            border-collapse: collapse;
+            text-align: left;
+            font-size: 0.875rem;
+        }
+
+        th {
+            background: rgba(224, 71%, 10%, 0.8);
+            color: var(--text-secondary);
+            font-weight: 600;
+            padding: 1rem 1.25rem;
+            border-bottom: 1px solid var(--glass-border);
+            text-transform: uppercase;
+            font-size: 0.75rem;
+            letter-spacing: 0.05em;
+        }
+
+        td {
+            padding: 1.15rem 1.25rem;
+            border-bottom: 1px solid rgba(224, 71%, 20%, 0.2);
+            color: var(--text-primary);
+            white-space: nowrap;
+        }
+
+        tr:last-child td {
+            border-bottom: none;
+        }
+
+        tr {
+            transition: background 0.2s ease;
+        }
+
+        tr:hover td {
+            background: rgba(263, 90%, 62%, 0.02);
+        }
+
+        .sender-col {
+            font-weight: 500;
+            max-width: 180px;
+            overflow: hidden;
+            text-overflow: ellipsis;
+        }
+
+        .subject-col {
+            max-width: 320px;
+            overflow: hidden;
+            text-overflow: ellipsis;
+            color: var(--text-primary);
+        }
+
+        /* Pill Badges */
+        .pill {
+            display: inline-flex;
+            align-items: center;
+            padding: 0.25rem 0.75rem;
+            border-radius: 9999px;
+            font-size: 0.75rem;
+            font-weight: 600;
+            text-transform: capitalize;
+            letter-spacing: 0.02em;
+        }
+
+        /* Priority Pills */
+        .pill.priority-high {
+            background: rgba(244, 63, 94, 0.1);
+            color: var(--priority-high);
+            border: 1px solid rgba(244, 63, 94, 0.2);
+            box-shadow: 0 0 10px var(--priority-high-glow);
+        }
+
+        .pill.priority-medium {
+            background: rgba(245, 158, 11, 0.1);
+            color: var(--priority-medium);
+            border: 1px solid rgba(245, 158, 11, 0.2);
+            box-shadow: 0 0 10px var(--priority-medium-glow);
+        }
+
+        .pill.priority-low {
+            background: rgba(16, 185, 129, 0.1);
+            color: var(--priority-low);
+            border: 1px solid rgba(16, 185, 129, 0.2);
+            box-shadow: 0 0 10px var(--priority-low-glow);
+        }
+
+        /* Action Pills */
+        .pill.action-sent {
+            background: rgba(139, 92, 246, 0.15);
+            color: var(--action-sent);
+            border: 1px solid rgba(139, 92, 246, 0.3);
+        }
+
+        .pill.action-draft {
+            background: rgba(6, 182, 212, 0.15);
+            color: var(--action-draft);
+            border: 1px solid rgba(6, 182, 212, 0.3);
+        }
+
+        .pill.action-skipped {
+            background: rgba(100, 116, 139, 0.15);
+            color: var(--action-skipped);
+            border: 1px solid rgba(100, 116, 139, 0.3);
+        }
+
+        .time-col {
+            color: var(--text-muted);
+            font-size: 0.8rem;
+        }
+
+        .empty-state {
+            text-align: center;
+            padding: 3rem 1.5rem;
+            color: var(--text-secondary);
+            display: flex;
+            flex-direction: column;
+            align-items: center;
+            gap: 1rem;
+        }
+
+        .empty-icon {
+            font-size: 2.5rem;
+            color: var(--text-muted);
+            opacity: 0.6;
+        }
+
+        /* Config Card Panel - Elegant Cloud integration guide */
+        .config-guide-panel {
+            background: var(--glass-bg);
+            border: 1px solid var(--glass-border);
+            backdrop-filter: blur(16px);
+            -webkit-backdrop-filter: blur(16px);
+            border-radius: 16px;
+            padding: 2rem;
+            box-shadow: 0 8px 32px 0 rgba(0, 0, 0, 0.25);
+            display: flex;
+            flex-direction: column;
+            gap: 1.25rem;
+        }
+
+        .config-header {
+            display: flex;
+            align-items: center;
+            gap: 0.75rem;
+            font-family: 'Outfit', sans-serif;
+            font-size: 1.25rem;
+            font-weight: 600;
+            color: var(--secondary);
+        }
+
+        .config-body {
+            color: var(--text-secondary);
+            font-size: 0.9rem;
+            line-height: 1.6;
+            display: flex;
+            flex-direction: column;
+            gap: 1rem;
+        }
+
+        .step-list {
+            list-style: none;
+            display: flex;
+            flex-direction: column;
+            gap: 0.75rem;
+            margin-top: 0.5rem;
+        }
+
+        .step-item {
+            display: flex;
+            align-items: flex-start;
+            gap: 0.75rem;
+        }
+
+        .step-num {
+            background: var(--secondary);
+            color: var(--bg-base);
+            width: 22px;
+            height: 22px;
+            border-radius: 50%;
+            display: inline-flex;
+            align-items: center;
+            justify-content: center;
+            font-weight: 700;
+            font-size: 0.75rem;
+            flex-shrink: 0;
+            margin-top: 2px;
+        }
+
+        .code-container {
+            background: rgba(0, 0, 0, 0.3);
+            border: 1px solid var(--glass-border);
+            border-radius: 8px;
+            padding: 1rem;
+            font-family: 'Courier New', Courier, monospace;
+            font-size: 0.825rem;
+            overflow-x: auto;
+            position: relative;
+            color: var(--text-primary);
+        }
+
+        .copy-btn {
+            position: absolute;
+            top: 8px;
+            right: 8px;
+            background: var(--glass-highlight);
+            border: 1px solid var(--glass-border);
+            color: var(--text-secondary);
+            width: 32px;
+            height: 32px;
+            border-radius: 6px;
+            display: flex;
+            align-items: center;
+            justify-content: center;
+            cursor: pointer;
+            transition: all 0.2s ease;
+        }
+
+        .copy-btn:hover {
+            color: var(--text-primary);
+            background: var(--glass-border);
+        }
+
+        /* Beautiful Dynamic Animations */
+        @keyframes pulse-glow {
+            0%, 100% { filter: drop-shadow(0 0 5px var(--primary-glow)); }
+            50% { filter: drop-shadow(0 0 15px var(--primary-glow)); }
+        }
+
+        @keyframes blink {
+            0%, 100% { opacity: 1; }
+            50% { opacity: 0.4; }
+        }
+
+        @keyframes ripple {
+            0% { transform: scale(1); opacity: 0.8; }
+            100% { transform: scale(2.2); opacity: 0; }
+        }
+
+        @keyframes spin {
+            100% { transform: rotate(360deg); }
+        }
+
+        .fa-spin-custom {
+            animation: spin 1s linear infinite;
+        }
+
+        /* Responsive Breakpoints */
+        @media (max-width: 768px) {
+            body {
+                padding: 1.5rem 1rem;
+            }
+            header {
+                flex-direction: column;
+                align-items: flex-start;
+                gap: 1rem;
+            }
+            .status-badge {
+                align-self: flex-end;
+            }
+        }
+    </style>
+</head>
+<body>
+
+    <div class="dashboard-container">
+        <!-- Dashboard Header -->
+        <header>
+            <div class="logo-section">
+                <i class="fa-solid fa-wand-magic-sparkles logo-icon"></i>
+                <div>
+                    <h1>AI Gmail Agent</h1>
+                    <p style="color: var(--text-secondary); font-size: 0.875rem;">Autonomously managing, categorizing & responding to Gmail</p>
+                </div>
+            </div>
+            <div class="status-badge">
+                <span class="status-dot"></span>
+                <span>Active Syncing</span>
+            </div>
+        </header>
+
+        <!-- Dynamic Statistics Cards -->
+        <div class="stats-grid">
+            <div class="stat-card total">
+                <div class="stat-icon"><i class="fa-solid fa-envelope-open-text"></i></div>
+                <div class="stat-info">
+                    <span class="stat-label">Total Processed</span>
+                    <span class="stat-value" id="stat-total">0</span>
+                </div>
+            </div>
+            <div class="stat-card sent">
+                <div class="stat-icon"><i class="fa-solid fa-paper-plane"></i></div>
+                <div class="stat-info">
+                    <span class="stat-label">Auto Sent Replies</span>
+                    <span class="stat-value" id="stat-sent">0</span>
+                </div>
+            </div>
+            <div class="stat-card draft">
+                <div class="stat-icon"><i class="fa-solid fa-file-pen"></i></div>
+                <div class="stat-info">
+                    <span class="stat-label">Drafts Created</span>
+                    <span class="stat-value" id="stat-drafts">0</span>
+                </div>
+            </div>
+            <div class="stat-card skipped">
+                <div class="stat-icon"><i class="fa-solid fa-forward"></i></div>
+                <div class="stat-info">
+                    <span class="stat-label">Spam/Skipped</span>
+                    <span class="stat-value" id="stat-skipped">0</span>
+                </div>
+            </div>
+        </div>
+
+        <!-- Live Activity Log -->
+        <div class="logs-section">
+            <div class="logs-header">
+                <div class="logs-title">
+                    <i class="fa-solid fa-clock-rotate-left"></i>
+                    <h2>Live Decision Log</h2>
+                </div>
+                <button class="refresh-btn" id="refresh-trigger">
+                    <i class="fa-solid fa-rotate" id="refresh-icon"></i>
+                    <span>Refresh</span>
+                </button>
+            </div>
+            
+            <div class="table-wrapper">
+                <table>
+                    <thead>
+                        <tr>
+                            <th>Sender</th>
+                            <th>Subject</th>
+                            <th>Category</th>
+                            <th>Priority</th>
+                            <th>Action Taken</th>
+                            <th>Processed Time</th>
+                        </tr>
+                    </thead>
+                    <tbody id="logs-tbody">
+                        <tr>
+                            <td colspan="6">
+                                <div class="empty-state">
+                                    <i class="fa-solid fa-circle-notch fa-spin empty-icon"></i>
+                                    <p>Loading agent telemetry...</p>
+                                </div>
+                            </td>
+                        </tr>
+                    </tbody>
+                </table>
+            </div>
+        </div>
+
+        <!-- Cloud Configuration Guide Panel -->
+        <div class="config-guide-panel">
+            <div class="config-header">
+                <i class="fa-solid fa-cloud-arrow-up"></i>
+                <h2>Cloud Deployment & Hugging Face Guide</h2>
+            </div>
+            <div class="config-body">
+                <p>This Gmail Agent runs entirely autonomously in the cloud. Since you are deploying to a secure, public or private Hugging Face Space, you <strong>do not</strong> need to expose your sensitive credential files in the repository. Instead, configure them as <strong>Repository Secrets</strong> in the Space settings:</p>
+                
+                <ul class="step-list">
+                    <li class="step-item">
+                        <span class="step-num">1</span>
+                        <div>
+                            <strong>GROQ_API_KEY</strong>: Generate an API key on Groq Console and add it as a secret.
+                        </div>
+                    </li>
+                    <li class="step-item">
+                        <span class="step-num">2</span>
+                        <div>
+                            <strong>GMAIL_TOKEN_JSON</strong>: Copy the exact contents of your local <code>token.json</code> and paste it as a secret. The agent will handle session refresh token rotation automatically!
+                        </div>
+                    </li>
+                </ul>
+
+                <p style="margin-top: 0.5rem; font-size: 0.85rem; color: var(--text-muted);">
+                    <i class="fa-solid fa-circle-info"></i> Note: For security, never commit <code>token.json</code>, <code>credentials.json</code>, or <code>.env</code> files to the public Git repository. They have been automatically added to the <code>.gitignore</code> and <code>.dockerignore</code>.
+                </p>
+            </div>
+        </div>
+    </div>
+
+    <!-- Script for Dynamic Operations -->
+    <script>
+        const statTotal = document.getElementById('stat-total');
+        const statSent = document.getElementById('stat-sent');
+        const statDrafts = document.getElementById('stat-drafts');
+        const statSkipped = document.getElementById('stat-skipped');
+        const logsTbody = document.getElementById('logs-tbody');
+        const refreshBtn = document.getElementById('refresh-trigger');
+        const refreshIcon = document.getElementById('refresh-icon');
+
+        // Format raw date strings neatly
+        function formatTime(isoString) {
+            if (!isoString) return 'N/A';
+            const date = new Date(isoString);
+            return date.toLocaleTimeString([], { hour: '2-digit', minute: '2-digit', second: '2-digit' }) + 
+                   ' ' + date.toLocaleDateString([], { month: 'short', day: 'numeric' });
+        }
+
+        // Fetch Stats & Logs from backend
+        async function fetchTelemetry() {
+            refreshIcon.classList.add('fa-spin-custom');
+            
+            try {
+                // 1. Fetch Stats
+                const statsResponse = await fetch('/api/stats');
+                if (statsResponse.ok) {
+                    const stats = await statsResponse.json();
+                    statTotal.textContent = stats.total_processed || 0;
+                    statSent.textContent = stats.auto_sent || 0;
+                    statDrafts.textContent = stats.drafts_saved || 0;
+                    statSkipped.textContent = stats.skipped || 0;
+                }
+
+                // 2. Fetch Logs
+                const logsResponse = await fetch('/api/logs?limit=15');
+                if (logsResponse.ok) {
+                    const logs = await logsResponse.json();
+                    
+                    if (logs.length === 0) {
+                        logsTbody.innerHTML = `
+                            <tr>
+                                <td colspan="6">
+                                    <div class="empty-state">
+                                        <i class="fa-solid fa-inbox empty-icon"></i>
+                                        <p>No processed emails found in the tracking database yet.</p>
+                                    </div>
+                                </td>
+                            </tr>
+                        `;
+                    } else {
+                        logsTbody.innerHTML = logs.map(log => {
+                            // Map Priority Pill
+                            let priorityClass = 'priority-low';
+                            if (log.priority === 'High') priorityClass = 'priority-high';
+                            else if (log.priority === 'Medium') priorityClass = 'priority-medium';
+
+                            // Map Action Pill
+                            let actionClass = 'action-skipped';
+                            let actionLabel = 'Skipped';
+                            if (log.action_taken === 'auto_sent') {
+                                actionClass = 'action-sent';
+                                actionLabel = 'Replied';
+                            } else if (log.action_taken === 'draft_saved') {
+                                actionClass = 'action-draft';
+                                actionLabel = 'Drafted';
+                            }
+
+                            // Clean subject/sender
+                            const sender = log.sender ? log.sender.replace(/<.*>/, '').trim() : 'Unknown';
+                            const subject = log.subject || '(No Subject)';
+
+                            return `
+                                <tr>
+                                    <td class="sender-col" title="${log.sender}">${sender}</td>
+                                    <td class="subject-col" title="${subject}">${subject}</td>
+                                    <td><span style="font-weight: 500;">${log.category || 'Other'}</span></td>
+                                    <td><span class="pill ${priorityClass}">${log.priority || 'Low'}</span></td>
+                                    <td><span class="pill ${actionClass}" title="${log.notes || ''}">${actionLabel}</span></td>
+                                    <td class="time-col">${formatTime(log.processed_at)}</td>
+                                </tr>
+                            `;
+                        }).join('');
+                    }
+                }
+            } catch (error) {
+                console.error('Error loading agent telemetry:', error);
+                logsTbody.innerHTML = `
+                    <tr>
+                        <td colspan="6">
+                            <div class="empty-state" style="color: var(--priority-high);">
+                                <i class="fa-solid fa-triangle-exclamation empty-icon" style="color: var(--priority-high);"></i>
+                                <p>Failed to connect to agent API backend. Check if service is active.</p>
+                            </div>
+                        </td>
+                    </tr>
+                `;
+            } finally {
+                setTimeout(() => {
+                    refreshIcon.classList.remove('fa-spin-custom');
+                }, 400);
+            }
+        }
+
+        // Setup manual and auto refresh loops
+        refreshBtn.addEventListener('click', fetchTelemetry);
+        
+        // Initial Fetch
+        fetchTelemetry();
+
+        // Auto Refresh every 10 seconds
+        setInterval(fetchTelemetry, 10000);
+    </script>
+</body>
+</html>

main.py

@@ -0,0 +1,75 @@
+import asyncio
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import HTMLResponse
+from loguru import logger
+import sys
+import os
+
+if sys.platform == "win32":
+    try:
+        sys.stdout.reconfigure(encoding='utf-8')
+        sys.stderr.reconfigure(encoding='utf-8')
+    except AttributeError:
+        pass
+
+from app.routes.health import router
+from app.workers.email_worker import email_loop
+from app.models.database import init_db
+
+
+# ── Logging setup ─────────────────────────────────────────────────────────────
+logger.remove()
+logger.add(sys.stdout, colorize=True, format="<green>{time:HH:mm:ss}</green> | <level>{level}</level> | {message}")
+logger.add("logs/agent.log", rotation="1 day", retention="7 days", level="INFO")
+
+# ── App ───────────────────────────────────────────────────────────────────────
+app = FastAPI(
+    title="AI Gmail Agent",
+    description="Automatically categorizes, filters, and replies to emails using Groq LLM",
+    version="2.0.0",
+)
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+app.include_router(router)
+
+
+@app.on_event("startup")
+async def startup_event():
+    init_db()
+    logger.info("✅ Database initialized")
+    asyncio.create_task(email_loop())
+
+
+@app.get("/", response_class=HTMLResponse)
+async def root():
+    if os.path.exists("index.html"):
+        try:
+            with open("index.html", "r", encoding="utf-8") as f:
+                return HTMLResponse(content=f.read(), status_code=200)
+        except Exception as e:
+            logger.error(f"Error reading index.html: {e}")
+            
+    return """
+    <html>
+        <head>
+            <title>AI Gmail Agent</title>
+            <style>
+                body { font-family: sans-serif; text-align: center; padding-top: 50px; background-color: #0f172a; color: #f8fafc; }
+                h1 { color: #818cf8; }
+                p { color: #94a3b8; }
+            </style>
+        </head>
+        <body>
+            <h1>AI Gmail Agent is Running 🚀</h1>
+            <p>Ready to categorize, filter, and reply to your emails!</p>
+            <p>View stats at <a href="/api/stats" style="color: #38bdf8;">/api/stats</a></p>
+        </body>
+    </html>
+    """

requirements.txt

@@ -0,0 +1,10 @@
+fastapi==0.111.0
+uvicorn==0.29.0
+groq==0.9.0
+google-auth==2.29.0
+google-auth-oauthlib==1.2.0
+google-auth-httplib2==0.2.0
+google-api-python-client==2.126.0
+sqlalchemy==2.0.30
+loguru==0.7.2
+python-dotenv==1.0.1