🌌 FinOps AI Agent Dashboard

El cuadro de mando premium para la gobernanza, optimización de costes y auditoría del consumo de tokens de agentes de IA en el ecosistema Megacore.

El FinOps AI Agent Dashboard es una solución integral diseñada para monitorizar, auditar y optimizar el consumo y gasto derivado del uso de Modelos de Lenguaje Grande (LLMs) por parte de agentes autónomos. Forma parte del ecosistema de calidad Megacore de Megasoft, proporcionando visibilidad en tiempo real del gasto de tokens y aplicando prácticas recomendadas de FinOps de forma automatizada.

---

🎨 Características Principales

El dashboard ofrece una interfaz interactiva y accesible que incluye:

1. Resumen de Métricas Clave (KPIs):

   • Inversión Acumulada: Gasto total en euros (€) acumulado durante las últimas 168 horas (7 días).
   • Tokens Procesados: Volumen total de tokens de entrada y salida procesados, medidos en millones (M).

2. Auditoría Visual de Consumo (Gráficos):

   • Línea Temporal de Gasto: Gráfico de líneas interactivo de Chart.js que muestra la evolución del coste diario de los últimos 7 días.
   • Distribución por Modelo: Gráfico circular (Doughnut) que segmenta visualmente el porcentaje de coste consumido por cada modelo específico (gpt-4o, gemini-1.5-flash, etc.).

3. Recomendaciones Inteligentes de FinOps:

   • Generación automática de recomendaciones de ahorro (ej. migrar tareas rutinarias de modelos caros a modelos eficientes como gemini-1.5-flash cuando se detecta un ratio elevado de tokens de entrada).

4. Detector de Anomalías y Picos de Gasto:

   • Panel dinámico que detecta llamadas individuales que superan un umbral de coste configurable en euros (€) (por defecto 0,25 €), alertando sobre comportamientos anómalos o bucles infinitos de los agentes.

5. Exportación de Informes de Cumplimiento:

   • Descarga instantánea de informes consolidados de consumo en formato JSON, estructurados y listos para justificar costes o archivar auditorías.

6. Accesibilidad Completa (A11y):

   • Diseñado con soporte de anuncios para lectores de pantalla (A11yAnnouncer), tablas de datos alternativas para los gráficos visuales y navegación por teclado optimizada.

---

🔌 Arquitectura y Flujo de Datos

El sistema funciona de manera descentralizada mediante un proxy local (AI Gateway) que intercepta las peticiones de los agentes, registra las métricas en una base de datos SQLite y reenvía las solicitudes a los proveedores de modelos reales.

sequenceDiagram
    autonumber
    actor Agente as "Agente Megacore"
    participant Gateway as "AI Gateway Proxy (Puerto 8000)"
    participant DB as "Base de Datos SQLite (usage_logs.db)"
    participant Proveedor as "Proveedores Reales (OpenAI / Gemini)"
    participant UI as "React UI Dashboard (Puerto 5174)"

    Agente->>Gateway: POST /v1/chat/completions (Headers: X-Agent-Name)
    activate Gateway
    Gateway->>Proveedor: Reenvia peticion con API Key real
    activate Proveedor
    Proveedor-->>Gateway: Retorna respuesta y tokens de uso
    deactivate Proveedor
    Gateway->>DB: INSERT/REPLACE en logs (modelo, coste, tokens, latencia, agente)
    Gateway-->>Agente: Retorna respuesta de completado
    deactivate Gateway

    UI->>Gateway: GET /api/usage
    activate Gateway
    Gateway->>DB: SELECT logs (LIMIT 150)
    DB-->>Gateway: Retorna registros
    Gateway-->>UI: Retorna JSON con historial de uso
    deactivate Gateway

---

🛠️ Guía de Instalación y Configuración ("For Dummies")

Sigue estos sencillos pasos para instalar el frontend y poner en marcha el proxy local en tu máquina.

Paso 1: Prerrequisitos

Asegúrate de tener instalados en tu sistema:

• Node.js (versión 18 o superior)
• Python 3 (para ejecutar el Gateway)
• SQLite3

Paso 2: Instalación del Frontend React

1. Abre tu terminal en el directorio raíz de la aplicación.
2. Instala los paquetes y dependencias requeridas mediante npm:

   npm install
   

Paso 3: Ejecución del Servidor de Desarrollo

1. Lanza el servidor local de desarrollo con Vite:

   npm run dev
   

2. Por defecto, el frontend estará disponible en la dirección: http://localhost:5174

Paso 4: Configuración del Servicio de Usuario Local de Systemd

Para mantener el proxy AI Gateway ejecutándose en segundo plano y garantizar que se inicie automáticamente con tu sistema, configúralo como un servicio de usuario de systemd:

1. Crea el directorio de servicios de usuario si no existe:

   mkdir -p ~/.config/systemd/user/
   

2. Crea el archivo de servicio en esa ruta:

   nano ~/.config/systemd/user/finops-ai-gateway.service
   

3. Pega el siguiente contenido (asegúrate de que las rutas coincidan con tu instalación local):

   [Unit]
   Description=FinOps AI Gateway Local Proxy
   After=network.target
   
   [Service]
   Type=simple
   WorkingDirectory=/home/asanchez/Code/forgejo/repositorios/finops-ai-dashboard
   ExecStart=/usr/bin/python3 scripts/ai_gateway.py
   Restart=always
   RestartSec=5
   
   [Install]
   WantedBy=default.target
   

4. Recarga la configuración de systemd de usuario para detectar el nuevo servicio:

   systemctl --user daemon-reload
   

5. Habilita el servicio para que se inicie automáticamente al arrancar el sistema:

   systemctl --user enable finops-ai-gateway.service
   

6. Inicia el servicio inmediatamente:

   systemctl --user start finops-ai-gateway.service
   

Comandos de Control Rápidos:

• Verificar el estado del servicio:

  systemctl --user status finops-ai-gateway.service
  

• Detener el servicio:

  systemctl --user stop finops-ai-gateway.service
  

• Reiniciar el servicio:

  systemctl --user restart finops-ai-gateway.service
  

• Ver logs del gateway en tiempo real:

  journalctl --user -u finops-ai-gateway.service -f
  

---

🔀 Cómo Enrutar las Peticiones de tus Agentes

Una vez que el gateway esté activo en el puerto 8000, puedes enrutar de forma transparente el tráfico de tus agentes de IA para que sea auditado en el Dashboard.

Opción A: Enrutamiento Global vía Variables de Entorno

Configura tu sesión de terminal o el entorno del agente para redirigir todas las peticiones que utilicen la biblioteca oficial de OpenAI u otra compatible:

export OPENAI_BASE_URL="http://localhost:8000/v1"

Nota: Con esta variable de entorno, cualquier cliente de OpenAI local redirigirá sus llamadas a tu proxy local.

Opción B: Configuración Explícita en Código Python

Puedes pasar la dirección del proxy y cabeceras de metadatos directamente al inicializar el cliente en tus scripts de Python:

from openai import OpenAI

# Inicializa el cliente apuntando al puerto del gateway local
client = OpenAI(
    base_url="http://localhost:8000/v1",
    api_key="local-proxy"  # El Gateway usará la API key real guardada en su fichero .env
)

# Realiza la llamada enviando el identificador del agente para su monitorización
response = client.chat.completions.create(
    model="gpt-4o",
    messages=[
        {"role": "user", "content": "Genera una recomendación de ahorro en la nube."}
    ],
    extra_headers={
        "X-Agent-Name": "CobroAgent-Prod"  # Cabecera para mapear el consumo a este agente en el dashboard
    }
)

print(response.choices[0].message.content)

---

📁 Estructura del Proyecto y Tecnologías

Ficheros Clave

• src/App.tsx: Componente raíz del frontend que coordina el estado y actualiza los logs.
• src/components/TokenAuditor.tsx: Gráficos interactivos de evolución de coste y distribución por modelo (Doughnut/Line).
• src/components/CostSpikes.tsx: Módulo interactivo de detección de picos de gasto con umbral configurable.
• src/components/FinOpsRecommendations.tsx: Lógica y visualización de recomendaciones de optimización.
• src/components/FinOpsReports.tsx: Generación y exportación de informes en formato JSON.
• scripts/ai_gateway.py: Proxy/Gateway local escrito en Python para interceptar, registrar e insertar datos en SQLite, y reenviar a APIs oficiales.
• usage_logs.db: Base de datos local SQLite donde se registran las auditorías de llamadas.

Stack Tecnológico

• Frontend: React (v18), TypeScript, Vite (v5)
• Estilos: Vanilla CSS con variables de diseño personalizadas y efecto glassmorphism
• Gráficos: Chart.js y React-Chartjs-2
• Iconografía: Lucide React
• Tipografía: Outfit (offline, vía @fontsource/outfit)
• Backend: Python 3 (librerías integradas http.server y urllib)
• Base de datos: SQLite