DB Chat Agent 🤖

Un sistema de chat interactivo que permite a los usuarios consultar una base de datos PostgreSQL utilizando lenguaje natural. Este proyecto utiliza un agente de IA, construido con el framework FastAgent, para traducir las preguntas de los usuarios en consultas SQL, ejecutarlas y devolver los resultados de una manera amigable.

✨ Características

• Interfaz de Chat Web: Interactúa con tu base de datos a través de una sencilla interfaz de chat.
• Traducción de Lenguaje Natural a SQL: Pregunta en español y obtén respuestas sin escribir una sola línea de SQL.
• Agente de IA Configurable: Potenciado por FastAgent, permitiendo cambiar fácilmente el modelo de lenguaje (LLM) subyacente (Gemini, OpenAI, Anthropic, etc.).
• Entorno Dockerizado: Configuración y despliegue sencillos con Docker Compose, incluyendo la base de datos, la API y herramientas de administración.
• Extensible: El protocolo MCP (Model Context Protocol) permite añadir nuevas herramientas al agente, como la búsqueda web (ej. Brave Search).

🛠️ Pila Tecnológica

• Backend: FastAPI (Python)
• Framework de Agente IA: FastAgent
• Base de Datos: PostgreSQL
• Administración de BD: pgAdmin
• Contenerización: Docker y Docker Compose

🚀 Puesta en Marcha

Sigue estos pasos para levantar el proyecto en tu entorno local.

Prerrequisitos

• Docker y Docker Compose instalados.
• Una clave de API de un proveedor de LLM (ej. Google para Gemini, OpenAI, etc.).

1. Clonar el Repositorio

git clone <URL-DEL-REPOSITORIO>
cd db_agent

2. Configurar las Variables de Entorno

Crea un archivo .env en la raíz del proyecto. Este archivo contendrá las credenciales para la base de datos y las claves de API.

# .env
# Credenciales para la base de datos PostgreSQL
POSTGRES_USER=admin
POSTGRES_PASSWORD=supersecret
POSTGRES_DB=db_chat

# Credenciales para pgAdmin
PGADMIN_EMAIL=admin@example.com
PGADMIN_PASSWORD=admin

# Clave de API para el LLM (ej. Gemini)
GEMINI_API_KEY=tu_api_key_aqui

3. Configurar las Claves de API del Agente

El agente FastAgent utiliza el archivo fastagent.secrets.yaml para gestionar las claves de API. Este archivo ya está configurado para leer la variable de entorno GEMINI_API_KEY que definiste en el paso anterior.

# fastagent.secrets.yaml
google:
    api_key: ${GEMINI_API_KEY}
    base_url: https://generativelanguage.googleapis.com/v1beta/openai

Importante: El archivo fastagent.secrets.yaml no debe ser subido al control de versiones. Asegúrate de que esté incluido en tu .gitignore.

4. Levantar los Servicios con Docker Compose

Desde la raíz del proyecto, ejecuta el siguiente comando:

docker-compose up --build -d

Esto construirá las imágenes y levantará todos los servicios en segundo plano:

• api: La aplicación FastAPI en http://localhost:8001
• db: La base de datos PostgreSQL en el puerto 5432
• pgadmin: El administrador de base de datos en http://localhost:5050
• brave-mcp-server: Un servidor de herramientas para búsqueda web.

💻 Uso

Interfaz Web

1. Abre tu navegador y ve a http://localhost:8001.
2. Verás una interfaz de chat. Escribe tu pregunta en lenguaje natural, por ejemplo: "¿Cuántos usuarios hay en la tabla de clientes?" o "Muéstrame los pedidos realizados en el último mes".
3. El agente procesará tu solicitud, generará una consulta SQL, la ejecutará en la base de datos y te devolverá una respuesta en lenguaje natural.

Administración de la Base de Datos

1. Accede a pgAdmin en http://localhost:5050.
2. Inicia sesión con las credenciales que definiste en el archivo .env (PGADMIN_EMAIL y PGADMIN_PASSWORD).
3. Puedes usar pgAdmin para crear tablas, insertar datos y gestionar tu base de datos PostgreSQL.

⚙️ Configuración

Cambiar el Modelo de LLM

Puedes cambiar el modelo de lenguaje que utiliza el agente editando el archivo fastagent.config.yaml:

# fastagent.config.yaml
# Cambia "gemini25" por el modelo que desees, ej. "openai.gpt-4.1-mini"
default_model: "gemini25"

Modificar el Comportamiento del Agente

El "cerebro" del agente es su prompt de sistema. Puedes modificar sus instrucciones, personalidad y formato de respuesta editando el archivo: app/services/agents/prompts/db_chat_agent.md