# Documentación Técnica: Controlador de Chat (Gemini Ecosystem)

El controlador `Chat.php` es el núcleo de la lógica de interacción entre el usuario y los agentes de Inteligencia Artificial. Gestiona el ciclo de vida de la conversación, desde la autenticación (estudiantes o usuarios temporales) hasta el procesamiento de lenguaje natural mediante la integración con la API de Gemini.

---

## 1. Arquitectura Técnica

El controlador está construido sobre **CodeIgniter 4** y utiliza una arquitectura de servicios para la resolución de conocimientos y el procesamiento de tokens.

### Dependencias Principales

* **GeminiClient:** Librería personalizada para la comunicación con modelos de lenguaje.
* **VariableResolver:** Servicio para procesar variables dinámicas dentro del conocimiento extraído.
* **Modelos:**
* `BotAgenteModel`: Gestión de personalidades y configuración de IA.
* `BotConocimientoModel`: Repositorio de información segmentada por tags.
* `BotMensajeModel`: Persistencia del historial y métricas de consumo (tokens).
* `BotUsuarioTemporalModel`: Registro de prospectos no inscritos.



---

## 2. Definición de Endpoints

### Acceso y Autenticación

| Método | Ruta | Descripción |
| --- | --- | --- |
| `seleccion()` | `/chat/seleccion` | Renderiza la galería de agentes activos disponibles. |
| `vincular($id)` | `/chat/vincular/{id}` | Formulario de identificación (Cédula o Registro Temporal). |
| `procesar_vinculacion()` | `/chat/procesar_vinculacion` | Valida estudiantes mediante servicios externos y reCAPTCHA. |
| `enviar_codigo_temporal()` | `/chat/enviar_codigo_temporal` | Genera y envía un código de 6 dígitos vía PHPMailer a visitantes. |
| `validar_codigo_temporal()` | `/chat/validar_codigo_temporal` | Verifica el código OTP para permitir el acceso a no-estudiantes. |

### Motor de Mensajería

| Método | Ruta | Descripción |
| --- | --- | --- |
| `send_message()` | `/chat/send_message` | **Endpoint Principal (POST).** Procesa el mensaje del usuario. |
| `index($id)` | `/chat/index/{id}` | Carga la interfaz de chat (UI) tras la autenticación exitosa. |

---

## 3. Flujo de Procesamiento de Mensajes (`send_message`)

El método `send_message` ejecuta un pipeline de IA en varias etapas para optimizar costos y precisión:

1. **Validación de Cuota:** Verifica si el agente ha superado el `MAX_TOKENS_MENSUALES`.
2. **Clasificación (Etiquetado):** La IA detecta intenciones (tags) a partir del mensaje.
3. **Recuperación de Conocimiento:** Se buscan fragmentos en la BD que coincidan con los tags detectados.
4. **Re-Ranking:** Si hay múltiples resultados, se re-ordenan para enviar solo los más relevantes al modelo.
5. **Detección de Cortesía:** Si es un saludo/despedida, evita la búsqueda exhaustiva para ahorrar recursos.
6. **Gestión de Preguntas No Respondidas:** Si no hay conocimiento suficiente, se registra un log para entrenamiento futuro y se redirige al soporte humano.
7. **Generación de Respuesta:** Se envía el prompt final al modelo configurado (ej. `gemini-2.0-flash`).

---

## 4. Ejemplo de Implementación

Para integrar el envío de mensajes desde el frontend (JavaScript/AJAX):

```javascript
async function enviarMensaje() {
    const formData = new FormData();
    formData.append('mensaje', '¿Cómo puedo inscribirme?');
    formData.append('id_agente', 5);
    formData.append('uuid_sesion', 'abc-123-unique-id');

    const response = await fetch('/chat/send_message', {
        method: 'POST',
        body: formData
    });

    const result = await response.json();

    if (result.status === 'success') {
        console.log('Respuesta de IA:', result.respuesta);
    } else {
        console.error('Error:', result.message);
    }
}

```

---

## 5. Casos de Uso

### Caso A: Atención al Estudiante Regular

Un alumno ingresa su cédula, el sistema recupera sus datos de sucursal y lo vincula con un agente de "Atención Académica". El controlador utiliza la sesión del estudiante para personalizar las respuestas.

### Caso B: Captación de Prospectos (Leads)

Un usuario interesado (no estudiante) solicita información. El controlador gestiona el envío de un código OTP a su correo. Una vez validado, se crea una sesión temporal `TEMP_email`, permitiendo al bot interactuar y registrar la inquietud.

### Caso C: Control de Costos Operativos

Si un agente configurado con un límite de 500,000 tokens alcanza su tope, el controlador bloquea automáticamente nuevas consultas, retornando un mensaje controlado al usuario y evitando excedentes en la facturación de la API de Google.

### Caso D: Mejora Continua (Log de Vacíos)

Cuando un usuario pregunta algo fuera de la base de conocimientos, el controlador dispara una inserción en `BotPreguntaNoRespondidaModel`. El administrador del sistema puede revisar estos logs para alimentar la base de conocimientos posteriormente.