Email Agent

Agente de IA que procesa emails de Gmail, los clasifica automáticamente usando Google Gemini, crea eventos en Google Calendar para reuniones, y expone todo a través de un dashboard web en React.

---

Stack tecnológico

Backend

• Python 3.11+ · FastAPI · uvicorn
• Google Gemini API (google-genai) — clasificación y resumen de correos
• Gmail API + Google Calendar API (OAuth2)
• SQLite + SQLAlchemy — historial local de correos procesados
• pytest · httpx — testing

Frontend

• React 18 + TypeScript · Vite
• react-big-calendar + date-fns — calendario interactivo
• Recharts — gráficos de estadísticas (donut, barras, línea)
• Axios — comunicación con el backend
• Vitest + React Testing Library + @vitest/coverage-v8 — tests de componentes
• Design system centralizado (src/theme.ts) — paleta AI Futuristic Glow con dark theme, glassmorphism y animaciones
• Google Fonts: Space Grotesk (headings) · Inter (body) · IBM Plex Mono (AI outputs)
• Sonner — toast notifications (crear/editar/eliminar eventos)

Deploy

• Docker + GitHub Actions (CI/CD)

---

Features implementadas

• Procesamiento manual de correos: botón "Procesar ahora" en el dashboard
• Clasificación IA: Gemini clasifica cada correo con categoría (reunion, urgente, promocion, informativo, otro) y genera un resumen
• Agendado manual de reuniones: correos clasificados como reunion muestran un botón "📅 Agendar" que abre un modal pre-llenado con los datos extraídos por Gemini (título, fecha, hora, ubicación, descripción). El usuario revisa y confirma antes de crear el evento. Si el email incluye un adjunto .ics, los datos se extraen directamente del archivo con mayor precisión.
• Panel de configuración (/settings): ajusta MAX_EMAILS_PER_RUN, CHECK_INTERVAL_MINUTES, GMAIL_FILTER_AFTER_DATE y horario de descanso (QUIET_HOURS_START/END) desde el dashboard. Los cambios se persisten en .env y se aplican sin reiniciar.
• Filtro por fecha: solo procesa correos llegados después de GMAIL_FILTER_AFTER_DATE (por defecto 2026/03/20)
• Límite configurable: hasta 100 correos por ciclo (MAX_EMAILS_PER_RUN)
• Historial SQLite: todos los correos procesados se guardan localmente con categoría, resumen y timestamp
• Briefing diario (/briefing): resumen ejecutivo narrativo generado por Gemini. Cards estructuradas con resumen general, correos urgentes (acción requerida), reuniones pendientes de agendar y recomendaciones del agente. Soporta consultar el briefing de cualquier fecha pasada.
• Búsqueda inteligente en historial: campo de texto libre que usa SQLite FTS5 (full-text search) para buscar simultáneamente en asunto, remitente y resumen. Se combina con los filtros de fecha y categoría existentes. Los términos encontrados se resaltan en amarillo en los resultados.
• Dashboard de correos con 3 pestañas: Pendientes · Procesados hoy · Historial filtrable + buscable
• Dashboard de estadísticas: donut por categoría · barras+línea de volumen diario · top remitentes
• Calendario interactivo: dos pestañas (lista de cards + grid mes/semana/día) · crear · editar · eliminar eventos · acciones inline en cards · etiquetas con color
• Script de arranque: email-agent inicia backend + frontend y abre el navegador automáticamente
• UI "AI Futuristic Glow": dark theme con fondo #0B0F19, glassmorphism en navbar, glow en botones IA, animación "AI thinking..." al procesar, overrides de react-big-calendar para dark mode
• Hover effects profesionales: glow pulsante en botones primarios, borde iluminado en secundarios, glow rojo en danger
• Empty state glassmorphism: bandeja vacía con card animada en lugar de texto plano
• Toast notifications: feedback visual al crear, editar y eliminar eventos del calendario
• Fix bug NaN: eventos de calendario recién creados ya muestran fecha correcta (normalización de respuesta de Google Calendar API)

---

Instalación y uso

Requisitos previos

• Python 3.11+
• Node.js 18+
• Una cuenta de Google con Gmail habilitado
• API Key de Google Gemini (gratuita)
• Un proyecto en Google Cloud Console con Gmail API y Google Calendar API habilitadas

1. Clonar el repositorio

git clone https://github.com/DeibyGS/email-agent.git
cd email-agent

2. Configurar credenciales de Google OAuth2

1. Ve a Google Cloud Console → APIs y servicios → Credenciales
2. Crea unas credenciales de tipo OAuth 2.0 (aplicación de escritorio)
3. Descarga el archivo JSON y renómbralo como credentials.json
4. Colócalo en backend/credentials.json

El archivo token.json se genera automáticamente la primera vez que arranques el proyecto — el navegador se abrirá para que autorices el acceso a tu cuenta de Google.

3. Configurar variables de entorno

cd backend
cp .env.example .env

Edita backend/.env y completa al menos GEMINI_API_KEY con tu clave de Gemini. El resto de variables tiene valores por defecto funcionales.

4. Instalar dependencias

# Backend
cd backend
python -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate
pip install -r requirements.txt

# Frontend
cd ../frontend
npm install

5. Arrancar el proyecto

Desde la raíz del proyecto:

./email-agent

Esto inicia el backend (puerto 8000), el frontend (puerto 5173) y abre el navegador automáticamente.

Para usar email-agent desde cualquier directorio, crea un symlink global:

sudo ln -sf $(pwd)/email-agent /usr/local/bin/email-agent

Para detener: Ctrl+C

Arranque manual

# Terminal 1 — Backend
cd backend && source .venv/bin/activate && python main.py

# Terminal 2 — Frontend
cd frontend && npm run dev

Arranque con Docker

# Requisito: tener backend/credentials.json y backend/token.json generados (OAuth2)
docker-compose up --build

Servicios disponibles:

• Backend: http://localhost:8000
• Frontend: http://localhost:3000

Tests

# Backend
cd backend && source .venv/bin/activate && pytest tests/ --ignore=tests/test_scheduler.py -v

# Frontend
cd frontend && npm test              # modo watch
cd frontend && npm run test:coverage # con reporte de cobertura

---

Variables de entorno

Copiar backend/.env.example a backend/.env y completar:

Variable	Descripción	Ejemplo
GEMINI_API_KEY	API Key de Google Gemini	AIza...
GMAIL_FILTER_AFTER_DATE	Solo procesar correos después de esta fecha	2026/03/20
MAX_EMAILS_PER_RUN	Máximo de correos por ciclo	100
CHECK_INTERVAL_MINUTES	Intervalo del scheduler automático	30
QUIET_HOURS_START	Hora de inicio del descanso (0–23)	0
QUIET_HOURS_END	Hora de fin del descanso (0–24)	8

Las credenciales OAuth2 de Google se guardan en backend/credentials.json y backend/token.json (no se suben al repositorio).

---

Estructura del proyecto

email-agent/
├── backend/
│   ├── config/settings.py          # Variables de entorno y credenciales
│   ├── src/
│   │   ├── gmail/client.py         # Cliente Gmail API
│   │   ├── ai/classifier.py        # Clasificador Gemini
│   │   ├── calendar/client.py      # Cliente Calendar API
│   │   ├── scheduler/job.py        # Pipeline de procesamiento
│   │   ├── database/
│   │   │   ├── models.py           # Modelos SQLAlchemy
│   │   │   ├── repository.py       # Acceso a datos
│   │   │   └── init_db.py          # Inicialización SQLite
│   │   └── api/
│   │       ├── routes.py           # Endpoints principales
│   │       └── calendar_router.py  # Endpoints de calendario
│   ├── tests/
│   ├── main.py
│   └── requirements.txt
├── frontend/
│   └── src/
│       ├── components/             # Navbar, EmailCard, modales
│       ├── pages/                  # EmailsPage · StatsPage · CalendarPage
│       ├── services/api.ts         # Llamadas al backend
│       └── types/index.ts          # Interfaces TypeScript
├── docs/API.md                     # Referencia completa de la API REST
├── docker-compose.yml              # Orquestación backend + frontend
├── .github/workflows/ci.yml        # CI: pytest · ruff · vitest · docker build
└── email-agent                     # Script de arranque rápido (local)

---

API

Ver referencia completa en docs/API.md.

Base URL local: http://localhost:8000