Feature: Smart Routing, Inteligencia de Costos y Dashboard de Stats

[thomas-vilte]

---

Plan de Implementación: Smart Routing y Control de Costos

Este documento detalla la estrategia para dotar a MateCommit de inteligencia financiera y optimización de ruteo, aprovechando el lanzamiento de Gemini 3.0 Flash. El objetivo principal es que la CLI deje de procesar datos de forma ciega y empiece a gestionar el presupuesto del usuario de manera eficiente.

1. Integración de Gemini 3.0 Flash

Considero que la gran novedad es este modelo, que mantiene la velocidad de las versiones anteriores pero con una capacidad de razonamiento cercana a los modelos Pro.

Tabla de Precios Oficial

Tipo de Token	Precio (por 1M)	Detalle
Input (Entrada)	$0.50	Diffs, contexto y prompts enviados
Output (Salida)	$3.00	Respuesta generada (commit, resumen, etc.)

Es importante destacar que la salida es seis veces más cara que la entrada, por lo que nuestras estimaciones deben ser sumamente precisas en ese apartado.

---

2. Lógica de Smart Routing

La idea es optimizar el gasto según la complejidad de la tarea. El sistema decidirá de forma automática o sugerirá la mejor opción siguiendo estos parámetros:

1. Diffs reducidos (< 1k tokens): Se procesarán con Gemini 2.5 Flash. Es la opción más económica y suficiente para cambios menores.
2. Diffs de gran volumen (> 10k tokens): Activaremos Gemini 3.0 Flash. Su mejor manejo de contexto evita alucinaciones cuando se analiza una gran cantidad de código.
3. Tareas de alta calidad (Releases y Docs): Para generar Changelogs o Issue Reports, priorizaremos el modelo 3.0 para asegurar una redacción superior.
4. Caché Local: Si se detecta que el diff no ha cambiado mediante una firma digital (hash), la respuesta se servirá desde el disco local. Costo: $0.

---

3. Flujo de Trabajo del Usuario (User Journey)

Implementaremos un proceso de validación previa antes de realizar cualquier llamada a la API:

1. El usuario ejecuta un comando, por ejemplo: matecommit summarize pr --n 50.
2. MateCommit realiza un conteo de tokens (sin costo) descartando archivos irrelevantes como logs o dependencias.
3. La CLI presenta una estimación clara:

   "El análisis de este PR requiere procesar aproximadamente 45.000 tokens. El costo estimado es de $0.01 USD. ¿Desea continuar? [Y/n]"

4. Tras la confirmación y ejecución, se informará el costo final real de la operación.

---

4. Cambios Técnicos y Arquitectura

Configuración y Modelos

Modificaremos internal/config/ai.go para incorporar formalmente a gemini-3.0-flash como opción disponible.

Servicio de Cálculo (internal/domain/services/cost/)

Crearemos un nuevo servicio que centralice las siguientes responsabilidades:

• CountTokens(): Uso de la API para obtener el conteo exacto antes de la petición.
• EstimateCost(): Cálculo basado en la tabla de precios vigente.
• CheckBudget(): Alerta al usuario si la operación supera un límite diario configurado (ej. $2.00 USD).

Historial y Persistencia

Guardaremos el detalle de cada operación en ~/.matecommit/history.json con la siguiente estructura:

• timestamp: Fecha y hora de la operación.
• model: Modelo de IA utilizado.
• latency_ms: Tiempo de respuesta de la API.
• cost_usd: Gasto real incurrido.
• tokens_saved: Tokens que no fueron facturados gracias al uso de caché.

---

5. Nuevos Comandos de Control

Añadiremos el comando matecommit cost (o stats) para que el usuario pueda visualizar su consumo:

• Resumen mensual de gastos.
• Métricas de ahorro logradas mediante el Smart Routing y la caché local.
• Visualización del uso de tokens de entrada y salida.

---

6. Plan de Pruebas y Validación

Para asegurar la precisión del sistema, realizaremos:

1. Tests Unitarios: Verificación de que el cálculo de tokens e importes coincida exactamente con la facturación de Google.
2. Dry Runs: Pruebas en entornos reales comparando las estimaciones de la CLI contra el dashboard de facturación de la Google Cloud Console.
3. Filtros de Contexto: Validar que archivos pesados como go.sum o package-lock.json sean efectivamente ignorados en el conteo.

Criterios de Aceptación

• Implementación de CountTokens excluyendo archivos binarios y de lock.
• Lógica de ruteo funcionando (Flash para volumen, 3.0 para calidad y razonamiento).
• Persistencia de historial en archivo JSON local.
• Comando de estadísticas con métricas de consumo y ahorro.
• Solicitud de confirmación de costo antes de operaciones de gran volumen.

---