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

El `BotConocimientoModel` es el componente encargado de gestionar la base de conocimientos específica para cada asistente. Su función principal es actuar como un repositorio de fragmentos de información (pregunta-respuesta) que se inyectan en el contexto de la IA para proporcionar respuestas técnicamente precisas y fundamentadas en datos reales.

---

## Estructura de la Entidad

Este modelo mapea la tabla `bot_agente_conocimiento`, la cual organiza la información técnica mediante un sistema de etiquetado.

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

* **id_agente**: Identificador del agente al que pertenece este fragmento de conocimiento.
* **pregunta_clave**: Resumen o pregunta corta que activa este conocimiento.
* **contenido_respuesta**: La información técnica detallada que se proporcionará al modelo de lenguaje.
* **etiquetas**: Cadena de texto (normalmente separada por comas) utilizada para la clasificación y búsqueda semántica.
* **es_dinamico**: Indicador booleano que prioriza fragmentos que requieren procesamiento adicional o actualizaciones frecuentes.

---

## Métodos Destacados

### `getConocimientoOptimizado(int $id_agente, array $categorias, int $limite)`

* **Propósito**: Recupera fragmentos de conocimiento filtrados por relevancia y etiquetas para evitar saturar el contexto del modelo.
* **Lógica**: Utiliza un constructor de consultas para buscar coincidencias (`LIKE`) entre las etiquetas proporcionadas y las almacenadas en la base de datos, priorizando siempre el contenido marcado como dinámico.

### `getTagsByAgente(int $id_agente)`

* **Propósito**: Genera una lista única y limpia de todas las etiquetas disponibles para un agente.
* **Lógica**: Extrae todas las cadenas de etiquetas, las descompone en arreglos, aplana la estructura y elimina duplicados. Esta lista es vital para el proceso de clasificación de intenciones en el controlador de chat.

---

## Configuración del Modelo

| Propiedad | Valor | Descripción |
| --- | --- | --- |
| `$table` | `bot_agente_conocimiento` | Tabla que almacena los recursos técnicos del bot. |
| `$primaryKey` | `id` | Identificador único del fragmento de conocimiento. |
| `$returnType` | `array` | Los resultados se manejan como arreglos para facilitar su manipulación en la librería Gemini. |

---

## Ejemplo de Implementación

### Recuperación de contexto para el prompt

Este ejemplo muestra cómo se obtienen los recursos técnicos que luego se envían a la librería `GeminiClient`:

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

$conocimientoModel = new BotConocimientoModel();

// 1. Obtener etiquetas para clasificar la duda del usuario
$tags = $conocimientoModel->getTagsByAgente(1);

// 2. Si el usuario pregunta por "pagos", recuperamos solo lo relevante
$contextoTecnico = $conocimientoModel->getConocimientoOptimizado(1, ['pagos', 'facturación'], 2);

foreach ($contextoTecnico as $recurso) {
    echo "Duda: " . $recurso['pregunta_clave'];
    echo "Solución: " . $recurso['contenido_respuesta'];
}

```

---

## Casos de Uso

### 1. Generación Aumentada por Recuperación (RAG)

En lugar de que la IA responda basándose solo en su entrenamiento general, el `BotConocimientoModel` le provee "manuales" específicos en tiempo de ejecución. Esto reduce las alucinaciones y garantiza que el bot de una empresa hable con propiedad sobre sus propios servicios.

### 2. Filtrado Inteligente de Contexto

Enviar miles de líneas de texto a una IA es costoso y lento. Este modelo permite, a través de `getConocimientoOptimizado`, seleccionar únicamente los 3 o 5 fragmentos más probables de contener la respuesta, optimizando el uso de tokens y la velocidad de respuesta.

### 3. Mantenimiento Modular del Saber

Los administradores pueden añadir, editar o eliminar fragmentos de conocimiento desde un panel de gestión sin alterar la lógica de programación. Al actualizar una fila en `bot_agente_conocimiento`, todos los agentes vinculados actualizan su "conocimiento" de forma inmediata.