Metadata-Version: 2.4
Name: eco-route
Version: 0.5.0
Summary: Thermal-aware GPU tensor routing with Active Carbon Mitigation for energy-efficient deep learning
Author: Eco-Route Research Team
License: MIT
Project-URL: Homepage, https://github.com/Navaneeth270/eco-route
Project-URL: Repository, https://github.com/Navaneeth270/eco-route
Project-URL: Issues, https://github.com/Navaneeth270/eco-route/issues
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.24.0
Requires-Dist: scikit-learn>=1.3.0
Requires-Dist: pynvml>=11.5.0
Requires-Dist: psutil>=5.9.0
Requires-Dist: rich>=13.0.0
Provides-Extra: dashboard
Requires-Dist: streamlit>=1.30.0; extra == "dashboard"
Requires-Dist: streamlit-autorefresh>=1.0.1; extra == "dashboard"
Requires-Dist: pandas>=2.0.0; extra == "dashboard"
Requires-Dist: plotly>=5.18.0; extra == "dashboard"
Provides-Extra: train
Requires-Dist: tensorflow>=2.12.0; extra == "train"
Provides-Extra: tray
Requires-Dist: pystray>=0.19.0; extra == "tray"
Requires-Dist: Pillow>=10.0.0; extra == "tray"
Provides-Extra: all
Requires-Dist: eco-route[dashboard,train,tray]; extra == "all"
Dynamic: license-file

# Eco-Route

**Thermal-Aware Dynamic Tensor Routing & Active Carbon Mitigation for Energy-Efficient Deep Learning**

Eco-Route is a Python framework that bridges hardware physics (thermals, power draw) with software orchestration (dynamic tensor routing). It monitors NVIDIA GPUs in real-time, predicts thermal throttling before it happens, migrates workloads to cooler devices, and actively reduces carbon emissions by adjusting GPU power limits based on grid carbon intensity.

## Installation

```bash
# Core package (CLI + monitoring)
pip install eco-route

# With web dashboard
pip install eco-route[dashboard]

# With TensorFlow training benchmark
pip install eco-route[train]

# With system tray app
pip install eco-route[tray]

# Everything
pip install eco-route[all]
```

**Or install from GitHub:**

```bash
pip install git+https://github.com/Navaneeth270/eco-route.git
```

## Requirements

- Python 3.10+
- NVIDIA GPU with drivers installed (the tool will clearly tell you if no GPU is detected)
- No GPU? You can still explore with `--synthetic` mode for testing

## Quick Start

```bash
# Check your system
eco-route info

# Live terminal monitor
eco-route monitor

# Launch web dashboard
eco-route dashboard

# Run training benchmark
eco-route train --steps 200 --batch-size 64

# System tray icon
eco-route tray
```

### No GPU? No Problem

If you don't have an NVIDIA GPU, Eco-Route tells you clearly instead of faking data:

```
+------------------------------- GPU Not Found --------------------------------+
| No NVIDIA GPU detected on this system.                                       |
|                                                                              |
| Reason: NVIDIA driver not available (NVML Shared Library Not Found)          |
|                                                                              |
| Eco-Route requires an NVIDIA GPU with proper drivers to monitor              |
| real hardware telemetry (temperature, power draw, clock speed).              |
|                                                                              |
| To run with simulated data for testing, use:                                 |
|   eco-route monitor --synthetic                                              |
+------------------------------------------------------------------------------+
```

For testing and development, use synthetic mode:

```bash
eco-route monitor --synthetic
eco-route train --synthetic --steps 100
```

## Features

### Real-Time GPU Monitoring
- Temperature, power draw, clock speed, utilization via NVIDIA NVML
- Energy consumption tracking (Joules, kWh) with trapezoidal integration
- Carbon footprint estimation using grid carbon intensity

### Thermal-Aware Tensor Routing
- Predicts GPU temperature 3 seconds ahead using scikit-learn
- Automatically migrates TensorFlow operations to cooler GPUs
- Cooldown mechanism prevents migration oscillation

### Active Carbon Mitigation (ACM)
- Monitors real-time grid carbon intensity
- Dynamically caps GPU power based on grid cleanliness:
  - **Clean grid** (<200 gCO2/kWh): Full power
  - **Moderate grid** (200-400 gCO2/kWh): 85% power
  - **Dirty grid** (>400 gCO2/kWh): 60% power
- Tracks carbon saved vs. training time trade-off

### Web Dashboard
- Real-time Streamlit dashboard with Plotly charts
- Live GPU metrics, grid carbon intensity, power draw
- Carbon Mitigation Impact visualizations (publication-ready)
- ACM toggle and training controls

### System Tray App
- Taskbar icon with live GPU temperature (color-coded by grid zone)
- Quick access to dashboard and ACM toggle

## Architecture

```
eco_route/
  telemetry.py        Async NVML GPU monitor + energy accounting
  predictor.py        Thermal forecaster (scikit-learn)
  router.py           TensorFlow device routing + ACM integration
  carbon_controller.py  Active Carbon Mitigation engine
  train_loop.py       Benchmark training loop with analytical report
  cli.py              Command-line interface
  tray_app.py         System tray application
  mock_hardware.py    Synthetic GPU telemetry for testing

app/
  dashboard.py        Streamlit web dashboard
```

## CLI Reference

| Command | Description |
|---|---|
| `eco-route info` | System hardware and framework detection report |
| `eco-route monitor` | Live terminal GPU & carbon monitor |
| `eco-route monitor --synthetic` | Monitor with simulated GPU data |
| `eco-route dashboard` | Launch Streamlit web dashboard |
| `eco-route dashboard --port 8502` | Dashboard on custom port |
| `eco-route train --steps 200` | Run training benchmark |
| `eco-route train --synthetic --no-acm` | Baseline without ACM |
| `eco-route tray` | Start system tray icon |

## License

MIT
