Skip to main content

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

pip install green-peft

The published package is available at PyPI. 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:

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:

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

# 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.

Metadata

Release files for green-peft 0.3.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for green-peft 0.3.0
File Size Uploaded Provenance Actions
green_peft-0.3.0.tar.gz 39.0 kB Without provenance Details for green_peft-0.3.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for green-peft 0.3.0
File Interpreter ABI Platform Actions
green_peft-0.3.0-py3-none-any.whl Python 3 none any Details for green_peft-0.3.0-py3-none-any.whl

Total release size: 74.7 kB

Release files / green_peft-0.3.0.tar.gz

Download URL green_peft-0.3.0.tar.gz
Size 39.0 kB
Tags Source
SHA-256 checksum
How to use checksums
a9c152625368b7357ffe7805b7dd1b23a93fd70c2bdb4b0df64ddc8be9d045c1
BLAKE2b-256 checksum
How to use checksums
1d5d91a6f2a9b614b0b1882d2d8ca4af43da097acb49ebc7c97d823b8a28e69f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.10

Release files / green_peft-0.3.0-py3-none-any.whl

Download URL green_peft-0.3.0-py3-none-any.whl
Size 35.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
5804a69281cd0c3cb7ee11722897b42737db41a2e9e824675194d19825b70271
BLAKE2b-256 checksum
How to use checksums
c1707471446d2966b28775b9e7da86753a2968b32a3235298ba238f4da968332
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.10

Security for green-peft 0.3.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page