Mercadinho Mercantes Multi-Agent AI Assistant

# Mercadinho Mercantes - Multi-Agent AI Assistant [](https://www.python.org/downloads/) [](https://streamlit.io/) [](https://modelcontextprotocol.io/) [](https://openai.com/) 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** ```bash git clone <repository-url> cd mcp_mercadinho ``` 2. **Install dependencies** ```bash pip install -r requirements.txt ``` 3. **Set up environment variables** ```bash export OPENAI_API_KEY="your_openai_api_key_here" ``` Or create a `.env` file: ```bash 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): ```bash python server.py ``` (By default, runs with stdio transport for local development.) 2. **Launch the Streamlit client** (in another terminal): ```bash 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) | Tool | Description | Parameters | |------|-------------|------------| | `get_produtos_disponiveis()` | Retrieve available products | None | | `get_lojas()` | Get store locations and information | None | | `get_categorias_produtos_promocao_por_loja(id_loja)` | Get categories with promotions for a store | `id_loja: int` | | `get_promocao_por_loja(id_loja)` | Get product promotions for a store | `id_loja: int` | | `get_info_cliente(cliente_id, nome)` | Get customer information | `cliente_id: int, nome: str` | | `reservar_pedido_com_desconto(id_loja, id_cliente, data_hora)` | Reserve order with discount | `id_loja: int, id_cliente: int, data_hora: str` | | `agenda_visita_para_compra(id_loja, data_hora)` | Schedule store visit | `id_loja: int, data_hora: str` | ## 📊 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](LICENSE) file for details. ## 🆘 Support For support and questions: - Check the [Issues](https://github.com/your-repo/issues) page - Contact the development team - Visit [Mercadinho Mercantes](https://www.mecadinhomercantes.com.br/) ## 🔮 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**