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.2.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.2.0
File Size Uploaded Provenance Actions
green_peft-0.2.0.tar.gz 30.9 kB Without provenance Details for green_peft-0.2.0.tar.gz

Built distribution (wheel)

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

Total release size: 59.5 kB

Release files / green_peft-0.2.0.tar.gz

Download URL green_peft-0.2.0.tar.gz
Size 30.9 kB
Tags Source
SHA-256 checksum
How to use checksums
51ffbd2059e9cd38fda5805241fc3a4978c994d1781c59dafa88a4bb696ee25d
BLAKE2b-256 checksum
How to use checksums
e6d2f72276a7e402a47e53cb81380d6a9a3e6a2fbb8c356bad7ecfcc9424a7d9
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.2.0-py3-none-any.whl

Download URL green_peft-0.2.0-py3-none-any.whl
Size 28.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
3f0ce2137fc886ab7942b418a66140eb9573e0ddd003c0015f99075635a69484
BLAKE2b-256 checksum
How to use checksums
094e83b0839d22bb4f218b000e1c2fc2bfde95429e6f8e1eae0a541116b40e07
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.2.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