# Documentación Técnica: BotLogExcesoModel (PHP)

El `BotLogExcesoModel` es el componente de auditoría y monitoreo de la arquitectura. Su propósito es registrar de forma íntegra las interacciones con la API de Gemini que superan los umbrales de consumo definidos o que requieren un seguimiento detallado por su complejidad. Este modelo es fundamental para el control de costos, la depuración de respuestas y el análisis del comportamiento del modelo de lenguaje.

---

## Estructura de la Entidad

El modelo gestiona la tabla `bot_logs_exceso_tokens`, la cual almacena tanto la petición enviada como la respuesta cruda del proveedor.

### Atributos y Campos Permitidos (`$allowedFields`)

* **id_agente**: Identificador del agente que originó la petición.
* **tokens_totales**: Cantidad exacta de tokens consumidos en el turno (incluyendo clasificación y re-ranking).
* **limite_configurado**: El umbral (threshold) que disparó el registro del log.
* **endpoint**: El modelo y versión de la API de Gemini utilizada (ej. `gemini-2.5-flash`).
* **payload_enviado**: Representación JSON completa de las instrucciones, historial y contexto enviados a la IA.
* **respuesta_recibida**: Respuesta cruda de la API, útil para analizar metadatos y estructuras de razonamiento.
* **fecha_registro**: Marca de tiempo de la interacción.
* **grupo_key**: Hash o ID único que agrupa múltiples peticiones (como clasificación y consulta) pertenecientes a un mismo turno de usuario.

---

## Configuración del Modelo

| Propiedad | Valor | Descripción |
| --- | --- | --- |
| `$table` | `bot_logs_exceso_tokens` | Tabla destinada al almacenamiento de logs pesados. |
| `$primaryKey` | `id` | Identificador único de cada registro de log. |
| `$returnType` | `array` | Las consultas devuelven arreglos asociativos de PHP. |

---

## Ejemplo de Implementación

### Registro Automático desde la Librería

Este modelo es invocado automáticamente por `GeminiClient` cuando el conteo de tokens excede el límite configurado en el agente:

```php
use App\Models\Bot\BotLogExcesoModel;

// Ejemplo de registro manual en caso de error o auditoría
$logModel = new BotLogExcesoModel();

$logModel->save([
    'id_agente'          => 1,
    'tokens_totales'     => 1850,
    'limite_configurado' => 1500,
    'endpoint'           => 'models/gemini-2.0-flash:generateContent',
    'payload_enviado'    => json_encode($datosEnviados),
    'respuesta_recibida' => $jsonRespuesta,
    'fecha_registro'     => date('Y-m-d H:i:s'),
    'grupo_key'          => 'log_65a1234b5678'
]);

```

---

## Casos de Uso

### 1. Auditoría de Costos (FinOps)

Permite identificar qué usuarios o qué tipos de preguntas están generando un consumo inusualmente alto de tokens. Al analizar el `payload_enviado`, los administradores pueden detectar si el contexto inyectado (RAG) está siendo demasiado extenso o irrelevante.

### 2. Depuración de "Alucinaciones"

Cuando un bot responde de manera incorrecta, el campo `respuesta_recibida` permite ver exactamente qué procesó la IA. Esto ayuda a ajustar la `instruccion_sistema` en el `BotAgenteModel` para corregir comportamientos no deseados.

### 3. Monitoreo de Rendimiento de Modelos

Al registrar el `endpoint` y los `tokens_totales`, se pueden comparar diferentes modelos de la familia Gemini para determinar cuál ofrece la mejor relación costo-beneficio para tareas específicas como la clasificación o la generación de texto técnico.