# Agente de Análisis de Ventas con Agentic AI 🧪📊

**Autora:** Carolina Mantilla
**Fecha:** Mayo 31 de 2026

---

## 📌 Propósito del taller

Este proyecto tiene como objetivo construir un agente inteligente capaz de analizar datos de ventas a partir de preguntas en lenguaje natural.

La idea principal del taller es practicar cómo un agente puede conectarse con una base de datos SQL, interpretar lo que el usuario necesita y ejecutar acciones como consultar información, generar gráficos o guardar resultados en archivos.

En lugar de que el usuario escriba directamente consultas SQL, puede hacer preguntas como:

```text
Top 5 productos más vendidos en Medellín
```

o:

```text
Guarda las ventas por vendedor en un archivo CSV
```

Y el agente se encarga de interpretar la intención, consultar la base de datos y devolver el resultado adecuado.

---

## 🎯 ¿Qué hace el proyecto?

El agente permite:

* Recibir preguntas en lenguaje natural sobre ventas.
* Consultar una base de datos SQL con información de ventas.
* Generar respuestas en texto o formato de tabla.
* Crear gráficos de barras.
* Exportar resultados a archivos CSV o Excel.
* Usar herramientas conectadas mediante MCP.
* Ejecutar el flujo localmente usando un modelo de lenguaje con Ollama.

---

## 🧱 Estructura del proyecto

```text
s2026q2xy-agente-ventas-cmantilla/
│
├── data/
│   └── ventas.csv
│
├── database/
│   └── ventas.db
│
├── outputs/
│   ├── ventas_por_vendedor.csv
│   ├── ventas_por_vendedor.xlsx
│   └── ventas_por_vendedor.png
│
├── src/
│   ├── agent.py
│   ├── charts.py
│   ├── database.py
│   ├── exports.py
│   ├── main.py
│   ├── mcp_server.py
│   └── tools.py
│
├── requirements.txt
├── .gitignore
└── README.md
```

---

## 🛠️ Herramientas utilizadas

### Python 🐍

Se usó Python como lenguaje principal del proyecto porque permite trabajar fácilmente con bases de datos, archivos, análisis de datos, gráficos y frameworks de agentes.

---

### SQLite 🗄️

Se usó SQLite como base de datos local.

La tabla principal del proyecto es `ventas`, con las siguientes columnas:

```text
id, vendedor, sede, producto, cantidad, precio, fecha
```

SQLite fue una buena opción porque no requiere instalar un servidor externo de base de datos. Todo queda en un archivo local llamado:

```text
database/ventas.db
```

---

### Pandas 📊

Pandas se usó para manejar los resultados de las consultas SQL como tablas.

Esto facilita mostrar resultados, exportarlos a CSV/Excel y usarlos para generar gráficos.

---

### Matplotlib 📈

Matplotlib se utilizó para generar gráficos de barras a partir de los resultados consultados en la base de datos.

Por ejemplo, el agente puede generar un gráfico de ventas por vendedor y guardarlo en la carpeta `outputs/`.

---

### FastMCP 🔌

FastMCP se usó para crear un servidor MCP local.

Este servidor expone herramientas que el agente puede usar, como:

* Consultar la base de datos.
* Exportar resultados a CSV.
* Exportar resultados a Excel.
* Generar gráficos.

Esto permite que el agente no acceda directamente a todo el código, sino que use herramientas específicas y controladas.

---

### LangChain 🧠

LangChain se usó como framework de agentes.

Su función principal en el proyecto es conectar el modelo de lenguaje con las herramientas disponibles mediante MCP.

---

### Ollama 🤖

Inicialmente se intentó usar modelos en la nube, pero por temas de cuota y facturación se decidió usar Ollama.

Ollama permite ejecutar modelos de lenguaje localmente, sin depender de créditos externos ni APIs pagas.

El modelo usado fue:

```text
llama3.2:3b
```

Esta decisión permitió mantener el enfoque del taller: usar un modelo de lenguaje para interpretar la intención del usuario, pero ejecutándolo de forma local.

---

## ⚙️ Cómo correr el proyecto

### 1. Clonar el repositorio

```bash
git clone [<URL_DEL_REPOSITORIO>](https://github.com/ai-scm/s2026q2xy-agente-ventas-cmantilla)
cd s2026q2xy-agente-ventas-cmantilla
```

---

### 2. Crear y activar el entorno virtual

```bash
python3 -m venv .venv
source .venv/bin/activate
```

---

### 3. Instalar dependencias

```bash
pip install -r requirements.txt
```

---

### 4. Instalar y ejecutar Ollama

Si estás en Mac y tienes Homebrew:

```bash
brew install ollama
```

Luego inicia el servidor de Ollama:

```bash
ollama serve
```

Es importante dejar esta terminal abierta mientras se ejecuta el agente.

---

### 5. Descargar el modelo local

En otra terminal, ejecuta:

```bash
ollama pull llama3.2:3b
```

Puedes verificar que el modelo quedó instalado con:

```bash
ollama list
```

---

### 6. Configurar el archivo `.env`

Crear un archivo `.env` en la raíz del proyecto con el siguiente contenido:

```env
MODEL_PROVIDER=ollama
MODEL_NAME=llama3.2:3b
```

Este archivo no se debe subir al repositorio.

---

### 7. Crear la base de datos

Antes de correr el agente, se debe crear la base de datos SQLite a partir del archivo CSV:

```bash
python3 src/database.py
```

Esto genera el archivo:

```text
database/ventas.db
```

---

### 8. Ejecutar el agente

Con el entorno virtual activo:

```bash
python3 src/main.py
```

Luego puedes escribir preguntas como:

```text
Top 5 productos más vendidos en Medellín
```

Para salir del agente:

```text
salir
```

---

## 🧠 ¿Cómo lo hicimos?

El proyecto se construyó por partes.

Primero se creó un archivo CSV con datos de ventas. Luego, esos datos se cargaron en una base SQLite mediante `src/database.py`.

Después se creó una herramienta para ejecutar consultas SQL de forma segura, permitiendo únicamente consultas `SELECT`. Esto se hizo para evitar que el agente pudiera modificar o borrar información de la base de datos.

También se agregaron herramientas para exportar resultados a CSV o Excel y para generar gráficos de barras.

Luego se implementó un servidor MCP local usando FastMCP. Este servidor expone las herramientas principales para que el agente pueda usarlas.

Finalmente, se conectó el agente con LangChain y Ollama. El modelo local interpreta la pregunta del usuario y decide qué herramienta debe usar.

---

## 🔍 Ajustes importantes realizados

Durante las pruebas se encontró que el problema no estaba en la base de datos, sino en cómo el modelo generaba algunas consultas SQL.

Por ejemplo, para Medellín a veces generaba valores incorrectos como:

```text
Medellñn
```

o versiones sin tilde como:

```text
Medellin
```

Como SQLite compara texto de forma exacta, esas variantes no encontraban registros.

Para solucionarlo, se agregó una normalización en `src/tools.py`, permitiendo reconocer variantes como:

```text
medellin
Medellín
MEDELLÍN
Medellñn
Bogota
Bogotá
Cali
```

También se ajustó el arranque del servidor MCP para usar `sys.executable`, asegurando que se ejecute con el mismo entorno virtual del proyecto.

Esto evitó errores relacionados con dependencias instaladas en el `.venv`, como `pandas` o `fastmcp`.

Además, se cambió la respuesta de las herramientas para que el modelo recibiera resultados en formato de tabla legible, no solo JSON compacto. Esto ayudó a que el modelo interpretara mejor los resultados devueltos por la base de datos.

---

## 🧪 Pruebas realizadas

### 1. Top productos más vendidos en Medellín

Pregunta:

```text
Top 5 productos más vendidos en Medellín
```

Resultado esperado:

```text
1. Mouse - 22 unidades
2. Tablet - 7 unidades
3. Laptop - 3 unidades
4. Monitor - 2 unidades
```

Esta prueba valida que el agente pueda filtrar por sede, agrupar por producto y sumar cantidades vendidas.

---

### 2. Variante sin tilde

Pregunta:

```text
Top productos más vendidos en Medellin
```

Resultado esperado:

```text
Mouse - 22 unidades
Tablet - 7 unidades
Laptop - 3 unidades
Monitor - 2 unidades
```

Esta prueba valida que la normalización de texto funcione aunque el usuario escriba sin tilde.

---

### 3. Vendedor con más ventas en Bogotá

Pregunta:

```text
Quién fue el vendedor con más ventas en Bogotá
```

Resultado esperado:

```text
Ana - 10,640,000
```

Esta prueba valida que el agente pueda calcular ventas en dinero usando:

```sql
SUM(cantidad * precio)
```

---

### 4. Ventas por vendedor

Pregunta:

```text
Cuánto vendió cada vendedor
```

Resultado esperado:

```text
María  - 13,600,000
Ana    - 10,640,000
Carlos - 8,860,000
Pedro  - 7,350,000
Luisa  - 6,770,000
```

Esta prueba valida agrupación por vendedor y ordenamiento por total vendido.

---

### 5. Gráfico de ventas por vendedor

Pregunta:

```text
Hazme un gráfico de ventas por vendedor
```

Resultado esperado:

```text
outputs/ventas_por_vendedor.png
```

Esta prueba valida que el agente pueda generar una visualización a partir de una consulta SQL.

---

### 6. Exportación a CSV

Pregunta:

```text
Guarda las ventas por vendedor en un archivo CSV
```

Resultado esperado:

```text
outputs/ventas_por_vendedor.csv
```

Esta prueba valida que el agente pueda guardar resultados en archivos.

---

### 7. Exportación a Excel

Pregunta:

```text
Guarda las ventas por vendedor en un archivo Excel
```

Resultado esperado:

```text
outputs/ventas_por_vendedor.xlsx
```

Esta prueba valida la persistencia de resultados en formato Excel.

---

## 📁 Archivos generados

Los resultados generados por el agente se guardan en la carpeta:

```text
outputs/
```

Algunos ejemplos de archivos generados son:

```text
ventas_por_vendedor.csv
ventas_por_vendedor.xlsx
ventas_por_vendedor.png
```

---