e2am 0.1.0__tar.gz

e2am-0.1.0/.gitattributes

@@ -0,0 +1,7 @@
+# Normalize all text files to LF in the repository.
+* text=auto eol=lf
+*.png binary
+*.jpg binary
+*.pdf binary
+*.pt binary
+*.pth binary

e2am-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,48 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Install
+        run: pip install -e ".[dev]"
+      - name: Ruff
+        run: ruff check src tests
+      - name: Black
+        run: black --check src tests
+      - name: isort
+        run: isort --check-only src tests
+      - name: Mypy
+        run: mypy src/e2am
+
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+        python-version: ["3.10", "3.11", "3.12"]
+        exclude:
+          - os: windows-latest
+            python-version: "3.10"
+          - os: windows-latest
+            python-version: "3.12"
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install
+        run: pip install -e ".[dev]"
+      - name: Run tests (no GPU on CI runners)
+        run: pytest -m "not gpu" --cov=e2am --cov-report=term-missing

e2am-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,63 @@
+name: Release
+
+# Publishes to PyPI via trusted publishing (OIDC) when a version tag is pushed.
+# One-time setup on pypi.org: project "e2am" -> Publishing -> add GitHub
+# publisher (owner: Shanmuk4622, repo: e2am, workflow: release.yml,
+# environment: pypi).
+
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch: {}
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Build sdist and wheel
+        run: |
+          pip install build twine
+          python -m build
+          twine check dist/*
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  test:
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Install the built wheel and smoke-test it
+        run: |
+          pip install dist/*.whl
+          python -c "import e2am; print(e2am.__version__)"
+          e2am version
+          e2am hardware --json > /dev/null
+
+  publish:
+    runs-on: ubuntu-latest
+    needs: [build, test]
+    if: startsWith(github.ref, 'refs/tags/v')
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Publish to PyPI (trusted publishing)
+        uses: pypa/gh-action-pypi-publish@release/v1

e2am-0.1.0/.gitignore

@@ -0,0 +1,44 @@
+# Byte-compiled / caches
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# Environments
+.venv/
+venv/
+env/
+.conda/
+
+# Editors / OS
+.vscode/
+.idea/
+.DS_Store
+Thumbs.db
+
+# Experiment outputs
+results/
+runs/
+emissions.csv
+*.ckpt
+*.pth
+*.pt
+
+# Data
+data/
+datasets/
+
+# Docs build
+docs/_build/
+site/
+
+# Local claude settings
+.claude/settings.local.json
+.claude/launch.json

e2am-0.1.0/CHANGELOG.md

@@ -0,0 +1,57 @@
+# Changelog
+
+All notable changes to E2AM are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/) and the project adheres to
+[Semantic Versioning](https://semver.org/).
+
+## [0.1.0] — 2026-07-11
+
+First public release. 🌱
+
+### Added
+
+**Monitoring**
+- `with monitor(project=...)` context manager / decorator — zero-code-change
+  energy, carbon, and utilization tracking for any code block.
+- Background `MonitorSession` with per-device samplers: GPU (NVML live power
+  sensor, TDP × utilization fallback for cards without one), CPU
+  (TDP × utilization), RAM (~3 W per 8 GB used); live `snapshot()` totals.
+- Trapezoidal power→energy integration robust to irregular intervals and
+  missing readings; measured-vs-estimated flags on every device.
+- Region-aware carbon estimation (27-country intensity table, user override,
+  world-average fallback).
+
+**Profiling & metrics**
+- `profile_model`: hook-based MACs/FLOPs/params with an extensible counter
+  registry and honest parameter-coverage reporting.
+- `benchmark_latency`: warmed-up, CUDA-synchronized latency (mean/p50/p95)
+  and throughput. `MemoryTracker`: exact CUDA peak + host RSS delta.
+- Torch-native classification metrics (accuracy, macro/weighted P/R/F1).
+- Green AI metrics: energy/carbon per sample, accuracy-per-joule,
+  Green Score (`100·acc·E_ref/(E_ref+E)`), EAG (energy-accuracy gradient).
+
+**Training**
+- Drop-in `Trainer` with AMP, gradient accumulation, clipping, LR scheduler
+  support, callback lifecycle, `EarlyStopping`, and automatic integration of
+  monitoring + profiling + green metrics.
+
+**Outputs**
+- Automatic artifacts per run: 10 plots, self-contained `report.html`,
+  `README.md`, optional `report.pdf`, `metrics.json`, `summary.yaml`,
+  `config.yaml`, cross-run `leaderboard.csv`, local `dashboard.html`.
+
+**CLI**
+- `e2am hardware | train | benchmark | report | compare | optimize | dashboard`.
+- `benchmark` reports energy per inference (joules) via live monitoring.
+- `optimize`: rule-based efficiency suggestions with quantified Wh savings
+  (wasted-epoch detection, AMP, batch size, torch.compile, checkpointing,
+  quantization).
+
+**Integrations**
+- Plugins (all Trainer callbacks): Weights & Biases, MLflow, TensorBoard,
+  Slack, Discord (webhooks are stdlib-only).
+- Hugging Face: `E2AMCallback` for `transformers.Trainer`.
+
+### Notes
+- Python ≥ 3.10. PyTorch is a peer dependency (install the build matching
+  your hardware); monitoring works without it.

e2am-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,62 @@
+# Contributing to E2AM
+
+Thanks for helping make AI training measurably greener! 🌱
+
+## Development setup
+
+```bash
+git clone https://github.com/Shanmuk4622/e2am.git
+cd e2am
+python -m venv .venv && source .venv/bin/activate   # or your conda env
+pip install -e ".[dev,pdf]"
+```
+
+PyTorch is a peer dependency — install the build matching your hardware from
+[pytorch.org](https://pytorch.org/get-started/locally/).
+
+## Quality gate
+
+Every PR must pass the same gate CI runs:
+
+```bash
+ruff check src tests
+black --check src tests
+isort --check-only src tests
+mypy src/e2am
+pytest -m "not gpu"        # GPU tests run only on machines with an NVIDIA GPU
+```
+
+On a GPU machine, also run the full suite: `pytest`.
+
+## Design rules of the codebase
+
+- **Graceful degradation** — no GPU, no power sensor, no torch: E2AM must
+  still work, estimating (and *labeling* the estimate) where it cannot measure.
+- **Never crash user training** — samplers, callbacks, and report generation
+  are failure-isolated; a monitoring bug must not kill an 8-hour run.
+- **Honesty over false precision** — anything estimated is flagged as
+  estimated in results, reports, and plots.
+- **One implementation** — the CLI orchestrates the Python API; it never
+  reimplements it.
+- **Torch stays optional at import time** — `import e2am` and monitoring work
+  without PyTorch; torch-backed modules are imported lazily.
+
+## Style
+
+Python ≥ 3.10, full type hints, Google-style docstrings, `ruff`/`black`/`isort`
+formatting (line length 100). Tests use plain `pytest` with markers `gpu`,
+`torch`, `slow`. New metrics or samplers need hand-computed expected values in
+their tests, not just "doesn't crash".
+
+## Adding a sampler / metric / report
+
+- New device sampler: subclass `e2am.monitoring.samplers.Sampler`, register in
+  `create_samplers`, never raise from `sample()`.
+- New MAC counter: `e2am.profiler.register_mac_counter(YourModule, fn)`.
+- New report format: consume `e2am.reports.common.build_sections` so every
+  format stays in sync.
+
+## Reporting issues
+
+Include your OS, Python, torch version, GPU/driver, and the output of
+`e2am hardware --json`.

e2am-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Satyanarayana (Shanmuk4622) and E2AM contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

e2am-0.1.0/PKG-INFO

@@ -0,0 +1,273 @@
+Metadata-Version: 2.4
+Name: e2am
+Version: 0.1.0
+Summary: E2AM — Energy Efficient AI Models: automatic energy, carbon, and performance profiling for AI training.
+Project-URL: Homepage, https://github.com/Shanmuk4622/e2am
+Project-URL: Repository, https://github.com/Shanmuk4622/e2am
+Project-URL: Issues, https://github.com/Shanmuk4622/e2am/issues
+Author-email: Satyanarayana <shanmukesh.bonala@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2026 Satyanarayana (Shanmuk4622) and E2AM contributors
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: benchmarking,carbon-emissions,energy-efficiency,green-ai,mlops,profiling,pytorch,sustainability
+Classifier: Development Status :: 3 - Alpha
+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.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: System :: Monitoring
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: matplotlib>=3.6
+Requires-Dist: numpy>=1.23
+Requires-Dist: nvidia-ml-py>=11.495.46
+Requires-Dist: psutil>=5.9
+Requires-Dist: pydantic>=2.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.0
+Requires-Dist: typer>=0.9
+Provides-Extra: all
+Requires-Dist: codecarbon>=2.3; extra == 'all'
+Requires-Dist: plotly>=5.18; extra == 'all'
+Requires-Dist: reportlab>=4.0; extra == 'all'
+Provides-Extra: carbon
+Requires-Dist: codecarbon>=2.3; extra == 'carbon'
+Provides-Extra: dashboard
+Requires-Dist: plotly>=5.18; extra == 'dashboard'
+Provides-Extra: dev
+Requires-Dist: black>=24.0; extra == 'dev'
+Requires-Dist: isort>=5.13; extra == 'dev'
+Requires-Dist: mypy>=1.8; extra == 'dev'
+Requires-Dist: pandas>=1.5; extra == 'dev'
+Requires-Dist: pre-commit>=3.5; extra == 'dev'
+Requires-Dist: pytest-cov>=4.1; extra == 'dev'
+Requires-Dist: pytest>=7.4; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Requires-Dist: types-psutil; extra == 'dev'
+Requires-Dist: types-pyyaml; extra == 'dev'
+Provides-Extra: pdf
+Requires-Dist: reportlab>=4.0; extra == 'pdf'
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+# ⚡ E2AM — Energy Efficient AI Models
+
+**Automatic energy, carbon, and performance profiling for AI training — with almost zero code changes.**
+
+[![CI](https://github.com/Shanmuk4622/e2am/actions/workflows/ci.yml/badge.svg)](https://github.com/Shanmuk4622/e2am/actions/workflows/ci.yml)
+[![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)
+[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+
+</div>
+
+---
+
+E2AM makes AI model training automatically measurable in terms of **energy efficiency**,
+**carbon emissions**, **computational cost**, and **model performance**. Think of it as
+*Weights & Biases + CodeCarbon + PyTorch Profiler* for **Green AI** — in one lightweight toolkit
+for researchers, ML engineers, universities, and companies.
+
+## Quickstart
+
+Wrap any training code:
+
+```python
+from e2am import monitor
+
+with monitor(project="ResNet50"):
+    train()
+```
+
+Or use the drop-in trainer:
+
+```python
+from e2am import Trainer
+
+trainer = Trainer(
+    model=model,
+    optimizer=optimizer,
+    train_loader=train_loader,
+    val_loader=val_loader,
+)
+trainer.fit()
+```
+
+Everything else happens automatically: energy, carbon, utilization, FLOPs, timing,
+accuracy metrics, plots, and reports land in `results/`.
+
+## Installation
+
+```bash
+pip install e2am            # once published; until then:
+pip install git+https://github.com/Shanmuk4622/e2am.git
+```
+
+> **Note:** PyTorch is not installed automatically — install the build matching your
+> hardware from [pytorch.org](https://pytorch.org/get-started/locally/). Monitoring
+> works even without PyTorch.
+
+Optional extras:
+
+```bash
+pip install "e2am[carbon]"     # CodeCarbon-backed carbon tracking
+pip install "e2am[pdf]"        # PDF reports (reportlab)
+pip install "e2am[dashboard]"  # interactive dashboards (plotly)
+pip install "e2am[all]"        # everything
+```
+
+## What E2AM measures
+
+| Category    | Metrics                                                                 |
+| ----------- | ----------------------------------------------------------------------- |
+| Energy      | GPU / CPU / RAM energy (Wh), power draw over time, energy per sample    |
+| Carbon      | CO₂eq emissions, carbon per sample, region-aware carbon intensity       |
+| Compute     | FLOPs, MACs, parameters, GPU/CPU utilization, peak memory               |
+| Time        | Training / epoch / batch time, latency, throughput                      |
+| Quality     | Accuracy, precision, recall, F1                                          |
+| Green AI    | Accuracy per joule, **Green Score**, **EAG** (Energy-Accuracy Gradient) |
+
+## Automatic outputs
+
+```
+results/<run_name>/
+    accuracy.png   loss.png      energy.png     power.png
+    gpu_usage.png  cpu_usage.png memory.png     carbon.png
+    latency.png    throughput.png
+    report.html    report.pdf
+    metrics.json   leaderboard.csv
+    config.yaml    README.md
+```
+
+## Architecture
+
+```
+e2am/
+    trainer/         # drop-in Trainer with callback lifecycle
+    monitor/         # background samplers: GPU (NVML), CPU, RAM, carbon
+    profiler/        # FLOPs / MACs / params, latency, memory
+    metrics/         # classification + Green AI metrics
+    benchmark/       # model/hardware benchmarking
+    reports/         # HTML / PDF / JSON / Markdown report generation
+    visualization/   # publication-quality plots
+    dashboard/       # interactive dashboard
+    plugins/         # W&B, MLflow, TensorBoard, Slack, Discord, HF
+    cli/             # `e2am` command line
+    config/          # typed, YAML-loadable configuration
+    utils/           # hardware detection, logging, timing
+```
+
+Design principles: SOLID, clean architecture, graceful degradation (no GPU? no NVML power
+sensor? no problem — E2AM falls back to utilization-based estimation), and zero required
+code changes to your training loop.
+
+## CLI
+
+```bash
+e2am hardware                                   # detected hardware & energy capabilities
+e2am train model.py --config config.yaml        # train with full telemetry
+e2am benchmark model.py --input-size 8,3,224,224  # FLOPs, latency, J/inference
+e2am report results/run1                        # regenerate reports for a run
+e2am compare results/run1 results/run2          # side-by-side comparison
+e2am optimize results/run1                      # efficiency suggestions + Wh savings
+e2am dashboard                                  # local HTML dashboard of all runs
+```
+
+`model.py` follows a tiny convention (see [examples/cli_model.py](examples/cli_model.py)):
+define `get_model()` and, for training, `get_loaders()`; optionally
+`get_optimizer(model)` and `get_loss()`.
+
+## Plugins
+
+Every plugin is a Trainer callback — pass any combination:
+
+```python
+from e2am import Trainer
+from e2am.plugins import WandbPlugin, MLflowPlugin, TensorBoardPlugin, SlackPlugin
+
+trainer = Trainer(
+    model=model, optimizer=optimizer, train_loader=train_loader,
+    callbacks=[
+        WandbPlugin(entity="my-team"),          # pip install wandb
+        MLflowPlugin(experiment_name="green"),  # pip install mlflow
+        TensorBoardPlugin(),                    # pip install tensorboard
+        SlackPlugin("https://hooks.slack.com/services/..."),  # no extra deps
+    ],
+)
+```
+
+Slack/Discord notify on completion **and on failure** — including the final
+energy, carbon, and Green Score. Missing packages fail fast at construction
+with the pip command; network errors during training are logged, never raised.
+Write your own by subclassing `e2am.trainer.Callback`.
+
+## Hugging Face
+
+Already using `transformers.Trainer`? One callback adds full E2AM telemetry:
+
+```python
+from transformers import Trainer
+from e2am.integrations import E2AMCallback
+
+trainer = Trainer(
+    model=model, args=training_args, train_dataset=train_ds, eval_dataset=eval_ds,
+    callbacks=[E2AMCallback(project="bert-finetune")],
+)
+trainer.train()   # energy, carbon, green metrics + full E2AM reports in results/
+```
+
+## Roadmap
+
+- [x] Hardware detection with energy-capability probing
+- [x] Background energy/carbon/utilization monitoring (`monitor()`)
+- [x] FLOPs/MACs/latency/peak-memory profiler
+- [x] Drop-in `Trainer` with callback lifecycle (AMP, grad accumulation, early stopping)
+- [x] Green AI metrics: energy/carbon per sample, accuracy/joule, Green Score, EAG
+- [x] Automatic plots + HTML/Markdown/PDF reports + leaderboard
+- [x] CLI (`hardware`, `train`, `benchmark`, `report`, `compare`, `dashboard`)
+- [x] Local HTML dashboard across runs
+- [x] Plugin integrations (W&B, MLflow, TensorBoard, Slack/Discord)
+- [x] Optimization engine (`e2am optimize`: AMP, batch size, torch.compile, checkpointing, quantization, wasted-epoch detection with measured Wh savings)
+- [x] Hugging Face `transformers` integration (`E2AMCallback`)
+- [ ] Distributed training support
+- [ ] Cloud dashboard
+
+## Contributing
+
+Contributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md). Development setup:
+
+```bash
+git clone https://github.com/Shanmuk4622/e2am.git
+cd e2am
+pip install -e ".[dev]"
+pytest
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).