README.md

---
title: FleetMind AI Dispatch Coordinator
emoji: 🚚
colorFrom: blue
colorTo: purple
sdk: gradio
sdk_version: 5.9.0
app_file: app.py
pinned: false
tags:
  - mcp
  - mcp-in-action-track-01
  - model-context-protocol
  - multi-agent
  - autonomous-ai
  - gemini-2.0-flash
  - delivery-management
  - postgresql
---

# FleetMind MCP - Autonomous Dispatch Coordinator

**🏆 MCP 1st Birthday Hackathon Submission - Track: MCP in Action**

An autonomous AI coordinator that handles delivery exceptions using multi-agent orchestration powered by Google Gemini 2.0 Flash and the Model Context Protocol (MCP).

**🔗 Links:**
- **GitHub Repository:** https://github.com/mashrur-rahman-fahim/fleetmind-mcp
- **Hugging Face Space:** https://huggingface.co/spaces/MCP-1st-Birthday/fleetmind-dispatch-ai
- **Auto-Sync:** Every push to GitHub automatically updates HF Space via GitHub Actions ✨

---

## 👥 Team

**Team Name:** [Your Team Name]

**Team Members:**
- **[Your Name]** - [@your-hf-username](https://huggingface.co/your-hf-username) - Lead Developer & Repository Manager
- **[Partner 2 Name]** - [@partner2-username](https://huggingface.co/partner2-username) - [Role - e.g., Backend Developer, Testing]


**Collaboration:** Team collaborates via GitHub repository (https://github.com/mashrur-rahman-fahim/fleetmind-mcp) with automatic sync to HF Space via GitHub Actions.

*(Note: Replace placeholders with actual team member information. All members must have Hugging Face accounts and be listed here for valid hackathon submission.)*

---

## 🚀 Quick Start

### 1. Install PostgreSQL

**Windows:**
- Download from https://www.postgresql.org/download/windows/
- Install with default settings
- Remember your postgres password

**macOS:**
```bash
brew install postgresql
brew services start postgresql
```

**Linux:**
```bash
sudo apt-get install postgresql postgresql-contrib
sudo systemctl start postgresql
```

### 2. Create Database

```bash
# Login to PostgreSQL
psql -U postgres

# Create the database
CREATE DATABASE fleetmind;

# Exit
\q
```

### 3. Set Up Environment

```bash
# Install Python dependencies
pip install -r requirements.txt

# Copy environment template
cp .env.example .env

# Edit .env with your database credentials
# DB_HOST=localhost
# DB_PORT=5432
# DB_NAME=fleetmind
# DB_USER=postgres
# DB_PASSWORD=your_password_here
```

### 4. Initialize Database Schema

```bash
# Run database initialization script
python scripts/init_db.py
```

This will create all necessary tables in the PostgreSQL database.

### 3. Run Application

```bash
# Start the Gradio UI (coming soon)
python ui/app.py
```

## 📁 Project Structure

```
fleetmind-mcp/
├── database/               # Database connection and schema
│   ├── __init__.py
│   ├── connection.py      # Database connection utilities
│   └── schema.py          # Database schema definitions
├── data/                  # Database and data files
│   └── fleetmind.db      # SQLite database (auto-generated)
├── mcp_server/           # MCP server implementation
├── agents/               # Multi-agent system
├── workflows/            # Orchestration workflows
├── ui/                   # Gradio interface
├── tests/                # Test suite
├── scripts/              # Utility scripts
│   └── init_db.py       # Database initialization
├── requirements.txt      # Python dependencies
├── .env.example         # Environment variables template
└── README.md            # This file
```

## 📊 Database Schema (PostgreSQL)

The system uses PostgreSQL with the following tables:

### Orders Table

The `orders` table stores all delivery order information:

| Column | Type | Description |
|--------|------|-------------|
| order_id | VARCHAR(50) | Primary key |
| customer_name | VARCHAR(255) | Customer name |
| customer_phone | VARCHAR(20) | Contact phone |
| customer_email | VARCHAR(255) | Contact email |
| delivery_address | TEXT | Delivery address |
| delivery_lat/lng | DECIMAL(10,8) | GPS coordinates |
| time_window_start/end | TIMESTAMP | Delivery time window |
| priority | VARCHAR(20) | standard/express/urgent |
| weight_kg | DECIMAL(10,2) | Package weight |
| status | VARCHAR(20) | pending/assigned/in_transit/delivered/failed/cancelled |
| assigned_driver_id | VARCHAR(50) | Assigned driver |
| created_at | TIMESTAMP | Creation timestamp |
| updated_at | TIMESTAMP | Auto-updated timestamp |

### Additional Tables

- **drivers** - Driver information and status
- **assignments** - Order-driver assignments with routing
- **exceptions** - Exception tracking and resolution
- **agent_decisions** - AI agent decision logging
- **metrics** - Performance metrics and analytics

## 🔧 Development

### Database Operations

```python
from database.connection import get_db_connection, execute_query, execute_write

# Get all pending orders (note: PostgreSQL uses %s for parameters)
orders = execute_query("SELECT * FROM orders WHERE status = %s", ("pending",))

# Create new order
order_id = execute_write(
    "INSERT INTO orders (order_id, customer_name, delivery_address, status) VALUES (%s, %s, %s, %s)",
    ("ORD-001", "John Doe", "123 Main St", "pending")
)

# Test connection
from database.connection import test_connection
if test_connection():
    print("Database connected successfully!")
```

## 📝 License

MIT License

## 🤝 Contributing

Contributions welcome! Please read the contributing guidelines first.