---
---
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](https://huggingface.co/spaces/ishraddhapawar/Trade-Storm-AI/blob/main/BLOG_POST.md)** 
- **🚀 [Hugging Face Space](https://huggingface.co/spaces/ishraddhapawar/TRADE-STORM-AI)**
- **🧠 [Self-Contained Training Notebook (Unsloth + TRL)](TradeStorm_Training.ipynb)**

## 📈 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:

![Agent Training Curves](training_curves.png)

## 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**
   ```bash
   cd server
   pip install -r requirements.txt
   python main.py
   ```
   The backend will run on `http://localhost:8000`.

2. **Start the Frontend**
   ```bash
   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**
   ```bash
   docker build -t sst-hug-simulator .
   ```

2. **Run the Container**
   ```bash
   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.