Asistente Empresarial de Ventas y Inventario

Asistente virtual inteligente en línea de comandos (CLI) diseñado para ayudar en la consulta y análisis de información comercial, inventario y ventas de una tienda de ropa. El sistema utiliza Model Context Protocol (MCP) con la biblioteca FastMCP y el framework LangChain, integrando datos locales de una hoja de cálculo de Excel con recursos externos, como búsqueda web y cotización de monedas en tiempo real.

Cómo Funciona

El proyecto está estructurado en dos partes principales conectadas por el Model Context Protocol (MCP):

1. Servidor MCP (server.py): Centraliza las herramientas de negocio, ejecutando operaciones de lectura y agregación en una hoja de cálculo de Excel, además de consultas a APIs externas.

2. Cliente/Agente (agente.py): Inicializa el servidor MCP mediante subproceso (stdio), expone las herramientas al LLM (gpt-4o-mini de OpenAI) y gestiona el flujo de razonamiento del asistente.

Flujo de Comunicación

Usuário (CLI) <──> main.py
                     │
                     ▼
             agente.py (Agente LangChain / GPT-4o-Mini)
                     │
         (Comunicação via MCP - stdio)
                     │
                     ▼
             server.py (Servidor FastMCP)
        ┌────────────┼────────────┐
        ▼            ▼            ▼
 Planilha Excel    Tavily API   Frankfurter API
(estoque_vendas)  (Busca Web)  (Cotação de Moedas)

Related MCP server: mcp-data-lens

Funcionalidades

El asistente tiene acceso a herramientas locales y externas para responder preguntas en lenguaje natural:

Herramientas de Negocio (Datos Locales)

• consulta_estoque: Devuelve la lista completa de productos y el inventario actual calculado (Quantidade Comprada - Quantidade Vendida).

• estoque_baixo: Lista productos con inventario calculado igual o inferior a 15 unidades.

• consulta_faturamento: Calcula y devuelve la facturación total acumulada (Precio de Venta × Cantidad Vendida).

• produto_mais_vendido: Identifica y detalla el producto con la mayor cantidad de unidades vendidas.

• vendas_por_cor: Agrupa y muestra el total de ventas agrupado por el color del producto.

• vendas_por_marca: Agrupa y muestra el total de ventas agrupado por la marca del producto.

Herramientas Utilitarias (APIs Externas)

• pesquisa_web: Realiza búsquedas en internet mediante la API de Tavily para responder preguntas sobre datos externos o actualizados.

• consultar_cotacao: Obtiene el tipo de cambio en tiempo real entre dos monedas utilizando la API de Frankfurter.

Estructura del Proyecto

Assistente_empresarial_v1/
├── .env.example             # Modelo das variáveis de ambiente necessárias
├── .gitignore               # Arquivos ignorados pelo Git
├── agente.py                # Inicialização do agente e conexão com o cliente MCP
├── estoque_vendas.xlsx      # Planilha de dados (fonte de dados de estoque e vendas)
├── main.py                  # Ponto de entrada da aplicação (loop interativo da CLI)
├── requirements.txt         # Lista de dependências do Python
└── server.py                # Definição das ferramentas e inicialização do servidor FastMCP

Prerrequisitos

• Python 3.10 o superior

• Clave de API de OpenAI (para el modelo LLM)

• Clave de API de Tavily (para búsquedas en internet)

Instalación y Configuración

1. Clonar o navegar hasta el repositorio

Navegue hasta el directorio del proyecto:

cd Assistente_empresarial_v1

2. Crear y activar el entorno virtual (Recomendado)

python -m venv venv

Activación en Windows (PowerShell):

.\venv\Scripts\Activate.ps1

Activación en Linux/macOS:

source venv/bin/activate

3. Instalar las dependencias

pip install -r requirements.txt

4. Configurar las variables de entorno

Cree un archivo .env en la raíz del proyecto basado en .env.example:

copy .env.example .env

Abra el archivo .env e inserte sus credenciales de OpenAI y Tavily:

OPENAI_API_KEY=sua_chave_da_openai_aqui
TAVILY_API_KEY=sua_chave_da_tavily_aqui

Cómo Ejecutar

Con el entorno virtual activado y las variables configuradas, ejecute el punto de entrada de la aplicación:

python main.py

El asistente iniciará el terminal interactivo. Verá el prompt de entrada:

Bem_vindo ao Assistente Empresarial
Digite 'sair' caso queira sair

oque temos para hoje: 

Ejemplos de Preguntas

Puede preguntar cosas como:

• "¿Qué productos tienen inventario bajo?"

• "¿Cuál fue la facturación total de la empresa?"

• "¿Cuál es la marca más vendida?"

• "¿Cuánto está la cotización del dólar frente al real hoy?"

• "¿Cuál es el color que más vende?"