Geschäftsassistent für Verkauf und Lagerbestand

Intelligenter virtueller Assistent in der Befehlszeile (CLI), entwickelt, um bei der Abfrage und Analyse von Geschäftsinformationen, Lagerbeständen und Verkäufen eines Bekleidungsgeschäfts zu helfen. Das System verwendet das Model Context Protocol (MCP) mit der Bibliothek FastMCP und dem Framework LangChain und integriert lokale Daten aus einer Excel-Tabelle mit externen Ressourcen wie Websuche und Echtzeit-Währungskursen.

So funktioniert es

Das Projekt ist in zwei Hauptteile strukturiert, die über das Model Context Protocol (MCP) verbunden sind:

1. MCP-Server (server.py): Zentralisiert die Geschäftswerkzeuge, führt Lese- und Aggregationsoperationen auf einer Excel-Tabelle aus, zusätzlich zu Abfragen an externe APIs.

2. Client/Agent (agente.py): Initialisiert den MCP-Server über einen Unterprozess (stdio), stellt die Werkzeuge für das LLM (gpt-4o-mini von OpenAI) bereit und verwaltet den Denkfluss des Assistenten.

Kommunikationsfluss

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

Funktionen

Der Assistent hat Zugriff auf lokale und externe Werkzeuge, um Fragen in natürlicher Sprache zu beantworten:

Geschäftswerkzeuge (Lokale Daten)

• consulta_estoque: Gibt die vollständige Produktliste und den berechneten aktuellen Lagerbestand zurück (Gekaufte Menge - Verkaufte Menge).

• estoque_baixo: Listet Produkte mit einem berechneten Lagerbestand von 15 oder weniger Einheiten auf.

• consulta_faturamento: Berechnet und gibt den gesamten kumulierten Umsatz zurück (Verkaufspreis × Verkaufte Menge).

• produto_mais_vendido: Identifiziert und beschreibt das Produkt mit der höchsten Anzahl verkaufter Einheiten.

• vendas_por_cor: Gruppiert und zeigt den Gesamtumsatz gruppiert nach Produktfarbe an.

• vendas_por_marca: Gruppiert und zeigt den Gesamtumsatz gruppiert nach Produktmarke an.

Hilfswerkzeuge (Externe APIs)

• pesquisa_web: Führt Internetsuchen über die Tavily API durch, um Fragen zu externen oder aktualisierten Daten zu beantworten.

• consultar_cotacao: Ruft den Echtzeit-Wechselkurs zwischen zwei Währungen mithilfe der Frankfurter API ab.

Projektstruktur

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

Voraussetzungen

• Python 3.10 oder höher

• OpenAI-API-Schlüssel (für das LLM-Modell)

• Tavily-API-Schlüssel (für Internetsuchen)

Installation und Konfiguration

1. Repository klonen oder zum Repository navigieren

Navigieren Sie zum Projektverzeichnis:

cd Assistente_empresarial_v1

2. Virtuelle Umgebung erstellen und aktivieren (Empfohlen)

python -m venv venv

Aktivierung unter Windows (PowerShell):

.\venv\Scripts\Activate.ps1

Aktivierung unter Linux/macOS:

source venv/bin/activate

3. Abhängigkeiten installieren

pip install -r requirements.txt

4. Umgebungsvariablen konfigurieren

Erstellen Sie eine .env-Datei im Projektstamm basierend auf .env.example:

copy .env.example .env

Öffnen Sie die .env-Datei und fügen Sie Ihre OpenAI- und Tavily-Anmeldeinformationen ein:

OPENAI_API_KEY=sua_chave_da_openai_aqui
TAVILY_API_KEY=sua_chave_da_tavily_aqui

Ausführen

Mit aktivierter virtueller Umgebung und konfigurierten Variablen führen Sie den Einstiegspunkt der Anwendung aus:

python main.py

Der Assistent startet das interaktive Terminal. Sie sehen die Eingabeaufforderung:

Bem_vindo ao Assistente Empresarial
Digite 'sair' caso queira sair

oque temos para hoje: 

Beispielfragen

Sie können zum Beispiel fragen:

• "Welche Produkte haben einen niedrigen Lagerbestand?"

• "Wie hoch war der Gesamtumsatz des Unternehmens?"

• "Welche Marke wurde am meisten verkauft?"

• "Wie hoch ist der Wechselkurs von Dollar zu Real heute?"

• "Welche Farbe verkauft sich am besten?"