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

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

### 2. Run Demo Mode

```bash
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

```bash
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

```bash
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

```python
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

```python
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>