PROJECT_SPEC.md

# 🚛 LogisticsShipmentRL — Environment Specification

> **Event:** Meta PyTorch OpenEnv Hackathon 2026  
> **Domain:** Supply Chain / Route Optimization  
> **Type:** Multi-Agent Reinforcement Learning Environment

## 1. Concept

**LogisticsShipmentRL** is a multi-step Reinforcement Learning environment built on the OpenEnv framework. An LLM agent acts as an **AI Logistics Coordinator**. The agent handles real-world supply chain disruptions — truck breakdowns, port congestion, weather delays, customs holds — by making intelligent re-routing and communication decisions under time pressure.

## 2. Gameplay & Rules

Each episode represents a **5-hour coordination window** (5 steps total). Every step simulates one hour of real-world time.

The agent receives a **shipment network snapshot** containing:
- 🚛 **Active Shipments:** 5–12 active shipments with SLA deadlines.
- ⚠️ **Disruptions:** 2–5 active events like port congestion, strikes, or bad weather.
- 🔄 **Routes:** Alternative routes with varying costs and delivery times.
- 📡 **Live Updates:** Feedback dynamically injected per step.

**The agent's objective is to:**
1. Re-route delayed shipments to bypass disruptions.
2. Prioritize high-value and perishable cargo.
3. Communicate clear ETA updates to affected customers.

## 3. Communication Contract (API)

### Agent -> Environment (Action)
The LLM agent must respond with a JSON object conforming to the `LogisticsAction` Pydantic model:
- `reasoning`: Chain-of-thought analysis explaining strategy.
- `rerouting_decisions`: Dictionary mapping shipment IDs to new routes.
- `priority_shipments`: List of up to 3 shipment IDs to fast-track.
- `customer_communications`: Dictionary of messages to send to customers.
- `escalations`: Any shipments needing a human dispatcher.

### Environment -> Agent (Observation)
The environment provides the current state via the `LogisticsObservation` Pydantic model:
- `network_snapshot`: Rich natural language description of the state.
- `active_shipments`: List of shipments and their individual statuses/SLAs.
- `disruption_events`: Active disruptions and estimated completion times.
- `available_routes`: Routes and their live viability.
- `current_total_delay_hours`: Network health metric.

## 4. Evaluation (Grader)

The environment calculates a float reward (0.0 to 1.0) based on shaped constraints:
1. **Delay Reduction (40%):** Total delay hours saved vs. a do-nothing baseline.
2. **Cost Efficiency (30%):** Re-routing cost relative to SLA breach penalty avoided.
3. **SLA Compliance (20%):** Percentage of shipments successfully delivered within the SLA window.
4. **Communication Quality (10%):** LLM-judged clarity and professionalism of the `customer_communications` output.

## 5. Development Roadmap

- [ ] Project directory initialization (`openenv.yaml`, `__init__.py`).
- [ ] Define precise domain models (`models.py`).
- [ ] Implement client interface for OpenEnv (`client.py`).
- [ ] Create the server backend for state management and simulation (`server/logistics_environment.py`).
- [ ] Build the reward calculation logic (`server/grader.py`).
- [ ] Design the procedural scenario generator (`server/scenarios.py`).
- [ ] Finalize the interactive FastAPI app (`server/app.py`).