Mercadinho Mercantes - Multi-Agent AI Assistant

A multi-agent AI system for Mercadinho Mercantes, a Brazilian retail chain. This system provides intelligent customer service through specialized AI agents that handle product inquiries, sales assistance, customer management, and store operations.

🏪 About Mercadinho Mercantes

Mercadinho Mercantes is a Brazilian retail company with multiple locations. This AI assistant system enhances customer experience by providing product recommendations, promotional information, and appointment scheduling.

✨ Features

🤖 Multi-Agent Architecture

• Reception Agent: Welcomes customers and directs them to appropriate services
• Sales Agent: Handles product inquiries, recommendations, and sales assistance
• Customer Maintenance Agent: Manages customer accounts and special discounts

🛍️ Core Functionality

• Product catalog browsing
• Store information lookup
• Promotional system (store-specific)
• Customer management and loyalty benefits
• Appointment scheduling for store visits and product reservations
• Special discounts for registered customers

🛠️ Technical Features

• MCP (Model Context Protocol) integration for tool calling
• Streamlit UI for interactive chat
• Real-time chat with AI agents
• Tool usage visualization
• Session management

🚀 Quick Start

Prerequisites

• Python 3.8 or higher
• OpenAI API key
• Git

Installation

1. Clone the repository

   git clone <repository-url>
   cd mcp_mercadinho
   

2. Install dependencies

   pip install -r requirements.txt
   

3. Set up environment variables

   export OPENAI_API_KEY="your_openai_api_key_here"
   

   Or create a .env file:

   echo "OPENAI_API_KEY=your_openai_api_key_here" > .env
   

4. Database setup

   • The application requires a pre-existing loja_sistema.db SQLite database with the correct schema. If you do not have this file, please request the schema or a setup script from the project maintainer. (The setup script is not included in this repository.)

Running the Application

1. Start the MCP server (in one terminal):

   python server.py
   

   (By default, runs with stdio transport for local development.)

2. Launch the Streamlit client (in another terminal):

   streamlit run chat_multi_agent_client.py
   

3. Open your browser and navigate to the URL shown in the Streamlit output (typically http://localhost:8501)

🏗️ Architecture

System Components

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   Streamlit UI  │◄──►│  Multi-Agent     │◄──►│   MCP Server    │
│   (Frontend)    │    │  System          │    │   (Backend)     │
└─────────────────┘    └──────────────────┘    └─────────────────┘
                              │
                              ▼
                       ┌──────────────────┐
                       │  OpenAI GPT-4    │
                       │  (LLM Backend)   │
                       └──────────────────┘

Agent Roles

Reception Agent (RecepcaoAssistente)

• Purpose: Initial customer contact and routing
• Responsibilities:
  • Welcome customers to Mercadinho Mercantes
  • Present company information and website
  • Route customers to specialized agents
  • Handle general inquiries

Sales Agent (VendasAssistente)

• Purpose: Product sales and recommendations
• Responsibilities:
  • Show available products and inventory
  • Provide product recommendations
  • Handle promotional offers
  • Schedule store visits
  • Process sales inquiries

Customer Maintenance Agent (ManutencaoSocioAssistente)

• Purpose: Existing customer support and loyalty management
• Responsibilities:
  • Verify customer membership status
  • Apply special discounts for members
  • Handle product reservations
  • Manage customer accounts

Available Tools (MCP Functions)

📊 Data Structure (Example)

Products

• Fields: produto_id, nome, descricao, categoria_id, valor

Stores

• Fields: loja_id, nome, cidade, estado, bairro

Customers

• Fields: cliente_id, nome, sobrenome, cliente_socio, cidade, estado, cep, rua, numero, bairro, complemento

🎯 Usage Examples

Product Inquiry

User: "What products do you have available?"
Agent: [Shows product catalog with prices and availability]

Store Visit Scheduling

User: "I want to visit a store to see the PlayStation 5"
Agent: [Finds nearest store, checks promotions, schedules visit]

Customer Discount Check

User: "My name is John Lennon, do I have any special discounts?"
Agent: [Verifies membership, applies special pricing]

🔧 Configuration

Environment Variables

• OPENAI_API_KEY: Your OpenAI API key for GPT-4 access

Model Settings

• Model: GPT-4-1106-preview
• Temperature: 0 (deterministic responses)
• Tool Choice: Auto
• Parallel Tool Calls: Disabled

🛡️ Security Considerations

• API keys should be stored securely in environment variables
• Never commit API keys to version control
• Use .env files for local development
• Consider implementing rate limiting for production use

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🆘 Support

For support and questions:

• Check the Issues page
• Contact the development team
• Visit Mercadinho Mercantes

🔮 Future Enhancements

• Integration with real inventory systems
• Payment processing capabilities
• Multi-language support (Portuguese/English)
• Mobile app development
• Advanced analytics and reporting
• Integration with CRM systems

---

Built with ❤️ for Mercadinho Mercantes