Metadata-Version: 2.3
Name: carbonaware-ml
Version: 0.1.0
Summary: Carbon-aware PyTorch training plugin (multi-region via Electricity Maps/WattTime).
License: MIT License
         
         Copyright (c) 2025 Carbon Aware Ontario
         
         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.
Keywords: pytorch,carbon,sustainability,scheduling,electricity,carbon-aware,ml
Author: Carbon Aware ML Maintainers
Requires-Python: >=3.9
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Provides-Extra: all
Provides-Extra: scheduler
Provides-Extra: tensorboard
Requires-Dist: apscheduler (>=3.10.4) ; extra == "all"
Requires-Dist: apscheduler (>=3.10.4) ; extra == "scheduler"
Requires-Dist: requests (>=2.31.0)
Requires-Dist: tensorboard (>=2.12.0) ; extra == "all"
Requires-Dist: tensorboard (>=2.12.0) ; extra == "tensorboard"
Requires-Dist: torch (>=2.0.0)
Project-URL: Homepage, https://github.com/tomalmog/carbonaware-ml
Project-URL: Issues, https://github.com/tomalmog/carbonaware-ml/issues
Project-URL: Repository, https://github.com/tomalmog/carbonaware-ml
Description-Content-Type: text/markdown

### Carbon Aware ML (multi-region)

Carbon-aware training for PyTorch that pauses or schedules training based on real-time grid carbon intensity (and optionally electricity prices). Works in any region supported by Electricity Maps or WattTime. Users supply their own API credentials and desired region.

#### Installation

```bash
pip install -e .
# Optional extras
pip install -e '.[scheduler]'
pip install -e '.[tensorboard]'
pip install -e '.[all]'
```

#### Quickstart

```python
from carbonaware_ml import CarbonAwareTrainer, providers

trainer = CarbonAwareTrainer(
    model=my_model,
    optimizer=my_optimizer,
    dataloader=my_dataloader,
    region=os.environ.get("CARBONAWARE_REGION", "CA-ON"),
    carbon_provider=providers.ElectricityMapsProvider(),
)

# Block until grid intensity is green enough, then train
trainer.train_until_green(threshold=200, num_epochs=3)

# Or always-on training but pausing when above threshold
trainer.train(num_epochs=3, threshold=200, check_interval_s=300)
```

You can also import via `carbonaware_ml`:

```python
from carbonaware_ml import CarbonAwareTrainer
```

Providers:
- Electricity Maps (real-time/forecast carbon intensity)
  - Set credentials via environment:
    - `ELECTRICITYMAPS_API_TOKEN` (required)
    - `ELECTRICITYMAPS_EMAIL` (optional; enables Basic Auth fallback if your plan requires it)
- WattTime (alternative intensity source)
- Ontario TOU price provider (demo, no API key)

If no external provider is configured, the trainer defaults to an "always-allow" mode.

#### Environment

- `CARBONAWARE_REGION`: your region/zone (e.g., `CA-ON`, `US-CAL-CISO`, `DE`)
- `ELECTRICITYMAPS_API_TOKEN`: Electricity Maps API token
- `ELECTRICITYMAPS_EMAIL`: your Electricity Maps account email (if Basic Auth is needed)

#### License

MIT

#### CLI

```bash
carbonaware intensity --region CA-ON          # or set CARBONAWARE_REGION
carbonaware price --region CA-ON
```

#### TensorBoard

```python
trainer = CarbonAwareTrainer(..., tb_log_dir="runs/demo")
```

#### Scheduler (optional)

```python
from carbonaware_ontario.scheduler import run_when_favorable
sched = run_when_favorable(trainer, num_epochs=1, threshold=150, price_threshold_cents=12.0, check_interval_s=300)
```



