Initial commit: FleetMind MCP with GitHub Actions auto-sync

- Complete FleetMind AI Dispatch Coordinator project
- Autonomous agent with Gemini 2.0 Flash
- Natural language order and driver creation
- GitHub Actions workflow for auto-sync to HF Space
- Team collaboration setup

MCP 1st Birthday Hackathon - Track: MCP in Action

.env.example

@@ -0,0 +1,28 @@
+# AI Provider Selection (choose one: "anthropic" or "gemini")
+AI_PROVIDER=anthropic
+
+# API Keys for AI Providers
+ANTHROPIC_API_KEY=your_anthropic_api_key_here
+GOOGLE_API_KEY=your_google_api_key_here
+
+# HERE Maps API Key (for geocoding)
+HERE_API_KEY=your_here_api_key_here
+
+# PostgreSQL Database Configuration
+DB_HOST=localhost
+DB_PORT=5432
+DB_NAME=fleetmind
+DB_USER=postgres
+DB_PASSWORD=your_password_here
+
+# MCP Server
+MCP_SERVER_NAME=dispatch-coordinator-mcp
+MCP_SERVER_VERSION=1.0.0
+
+# Gradio
+GRADIO_SERVER_PORT=7860
+GRADIO_SHARE=false
+
+# Logging
+LOG_LEVEL=INFO
+LOG_FILE=logs/fleetmind.log

.github/workflows/check-file-size.yml

@@ -0,0 +1,16 @@
+name: Check file size
+on:
+  pull_request:
+    branches: [main]
+
+  # Allow manual trigger from Actions tab
+  workflow_dispatch:
+
+jobs:
+  check-file-size:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check large files
+        uses: ActionsDesk/lfs-warning@v2.0
+        with:
+          filesizelimit: 10485760 # 10MB limit for HF Spaces sync

.github/workflows/sync-to-huggingface.yml

@@ -0,0 +1,24 @@
+name: Sync to Hugging Face Space
+on:
+  push:
+    branches: [main]
+
+  # Allow manual trigger from Actions tab
+  workflow_dispatch:
+
+jobs:
+  sync-to-hub:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+          lfs: true
+
+      - name: Push to Hugging Face Space
+        env:
+          HF_TOKEN: ${{ secrets.HF_TOKEN }}
+        run: |
+          git config --global user.email "github-actions[bot]@users.noreply.github.com"
+          git config --global user.name "github-actions[bot]"
+          git push https://MCP-1st-Birthday:$HF_TOKEN@huggingface.co/spaces/MCP-1st-Birthday/fleetmind-dispatch-ai main --force

.gitignore

@@ -0,0 +1,59 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual Environment
+venv/
+env/
+ENV/
+
+# Database
+*.db
+*.sqlite
+*.sqlite3
+data/*.db
+
+# Environment Variables
+.env
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# Logs
+logs/
+*.log
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Gradio
+gradio_cached_examples/
+flagged/

DRIVER_CREATION_GUIDE.md

@@ -0,0 +1,318 @@
+# Driver Creation Feature Guide
+
+## ✅ **Feature Status: READY**
+
+The driver creation feature has been successfully implemented and tested!
+
+---
+
+## 🚀 **How to Use**
+
+### **Step 1: Restart Your Application**
+
+Since we updated Gemini's system prompt and tools, restart the app:
+
+```bash
+# Stop the current app (Ctrl+C)
+python ui/app.py
+```
+
+---
+
+### **Step 2: Create Drivers Using Natural Language**
+
+Open the chat at http://127.0.0.1:7860 and type naturally!
+
+---
+
+## 📝 **Example Commands**
+
+### **Example 1: Complete Driver Info**
+
+```
+Add new driver Tom Wilson, phone 555-0101, drives a van, plate ABC-123
+```
+
+**Gemini will create:**
+- Driver ID: DRV-20251114HHMMSS (auto-generated)
+- Name: Tom Wilson
+- Phone: 555-0101
+- Vehicle: van
+- Plate: ABC-123
+- Status: active (default)
+- Capacity: 1000 kg (default for van)
+
+---
+
+### **Example 2: Driver with Skills**
+
+```
+Create driver Sarah Martinez, phone 555-0202, refrigerated truck, plate XYZ-789,
+skills: medical_certified, refrigerated
+```
+
+**Gemini will create:**
+- Name: Sarah Martinez
+- Phone: 555-0202
+- Vehicle: truck
+- Plate: XYZ-789
+- Skills: ["medical_certified", "refrigerated"]
+- Capacity: 1000 kg (default)
+
+---
+
+### **Example 3: Minimal Info (Name Only)**
+
+```
+Add driver Mike Chen
+```
+
+**Gemini will create:**
+- Name: Mike Chen
+- Vehicle: van (default)
+- Capacity: 1000 kg (default)
+- Status: active (default)
+- Skills: [] (empty by default)
+
+Gemini might ask: "Would you like to provide phone number or vehicle details?"
+
+---
+
+### **Example 4: Motorcycle Courier**
+
+```
+New driver: Lisa Anderson, phone 555-0303, motorcycle, express delivery specialist
+```
+
+**Gemini will create:**
+- Name: Lisa Anderson
+- Phone: 555-0303
+- Vehicle: motorcycle
+- Skills: ["express_delivery"]
+- Capacity: 50 kg (you can specify)
+
+---
+
+## 🎯 **Available Fields**
+
+### **Required:**
+- ✅ **name** - Driver's full name
+
+### **Optional:**
+- **phone** - Contact number (e.g., "+1-555-0101")
+- **email** - Email address (e.g., "driver@fleet.com")
+- **vehicle_type** - van | truck | car | motorcycle (default: van)
+- **vehicle_plate** - License plate (e.g., "ABC-1234")
+- **capacity_kg** - Cargo weight capacity in kg (default: 1000.0)
+- **capacity_m3** - Cargo volume capacity in m³ (default: 12.0)
+- **skills** - List of certifications/skills:
+  - `refrigerated` - Can handle cold storage
+  - `medical_certified` - Medical deliveries
+  - `fragile_handler` - Fragile items expert
+  - `overnight` - Overnight/late deliveries
+  - `express_delivery` - Express/rush deliveries
+- **status** - active | busy | offline | unavailable (default: active)
+
+---
+
+## 🧪 **Testing**
+
+### **Test 1: Verify Creation**
+
+After creating a driver, check the database:
+
+```bash
+python verify_drivers.py
+```
+
+This will show all drivers including the newly created one.
+
+---
+
+### **Test 2: Check in UI**
+
+Go to the **Orders** tab in the UI and you should see new drivers available for assignment.
+
+---
+
+## 📊 **What Happens Behind the Scenes**
+
+### **User Input:**
+```
+"Add new driver Tom Wilson, phone 555-0101, drives a van, plate ABC-123"
+```
+
+### **Gemini Processing:**
+1. **Parses** your natural language input
+2. **Extracts** driver information:
+   - name: "Tom Wilson"
+   - phone: "555-0101"
+   - vehicle_type: "van"
+   - vehicle_plate: "ABC-123"
+3. **Calls** `create_driver` tool with extracted data
+4. **Database** inserts the driver with auto-generated ID
+5. **Returns** confirmation message
+
+### **Database Record Created:**
+```sql
+INSERT INTO drivers (
+    driver_id,           -- DRV-20251114113250 (auto)
+    name,                -- Tom Wilson
+    phone,               -- 555-0101
+    vehicle_type,        -- van
+    vehicle_plate,       -- ABC-123
+    status,              -- active (default)
+    capacity_kg,         -- 1000.0 (default)
+    capacity_m3,         -- 12.0 (default)
+    skills,              -- [] (empty)
+    current_lat,         -- 37.7749 (default SF)
+    current_lng,         -- -122.4194 (default SF)
+    last_location_update -- 2025-11-14 11:32:50
+) VALUES (...)
+```
+
+---
+
+## 🔄 **Comparison: Orders vs Drivers**
+
+### **Creating an Order:**
+```
+User: "Create order for John Doe, 123 Main St SF, phone 555-1234"
+    ↓
+Gemini: [geocode_address] → [create_order] → "✅ Order created!"
+```
+**2 tools called** (geocoding required for addresses)
+
+### **Creating a Driver:**
+```
+User: "Add driver Tom Wilson, phone 555-0101, van"
+    ↓
+Gemini: [create_driver] → "✅ Driver created!"
+```
+**1 tool called** (no geocoding needed)
+
+---
+
+## ⚡ **Quick Reference**
+
+### **Conversational Examples:**
+
+✅ "I need to onboard a new driver named Alex"
+✅ "Add Sarah to the fleet, she drives a truck"
+✅ "New driver: Mike, phone 555-9999, motorcycle"
+✅ "Create driver with medical certification"
+✅ "Add a refrigerated truck driver named Bob"
+
+### **Structured Examples:**
+
+✅ "Create driver: Name: Tom Wilson, Phone: 555-0101, Vehicle: van, Plate: ABC-123"
+✅ "New driver - Name: Sarah, Email: sarah@fleet.com, Vehicle type: truck, Skills: refrigerated, medical_certified"
+
+---
+
+## 🎨 **Sample Responses from Gemini**
+
+### **Successful Creation:**
+```
+✅ Driver DRV-20251114113250 created successfully!
+
+Driver Details:
+• Driver ID: DRV-20251114113250
+• Name: Tom Wilson
+• Phone: 555-0101
+• Vehicle: van (ABC-123)
+• Capacity: 1000 kg
+• Status: Active
+• Skills: None
+
+The driver has been added to your fleet and is ready for order assignments!
+```
+
+### **Missing Information:**
+```
+I can create a driver for you! I have:
+• Name: Tom Wilson
+
+To complete the driver profile, please provide (optional):
+• Phone number
+• Vehicle type (van/truck/car/motorcycle)
+• License plate number
+• Any special skills or certifications
+
+Or I can create the driver now with default settings?
+```
+
+---
+
+## 🛠️ **Technical Details**
+
+### **Function:** `handle_create_driver()`
+**Location:** `chat/tools.py:245-331`
+
+### **Tool Definition:**
+**Location:** `chat/providers/gemini_provider.py:140-186`
+
+### **System Prompt:**
+**Location:** `chat/providers/gemini_provider.py:32-89`
+
+---
+
+## ✨ **Next Steps**
+
+After creating drivers, you can:
+
+1. **Assign orders to drivers** (coming soon)
+2. **View driver list** in the UI
+3. **Update driver status** (active/busy/offline)
+4. **Track driver locations** (coming soon)
+
+---
+
+## 🐛 **Troubleshooting**
+
+### **Issue: "Unknown tool: create_driver"**
+
+**Solution:** Restart the application to reload the new tools:
+```bash
+# Stop app (Ctrl+C)
+python ui/app.py
+```
+
+### **Issue: Driver created but not showing in database**
+
+**Solution:** Check database connection and verify:
+```bash
+python verify_drivers.py
+```
+
+### **Issue: "Missing required field: name"**
+
+**Solution:** Make sure you provide at least the driver's name:
+```
+"Add driver John Smith"  ✅
+"Add a new driver"       ❌ (no name)
+```
+
+---
+
+## 📈 **Feature Comparison**
+
+| Feature | Orders | Drivers |
+|---------|--------|---------|
+| **Required Fields** | 3 (name, address, contact) | 1 (name) |
+| **Geocoding Needed** | ✅ Yes | ❌ No |
+| **Tools Called** | 2 (geocode + create) | 1 (create) |
+| **Default Values** | Priority, weight | Vehicle type, capacity, status |
+| **Complex Data** | Time windows, coordinates | Skills array, JSON |
+
+---
+
+## 🎉 **Ready to Use!**
+
+Your FleetMind system can now:
+- ✅ Create customer orders
+- ✅ Create delivery drivers
+- ✅ Geocode addresses
+- ✅ Store everything in PostgreSQL
+
+Just talk naturally to Gemini and it handles the rest! 🚀

GITHUB_ACTIONS_SETUP.md

@@ -0,0 +1,315 @@
+# GitHub Actions Auto-Sync Setup Guide
+
+This guide walks you through setting up automatic synchronization from your GitHub repository to your Hugging Face Space using GitHub Actions.
+
+## ✅ What's Already Done
+
+- [x] Created GitHub repository directory: `F:\github-fleetmind-team`
+- [x] Copied all HF Space code to GitHub repo
+- [x] Created GitHub Actions workflows:
+  - `.github/workflows/sync-to-huggingface.yml` - Auto-sync on push
+  - `.github/workflows/check-file-size.yml` - Check file sizes on PRs
+
+## 🎯 What You Need to Do Now
+
+### STEP 3: Get Your Hugging Face Token
+
+1. **Go to:** https://huggingface.co/settings/tokens
+
+2. **Click:** "Create new token"
+
+3. **Fill in:**
+   - Name: `GitHub Actions Sync`
+   - Type: **Write** (important!)
+   - Scope: Select **all** or at least:
+     - ✅ Write access to repos
+     - ✅ Write access to spaces
+
+4. **Click:** "Generate token"
+
+5. **COPY THE TOKEN** (you won't see it again!)
+   - It looks like: `hf_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx`
+
+---
+
+### STEP 4: Push Code to GitHub
+
+Open PowerShell or Command Prompt:
+
+```bash
+# Navigate to the GitHub repo
+cd F:\github-fleetmind-team
+
+# Add all files
+git add .
+
+# Commit
+git commit -m "Initial commit: FleetMind MCP with GitHub Actions sync"
+
+# Add GitHub remote (REPLACE YOUR-USERNAME with your actual GitHub username)
+git remote add origin https://github.com/YOUR-USERNAME/fleetmind-mcp.git
+
+# Push to GitHub
+git push -u origin main
+```
+
+**If you get an error about 'main' branch:**
+```bash
+# Rename branch to main
+git branch -M main
+
+# Push again
+git push -u origin main
+```
+
+---
+
+### STEP 5: Add HF_TOKEN as GitHub Secret
+
+1. **Go to your GitHub repo:**
+   - URL: `https://github.com/YOUR-USERNAME/fleetmind-mcp`
+
+2. **Click:** Settings (top right of repo page)
+
+3. **In left sidebar, click:**
+   - Secrets and variables → Actions
+
+4. **Click:** "New repository secret"
+
+5. **Fill in:**
+   - Name: `HF_TOKEN`
+   - Secret: Paste the Hugging Face token you copied in Step 3
+
+6. **Click:** "Add secret"
+
+---
+
+### STEP 6: Add HF Space as Git Remote (Optional but Recommended)
+
+This allows you to manually push to HF Space if needed:
+
+```bash
+cd F:\github-fleetmind-team
+
+# Add HF Space as a remote
+git remote add space https://huggingface.co/spaces/MCP-1st-Birthday/fleetmind-dispatch-ai
+
+# Verify remotes
+git remote -v
+```
+
+You should see:
+```
+origin  https://github.com/YOUR-USERNAME/fleetmind-mcp.git (fetch)
+origin  https://github.com/YOUR-USERNAME/fleetmind-mcp.git (push)
+space   https://huggingface.co/spaces/MCP-1st-Birthday/fleetmind-dispatch-ai (fetch)
+space   https://huggingface.co/spaces/MCP-1st-Birthday/fleetmind-dispatch-ai (push)
+```
+
+---
+
+### STEP 7: Test the Auto-Sync
+
+Let's make a test change to verify everything works:
+
+```bash
+cd F:\github-fleetmind-team
+
+# Make a small change to README
+echo "\n\n## 🤖 Auto-Synced with GitHub Actions" >> README.md
+
+# Commit the change
+git add README.md
+git commit -m "Test: GitHub Actions auto-sync"
+
+# Push to GitHub
+git push origin main
+```
+
+**What happens next:**
+
+1. ✅ Code pushes to GitHub
+2. ✅ GitHub Actions triggers automatically
+3. ✅ Workflow runs and pushes to HF Space
+4. ✅ HF Space rebuilds with new code
+
+**Check the progress:**
+
+1. **On GitHub:**
+   - Go to: `https://github.com/YOUR-USERNAME/fleetmind-mcp/actions`
+   - You'll see "Sync to Hugging Face Space" workflow running
+   - Wait for green checkmark ✅
+
+2. **On Hugging Face:**
+   - Go to: https://huggingface.co/spaces/MCP-1st-Birthday/fleetmind-dispatch-ai
+   - Check the "Files" tab - you should see the new commit
+   - Space will rebuild automatically
+
+---
+
+## 🎉 Success! Your Setup is Complete
+
+From now on:
+
+### **Team Members Workflow:**
+
+```bash
+# 1. Clone the GitHub repo (one time)
+git clone https://github.com/YOUR-USERNAME/fleetmind-mcp.git
+cd fleetmind-mcp
+
+# 2. Make changes
+# ... edit files ...
+
+# 3. Commit and push to GitHub
+git add .
+git commit -m "Add new feature"
+git push origin main
+
+# 4. GitHub Actions automatically syncs to HF Space
+# ✨ DONE! Nothing else needed!
+```
+
+### **What GitHub Actions Does:**
+
+Every time someone pushes to the `main` branch on GitHub:
+
+1. ✅ GitHub Actions workflow starts
+2. ✅ Checks out the code
+3. ✅ Pushes to HF Space using your HF_TOKEN
+4. ✅ HF Space rebuilds automatically
+5. ✅ Your app goes live with the new changes
+
+---
+
+## 📋 Adding Team Members
+
+### On GitHub (Full Access):
+
+1. Go to: `https://github.com/YOUR-USERNAME/fleetmind-mcp/settings/access`
+2. Click "Add people"
+3. Enter their GitHub username
+4. Select role: **Write** (they can push directly)
+5. Click "Add"
+
+### On Hugging Face (Documentation Only):
+
+Team members don't need HF access! The GitHub Actions bot handles all HF Space updates using your HF_TOKEN.
+
+Just make sure they're listed in the README:
+- Edit `README.md` lines 29-42
+- Add their real names and HF usernames
+- Commit and push
+
+---
+
+## 🔧 Troubleshooting
+
+### ❌ "Error: Process completed with exit code 128"
+
+**Solution:** Check that HF_TOKEN is correctly set in GitHub Secrets
+- Go to: `https://github.com/YOUR-USERNAME/fleetmind-mcp/settings/secrets/actions`
+- Verify `HF_TOKEN` exists
+- If not, add it (see Step 5)
+
+### ❌ "Error: failed to push some refs"
+
+**Solution:** HF Space has newer commits
+```bash
+# Pull from HF Space first
+git pull space main --allow-unrelated-histories
+
+# Then push again
+git push origin main
+```
+
+### ❌ GitHub Actions workflow doesn't run
+
+**Solution:** Check that workflow file is in correct location
+- Must be: `.github/workflows/sync-to-huggingface.yml`
+- Check GitHub repo → Actions tab
+- Click "I understand my workflows, go ahead and enable them"
+
+### ❌ Files larger than 10MB
+
+**Solution:** Use Git LFS
+```bash
+# Install Git LFS
+git lfs install
+
+# Track large files
+git lfs track "*.psd"  # Example: Photoshop files
+git lfs track "*.pkl"  # Example: Model files
+
+# Commit .gitattributes
+git add .gitattributes
+git commit -m "Add Git LFS tracking"
+git push
+```
+
+---
+
+## 🚀 Advanced: Manual Sync
+
+If you ever need to manually sync to HF Space:
+
+```bash
+cd F:\github-fleetmind-team
+
+# Option 1: Push directly to HF Space remote
+git push space main
+
+# Option 2: Trigger GitHub Actions manually
+# Go to: https://github.com/YOUR-USERNAME/fleetmind-mcp/actions
+# Click "Sync to Hugging Face Space"
+# Click "Run workflow" → "Run workflow"
+```
+
+---
+
+## 📊 Workflow Diagram
+
+```
+Developer → GitHub Repo → GitHub Actions → HF Space → Live App
+   ↓            ↓              ↓              ↓          ↓
+ Codes      Receives       Triggers       Updates    Rebuilds
+           Push Event       Sync         with new    & Serves
+                                          code
+```
+
+---
+
+## 🎯 Benefits of This Setup
+
+✅ **Team Collaboration:** Everyone works on GitHub (familiar workflow)
+✅ **Automatic Deployment:** Push to GitHub = Deploy to HF Space
+✅ **No Permission Issues:** GitHub Actions uses your HF_TOKEN
+✅ **Version Control:** Full history on GitHub
+✅ **CI/CD Ready:** Can add tests, linting, etc.
+✅ **Hackathon Compliant:** Final Space is on HF organization
+
+---
+
+## 📝 Next Steps
+
+After setup is complete:
+
+1. **Invite team members to GitHub repo**
+2. **Update README with team information**
+3. **Continue building your project**
+4. **Create demo video (1-5 minutes)**
+5. **Post on social media**
+6. **Submit before November 30, 2025**
+
+---
+
+## 📚 Resources
+
+- **GitHub Actions Docs:** https://docs.github.com/en/actions
+- **HF Spaces Docs:** https://huggingface.co/docs/hub/spaces
+- **Git LFS:** https://git-lfs.github.com/
+- **Hackathon Info:** https://huggingface.co/MCP-1st-Birthday
+
+---
+
+**You're all set! Happy coding! 🚀**

QUICK_START.md

@@ -0,0 +1,138 @@
+# GitHub Actions Setup - Quick Start
+
+## ⚡ Complete These 4 Steps (15 minutes)
+
+### STEP 1: Create GitHub Repository (2 min)
+
+1. Go to: https://github.com/new
+2. Name: `fleetmind-mcp`
+3. Visibility: Public
+4. **DON'T** initialize with README
+5. Click "Create repository"
+6. **SAVE YOUR USERNAME!**
+
+---
+
+### STEP 2: Get Hugging Face Token (2 min)
+
+1. Go to: https://huggingface.co/settings/tokens
+2. Click "Create new token"
+3. Name: `GitHub Actions Sync`
+4. Type: **Write**
+5. Click "Generate token"
+6. **COPY THE TOKEN** (starts with `hf_...`)
+
+---
+
+### STEP 3: Push to GitHub (3 min)
+
+**Open PowerShell and run:**
+
+```powershell
+# Navigate to repo
+cd F:\github-fleetmind-team
+
+# Add and commit
+git add .
+git commit -m "Initial commit with GitHub Actions"
+
+# Add GitHub remote (REPLACE YOUR-USERNAME!)
+git remote add origin https://github.com/YOUR-USERNAME/fleetmind-mcp.git
+
+# Push to GitHub
+git branch -M main
+git push -u origin main
+```
+
+**You'll be asked for credentials:**
+- Username: Your GitHub username
+- Password: Your GitHub Personal Access Token
+  - Get it at: https://github.com/settings/tokens
+  - Or use GitHub Desktop/CLI for easier auth
+
+---
+
+### STEP 4: Add HF_TOKEN to GitHub (3 min)
+
+1. **Go to:** `https://github.com/YOUR-USERNAME/fleetmind-mcp/settings/secrets/actions`
+
+2. **Click:** "New repository secret"
+
+3. **Fill in:**
+   - Name: `HF_TOKEN`
+   - Secret: Paste your Hugging Face token from Step 2
+
+4. **Click:** "Add secret"
+
+---
+
+## ✅ Test It Works (5 min)
+
+```powershell
+cd F:\github-fleetmind-team
+
+# Make a small change
+echo "`n## Auto-synced from GitHub" >> README.md
+
+# Commit and push
+git add README.md
+git commit -m "Test: Auto-sync"
+git push origin main
+```
+
+**Check:**
+1. GitHub Actions: `https://github.com/YOUR-USERNAME/fleetmind-mcp/actions`
+   - Should show green checkmark ✅
+2. HF Space: https://huggingface.co/spaces/MCP-1st-Birthday/fleetmind-dispatch-ai
+   - Should have new commit
+
+---
+
+## 🎉 Done! Now Your Team Can Collaborate
+
+**Team members:**
+
+```bash
+# Clone GitHub repo
+git clone https://github.com/YOUR-USERNAME/fleetmind-mcp.git
+cd fleetmind-mcp
+
+# Make changes
+# ... edit files ...
+
+# Push to GitHub (auto-syncs to HF Space!)
+git add .
+git commit -m "Add feature"
+git push
+```
+
+**Every push to GitHub automatically updates HF Space!** ✨
+
+---
+
+## 📋 Add Team Members to GitHub
+
+1. Go to: `https://github.com/YOUR-USERNAME/fleetmind-mcp/settings/access`
+2. Click "Add people"
+3. Enter their GitHub username
+4. Role: **Write**
+5. Click "Add"
+
+---
+
+## 🆘 Quick Troubleshooting
+
+**GitHub Actions fails?**
+→ Check HF_TOKEN is set correctly in GitHub Secrets
+
+**Can't push to GitHub?**
+→ Create GitHub Personal Access Token: https://github.com/settings/tokens
+
+**Files too large?**
+→ Use Git LFS (see full guide)
+
+---
+
+**Full documentation:** See `GITHUB_ACTIONS_SETUP.md`
+
+**Ready to build!** 🚀

README.md

@@ -0,0 +1,195 @@
+---
+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](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]
+- **[Partner 3 Name]** - [@partner3-username](https://huggingface.co/partner3-username) - [Role - e.g., Documentation, Video]
+- **[Partner 4 Name]** - [@partner4-username](https://huggingface.co/partner4-username) - [Role - e.g., UI/UX Designer]
+- **[Partner 5 Name]** - [@partner5-username](https://huggingface.co/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:**
+```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.

TEAM_COLLABORATION_GUIDE.md

@@ -0,0 +1,305 @@
+# Team Collaboration Guide - MCP 1st Birthday Hackathon
+
+## Overview
+
+This guide explains how to add team partners to your FleetMind MCP hackathon submission on Hugging Face Spaces.
+
+**Hackathon Details:**
+- **Team Size:** 2-5 members allowed
+- **Your Space:** https://huggingface.co/spaces/MCP-1st-Birthday/fleetmind-dispatch-ai
+- **Submission Deadline:** November 30, 2025 (11:59 PM UTC)
+- **Track:** MCP in Action (Track 01)
+
+---
+
+## Method 1: Add Team Members via README Documentation (EASIEST)
+
+For hackathon submission purposes, you MUST document your team in the Space's README.md file.
+
+### Steps:
+
+1. **Edit the Team Section in README.md**
+
+   The Team section is already added to your README. Update it with your actual team information:
+
+   ```markdown
+   ## 👥 Team
+
+   **Team Name:** FleetMind AI Team
+
+   **Team Members:**
+   - **John Doe** - [@johndoe](https://huggingface.co/johndoe) - Lead Developer & AI Architect
+   - **Jane Smith** - [@janesmith](https://huggingface.co/janesmith) - Database Engineer
+   - **Alex Chen** - [@alexchen](https://huggingface.co/alexchen) - UI/UX Developer
+   ```
+
+2. **Replace Placeholders:**
+   - `[Your Team Name]` → Your actual team name
+   - `[Your Name]` → Team member's real name
+   - `@your-hf-username` → Their Hugging Face username
+   - `[Role]` → Their role in the project
+
+3. **Commit and Push:**
+
+   ```bash
+   cd F:\fleetmind-mcp\fleetmind-dispatch-ai
+   git add README.md
+   git commit -m "Update team member information"
+   git push
+   ```
+
+---
+
+## Method 2: Grant Git Access to Team Partners (TECHNICAL COLLABORATION)
+
+If your team partners need to push code directly to the Space, they need Git access.
+
+### Option A: Via Organization Membership
+
+Since your Space is owned by the **MCP-1st-Birthday organization**, team members can:
+
+1. **Join the Organization:**
+   - Go to https://huggingface.co/MCP-1st-Birthday
+   - Click **"Request to join this org"** (top right)
+   - Fill out the registration form
+   - Wait for admin approval
+
+2. **Verify Access:**
+   - Once approved, they'll automatically have access based on organization permissions
+   - Organization members with "write" or "contributor" roles can collaborate
+
+### Option B: Direct Collaborator Access
+
+If you have admin rights to your Space:
+
+1. **Go to Space Settings:**
+   - Visit: https://huggingface.co/spaces/MCP-1st-Birthday/fleetmind-dispatch-ai/settings
+   - Look for "Collaborators" or "Access" section
+
+2. **Add Collaborators by Username:**
+   - Enter their Hugging Face username
+   - Set their permission level (read/write/admin)
+   - Send invitation
+
+---
+
+## Method 3: Collaborate via Pull Requests (SAFEST)
+
+Team members can contribute without direct write access using Pull Requests.
+
+### Steps:
+
+1. **Team Partner Forks/Duplicates the Space:**
+   - They go to your Space page
+   - Click the three dots (top right) → "Duplicate this Space"
+   - Make changes in their forked version
+
+2. **Create Pull Request:**
+   - After making changes, they create a Pull Request
+   - You review and merge their changes
+
+3. **Enable Pull Requests:**
+   - Go to Space Settings
+   - Ensure "Pull Requests" are enabled
+
+---
+
+## Method 4: Share Git Credentials (NOT RECOMMENDED)
+
+While technically possible, sharing your Git credentials is NOT recommended for security reasons. Use Methods 1-3 instead.
+
+---
+
+## Technical Setup for Team Partners
+
+Once your team partners have access, they need to set up their local environment:
+
+### 1. Clone the Space
+
+```bash
+# Navigate to desired directory
+cd F:\
+
+# Clone the Space
+git clone https://huggingface.co/spaces/MCP-1st-Birthday/fleetmind-dispatch-ai
+
+# Enter directory
+cd fleetmind-dispatch-ai
+```
+
+### 2. Authenticate with Hugging Face
+
+They need a Hugging Face access token:
+
+1. **Get Token:**
+   - Go to https://huggingface.co/settings/tokens
+   - Click "New token"
+   - Create a token with "write" permissions
+
+2. **Login via CLI:**
+   ```bash
+   # Install Hugging Face CLI
+   pip install huggingface_hub
+
+   # Login (they'll be prompted for token)
+   huggingface-cli login
+   ```
+
+3. **Or Configure Git Credentials:**
+   ```bash
+   git config credential.helper store
+   ```
+
+   When they push for the first time, Git will ask for:
+   - Username: Their HF username
+   - Password: Their HF access token (NOT their account password)
+
+### 3. Make Changes and Push
+
+```bash
+# Make changes to files
+# ...
+
+# Stage changes
+git add .
+
+# Commit
+git commit -m "Add feature X"
+
+# Push to Space
+git push
+```
+
+---
+
+## Hugging Face Spaces Access Levels
+
+Understanding permission levels helps you decide what access to grant:
+
+| Role | Can View | Can Clone | Can Push | Can Manage Settings |
+|------|----------|-----------|----------|---------------------|
+| **Public** | ✅ | ✅ | ❌ | ❌ |
+| **Read** | ✅ | ✅ | ❌ | ❌ |
+| **Contributor** | ✅ | ✅ | Via PR only | ❌ |
+| **Write** | ✅ | ✅ | ✅ | ❌ |
+| **Admin** | ✅ | ✅ | ✅ | ✅ |
+
+---
+
+## Hackathon Submission Requirements
+
+For your team submission to be valid, ensure:
+
+### Required in README.md:
+- ✅ **Team section** with all member names and HF usernames
+- ✅ **Track tag:** `mcp-in-action-track-01` (already added)
+- ✅ **Demo video link** (1-5 minutes) - TODO
+- ✅ **Social media post link** - TODO
+
+### Required in Space:
+- ✅ Published as a Space in MCP-1st-Birthday organization
+- ✅ App.py entry point (already created)
+- ✅ Working Gradio interface
+- ✅ All code created during hackathon period (Nov 14-30, 2025)
+
+---
+
+## Troubleshooting
+
+### "Permission denied" when team partner tries to push
+
+**Solution:**
+1. Verify they're added as collaborators with write access
+2. Check they're using the correct HF access token (not account password)
+3. Ensure token has "write" permissions
+
+### "Repository not found" error
+
+**Solution:**
+1. Verify the Space URL is correct
+2. Check they have at least "read" access
+3. Ensure they're logged in: `huggingface-cli whoami`
+
+### Team member can't see the Space
+
+**Solution:**
+1. If Space is private, add them as collaborators
+2. If Space is public (recommended for hackathon), they should see it
+3. Check organization membership status
+
+---
+
+## Best Practices for Team Collaboration
+
+1. **Communication:**
+   - Use Discord channel: agents-mcp-hackathon-winter25
+   - Create a team group chat
+   - Document decisions in README
+
+2. **Code Management:**
+   - Pull before making changes: `git pull`
+   - Commit frequently with clear messages
+   - Test locally before pushing
+
+3. **Task Distribution:**
+   - Assign specific files/features to team members
+   - Avoid editing the same files simultaneously
+   - Use TODO comments in code
+
+4. **Version Control:**
+   - Create branches for major features (optional)
+   - Use descriptive commit messages
+   - Review each other's code
+
+---
+
+## Quick Reference Commands
+
+```bash
+# Clone the Space
+git clone https://huggingface.co/spaces/MCP-1st-Birthday/fleetmind-dispatch-ai
+
+# Check current status
+git status
+
+# Pull latest changes
+git pull
+
+# Add all changes
+git add .
+
+# Commit with message
+git commit -m "Description of changes"
+
+# Push to Space
+git push
+
+# Check who you're logged in as
+huggingface-cli whoami
+
+# Login to HF
+huggingface-cli login
+```
+
+---
+
+## Support & Resources
+
+- **Hackathon Discord:** agents-mcp-hackathon-winter25 channel
+- **Office Hours:** November 17-28 with Gradio team
+- **HF Documentation:** https://huggingface.co/docs/hub/spaces
+- **Git Documentation:** https://git-scm.com/doc
+
+---
+
+## Timeline Reminder
+
+- **Start Date:** November 14, 2025
+- **Submission Deadline:** November 30, 2025 (11:59 PM UTC)
+- **Days Remaining:** Check dashboard regularly
+
+Make sure all team members are added to README.md before the deadline!
+
+---
+
+**Good luck with your hackathon submission! 🚀**

app.py

@@ -0,0 +1,27 @@
+"""
+FleetMind MCP - Hugging Face Spaces Entry Point
+This is the main entry point for the HF Space deployment
+"""
+
+import sys
+from pathlib import Path
+
+# Add current directory to path
+sys.path.insert(0, str(Path(__file__).parent))
+
+# Import and launch the Gradio app
+from ui.app import create_interface
+
+if __name__ == "__main__":
+    print("=" * 60)
+    print("FleetMind MCP - Starting on Hugging Face Spaces")
+    print("=" * 60)
+
+    # Create and launch the interface
+    app = create_interface()
+    app.launch(
+        server_name="0.0.0.0",
+        server_port=7860,
+        share=False,
+        show_error=True
+    )

chat/__init__.py

@@ -0,0 +1,9 @@
+"""
+Chat package for FleetMind MCP
+Handles AI-powered natural language order creation
+"""
+
+from .chat_engine import ChatEngine
+from .conversation import ConversationManager
+
+__all__ = ['ChatEngine', 'ConversationManager']

chat/chat_engine.py

@@ -0,0 +1,108 @@
+"""
+Chat engine for FleetMind
+Main orchestrator for AI-powered conversations with multi-provider support
+"""
+
+import os
+import logging
+from typing import Tuple, List, Dict
+
+from chat.providers import ClaudeProvider, GeminiProvider
+
+logger = logging.getLogger(__name__)
+
+
+class ChatEngine:
+    """Main orchestrator for AI chat conversations with multi-provider support"""
+
+    def __init__(self):
+        # Get provider selection from environment
+        provider_name = os.getenv("AI_PROVIDER", "anthropic").lower()
+
+        logger.info(f"ChatEngine: Selected provider: {provider_name}")
+
+        # Initialize the selected provider
+        if provider_name == "gemini":
+            self.provider = GeminiProvider()
+            logger.info("ChatEngine: Using Gemini provider")
+        elif provider_name == "anthropic":
+            self.provider = ClaudeProvider()
+            logger.info("ChatEngine: Using Claude provider")
+        else:
+            # Default to Claude if unknown provider
+            logger.warning(f"ChatEngine: Unknown provider '{provider_name}', defaulting to Claude")
+            self.provider = ClaudeProvider()
+
+        # Store provider name for UI
+        self.selected_provider = provider_name
+
+    def is_available(self) -> bool:
+        """Check if the chat engine is available"""
+        return self.provider.is_available()
+
+    def get_status(self) -> str:
+        """Get status message for UI"""
+        provider_status = self.provider.get_status()
+        provider_name = self.provider.get_provider_name()
+
+        return f"**{provider_name}:** {provider_status}"
+
+    def get_provider_name(self) -> str:
+        """Get the active provider name"""
+        return self.provider.get_provider_name()
+
+    def get_model_name(self) -> str:
+        """Get the active model name"""
+        return self.provider.get_model_name()
+
+    def process_message(
+        self,
+        user_message: str,
+        conversation
+    ) -> Tuple[str, List[Dict]]:
+        """
+        Process user message and return AI response
+
+        Args:
+            user_message: User's message
+            conversation: ConversationManager instance
+
+        Returns:
+            Tuple of (assistant_response, tool_calls_made)
+        """
+        return self.provider.process_message(user_message, conversation)
+
+    def get_welcome_message(self) -> str:
+        """Get welcome message for new conversations"""
+        return self.provider.get_welcome_message()
+
+    def get_full_status(self) -> Dict[str, str]:
+        """
+        Get detailed status for all providers
+
+        Returns:
+            Dict with status for each provider
+        """
+        # Get status without creating new instances (avoid API calls)
+        claude_key = os.getenv("ANTHROPIC_API_KEY", "")
+        gemini_key = os.getenv("GOOGLE_API_KEY", "")
+
+        claude_available = bool(claude_key and not claude_key.startswith("your_"))
+        gemini_available = bool(gemini_key and not gemini_key.startswith("your_"))
+
+        claude_status = "✅ Connected - Model: claude-3-5-sonnet-20241022" if claude_available else "⚠️ Not configured (add ANTHROPIC_API_KEY)"
+        gemini_status = f"✅ Connected - Model: {self.provider.get_model_name()}" if (self.selected_provider == "gemini" and gemini_available) else "⚠️ Not configured (add GOOGLE_API_KEY)" if not gemini_available else "✅ Configured"
+
+        return {
+            "selected": self.selected_provider,
+            "claude": {
+                "name": "Claude (Anthropic)",
+                "status": claude_status,
+                "available": claude_available
+            },
+            "gemini": {
+                "name": "Gemini (Google)",
+                "status": gemini_status,
+                "available": gemini_available
+            }
+        }

chat/conversation.py

@@ -0,0 +1,85 @@
+"""
+Conversation manager for FleetMind chat
+Handles conversation state and history
+"""
+
+import logging
+from typing import List, Dict
+
+logger = logging.getLogger(__name__)
+
+
+class ConversationManager:
+    """Manage conversation state and history"""
+
+    def __init__(self):
+        self.history = []
+        self.tool_calls = []  # Track all tool calls for transparency
+        self.order_context = {}  # Accumulated order details
+
+    def add_message(self, role: str, content: str):
+        """
+        Add message to conversation history
+
+        Args:
+            role: "user" or "assistant"
+            content: Message content
+        """
+        self.history.append({
+            "role": role,
+            "content": content
+        })
+
+    def add_tool_result(self, tool_name: str, tool_input: dict, tool_result: dict):
+        """
+        Track tool usage for transparency
+
+        Args:
+            tool_name: Name of the tool called
+            tool_input: Input parameters
+            tool_result: Result from tool execution
+        """
+        self.tool_calls.append({
+            "tool": tool_name,
+            "input": tool_input,
+            "result": tool_result
+        })
+
+    def get_history(self) -> List[Dict]:
+        """Get full conversation history"""
+        return self.history
+
+    def get_tool_calls(self) -> List[Dict]:
+        """Get all tool calls made in this conversation"""
+        return self.tool_calls
+
+    def get_last_tool_call(self) -> Dict:
+        """Get the most recent tool call"""
+        if self.tool_calls:
+            return self.tool_calls[-1]
+        return {}
+
+    def clear_tool_calls(self):
+        """Clear tool call history"""
+        self.tool_calls = []
+
+    def reset(self):
+        """Start a new conversation"""
+        self.history = []
+        self.tool_calls = []
+        self.order_context = {}
+        logger.info("Conversation reset")
+
+    def get_message_count(self) -> int:
+        """Get number of messages in conversation"""
+        return len(self.history)
+
+    def get_formatted_history(self) -> List[Dict]:
+        """
+        Get history formatted for Gradio chatbot (messages format)
+
+        Returns:
+            List of message dictionaries with 'role' and 'content' keys
+        """
+        # For Gradio type="messages", return list of dicts with role/content
+        return self.history

chat/geocoding.py

@@ -0,0 +1,131 @@
+"""
+Geocoding service for FleetMind
+Handles address validation with HERE API and smart mock fallback
+"""
+
+import os
+import requests
+import logging
+from typing import Dict, Optional
+
+logger = logging.getLogger(__name__)
+
+# Common city coordinates for mock geocoding
+CITY_COORDINATES = {
+    "san francisco": (37.7749, -122.4194),
+    "sf": (37.7749, -122.4194),
+    "new york": (40.7128, -74.0060),
+    "nyc": (40.7128, -74.0060),
+    "los angeles": (34.0522, -118.2437),
+    "la": (34.0522, -118.2437),
+    "chicago": (41.8781, -87.6298),
+    "houston": (29.7604, -95.3698),
+    "phoenix": (33.4484, -112.0740),
+    "philadelphia": (39.9526, -75.1652),
+    "san antonio": (29.4241, -98.4936),
+    "san diego": (32.7157, -117.1611),
+    "dallas": (32.7767, -96.7970),
+    "austin": (30.2672, -97.7431),
+    "seattle": (47.6062, -122.3321),
+    "boston": (42.3601, -71.0589),
+    "denver": (39.7392, -104.9903),
+    "miami": (25.7617, -80.1918),
+    "atlanta": (33.7490, -84.3880),
+    "portland": (45.5152, -122.6784),
+}
+
+
+class GeocodingService:
+    """Handle address geocoding with HERE API and smart mock fallback"""
+
+    def __init__(self):
+        self.here_api_key = os.getenv("HERE_API_KEY", "")
+        self.use_mock = not self.here_api_key or self.here_api_key.startswith("your_")
+
+        if self.use_mock:
+            logger.info("Geocoding: Using mock (HERE_API_KEY not configured)")
+        else:
+            logger.info("Geocoding: Using HERE Maps API")
+
+    def geocode(self, address: str) -> Dict:
+        """
+        Geocode address, using mock if API unavailable
+
+        Args:
+            address: Street address to geocode
+
+        Returns:
+            Dict with keys: lat, lng, formatted_address, confidence
+        """
+        if self.use_mock:
+            return self._geocode_mock(address)
+        else:
+            try:
+                return self._geocode_here(address)
+            except Exception as e:
+                logger.error(f"HERE API failed: {e}, falling back to mock")
+                return self._geocode_mock(address)
+
+    def _geocode_here(self, address: str) -> Dict:
+        """Real HERE API geocoding"""
+        url = "https://geocode.search.hereapi.com/v1/geocode"
+
+        params = {
+            "q": address,
+            "apiKey": self.here_api_key
+        }
+
+        response = requests.get(url, params=params, timeout=10)
+        response.raise_for_status()
+
+        data = response.json()
+
+        if not data.get("items"):
+            # No results found, fall back to mock
+            logger.warning(f"HERE API found no results for: {address}")
+            return self._geocode_mock(address)
+
+        # Get first result
+        item = data["items"][0]
+        position = item["position"]
+
+        return {
+            "lat": position["lat"],
+            "lng": position["lng"],
+            "formatted_address": item.get("address", {}).get("label", address),
+            "confidence": "high (HERE API)"
+        }
+
+    def _geocode_mock(self, address: str) -> Dict:
+        """
+        Smart mock geocoding for testing
+        Tries to detect city name and use approximate coordinates
+        """
+        address_lower = address.lower()
+
+        # Try to find a city match
+        for city, coords in CITY_COORDINATES.items():
+            if city in address_lower:
+                logger.info(f"Mock geocoding detected city: {city}")
+                return {
+                    "lat": coords[0],
+                    "lng": coords[1],
+                    "formatted_address": address,
+                    "confidence": f"medium (mock - {city})"
+                }
+
+        # Default to San Francisco if no city detected
+        logger.info("Mock geocoding: Using default SF coordinates")
+        return {
+            "lat": 37.7749,
+            "lng": -122.4194,
+            "formatted_address": address,
+            "confidence": "low (mock - default)"
+        }
+
+    def get_status(self) -> str:
+        """Get geocoding service status"""
+        if self.use_mock:
+            return "⚠️ Using mock geocoding (add HERE_API_KEY for real)"
+        else:
+            return "✅ HERE Maps API connected"

chat/providers/__init__.py

@@ -0,0 +1,10 @@
+"""
+AI Provider implementations for FleetMind chat
+Supports multiple AI providers (Anthropic Claude, Google Gemini)
+"""
+
+from .base_provider import AIProvider
+from .claude_provider import ClaudeProvider
+from .gemini_provider import GeminiProvider
+
+__all__ = ['AIProvider', 'ClaudeProvider', 'GeminiProvider']

chat/providers/base_provider.py

@@ -0,0 +1,53 @@
+"""
+Base provider interface for AI providers
+"""
+
+from abc import ABC, abstractmethod
+from typing import Tuple, List, Dict
+
+
+class AIProvider(ABC):
+    """Abstract base class for AI providers"""
+
+    @abstractmethod
+    def is_available(self) -> bool:
+        """Check if the provider is available (API key configured)"""
+        pass
+
+    @abstractmethod
+    def get_status(self) -> str:
+        """Get status message for UI"""
+        pass
+
+    @abstractmethod
+    def get_provider_name(self) -> str:
+        """Get provider name (e.g., 'Claude', 'Gemini')"""
+        pass
+
+    @abstractmethod
+    def get_model_name(self) -> str:
+        """Get model name (e.g., 'claude-3-5-sonnet-20241022')"""
+        pass
+
+    @abstractmethod
+    def process_message(
+        self,
+        user_message: str,
+        conversation
+    ) -> Tuple[str, List[Dict]]:
+        """
+        Process user message and return AI response
+
+        Args:
+            user_message: User's message
+            conversation: ConversationManager instance
+
+        Returns:
+            Tuple of (assistant_response, tool_calls_made)
+        """
+        pass
+
+    @abstractmethod
+    def get_welcome_message(self) -> str:
+        """Get welcome message for new conversations"""
+        pass

chat/providers/claude_provider.py

@@ -0,0 +1,271 @@
+"""
+Anthropic Claude provider for FleetMind chat
+"""
+
+import os
+import logging
+from typing import Tuple, List, Dict
+from anthropic import Anthropic, APIError, APIConnectionError, AuthenticationError
+
+from chat.providers.base_provider import AIProvider
+from chat.tools import TOOLS_SCHEMA, execute_tool
+
+logger = logging.getLogger(__name__)
+
+
+class ClaudeProvider(AIProvider):
+    """Anthropic Claude AI provider"""
+
+    def __init__(self):
+        self.api_key = os.getenv("ANTHROPIC_API_KEY", "")
+        self.api_available = bool(self.api_key and not self.api_key.startswith("your_"))
+
+        if self.api_available:
+            try:
+                self.client = Anthropic(api_key=self.api_key)
+                logger.info("ClaudeProvider: Initialized successfully")
+            except Exception as e:
+                logger.error(f"ClaudeProvider: Failed to initialize: {e}")
+                self.api_available = False
+        else:
+            self.client = None
+            logger.warning("ClaudeProvider: ANTHROPIC_API_KEY not configured")
+
+        self.model = "claude-3-5-sonnet-20241022"
+        self.system_prompt = self._get_system_prompt()
+
+    def _get_system_prompt(self) -> str:
+        """Get the system prompt for Claude"""
+        return """You are an AI assistant for FleetMind, a delivery dispatch system. Your job is to help coordinators create delivery orders efficiently.
+
+**IMPORTANT: When a user wants to create an order, FIRST show them this order form:**
+
+📋 **Order Information Form**
+Please provide the following details:
+
+**Required Fields:**
+• Customer Name: [Full name]
+• Delivery Address: [Street address, city, state, zip]
+• Contact: [Phone number OR email address]
+
+**Optional Fields:**
+• Delivery Deadline: [Date/time, or "ASAP" - default: 6 hours from now]
+• Priority: [standard/express/urgent - default: standard]
+• Special Instructions: [Any special notes]
+• Package Weight: [In kg - default: 5.0 kg]
+
+**Example:**
+"Customer: John Doe, Address: 123 Main St, San Francisco, CA 94103, Phone: 555-1234, Deliver by 5 PM today"
+
+---
+
+**Your Workflow:**
+1. **If user says "create order" or similar:** Show the form above and ask them to provide the information
+2. **If they provide all/most info:** Proceed immediately with geocoding and order creation
+3. **If information is missing:** Show what's missing from the form and ask for those specific fields
+4. **After collecting required fields:**
+   - Use `geocode_address` tool to validate the address
+   - Use `create_order` tool to save the order
+   - Provide a clear confirmation with order ID
+
+**Important Rules:**
+- ALWAYS geocode the address BEFORE creating an order
+- Be efficient - don't ask questions one at a time
+- Accept information in any format (natural language, bullet points, etc.)
+- Keep responses concise and professional
+- Show enthusiasm when orders are successfully created
+
+Remember: Dispatch coordinators are busy - help them create orders FAST!"""
+
+    def is_available(self) -> bool:
+        return self.api_available
+
+    def get_status(self) -> str:
+        if self.api_available:
+            return f"✅ Connected - Model: {self.model}"
+        return "⚠️ Not configured (add ANTHROPIC_API_KEY)"
+
+    def get_provider_name(self) -> str:
+        return "Claude (Anthropic)"
+
+    def get_model_name(self) -> str:
+        return self.model
+
+    def process_message(
+        self,
+        user_message: str,
+        conversation
+    ) -> Tuple[str, List[Dict]]:
+        """Process user message with Claude"""
+        if not self.api_available:
+            return self._handle_no_api(), []
+
+        # Add user message to history
+        conversation.add_message("user", user_message)
+
+        try:
+            # Make API call to Claude
+            response = self.client.messages.create(
+                model=self.model,
+                max_tokens=4096,
+                system=self.system_prompt,
+                tools=TOOLS_SCHEMA,
+                messages=conversation.get_history()
+            )
+
+            # Process response and handle tool calls
+            return self._process_response(response, conversation)
+
+        except AuthenticationError:
+            error_msg = "⚠️ Invalid API key. Please check your ANTHROPIC_API_KEY in .env file."
+            logger.error("Authentication error with Anthropic API")
+            return error_msg, []
+
+        except APIConnectionError:
+            error_msg = "⚠️ Cannot connect to Anthropic API. Please check your internet connection."
+            logger.error("Connection error with Anthropic API")
+            return error_msg, []
+
+        except APIError as e:
+            error_msg = f"⚠️ API error: {str(e)}"
+            logger.error(f"Anthropic API error: {e}")
+            return error_msg, []
+
+        except Exception as e:
+            error_msg = f"⚠️ Unexpected error: {str(e)}"
+            logger.error(f"Claude provider error: {e}")
+            return error_msg, []
+
+    def _process_response(
+        self,
+        response,
+        conversation
+    ) -> Tuple[str, List[Dict]]:
+        """Process Claude's response and handle tool calls"""
+        tool_calls_made = []
+
+        # Check if Claude wants to use tools
+        if response.stop_reason == "tool_use":
+            # Execute tools
+            tool_results = []
+
+            for content_block in response.content:
+                if content_block.type == "tool_use":
+                    tool_name = content_block.name
+                    tool_input = content_block.input
+
+                    logger.info(f"Claude executing tool: {tool_name}")
+
+                    # Execute the tool
+                    tool_result = execute_tool(tool_name, tool_input)
+
+                    # Track for transparency
+                    tool_calls_made.append({
+                        "tool": tool_name,
+                        "input": tool_input,
+                        "result": tool_result
+                    })
+
+                    conversation.add_tool_result(tool_name, tool_input, tool_result)
+
+                    # Prepare result for Claude
+                    tool_results.append({
+                        "type": "tool_result",
+                        "tool_use_id": content_block.id,
+                        "content": str(tool_result)
+                    })
+
+            # Add assistant's tool use to history
+            conversation.add_message("assistant", response.content)
+
+            # Add tool results to history
+            conversation.add_message("user", tool_results)
+
+            # Continue conversation with tool results
+            followup_response = self.client.messages.create(
+                model=self.model,
+                max_tokens=4096,
+                system=self.system_prompt,
+                tools=TOOLS_SCHEMA,
+                messages=conversation.get_history()
+            )
+
+            # Extract final text response
+            final_text = self._extract_text_response(followup_response)
+            conversation.add_message("assistant", final_text)
+
+            return final_text, tool_calls_made
+
+        else:
+            # No tool use, just text response
+            text_response = self._extract_text_response(response)
+            conversation.add_message("assistant", text_response)
+            return text_response, tool_calls_made
+
+    def _extract_text_response(self, response) -> str:
+        """Extract text content from Claude's response"""
+        text_parts = []
+        for block in response.content:
+            if hasattr(block, 'text'):
+                text_parts.append(block.text)
+            elif block.type == "text":
+                text_parts.append(block.text if hasattr(block, 'text') else str(block))
+
+        return "\n".join(text_parts) if text_parts else "I apologize, but I couldn't generate a response."
+
+    def _handle_no_api(self) -> str:
+        """Return error message when API is not available"""
+        return """⚠️ **Claude API requires Anthropic API key**
+
+To use Claude:
+
+1. Get an API key from: https://console.anthropic.com/
+   - Sign up for free ($5 credit available)
+   - Or use hackathon credits
+
+2. Add to your `.env` file:
+   ```
+   ANTHROPIC_API_KEY=sk-ant-your-key-here
+   ```
+
+3. Restart the application
+
+**Alternative:** Switch to Gemini by setting `AI_PROVIDER=gemini` in .env
+"""
+
+    def get_welcome_message(self) -> str:
+        if not self.api_available:
+            return self._handle_no_api()
+
+        return """👋 Hello! I'm your AI dispatch assistant powered by **Claude Sonnet 3.5**.
+
+I can help you create delivery orders quickly and efficiently!
+
+---
+
+📋 **To Create an Order, Provide:**
+
+**Required:**
+• Customer Name
+• Delivery Address
+• Contact (Phone OR Email)
+
+**Optional:**
+• Delivery Deadline (default: 6 hours)
+• Priority: standard/express/urgent (default: standard)
+• Special Instructions
+• Package Weight in kg (default: 5.0)
+
+---
+
+**Quick Start Examples:**
+
+✅ *Complete:* "Create order for John Doe, 123 Main St San Francisco CA, phone 555-1234, deliver by 5 PM"
+
+✅ *Partial:* "I need a delivery for Sarah" *(I'll ask for missing details)*
+
+✅ *Natural:* "Urgent package to john@email.com at 456 Market Street"
+
+---
+
+What would you like to do?"""

chat/providers/gemini_provider.py

@@ -0,0 +1,551 @@
+"""
+Google Gemini provider for FleetMind chat
+"""
+
+import os
+import logging
+from typing import Tuple, List, Dict
+import google.generativeai as genai
+from google.generativeai.types import HarmCategory, HarmBlockThreshold
+
+from chat.providers.base_provider import AIProvider
+from chat.tools import execute_tool
+
+logger = logging.getLogger(__name__)
+
+
+class GeminiProvider(AIProvider):
+    """Google Gemini AI provider"""
+
+    def __init__(self):
+        self.api_key = os.getenv("GOOGLE_API_KEY", "")
+        self.api_available = bool(self.api_key and not self.api_key.startswith("your_"))
+        self.model_name = "gemini-2.0-flash"
+        self.model = None
+        self._initialized = False
+
+        if not self.api_available:
+            logger.warning("GeminiProvider: GOOGLE_API_KEY not configured")
+        else:
+            logger.info("GeminiProvider: Ready (will initialize on first use)")
+
+    def _get_system_prompt(self) -> str:
+        """Get the system prompt for Gemini"""
+        return """You are an AI assistant for FleetMind, a delivery dispatch system.
+
+**🚨 CRITICAL RULES - READ CAREFULLY:**
+
+1. **NEVER return text in the middle of tool calls**
+   - If you need to call multiple tools, call them ALL in sequence
+   - Only return text AFTER all tools are complete
+
+2. **Order Creation MUST be a single automated flow:**
+   - Step 1: Call geocode_address (get coordinates)
+   - Step 2: IMMEDIATELY call create_order (save to database)
+   - Step 3: ONLY THEN return success message
+   - DO NOT stop between Step 1 and Step 2
+   - DO NOT say "Now creating order..." - just DO it!
+
+3. **Driver Creation is a SINGLE tool call:**
+   - When user wants to create a driver, call create_driver immediately
+   - NO geocoding needed for drivers
+   - Just call create_driver → confirm
+
+4. **If user provides required info, START IMMEDIATELY:**
+   - For Orders: Customer name, address, contact (phone OR email)
+   - For Drivers: Driver name (phone/email optional)
+   - If all present → execute → confirm
+   - If missing → ask ONCE for all missing fields
+
+**Example of CORRECT behavior:**
+
+ORDER:
+User: "Create order for John Doe, 123 Main St SF, phone 555-1234"
+You: [geocode_address] → [create_order] → "✅ Order ORD-123 created!"
+(ALL in one response, no intermediate text)
+
+DRIVER:
+User: "Add new driver Mike Johnson, phone 555-0101, drives a van"
+You: [create_driver] → "✅ Driver DRV-123 (Mike Johnson) added to fleet!"
+(Single tool call, immediate response)
+
+**Example of WRONG behavior (DO NOT DO THIS):**
+User: "Create order for John Doe..."
+You: [geocode_address] → "OK geocoded, now creating..." ❌ WRONG!
+
+**Available Tools:**
+- geocode_address: Convert address to GPS coordinates
+- create_order: Create customer delivery order (REQUIRES geocoded address)
+- create_driver: Add new driver/delivery man to fleet
+
+**Order Fields:**
+Required: customer_name, delivery_address, contact
+Optional: time_window_end, priority (standard/express/urgent), special_instructions, weight_kg
+
+**Driver Fields:**
+Required: name
+Optional: phone, email, vehicle_type (van/truck/car/motorcycle), vehicle_plate, capacity_kg, capacity_m3, skills (list), status (active/busy/offline)
+
+**Your goal:** Execute tasks in ONE smooth automated flow. No stopping, no intermediate messages!"""
+
+    def _get_gemini_tools(self) -> list:
+        """Convert tool schemas to Gemini function calling format"""
+        # Gemini expects tools wrapped in function_declarations
+        return [
+            genai.protos.Tool(
+                function_declarations=[
+                    genai.protos.FunctionDeclaration(
+                        name="geocode_address",
+                        description="Convert a delivery address to GPS coordinates and validate the address format. Use this before creating an order to ensure the address is valid.",
+                        parameters=genai.protos.Schema(
+                            type=genai.protos.Type.OBJECT,
+                            properties={
+                                "address": genai.protos.Schema(
+                                    type=genai.protos.Type.STRING,
+                                    description="The full delivery address to geocode (e.g., '123 Main St, San Francisco, CA')"
+                                )
+                            },
+                            required=["address"]
+                        )
+                    ),
+                    genai.protos.FunctionDeclaration(
+                        name="create_order",
+                        description="Create a new delivery order in the database. Only call this after geocoding the address successfully.",
+                        parameters=genai.protos.Schema(
+                            type=genai.protos.Type.OBJECT,
+                            properties={
+                                "customer_name": genai.protos.Schema(
+                                    type=genai.protos.Type.STRING,
+                                    description="Full name of the customer"
+                                ),
+                                "customer_phone": genai.protos.Schema(
+                                    type=genai.protos.Type.STRING,
+                                    description="Customer phone number (optional)"
+                                ),
+                                "customer_email": genai.protos.Schema(
+                                    type=genai.protos.Type.STRING,
+                                    description="Customer email address (optional)"
+                                ),
+                                "delivery_address": genai.protos.Schema(
+                                    type=genai.protos.Type.STRING,
+                                    description="Full delivery address"
+                                ),
+                                "delivery_lat": genai.protos.Schema(
+                                    type=genai.protos.Type.NUMBER,
+                                    description="Latitude from geocoding"
+                                ),
+                                "delivery_lng": genai.protos.Schema(
+                                    type=genai.protos.Type.NUMBER,
+                                    description="Longitude from geocoding"
+                                ),
+                                "time_window_end": genai.protos.Schema(
+                                    type=genai.protos.Type.STRING,
+                                    description="Delivery deadline in ISO format (e.g., '2025-11-13T17:00:00'). If not specified by user, default to 6 hours from now."
+                                ),
+                                "priority": genai.protos.Schema(
+                                    type=genai.protos.Type.STRING,
+                                    description="Delivery priority. Default to 'standard' unless user specifies urgent/express."
+                                ),
+                                "special_instructions": genai.protos.Schema(
+                                    type=genai.protos.Type.STRING,
+                                    description="Any special delivery instructions (optional)"
+                                ),
+                                "weight_kg": genai.protos.Schema(
+                                    type=genai.protos.Type.NUMBER,
+                                    description="Package weight in kilograms (optional, default to 5.0)"
+                                )
+                            },
+                            required=["customer_name", "delivery_address", "delivery_lat", "delivery_lng"]
+                        )
+                    ),
+                    genai.protos.FunctionDeclaration(
+                        name="create_driver",
+                        description="Create a new delivery driver/delivery man in the database. Use this to onboard new drivers to the fleet.",
+                        parameters=genai.protos.Schema(
+                            type=genai.protos.Type.OBJECT,
+                            properties={
+                                "name": genai.protos.Schema(
+                                    type=genai.protos.Type.STRING,
+                                    description="Full name of the driver"
+                                ),
+                                "phone": genai.protos.Schema(
+                                    type=genai.protos.Type.STRING,
+                                    description="Driver phone number"
+                                ),
+                                "email": genai.protos.Schema(
+                                    type=genai.protos.Type.STRING,
+                                    description="Driver email address (optional)"
+                                ),
+                                "vehicle_type": genai.protos.Schema(
+                                    type=genai.protos.Type.STRING,
+                                    description="Type of vehicle: van, truck, car, motorcycle (default: van)"
+                                ),
+                                "vehicle_plate": genai.protos.Schema(
+                                    type=genai.protos.Type.STRING,
+                                    description="Vehicle license plate number"
+                                ),
+                                "capacity_kg": genai.protos.Schema(
+                                    type=genai.protos.Type.NUMBER,
+                                    description="Vehicle cargo capacity in kilograms (default: 1000.0)"
+                                ),
+                                "capacity_m3": genai.protos.Schema(
+                                    type=genai.protos.Type.NUMBER,
+                                    description="Vehicle cargo volume in cubic meters (default: 12.0)"
+                                ),
+                                "skills": genai.protos.Schema(
+                                    type=genai.protos.Type.ARRAY,
+                                    description="List of driver skills/certifications: refrigerated, medical_certified, fragile_handler, overnight, express_delivery",
+                                    items=genai.protos.Schema(type=genai.protos.Type.STRING)
+                                ),
+                                "status": genai.protos.Schema(
+                                    type=genai.protos.Type.STRING,
+                                    description="Driver status: active, busy, offline, unavailable (default: active)"
+                                )
+                            },
+                            required=["name"]
+                        )
+                    )
+                ]
+            )
+        ]
+
+    def _ensure_initialized(self):
+        """Lazy initialization - only create model when first needed"""
+        if self._initialized or not self.api_available:
+            return
+
+        try:
+            genai.configure(api_key=self.api_key)
+            self.model = genai.GenerativeModel(
+                model_name=self.model_name,
+                tools=self._get_gemini_tools(),
+                system_instruction=self._get_system_prompt()
+            )
+            self._initialized = True
+            logger.info(f"GeminiProvider: Model initialized ({self.model_name})")
+        except Exception as e:
+            logger.error(f"GeminiProvider: Failed to initialize: {e}")
+            self.api_available = False
+            self.model = None
+
+    def is_available(self) -> bool:
+        return self.api_available
+
+    def get_status(self) -> str:
+        if self.api_available:
+            return f"✅ Connected - Model: {self.model_name}"
+        return "⚠️ Not configured (add GOOGLE_API_KEY)"
+
+    def get_provider_name(self) -> str:
+        return "Gemini (Google)"
+
+    def get_model_name(self) -> str:
+        return self.model_name if self.api_available else "gemini-2.0-flash"
+
+    def process_message(
+        self,
+        user_message: str,
+        conversation
+    ) -> Tuple[str, List[Dict]]:
+        """Process user message with Gemini"""
+        if not self.api_available:
+            return self._handle_no_api(), []
+
+        # Lazy initialization on first use
+        self._ensure_initialized()
+
+        if not self._initialized:
+            return "⚠️ Failed to initialize Gemini model. Please check your API key and try again.", []
+
+        try:
+            # Build conversation history for Gemini
+            chat = self.model.start_chat(history=self._convert_history(conversation))
+
+            # Send message and get response
+            response = chat.send_message(
+                user_message,
+                safety_settings={
+                    HarmCategory.HARM_CATEGORY_HATE_SPEECH: HarmBlockThreshold.BLOCK_NONE,
+                    HarmCategory.HARM_CATEGORY_HARASSMENT: HarmBlockThreshold.BLOCK_NONE,
+                    HarmCategory.HARM_CATEGORY_SEXUALLY_EXPLICIT: HarmBlockThreshold.BLOCK_NONE,
+                    HarmCategory.HARM_CATEGORY_DANGEROUS_CONTENT: HarmBlockThreshold.BLOCK_NONE,
+                }
+            )
+
+            # Add user message to conversation
+            conversation.add_message("user", user_message)
+
+            # Process response and handle function calls
+            return self._process_response(response, conversation, chat)
+
+        except Exception as e:
+            error_msg = f"⚠️ Gemini API error: {str(e)}"
+            logger.error(f"Gemini provider error: {e}")
+            return error_msg, []
+
+    def _convert_history(self, conversation) -> list:
+        """Convert conversation history to Gemini format"""
+        history = []
+        # Get all messages from conversation (history is built before adding current message)
+        for msg in conversation.get_history():
+            role = "user" if msg["role"] == "user" else "model"
+            history.append({
+                "role": role,
+                "parts": [{"text": str(msg["content"])}]
+            })
+        return history
+
+    def _process_response(
+        self,
+        response,
+        conversation,
+        chat
+    ) -> Tuple[str, List[Dict]]:
+        """Process Gemini's response and handle function calls"""
+        tool_calls_made = []
+
+        # Check if Gemini wants to call functions
+        try:
+            # Check ALL parts for function calls (not just first)
+            has_function_call = False
+            parts = response.candidates[0].content.parts
+            logger.info(f"Processing response with {len(parts)} part(s)")
+
+            for part in parts:
+                if hasattr(part, 'function_call'):
+                    fc = part.function_call
+                    # More robust check
+                    if fc is not None:
+                        try:
+                            if hasattr(fc, 'name') and fc.name:
+                                has_function_call = True
+                                logger.info(f"Detected function call: {fc.name}")
+                                break
+                        except Exception as e:
+                            logger.warning(f"Error checking function call: {e}")
+
+            if has_function_call:
+                # Handle function calls (potentially multiple in sequence)
+                current_response = response
+                max_iterations = 10  # Allow more iterations for complex tasks
+
+                for iteration in range(max_iterations):
+                    # Check if current response has a function call
+                    try:
+                        parts = current_response.candidates[0].content.parts
+                        logger.info(f"Iteration {iteration + 1}: Response has {len(parts)} part(s)")
+                    except (IndexError, AttributeError) as e:
+                        logger.error(f"Cannot access response parts: {e}")
+                        break
+
+                    # Check ALL parts for function calls (some responses have text + function_call)
+                    has_fc = False
+                    fc_part = None
+
+                    for idx, part in enumerate(parts):
+                        if hasattr(part, 'function_call'):
+                            fc = part.function_call
+                            if fc and hasattr(fc, 'name') and fc.name:
+                                has_fc = True
+                                fc_part = part
+                                logger.info(f"Iteration {iteration + 1}: Found function_call in part {idx}: {fc.name}")
+                                break
+
+                        # Also check if there's text (indicates Gemini wants to respond instead of continuing)
+                        if hasattr(part, 'text') and part.text:
+                            logger.warning(f"Iteration {iteration + 1}: Part {idx} has text: {part.text[:100]}")
+
+                    if not has_fc:
+                        # No more function calls, break and extract text
+                        logger.info(f"No more function calls after iteration {iteration + 1}")
+                        break
+
+                    # Use the part with function_call
+                    first_part = fc_part
+
+                    # Extract function call details
+                    function_call = first_part.function_call
+                    function_name = function_call.name
+                    function_args = dict(function_call.args) if function_call.args else {}
+
+                    logger.info(f"Gemini executing function: {function_name} (iteration {iteration + 1})")
+
+                    # Execute the tool
+                    tool_result = execute_tool(function_name, function_args)
+
+                    # Track for transparency
+                    tool_calls_made.append({
+                        "tool": function_name,
+                        "input": function_args,
+                        "result": tool_result
+                    })
+
+                    conversation.add_tool_result(function_name, function_args, tool_result)
+
+                    # Send function result back to Gemini
+                    try:
+                        current_response = chat.send_message(
+                            genai.protos.Content(
+                                parts=[genai.protos.Part(
+                                    function_response=genai.protos.FunctionResponse(
+                                        name=function_name,
+                                        response={"result": tool_result}
+                                    )
+                                )]
+                            )
+                        )
+                    except Exception as e:
+                        logger.error(f"Error sending function response: {e}")
+                        break
+
+                # Now extract text from the final response
+                # NEVER use .text property directly - always check parts
+                final_text = ""
+                try:
+                    parts = current_response.candidates[0].content.parts
+                    logger.info(f"Extracting text from {len(parts)} parts")
+
+                    for idx, part in enumerate(parts):
+                        # Check if this part has a function call
+                        if hasattr(part, 'function_call') and part.function_call:
+                            fc = part.function_call
+                            if hasattr(fc, 'name') and fc.name:
+                                logger.warning(f"Part {idx} still has function call: {fc.name}. Skipping.")
+                                continue
+
+                        # Extract text from this part
+                        if hasattr(part, 'text') and part.text:
+                            logger.info(f"Part {idx} has text: {part.text[:50]}...")
+                            final_text += part.text
+
+                except (AttributeError, IndexError) as e:
+                    logger.error(f"Error extracting text from parts: {e}")
+
+                # Generate fallback message if still no text
+                if not final_text:
+                    logger.warning("No text extracted from response, generating fallback")
+                    if tool_calls_made:
+                        # Create a summary of what was done
+                        tool_names = [t["tool"] for t in tool_calls_made]
+                        if "create_order" in tool_names:
+                            # Check if order was created successfully
+                            create_result = next((t["result"] for t in tool_calls_made if t["tool"] == "create_order"), {})
+                            if create_result.get("success"):
+                                order_id = create_result.get("order_id", "")
+                                final_text = f"✅ Order {order_id} created successfully!"
+                            else:
+                                final_text = "⚠️ There was an issue creating the order."
+                        else:
+                            final_text = f"✅ Executed {len(tool_calls_made)} tool(s) successfully!"
+                    else:
+                        final_text = "✅ Task completed!"
+
+                logger.info(f"Returning response: {final_text[:100]}")
+                conversation.add_message("assistant", final_text)
+                return final_text, tool_calls_made
+
+            else:
+                # No function call detected, extract text from parts
+                text_response = ""
+                try:
+                    parts = response.candidates[0].content.parts
+                    logger.info(f"Extracting text from {len(parts)} parts (no function call)")
+
+                    for idx, part in enumerate(parts):
+                        # Double-check no function call in this part
+                        if hasattr(part, 'function_call') and part.function_call:
+                            fc = part.function_call
+                            if hasattr(fc, 'name') and fc.name:
+                                logger.error(f"Part {idx} has function call {fc.name} but was not detected earlier!")
+                                # We missed a function call - handle it now
+                                logger.info("Re-processing response with function call handling")
+                                return self._process_response(response, conversation, chat)
+
+                        # Extract text
+                        if hasattr(part, 'text') and part.text:
+                            logger.info(f"Part {idx} has text: {part.text[:50]}...")
+                            text_response += part.text
+
+                except (ValueError, AttributeError, IndexError) as e:
+                    logger.error(f"Error extracting text from response: {e}")
+
+                # Fallback if no text extracted
+                if not text_response:
+                    logger.warning("No text in response, using fallback")
+                    text_response = "I'm ready to help! What would you like me to do?"
+
+                conversation.add_message("assistant", text_response)
+                return text_response, tool_calls_made
+
+        except Exception as e:
+            logger.error(f"Error processing Gemini response: {e}")
+            error_msg = f"⚠️ Error processing response: {str(e)}"
+            conversation.add_message("assistant", error_msg)
+            return error_msg, tool_calls_made
+
+    def _handle_no_api(self) -> str:
+        """Return error message when API is not available"""
+        return """⚠️ **Gemini API requires Google API key**
+
+To use Gemini:
+
+1. Get an API key from: https://aistudio.google.com/app/apikey
+   - Free tier: 15 requests/min, 1500/day
+   - Or use hackathon credits
+
+2. Add to your `.env` file:
+   ```
+   GOOGLE_API_KEY=your-gemini-key-here
+   ```
+
+3. Restart the application
+
+**Alternative:** Switch to Claude by setting `AI_PROVIDER=anthropic` in .env
+"""
+
+    def get_welcome_message(self) -> str:
+        if not self.api_available:
+            return self._handle_no_api()
+
+        # Initialize on first use (welcome message)
+        self._ensure_initialized()
+
+        return """👋 Hello! I'm your AI dispatch assistant powered by **Google Gemini 2.0 Flash**.
+
+I can help you manage your delivery fleet!
+
+---
+
+📋 **What I Can Do:**
+
+**1. Create Delivery Orders:**
+• Customer Name
+• Delivery Address
+• Contact (Phone OR Email)
+• Optional: Deadline, Priority, Special Instructions
+
+**2. Add New Drivers:**
+• Driver Name (required)
+• Optional: Phone, Email, Vehicle Type, License Plate, Skills
+
+---
+
+**Examples - Just Type Naturally:**
+
+📦 **Orders:**
+💬 "Create order for John Doe, 123 Main St San Francisco CA, phone 555-1234, deliver by 5 PM"
+💬 "New urgent delivery to Sarah at 456 Oak Ave NYC, email sarah@email.com"
+
+🚚 **Drivers:**
+💬 "Add new driver Tom Wilson, phone 555-0101, drives a van, plate ABC-123"
+💬 "Create driver Sarah Martinez with refrigerated truck, phone 555-0202"
+💬 "New driver: Mike Chen, email mike@fleet.com, motorcycle delivery"
+
+---
+
+🚀 **I'll automatically:**
+• Geocode addresses for orders
+• Generate unique IDs
+• Save everything to the database
+
+What would you like to do?"""

chat/tools.py

@@ -0,0 +1,350 @@
+"""
+Tool definitions and execution handlers for FleetMind chat
+Simulates MCP tools using Claude's tool calling feature
+"""
+
+import sys
+from pathlib import Path
+from datetime import datetime, timedelta
+import logging
+
+# Add parent directory to path
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+from database.connection import execute_write
+from chat.geocoding import GeocodingService
+
+logger = logging.getLogger(__name__)
+
+# Initialize geocoding service
+geocoding_service = GeocodingService()
+
+# Tool schemas for Claude
+TOOLS_SCHEMA = [
+    {
+        "name": "geocode_address",
+        "description": "Convert a delivery address to GPS coordinates and validate the address format. Use this before creating an order to ensure the address is valid.",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "address": {
+                    "type": "string",
+                    "description": "The full delivery address to geocode (e.g., '123 Main St, San Francisco, CA')"
+                }
+            },
+            "required": ["address"]
+        }
+    },
+    {
+        "name": "create_order",
+        "description": "Create a new delivery order in the database. Only call this after geocoding the address successfully.",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "customer_name": {
+                    "type": "string",
+                    "description": "Full name of the customer"
+                },
+                "customer_phone": {
+                    "type": "string",
+                    "description": "Customer phone number (optional)"
+                },
+                "customer_email": {
+                    "type": "string",
+                    "description": "Customer email address (optional)"
+                },
+                "delivery_address": {
+                    "type": "string",
+                    "description": "Full delivery address"
+                },
+                "delivery_lat": {
+                    "type": "number",
+                    "description": "Latitude from geocoding"
+                },
+                "delivery_lng": {
+                    "type": "number",
+                    "description": "Longitude from geocoding"
+                },
+                "time_window_end": {
+                    "type": "string",
+                    "description": "Delivery deadline in ISO format (e.g., '2025-11-13T17:00:00'). If not specified by user, default to 6 hours from now."
+                },
+                "priority": {
+                    "type": "string",
+                    "enum": ["standard", "express", "urgent"],
+                    "description": "Delivery priority. Default to 'standard' unless user specifies urgent/express."
+                },
+                "special_instructions": {
+                    "type": "string",
+                    "description": "Any special delivery instructions (optional)"
+                },
+                "weight_kg": {
+                    "type": "number",
+                    "description": "Package weight in kilograms (optional, default to 5.0)"
+                }
+            },
+            "required": ["customer_name", "delivery_address", "delivery_lat", "delivery_lng"]
+        }
+    }
+]
+
+
+def execute_tool(tool_name: str, tool_input: dict) -> dict:
+    """
+    Route tool execution to appropriate handler
+
+    Args:
+        tool_name: Name of the tool to execute
+        tool_input: Tool input parameters
+
+    Returns:
+        Dict with tool execution results
+    """
+    try:
+        if tool_name == "geocode_address":
+            return handle_geocode_address(tool_input)
+        elif tool_name == "create_order":
+            return handle_create_order(tool_input)
+        elif tool_name == "create_driver":
+            return handle_create_driver(tool_input)
+        else:
+            return {
+                "success": False,
+                "error": f"Unknown tool: {tool_name}"
+            }
+    except Exception as e:
+        logger.error(f"Tool execution error ({tool_name}): {e}")
+        return {
+            "success": False,
+            "error": str(e)
+        }
+
+
+def handle_geocode_address(tool_input: dict) -> dict:
+    """
+    Execute geocoding tool
+
+    Args:
+        tool_input: Dict with 'address' key
+
+    Returns:
+        Geocoding result
+    """
+    address = tool_input.get("address", "")
+
+    if not address:
+        return {
+            "success": False,
+            "error": "Address is required"
+        }
+
+    logger.info(f"Geocoding address: {address}")
+
+    result = geocoding_service.geocode(address)
+
+    return {
+        "success": True,
+        "latitude": result["lat"],
+        "longitude": result["lng"],
+        "formatted_address": result["formatted_address"],
+        "confidence": result["confidence"],
+        "message": f"Address geocoded successfully ({result['confidence']})"
+    }
+
+
+def handle_create_order(tool_input: dict) -> dict:
+    """
+    Execute order creation tool
+
+    Args:
+        tool_input: Dict with order fields
+
+    Returns:
+        Order creation result
+    """
+    # Extract fields with defaults
+    customer_name = tool_input.get("customer_name")
+    customer_phone = tool_input.get("customer_phone")
+    customer_email = tool_input.get("customer_email")
+    delivery_address = tool_input.get("delivery_address")
+    delivery_lat = tool_input.get("delivery_lat")
+    delivery_lng = tool_input.get("delivery_lng")
+    priority = tool_input.get("priority", "standard")
+    special_instructions = tool_input.get("special_instructions")
+    weight_kg = tool_input.get("weight_kg", 5.0)
+
+    # Validate required fields
+    if not all([customer_name, delivery_address, delivery_lat, delivery_lng]):
+        return {
+            "success": False,
+            "error": "Missing required fields: customer_name, delivery_address, delivery_lat, delivery_lng"
+        }
+
+    # Generate order ID
+    now = datetime.now()
+    order_id = f"ORD-{now.strftime('%Y%m%d%H%M%S')}"
+
+    # Handle time window
+    time_window_end_str = tool_input.get("time_window_end")
+    if time_window_end_str:
+        try:
+            time_window_end = datetime.fromisoformat(time_window_end_str.replace('Z', '+00:00'))
+        except:
+            time_window_end = now + timedelta(hours=6)
+    else:
+        time_window_end = now + timedelta(hours=6)
+
+    time_window_start = now + timedelta(hours=2)
+
+    # Insert into database
+    query = """
+        INSERT INTO orders (
+            order_id, customer_name, customer_phone, customer_email,
+            delivery_address, delivery_lat, delivery_lng,
+            time_window_start, time_window_end,
+            priority, weight_kg, status, special_instructions
+        ) VALUES (%s, %s, %s, %s, %s, %s, %s, %s, %s, %s, %s, %s, %s)
+    """
+
+    params = (
+        order_id,
+        customer_name,
+        customer_phone,
+        customer_email,
+        delivery_address,
+        delivery_lat,
+        delivery_lng,
+        time_window_start,
+        time_window_end,
+        priority,
+        weight_kg,
+        "pending",
+        special_instructions
+    )
+
+    try:
+        execute_write(query, params)
+        logger.info(f"Order created: {order_id}")
+
+        return {
+            "success": True,
+            "order_id": order_id,
+            "status": "pending",
+            "customer": customer_name,
+            "address": delivery_address,
+            "deadline": time_window_end.strftime("%Y-%m-%d %H:%M"),
+            "priority": priority,
+            "message": f"Order {order_id} created successfully!"
+        }
+    except Exception as e:
+        logger.error(f"Database error creating order: {e}")
+        return {
+            "success": False,
+            "error": f"Failed to create order: {str(e)}"
+        }
+
+
+def handle_create_driver(tool_input: dict) -> dict:
+    """
+    Execute driver creation tool
+
+    Args:
+        tool_input: Dict with driver fields
+
+    Returns:
+        Driver creation result
+    """
+    # Extract fields with defaults
+    name = tool_input.get("name")
+    phone = tool_input.get("phone")
+    email = tool_input.get("email")
+    vehicle_type = tool_input.get("vehicle_type", "van")
+    vehicle_plate = tool_input.get("vehicle_plate")
+    capacity_kg = tool_input.get("capacity_kg", 1000.0)
+    capacity_m3 = tool_input.get("capacity_m3", 12.0)
+
+    # Convert skills to regular list (handles protobuf RepeatedComposite)
+    skills_raw = tool_input.get("skills", [])
+    skills = list(skills_raw) if skills_raw else []
+
+    status = tool_input.get("status", "active")
+
+    # Validate required fields
+    if not name:
+        return {
+            "success": False,
+            "error": "Missing required field: name"
+        }
+
+    # Generate driver ID
+    now = datetime.now()
+    driver_id = f"DRV-{now.strftime('%Y%m%d%H%M%S')}"
+
+    # Default location (San Francisco)
+    current_lat = tool_input.get("current_lat", 37.7749)
+    current_lng = tool_input.get("current_lng", -122.4194)
+
+    # Insert into database
+    query = """
+        INSERT INTO drivers (
+            driver_id, name, phone, email,
+            current_lat, current_lng, last_location_update,
+            status, vehicle_type, vehicle_plate,
+            capacity_kg, capacity_m3, skills
+        ) VALUES (%s, %s, %s, %s, %s, %s, %s, %s, %s, %s, %s, %s, %s)
+    """
+
+    # Convert skills list to JSON
+    import json
+    skills_json = json.dumps(skills) if skills else json.dumps([])
+
+    params = (
+        driver_id,
+        name,
+        phone,
+        email,
+        current_lat,
+        current_lng,
+        now,
+        status,
+        vehicle_type,
+        vehicle_plate,
+        capacity_kg,
+        capacity_m3,
+        skills_json
+    )
+
+    try:
+        execute_write(query, params)
+        logger.info(f"Driver created: {driver_id}")
+
+        return {
+            "success": True,
+            "driver_id": driver_id,
+            "name": name,
+            "status": status,
+            "vehicle_type": vehicle_type,
+            "vehicle_plate": vehicle_plate,
+            "capacity_kg": capacity_kg,
+            "skills": skills,
+            "message": f"Driver {driver_id} ({name}) created successfully!"
+        }
+    except Exception as e:
+        logger.error(f"Database error creating driver: {e}")
+        return {
+            "success": False,
+            "error": f"Failed to create driver: {str(e)}"
+        }
+
+
+def get_tools_list() -> list:
+    """Get list of available tools"""
+    return [tool["name"] for tool in TOOLS_SCHEMA]
+
+
+def get_tool_description(tool_name: str) -> str:
+    """Get description for a specific tool"""
+    for tool in TOOLS_SCHEMA:
+        if tool["name"] == tool_name:
+            return tool["description"]
+    return ""

database/__init__.py

@@ -0,0 +1,8 @@
+"""
+Database package for FleetMind MCP
+Handles all database connections and operations
+"""
+
+from .connection import get_db_connection, init_database
+
+__all__ = ['get_db_connection', 'init_database']

database/connection.py

@@ -0,0 +1,219 @@
+"""
+Database connection module for FleetMind
+Handles PostgreSQL database connections and initialization
+"""
+
+import psycopg2
+import psycopg2.extras
+import os
+from typing import Optional, List, Dict, Any
+from pathlib import Path
+import logging
+from dotenv import load_dotenv
+
+# Load environment variables
+load_dotenv()
+
+# Set up logging
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+# Database configuration from environment variables
+DB_CONFIG = {
+    'host': os.getenv('DB_HOST', 'localhost'),
+    'port': os.getenv('DB_PORT', '5432'),
+    'database': os.getenv('DB_NAME', 'fleetmind'),
+    'user': os.getenv('DB_USER', 'postgres'),
+    'password': os.getenv('DB_PASSWORD', ''),
+}
+
+
+def get_db_connection() -> psycopg2.extensions.connection:
+    """
+    Create and return a PostgreSQL database connection.
+
+    Returns:
+        psycopg2.connection: Database connection object
+
+    Raises:
+        psycopg2.Error: If connection fails
+    """
+    try:
+        conn = psycopg2.connect(
+            host=DB_CONFIG['host'],
+            port=DB_CONFIG['port'],
+            database=DB_CONFIG['database'],
+            user=DB_CONFIG['user'],
+            password=DB_CONFIG['password'],
+            cursor_factory=psycopg2.extras.RealDictCursor
+        )
+
+        logger.info(f"Database connection established: {DB_CONFIG['database']}@{DB_CONFIG['host']}")
+        return conn
+
+    except psycopg2.Error as e:
+        logger.error(f"Database connection error: {e}")
+        raise
+
+
+def init_database(schema_file: Optional[str] = None) -> None:
+    """
+    Initialize the database with schema.
+
+    Args:
+        schema_file: Path to SQL schema file. If None, uses default schema.
+
+    Raises:
+        psycopg2.Error: If initialization fails
+    """
+    try:
+        conn = get_db_connection()
+        cursor = conn.cursor()
+
+        if schema_file and os.path.exists(schema_file):
+            # Read and execute schema from file
+            with open(schema_file, 'r') as f:
+                schema_sql = f.read()
+            cursor.execute(schema_sql)
+            logger.info(f"Database initialized from schema file: {schema_file}")
+        else:
+            # Use default schema
+            from .schema import SCHEMA_SQL
+            cursor.execute(SCHEMA_SQL)
+            logger.info("Database initialized with default schema")
+
+        conn.commit()
+        cursor.close()
+        conn.close()
+
+        logger.info("Database initialization completed successfully")
+
+    except psycopg2.Error as e:
+        logger.error(f"Database initialization error: {e}")
+        if conn:
+            conn.rollback()
+        raise
+
+
+def close_connection(conn: psycopg2.extensions.connection) -> None:
+    """
+    Safely close database connection.
+
+    Args:
+        conn: Database connection to close
+    """
+    try:
+        if conn and not conn.closed:
+            conn.close()
+            logger.info("Database connection closed")
+    except psycopg2.Error as e:
+        logger.error(f"Error closing connection: {e}")
+
+
+def execute_query(query: str, params: tuple = ()) -> List[Dict[str, Any]]:
+    """
+    Execute a SELECT query and return results.
+
+    Args:
+        query: SQL query string
+        params: Query parameters tuple
+
+    Returns:
+        list: Query results as list of dictionaries
+
+    Raises:
+        psycopg2.Error: If query fails
+    """
+    conn = get_db_connection()
+    try:
+        cursor = conn.cursor()
+        cursor.execute(query, params)
+        results = cursor.fetchall()
+        cursor.close()
+        return results
+    except psycopg2.Error as e:
+        logger.error(f"Query execution error: {e}")
+        raise
+    finally:
+        close_connection(conn)
+
+
+def execute_write(query: str, params: tuple = ()) -> int:
+    """
+    Execute an INSERT, UPDATE, or DELETE query.
+
+    Args:
+        query: SQL query string
+        params: Query parameters tuple
+
+    Returns:
+        int: Number of rows affected
+
+    Raises:
+        psycopg2.Error: If query fails
+    """
+    conn = get_db_connection()
+    try:
+        cursor = conn.cursor()
+        cursor.execute(query, params)
+        rows_affected = cursor.rowcount
+        conn.commit()
+        cursor.close()
+        return rows_affected
+    except psycopg2.Error as e:
+        conn.rollback()
+        logger.error(f"Write query error: {e}")
+        raise
+    finally:
+        close_connection(conn)
+
+
+def execute_many(query: str, params_list: List[tuple]) -> int:
+    """
+    Execute multiple INSERT/UPDATE queries in a batch.
+
+    Args:
+        query: SQL query string
+        params_list: List of parameter tuples
+
+    Returns:
+        int: Number of rows affected
+
+    Raises:
+        psycopg2.Error: If query fails
+    """
+    conn = get_db_connection()
+    try:
+        cursor = conn.cursor()
+        cursor.executemany(query, params_list)
+        rows_affected = cursor.rowcount
+        conn.commit()
+        cursor.close()
+        return rows_affected
+    except psycopg2.Error as e:
+        conn.rollback()
+        logger.error(f"Batch write error: {e}")
+        raise
+    finally:
+        close_connection(conn)
+
+
+def test_connection() -> bool:
+    """
+    Test database connection.
+
+    Returns:
+        bool: True if connection successful, False otherwise
+    """
+    try:
+        conn = get_db_connection()
+        cursor = conn.cursor()
+        cursor.execute("SELECT version();")
+        version = cursor.fetchone()
+        logger.info(f"PostgreSQL version: {version['version']}")
+        cursor.close()
+        close_connection(conn)
+        return True
+    except Exception as e:
+        logger.error(f"Connection test failed: {e}")
+        return False

database/migrations/001_create_drivers_table.py

@@ -0,0 +1,81 @@
+"""
+Migration: Create drivers table
+Created: 2025-11-14
+"""
+
+import sys
+from pathlib import Path
+
+# Add parent directory to path
+sys.path.insert(0, str(Path(__file__).parent.parent.parent))
+
+from database.connection import get_db_connection
+from database.schema import DRIVERS_SCHEMA
+import logging
+
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+
+def up():
+    """Apply migration - Create drivers table"""
+    logger.info("Starting migration: Create drivers table")
+
+    try:
+        conn = get_db_connection()
+        cursor = conn.cursor()
+
+        # Execute drivers schema
+        logger.info("Creating drivers table...")
+        cursor.execute(DRIVERS_SCHEMA)
+
+        conn.commit()
+        cursor.close()
+        conn.close()
+
+        logger.info("✅ Migration completed successfully: Drivers table created")
+        return True
+
+    except Exception as e:
+        logger.error(f"❌ Migration failed: {e}")
+        if conn:
+            conn.rollback()
+        return False
+
+
+def down():
+    """Rollback migration - Drop drivers table"""
+    logger.info("Rolling back migration: Drop drivers table")
+
+    try:
+        conn = get_db_connection()
+        cursor = conn.cursor()
+
+        logger.info("Dropping drivers table...")
+        cursor.execute("DROP TABLE IF EXISTS drivers CASCADE;")
+
+        conn.commit()
+        cursor.close()
+        conn.close()
+
+        logger.info("✅ Rollback completed successfully: Drivers table dropped")
+        return True
+
+    except Exception as e:
+        logger.error(f"❌ Rollback failed: {e}")
+        if conn:
+            conn.rollback()
+        return False
+
+
+if __name__ == "__main__":
+    import sys
+
+    if len(sys.argv) > 1 and sys.argv[1] == "down":
+        # Rollback
+        success = down()
+    else:
+        # Apply migration
+        success = up()
+
+    sys.exit(0 if success else 1)

database/migrations/__init__.py

@@ -0,0 +1,3 @@
+"""
+Database migrations package
+"""

database/schema.py

@@ -0,0 +1,212 @@
+"""
+Database schema definitions for FleetMind
+Contains PostgreSQL schema for all database tables
+"""
+
+SCHEMA_SQL = """
+-- ============================================
+-- ORDERS TABLE
+-- ============================================
+
+CREATE TABLE IF NOT EXISTS orders (
+    order_id VARCHAR(50) PRIMARY KEY,
+    customer_name VARCHAR(255) NOT NULL,
+    customer_phone VARCHAR(20),
+    customer_email VARCHAR(255),
+    pickup_address TEXT,
+    pickup_lat DECIMAL(10, 8),
+    pickup_lng DECIMAL(11, 8),
+    delivery_address TEXT NOT NULL,
+    delivery_lat DECIMAL(10, 8),
+    delivery_lng DECIMAL(11, 8),
+    time_window_start TIMESTAMP,
+    time_window_end TIMESTAMP,
+    priority VARCHAR(20) CHECK(priority IN ('standard', 'express', 'urgent')) DEFAULT 'standard',
+    weight_kg DECIMAL(10, 2),
+    volume_m3 DECIMAL(10, 3),
+    special_instructions TEXT,
+    status VARCHAR(20) CHECK(status IN ('pending', 'assigned', 'in_transit', 'delivered', 'failed', 'cancelled')) DEFAULT 'pending',
+    assigned_driver_id VARCHAR(50),
+    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+    delivered_at TIMESTAMP,
+
+    -- Additional fields for order management
+    order_value DECIMAL(10, 2),
+    payment_status VARCHAR(20) CHECK(payment_status IN ('pending', 'paid', 'cod')) DEFAULT 'pending',
+    requires_signature BOOLEAN DEFAULT FALSE,
+    is_fragile BOOLEAN DEFAULT FALSE,
+    requires_cold_storage BOOLEAN DEFAULT FALSE
+);
+
+-- ============================================
+-- INDEXES FOR ORDERS TABLE
+-- ============================================
+
+CREATE INDEX IF NOT EXISTS idx_orders_status ON orders(status);
+CREATE INDEX IF NOT EXISTS idx_orders_priority ON orders(priority);
+CREATE INDEX IF NOT EXISTS idx_orders_assigned_driver ON orders(assigned_driver_id);
+CREATE INDEX IF NOT EXISTS idx_orders_created_at ON orders(created_at);
+CREATE INDEX IF NOT EXISTS idx_orders_time_window ON orders(time_window_start, time_window_end);
+
+-- ============================================
+-- TRIGGER TO UPDATE updated_at TIMESTAMP
+-- ============================================
+
+CREATE OR REPLACE FUNCTION update_updated_at_column()
+RETURNS TRIGGER AS $$
+BEGIN
+    NEW.updated_at = CURRENT_TIMESTAMP;
+    RETURN NEW;
+END;
+$$ language 'plpgsql';
+
+DROP TRIGGER IF EXISTS update_orders_timestamp ON orders;
+CREATE TRIGGER update_orders_timestamp
+    BEFORE UPDATE ON orders
+    FOR EACH ROW
+    EXECUTE FUNCTION update_updated_at_column();
+"""
+
+# Additional schema components can be added here as needed
+DRIVERS_SCHEMA = """
+-- ============================================
+-- DRIVERS TABLE
+-- ============================================
+
+CREATE TABLE IF NOT EXISTS drivers (
+    driver_id VARCHAR(50) PRIMARY KEY,
+    name VARCHAR(255) NOT NULL,
+    phone VARCHAR(20),
+    email VARCHAR(255),
+    current_lat DECIMAL(10, 8),
+    current_lng DECIMAL(11, 8),
+    last_location_update TIMESTAMP,
+    status VARCHAR(20) CHECK(status IN ('active', 'busy', 'offline', 'unavailable')) DEFAULT 'active',
+    vehicle_type VARCHAR(50),
+    vehicle_plate VARCHAR(20),
+    capacity_kg DECIMAL(10, 2),
+    capacity_m3 DECIMAL(10, 3),
+    skills JSONB,  -- JSON array: ["medical_certified", "refrigerated"]
+    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE INDEX IF NOT EXISTS idx_drivers_status ON drivers(status);
+
+DROP TRIGGER IF EXISTS update_drivers_timestamp ON drivers;
+CREATE TRIGGER update_drivers_timestamp
+    BEFORE UPDATE ON drivers
+    FOR EACH ROW
+    EXECUTE FUNCTION update_updated_at_column();
+"""
+
+ASSIGNMENTS_SCHEMA = """
+-- ============================================
+-- ASSIGNMENTS TABLE
+-- ============================================
+
+CREATE TABLE IF NOT EXISTS assignments (
+    assignment_id VARCHAR(50) PRIMARY KEY,
+    order_id VARCHAR(50) NOT NULL,
+    driver_id VARCHAR(50) NOT NULL,
+    assigned_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+    sequence_number INTEGER,  -- Order in driver's route
+    estimated_arrival TIMESTAMP,
+    actual_arrival TIMESTAMP,
+    estimated_distance_km DECIMAL(10, 2),
+    actual_distance_km DECIMAL(10, 2),
+    status VARCHAR(20) CHECK(status IN ('assigned', 'in_progress', 'completed', 'failed')) DEFAULT 'assigned',
+    notes TEXT,
+    FOREIGN KEY (order_id) REFERENCES orders(order_id) ON DELETE CASCADE,
+    FOREIGN KEY (driver_id) REFERENCES drivers(driver_id) ON DELETE CASCADE
+);
+
+CREATE INDEX IF NOT EXISTS idx_assignments_driver ON assignments(driver_id);
+CREATE INDEX IF NOT EXISTS idx_assignments_order ON assignments(order_id);
+CREATE INDEX IF NOT EXISTS idx_assignments_status ON assignments(status);
+"""
+
+EXCEPTIONS_SCHEMA = """
+-- ============================================
+-- EXCEPTIONS TABLE
+-- ============================================
+
+CREATE TABLE IF NOT EXISTS exceptions (
+    exception_id VARCHAR(50) PRIMARY KEY,
+    exception_type VARCHAR(50) CHECK(exception_type IN ('driver_breakdown', 'traffic_delay', 'weather', 'customer_unavailable', 'other')),
+    severity VARCHAR(20) CHECK(severity IN ('low', 'medium', 'high', 'critical')),
+    description TEXT,
+    affected_orders JSONB,  -- JSON array of order IDs
+    affected_drivers JSONB,  -- JSON array of driver IDs
+    detected_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+    resolved_at TIMESTAMP,
+    resolution_method JSONB,  -- JSON: {agent: "...", actions: [...]}
+    coordinator_override BOOLEAN DEFAULT FALSE,
+    resolution_time_seconds INTEGER
+);
+
+CREATE INDEX IF NOT EXISTS idx_exceptions_type ON exceptions(exception_type);
+CREATE INDEX IF NOT EXISTS idx_exceptions_severity ON exceptions(severity);
+CREATE INDEX IF NOT EXISTS idx_exceptions_detected_at ON exceptions(detected_at);
+"""
+
+AGENT_DECISIONS_SCHEMA = """
+-- ============================================
+-- AGENT DECISIONS TABLE (For Agent Learning)
+-- ============================================
+
+CREATE TABLE IF NOT EXISTS agent_decisions (
+    decision_id VARCHAR(50) PRIMARY KEY,
+    session_id VARCHAR(50),
+    task_type VARCHAR(50),
+    situation_context JSONB,  -- JSON
+    options_generated JSONB,  -- JSON array
+    selected_option JSONB,  -- JSON
+    reasoning TEXT,
+    approval_status VARCHAR(20) CHECK(approval_status IN ('approved', 'rejected', 'modified')),
+    coordinator_feedback TEXT,
+    outcome_success BOOLEAN,
+    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE INDEX IF NOT EXISTS idx_decisions_session ON agent_decisions(session_id);
+CREATE INDEX IF NOT EXISTS idx_decisions_task_type ON agent_decisions(task_type);
+"""
+
+METRICS_SCHEMA = """
+-- ============================================
+-- PERFORMANCE METRICS TABLE
+-- ============================================
+
+CREATE TABLE IF NOT EXISTS metrics (
+    metric_id VARCHAR(50) PRIMARY KEY,
+    date DATE,
+    total_orders INTEGER,
+    on_time_deliveries INTEGER,
+    failed_deliveries INTEGER,
+    exceptions_count INTEGER,
+    avg_resolution_time_seconds DECIMAL(10, 2),
+    coordinator_time_saved_minutes INTEGER,
+    fuel_cost_savings DECIMAL(10, 2)
+);
+
+CREATE INDEX IF NOT EXISTS idx_metrics_date ON metrics(date);
+"""
+
+
+def get_full_schema() -> str:
+    """
+    Get the complete database schema including all tables.
+
+    Returns:
+        str: Complete SQL schema
+    """
+    return (
+        SCHEMA_SQL + "\n" +
+        DRIVERS_SCHEMA + "\n" +
+        ASSIGNMENTS_SCHEMA + "\n" +
+        EXCEPTIONS_SCHEMA + "\n" +
+        AGENT_DECISIONS_SCHEMA + "\n" +
+        METRICS_SCHEMA
+    )

flow.md

@@ -0,0 +1,828 @@
+● 🔄 Complete Function Flow
+
+  Input: "Create an order for John Doe at 123 Main St, San 
+  Francisco"
+
+  Let me trace every single function call with this exact example!      
+
+  ---
+  📞 FUNCTION CALL SEQUENCE:
+
+  STEP 1: User Clicks Send Button
+
+  FILE: ui/app.py
+  LINE: 448-452
+
+  User clicks "Send" button in Gradio UI
+      ↓
+  FUNCTION CALLED: send_message(message, conv_state)
+      message = "Create an order for John Doe at 123 Main St, San       
+  Francisco"
+      conv_state = ConversationManager object
+
+  Function Code:
+  def send_message(message, conv_state):
+      """Handle send button click"""
+      chat_history, tools, new_state = handle_chat_message(message,     
+  conv_state)
+      #                                 ↑
+      #                                 CALLS THIS NEXT
+      return chat_history, tools, new_state, ""
+
+  ---
+  STEP 2: handle_chat_message()
+
+  FILE: ui/app.py
+  LINE: 223-241
+
+  FUNCTION: handle_chat_message(message, conversation_state)
+      message = "Create an order for John Doe at 123 Main St, San       
+  Francisco"
+      conversation_state = ConversationManager object
+
+  Function Code:
+  def handle_chat_message(message, conversation_state):
+      if not message.strip():
+          return ...
+
+      # Process message through chat engine
+      response, tool_calls = chat_engine.process_message(message,       
+  conversation_state)
+      #                      ↑
+      #                      CALLS THIS NEXT
+
+      # Return updated UI
+      return conversation_state.get_formatted_history(),
+  conversation_state.get_tool_calls(), conversation_state
+
+  ---
+  STEP 3: chat_engine.process_message()
+
+  FILE: chat/chat_engine.py
+  LINE: 58-73
+
+  FUNCTION: ChatEngine.process_message(user_message, conversation)      
+      user_message = "Create an order for John Doe at 123 Main St,      
+  San Francisco"
+      conversation = ConversationManager object
+
+  Function Code:
+  def process_message(self, user_message, conversation):
+      """Process user message and return AI response"""
+      return self.provider.process_message(user_message,
+  conversation)
+      #      ↑
+      #      self.provider = GeminiProvider (from chat_engine.py:26)    
+      #      CALLS GeminiProvider.process_message() NEXT
+
+  ---
+  STEP 4: GeminiProvider.process_message()
+
+  FILE: chat/providers/gemini_provider.py
+  LINE: 173-212
+
+  FUNCTION: GeminiProvider.process_message(user_message,
+  conversation)
+      user_message = "Create an order for John Doe at 123 Main St,      
+  San Francisco"
+      conversation = ConversationManager object
+
+  Function Code:
+  def process_message(self, user_message, conversation):
+      """Process user message with Gemini"""
+      if not self.api_available:
+          return self._handle_no_api(), []
+
+      # Lazy initialization on first use
+      self._ensure_initialized()  # ← CALLS THIS if not initialized     
+
+      if not self._initialized:
+          return "⚠️ Failed to initialize...", []
+
+      try:
+          # Build conversation history for Gemini
+          chat =
+  self.model.start_chat(history=self._convert_history(conversation))    
+          #                                      ↑
+          #                                      CALLS
+  _convert_history()
+
+          # Send message and get response
+          response = chat.send_message(user_message,
+  safety_settings={...})
+          #          ↑
+          #          🌐 API CALL TO GOOGLE GEMINI
+          #          Sends: "Create an order for John Doe at 123        
+  Main St, San Francisco"
+
+          # Add user message to conversation
+          conversation.add_message("user", user_message)
+
+          # Process response and handle function calls
+          return self._process_response(response, conversation,
+  chat)
+          #      ↑
+          #      CALLS THIS NEXT
+
+  ---
+  STEP 5: Gemini API Processes Request
+
+  🌐 GOOGLE GEMINI API (External)
+
+  RECEIVES:
+  - System Prompt: "You are an AI assistant for FleetMind..."
+  - User Message: "Create an order for John Doe at 123 Main St, San     
+  Francisco"
+  - Available Tools: [geocode_address, create_order]
+
+  AI ANALYZES:
+  "User wants to create an order. I have:
+   ✅ Customer Name: John Doe
+   ✅ Address: 123 Main St, San Francisco
+   ❌ GPS Coordinates: Missing!
+
+   DECISION: Call geocode_address tool first to get coordinates."       
+
+  RETURNS TO CODE:
+  response = {
+      candidates: [{
+          content: {
+              parts: [{
+                  function_call: {
+                      name: "geocode_address",
+                      args: {
+                          "address": "123 Main St, San Francisco"       
+                      }
+                  }
+              }]
+          }
+      }]
+  }
+
+  ---
+  STEP 6: _process_response() - Detects Function Call
+
+  FILE: chat/providers/gemini_provider.py
+  LINE: 226-393
+
+  FUNCTION: _process_response(response, conversation, chat)
+      response = Response from Gemini with function_call
+      conversation = ConversationManager object
+      chat = Gemini chat session
+
+  Function Code:
+  def _process_response(self, response, conversation, chat):
+      """Process Gemini's response and handle function calls"""
+      tool_calls_made = []
+
+      try:
+          # Check ALL parts for function calls
+          parts = response.candidates[0].content.parts
+          logger.info(f"Processing response with {len(parts)}
+  part(s)")
+          #            ↑
+          #            LOGS: "Processing response with 1 part(s)"       
+
+          for part in parts:
+              if hasattr(part, 'function_call'):
+                  fc = part.function_call
+                  if fc and hasattr(fc, 'name') and fc.name:
+                      has_function_call = True
+                      logger.info(f"Detected function call:
+  {fc.name}")
+                      #            ↑
+                      #            LOGS: "Detected function call:       
+  geocode_address"
+                      break
+
+          if has_function_call:
+              # Handle function calls (potentially multiple in
+  sequence)
+              current_response = response
+              max_iterations = 10
+
+              for iteration in range(max_iterations):  # ← LOOP
+  STARTS
+                  # Extract function call details
+                  first_part =
+  current_response.candidates[0].content.parts[0]
+                  function_call = first_part.function_call
+                  function_name = function_call.name  #
+  "geocode_address"
+                  function_args = dict(function_call.args)  #
+  {"address": "123 Main St, San Francisco"}
+
+                  logger.info(f"Gemini executing function:
+  {function_name} (iteration {iteration + 1})")
+                  #            ↑
+                  #            LOGS: "Gemini executing function:        
+  geocode_address (iteration 1)"
+
+                  # Execute the tool
+                  tool_result = execute_tool(function_name,
+  function_args)
+                  #             ↑
+                  #             CALLS execute_tool() NEXT
+
+  ---
+  STEP 7: execute_tool() - Routes to Handler
+
+  FILE: chat/tools.py
+  LINE: 92-118
+
+  FUNCTION: execute_tool(tool_name, tool_input)
+      tool_name = "geocode_address"
+      tool_input = {"address": "123 Main St, San Francisco"}
+
+  Function Code:
+  def execute_tool(tool_name, tool_input):
+      """Route tool execution to appropriate handler"""
+      try:
+          if tool_name == "geocode_address":
+              return handle_geocode_address(tool_input)
+              #      ↑
+              #      CALLS THIS NEXT
+          elif tool_name == "create_order":
+              return handle_create_order(tool_input)
+          else:
+              return {"success": False, "error": f"Unknown tool:        
+  {tool_name}"}
+      except Exception as e:
+          logger.error(f"Tool execution error ({tool_name}): {e}")      
+          return {"success": False, "error": str(e)}
+
+  ---
+  STEP 8: handle_geocode_address()
+
+  FILE: chat/tools.py
+  LINE: 121-150
+
+  FUNCTION: handle_geocode_address(tool_input)
+      tool_input = {"address": "123 Main St, San Francisco"}
+
+  Function Code:
+  def handle_geocode_address(tool_input):
+      """Execute geocoding tool"""
+      address = tool_input.get("address", "")  # "123 Main St, San      
+  Francisco"
+
+      if not address:
+          return {"success": False, "error": "Address is required"}     
+
+      logger.info(f"Geocoding address: {address}")
+      #            ↑
+      #            LOGS: "Geocoding address: 123 Main St, San
+  Francisco"
+
+      result = geocoding_service.geocode(address)
+      #        ↑
+      #        CALLS geocoding_service.geocode() NEXT
+
+      return {
+          "success": True,
+          "latitude": result["lat"],
+          "longitude": result["lng"],
+          "formatted_address": result["formatted_address"],
+          "confidence": result["confidence"],
+          "message": f"Address geocoded successfully
+  ({result['confidence']})"
+      }
+
+  ---
+  STEP 9: GeocodingService.geocode()
+
+  FILE: chat/geocoding.py
+  LINE: 28-65
+
+  FUNCTION: GeocodingService.geocode(address)
+      address = "123 Main St, San Francisco"
+
+  Function Code:
+  def geocode(self, address):
+      """Geocode an address to coordinates"""
+      if not address:
+          return self._error_response("Address is required")
+
+      # Use mock or real API
+      if self.use_mock:  # True (no HERE_API_KEY configured)
+          return self._geocode_mock(address)
+          #      ↑
+          #      CALLS THIS NEXT
+      else:
+          return self._geocode_here(address)
+
+  ---
+  STEP 10: _geocode_mock() - Returns Coordinates
+
+  FILE: chat/geocoding.py
+  LINE: 52-70
+
+  FUNCTION: _geocode_mock(address)
+      address = "123 Main St, San Francisco"
+
+  Function Code:
+  def _geocode_mock(self, address):
+      """Mock geocoding using city detection"""
+      address_lower = address.lower()
+
+      # Try to detect city in address
+      for city_name, (lat, lng) in CITY_COORDINATES.items():
+          if city_name in address_lower:
+              logger.info(f"Mock geocoding detected city:
+  {city_name}")
+              #            ↑
+              #            LOGS: "Mock geocoding detected city: san     
+  francisco"
+
+              return {
+                  "lat": lat,      # 37.7749
+                  "lng": lng,      # -122.4194
+                  "formatted_address": address,
+                  "confidence": "mock"
+              }
+
+      # Default to San Francisco if no city detected
+      return {
+          "lat": 37.7749,
+          "lng": -122.4194,
+          "formatted_address": address,
+          "confidence": "mock"
+      }
+
+  RETURNS:
+  {
+      "lat": 37.7749,
+      "lng": -122.4194,
+      "formatted_address": "123 Main St, San Francisco",
+      "confidence": "mock"
+  }
+
+  ---
+  STEP 11: Back to handle_geocode_address()
+
+  FILE: chat/tools.py
+  LINE: 141-150
+
+  result = {
+      "lat": 37.7749,
+      "lng": -122.4194,
+      "formatted_address": "123 Main St, San Francisco",
+      "confidence": "mock"
+  }
+
+  RETURNS:
+  {
+      "success": True,
+      "latitude": 37.7749,
+      "longitude": -122.4194,
+      "formatted_address": "123 Main St, San Francisco",
+      "confidence": "mock",
+      "message": "Address geocoded successfully (mock)"
+  }
+
+  ---
+  STEP 12: Back to _process_response() - Tool Result Received
+
+  FILE: chat/providers/gemini_provider.py
+  LINE: 285-310
+
+  tool_result = {
+      "success": True,
+      "latitude": 37.7749,
+      "longitude": -122.4194,
+      "formatted_address": "123 Main St, San Francisco",
+      "confidence": "mock",
+      "message": "Address geocoded successfully (mock)"
+  }
+
+  # Track for transparency
+  tool_calls_made.append({
+      "tool": "geocode_address",
+      "input": {"address": "123 Main St, San Francisco"},
+      "result": tool_result
+  })
+
+  conversation.add_tool_result("geocode_address", function_args,        
+  tool_result)
+
+  # Send function result back to Gemini
+  current_response = chat.send_message(
+      genai.protos.Content(
+          parts=[genai.protos.Part(
+              function_response=genai.protos.FunctionResponse(
+                  name="geocode_address",
+                  response={"result": tool_result}
+              )
+          )]
+      )
+  )
+  #  ↑
+  #  🌐 API CALL TO GEMINI WITH GEOCODING RESULT
+
+  ---
+  STEP 13: Gemini Receives Geocoding Result
+
+  🌐 GOOGLE GEMINI API (External)
+
+  RECEIVES:
+  - Function: geocode_address
+  - Result: {
+      "success": True,
+      "latitude": 37.7749,
+      "longitude": -122.4194
+    }
+
+  AI ANALYZES:
+  "Great! I now have GPS coordinates:
+   ✅ Customer Name: John Doe
+   ✅ Address: 123 Main St, San Francisco
+   ✅ Latitude: 37.7749
+   ✅ Longitude: -122.4194
+
+   DECISION: Now I can create the order in the database!
+             Call create_order tool."
+
+  RETURNS TO CODE:
+  response = {
+      candidates: [{
+          content: {
+              parts: [{
+                  function_call: {
+                      name: "create_order",
+                      args: {
+                          "customer_name": "John Doe",
+                          "delivery_address": "123 Main St, San
+  Francisco",
+                          "delivery_lat": 37.7749,
+                          "delivery_lng": -122.4194,
+                          "priority": "standard"
+                      }
+                  }
+              }]
+          }
+      }]
+  }
+
+  ---
+  STEP 14: Loop Continues - Detects create_order
+
+  FILE: chat/providers/gemini_provider.py
+  LINE: 252-285
+
+  # Still in the for loop (iteration 2)
+  first_part = current_response.candidates[0].content.parts[0]
+  has_fc = True  # Another function call detected
+
+  function_call = first_part.function_call
+  function_name = function_call.name  # "create_order"
+  function_args = dict(function_call.args)  # {customer_name,
+  address, lat, lng...}
+
+  logger.info(f"Gemini executing function: {function_name}
+  (iteration 2)")
+  #            ↑
+  #            LOGS: "Gemini executing function: create_order
+  (iteration 2)"
+
+  # Execute the tool
+  tool_result = execute_tool(function_name, function_args)
+  #             ↑
+  #             CALLS execute_tool() AGAIN
+
+  ---
+  STEP 15: execute_tool() - Routes to create_order
+
+  FILE: chat/tools.py
+  LINE: 92-118
+
+  FUNCTION: execute_tool(tool_name, tool_input)
+      tool_name = "create_order"
+      tool_input = {
+          "customer_name": "John Doe",
+          "delivery_address": "123 Main St, San Francisco",
+          "delivery_lat": 37.7749,
+          "delivery_lng": -122.4194,
+          "priority": "standard"
+      }
+
+  Function Code:
+  def execute_tool(tool_name, tool_input):
+      try:
+          if tool_name == "geocode_address":
+              return handle_geocode_address(tool_input)
+          elif tool_name == "create_order":
+              return handle_create_order(tool_input)
+              #      ↑
+              #      CALLS THIS NEXT
+
+  ---
+  STEP 16: handle_create_order()
+
+  FILE: chat/tools.py
+  LINE: 153-242
+
+  FUNCTION: handle_create_order(tool_input)
+      tool_input = {
+          "customer_name": "John Doe",
+          "delivery_address": "123 Main St, San Francisco",
+          "delivery_lat": 37.7749,
+          "delivery_lng": -122.4194,
+          "priority": "standard"
+      }
+
+  Function Code:
+  def handle_create_order(tool_input):
+      """Execute order creation tool"""
+
+      # Extract fields with defaults
+      customer_name = tool_input.get("customer_name")  # "John Doe"     
+      customer_phone = tool_input.get("customer_phone")  # None
+      customer_email = tool_input.get("customer_email")  # None
+      delivery_address = tool_input.get("delivery_address")  # "123     
+  Main St, San Francisco"
+      delivery_lat = tool_input.get("delivery_lat")  # 37.7749
+      delivery_lng = tool_input.get("delivery_lng")  # -122.4194        
+      priority = tool_input.get("priority", "standard")  #
+  "standard"
+      special_instructions = tool_input.get("special_instructions")     
+   # None
+      weight_kg = tool_input.get("weight_kg", 5.0)  # 5.0
+
+      # Validate required fields
+      if not all([customer_name, delivery_address, delivery_lat,        
+  delivery_lng]):
+          return {"success": False, "error": "Missing required
+  fields..."}
+
+      # Generate order ID
+      now = datetime.now()
+      order_id = f"ORD-{now.strftime('%Y%m%d%H%M%S')}"
+      #          ↑
+      #          e.g., "ORD-20251114015858"
+
+      # Handle time window
+      time_window_end = now + timedelta(hours=6)  # 6 hours from now    
+      time_window_start = now + timedelta(hours=2)  # 2 hours from      
+  now
+
+      # Insert into database
+      query = """
+          INSERT INTO orders (
+              order_id, customer_name, customer_phone,
+  customer_email,
+              delivery_address, delivery_lat, delivery_lng,
+              time_window_start, time_window_end,
+              priority, weight_kg, status, special_instructions
+          ) VALUES (%s, %s, %s, %s, %s, %s, %s, %s, %s, %s, %s, %s,     
+  %s)
+      """
+
+      params = (
+          order_id,                # "ORD-20251114015858"
+          customer_name,           # "John Doe"
+          customer_phone,          # None
+          customer_email,          # None
+          delivery_address,        # "123 Main St, San Francisco"       
+          delivery_lat,            # 37.7749
+          delivery_lng,            # -122.4194
+          time_window_start,       # 2025-11-14 03:58:58
+          time_window_end,         # 2025-11-14 07:58:58
+          priority,                # "standard"
+          weight_kg,               # 5.0
+          "pending",               # status
+          special_instructions     # None
+      )
+
+      try:
+          execute_write(query, params)
+          #     ↑
+          #     CALLS THIS NEXT - DATABASE WRITE!
+
+  ---
+  STEP 17: execute_write() - INSERT INTO DATABASE
+
+  FILE: database/connection.py
+  LINE: 71-97
+
+  FUNCTION: execute_write(query, params)
+      query = "INSERT INTO orders (...) VALUES (%s, %s, ...)"
+      params = ("ORD-20251114015858", "John Doe", None, None, "123      
+  Main St...", ...)
+
+  Function Code:
+  def execute_write(query, params=None):
+      """Execute a write query (INSERT, UPDATE, DELETE)"""
+      try:
+          # Connect to PostgreSQL
+          conn = get_db_connection()
+          #      ↑
+          #      Opens connection to localhost:5432/fleetmind
+
+          logger.info("Database connection established:
+  fleetmind@localhost")
+
+          cursor = conn.cursor()
+
+          # Execute INSERT query
+          cursor.execute(query, params)
+          #     ↑
+          #     💾 EXECUTES SQL:
+          #     INSERT INTO orders (order_id, customer_name, ...)       
+          #     VALUES ('ORD-20251114015858', 'John Doe', ...)
+
+          conn.commit()  # ← SAVES TO POSTGRESQL PERMANENTLY!
+
+          rows_affected = cursor.rowcount  # 1
+
+          cursor.close()
+          conn.close()
+
+          logger.info("Database connection closed")
+
+          return rows_affected  # Returns 1
+
+  DATABASE STATE:
+  -- New row added to orders table:
+  ORDER_ID: ORD-20251114015858
+  CUSTOMER_NAME: John Doe
+  CUSTOMER_PHONE: NULL
+  CUSTOMER_EMAIL: NULL
+  DELIVERY_ADDRESS: 123 Main St, San Francisco
+  DELIVERY_LAT: 37.7749
+  DELIVERY_LNG: -122.4194
+  STATUS: pending
+  PRIORITY: standard
+  WEIGHT_KG: 5.0
+  CREATED_AT: 2025-11-14 01:58:58
+
+  ---
+  STEP 18: Back to handle_create_order() - Success!
+
+  FILE: chat/tools.py
+  LINE: 224-242
+
+  execute_write(query, params)  # Returned 1 (success)
+
+  logger.info(f"Order created: {order_id}")
+  #            ↑
+  #            LOGS: "Order created: ORD-20251114015858"
+
+  return {
+      "success": True,
+      "order_id": "ORD-20251114015858",
+      "status": "pending",
+      "customer": "John Doe",
+      "address": "123 Main St, San Francisco",
+      "deadline": "2025-11-14 07:58",
+      "priority": "standard",
+      "message": "Order ORD-20251114015858 created successfully!"       
+  }
+
+  ---
+  STEP 19: Back to _process_response() - Second Tool Complete
+
+  FILE: chat/providers/gemini_provider.py
+  LINE: 285-310
+
+  tool_result = {
+      "success": True,
+      "order_id": "ORD-20251114015858",
+      "status": "pending",
+      "customer": "John Doe",
+      ...
+  }
+
+  # Track for transparency
+  tool_calls_made.append({
+      "tool": "create_order",
+      "input": {
+          "customer_name": "John Doe",
+          "delivery_address": "123 Main St, San Francisco",
+          "delivery_lat": 37.7749,
+          "delivery_lng": -122.4194
+      },
+      "result": tool_result
+  })
+
+  conversation.add_tool_result("create_order", function_args,
+  tool_result)
+
+  # Send function result back to Gemini
+  current_response = chat.send_message(
+      genai.protos.Content(
+          parts=[genai.protos.Part(
+              function_response=genai.protos.FunctionResponse(
+                  name="create_order",
+                  response={"result": tool_result}
+              )
+          )]
+      )
+  )
+  #  ↑
+  #  🌐 API CALL TO GEMINI WITH ORDER CREATION RESULT
+
+  ---
+  STEP 20: Gemini Generates Final Response
+
+  🌐 GOOGLE GEMINI API (External)
+
+  RECEIVES:
+  - Function: create_order
+  - Result: {
+      "success": True,
+      "order_id": "ORD-20251114015858",
+      "customer": "John Doe",
+      "address": "123 Main St, San Francisco"
+    }
+
+  AI ANALYZES:
+  "Perfect! Order successfully created in database!
+   Let me tell the user with a nice summary."
+
+  GENERATES TEXT RESPONSE:
+  "Awesome! I have created the order for John Doe.
+
+  **Here's a summary:**
+  • Order ID: ORD-20251114015858
+  • Customer: John Doe
+  • Address: 123 Main St, San Francisco
+  • Status: Pending
+  • Priority: Standard
+
+  The order has been successfully saved to the database!"
+
+  RETURNS TO CODE:
+  response = {
+      candidates: [{
+          content: {
+              parts: [{
+                  text: "Awesome! I have created the order for John     
+  Doe.\n\n**Here's a summary:**..."
+              }]
+          }
+      }]
+  }
+
+  ---
+  STEP 21: _process_response() - Extract Final Text
+
+  FILE: chat/providers/gemini_provider.py
+  LINE: 272-356
+
+  # Loop detects no more function calls
+  logger.info(f"No more function calls after iteration 2")
+
+  # Extract text from final response
+  parts = current_response.candidates[0].content.parts
+  logger.info(f"Extracting text from {len(parts)} parts")
+
+  for idx, part in enumerate(parts):
+      if hasattr(part, 'text') and part.text:
+          logger.info(f"Part {idx} has text: {part.text[:50]}...")      
+          final_text += part.text
+
+  # final_text = "Awesome! I have created the order for John Doe..."    
+
+  logger.info(f"Returning response: {final_text[:100]}")
+
+  conversation.add_message("assistant", final_text)
+
+  return final_text, tool_calls_made
+  #      ↑           ↑
+  #      Response    List of 2 tool calls [geocode, create_order]       
+
+  RETURNS:
+  (
+      "Awesome! I have created the order for John Doe.\n\n**Here's a    
+   summary:**...",
+      [
+          {"tool": "geocode_address", "input": {...}, "result":
+  {...}},
+          {"tool": "create_order", "input": {...}, "result": {...}}     
+      ]
+  )
+
+  ---
+  STEP 22: Back Through All Functions
+
+  ← Returns to: GeminiProvider.process_message() (line 206)
+  ← Returns to: ChatEngine.process_message() (line 58)
+  ← Returns to: handle_chat_message() (line 223)
+  ← Returns to: send_message() (line 443)
+  ← Returns to: Gradio UI (line 448)
+
+  ---
+  STEP 23: Gradio Updates UI
+
+  FILE: ui/app.py
+  LINE: 448-452
+
+  send_btn.click(
+      fn=send_message,
+      outputs=[chatbot, tool_display, conversation_state, msg_input]    
+      #        ↑        ↑
+      #        Updates  Shows tool calls
+  )
+
+  CHATBOT DISPLAYS:
+  User: "Create an order for John Doe at 123 Main St, San Francisco"    

requirements.txt

@@ -0,0 +1,27 @@
+# Core Framework
+gradio>=5.9.0
+fastmcp>=0.3.0
+
+# AI/ML
+anthropic>=0.40.0
+google-generativeai>=0.3.0
+
+# Data & Database
+pandas>=2.2.0
+faker>=23.0.0
+psycopg2-binary>=2.9.9
+
+# API Clients
+requests>=2.31.0
+httpx>=0.27.1
+
+# Utilities
+python-dotenv>=1.0.0
+pydantic>=2.5.3
+
+# Testing
+pytest>=8.0.0
+pytest-asyncio>=0.23.0
+
+# Type Checking
+mypy>=1.8.0

scripts/init_db.py

@@ -0,0 +1,115 @@
+"""
+Database initialization script for FleetMind
+Run this script to create the PostgreSQL database and tables
+"""
+
+import sys
+from pathlib import Path
+
+# Add parent directory to path to import database module
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+from database.connection import init_database, get_db_connection, test_connection
+from database.schema import get_full_schema
+import logging
+
+logging.basicConfig(
+    level=logging.INFO,
+    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
+)
+logger = logging.getLogger(__name__)
+
+
+def main():
+    """Initialize the FleetMind PostgreSQL database"""
+    try:
+        logger.info("=" * 60)
+        logger.info("FleetMind Database Initialization")
+        logger.info("=" * 60)
+
+        # Test connection first
+        logger.info("\nStep 1: Testing PostgreSQL connection...")
+        if not test_connection():
+            logger.error("Failed to connect to PostgreSQL database")
+            logger.error("Please check your .env file and ensure PostgreSQL is running")
+            sys.exit(1)
+
+        logger.info("✓ PostgreSQL connection successful")
+
+        # Initialize database with full schema
+        logger.info("\nStep 2: Creating database schema...")
+        init_database()
+
+        # Verify tables were created
+        logger.info("\nStep 3: Verifying table creation...")
+        conn = get_db_connection()
+        cursor = conn.cursor()
+
+        # Get list of all tables
+        cursor.execute("""
+            SELECT table_name
+            FROM information_schema.tables
+            WHERE table_schema = 'public'
+            ORDER BY table_name
+        """)
+        tables = cursor.fetchall()
+
+        if tables:
+            logger.info(f"✓ Successfully created {len(tables)} tables:")
+            for table in tables:
+                logger.info(f"  - {table['table_name']}")
+
+                # Get column count for each table
+                cursor.execute(f"""
+                    SELECT COUNT(*) as column_count
+                    FROM information_schema.columns
+                    WHERE table_name = %s
+                """, (table['table_name'],))
+                col_count = cursor.fetchone()
+                logger.info(f"    ({col_count['column_count']} columns)")
+        else:
+            logger.warning("No tables were created")
+
+        # Specifically check orders table
+        logger.info("\nStep 4: Verifying orders table...")
+        cursor.execute("""
+            SELECT column_name, data_type, is_nullable
+            FROM information_schema.columns
+            WHERE table_name = 'orders'
+            ORDER BY ordinal_position
+        """)
+        columns = cursor.fetchall()
+
+        if columns:
+            logger.info(f"✓ Orders table created with {len(columns)} columns:")
+            for col in columns[:10]:  # Show first 10 columns
+                nullable = "NULL" if col['is_nullable'] == 'YES' else "NOT NULL"
+                logger.info(f"  - {col['column_name']}: {col['data_type']} ({nullable})")
+
+            if len(columns) > 10:
+                logger.info(f"  ... and {len(columns) - 10} more columns")
+        else:
+            logger.error("✗ Orders table was not created")
+
+        conn.close()
+
+        logger.info("\n" + "=" * 60)
+        logger.info("Database initialization completed successfully!")
+        logger.info("=" * 60)
+        logger.info("\nYou can now:")
+        logger.info("  1. Test the database: python scripts/test_db.py")
+        logger.info("  2. Start the application: python ui/app.py")
+
+    except Exception as e:
+        logger.error(f"\n✗ Database initialization failed: {e}")
+        logger.error("\nTroubleshooting:")
+        logger.error("  1. Ensure PostgreSQL is installed and running")
+        logger.error("  2. Create a database named 'fleetmind' in PostgreSQL")
+        logger.error("     Command: createdb fleetmind")
+        logger.error("  3. Update .env file with correct database credentials")
+        logger.error("  4. Verify PostgreSQL user has necessary permissions")
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

scripts/test_db.py

@@ -0,0 +1,169 @@
+"""
+Test script to verify PostgreSQL database operations
+"""
+
+import sys
+from pathlib import Path
+from datetime import datetime, timedelta
+
+# Add parent directory to path
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+from database.connection import execute_query, execute_write
+import logging
+
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+
+def test_insert_order():
+    """Test inserting a new order"""
+    logger.info("Testing order insertion...")
+
+    now = datetime.now()
+    time_window_start = now + timedelta(hours=2)
+    time_window_end = now + timedelta(hours=6)
+
+    query = """
+        INSERT INTO orders (
+            order_id, customer_name, customer_phone, customer_email,
+            delivery_address, delivery_lat, delivery_lng,
+            time_window_start, time_window_end,
+            priority, weight_kg, status
+        ) VALUES (%s, %s, %s, %s, %s, %s, %s, %s, %s, %s, %s, %s)
+    """
+
+    params = (
+        "ORD-TEST-001",
+        "John Doe",
+        "+1-555-0123",
+        "john.doe@example.com",
+        "123 Main Street, San Francisco, CA 94103",
+        37.7749,
+        -122.4194,
+        time_window_start,
+        time_window_end,
+        "standard",
+        5.5,
+        "pending"
+    )
+
+    try:
+        result = execute_write(query, params)
+        logger.info(f"✓ Order inserted successfully (rows affected: {result})")
+        return True
+    except Exception as e:
+        logger.error(f"✗ Failed to insert order: {e}")
+        return False
+
+
+def test_query_orders():
+    """Test querying orders"""
+    logger.info("Testing order query...")
+
+    query = "SELECT * FROM orders WHERE status = %s"
+    params = ("pending",)
+
+    try:
+        results = execute_query(query, params)
+        logger.info(f"✓ Query successful: Found {len(results)} pending orders")
+
+        for row in results:
+            logger.info(f"  Order ID: {row['order_id']}")
+            logger.info(f"  Customer: {row['customer_name']}")
+            logger.info(f"  Address: {row['delivery_address']}")
+            logger.info(f"  Priority: {row['priority']}")
+            logger.info(f"  Status: {row['status']}")
+            logger.info("  ---")
+
+        return True
+    except Exception as e:
+        logger.error(f"✗ Failed to query orders: {e}")
+        return False
+
+
+def test_update_order():
+    """Test updating an order"""
+    logger.info("Testing order update...")
+
+    query = "UPDATE orders SET status = %s, assigned_driver_id = %s WHERE order_id = %s"
+    params = ("assigned", "DRV-001", "ORD-TEST-001")
+
+    try:
+        result = execute_write(query, params)
+        logger.info(f"✓ Order updated successfully (rows affected: {result})")
+
+        # Verify update
+        verify_query = "SELECT status, assigned_driver_id FROM orders WHERE order_id = %s"
+        verify_result = execute_query(verify_query, ("ORD-TEST-001",))
+
+        if verify_result:
+            row = verify_result[0]
+            logger.info(f"  New status: {row['status']}")
+            logger.info(f"  Assigned driver: {row['assigned_driver_id']}")
+
+        return True
+    except Exception as e:
+        logger.error(f"✗ Failed to update order: {e}")
+        return False
+
+
+def test_delete_order():
+    """Test deleting the test order"""
+    logger.info("Testing order deletion (cleanup)...")
+
+    query = "DELETE FROM orders WHERE order_id = %s"
+    params = ("ORD-TEST-001",)
+
+    try:
+        result = execute_write(query, params)
+        logger.info(f"✓ Order deleted successfully (rows affected: {result})")
+        return True
+    except Exception as e:
+        logger.error(f"✗ Failed to delete order: {e}")
+        return False
+
+
+def main():
+    """Run all database tests"""
+    logger.info("=" * 50)
+    logger.info("Starting FleetMind PostgreSQL Database Tests")
+    logger.info("=" * 50)
+
+    tests = [
+        ("Insert Order", test_insert_order),
+        ("Query Orders", test_query_orders),
+        ("Update Order", test_update_order),
+        ("Delete Order", test_delete_order),
+    ]
+
+    results = []
+    for test_name, test_func in tests:
+        logger.info(f"\n--- {test_name} ---")
+        success = test_func()
+        results.append((test_name, success))
+
+    # Summary
+    logger.info("\n" + "=" * 50)
+    logger.info("Test Summary")
+    logger.info("=" * 50)
+
+    passed = sum(1 for _, success in results if success)
+    total = len(results)
+
+    for test_name, success in results:
+        status = "✓ PASSED" if success else "✗ FAILED"
+        logger.info(f"{test_name}: {status}")
+
+    logger.info(f"\nTotal: {passed}/{total} tests passed")
+
+    if passed == total:
+        logger.info("\n🎉 All tests passed! Your PostgreSQL database is working correctly!")
+        return 0
+    else:
+        logger.error("\n❌ Some tests failed. Please check the errors above.")
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

ui/__init__.py

@@ -0,0 +1,4 @@
+"""
+UI package for FleetMind
+Contains Gradio interface components
+"""

ui/app.py

@@ -0,0 +1,542 @@
+"""
+FleetMind MCP - Gradio Web Interface
+Simple dashboard to interact with the MCP server and database
+"""
+
+import sys
+from pathlib import Path
+
+# Add parent directory to path
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+import gradio as gr
+from database.connection import execute_query, execute_write, test_connection
+from datetime import datetime, timedelta
+import json
+
+# Import chat functionality
+from chat.chat_engine import ChatEngine
+from chat.conversation import ConversationManager
+from chat.geocoding import GeocodingService
+
+# ============================================
+# DATABASE FUNCTIONS
+# ============================================
+
+def get_database_status():
+    """Check if database is connected"""
+    try:
+        if test_connection():
+            return "✅ Connected", "success"
+        else:
+            return "❌ Disconnected", "error"
+    except Exception as e:
+        return f"❌ Error: {str(e)}", "error"
+
+
+def get_orders_summary():
+    """Get summary of orders by status"""
+    try:
+        query = """
+            SELECT
+                status,
+                COUNT(*) as count
+            FROM orders
+            GROUP BY status
+            ORDER BY count DESC
+        """
+        results = execute_query(query)
+
+        if not results:
+            return "No orders in database"
+
+        summary = "**Orders Summary:**\n\n"
+        for row in results:
+            summary += f"- {row['status'].upper()}: {row['count']}\n"
+
+        return summary
+    except Exception as e:
+        return f"Error: {str(e)}"
+
+
+def get_all_orders():
+    """Get all orders from database"""
+    try:
+        query = """
+            SELECT
+                order_id,
+                customer_name,
+                delivery_address,
+                status,
+                priority,
+                created_at
+            FROM orders
+            ORDER BY created_at DESC
+            LIMIT 50
+        """
+        results = execute_query(query)
+
+        if not results:
+            return [["No orders found", "", "", "", "", ""]]
+
+        # Convert to list of lists for Gradio dataframe
+        data = []
+        for row in results:
+            data.append([
+                row['order_id'],
+                row['customer_name'],
+                row['delivery_address'][:50] + "..." if len(row['delivery_address']) > 50 else row['delivery_address'],
+                row['status'],
+                row['priority'],
+                str(row['created_at'])
+            ])
+
+        return data
+    except Exception as e:
+        return [[f"Error: {str(e)}", "", "", "", "", ""]]
+
+
+def create_sample_order():
+    """Create a sample order for testing"""
+    try:
+        now = datetime.now()
+        order_id = f"ORD-{now.strftime('%Y%m%d%H%M%S')}"
+
+        query = """
+            INSERT INTO orders (
+                order_id, customer_name, customer_phone, customer_email,
+                delivery_address, delivery_lat, delivery_lng,
+                time_window_start, time_window_end,
+                priority, weight_kg, status
+            ) VALUES (%s, %s, %s, %s, %s, %s, %s, %s, %s, %s, %s, %s)
+        """
+
+        params = (
+            order_id,
+            "Sample Customer",
+            "+1-555-0100",
+            "sample@example.com",
+            "456 Sample Street, San Francisco, CA 94103",
+            37.7749,
+            -122.4194,
+            now + timedelta(hours=2),
+            now + timedelta(hours=6),
+            "standard",
+            10.5,
+            "pending"
+        )
+
+        execute_write(query, params)
+        return f"✅ Order {order_id} created successfully!", get_all_orders()
+    except Exception as e:
+        return f"❌ Error: {str(e)}", get_all_orders()
+
+
+def search_orders(search_term):
+    """Search orders by customer name or order ID"""
+    try:
+        if not search_term:
+            return get_all_orders()
+
+        query = """
+            SELECT
+                order_id,
+                customer_name,
+                delivery_address,
+                status,
+                priority,
+                created_at
+            FROM orders
+            WHERE
+                order_id ILIKE %s OR
+                customer_name ILIKE %s
+            ORDER BY created_at DESC
+            LIMIT 50
+        """
+
+        search_pattern = f"%{search_term}%"
+        results = execute_query(query, (search_pattern, search_pattern))
+
+        if not results:
+            return [["No matching orders found", "", "", "", "", ""]]
+
+        data = []
+        for row in results:
+            data.append([
+                row['order_id'],
+                row['customer_name'],
+                row['delivery_address'][:50] + "..." if len(row['delivery_address']) > 50 else row['delivery_address'],
+                row['status'],
+                row['priority'],
+                str(row['created_at'])
+            ])
+
+        return data
+    except Exception as e:
+        return [[f"Error: {str(e)}", "", "", "", "", ""]]
+
+
+# ============================================
+# CHAT FUNCTIONS
+# ============================================
+
+# Initialize chat engine and geocoding service
+chat_engine = ChatEngine()
+geocoding_service = GeocodingService()
+
+
+def get_api_status():
+    """Get API status for chat"""
+    # Get full status for all providers
+    full_status = chat_engine.get_full_status()
+    selected = full_status["selected"]
+    claude_status = full_status["claude"]["status"]
+    gemini_status = full_status["gemini"]["status"]
+
+    geocoding_status = geocoding_service.get_status()
+
+    # Mark selected provider
+    claude_marker = "🎯 **ACTIVE** - " if selected == "anthropic" else ""
+    gemini_marker = "🎯 **ACTIVE** - " if selected == "gemini" else ""
+
+    return f"""### API Status
+
+**AI Provider:**
+
+**Claude (Anthropic):**
+{claude_marker}{claude_status}
+
+**Gemini (Google):**
+{gemini_marker}{gemini_status}
+
+*💡 Switch provider by setting `AI_PROVIDER=anthropic` or `AI_PROVIDER=gemini` in .env*
+
+---
+
+**Geocoding:**
+
+**HERE Maps:**
+{geocoding_status}
+"""
+
+
+def handle_chat_message(message, conversation_state):
+    """
+    Handle chat message from user
+
+    Args:
+        message: User's message
+        conversation_state: ConversationManager instance
+
+    Returns:
+        Updated chatbot history, tool display, conversation state
+    """
+    if not message.strip():
+        return conversation_state.get_formatted_history(), conversation_state.get_tool_calls(), conversation_state
+
+    # Process message through chat engine
+    response, tool_calls = chat_engine.process_message(message, conversation_state)
+
+    # Return updated UI
+    return conversation_state.get_formatted_history(), conversation_state.get_tool_calls(), conversation_state
+
+
+def reset_conversation():
+    """Reset conversation to start fresh"""
+    new_conversation = ConversationManager()
+
+    # Add welcome message
+    welcome = chat_engine.get_welcome_message()
+    new_conversation.add_message("assistant", welcome)
+
+    return (
+        new_conversation.get_formatted_history(),
+        [],  # Clear tool calls
+        new_conversation
+    )
+
+
+def get_initial_chat():
+    """Get initial chat state with welcome message"""
+    conversation = ConversationManager()
+    welcome = chat_engine.get_welcome_message()
+    conversation.add_message("assistant", welcome)
+
+    return conversation.get_formatted_history(), [], conversation
+
+
+# ============================================
+# MCP SERVER INFO
+# ============================================
+
+def get_mcp_server_info():
+    """Get MCP server information"""
+    mcp_info = {
+        "server_name": "dispatch-coordinator-mcp",
+        "version": "1.0.0",
+        "status": "Ready",
+        "tools": [
+            "route_optimizer",
+            "geocoder",
+            "weather_monitor",
+            "traffic_checker",
+            "distance_matrix",
+            "order_manager"
+        ]
+    }
+
+    return f"""
+### MCP Server Information
+
+**Name:** {mcp_info['server_name']}
+**Version:** {mcp_info['version']}
+**Status:** 🟢 {mcp_info['status']}
+
+**Available Tools ({len(mcp_info['tools'])}):**
+{chr(10).join([f"- {tool}" for tool in mcp_info['tools']])}
+"""
+
+
+# ============================================
+# GRADIO INTERFACE
+# ============================================
+
+def create_interface():
+    """Create the Gradio interface"""
+
+    with gr.Blocks(theme=gr.themes.Soft(), title="FleetMind MCP Dashboard") as app:
+
+        gr.Markdown("# 🚚 FleetMind MCP Dashboard")
+        gr.Markdown("*Autonomous Dispatch Coordinator powered by MCP and PostgreSQL*")
+
+        with gr.Tabs():
+
+            # ==========================================
+            # TAB 1: OVERVIEW
+            # ==========================================
+            with gr.Tab("📊 Overview"):
+                with gr.Row():
+                    with gr.Column(scale=1):
+                        gr.Markdown("### System Status")
+                        db_status = gr.Textbox(
+                            label="Database Connection",
+                            value=get_database_status()[0],
+                            interactive=False
+                        )
+                        refresh_status_btn = gr.Button("🔄 Refresh Status", size="sm")
+
+                        gr.Markdown("---")
+                        orders_summary = gr.Markdown(get_orders_summary())
+
+                    with gr.Column(scale=2):
+                        mcp_info = gr.Markdown(get_mcp_server_info())
+
+                # Refresh status button action
+                refresh_status_btn.click(
+                    fn=lambda: get_database_status()[0],
+                    outputs=db_status
+                )
+
+            # ==========================================
+            # TAB 2: ORDERS MANAGEMENT
+            # ==========================================
+            with gr.Tab("📦 Orders"):
+                gr.Markdown("### Orders Management")
+
+                with gr.Row():
+                    search_box = gr.Textbox(
+                        placeholder="Search by Order ID or Customer Name...",
+                        label="Search Orders",
+                        scale=3
+                    )
+                    search_btn = gr.Button("🔍 Search", scale=1)
+                    create_btn = gr.Button("➕ Create Sample Order", scale=1, variant="primary")
+
+                create_result = gr.Textbox(label="Result", visible=False)
+
+                orders_table = gr.Dataframe(
+                    headers=["Order ID", "Customer", "Delivery Address", "Status", "Priority", "Created At"],
+                    datatype=["str", "str", "str", "str", "str", "str"],
+                    label="Orders List",
+                    value=get_all_orders(),
+                    interactive=False,
+                    wrap=True
+                )
+
+                refresh_orders_btn = gr.Button("🔄 Refresh Orders")
+
+                # Button actions
+                create_btn.click(
+                    fn=create_sample_order,
+                    outputs=[create_result, orders_table]
+                ).then(
+                    fn=lambda: gr.update(visible=True),
+                    outputs=create_result
+                ).then(
+                    fn=lambda: get_orders_summary(),
+                    outputs=orders_summary
+                )
+
+                search_btn.click(
+                    fn=search_orders,
+                    inputs=search_box,
+                    outputs=orders_table
+                )
+
+                search_box.submit(
+                    fn=search_orders,
+                    inputs=search_box,
+                    outputs=orders_table
+                )
+
+                refresh_orders_btn.click(
+                    fn=get_all_orders,
+                    outputs=orders_table
+                ).then(
+                    fn=lambda: get_orders_summary(),
+                    outputs=orders_summary
+                )
+
+            # ==========================================
+            # TAB 3: AI CHAT
+            # ==========================================
+            with gr.Tab("💬 Chat"):
+                provider_name = chat_engine.get_provider_name()
+                model_name = chat_engine.get_model_name()
+
+                gr.Markdown(f"### AI Order Assistant")
+                gr.Markdown(f"*Powered by: **{provider_name}** ({model_name})*")
+
+                # API Status
+                api_status = gr.Markdown(get_api_status())
+
+                # Chat interface
+                chatbot = gr.Chatbot(
+                    label="Order Assistant",
+                    height=500,
+                    type="messages",
+                    show_copy_button=True
+                )
+
+                msg_input = gr.Textbox(
+                    placeholder="e.g., 'Create an order for John Doe at 123 Main St, deliver by 5 PM'",
+                    label="Your Message",
+                    lines=2
+                )
+
+                with gr.Row():
+                    send_btn = gr.Button("📤 Send", variant="primary", scale=2)
+                    clear_btn = gr.Button("🔄 Clear Chat", scale=1)
+
+                # Tool usage display (reasoning transparency)
+                with gr.Accordion("🔧 Tool Usage (AI Reasoning)", open=False):
+                    gr.Markdown("See what tools the AI is using behind the scenes:")
+                    tool_display = gr.JSON(label="Tools Called")
+
+                # Conversation state
+                conversation_state = gr.State(value=None)
+
+                # Initialize with welcome message
+                chatbot.value, tool_display.value, conversation_state.value = get_initial_chat()
+
+                # Event handlers
+                def send_message(message, conv_state):
+                    """Handle send button click"""
+                    chat_history, tools, new_state = handle_chat_message(message, conv_state)
+                    return chat_history, tools, new_state, ""  # Clear input
+
+                send_btn.click(
+                    fn=send_message,
+                    inputs=[msg_input, conversation_state],
+                    outputs=[chatbot, tool_display, conversation_state, msg_input]
+                )
+
+                msg_input.submit(
+                    fn=send_message,
+                    inputs=[msg_input, conversation_state],
+                    outputs=[chatbot, tool_display, conversation_state, msg_input]
+                )
+
+                clear_btn.click(
+                    fn=reset_conversation,
+                    outputs=[chatbot, tool_display, conversation_state]
+                )
+
+            # ==========================================
+            # TAB 4: MCP TOOLS (Coming Soon)
+            # ==========================================
+            with gr.Tab("🔧 MCP Tools"):
+                gr.Markdown("### MCP Tools")
+                gr.Markdown("*MCP tool integration coming soon...*")
+
+                gr.Markdown("""
+                Available tools:
+                - **route_optimizer** - Optimize delivery routes
+                - **geocoder** - Convert addresses to coordinates
+                - **weather_monitor** - Check weather conditions
+                - **traffic_checker** - Monitor traffic conditions
+                - **distance_matrix** - Calculate distances
+                - **order_manager** - Manage orders via MCP
+                """)
+
+            # ==========================================
+            # TAB 5: DATABASE INFO
+            # ==========================================
+            with gr.Tab("💾 Database"):
+                gr.Markdown("### Database Information")
+
+                db_info = gr.Markdown(f"""
+                **Database:** PostgreSQL
+                **Name:** fleetmind
+                **Host:** localhost
+                **Port:** 5432
+
+                **Tables:**
+                - orders (26 columns)
+                - drivers (coming soon)
+                - assignments (coming soon)
+                - exceptions (coming soon)
+                """)
+
+                test_db_btn = gr.Button("🧪 Test Connection", variant="primary")
+                test_result = gr.Textbox(label="Test Result", interactive=False)
+
+                test_db_btn.click(
+                    fn=lambda: "✅ Connection successful!" if test_connection() else "❌ Connection failed",
+                    outputs=test_result
+                )
+
+        gr.Markdown("---")
+        gr.Markdown("*FleetMind MCP v1.0.0 - Built with Gradio, PostgreSQL, and FastMCP*")
+
+    return app
+
+
+# ============================================
+# MAIN
+# ============================================
+
+if __name__ == "__main__":
+    print("=" * 60)
+    print("FleetMind MCP - Starting Gradio Server")
+    print("=" * 60)
+
+    # Check database connection
+    print("\nChecking database connection...")
+    if test_connection():
+        print("✅ Database connected")
+    else:
+        print("❌ Database connection failed")
+        print("Please check your .env file and PostgreSQL server")
+
+    print("\nStarting Gradio interface...")
+    print("=" * 60)
+
+    # Create and launch the interface
+    app = create_interface()
+    app.launch(
+        server_name="0.0.0.0",  # Allow external connections for HF Spaces
+        server_port=7860,
+        share=False,
+        show_error=True
+    )