README.md

metadata

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).

---

👥 Team

Team Name: [Your Team Name]

Team Members:

• [Your Name] - @your-hf-username - Lead Developer & Repository Manager
• [Partner 2 Name] - @partner2-username - [Role - e.g., Backend Developer, Testing]
• [Partner 3 Name] - @partner3-username - [Role - e.g., Documentation, Video]
• [Partner 4 Name] - @partner4-username - [Role - e.g., UI/UX Designer]
• [Partner 5 Name] - @partner5-username - [Role - e.g., Project Manager]

Collaboration: Team collaborates via [GitHub repository / Pull Requests / Task Division] with contributions managed by the lead developer.

(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:

brew install postgresql
brew services start postgresql

Linux:

sudo apt-get install postgresql postgresql-contrib
sudo systemctl start postgresql

2. Create Database

# Login to PostgreSQL
psql -U postgres

# Create the database
CREATE DATABASE fleetmind;

# Exit
\q

3. Set Up Environment

# 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

# Run database initialization script
python scripts/init_db.py

This will create all necessary tables in the PostgreSQL database.

3. Run Application

# 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

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.