Metadata-Version: 2.4
Name: matcha-gpu
Version: 0.2.2
Summary: GPU energy metering for AI training workloads
Author-email: Keeya Labs <hello@keeyalabs.com>
License-Expression: Apache-2.0
Project-URL: Homepage, https://usematcha.dev
Project-URL: Repository, https://github.com/keeyalabs/matcha-gpu
Keywords: gpu,energy,power,training,nvml,observability
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: System :: Monitoring
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
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
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: nvidia-ml-py
Dynamic: license-file

# ⚡ matcha

GPU energy metering for AI training workloads. Pure Python. No dashboards.

Polls GPU power at 100ms via NVML and reports energy consumption per training step.

Built by [Keeya Labs](https://keeyalabs.com).

## Install

```bash
pip install matcha-gpu
```

Requires an NVIDIA GPU with drivers installed (`nvidia-smi` must work).

## Quick Start

### Option A: Wrap any training script (zero code changes)

```bash
matcha wrap python train_gpt.py
```

Matcha parses your script's stdout for step markers (`step 10`, `iter 10`, `[10/1000]`, etc.)
and reports energy between each step.

```bash
# also print the training script's output
matcha wrap -p python train_gpt.py

# custom gpu and sampling interval
matcha wrap --gpu 1 --interval 50 python train_gpt.py
```

### Option B: SDK (3 lines added to your training loop)

```python
import matcha

m = matcha.init()

for step in range(num_steps):
    m.step_start()

    # ... your training code, unchanged ...

    energy = m.step_end(step)
    # energy.energy_j   — joules
    # energy.avg_power_w — average watts during step
    # energy.peak_power_w

summary = m.finish()
# summary.total_energy_j
# summary.energy_kwh
# summary.j_per_step
```

### Monitor GPU power (no training script)

```bash
matcha monitor
matcha monitor --gpu 0 --window 2.0
```

## Output

```
  ⚡ matcha — gpu energy metering
  ────────────────────────────────────────────────────────
  gpu        NVIDIA H100 80GB HBM3
  tdp        700W
  sampling   every 100ms
  ────────────────────────────────────────────────────────

    step      energy      time    avg W   peak W  power
  ────────────────────────────────────────────────────────
       0     12.45 J    0.198s   62.8W    71.2W  ██████░░░░░░
       1     13.01 J    0.201s   64.7W    73.1W  ██████░░░░░░
       2     12.88 J    0.199s   64.7W    72.4W  ██████░░░░░░

  ────────────────────────────────────────────────────────
  ⚡ session summary
  ────────────────────────────────────────────────────────

  gpu            NVIDIA H100 80GB HBM3
  total energy   623.45 J
  total time     10.02s
  steps          50
  energy/step    12.47 J
  avg power      62.2W
  peak power     73.1W

  est. cost      $0.000021 @ $0.12/kWh
```

## License

Apache 2.0 — see [LICENSE](LICENSE).
