Бизнес-ассистент по продажам и складским запасам

Интеллектуальный виртуальный ассистент с интерфейсом командной строки (CLI), предназначенный для помощи в запросах и анализе коммерческой информации, складских запасов и продаж магазина одежды. Система использует Model Context Protocol (MCP) с библиотекой FastMCP и фреймворком LangChain, интегрируя локальные данные из таблицы Excel с внешними ресурсами, такими как веб-поиск и котировки валют в реальном времени.

Как это работает

Проект состоит из двух основных частей, связанных через Model Context Protocol (MCP):

1. Сервер MCP (server.py): Централизует бизнес-инструменты, выполняя операции чтения и агрегации в таблице Excel, а также запросы к внешним API.

2. Клиент/агент (agente.py): Запускает сервер MCP через подпроцесс (stdio), предоставляет инструменты LLM (gpt-4o-mini от OpenAI) и управляет потоком рассуждений ассистента.

Поток связи

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

Возможности

Ассистент имеет доступ к локальным и внешним инструментам для ответа на вопросы на естественном языке:

Бизнес-инструменты (локальные данные)

• consulta_estoque: Возвращает полный список товаров и текущий расчётный запас (Купленное количество - Проданное количество).

• estoque_baixo: Перечисляет товары с расчётным остатком 15 единиц или менее.

• consulta_faturamento: Рассчитывает и возвращает общий накопленный оборот (Цена продажи × Проданное количество).

• produto_mais_vendido: Определяет и детализирует товар с наибольшим количеством проданных единиц.

• vendas_por_cor: Группирует и отображает общий объём продаж по цвету товара.

• vendas_por_marca: Группирует и отображает общий объём продаж по бренду товара.

Вспомогательные инструменты (внешние API)

• pesquisa_web: Выполняет поиск в интернете через Tavily API для ответа на вопросы о внешних или обновлённых данных.

• consultar_cotacao: Получает обменный курс в реальном времени между двумя валютами с использованием API Frankfurter.

Структура проекта

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

Предварительные требования

• Python 3.10 или новее

• Ключ API от OpenAI (для LLM-модели)

• Ключ API от Tavily (для поиска в интернете)

Установка и настройка

1. Клонировать или перейти в репозиторий

Перейдите в каталог проекта:

cd Assistente_empresarial_v1

2. Создать и активировать виртуальное окружение (рекомендуется)

python -m venv venv

Активация в Windows (PowerShell):

.\venv\Scripts\Activate.ps1

Активация в Linux/macOS:

source venv/bin/activate

3. Установить зависимости

pip install -r requirements.txt

4. Настроить переменные окружения

Создайте файл .env в корне проекта на основе .env.example:

copy .env.example .env

Откройте файл .env и введите свои учётные данные OpenAI и Tavily:

OPENAI_API_KEY=sua_chave_da_openai_aqui
TAVILY_API_KEY=sua_chave_da_tavily_aqui

Как запустить

С активированным виртуальным окружением и настроенными переменными выполните точку входа приложения:

python main.py

Ассистент запустит интерактивный терминал. Вы увидите приглашение ввода:

Bem_vindo ao Assistente Empresarial
Digite 'sair' caso queira sair

oque temos para hoje: 

Примеры вопросов

Вы можете задавать вопросы, например:

• "Какие товары с низким запасом?"

• "Какой был общий доход компании?"

• "Какой бренд продаётся лучше всего?"

• "Какой сегодня курс доллара к реалу?"

• "Какой цвет продаётся лучше всего?"