# ai-tanzil811/green-ai-decision-support-frameworks architecture

> Architecture diagram of the GitHub repository ai-tanzil811/green-ai-decision-support-frameworks, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ai-tanzil811/green-ai-decision-support-frameworks
- Repository: https://github.com/ai-tanzil811/green-ai-decision-support-frameworks

## Overview

GreenPEFT is a research and decision-support framework for sustainable parameter-efficient fine-tuning. Its user-facing workflow loads surrogate artifacts and a candidate catalog, builds pre-run features, predicts outcomes, applies resource constraints, and ranks feasible strategies with Pareto filtering and GEI. A separate empirical-analysis branch organizes benchmark measurements and examines feasibility and trade-offs; validation and export support the surrogate lifecycle. Links among CLI internals and analysis modules follow excerpts or SOURCE INDEX references; broader benchmark-to-surrogate relationships are documented in the README.

Main entry points: [`green_peft_cli/green_peft_pkg/green_peft/recommender.py`](https://github.com/ai-tanzil811/green-ai-decision-support-frameworks/blob/main/green_peft_cli/green_peft_pkg/green_peft/recommender.py) (Surrogate Prediction), [`analysis/greenpeft_data.py`](https://github.com/ai-tanzil811/green-ai-decision-support-frameworks/blob/main/analysis/greenpeft_data.py) (Shared Data Loader), [`results/canonical_benchmark/metrics`](https://github.com/ai-tanzil811/green-ai-decision-support-frameworks/tree/main/results/canonical_benchmark/metrics) (Benchmark Results), [`green_peft_cli/green_peft_pkg/green_peft/cli.py`](https://github.com/ai-tanzil811/green-ai-decision-support-frameworks/blob/main/green_peft_cli/green_peft_pkg/green_peft/cli.py) (CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_decision["Recommendation Engine"]
  node_cli["CLI<br/>[cli.py]"]
  node_banner["CLI Banner<br/>[banner.py]"]
  node_catalog["Model Catalog"]
  node_features["Pre-run Features<br/>[features.py]"]
  node_predict["Surrogate Prediction<br/>[recommender.py]"]
  node_confidence["Confidence Scope<br/>[confidence.py]"]
  node_constraints["Constraint Filtering<br/>[recommender.py]"]
  node_ranking["Pareto and GEI<br/>[recommender.py]"]
end

subgraph group_research["Benchmark Analysis"]
  node_dataset[("Benchmark Data")]
  node_data_loader["Shared Data Loader<br/>[greenpeft_data.py]"]
  node_benchmark["Benchmark Analysis"]
  node_pareto_analysis["Frontier Analysis<br/>[pareto_analysis.py]"]
  node_figures["Research Figures<br/>[figures.py]"]
  node_scenarios["Recommendation Scenarios"]
end

subgraph group_surrogate["Surrogate Lifecycle"]
  node_envelope["Training Envelope"]
  node_surrogate_model[("Surrogate Artifacts")]
  node_model_metadata["Model Metadata"]
  node_export["Model Export<br/>[build_hf_export.py]"]
end

subgraph group_evidence["Results and Validation"]
  node_validation["Prediction Validation"]
  node_benchmark_results[("Benchmark Results")]
  node_recommendation_results[("Recommendation Results")]
end

node_practitioner(("Practitioner"))

node_practitioner -->|"requests recommendation"| node_cli
node_cli -->|"prints banner"| node_banner
node_cli -->|"invokes engine"| node_predict
node_predict -->|"loads catalog"| node_catalog
node_predict -->|"loads models"| node_surrogate_model
node_predict -->|"builds features"| node_features
node_predict -->|"annotates predictions"| node_confidence
node_predict -->|"filters candidates"| node_constraints
node_predict -->|"scores candidates"| node_ranking
node_dataset -->|"provides measurements"| node_data_loader
node_data_loader -->|"supplies benchmark data"| node_benchmark
node_data_loader -->|"supplies measured runs"| node_pareto_analysis
node_data_loader -->|"supplies analysis data"| node_figures
node_data_loader -->|"supplies analysis data"| node_scenarios
node_benchmark -->|"writes summaries"| node_benchmark_results
node_pareto_analysis -->|"uses decision engine"| node_ranking
node_pareto_analysis -->|"writes frontiers"| node_benchmark_results
node_figures -->|"renders results"| node_benchmark_results
node_scenarios -->|"uses decision engine"| node_ranking
node_scenarios -->|"writes scenarios"| node_recommendation_results
node_dataset -->|"defines measured scope"| node_envelope
node_envelope -->|"records envelope"| node_model_metadata
node_surrogate_model -->|"packages model"| node_export
node_model_metadata -->|"supplies metadata"| node_export
node_catalog -->|"packages configs"| node_export
node_validation -->|"checks predictions"| node_ranking
node_validation -->|"backtests against"| node_benchmark_results

click node_cli "https://github.com/ai-tanzil811/green-ai-decision-support-frameworks/blob/main/green_peft_cli/green_peft_pkg/green_peft/cli.py"
click node_banner "https://github.com/ai-tanzil811/green-ai-decision-support-frameworks/blob/main/green_peft_cli/green_peft_pkg/green_peft/banner.py"
click node_catalog "https://github.com/ai-tanzil811/green-ai-decision-support-frameworks/tree/main/green_peft_cli/green_peft_pkg/green_peft/data"
click node_features "https://github.com/ai-tanzil811/green-ai-decision-support-frameworks/blob/main/green_peft_cli/green_peft_pkg/green_peft/features.py"
click node_predict "https://github.com/ai-tanzil811/green-ai-decision-support-frameworks/blob/main/green_peft_cli/green_peft_pkg/green_peft/recommender.py"
click node_confidence "https://github.com/ai-tanzil811/green-ai-decision-support-frameworks/blob/main/green_peft_cli/green_peft_pkg/green_peft/confidence.py"
click node_constraints "https://github.com/ai-tanzil811/green-ai-decision-support-frameworks/blob/main/green_peft_cli/green_peft_pkg/green_peft/recommender.py"
click node_ranking "https://github.com/ai-tanzil811/green-ai-decision-support-frameworks/blob/main/green_peft_cli/green_peft_pkg/green_peft/recommender.py"
click node_dataset "https://github.com/ai-tanzil811/green-ai-decision-support-frameworks/blob/main/new%20update%20works/greenpeft_ml_ready_dataset.csv"
click node_data_loader "https://github.com/ai-tanzil811/green-ai-decision-support-frameworks/blob/main/analysis/greenpeft_data.py"
click node_benchmark "https://github.com/ai-tanzil811/green-ai-decision-support-frameworks/blob/main/analysis/benchmark_analysis.py"
click node_pareto_analysis "https://github.com/ai-tanzil811/green-ai-decision-support-frameworks/blob/main/analysis/pareto_analysis.py"
click node_figures "https://github.com/ai-tanzil811/green-ai-decision-support-frameworks/blob/main/analysis/figures.py"
click node_scenarios "https://github.com/ai-tanzil811/green-ai-decision-support-frameworks/blob/main/analysis/recommendation_scenarios.py"
click node_envelope "https://github.com/ai-tanzil811/green-ai-decision-support-frameworks/blob/main/analysis/build_training_envelope.py"
click node_surrogate_model "https://github.com/ai-tanzil811/green-ai-decision-support-frameworks/blob/main/new%20update%20works/greenpeft_surrogate_models.joblib"
click node_model_metadata "https://github.com/ai-tanzil811/green-ai-decision-support-frameworks/blob/main/models/model_metadata.json"
click node_export "https://github.com/ai-tanzil811/green-ai-decision-support-frameworks/blob/main/analysis/build_hf_export.py"
click node_validation "https://github.com/ai-tanzil811/green-ai-decision-support-frameworks/blob/main/experiments/validate_recommendation.py"
click node_benchmark_results "https://github.com/ai-tanzil811/green-ai-decision-support-frameworks/tree/main/results/canonical_benchmark/metrics"
click node_recommendation_results "https://github.com/ai-tanzil811/green-ai-decision-support-frameworks/tree/main/results/recommendations"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_banner,node_catalog,node_features,node_predict,node_confidence,node_constraints,node_ranking toneBlue
class node_dataset,node_data_loader,node_benchmark,node_pareto_analysis,node_figures,node_scenarios toneAmber
class node_envelope,node_surrogate_model,node_model_metadata,node_export toneMint
class node_validation,node_benchmark_results,node_recommendation_results toneRose
class node_practitioner toneIndigo
```

## Components

### Recommendation Engine

- [CLI](https://github.com/ai-tanzil811/green-ai-decision-support-frameworks/blob/main/green_peft_cli/green_peft_pkg/green_peft/cli.py): `green_peft_cli/green_peft_pkg/green_peft/cli.py`
- [CLI Banner](https://github.com/ai-tanzil811/green-ai-decision-support-frameworks/blob/main/green_peft_cli/green_peft_pkg/green_peft/banner.py): `green_peft_cli/green_peft_pkg/green_peft/banner.py`
- [Model Catalog](https://github.com/ai-tanzil811/green-ai-decision-support-frameworks/tree/main/green_peft_cli/green_peft_pkg/green_peft/data): `green_peft_cli/green_peft_pkg/green_peft/data`
- [Pre-run Features](https://github.com/ai-tanzil811/green-ai-decision-support-frameworks/blob/main/green_peft_cli/green_peft_pkg/green_peft/features.py): `green_peft_cli/green_peft_pkg/green_peft/features.py`
- [Surrogate Prediction](https://github.com/ai-tanzil811/green-ai-decision-support-frameworks/blob/main/green_peft_cli/green_peft_pkg/green_peft/recommender.py): `green_peft_cli/green_peft_pkg/green_peft/recommender.py`
- [Confidence Scope](https://github.com/ai-tanzil811/green-ai-decision-support-frameworks/blob/main/green_peft_cli/green_peft_pkg/green_peft/confidence.py): `green_peft_cli/green_peft_pkg/green_peft/confidence.py`
- [Constraint Filtering](https://github.com/ai-tanzil811/green-ai-decision-support-frameworks/blob/main/green_peft_cli/green_peft_pkg/green_peft/recommender.py): `green_peft_cli/green_peft_pkg/green_peft/recommender.py`
- [Pareto and GEI](https://github.com/ai-tanzil811/green-ai-decision-support-frameworks/blob/main/green_peft_cli/green_peft_pkg/green_peft/recommender.py): `green_peft_cli/green_peft_pkg/green_peft/recommender.py`

### Benchmark Analysis

- [Benchmark Data](https://github.com/ai-tanzil811/green-ai-decision-support-frameworks/blob/main/new%20update%20works/greenpeft_ml_ready_dataset.csv): `new update works/greenpeft_ml_ready_dataset.csv`
- [Shared Data Loader](https://github.com/ai-tanzil811/green-ai-decision-support-frameworks/blob/main/analysis/greenpeft_data.py): `analysis/greenpeft_data.py`
- [Benchmark Analysis](https://github.com/ai-tanzil811/green-ai-decision-support-frameworks/blob/main/analysis/benchmark_analysis.py): `analysis/benchmark_analysis.py`
- [Frontier Analysis](https://github.com/ai-tanzil811/green-ai-decision-support-frameworks/blob/main/analysis/pareto_analysis.py): `analysis/pareto_analysis.py`
- [Research Figures](https://github.com/ai-tanzil811/green-ai-decision-support-frameworks/blob/main/analysis/figures.py): `analysis/figures.py`
- [Recommendation Scenarios](https://github.com/ai-tanzil811/green-ai-decision-support-frameworks/blob/main/analysis/recommendation_scenarios.py): `analysis/recommendation_scenarios.py`

### Surrogate Lifecycle

- [Training Envelope](https://github.com/ai-tanzil811/green-ai-decision-support-frameworks/blob/main/analysis/build_training_envelope.py): `analysis/build_training_envelope.py`
- [Surrogate Artifacts](https://github.com/ai-tanzil811/green-ai-decision-support-frameworks/blob/main/new%20update%20works/greenpeft_surrogate_models.joblib): `new update works/greenpeft_surrogate_models.joblib`
- [Model Metadata](https://github.com/ai-tanzil811/green-ai-decision-support-frameworks/blob/main/models/model_metadata.json): `models/model_metadata.json`
- [Model Export](https://github.com/ai-tanzil811/green-ai-decision-support-frameworks/blob/main/analysis/build_hf_export.py): `analysis/build_hf_export.py`

### Results and Validation

- [Prediction Validation](https://github.com/ai-tanzil811/green-ai-decision-support-frameworks/blob/main/experiments/validate_recommendation.py): `experiments/validate_recommendation.py`
- [Benchmark Results](https://github.com/ai-tanzil811/green-ai-decision-support-frameworks/tree/main/results/canonical_benchmark/metrics): `results/canonical_benchmark/metrics`
- [Recommendation Results](https://github.com/ai-tanzil811/green-ai-decision-support-frameworks/tree/main/results/recommendations): `results/recommendations`

### Other components

- **Practitioner**

## Connections

- Practitioner → CLI: requests recommendation (evidence: `readme.md`)
- CLI → CLI Banner: prints banner (evidence: `green_peft_cli/green_peft_pkg/green_peft/cli.py`)
- CLI → Surrogate Prediction: invokes engine (evidence: `green_peft_cli/green_peft_pkg/green_peft/cli.py`)
- Surrogate Prediction → Model Catalog: loads catalog (evidence: `green_peft_cli/green_peft_pkg/green_peft/recommender.py`)
- Surrogate Prediction → Surrogate Artifacts: loads models (evidence: `green_peft_cli/green_peft_pkg/green_peft/recommender.py`)
- Surrogate Prediction → Pre-run Features: builds features (evidence: `green_peft_cli/green_peft_pkg/green_peft/recommender.py`)
- Surrogate Prediction → Confidence Scope: annotates predictions (evidence: `green_peft_cli/green_peft_pkg/green_peft/recommender.py`)
- Surrogate Prediction → Constraint Filtering: filters candidates (evidence: `green_peft_cli/green_peft_pkg/green_peft/recommender.py`)
- Surrogate Prediction → Pareto and GEI: scores candidates (evidence: `green_peft_cli/green_peft_pkg/green_peft/recommender.py`)
- Benchmark Data → Shared Data Loader: provides measurements (evidence: `analysis/greenpeft_data.py`)
- Shared Data Loader → Benchmark Analysis: supplies benchmark data (evidence: `analysis/benchmark_analysis.py`)
- Shared Data Loader → Frontier Analysis: supplies measured runs (evidence: `analysis/pareto_analysis.py`)
- Shared Data Loader → Research Figures: supplies analysis data (evidence: `analysis/figures.py`)
- Shared Data Loader → Recommendation Scenarios: supplies analysis data (evidence: `analysis/recommendation_scenarios.py`)
- Benchmark Analysis → Benchmark Results: writes summaries (evidence: `readme.md`)
- Frontier Analysis → Pareto and GEI: uses decision engine (evidence: `analysis/pareto_analysis.py`)
- Frontier Analysis → Benchmark Results: writes frontiers (evidence: `readme.md`)
- Research Figures → Benchmark Results: renders results (evidence: `analysis/figures.py`)
- Recommendation Scenarios → Pareto and GEI: uses decision engine (evidence: `analysis/recommendation_scenarios.py`)
- Recommendation Scenarios → Recommendation Results: writes scenarios (evidence: `readme.md`)
- Benchmark Data → Training Envelope: defines measured scope (evidence: `readme.md`)
- Training Envelope → Model Metadata: records envelope (evidence: `readme.md`)
- Surrogate Artifacts → Model Export: packages model (evidence: `analysis/build_hf_export.py`)
- Model Metadata → Model Export: supplies metadata (evidence: `analysis/build_hf_export.py`)
- Model Catalog → Model Export: packages configs (evidence: `analysis/build_hf_export.py`)
- Prediction Validation → Pareto and GEI: checks predictions (evidence: `experiments/validate_recommendation.py`)
- Prediction Validation → Benchmark Results: backtests against (evidence: `experiments/validate_recommendation.py`)
