Metadata-Version: 2.4
Name: green-peft
Version: 0.2.0
Summary: Constraint-aware, zero-shot PEFT strategy recommender using the GreenPEFT surrogate models.
Author: Ashraful Islam Tanzil
License-Expression: MIT
Project-URL: Homepage, https://github.com/ai-tanzil811/Green-AI-Decision-Support-Frameworks
Project-URL: Dataset, https://www.kaggle.com/dsv/20178095
Project-URL: Model, https://huggingface.co/ai-tanzil/GreenPEFT-v2
Keywords: peft,lora,qlora,green-ai,sustainability,carbon,llm
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: scikit-learn<1.10,>=1.9
Requires-Dist: pandas<3,>=1.5
Requires-Dist: numpy>=1.23
Requires-Dist: joblib>=1.2
Requires-Dist: pyyaml>=6.0
Dynamic: license-file

# green-peft

Constraint-aware PEFT strategy recommender. Wraps the surrogate models trained in
Cell 13 of the GreenPEFT notebook so you can ask "which method + model size should I
use?" from the command line, without running anything.

## Install

```bash
pip install green-peft
```

The published package is available at
[PyPI](https://pypi.org/project/green-peft/0.1.0/). For development from this
repository, use `python -m pip install -e .` instead.

## Export artifacts from your notebook run

The CLI needs two things out of your Kaggle/Colab `peft_bench/` folder:

```
peft_bench/results/surrogate_models.joblib   # written by Cell 13
peft_bench/configs/backbones.yaml            # written by Cell 3 (has model_zoo:)
peft_bench/configs/methods/*.yaml            # written by Cell 3
```

Zip `results/` and `configs/` together, download from Kaggle, unzip locally into
e.g. `./peft_bench_export/`, and point `--artifacts-dir` at it.

This repository includes a ready-to-use export at:

```text
model/artifacts_export/
├── configs/backbones.yaml
├── configs/methods/*.yaml
├── configs/tasks.yaml
├── results/surrogate_models.joblib
├── results/surrogate_cv_metrics.json
└── results/surrogate_dataset.csv
```

From the repository root, install the package and use that export directly:

```powershell
python -m pip install green-peft
git clone https://huggingface.co/ai-tanzil/GreenPEFT
green-peft list-zoo --artifacts-dir ./GreenPEFT
```

For local development from this repository, use the checked-in export with
`--artifacts-dir ./model/artifacts_export` from the project root.

## Usage

```bash
# Basic recommendation under a VRAM + accuracy constraint
green-peft recommend --artifacts-dir ./peft_bench_export \
    --vram 16 --accuracy 0.90 --profile balanced

# Strict carbon budget, custom weight profile, JSON output for scripting
green-peft recommend --artifacts-dir ./peft_bench_export \
    --vram 24 --carbon 0.003 --weights 0.3,0.2,0.4,0.1 --top-k 5 --json

# See every backbone x method combination the engine can currently score
green-peft list-zoo --artifacts-dir ./peft_bench_export
```

## What it actually does

1. Builds a candidate table crossing every backbone in your `model_zoo` (including
   ones you never ran) with every configured method.
2. Runs the four surrogate models (feasibility classifier + accuracy / peak-VRAM /
   energy / wall-clock regressors) over every candidate.
3. Drops candidates the feasibility classifier doesn't trust, or that violate your
   `--vram` / `--carbon` / `--accuracy` / `--time` constraints.
4. Computes the Pareto front and a GEI score (same formula as the paper: weighted sum
   of normalized accuracy/memory/carbon/time scores) over the surviving candidates.
5. Prints the top-k ranked options with a plain-English explanation, or an explicit
   breakdown of why nothing survived if your constraints are infeasible together.

Predictions are only as reliable as the surrogate's leave-one-tier-out validation
(`results/surrogate_cv_metrics.json` from Cell 13) says they are for that target --
check `regression.<target>.best_model` R2 there before trusting a specific number.

## Current validation and limitations

The included export reports leave-one-tier-out feasibility accuracy of `0.7833`.
Selected regression models report the following validation results:

| Target | Model | MAE | R2 |
| --- | --- | ---: | ---: |
| Accuracy | Gradient boosting | 0.0182 | -0.4573 |
| Peak VRAM | Gradient boosting | 3.9703 GB | -0.5154 |
| Energy | Ridge | 0.000563 kWh | 0.3740 |
| Wall-clock time | Gradient boosting | 33.12 s | 0.4077 |

Use the CLI for experiment planning, shortlist generation, and explicit budget checks.
It does not run fine-tuning, measure the target hardware, or guarantee performance.
The benchmark evidence is primarily SST-2 classification on a Tesla T4; recommendations
for unbenchmarked catalog entries are extrapolations. Validate the selected option with
a real run and retain the JSON output alongside the measured results. The published
CLI version is `0.1.0`; cite the release with DOI
[10.57967/hf/10504](https://doi.org/10.57967/hf/10504).
