Preet20/openenv-logistics

🌍 Global Logistics Dispatcher (OpenEnv)

![OpenEnv Compliant]() ![Python 3.11]() ![License: MIT]()

A stochastic, multi-modal supply chain simulator designed to test frontier LLMs on real-world freight consolidation, cold-chain management, and carbon-cost tradeoffs.

🚀 The Problem: Real-World Utility

Most AI benchmarks test simple logic puzzles or static Q&A. In the real enterprise world, AI agents are being deployed to manage supply chains—a domain defined by Pareto tradeoffs.

Global Logistics Dispatcher models the actual daily challenges of a freight forwarder. To succeed, an LLM agent must navigate:

1. 1.The Cold Chain: Perishable cargo decays daily. It must be routed through specific, expensive supports_reefer lanes.
2. 2.Consolidation Economics: Grouping cargo at the same node yields a massive 40% cost discount, forcing the AI to weigh the cost of "waiting" against the discount of "consolidating."
3. 3.The Carbon vs. Cost Dilemma: Air freight saves perishable food but destroys the sustainability index. Ocean freight is cheap and green but slow.
4. 4.Stochastic Chaos: A daily 15% probability of global disruptions (Port Strikes, Fuel Surcharges) forces the AI to dynamically reroute cargo mid-transit.

🧠 Environment Design & Mechanics

Observation Space

At each step, the environment provides the agent with the current state of the world, including active shipments, dynamic local routing options (edges), and active global alerts.

{
  "current_day": 2,
  "active_shipments": [
    {
      "id": "PERISH-BOM-01",
      "weight_kg": 500.0,
      "commodity": "perishable",
      "status": "warehoused",
      "current_node": "INBOM",
      "days_until_deadline": 10,
      "shelf_life_days_remaining": 8,
      "is_consolidated": false
    }
  ],
  "local_edges": {
    "INBOM": [
      {
        "edge_id": "LANE-002",
        "mode": "air",
        "cost_per_kg": 5.0,
        "transit_days": 1,
        "supports_reefer": true
      }
    ]
  },
  "global_alerts": ["SEVERE: Global port congestion expected."]
}

Action Space

The agent responds with a strictly typed JSON object mapping to one of three core logistics actions:

{
  "thought_process": "Brief explanation of the strategy.",
  "action_type": "dispatch_leg",
  "shipment_ids": ["PERISH-BOM-01"],
  "target_edge_id": "LANE-002"
}

📈 Task Difficulty & Progression

The environment exposes 3 strict tasks via reset(task_name="...") to evaluate agent scaling:

⚖️ Evaluation & Grader (0.0 to 1.0)

The environment features a deterministic mathematical grader that returns a strict 0.0 to 1.0 score based on the OpenEnv spec.

🏆 Baseline Scores

Running our baseline zero-shot LLM agent against the environment yields the following deterministic scores, proving the environment correctly scales in difficulty:

• —🟢 Easy: 1.0 / 1.0
• —🟡 Medium: 1.0 / 1.0
• —🔴 Hard: 0.63 / 1.0 (The agent struggles with the severe port strike penalty)

🛠️ Setup & Reproducibility

1. Local Installation

Clone the repository and install the dependencies:

git clone https://github.com/PreetHirani20/openenv-logistics.git
cd openenv-logistics
pip install -r requirements.txt

2. Run the OpenEnv Server

Launch the FastAPI environment physics engine:

uvicorn src.server:app --host 0.0.0.0 --port 7860

3. Run the Baseline Agent

In a separate terminal, run the baseline inference script. This script uses the standard OpenAI client to run all 3 OpenEnv tasks sequentially.

export OPENAI_API_KEY="sk-your-openai-key-here"
python inference.py

4. Docker & Hugging Face Spaces Deployment

The environment is fully containerized and ready for HF Spaces validation.

docker build -t openenv-logistics .
docker run -p 7860:7860 openenv-logistics

👤 Author & License

Author: Preet  |  License: MIT