Chatbot Vendedor Conversacional

Asistente de ventas en lenguaje natural que responde consultas sobre un catálogo de productos (CSV) usando inteligencia artificial. Clasifica cada pregunta, consulta datos reales sin alucinar y mantiene contexto conversacional.

Stack: Python · LangChain · LangGraph · DeepSeek · Streamlit · pandas · SQLite

---

Cómo funciona

El bot carga un catálogo de productos desde un archivo CSV, detecta automáticamente las columnas (marca, modelo, precio, color, etc.) y expone dos interfaces:

Interfaz	Comando	Uso
Terminal (REPL)	python main.py	Desarrollo y pruebas
Web (Streamlit)	streamlit run app.py	Demo y uso diario

Flujo conversacional

INICIO
  ├── Es el primer turno → saludo amable + lista de atributos disponibles
  └── Ya conversamos antes:
        ├── Pregunta sobre productos → busca en el CSV → responde con datos reales
        └── Pregunta fuera de tema → redirige amablemente sin responder

El grafo de conversación está implementado con LangGraph (StateGraph), lo que hace el flujo auditable y extensible sin modificar prompts.

Clasificación de preguntas

Antes de responder, el bot analiza la pregunta y decide:

• product_question: la consulta puede responderse con el catálogo
• off_topic: la consulta está fuera del alcance (clima, política, etc.)

Para preguntas de producto, el bot genera una consulta SQL contra el CSV (cargado en SQLite en memoria) para obtener solo los productos relevantes y responder sin inventar datos.

---

Estructura del proyecto

chatbot_seller/
├── app.py                      # Interfaz Streamlit
├── main.py                     # REPL de consola
├── requirements.txt            # Dependencias pip
├── .env.example                # Template de variables de entorno
├── PRD.md                      # PRD completo
├── SPEC.md                     # Especificación técnica
├── data/
│   └── products.csv            # Catálogo (celulares de ejemplo)
├── chatbot/
│   ├── config.py               # Variables de entorno y constantes
│   ├── data_loader.py          # Carga CSV + conexión SQLite
│   ├── graph.py                # StateGraph de LangGraph
│   ├── llm.py                  # Cliente DeepSeek (compatible OpenAI)
│   ├── prompts.py              # Templates de prompts
│   ├── state.py                # TypedDict del estado
│   └── nodes/
│       ├── greeter.py           # Saludo inicial
│       ├── router_analyzer.py   # Clasifica y analiza la pregunta
│       ├── categorizer.py       # Extrae categorías del CSV
│       ├── sql_generator.py     # Genera SQL desde lenguaje natural
│       ├── sql_executor.py      # Ejecuta la consulta SQL
│       ├── responder.py         # Redacta la respuesta final
│       └── redirector.py        # Redirige preguntas off-topic
└── validator/
    ├── run_validation.py        # Ejecuta la validación completa
    ├── question_bank.py         # Banco de preguntas de prueba
    ├── eda_ground_truth.py      # Ground truth generado del CSV
    ├── bot_runner.py            # Ejecuta el bot contra preguntas
    ├── judge.py                 # Evalúa respuestas contra ground truth
    └── quick_test.py            # Test rápido de humo

---

Instalación y uso

1. Clonar el repositorio

git clone https://github.com/lbruno086/-Chatbot-Vendedor-Conversacional.git
cd -Chatbot-Vendedor-Conversacional

2. Instalar dependencias

Requiere Python 3.10 o superior.

pip install -r requirements.txt

3. Configurar API key de DeepSeek

Copiá el template y completalo con tu API key:

cp .env.example .env

Editá .env y poné tu key:

DEEPSEEK_API_KEY=sk-tu-api-key
DEEPSEEK_MODEL=deepseek-chat
CSV_PATH=data/products.csv
HISTORY_WINDOW=6
TOP_K_PRODUCTS=3

Obtené tu API key en: https://platform.deepseek.com/api_keys

4. Ejecutar

Interfaz web (recomendada):

streamlit run app.py

Abre http://localhost:8501 en el navegador.

Terminal:

python main.py

Escribí salir, exit o quit para terminar.

---

Usar tu propio catálogo

Reemplazá data/products.csv con tu propio archivo CSV. El bot detecta automáticamente las columnas, sin hardcodear nombres de atributos.

Requisitos del CSV:

• Formato UTF-8
• Separado por comas
• Primera fila = nombres de columna
• Una columna debe identificar el producto (ej: titulo, nombre, producto)

Ejemplo mínimo:

nombre,precio,stock
Café Premium,2500,50
Té Verde,1800,30

El bot se adapta solo y responde consultas sobre cualquier columna que exista en el CSV.

---

Variables de entorno

Variable	Default	Descripción
DEEPSEEK_API_KEY	(requerida)	API key de DeepSeek
DEEPSEEK_MODEL	deepseek-chat	Modelo: deepseek-chat o deepseek-reasoner
CSV_PATH	data/products.csv	Ruta al catálogo CSV
HISTORY_WINDOW	6	Entradas de historial (6 = 3 turnos)
TOP_K_PRODUCTS	3	Máximo de productos por respuesta

---

Validación

El proyecto incluye un sistema de validación automática que mide la calidad de las respuestas del bot contra un ground truth generado desde el propio CSV.

python validator/run_validation.py

Esto ejecuta un banco de preguntas predefinidas, compara cada respuesta del bot con los datos reales del CSV y genera un reporte con precisión por tipo de pregunta.

---

Límites del MVP

Siempre:

• Responder en español
• Usar únicamente datos del CSV
• Redirigir preguntas fuera de tema sin responderlas

Nunca:

• Inventar atributos, precios o specs que no estén en el CSV
• Procesar pagos ni tomar pedidos
• Hardcodear nombres de columna

---

Roadmap

• v0.2 — Persistencia de historial entre sesiones (SQLite)
• v0.3 — Scraping de Mercado Libre para actualizar el CSV automáticamente
• v0.4 — Búsqueda con embeddings para catálogos grandes (+1000 productos)
• v0.5 — Integración con WhatsApp / Telegram