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

El `BotMensajeModel` es el componente encargado de la persistencia de cada interacción individual dentro de una conversación. Su función es vital para mantener la memoria del chat (historial), realizar el seguimiento del consumo de recursos (tokens) y almacenar metadatos de razonamiento de la IA.

---

## Estructura de la Entidad

Este modelo gestiona la tabla `bot_mensajes`, donde se almacenan secuencialmente las entradas tanto del usuario como del asistente.

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

* **id_chat**: Identificador de la sesión de chat a la que pertenece el mensaje.
* **rol**: Define el origen del mensaje (usualmente `1` para usuario y `2` para el modelo/asistente).
* **contenido**: El texto íntegro del mensaje enviado o recibido.
* **firma_pensamiento**: Campo de metadatos (JSON) que almacena detalles técnicos del turno, como tags detectados, IDs de conocimiento usados y desglose de tokens.
* **tokens_usados**: Registro numérico del costo del mensaje en términos de procesamiento de lenguaje.

---

## Métodos Destacados

### `getHistorialChat(int $idChat)`

* **Propósito**: Recupera todos los mensajes asociados a una sesión específica.
* **Uso**: Es fundamental para el `Chat` controller, ya que permite enviar el contexto previo a Gemini para mantener la coherencia en la charla.

### `guardarHistorialChat(array $userMsg, array $modelMsg)`

* **Propósito**: Realiza una inserción doble en una sola operación lógica.
* **Lógica**: Guarda simultáneamente el mensaje que envió el usuario y la respuesta generada por la IA, asegurando que el historial siempre esté balanceado.

### `getTokensConsumidosMes(int $idAgente)`

* **Propósito**: Calcula el consumo acumulado de un agente durante el mes actual.
* **Lógica**: Realiza un `JOIN` entre las tablas de mensajes y chats para sumar los tokens de todas las sesiones de un agente específico dentro del rango de fechas del mes en curso.

---

## Configuración del Modelo

| Propiedad | Valor | Descripción |
| --- | --- | --- |
| `$table` | `bot_mensajes` | Tabla de almacenamiento de interacciones. |
| `$primaryKey` | `id` | Identificador único del mensaje. |
| `$returnType` | `array` | Las filas se retornan como arreglos asociativos. |

---

## Ejemplo de Implementación

### Control de Cuota Mensual

El sistema utiliza este modelo para prevenir excesos de facturación antes de procesar un nuevo mensaje:

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

$mensajeModel = new BotMensajeModel();
$idAgente = 5;

// Obtener consumo actual
$consumo = $mensajeModel->getTokensConsumidosMes($idAgente);
$limite = 500000; // Ejemplo de límite de 500k tokens

if ($consumo >= $limite) {
    die("Límite mensual alcanzado para este agente.");
}

```

---

## Casos de Uso

### 1. Memoria de Corto Plazo (Context Window)

El `Chat` controller llama a `getHistorialChat` para alimentar la propiedad `contents` de la API de Gemini. Esto permite que el bot recuerde, por ejemplo, el nombre del usuario mencionado tres mensajes atrás.

### 2. Análisis de Calidad con la "Firma de Pensamiento"

Al almacenar la `firma_pensamiento`, los administradores pueden auditar por qué el bot dio una respuesta específica, viendo qué etiquetas se detectaron y qué fragmentos de conocimiento se seleccionaron en ese turno exacto.

### 3. Facturación y Límites de Uso

El método `getTokensConsumidosMes` permite implementar políticas de uso justo (Fair Use Policy). Es la herramienta principal para que el sistema pueda suspender temporalmente un agente si este ha consumido su presupuesto de tokens asignado en el archivo `.env` o en la configuración.