ecoml 0.2.1

EcoML – Track, analyse and reduce ML carbon emissions inside Jupyter notebooks.

EcoML 🌿

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

---

Install

pip install ecoml

To also enable Gemini AI tips (recommended):

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

---

Quick Start

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.

---

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