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

`GeminiClient` es una librería robusta para la integración de modelos de lenguaje **Google Gemini** en aplicaciones PHP (específicamente diseñada para el framework CodeIgniter 4). Permite gestionar conversaciones con memoria (historial), clasificar intenciones de usuario y realizar re-ranking de fragmentos de conocimiento para optimizar el contexto enviado al modelo.

---

## Especificaciones Técnicas

### Propiedades

* **$client**: Instancia de `CURLRequest` para manejar las peticiones HTTP.
* **$apiKey**: Llave de autenticación cargada desde el entorno (`.env`).
* **$baseUrl**: Endpoint base de la API de Google Generative Language (v1beta).
* **$models**: Listado de modelos disponibles, incluyendo versiones Flash, Pro y experimentales.

### Métodos Principales

#### `consultar()`

Es el motor principal de generación de respuestas.

* **Propósito**: Generar una respuesta basada en la personalidad del bot, el historial de chat y el conocimiento técnico inyectado.
* **Parámetros**:
* `string $pregunta`: El mensaje actual del usuario.
* `string $personalidad`: Instrucciones de sistema (System Prompt).
* `array $conocimientoArray`: Datos técnicos para alimentar el contexto.
* `array $historial`: Mensajes previos para mantener la coherencia.
* `int $model`: Índice o nombre del modelo a utilizar (por defecto Flash 2.5).



#### `clasificarPregunta()`

* **Propósito**: Identificar la intención del usuario comparándola contra una lista de etiquetas permitidas (tags) y categorías de cortesía.
* **Configuración**: Utiliza una temperatura de **0.0** para garantizar resultados deterministas y precisos.

#### `reRankearContexto()`

* **Propósito**: Filtrar y seleccionar los fragmentos de información más relevantes de una lista de candidatos antes de generar la respuesta final.
* **Retorno**: Un arreglo con los IDs de los fragmentos que realmente aportan valor a la consulta.

#### `guardarLogGlobal()`

* **Propósito**: Persistir cada petición y respuesta en la base de datos (vía `BotLogExcesoModel`) para auditoría de tokens y depuración de errores.

---

## Ejemplo de Implementación

A continuación, se muestra cómo inicializar la librería y realizar una consulta técnica básica:

```php
use App\Libraries\GeminiClient;

$gemini = new GeminiClient();

// 1. Definir el contexto y personalidad
$personalidad = "Eres un asistente técnico de soporte para una empresa de software.\nSé breve y profesional.";
$historial = [
    ['rol' => 'user', 'contenido' => 'Hola, ¿qué tal?'],
    ['rol' => 'model', 'contenido' => 'Hola, ¿en qué puedo ayudarte hoy?']
];

// 2. Simular conocimiento extraído de DB
$conocimiento = [
    [
        'pregunta_clave' => '¿Cómo resetear contraseña?',
        'contenido_respuesta' => 'Ir a Ajustes > Seguridad > Cambiar clave.'
    ]
];

// 3. Ejecutar consulta
try {
    $respuesta = $gemini->consultar(
        "Olvidé mi clave, ¿qué hago?",
        $personalidad,
        $conocimiento,
        $historial
    );

    if ($respuesta['success']) {
        echo "Bot: " . $respuesta['mensaje'];
        echo "Tokens usados: " . $respuesta['tokens'];
    }
} catch (\Exception $e) {
    echo "Error: " . $e->getMessage();
}

```

---

## Casos de Uso

### 1. Clasificación de Intenciones (NLU)

Antes de procesar una respuesta costosa, el sistema utiliza `clasificarPregunta` para saber si el usuario está saludando, despidiéndose o haciendo una pregunta técnica. Si se detecta un "saludo", se puede omitir la búsqueda en la base de datos de conocimiento para ahorrar recursos.

### 2. Optimización de Contexto (RAG)

En sistemas con bases de datos de conocimiento extensas, `reRankearContexto` actúa como un filtro inteligente. Si una búsqueda semántica devuelve 10 resultados, este método le pregunta a un modelo ligero (como Flash Lite) cuáles 3 son realmente útiles para la pregunta específica del usuario, reduciendo el ruido en el prompt final.

### 3. Monitoreo de Consumo y Auditoría

Mediante `guardarLogGlobal`, la librería registra el `payload` exacto enviado a Google y la respuesta recibida. Esto es vital para:

* Calcular costos por agente.
* Detectar si el modelo está "alucinando" debido a instrucciones contradictorias.
* Mantener un histórico de cumplimiento de límites de tokens.