# EcoML 🌿

**Track, analyse and reduce the carbon footprint of your ML experiments — directly inside Jupyter.**

[![PyPI version](https://badge.fury.io/py/ecoml.svg)](https://pypi.org/project/ecoml/)
[![Python](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)

---

## Install

```bash
pip install ecoml
```

To also enable Gemini AI tips (recommended):

```bash
pip install "ecoml[gpu]"   # + WMI GPU temp on Windows
```

---

## Quick Start

```python
import sys, pathlib
ROOT = pathlib.Path().resolve().parent
sys.path.insert(0, str(ROOT))

from ecoml import EcoTracker, CellHook, RecommendationEngine, GeminiAdvisor

tracker    = EcoTracker(log_path=str(ROOT / "data" / "emissions_log.csv"))
gemini     = GeminiAdvisor()                   # needs GEMINI_API_KEY in .env
recommender = RecommendationEngine(gemini=gemini)

hook = CellHook(tracker, recommender)
hook.register()
print("🌿 EcoML Ready")
```

After `hook.register()` every subsequent cell automatically shows:
- 🌿 **CO₂ produced** (grams)
- ⚙️ **Hardware recommendation** with confidence score
- 💡 **AI-powered tips** via Gemini
- 📊 **Eco Score** (0–100)

---

## What's New in v0.2.0

| Area | Improvement |
|------|------------|
| **Recommender** | 12 intelligent rules (RAM, vRAM, temps, runtime, CO₂, GPU/CPU bottlenecks) |
| **Confidence Score** | Dynamic 0–1 score based on how many issues are detected |
| **RAM Monitoring** | System RAM % and GPU VRAM % tracked per cell |
| **Gemini Prompts** | Rich context-aware prompts with all metrics for targeted advice |
| **Eco Score** | Physics-inspired formula penalising load, heat, runtime & carbon |
| **UI** | RAM/VRAM rows, colour-coded confidence badge, both CPU + GPU temps |

---

## Environment Setup

Create a `.env` file in your project root:

```
GEMINI_API_KEY=your_key_here
```

Get a free key at [aistudio.google.com](https://aistudio.google.com).

---

## Dependencies

Automatically installed with `pip install ecoml`:

- `psutil` — CPU / RAM metrics
- `GPUtil` — GPU utilisation & temperature
- `pandas` — CSV logging
- `scikit-learn` — ML-based hardware predictor
- `ipython` — Jupyter cell hooks
- `python-dotenv` — `.env` key loading
- `google-generativeai` — Gemini AI advisor

---

## License

MIT © EcoML Team
