green-peft 0.1.0__tar.gz

green_peft-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ashraful Islam Tanzil
+
+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.

green_peft-0.1.0/PKG-INFO

@@ -0,0 +1,109 @@
+Metadata-Version: 2.4
+Name: green-peft
+Version: 0.1.0
+Summary: Constraint-aware, zero-shot PEFT strategy recommender using the GreenPEFT surrogate models.
+License-Expression: MIT
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: scikit-learn<1.9,>=1.8
+Requires-Dist: pandas<2.3,>=1.5
+Requires-Dist: numpy<2.1,>=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 -e .
+```
+
+## 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
+cd green_peft_cli/green_peft_pkg
+python -m pip install -e .
+green-peft list-zoo --artifacts-dir ../../model/artifacts_export
+```
+
+## 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.

green_peft-0.1.0/README.md

@@ -0,0 +1,94 @@
+# 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 -e .
+```
+
+## 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
+cd green_peft_cli/green_peft_pkg
+python -m pip install -e .
+green-peft list-zoo --artifacts-dir ../../model/artifacts_export
+```
+
+## 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.

green_peft-0.1.0/green_peft/__init__.py

@@ -0,0 +1,12 @@
+from .recommender import (
+    GreenPEFTArtifacts, Constraints, GEI_PROFILES,
+    build_candidates, predict_all, apply_constraints, pareto_front, score_gei,
+    recommend, explain,
+)
+
+__all__ = [
+    'GreenPEFTArtifacts', 'Constraints', 'GEI_PROFILES',
+    'build_candidates', 'predict_all', 'apply_constraints', 'pareto_front', 'score_gei',
+    'recommend', 'explain',
+]
+__version__ = '0.1.0'

green_peft-0.1.0/green_peft/cli.py

@@ -0,0 +1,147 @@
+"""
+green-peft: command-line recommender built on the GreenPEFT surrogate models.
+
+Usage:
+    green-peft recommend --artifacts-dir ./peft_bench_export --vram 16 \\
+        --carbon 0.005 --accuracy 0.90 --profile balanced
+
+    green-peft recommend --artifacts-dir ./peft_bench_export --vram 16 \\
+        --weights 0.5,0.2,0.2,0.1 --top-k 5 --json
+
+    green-peft list-zoo --artifacts-dir ./peft_bench_export
+
+The artifacts directory is whatever you exported from the notebook -- it must contain
+results/surrogate_models.joblib (from Cell 13) and configs/backbones.yaml +
+configs/methods/*.yaml (from Cell 3). Zip peft_bench/results and peft_bench/configs
+together and unzip them here; nothing else from the run is needed.
+"""
+
+from __future__ import annotations
+import argparse
+import json
+import sys
+
+import pandas as pd
+
+from .recommender import (
+    GreenPEFTArtifacts, Constraints, GEI_PROFILES, recommend, explain, build_candidates,
+)
+
+
+def _parse_weights(s: str) -> tuple:
+    parts = [float(x) for x in s.split(',')]
+    if len(parts) != 4:
+        raise argparse.ArgumentTypeError(
+            '--weights needs exactly 4 comma-separated numbers: accuracy,memory,carbon,time')
+    return tuple(parts)
+
+
+def cmd_recommend(args):
+    try:
+        artifacts = GreenPEFTArtifacts.load(args.artifacts_dir)
+    except FileNotFoundError as e:
+        print(f'error: {e}', file=sys.stderr)
+        return 2
+
+    constraints = Constraints(
+        max_vram_gb=args.vram,
+        max_carbon_kgco2eq=args.carbon,
+        min_accuracy=args.accuracy,
+        max_time_seconds=args.time,
+    )
+    weights = _parse_weights(args.weights) if args.weights else None
+    profile = args.profile if weights is None else None
+
+    result = recommend(
+        artifacts, constraints,
+        profile=profile or 'balanced', custom_weights=weights,
+        gpu_vram_gb=args.vram,
+        backbones=args.backbones.split(',') if args.backbones else None,
+        methods=args.methods.split(',') if args.methods else None,
+        top_k=args.top_k,
+    )
+
+    if args.json:
+        payload = {
+            'n_candidates': result['n_candidates'], 'n_feasible': result['n_feasible'],
+            'profile': result['profile'], 'weights': result['weights'],
+        }
+        if result['ranked'] is not None:
+            payload['ranked'] = json.loads(result['ranked'].to_json(orient='records'))
+            payload['pareto_only'] = json.loads(result['pareto_only'].to_json(orient='records'))
+        else:
+            payload['dropped_summary'] = result['dropped_summary']
+        print(json.dumps(payload, indent=2))
+        return 0
+
+    print(explain(result))
+    if result['ranked'] is not None and args.top_k > 1:
+        print(f"\nTop {min(args.top_k, len(result['ranked']))} by GEI:")
+        cols = ['backbone', 'method', 'pred_accuracy', 'pred_peak_vram_gb',
+               'pred_carbon_kgco2eq', 'gei', 'on_pareto_front']
+        with pd.option_context('display.width', 120, 'display.float_format', '{:.4f}'.format):
+            print(result['ranked'][cols].to_string(index=False))
+    return 0
+
+
+def cmd_list_zoo(args):
+    try:
+        artifacts = GreenPEFTArtifacts.load(args.artifacts_dir)
+    except FileNotFoundError as e:
+        print(f'error: {e}', file=sys.stderr)
+        return 2
+    candidates = build_candidates(artifacts,
+                                  args.backbones.split(',') if args.backbones else None,
+                                  args.methods.split(',') if args.methods else None)
+    with pd.option_context('display.width', 120):
+        print(candidates[['backbone', 'model_id', 'family', 'params_b', 'method']]
+              .drop_duplicates(subset=['backbone', 'method']).to_string(index=False))
+    return 0
+
+
+def build_parser():
+    p = argparse.ArgumentParser(prog='green-peft',
+                                description='Constraint-aware PEFT strategy recommender.')
+    sub = p.add_subparsers(dest='command', required=True)
+
+    r = sub.add_parser('recommend', help='Recommend a PEFT config under given constraints.')
+    r.add_argument('--artifacts-dir', required=True,
+                   help='Directory with results/surrogate_models.joblib and configs/.')
+    r.add_argument('--vram', type=float, default=None, help='Max VRAM budget in GB.')
+    r.add_argument('--carbon', type=float, default=None, help='Max carbon budget in kgCO2eq.')
+    r.add_argument('--accuracy', type=float, default=None, help='Minimum required accuracy.')
+    r.add_argument('--time', type=float, default=None, help='Max wall-clock budget in seconds.')
+    r.add_argument('--profile', choices=list(GEI_PROFILES), default='balanced',
+                   help='Named GEI weight profile (ignored if --weights is given).')
+    r.add_argument('--weights', type=str, default=None,
+                   help='Custom GEI weights "w_acc,w_mem,w_carbon,w_time", must sum to 1.0.')
+    r.add_argument('--backbones', type=str, default=None,
+                   help='Comma-separated backbone keys to consider (default: whole model_zoo).')
+    r.add_argument('--methods', type=str, default=None,
+                   help='Comma-separated method keys to consider (default: all configured methods).')
+    r.add_argument('--top-k', type=int, default=3, help='How many ranked candidates to show.')
+    r.add_argument('--json', action='store_true', help='Emit machine-readable JSON instead of text.')
+    r.set_defaults(func=cmd_recommend)
+
+    z = sub.add_parser('list-zoo', help='List every backbone x method candidate the engine can score.')
+    z.add_argument('--artifacts-dir', required=True)
+    z.add_argument('--backbones', type=str, default=None)
+    z.add_argument('--methods', type=str, default=None)
+    z.set_defaults(func=cmd_list_zoo)
+
+    return p
+
+
+def main(argv=None):
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    try:
+        return args.func(args)
+    except BrokenPipeError:
+        # e.g. `green-peft list-zoo ... | head` -- the reader closed early, not an error.
+        sys.stderr.close()
+        return 0
+
+
+if __name__ == '__main__':
+    raise SystemExit(main())

green_peft-0.1.0/green_peft/recommender.py

@@ -0,0 +1,343 @@
+"""
+GreenPEFT decision engine.
+
+Loads the surrogate models trained in Cell 13 (surrogate_models.joblib) and the
+model/method catalog written by Cell 3 (configs/backbones.yaml, configs/methods/*.yaml),
+then answers: "given VRAM / carbon / accuracy / time constraints, which PEFT
+configuration should I run?" -- WITHOUT running it. This is RQ3 + RQ4 together:
+zero-shot prediction (surrogate) feeding constraint-aware prescription (this module).
+
+Design notes:
+- Candidates are drawn from the FULL model_zoo in backbones.yaml, not just the tiers
+  that were actually benchmarked. Predicting for an untested backbone is the entire
+  point of having a surrogate instead of just looking up aggregated_gei.csv.
+- GEI normalization (S_Acc, S_Mem, S_C, S_T) follows the formula in the README exactly:
+  higher-is-better for accuracy, lower-is-better for memory/carbon/time. Normalization
+  bounds are taken from the FEASIBLE, CONSTRAINT-FILTERED candidate set -- not the whole
+  catalog -- because GEI is meant to score trade-offs among options the user could
+  actually choose, not options that were already ruled out.
+- A candidate whose predicted VRAM/accuracy/carbon/time we don't trust (feasibility
+  classifier says P(fits) < FEASIBILITY_THRESHOLD) is dropped before scoring, not
+  penalized within GEI -- an infeasible config isn't a worse option, it isn't an option.
+"""
+
+from __future__ import annotations
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Optional
+
+import joblib
+import numpy as np
+import pandas as pd
+import yaml
+
+CAT_FEATURES = ['method', 'family']
+NUM_FEATURES = ['params_b', 'rank', 'quant_bits', 'is_adapter_method']
+FEASIBILITY_THRESHOLD = 0.5
+
+# Grid/cost assumptions -- mirror Cell 2 defaults. Override via GreenPEFTArtifacts if
+# your notebook used different constants, so predicted carbon/cost stay consistent
+# with what was actually measured.
+DEFAULT_GRID_CARBON_KG_PER_KWH = 0.650
+DEFAULT_ELECTRICITY_USD_PER_KWH = 0.12
+DEFAULT_GPU_RENTAL_USD_PER_HOUR = 0.35
+
+GEI_PROFILES = {
+    # (w_accuracy, w_memory, w_carbon, w_time) -- must sum to 1.0
+    'balanced':      (0.35, 0.25, 0.25, 0.15),
+    'strict_carbon':  (0.20, 0.20, 0.50, 0.10),
+    'high_accuracy':  (0.60, 0.15, 0.15, 0.10),
+}
+
+
+def _method_rank(method_cfg: dict) -> int:
+    return int(method_cfg.get('rank', 0))
+
+
+def _method_quant_bits(method_name: str) -> int:
+    if method_name == 'qlora':
+        return 4
+    if method_name == 'full_ft':
+        return 32
+    return 16
+
+
+def _method_is_adapter(method_name: str) -> int:
+    return int(method_name in ('lora', 'qlora', 'lora_fa'))
+
+
+@dataclass
+class GreenPEFTArtifacts:
+    """Everything the engine needs, loaded from one export directory.
+
+    Expected layout (this is exactly what Cells 1-3 and 13 already write):
+        artifacts_dir/
+          results/surrogate_models.joblib
+          configs/backbones.yaml        (has a top-level `model_zoo:` key)
+          configs/methods/*.yaml
+    """
+    model_zoo: dict
+    method_configs: dict
+    models: dict                      # {'fits':..., 'accuracy':..., 'peak_gpu_memory_gb':..., 'energy_kwh':..., ['wall_clock_seconds':...]}
+    grid_carbon_kg_per_kwh: float = DEFAULT_GRID_CARBON_KG_PER_KWH
+    electricity_usd_per_kwh: float = DEFAULT_ELECTRICITY_USD_PER_KWH
+    gpu_rental_usd_per_hour: float = DEFAULT_GPU_RENTAL_USD_PER_HOUR
+
+    @classmethod
+    def load(cls, artifacts_dir: str | Path) -> 'GreenPEFTArtifacts':
+        root = Path(artifacts_dir)
+        joblib_path = root / 'results' / 'surrogate_models.joblib'
+        backbones_path = root / 'configs' / 'backbones.yaml'
+        methods_dir = root / 'configs' / 'methods'
+
+        if not joblib_path.exists():
+            raise FileNotFoundError(
+                f'{joblib_path} not found. Run Cell 13 in the notebook and download/export '
+                f'the peft_bench/ folder (or just results/ + configs/) to this location.')
+        if not backbones_path.exists():
+            raise FileNotFoundError(f'{backbones_path} not found (from Cell 3).')
+
+        models = joblib.load(joblib_path)
+        backbones_yaml = yaml.safe_load(open(backbones_path))
+        model_zoo = backbones_yaml.get('model_zoo') or backbones_yaml.get('backbones')
+
+        method_configs = {}
+        if methods_dir.exists():
+            for p in methods_dir.glob('*.yaml'):
+                cfg = yaml.safe_load(open(p))
+                method_configs[cfg['method']] = cfg
+        else:
+            raise FileNotFoundError(f'{methods_dir} not found (from Cell 3).')
+
+        return cls(model_zoo=model_zoo, method_configs=method_configs, models=models)
+
+
+@dataclass
+class Constraints:
+    max_vram_gb: Optional[float] = None
+    max_carbon_kgco2eq: Optional[float] = None
+    min_accuracy: Optional[float] = None
+    max_time_seconds: Optional[float] = None
+
+
+def build_candidates(artifacts: GreenPEFTArtifacts,
+                     backbones: Optional[list[str]] = None,
+                     methods: Optional[list[str]] = None) -> pd.DataFrame:
+    """Cross-product of model_zoo x methods with surrogate feature columns filled in."""
+    backbones = backbones or list(artifacts.model_zoo.keys())
+    methods = methods or list(artifacts.method_configs.keys())
+
+    rows = []
+    for bname in backbones:
+        bb = artifacts.model_zoo[bname]
+        for mname in methods:
+            mcfg = artifacts.method_configs.get(mname, {'method': mname})
+            rows.append({
+                'backbone': bname, 'model_id': bb.get('model_id', bname),
+                'method': mname, 'family': bb.get('family', 'unknown'),
+                'params_b': float(bb['params_b']),
+                'rank': _method_rank(mcfg),
+                'quant_bits': _method_quant_bits(mname),
+                'is_adapter_method': _method_is_adapter(mname),
+            })
+    return pd.DataFrame(rows)
+
+
+def predict_all(artifacts: GreenPEFTArtifacts, candidates: pd.DataFrame) -> pd.DataFrame:
+    """Run every surrogate model over the candidate table; derive carbon and cost."""
+    X = candidates[CAT_FEATURES + NUM_FEATURES]
+    out = candidates.copy()
+
+    fits_model = artifacts.models.get('fits')
+    if fits_model is not None:
+        proba = fits_model.predict_proba(X)
+        classes = list(fits_model.named_steps['model'].classes_) if hasattr(fits_model, 'named_steps') \
+            else list(fits_model.classes_)
+        fit_idx = classes.index(1) if 1 in classes else -1
+        out['p_fits'] = proba[:, fit_idx]
+    else:
+        out['p_fits'] = np.nan
+
+    for target, col in [('accuracy', 'pred_accuracy'),
+                        ('peak_gpu_memory_gb', 'pred_peak_vram_gb'),
+                        ('energy_kwh', 'pred_energy_kwh'),
+                        ('wall_clock_seconds', 'pred_wall_clock_s')]:
+        model = artifacts.models.get(target)
+        out[col] = model.predict(X) if model is not None else np.nan
+
+    out['pred_carbon_kgco2eq'] = out['pred_energy_kwh'] * artifacts.grid_carbon_kg_per_kwh
+    hours = out['pred_wall_clock_s'].fillna(0) / 3600.0
+    out['pred_cost_usd'] = (out['pred_energy_kwh'] * artifacts.electricity_usd_per_kwh
+                            + hours * artifacts.gpu_rental_usd_per_hour)
+    return out
+
+
+def apply_constraints(df: pd.DataFrame, constraints: Constraints,
+                      gpu_vram_gb: Optional[float] = None) -> pd.DataFrame:
+    """Constraint filtering (RQ3): drop candidates the surrogate doesn't trust or that
+    violate the user's stated budget. Every drop is explainable -- callers can diff
+    df vs the return value to see exactly which rows were cut and why, by re-checking
+    each condition."""
+    out = df[df['p_fits'] >= FEASIBILITY_THRESHOLD].copy()
+    vram_cap = constraints.max_vram_gb or gpu_vram_gb
+    if vram_cap is not None:
+        out = out[out['pred_peak_vram_gb'] <= vram_cap]
+    if constraints.max_carbon_kgco2eq is not None:
+        out = out[out['pred_carbon_kgco2eq'] <= constraints.max_carbon_kgco2eq]
+    if constraints.min_accuracy is not None:
+        out = out[out['pred_accuracy'] >= constraints.min_accuracy]
+    if constraints.max_time_seconds is not None:
+        out = out[out['pred_wall_clock_s'] <= constraints.max_time_seconds]
+    return out
+
+
+def _time_available(df: pd.DataFrame) -> bool:
+    return 'pred_wall_clock_s' in df.columns and df['pred_wall_clock_s'].notna().any()
+
+
+def pareto_front(df: pd.DataFrame) -> pd.Series:
+    """Boolean mask: True where no other row is at-least-as-good on every ACTIVE axis
+    and strictly better on at least one (accuracy up; VRAM, carbon, [time] down).
+    If no wall-clock model was trained (pred_wall_clock_s is all-NaN), time is dropped
+    from the comparison entirely rather than left in as NaN -- NaN comparisons are
+    always False in numpy, which would silently make every candidate "non-dominated."""
+    if df.empty:
+        return pd.Series([], dtype=bool)
+    acc = df['pred_accuracy'].values
+    mem = df['pred_peak_vram_gb'].values
+    car = df['pred_carbon_kgco2eq'].values
+    use_time = _time_available(df)
+    tim = df['pred_wall_clock_s'].values if use_time else None
+    n = len(df)
+    dominated = np.zeros(n, dtype=bool)
+    for i in range(n):
+        for j in range(n):
+            if i == j:
+                continue
+            better_or_equal = (acc[j] >= acc[i]) and (mem[j] <= mem[i]) and (car[j] <= car[i])
+            strictly_better = (acc[j] > acc[i]) or (mem[j] < mem[i]) or (car[j] < car[i])
+            if use_time:
+                better_or_equal = better_or_equal and (tim[j] <= tim[i])
+                strictly_better = strictly_better or (tim[j] < tim[i])
+            if better_or_equal and strictly_better:
+                dominated[i] = True
+                break
+    return pd.Series(~dominated, index=df.index)
+
+
+def _normalize(series: pd.Series, higher_is_better: bool) -> pd.Series:
+    lo, hi = series.min(), series.max()
+    if hi - lo < 1e-12:
+        return pd.Series(1.0, index=series.index)   # only one distinct value -> no trade-off to score
+    s = (series - lo) / (hi - lo)
+    return s if higher_is_better else (1.0 - s)
+
+
+def score_gei(df: pd.DataFrame, weights: tuple[float, float, float, float]) -> tuple[pd.DataFrame, bool]:
+    """Adds S_Acc, S_Mem, S_C, [S_T] and gei columns, normalized over THIS df only --
+    call this on the constraint-filtered candidate set, not the full catalog.
+    Returns (scored_df, time_was_used). If no wall-clock surrogate was trained, the
+    time term is dropped from the sum and the remaining three weights are renormalized
+    to sum to 1 -- silently defaulting a missing objective to 0 would understate GEI
+    for every candidate uniformly, and dropping the row entirely would discard otherwise
+    valid accuracy/memory/carbon predictions over a target this run never produced."""
+    w_acc, w_mem, w_c, w_t = weights
+    out = df.copy()
+    out['S_Acc'] = _normalize(out['pred_accuracy'], higher_is_better=True)
+    out['S_Mem'] = _normalize(out['pred_peak_vram_gb'], higher_is_better=False)
+    out['S_C'] = _normalize(out['pred_carbon_kgco2eq'], higher_is_better=False)
+
+    use_time = _time_available(out)
+    if use_time:
+        out['S_T'] = _normalize(out['pred_wall_clock_s'], higher_is_better=False)
+        out['gei'] = w_acc * out['S_Acc'] + w_mem * out['S_Mem'] + w_c * out['S_C'] + w_t * out['S_T']
+    else:
+        out['S_T'] = np.nan
+        renorm = w_acc + w_mem + w_c
+        out['gei'] = (w_acc * out['S_Acc'] + w_mem * out['S_Mem'] + w_c * out['S_C']) / renorm
+    return out, use_time
+
+
+def recommend(artifacts: GreenPEFTArtifacts, constraints: Constraints,
+             profile: str = 'balanced', custom_weights: Optional[tuple] = None,
+             gpu_vram_gb: Optional[float] = None,
+             backbones: Optional[list[str]] = None, methods: Optional[list[str]] = None,
+             top_k: int = 3) -> dict:
+    weights = custom_weights or GEI_PROFILES.get(profile)
+    if weights is None:
+        raise ValueError(f'Unknown profile "{profile}", choose from {list(GEI_PROFILES)} '
+                         f'or pass custom_weights=(w_acc, w_mem, w_carbon, w_time)')
+    if abs(sum(weights) - 1.0) > 1e-6:
+        raise ValueError(f'weights must sum to 1.0, got {weights} (sum={sum(weights):.3f})')
+
+    candidates = build_candidates(artifacts, backbones, methods)
+    predicted = predict_all(artifacts, candidates)
+    filtered = apply_constraints(predicted, constraints, gpu_vram_gb=gpu_vram_gb)
+
+    result = {
+        'n_candidates': len(predicted), 'n_feasible': len(filtered),
+        'constraints': constraints, 'profile': profile, 'weights': weights,
+        'ranked': None, 'pareto_only': None, 'dropped_summary': None,
+    }
+    if filtered.empty:
+        # Explain WHY nothing survived rather than just returning empty -- this is the
+        # difference between a decision engine and a silent failure.
+        reasons = []
+        no_fit = predicted[predicted['p_fits'] < FEASIBILITY_THRESHOLD]
+        reasons.append(f"{len(no_fit)}/{len(predicted)} candidates predicted infeasible "
+                       f"(p_fits < {FEASIBILITY_THRESHOLD})")
+        vram_cap = constraints.max_vram_gb or gpu_vram_gb
+        if vram_cap is not None:
+            over = predicted[predicted['pred_peak_vram_gb'] > vram_cap]
+            reasons.append(f"{len(over)}/{len(predicted)} exceed {vram_cap} GB VRAM cap")
+        if constraints.min_accuracy is not None:
+            under = predicted[predicted['pred_accuracy'] < constraints.min_accuracy]
+            reasons.append(f"{len(under)}/{len(predicted)} predicted below "
+                           f"{constraints.min_accuracy} accuracy floor")
+        result['dropped_summary'] = reasons
+        return result
+
+    scored, time_used = score_gei(filtered, weights)
+    scored['on_pareto_front'] = pareto_front(filtered)
+    scored = scored.sort_values('gei', ascending=False)
+
+    result['ranked'] = scored.head(top_k)
+    result['pareto_only'] = scored[scored['on_pareto_front']].sort_values('gei', ascending=False)
+    result['time_objective_used'] = time_used
+    return result
+
+
+def explain(result: dict) -> str:
+    """Human-readable summary of a recommend() result."""
+    if result['ranked'] is None:
+        lines = [f"No candidate satisfies every constraint out of {result['n_candidates']} tried.",
+                 'Reasons:']
+        lines += [f'  - {r}' for r in result['dropped_summary']]
+        lines.append('Loosen one constraint (VRAM cap, carbon cap, or accuracy floor) and retry.')
+        return '\n'.join(lines)
+
+    top = result['ranked'].iloc[0]
+    lines = [
+        f"Recommendation ({result['profile']} profile, weights={result['weights']}):",
+        f"  {top['method']} on {top['backbone']} ({top['model_id']}, {top['params_b']}B params)",
+        f"  predicted accuracy   : {top['pred_accuracy']:.4f}",
+        f"  predicted peak VRAM  : {top['pred_peak_vram_gb']:.2f} GB",
+        f"  predicted energy     : {top['pred_energy_kwh']:.6f} kWh",
+        f"  predicted carbon     : {top['pred_carbon_kgco2eq']:.6f} kgCO2eq",
+        f"  predicted wall-clock : {top['pred_wall_clock_s']:.1f} s"
+        if not pd.isna(top['pred_wall_clock_s']) else "  predicted wall-clock : (no time model trained)",
+        f"  GEI score            : {top['gei']:.4f}"
+        + ('  [on Pareto front]' if top['on_pareto_front'] else '  [dominated by another feasible option -- see note below]'),
+        f"  {result['n_feasible']}/{result['n_candidates']} candidates satisfied all constraints, "
+        f"{result['pareto_only'].shape[0]} of those are Pareto-optimal.",
+    ]
+    if not result.get('time_objective_used', True):
+        lines.append('  Note: no wall-clock surrogate is in this artifacts export, so GEI and the '
+                     'Pareto front were computed over accuracy/VRAM/carbon only (weights renormalized '
+                     'over those three). Add wall_clock_seconds to Cell 13\'s REGRESSION_TARGETS and '
+                     're-run to include a time objective.')
+    if not top['on_pareto_front']:
+        lines.append('  Note: top GEI pick is not Pareto-optimal under these exact weights -- this can '
+                     'happen when weights trade off two close options; check pareto_only for alternatives.')
+    return '\n'.join(lines)

green_peft-0.1.0/green_peft.egg-info/PKG-INFO

@@ -0,0 +1,109 @@
+Metadata-Version: 2.4
+Name: green-peft
+Version: 0.1.0
+Summary: Constraint-aware, zero-shot PEFT strategy recommender using the GreenPEFT surrogate models.
+License-Expression: MIT
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: scikit-learn<1.9,>=1.8
+Requires-Dist: pandas<2.3,>=1.5
+Requires-Dist: numpy<2.1,>=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 -e .
+```
+
+## 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
+cd green_peft_cli/green_peft_pkg
+python -m pip install -e .
+green-peft list-zoo --artifacts-dir ../../model/artifacts_export
+```
+
+## 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.

green_peft-0.1.0/green_peft.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+LICENSE
+README.md
+pyproject.toml
+green_peft/__init__.py
+green_peft/cli.py
+green_peft/recommender.py
+green_peft.egg-info/PKG-INFO
+green_peft.egg-info/SOURCES.txt
+green_peft.egg-info/dependency_links.txt
+green_peft.egg-info/entry_points.txt
+green_peft.egg-info/requires.txt
+green_peft.egg-info/top_level.txt

green_peft-0.1.0/green_peft.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

green_peft-0.1.0/green_peft.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+green-peft = green_peft.cli:main

green_peft-0.1.0/green_peft.egg-info/requires.txt

@@ -0,0 +1,5 @@
+scikit-learn<1.9,>=1.8
+pandas<2.3,>=1.5
+numpy<2.1,>=1.23
+joblib>=1.2
+pyyaml>=6.0

green_peft-0.1.0/green_peft.egg-info/top_level.txt

@@ -0,0 +1 @@
+green_peft

green_peft-0.1.0/pyproject.toml

@@ -0,0 +1,25 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "green-peft"
+version = "0.1.0"
+description = "Constraint-aware, zero-shot PEFT strategy recommender using the GreenPEFT surrogate models."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.9"
+dependencies = [
+    "scikit-learn>=1.8,<1.9",
+    "pandas>=1.5,<2.3",
+    "numpy>=1.23,<2.1",
+    "joblib>=1.2",
+    "pyyaml>=6.0",
+]
+
+[project.scripts]
+green-peft = "green_peft.cli:main"
+
+[tool.setuptools.packages.find]
+include = ["green_peft*"]

green_peft-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+