README.md

metadata

title: SST and HUG Autonomous Supply Chain
emoji: 🚢
colorFrom: blue
colorTo: green
sdk: docker
app_port: 7860

---

SST & HUG — Autonomous Supply Chain Simulator

A premium, interactive reinforcement learning environment and web application designed for the OpenEnv Hackathon. This project simulates a global supply chain where users—or AI agents—must optimize orders, manage warehouse inventory, and navigate geopolitical shocks and demand volatility.

🌟 Hackathon Materials & Links

• 📝 Hugging Face Mini-Blog Writeup
• 🚀 Hugging Face Space
• 🧠 Self-Contained Training Notebook (Unsloth + TRL)

📈 Training Results & Evidence

We trained an AI Logistics Agent using Proximal Policy Optimization (PPO) via Hugging Face TRL and Unsloth. The model learns to avoid stockouts and minimize shipping delays while preserving the initial capital benchmark.

Below are the learning curves demonstrating convergence from a random baseline to a profitable policy:

Features

• Global Logistics Network: Interactive vector-based world map showing live factory costs and port delays.
• AI Oracle: Generates strategic advisory based on real-time simulation events (e.g., port closures, demand spikes).
• Auto-Play Agent: A built-in heuristic agent that automatically evaluates demand and routes optimal shipments.
• Dynamic Scenarios: Switch between Normal, Crisis, and Growth modes to stress-test your supply chain.
• Full Analytics Suite: Real-time Recharts tracking balance vs AI benchmark, lifetime cost allocation, and revenue flow.
• Hackathon Ready: Beautiful "cyber-aesthetic" glassmorphism design, fully responsive, and export-ready data tracking.

Technology Stack

• Backend: Python, FastAPI, Uvicorn
• Frontend: React 19, Vite, Recharts, Lucide React, React Simple Maps, React Hot Toast
• Deployment: Dockerized for seamless deployment to Hugging Face Spaces

Local Development Setup

1. Start the Backend

   cd server
   pip install -r requirements.txt
   python main.py
   

   The backend will run on http://localhost:8000.

2. Start the Frontend

   npm install
   npm run dev
   

   The frontend will run on http://localhost:5173.

Hugging Face Spaces / Docker Deployment

The application includes a Dockerfile that builds the React frontend and serves it using the FastAPI backend, making it perfectly suited for a one-click Hugging Face Spaces deployment.

1. Build the Image

   docker build -t sst-hug-simulator .
   

2. Run the Container

   docker run -p 7860:7860 sst-hug-simulator
   

   The full application will be accessible at http://localhost:7860.

Architecture & Integration

• server/main.py: The core state machine and FastAPI routes. Handles all game logic, random shocks, and AI Oracle generation.
• server/openenv_wrapper.py: An OpenEnv-compliant reinforcement learning wrapper (SupplyChainEnv) for training custom LLMs/agents.
• src/App.jsx: The comprehensive React dashboard.

Acknowledgements

Built for the OpenEnv Hackathon.