A conversational copilot that guides users through the KDD process.
KDD Conversacional
Descripción del Proyecto
Sistema conversacional que acompaña al usuario durante todo el proceso de Descubrimiento de Conocimiento en Datos (KDD). Funciona como un copiloto analítico, facilitador metodológico y orquestador del workflow que guía al usuario mediante lenguaje natural, ejecuta análisis de forma automática y culmina con la generación autónoma de un dashboard interactivo que sintetiza resultados, insights y modelos.
El Horizonte MCP (Model Context Protocol)
El objetivo final arquitectónico de la aplicación transciende su interfaz web (Streamlit). Una vez que el ciclo KDD esté totalmente operativo y el motor de agentes sea infalible, se creará una versión independiente exponiendo el sistema íntegramente como un servicio MCP.
Esto significa que el proyecto actuará como un "Agente KDD Universal" conectable a cualquier ecosistema de IA corporativo o cliente compatible (como Claude Desktop o Cursor), permitiéndoles usar a nuestro experto en datos como si fuera una simple función o comando a la que delegarle la ingesta, análisis y creación de modelos de Machine Learning dentro del Sandbox aislado, devolviendo los insights y artefactos extraídos al agente principal.
Arquitectura del Motor Conversacional (Agentes)
El corazón conversacional de la aplicación funciona como una máquina de estados orquestada por LangGraph. A diferencia de un chatbot tradicional lineal, el sistema actúa como un grupo de agentes especialistas organizados por un Router:
- Nodo Router: El usuario habla y el mensaje pasa por el router. Este nodo monitoriza la fase metodológica en la que se encuentra la conversación (
1_understanding,4_eda, etc.) y decide a qué agente experto enviarle el flujo. - Goal Agent (Especialista Fase 1): Un modelo dedicado exclusivamente a hacer preguntas exploratorias al principio de la conversación. No ejecuta código. Su misión es garantizar que el usuario define claramente "qué quiere conseguir" (predecir, agrupar, encontrar anomalías) y almacenarlo en la memoria del sistema.
- Generic/Specialist Agents (Fases > 1): A medida que la fase avanza a perfilado, EDA o modelado, el router despertará a agentes que tienen capacidades de escribir Python (usando LLMs a los que se asocia el Tool_Node). Estos agentes delegarán la ejecución del código al [Sandbox Docker], recuperarán las respuestas y se las explicarán al usuario.
Para el desarrollo es imprescindible que exista un archivo src/.env configurado que contenga al menos las API keys de los LLM predeterminados (Ej: OPENAI_API_KEY, MISTRAL_API_KEY, etc), que la aplicación se encargará de cargar en tiempo de inicialización.
Utilidad
El valor principal del sistema no radica únicamente en el dashboard final, sino en el proceso guiado. Al actuar como un analista senior, el sistema:
- Evita análisis estadísticos o de machine learning incorrectos.
- Reduce errores en la preparación de datos.
- Mejora la interpretación de los resultados.
- Educa y enseña al usuario durante la exploración.
Instalación y Ejecución Local
Para reproducir este sistema en local, se recomienda el uso de pyenv para preservar la pureza del entorno de desarrollo.
Pre-requisitos
- Python 3.12.3 (Configurado a través de
pyenv) - Docker Desktop / Engine (Activo en segundo plano para el Sandbox Analítico)
1. Preparación del Entorno
# 1. Configurar la versión correcta de Python
pyenv local 3.12.3
# 2. Crear entorno virtual
python -m venv .venv
source .venv/bin/activate
# 3. Instalar librerías
pip install -r requirements.txt
2. Variables de Entorno
Es imprescindible crear un archivo src/.env y, opcionalmente, .env en la raíz del proyecto para definir las claves base de los LLM que alimentan LangGraph. Un ejemplo del archivo (o su plantilla .env.example si existe) sería:
OPENAI_API_KEY=sk-....
MISTRAL_API_KEY=your_key_here
3. Ejecución Paralela
El sistema utiliza una arquitectura bi-modal manual para depuración. Se requieren dos terminales abiertas:
Terminal 1: Iniciar el Motor Inteligente KDD (FastAPI) Conserva el contexto, la memoria SQLite de las sesiones, y el enrutamiento LangGraph.
source .venv/bin/activate
uvicorn src.main:app --host 127.0.0.1 --port 8000 --reload
Terminal 2: Iniciar la Interfaz de Usuario Experto (Streamlit) Levanta la SPA que interactúa con el backend consumiendo los endpoints REST.
source .venv/bin/activate
streamlit run src/ui/app.py
Accede posteriormente por navegador web a http://localhost:8501.
Fases de Construcción del Sistema
🟢 Fase 1 — Fundaciones del sistema (infraestructura base)
Objetivo: Crear el "esqueleto" donde todo podrá ejecutarse. Qué se construyó: Backend FastAPI async, contrato inicial de servers MCP, Docker sandbox para ejecución analítica aislada y logging estandarizado.
🟢 Fase 2 — Motor conversacional y estado del análisis
Objetivo: Que el s
Tools (2)
kdd_routerRoutes user requests to the appropriate KDD phase agent based on the current analytical state.execute_sandbox_codeExecutes Python code within an isolated Docker sandbox for data profiling or modeling.Environment Variables
OPENAI_API_KEYrequiredAPI key for OpenAI LLM servicesMISTRAL_API_KEYrequiredAPI key for Mistral LLM servicesConfiguration
{ "mcpServers": { "kdd-conversacional": { "command": "python", "args": ["src/main.py"], "env": { "OPENAI_API_KEY": "your_key_here", "MISTRAL_API_KEY": "your_key_here" } } } }