AI_engine/README.md

🤖 LogiFlow AI - Autonomous Logistics Agent System

A complete multi-agent AI system for autonomous logistics operations. Built with Python, featuring 8 intelligent agents coordinated by a master orchestrator (JARVIS).

🏗️ Architecture

                    ┌─────────────────────────────────────────┐
                    │         🧠 JARVIS (Master Agent)          │
                    │   Central orchestrator & decision maker  │
                    └─────────────────┬─────────────────────────┘
                                      │
        ┌─────────────────────────────┼─────────────────────────────┐
        │                             │                             │
        ▼                             ▼                             ▼
┌───────────────┐           ┌─────────────────┐           ┌─────────────────┐
│ ORDER_AGENT   │           │ DISPATCH_AGENT  │           │  FLEET_AGENT    │
│ ─────────────│           │ ────────────────│           │ ────────────────│
│ • Receive     │           │ • Analyze zones │           │ • Vehicle status│
│ • Validate    │           │ • Assign routes │           │ • Capacity mgmt  │
│ • Categorize  │           │ • Route opt.    │           │ • Maintenance    │
└───────────────┘           └─────────────────┘           └─────────────────┘
        │                             │                             │
        ▼                             ▼                             ▼
┌───────────────┐           ┌─────────────────┐           ┌─────────────────┐
│ HUB_AGENT     │           │ CUSTOMER_AGENT  │           │ EXCEPTION_AGENT │
│ ─────────────│           │ ────────────────│           │ ────────────────│
│ • Hub routing │           │ • Notifications │           │ • Delay handling│
│ • Transit mgmt│           │ • Tracking      │           │ • Rescheduling  │
│ • Capacity    │           │ • Feedback      │           │ • Cancellations │
└───────────────┘           └─────────────────┘           └─────────────────┘
                                      │
                                      ▼
                           ┌─────────────────┐
                           │ROUTE_OPTIMIZER  │
                           │ ────────────────│
                           │ • Zone planning │
                           │ • Pathfinding   │
                           │ • Traffic adapt │
                           └─────────────────┘

✨ Features

🤖 Intelligent Agents

Agent	Function	Key Capabilities
JARVIS	Master Orchestrator	Task delegation, system monitoring, decision making
ORDER_AGENT	Order Management	Receive, validate, categorize orders by priority/zone
DISPATCH_AGENT	Route Assignment	Zone analysis, hub assignment, route planning
FLEET_AGENT	Vehicle Management	Capacity tracking, vehicle assignment, maintenance
HUB_AGENT	Hub Operations	Transit management, capacity monitoring, overflow handling
CUSTOMER_AGENT	Customer Communication	Notifications, tracking updates, support
EXCEPTION_AGENT	Problem Resolution	Delay handling, cancellations, rescheduling
ROUTE_OPTIMIZER	Route Planning	Zone-based optimization, path calculation

🔄 Agent Communication Flow

Order Received → ORDER_AGENT validates → DISPATCH_AGENT assigns route
     ↓                                    ↓
FLEET_AGENT assigns vehicle    →     HUB_AGENT prepares receiving
     ↓                                    ↓
ROUTE_OPTIMIZER calculates path   →     CUSTOMER_AGENT sends notification
     ↓
EXCEPTION_AGENT monitors (handles any issues)
     ↓
JARVIS monitors all agents, logs decisions, reports to admin

🚀 Quick Start

1. Install Dependencies

cd /workspace/project/logistics-ai
pip install -r requirements.txt

2. Run Demo Mode

python main.py

This will:

• Initialize all 8 agents
• Run system diagnostics
• Process a sample order through all agents
• Display complete agent coordination

3. Launch Admin Dashboard

python main.py --dashboard

Opens Streamlit dashboard at http://localhost:8501 with:

• Real-time agent status monitoring
• Order management
• Fleet tracking
• Hub network visualization
• Message feed

4. Launch Customer Portal

python main.py --portal

Opens customer-facing portal at http://localhost:8502 with:

• Order tracking
• Live updates
• AI assistant chat
• Delivery scheduling

📁 Project Structure

logistics-ai/
├── main.py                    # Main orchestration & demo
├── requirements.txt           # Python dependencies
├── core/
│   ├── __init__.py
│   ├── types.py              # Data models & message types
│   ├── agent.py              # Base Agent, MasterAgent classes
│   └── message_bus.py        # Agent communication bus
├── agents/
│   ├── __init__.py
│   ├── order_agent.py         # Order validation & categorization
│   ├── dispatch_agent.py       # Route assignment & zone analysis
│   ├── fleet_agent.py         # Vehicle management
│   ├── hub_agent.py           # Hub operations & transit
│   ├── customer_agent.py      # Notifications & tracking
│   ├── exception_agent.py      # Problem resolution
│   └── route_optimizer_agent.py # Route optimization
├── dashboard/
│   └── admin_dashboard.py     # Streamlit admin interface
├── customer_portal/
│   └── portal.py              # Streamlit customer interface
└── config/
    └── system_config.py       # Configuration & zone definitions

🔧 Configuration

Edit config/system_config.py to customize:

• Zones: Pincode ranges and hub assignments
• Hubs: Capacity, processing rates, connections
• Vehicles: Types, capacities, fuel costs
• SLA: Delivery windows, response times
• Notifications: Templates for SMS/Email/WhatsApp

🎯 Usage Examples

Create an Order via API

from main import LogiFlowAI

system = LogiFlowAI()
system.initialize_agents()

order = {
    "customer_name": "Rajesh Kumar",
    "customer_phone": "+919876543210",
    "pickup_address": {"city": "Delhi", "pincode": "110001"},
    "delivery_address": {"city": "Mumbai", "pincode": "400001"},
    "items": [{"name": "Laptop", "weight": 2.5}]
}

await system.create_order(order)

Monitor System Status

status = system.get_system_status()
print(f"Active agents: {len(status['agents'])}")
print(f"System: {status['system']}")

🔌 Integration Points

REST API (Future)

• POST /orders - Create new order
• GET /orders/{id} - Get order status
• PATCH /orders/{id} - Update order
• GET /agents/status - Get agent statuses
• POST /agents/{id}/task - Submit task to agent

Webhook Support (Future)

• Order created
• Order status changed
• Exception detected
• Delivery completed

📊 Monitoring

The system provides:

• Real-time agent status
• Message traffic monitoring
• Performance metrics
• Exception alerts
• SLA compliance tracking

🔒 Security

• Agent authentication via tokens
• Message signing and verification
• Rate limiting on API endpoints
• Audit logging for all operations

🚀 Scaling

The architecture supports:

• Horizontal agent scaling
• Multiple message bus instances
• Distributed hub networks
• Multi-region deployment

📝 License

MIT License - See LICENSE file

🤝 Contributing

Contributions welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Add tests for new features
4. Submit a pull request

---

Built with ❤️ for autonomous logistics operations

Resume this session with: claude --resume d1f8a432-2298-4ff5-bee4-15e64d04bfa4 PS C:\Users\Admin\Downloads\logiflow-ai-logistics-agent-system\logistics-ai>