Metadata-Version: 2.4
Name: ml-ecolyzer
Version: 1.1.1
Summary: Machine Learning Environmental Impact Analysis Framework supporting HuggingFace, scikit-learn, and PyTorch
Author: Jose Marie Antonio Minoza, Rex Gregor Laylo, Christian Villarin, Sebastian Ibanez
Author-email: Center for AI Research PH <contact@cair.ph>
Maintainer: Jose Marie Antonio Minoza
License: MIT
Project-URL: Homepage, https://github.com/JomaMinoza/ml-ecolyzer
Project-URL: Repository, https://github.com/JomaMinoza/ml-ecolyzer
Project-URL: Documentation, https://ml-ecolyzer.readthedocs.io
Project-URL: Bug Reports, https://github.com/JomaMinoza/ml-ecolyzer/issues
Project-URL: Paper, https://arxiv.org/abs/xxxx.xxxxx
Project-URL: PyPI, https://pypi.org/project/ml-ecolyzer
Project-URL: Discussions, https://github.com/JomaMinoza/ml-ecolyzer/discussions
Keywords: machine-learning,ml,environmental-impact,carbon-emissions,sustainability,pytorch,huggingface,scikit-learn,sklearn,benchmarking,green-ai,carbon-footprint,neural-networks
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: System :: Monitoring
Classifier: Topic :: Software Development :: Testing
Classifier: Environment :: Console
Classifier: Environment :: GPU :: NVIDIA CUDA
Classifier: Framework :: Jupyter
Classifier: Intended Audience :: Education
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.21.0
Requires-Dist: psutil>=5.8.0
Requires-Dist: codecarbon>=2.0.0
Requires-Dist: pandas>=1.3.0
Requires-Dist: tqdm>=4.60.0
Requires-Dist: pyyaml>=5.4.0
Requires-Dist: click>=8.0.0
Requires-Dist: typing-extensions>=4.0.0
Requires-Dist: scikit-learn>=1.0.0
Requires-Dist: joblib>=1.0.0
Provides-Extra: huggingface
Requires-Dist: torch>=1.9.0; extra == "huggingface"
Requires-Dist: transformers>=4.20.0; extra == "huggingface"
Requires-Dist: datasets>=2.0.0; extra == "huggingface"
Requires-Dist: diffusers>=0.10.0; extra == "huggingface"
Requires-Dist: evaluate>=0.3.0; extra == "huggingface"
Requires-Dist: sacrebleu>=2.0.0; extra == "huggingface"
Requires-Dist: accelerate>=0.20.0; extra == "huggingface"
Provides-Extra: sklearn
Requires-Dist: scikit-learn>=1.0.0; extra == "sklearn"
Requires-Dist: imbalanced-learn>=0.8.0; extra == "sklearn"
Requires-Dist: yellowbrick>=1.4.0; extra == "sklearn"
Requires-Dist: openpyxl>=3.0.0; extra == "sklearn"
Requires-Dist: xlrd>=2.0.0; extra == "sklearn"
Provides-Extra: pytorch
Requires-Dist: torch>=1.9.0; extra == "pytorch"
Requires-Dist: torchvision>=0.10.0; extra == "pytorch"
Requires-Dist: torchaudio>=0.9.0; extra == "pytorch"
Requires-Dist: pytorch-lightning>=1.5.0; extra == "pytorch"
Requires-Dist: torchmetrics>=0.6.0; extra == "pytorch"
Provides-Extra: gpu
Requires-Dist: nvidia-ml-py3>=7.352.0; extra == "gpu"
Requires-Dist: pynvml>=11.0.0; extra == "gpu"
Provides-Extra: audio
Requires-Dist: librosa>=0.8.0; extra == "audio"
Requires-Dist: soundfile>=0.10.0; extra == "audio"
Requires-Dist: jiwer>=2.0.0; extra == "audio"
Requires-Dist: torchaudio>=0.9.0; extra == "audio"
Provides-Extra: vision
Requires-Dist: opencv-python>=4.5.0; extra == "vision"
Requires-Dist: pillow>=8.0.0; extra == "vision"
Requires-Dist: torchvision>=0.10.0; extra == "vision"
Provides-Extra: tracking
Requires-Dist: wandb>=0.13.0; extra == "tracking"
Requires-Dist: rich>=12.0.0; extra == "tracking"
Provides-Extra: metrics
Requires-Dist: sentence-transformers>=2.0.0; extra == "metrics"
Requires-Dist: scipy>=1.7.0; extra == "metrics"
Provides-Extra: visualization
Requires-Dist: matplotlib>=3.5.0; extra == "visualization"
Requires-Dist: seaborn>=0.11.0; extra == "visualization"
Requires-Dist: plotly>=5.0.0; extra == "visualization"
Requires-Dist: ipywidgets>=7.6.0; extra == "visualization"
Provides-Extra: dev
Requires-Dist: pytest>=6.0; extra == "dev"
Requires-Dist: pytest-cov>=2.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: black>=21.0; extra == "dev"
Requires-Dist: flake8>=3.8; extra == "dev"
Requires-Dist: isort>=5.0; extra == "dev"
Requires-Dist: mypy>=0.900; extra == "dev"
Requires-Dist: pre-commit>=2.15.0; extra == "dev"
Requires-Dist: memory-profiler>=0.60.0; extra == "dev"
Provides-Extra: docs
Requires-Dist: sphinx>=4.0; extra == "docs"
Requires-Dist: sphinx-rtd-theme>=1.0; extra == "docs"
Requires-Dist: myst-parser>=0.15; extra == "docs"
Requires-Dist: sphinx-autodoc-typehints>=1.12; extra == "docs"
Requires-Dist: nbsphinx>=0.8.0; extra == "docs"
Requires-Dist: jupyter>=1.0.0; extra == "docs"
Provides-Extra: config
Requires-Dist: omegaconf>=2.1.0; extra == "config"
Requires-Dist: hydra-core>=1.1.0; extra == "config"
Provides-Extra: research
Requires-Dist: jupyter>=1.0.0; extra == "research"
Requires-Dist: notebook>=6.4.0; extra == "research"
Requires-Dist: ipykernel>=6.0.0; extra == "research"
Requires-Dist: requests>=2.25.0; extra == "research"
Provides-Extra: all
Requires-Dist: torch>=1.9.0; extra == "all"
Requires-Dist: transformers>=4.20.0; extra == "all"
Requires-Dist: datasets>=2.0.0; extra == "all"
Requires-Dist: diffusers>=0.10.0; extra == "all"
Requires-Dist: evaluate>=0.3.0; extra == "all"
Requires-Dist: sacrebleu>=2.0.0; extra == "all"
Requires-Dist: accelerate>=0.20.0; extra == "all"
Requires-Dist: imbalanced-learn>=0.8.0; extra == "all"
Requires-Dist: yellowbrick>=1.4.0; extra == "all"
Requires-Dist: openpyxl>=3.0.0; extra == "all"
Requires-Dist: xlrd>=2.0.0; extra == "all"
Requires-Dist: torchvision>=0.10.0; extra == "all"
Requires-Dist: torchaudio>=0.9.0; extra == "all"
Requires-Dist: pytorch-lightning>=1.5.0; extra == "all"
Requires-Dist: torchmetrics>=0.6.0; extra == "all"
Requires-Dist: nvidia-ml-py3>=7.352.0; extra == "all"
Requires-Dist: pynvml>=11.0.0; extra == "all"
Requires-Dist: librosa>=0.8.0; extra == "all"
Requires-Dist: soundfile>=0.10.0; extra == "all"
Requires-Dist: jiwer>=2.0.0; extra == "all"
Requires-Dist: opencv-python>=4.5.0; extra == "all"
Requires-Dist: pillow>=8.0.0; extra == "all"
Requires-Dist: wandb>=0.13.0; extra == "all"
Requires-Dist: rich>=12.0.0; extra == "all"
Requires-Dist: sentence-transformers>=2.0.0; extra == "all"
Requires-Dist: scipy>=1.7.0; extra == "all"
Requires-Dist: matplotlib>=3.5.0; extra == "all"
Requires-Dist: seaborn>=0.11.0; extra == "all"
Requires-Dist: plotly>=5.0.0; extra == "all"
Requires-Dist: ipywidgets>=7.6.0; extra == "all"
Requires-Dist: omegaconf>=2.1.0; extra == "all"
Requires-Dist: jupyter>=1.0.0; extra == "all"
Requires-Dist: requests>=2.25.0; extra == "all"
Requires-Dist: memory-profiler>=0.60.0; extra == "all"
Provides-Extra: minimal
Requires-Dist: scikit-learn>=1.0.0; extra == "minimal"
Requires-Dist: joblib>=1.0.0; extra == "minimal"
Provides-Extra: text
Requires-Dist: torch>=1.9.0; extra == "text"
Requires-Dist: transformers>=4.20.0; extra == "text"
Requires-Dist: datasets>=2.0.0; extra == "text"
Requires-Dist: evaluate>=0.3.0; extra == "text"
Requires-Dist: sacrebleu>=2.0.0; extra == "text"
Provides-Extra: cv
Requires-Dist: torch>=1.9.0; extra == "cv"
Requires-Dist: torchvision>=0.10.0; extra == "cv"
Requires-Dist: opencv-python>=4.5.0; extra == "cv"
Requires-Dist: pillow>=8.0.0; extra == "cv"
Provides-Extra: classical
Requires-Dist: scikit-learn>=1.0.0; extra == "classical"
Requires-Dist: imbalanced-learn>=0.8.0; extra == "classical"
Requires-Dist: yellowbrick>=1.4.0; extra == "classical"
Requires-Dist: openpyxl>=3.0.0; extra == "classical"
Requires-Dist: xlrd>=2.0.0; extra == "classical"
Dynamic: license-file

# ML-EcoLyzer

[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![PyPI version](https://badge.fury.io/py/ml-ecolyzer.svg)](https://badge.fury.io/py/ml-ecolyzer)

A framework for measuring the environmental impact of ML inference. Tracks CO2 emissions, energy consumption, and water usage across different hardware setups.

![ML-EcoLyzer Overview](docs/assets/ml_ecolyzer.png)

## Why?

Training gets all the attention, but inference runs 24/7 in production. We built this to answer: "How much does running this model actually cost the environment?"

## Install

Available on [PyPI](https://pypi.org/project/ml-ecolyzer/):

```bash
pip install ml-ecolyzer
```

With framework-specific dependencies:
```bash
pip install ml-ecolyzer[huggingface]  # transformers, diffusers
pip install ml-ecolyzer[pytorch]       # torchvision, torchaudio
pip install ml-ecolyzer[all]           # everything
```

## Quick Start

```python
from mlecolyzer import EcoLyzer

config = {
    "project": "my_analysis",
    "models": [{"name": "gpt2", "task": "text"}],
    "datasets": [{"name": "wikitext", "task": "text", "limit": 100}]
}

eco = EcoLyzer(config)
results = eco.run()

print(f"CO2: {results['final_report']['analysis_summary']['total_co2_emissions_kg']:.6f} kg")
print(f"Energy: {results['final_report']['analysis_summary']['total_energy_kwh']:.6f} kWh")
```

## What it measures

- **CO2 emissions** - Based on power draw and regional carbon intensity
- **Energy usage** - Via NVIDIA-SMI, psutil, or RAPL
- **Water footprint** - Cooling overhead varies by hardware tier
- **ESS (Environmental Sustainability Score)** - Parameters per gram of CO2, useful for comparing models

```
ESS = Effective Parameters (M) / CO2 (g)
```

Higher ESS = more efficient. INT8 models typically score ~74% higher than FP32.

## Supported setups

- GPUs: A100, T4, RTX series, GTX series
- CPU-only works too
- Frameworks: HuggingFace, PyTorch, scikit-learn

## Config file

```yaml
project: "benchmark_run"

models:
  - name: "facebook/opt-350m"
    task: "text"
    quantization:
      enabled: true
      target_dtype: "int8"

datasets:
  - name: "wikitext"
    task: "text"
    limit: 500

hardware:
  device_profile: "auto"

output:
  output_dir: "./results"
  export_formats: ["json", "csv"]
```

## CLI

```bash
# Single run
mlecolyzer analyze --model gpt2 --dataset wikitext --task text

# System info
mlecolyzer info
```

## Benchmarks

Ran 1,500+ inference configs across:
- Hardware: GTX 1650, RTX 4090, Tesla T4, A100
- Models: GPT-2, OPT, Qwen, LLaMA, Phi, Whisper, ViT
- Precisions: FP32, FP16, INT8

Key findings:
- A100 has poor ESS when underutilized (overkill for small batches)
- Consumer GPUs (RTX/T4) often more efficient for single-batch inference
- Quantization helps a lot, especially INT8

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md). PRs welcome.

```bash
# Dev setup
pip install -e ".[dev]"
pytest
```

## Citation

```bibtex
@inproceedings{mlecolyzer2025,
  title={ML-EcoLyzer: A Framework for Quantifying the Environmental Impact of Machine Learning Inference},
  author={Minoza, Jose Marie Antonio and Laylo, Rex Gregor and Villarin, Christian and Ibanez, Sebastian},
  booktitle={AAAI Workshop on AI for Environmental Science},
  year={2025}
}
```

## License

MIT
