Assistente Empresarial de Vendas e Estoque

Assistente virtual inteligente em linha de comando (CLI) projetado para auxiliar na consulta e análise de informações comerciais, estoque e vendas de uma loja de roupas. O sistema utiliza Model Context Protocol (MCP) com a biblioteca FastMCP e o framework LangChain, integrando dados locais de uma planilha Excel com recursos externos, como pesquisa web e cotação de moedas em tempo real.

Como Funciona

O projeto é estruturado em duas partes principais conectadas pelo Model Context Protocol (MCP):

1. Servidor MCP (server.py): Centraliza as ferramentas de negócio, executando operações de leitura e agregação em uma planilha Excel, além de consultas a APIs externas.

2. Cliente/Agente (agente.py): Inicializa o servidor MCP via subprocesso (stdio), expõe as ferramentas para o LLM (gpt-4o-mini da OpenAI) e gerencia o fluxo de raciocínio do assistente.

Fluxo de Comunicação

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

O assistente possui acesso a ferramentas locais e externas para responder a perguntas em linguagem natural:

Ferramentas de Negócio (Dados Locais)

• consulta_estoque: Retorna a lista completa de produtos e o estoque atual calculado (Quantidade Comprada - Quantidade Vendida).

• estoque_baixo: Lista produtos com estoque calculado igual ou inferior a 15 unidades.

• consulta_faturamento: Calcula e retorna o faturamento total acumulado (Preço de Venda × Quantidade Vendida).

• produto_mais_vendido: Identifica e detalha o produto com a maior quantidade de unidades vendidas.

• vendas_por_cor: Agrupa e exibe o total de vendas agrupado pela cor do produto.

• vendas_por_marca: Agrupa e exibe o total de vendas agrupado pela marca do produto.

Ferramentas Utilitárias (APIs Externas)

• pesquisa_web: Realiza buscas na internet via Tavily API para responder a perguntas sobre dados externos ou atualizados.

• consultar_cotacao: Obtém a taxa de câmbio em tempo real entre duas moedas utilizando a API Frankfurter.

Estrutura do Projeto

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

Pré-requisitos

• Python 3.10 ou superior

• Chave de API da OpenAI (para o modelo LLM)

• Chave de API da Tavily (para buscas na internet)

Instalação e Configuração

1. Clonar ou navegar até o repositório

Navegue até o diretório do projeto:

cd Assistente_empresarial_v1

2. Criar e ativar o ambiente virtual (Recomendado)

python -m venv venv

Ativação no Windows (PowerShell):

.\venv\Scripts\Activate.ps1

Ativação no Linux/macOS:

source venv/bin/activate

3. Instalar as dependências

pip install -r requirements.txt

4. Configurar as variáveis de ambiente

Crie um arquivo .env na raiz do projeto baseado no .env.example:

copy .env.example .env

Abra o arquivo .env e insira suas credenciais da OpenAI e Tavily:

OPENAI_API_KEY=sua_chave_da_openai_aqui
TAVILY_API_KEY=sua_chave_da_tavily_aqui

Como Executar

Com o ambiente virtual ativado e as variáveis configuradas, execute o ponto de entrada da aplicação:

python main.py

O assistente iniciará o terminal interativo. Você verá o prompt de entrada:

Bem_vindo ao Assistente Empresarial
Digite 'sair' caso queira sair

oque temos para hoje: 

Exemplos de Perguntas

Você pode perguntar coisas como:

• "Quais produtos estão com estoque baixo?"

• "Qual foi o faturamento total da empresa?"

• "Qual a marca mais vendida?"

• "Quanto está a cotação do dólar para o real hoje?"

• "Qual a cor que mais vende?"