FacturIA 2.0
Sistema Inteligente de Gestión Financiera

🎯 Descripción del Proyecto

FacturIA 2.0 es un sistema end-to-end que revoluciona la gestión contable empresarial mediante la automatización completa del proceso de análisis financiero. A diferencia de su versión anterior que solo procesaba PDFs manualmente, esta segunda versión implementa un ecosistema completo con monitor de email 24/7, clasificación automática con IA, base de datos robusta y dashboard web interactivo.

Evolución desde FacturIA 1.0:

• Monitor automático de email con Gmail IMAP que revisa constantemente tu casilla
• Detección automática de personas a partir del remitente del email
• Google Gemini 2.0 Flash (última versión) con optimización para free tier (15 RPM)
• Dashboard web interactivo con Streamlit (multi-página con 4 secciones especializadas)
• Base de datos SQLAlchemy con soporte SQLite/PostgreSQL
• Sistema de notificaciones por email con resúmenes HTML profesionales
• Exportaciones avanzadas a Excel y PDF con formato profesional
• Rate limiting inteligente y circuit breaker para evitar costos en APIs
• Manejo robusto de UTF-8 para caracteres especiales del español

🚀 Problema que Resuelve

Las pequeñas empresas y freelancers enfrentan un desafío crítico: gestionar manualmente decenas de comprobantes que llegan por email cada mes. Este proceso consume horas valiosas, es propenso a errores humanos y dificulta la toma de decisiones financieras oportunas.

⚙️ Arquitectura del Sistema

FacturIA 2.0 implementa una arquitectura modular con 5 componentes principales que trabajan de manera coordinada:

1. Monitor de Email (email_monitor/)

• Conexión IMAP persistente con Gmail
• Busca emails con adjuntos cada 5 minutos (configurable)
• Filtra por palabras clave: "factura", "comprobante", "recibo"
• Descarga PDFs, PNGs y JPGs automáticamente
• Evita duplicados mediante tracking de Message-ID
• Extracción inteligente de personas: detecta el remitente desde el email

2. Procesador con IA (ai_processor/)

• Google Gemini 2.0 Flash (modelo multimodal más reciente)
• Analiza PDFs e imágenes de comprobantes
• Extrae: tipo (ingreso/egreso), categoría, monto, fecha, emisor, número de comprobante
• Rate limiting inteligente: respeta límite de 15 RPM del free tier
• Circuit breaker: pausa procesamiento si detecta múltiples fallos consecutivos
• Error recovery: corrige JSON malformado automáticamente
• Confianza ajustable: marca transacciones que requieren revisión manual

3. Base de Datos (database/)

• SQLAlchemy ORM para abstracción completa de SQL
• Soporte multi-DB: SQLite (desarrollo) y PostgreSQL (producción)
• Modelo de datos robusto con 20+ campos:
  • Información financiera: tipo, categoría, monto, fecha
  • Metadata: persona, emisor/receptor, descripción
  • Auditoría: fecha de creación, edición manual, última modificación
  • Flags: requiere_revision, editado_manualmente, confianza_ia
• CRUD operations completas con validaciones
• Script de limpieza incluido (limpiar_db.py)

4. Dashboard Interactivo (dashboard/)

• Streamlit Framework con 4 páginas especializadas:
  1. Principal: KPIs, gráficos de evolución temporal, distribución por categorías
  2. Revisar Transacciones: edición manual con interfaz intuitiva, búsqueda y filtros avanzados
  3. Cargar CSV: importación masiva con mapeo de columnas y validación
  4. Configuración: estadísticas del sistema y mantenimiento
• Visualizaciones con Plotly: gráficos interactivos 100% responsivos
• Filtros avanzados: por fecha, categoría, persona, tipo y origen
• Exportaciones profesionales: Excel con formato y PDF con gráficos

5. Sistema de Notificaciones (notifications/)

• Envía emails automáticos cuando se procesan nuevas transacciones
• HTML estilizado con formato profesional
• Incluye resumen estadístico y lista detallada de transacciones
• Soporte multi-destinatario

🛠️ Stack Tecnológico

📊 Funcionalidades Destacadas

1. Rate Limiting Inteligente

Optimizado para el free tier de Google Gemini (15 requests por minuto):

• Espera de 15 segundos entre archivos
• Exponential backoff en reintentos: 10s → 20s → 30s
• Circuit breaker: si fallan 10 archivos consecutivos, pausa 5 minutos
• Logging detallado de cada request para debugging

2. Detección Automática de Personas

Extrae nombres automáticamente desde el email del remitente:

• silva.puccini@gmail.com → Silva Puccini
• maria_rodriguez_123@hotmail.com → Maria Rodriguez
• info@empresa.com → Empresa (usa dominio)

3. Manejo Robusto de UTF-8

Procesa correctamente caracteres especiales del español:

• Acentos: á, é, í, ó, ú
• Ñ mayúscula y minúscula
• Símbolos: ¿, ¡, €, $
• Función safe_str() en todas las exportaciones

4. Exportaciones Profesionales

Excel (.xlsx):

• Encabezados en negrita con fondo azul
• Formato de moneda con símbolo $
• Columnas auto-ajustadas
• Filtros automáticos

PDF:

• Header profesional con título
• Tabla con bordes y colores alternados
• Pie de página con número de página y fecha
• Resumen estadístico al final

📈 Resultados y Métricas

💡 Desafíos Técnicos Resueltos

1. Rate Limiting de APIs Gratuitas: Implementé un rate limiter inteligente con exponential backoff y circuit breaker para respetar el límite de 15 RPM de Gemini sin perder procesamiento.
2. JSON Parsing con Errores: Gemini 2.0 a veces devuelve JSON con doble llaves {{ }}. Creé un sistema de detección y corrección automática que normaliza la respuesta antes de parsear.
3. UTF-8 Encoding en Español: Los caracteres especiales (á, é, í, ó, ú, ñ) causaban errores en exportaciones. Implementé la función safe_str() y declaraciones de encoding en todos los módulos.
4. Persistencia de Cambios en Streamlit: Los botones "Guardar" no persistían cambios porque st.rerun() terminaba el script antes del auto-commit. Solución: agregar session.commit() explícito antes de rerun.
5. Detección de Usuarios Duplicados: El sistema creaba múltiples usuarios para la misma persona por variaciones en el campo From del email. Implementé regex para extraer solo el email limpio desde "Nombre <email>".
6. Cambio de Modelo de Gemini: El modelo original (gemini-1.5-flash-8b) se deprecó. Migré a gemini-2.0-flash-exp ajustando delays y prompts para mantener precisión.

🎓 Aprendizajes Clave

• Arquitectura Modular: Diseñar sistemas con separación de responsabilidades (SoC) facilita el mantenimiento y escalabilidad.
• IA en Producción: Implementar rate limiting, error recovery y circuit breakers es esencial para sistemas que dependen de APIs externas.
• Full Stack Development: Integrar backend (Python), IA (Gemini), base de datos (SQLAlchemy) y frontend (Streamlit) en un flujo end-to-end.
• Ingeniería de Prompts: Diseñar prompts efectivos para extraer datos estructurados de manera consistente de documentos no estructurados.
• Testing en Producción: Los usuarios reales encuentran edge cases que los tests unitarios no cubren. Implementar logging exhaustivo es crucial.
• Optimización de Costos: Aprovechar free tiers de APIs (Gemini) con estrategias inteligentes de rate limiting puede resultar en sistemas $0 costo de operación.

🔗 Enlaces del Proyecto

• Ver Proyecto en GitHub