# Integración de Asistente IA con Base de Datos Secundaria (Text-to-SQL)

El objetivo es permitir que el asistente, desde el chat, pueda responder preguntas formuladas en lenguaje natural consultando una base de datos secundaria. Para lograr esto, el asistente debe conocer la estructura de las tablas permitidas, convertir la intención del usuario en consultas SQL, ejecutar la consulta de forma segura y devolver una respuesta interpretada.

## Gestión del Prompt y Optimización de Costos

- **¿Se construye el prompt en cada petición?** Sí, el LLM es "stateless" (sin estado), por lo que en cada petición que requiera consultar la base de datos, necesita recibir el esquema de las tablas permitidas en su *System Prompt*.
- **¿Es óptimo en cuanto a costos?** Sí, está diseñado para ser altamente eficiente:
  1. **Filtrado estricto:** Solo se envía el esquema de las tablas específicas configuradas.
  2. **Caché del Esquema:** El resultado de leer la estructura de la base de datos se guarda en caché (`Cache::remember`).
  3. **Solo DDL Esencial:** Se omiten detalles innecesarios como índices, collations o llaves primarias complejas.

## ¿Dónde se especifican las tablas y cómo sabe la IA qué significan las columnas?

1. **Configuración de Tablas**: En el archivo `config/agent.php` (sección `agent_database`), donde puedes añadir el nombre de la tabla y una pequeña descripción.
2. **Comentarios de las Columnas**: La implementación extrae los metadatos directamente del motor de base de datos usando `Schema::getColumns()`. El asistente lee automáticamente el comentario definido en cada columna en tu base de datos nativa.

## Resumen de la Implementación (Ya ejecutada en código)

1. **Variables de Conexión (`AGENT_DB_*`)**
   Se añadió la conexión `agent_db_secondary` en `config/database.php`.

2. **Servicio de Extracción de Esquema (`DatabaseSchemaService`)**
   Servicio (`app/Services/Agent/DatabaseSchemaService.php`) que lee las tablas permitidas, consulta el esquema (incluyendo los comentarios) y genera un DDL simplificado.

3. **Handler de Capacidad (`AgentDatabaseQueryCapabilityHandler`)**
   Handler (`app/Services/Agent/Handlers/AgentDatabaseQueryCapabilityHandler.php`) que utiliza **JSON Mode**. Inyecta el esquema al LLM y espera un JSON `{"query": "SELECT ..."}`.
   Tiene validación estricta de seguridad: la consulta debe empezar por `SELECT`.

4. **Registro en el Orquestador**
   Registrado en `app/Enums/AgentCapability.php` y `app/Services/Agent/AgentOrchestratorService.php`.

## Instrucciones de Configuración Local

Añade las siguientes variables a tu archivo `.env`:

```env
# Conexión del Agente a la BD Secundaria
AGENT_CAPABILITY_AGENT_DATABASE=true
AGENT_DB_CONNECTION=mysql
AGENT_DB_HOST=127.0.0.1
AGENT_DB_PORT=3306
AGENT_DB_DATABASE=nombre_de_tu_db
AGENT_DB_USERNAME=usuario_solo_lectura
AGENT_DB_PASSWORD=tu_password
```

Y luego, edita el array en `config/agent.php` añadiendo tus tablas reales:

```php
'agent_database' => [
    'connection' => 'agent_db_secondary',
    'allowed_tables' => [
        'nombre_tabla_1' => 'Breve descripción de qué contiene esta tabla',
        'nombre_tabla_2' => 'Breve descripción de esta otra tabla',
    ],
],
```