README.md

---
title: NetZero Nav
emoji: 🌍
colorFrom: green
colorTo: blue
sdk: docker
pinned: false
---

# 🌍 NetZero Nav: Eco-Resilient Logistics

![Status](https://img.shields.io/badge/Status-Active_Simulation-brightgreen)
![Python](https://img.shields.io/badge/Python-3.10+-blue)
![FastAPI](https://img.shields.io/badge/Backend-FastAPI-009688)
![Frontend](https://img.shields.io/badge/Frontend-Vanilla_JS_|_CSS-f39c12)
![Deployment](https://img.shields.io/badge/Deployment-HuggingFace_Spaces-ffcc00)

**Autonomous RL logistics agent navigating global disruptions with a Net-Zero carbon mandate.**

## 📖 Overview
**NetZero Nav** is an AI agentic simulation environment built for logistics optimization. In modern supply chains, decision-making is a multi-objective problem: balancing financial costs, delivery speed, and environmental sustainability. This project simulates a supply chain command center where an agent (or human operator) manages electronic product manufacturing while adhering strictly to "Net-Zero" carbon quotas.

This interface serves as the visual playground and telemetry dashboard representing what an AI Reinforcement Learning (RL) agent interacts with behind the scenes via a custom FastAPI `/step` loop.

## ⚡ The Challenge
Every logistical decision involves a strategic trade-off:
- 🛳️ **Sea Freight ($10, 10 Days, 0.1kg CO2)**: Ultra-low carbon footprint and cheap, but extremely slow.
- ✈️ **Air Freight ($50, 2 Days, 2.0kg CO2)**: High speed fulfillment, but massive CO2 emissions and 5x the cost.
- 🚂 **Rail Freight ($25, 5 Days, 0.5kg CO2)**: The hybrid option for balanced regional resilience.

Operators must balance raw inventory against pending order fulfillment schedules to prevent bleeding capital, while ensuring they do not breach the 1,000kg Carbon Footprint limit.

## 🚀 Core Features
1. **Real-time Telemetry Dashboard**: A high-fidelity, reactive command console providing live readouts on Capital Balance, Carbon Footprint, and Raw Inventory limitations.
2. **Dynamic Order Routing & Cart Aggregation**: The environment automatically merges overlapping delivery constraints and cleanly manages multi-batch shipments in the `Your Orders` logistics stream.
3. **Disruption Management ("The Suez Jam")**: Triggering real-world crises blocks optimal ocean routes (e.g., SEA mode) for 7 simulation days. The agent must rapidly recompute air and rail alternatives without bankrupting the system or violating carbon quotas.
4. **ESG Strategic Offsetting**: Allows excess capital to be dynamically diverted into Carbon Offset programs, driving the footprint back down toward sustainable parameters.
5. **Headless Python RL Engine**: Driven entirely by a custom `NetZeroEnv` state machine with a strict Pydantic ruleset, validating constraints prior to DOM interaction.

## 🛠️ Tech Stack
- **Simulation Engine**: Custom Python RL Simulator (`env.py`)
- **Backend Infrastructure**: FastAPI (Handling continuous Step/Reset states)
- **Frontend Command Center**: Vanilla HTML/CSS/JS (Glassmorphic Enterprise aesthetic)
- **Deployment**: Fully dockerized & hosted on Hugging Face Spaces

## 💻 Getting Started
To run locally:
```bash
pip install fastapi uvicorn pydantic
uvicorn netzero_nav.server:app --host 0.0.0.0 --port 7860
```
Navigate to `http://localhost:7860/` to launch the Command Console.