README.md

# 🛡️ Aegis — Autonomous Enterprise Crisis Management

> **AMD Developer Hackathon 2026** | Track 1: AI Agents & Agentic Workflows

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Python](https://img.shields.io/badge/Python-3.11-blue.svg)](https://python.org)
[![FastAPI](https://img.shields.io/badge/FastAPI-0.110-green.svg)](https://fastapi.tiangolo.com)
[![Groq](https://img.shields.io/badge/LLM-Groq%20LLaMA%203.3%2070B-orange.svg)](https://groq.com)
[![AMD](https://img.shields.io/badge/GPU-AMD%20Instinct%20MI300X-red.svg)](https://amd.com)
[![ROCm](https://img.shields.io/badge/ROCm-6.2-red.svg)](https://rocm.docs.amd.com)

**Aegis** is a fully autonomous 7-agent AI system that monitors global supply chain risks in real time, scrapes live maritime shipping intelligence, predicts disruptions using a hybrid ML forecasting model, and autonomously executes crisis response decisions — before humans can react.

> *"Aegis protects enterprises from global disruptions by turning real-time chaos into autonomous decisions."*

---

## 🎬 Live Demo

| | |
|---|---|
| **Live App** | http://YOUR_AMD_INSTANCE_IP:8000 |
| **Demo Video** | https://youtu.be/w_jquBRuLkA |
| **API Docs** | http://YOUR_AMD_INSTANCE_IP:8000/docs |
| **GitHub** | https://github.com/Benny-Tang/aegis |

---

## 🌍 Real-World Relevance

Aegis was built as the **Strait of Hormuz crisis unfolded in real time** (2026). The exact scenario we demo — oil price spike, shipping disruption, geopolitical escalation — is actively happening right now. Our live MarineTraffic scraper pulls **real headlines** like:

- *"Trump's Hormuz Blockade Has Deepened A Historic Shipping Crisis"*
- *"Strait of Hormuz Remains Near-Empty With Just A Few Iran Ships Moving"*
- *"Iran War Leaves Seafarers Stranded In The Gulf"*
- *"US Says Navy Intercepted Iran-Linked Vessel in Arabian Sea"*

**Aegis responds to this real crisis autonomously in 2 seconds.**

---

## 🧠 How It Works

When a crisis event is detected, Aegis activates a chain of 7 specialized AI agents that observe, think, predict, simulate, decide, alert and act — autonomously.

```
Crisis Event Detected
        │
        ▼
┌─────────────────────────────────────────────────────┐
│                AEGIS 7-AGENT PIPELINE               │
│                                                     │
│  📡 Signal Agent      → Detects anomalies +         │
│                          scrapes live MarineTraffic  │
│  🧠 Intelligence Agent → Interprets risk context    │
│  📈 Forecast Agent    → ARIMA + XGBoost prediction  │
│  🧩 Simulation Agent  → Runs what-if scenarios      │
│  ⚡ Decision Agent    → Ranks action plan           │
│  🚨 Alert Agent       → Dispatches notifications    │
│  🔄 Execution Agent   → Triggers workflows          │
└─────────────────────────────────────────────────────┘
        │
        ▼
  Autonomous Response in ~2 seconds
  ($1.7M savings identified per crisis event)
```

---

## 🚢 Live MarineTraffic Intelligence

Aegis scrapes **real-time shipping intelligence** from multiple maritime sources on every crisis trigger:

| Source | Type | Status |
|--------|------|--------|
| gCaptain | Maritime news | ✅ Live |
| TradeWinds | Shipping intelligence | ✅ Live |
| MarineTraffic Blog | Vessel tracking news | ⚠️ Partial |
| Reuters | Geopolitical news | ⚠️ Auth required |

The Signal Agent automatically enriches every crisis analysis with live shipping alerts — tanker reroutes, port closures, war risk insurance changes, navy intercepts.

**Tested live — 8 real shipping intelligence items scraped in a single run with 95% CRITICAL confidence classification by Groq LLaMA 3.3 70B.**

---

## ⚙️ Tech Stack

| Layer | Technology |
|-------|-----------|
| **LLM** | Groq — LLaMA 3.3 70B Versatile |
| **ML Forecast** | XGBoost 2.0 + ARIMA(2,1,2) hybrid ensemble |
| **Marine Intelligence** | MarineTraffic + gCaptain + TradeWinds scraper |
| **GPU Acceleration** | AMD Instinct MI300X via ROCm 6.2 |
| **API** | FastAPI + Uvicorn + Gunicorn (4 workers) |
| **Streaming** | Server-Sent Events (SSE) — live agent updates |
| **Deployment** | AMD Developer Cloud (amd.digitalocean.com) |
| **Frontend** | Vanilla JS + CSS — dark terminal aesthetic |
| **Auto-Monitor** | Autonomous scan every 5 minutes 24/7 |

---

## 🚀 Quick Start

### Option A — Google Colab (easiest)
1. Open `Aegis_Hackathon.ipynb` in Google Colab
2. Fill in your `GROQ_API_KEY` and `NGROK_TOKEN` in Cell 1
3. Click **Runtime → Run All**
4. Copy the ngrok URL printed at the bottom

### Option B — AMD Developer Cloud (production)
```bash
# 1. SSH into your AMD MI300X instance
ssh -i your-key.ppk root@YOUR_AMD_IP

# 2. Set your Groq API key
export GROQ_API_KEY=gsk_YOUR_KEY_HERE

# 3. Install packages
pip3 install fastapi "uvicorn[standard]" groq httpx pydantic \
    numpy pandas scikit-learn xgboost statsmodels \
    python-multipart aiofiles gunicorn \
    requests beautifulsoup4 lxml

# 4. Create project folders
mkdir -p /opt/aegis/agents /opt/aegis/models /opt/aegis/api /opt/aegis/logs

# 5. Upload project files and start
cd /opt/aegis && gunicorn api.server:app \
    --workers 4 \
    --worker-class uvicorn.workers.UvicornWorker \
    --bind 0.0.0.0:8000 \
    --timeout 120 \
    --daemon

# 6. Open in browser
http://YOUR_AMD_IP:8000
```

---

## 📁 Project Structure

```
aegis/
├── agents/
│   └── swarm.py              # 7 Groq-powered autonomous agents
│                             # + MarineTraffic live scraper
├── models/
│   └── forecaster.py         # ARIMA + XGBoost hybrid ML model
├── api/
│   └── server.py             # FastAPI + SSE streaming server
├── frontend.html             # Live dashboard — dark terminal UI
├── Aegis_Hackathon.ipynb     # Google Colab notebook
├── requirements.txt          # Python dependencies
└── LICENSE                   # MIT License
```

---

## 🤖 The 7 Agents

### 1. 📡 Signal Agent (Watcher)
Monitors real-time feeds — oil prices, shipping routes, geopolitical news. **Automatically scrapes live MarineTraffic, gCaptain and TradeWinds shipping intelligence on every trigger.** Classifies anomalies by severity (LOW → CRITICAL) with confidence score.

### 2. 🧠 Intelligence Agent (Interpreter)
Uses LLaMA 3.3 70B to convert raw signals and marine data into structured risk context. Identifies root causes, affected regions, and escalation probability.

### 3. 📈 Forecast Agent (Predictor)
Runs a **hybrid ARIMA(2,1,2) + XGBoost ensemble** model to predict oil prices, logistics delays, and cost impact over a 14-day horizon. XGBoost runs on AMD MI300X GPU via ROCm for accelerated inference.

### 4. 🧩 Simulation Agent (Strategist)
Generates 3 weighted what-if scenarios (best case, base case, worst case) with probability weights and cost impact estimates for each.

### 5. ⚡ Decision Agent (Brain)
Synthesizes all upstream intelligence into a ranked action plan with dollar savings estimates, implementation timelines, and risk ratings.

### 6. 🚨 Alert Agent (Communicator)
Formats and dispatches real-time notifications to Slack, email, and live dashboard. Generates executive summaries for C-suite stakeholders.

### 7. 🔄 Execution Agent (Operator)
Triggers downstream enterprise workflows autonomously — ERP supplier switches, procurement API calls, logistics rerouting.

---

## 📊 ML Forecasting Model

**Why ARIMA + XGBoost hybrid?**

| Component | Role | Weight (crisis) |
|-----------|------|-----------------|
| ARIMA(2,1,2) | Linear trend + autocorrelation | 30% |
| XGBoost (ROCm GPU) | Non-linear geopolitical signals | 70% |

**Features engineered:** lag-1, lag-3, lag-7, lag-14, rolling mean/std (7 & 14 day), 3-day % change, day-of-week

**AMD MI300X advantage:** XGBoost tree building runs 8–15x faster on MI300X vs CPU via ROCm CUDA compatibility layer.

---

## 🔌 API Reference

| Method | Endpoint | Description |
|--------|----------|-------------|
| `GET` | `/` | Live dashboard |
| `GET` | `/health` | System health check |
| `GET` | `/docs` | Swagger UI |
| `POST` | `/api/crisis` | Full 7-agent pipeline (JSON) |
| `GET` | `/api/stream` | SSE live agent stream |
| `POST` | `/api/forecast` | ML forecast only |
| `GET` | `/api/marine` | Live MarineTraffic shipping feed |
| `GET` | `/api/status` | Live system status |

### Example — trigger crisis
```bash
curl -X POST http://YOUR_IP:8000/api/crisis \
  -H "Content-Type: application/json" \
  -d '{
    "oil_price_change_pct": 18.0,
    "shipping_disruption": "Strait of Hormuz — 3 tankers rerouted",
    "news_headline": "Regional conflict escalation near Persian Gulf",
    "severity": "HIGH",
    "disruption_factor": 0.7,
    "horizon_days": 14
  }'
```

### Example — get live marine intelligence
```bash
curl http://YOUR_IP:8000/api/marine
```

### Example — SSE stream
```javascript
const es = new EventSource('http://YOUR_IP:8000/api/stream?oil_change=18&disruption=0.7');
es.onmessage = (e) => {
  const msg = JSON.parse(e.data);
  console.log(msg.type, msg.agent, msg.data);
};
```

---

## 💡 Business Value

Aegis addresses a **$1.5 trillion annual problem** — global supply chain disruptions caused by geopolitical events, commodity shocks, and logistics failures.

**Key metrics from live demo (Strait of Hormuz crisis):**

| Metric | Value |
|--------|-------|
| Pipeline response time | **2 seconds** |
| Agents active simultaneously | **7 / 7** |
| Savings identified | **$1.7M per crisis** |
| Logistics delay risk detected | **45.8%** |
| Oil price forecast accuracy | ARIMA+XGBoost hybrid |
| Marine intelligence items | **8 live headlines** |
| Auto-monitoring interval | **Every 5 minutes** |
| Concurrent viewers supported | **Unlimited** |

---

## 🔥 Auto-Monitoring — 24/7 Autonomous Operation

Aegis doesn't wait for humans. It monitors global signals **every 5 minutes autonomously**:

- Fetches live oil price from status API
- Detects anomalies automatically
- Triggers full 7-agent pipeline when risk threshold exceeded
- Dashboard shows live countdown timer to next scan
- Zero human intervention required in production mode

---

## 🏗️ AMD Developer Cloud Deployment

```bash
# Verify MI300X is available
rocm-smi

# Check server health
curl http://localhost:8000/health

# View live marine intelligence
curl http://localhost:8000/api/marine

# Monitor logs
tail -f /opt/aegis/logs/error.log
```

---

## 📋 Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `GROQ_API_KEY` | ✅ Yes | Get free at console.groq.com |
| `NGROK_TOKEN` | Colab only | Get free at ngrok.com |

---

## 🙏 Acknowledgements

- **AMD** — MI300X GPU access via AMD Developer Cloud
- **Groq** — Ultra-fast LLaMA 3.3 70B inference
- **lablab.ai** — Hackathon platform and community
- **gCaptain** — Live maritime news intelligence
- **TradeWinds** — Live shipping intelligence
- **FastAPI** — Production API framework
- **XGBoost** — GPU-accelerated gradient boosting

---

## 📄 License

MIT License — see [LICENSE](LICENSE) for details.

---

*Built with ❤️ for the AMD Developer Hackathon 2026*

*🛡️ SHIELD AGAINST CHAOS*