{"id":47703880,"url":"https://github.com/aliakarma/eagf","last_synced_at":"2026-04-08T00:04:04.242Z","repository":{"id":345156730,"uuid":"1184715268","full_name":"aliakarma/eagf","owner":"aliakarma","description":"EAGF (Ethical Agent Governance Framework)","archived":false,"fork":false,"pushed_at":"2026-04-02T19:10:42.000Z","size":35441,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-03T04:14:35.324Z","etag":null,"topics":["cybersecurity","ethics-in-ai","iot-system","renewable-energy"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/aliakarma.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-17T21:32:48.000Z","updated_at":"2026-04-02T19:10:45.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/aliakarma/eagf","commit_stats":null,"previous_names":["aliakarma/eagf"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/aliakarma/eagf","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aliakarma%2Feagf","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aliakarma%2Feagf/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aliakarma%2Feagf/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aliakarma%2Feagf/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aliakarma","download_url":"https://codeload.github.com/aliakarma/eagf/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aliakarma%2Feagf/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31533828,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-07T16:28:08.000Z","status":"ssl_error","status_checked_at":"2026-04-07T16:28:06.951Z","response_time":105,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cybersecurity","ethics-in-ai","iot-system","renewable-energy"],"created_at":"2026-04-02T17:48:46.311Z","updated_at":"2026-04-08T00:04:04.172Z","avatar_url":"https://github.com/aliakarma.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# EAGF: Ethical AI Governance Framework\n\n\u003e **Joint Optimization of Fairness, Privacy, Explainability \u0026 Accountability in AI-Based Cybersecurity**\n\n![Python](https://img.shields.io/badge/Python-3.9%2B-blue?style=flat-square)\n![License](https://img.shields.io/badge/License-MIT-green?style=flat-square)\n![Status](https://img.shields.io/badge/Status-Publication_Ready-brightgreen?style=flat-square)\n![PyTorch](https://img.shields.io/badge/PyTorch-2.0%2B-red?style=flat-square)\n![Reproducibility](https://img.shields.io/badge/Reproducibility-5_Seeds-success?style=flat-square)\n\n[![Open Demo in Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/aliakarma/eagf/blob/main/notebooks/01_eagf_demo.ipynb)\n[![Open Statistical Analysis in Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/aliakarma/eagf/blob/main/notebooks/02_statistical_analysis.ipynb)\n[![Open Fairness Study in Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/aliakarma/eagf/blob/main/notebooks/03_reiot_fairness.ipynb)\n[![Open Pareto Analysis in Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/aliakarma/eagf/blob/main/notebooks/04_pareto_front.ipynb)\n[![Open Sensitivity Analysis in Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/aliakarma/eagf/blob/main/notebooks/05_trust_index_sensitivity.ipynb)\n\n---\n\n## 📋 Overview\n\nEAGF is a reproducible research framework that combines **differential privacy (DP-SGD)**, **fairness regularization (false positive rate parity)**, **explainability (SHAP)**, and **audit logging** into a unified governance pipeline. Evaluated on the real-world **Edge-IIoTset** (IEEE 2022) for IoT anomaly detection with multi-objective Pareto trade-off analysis.\n\n**Key Focus**: Cybersecurity for IoT networks with resource-constrained devices. EAGF enables governance-aware AI deployment with minimal system overhead.\n\n---\n\n## 🎯 Key Contributions\n\n- 🏭 **Real-world dataset integration**: Edge-IIoTset (IEEE 2022, 150K samples, 40 network flow features)\n- ⚖️ **Multi-objective governance**: Joint optimization of four pillars—fairness, privacy, clarity, accountability\n- 📊 **Trust Index metric**: Composite governance score for model selection and comparison\n- 📈 **Pareto trade-off analysis**: Quantify accuracy-fairness-privacy trade-offs with front visualization\n- 🔄 **Reproducible pipeline**: Deterministic execution, fixed seeds, publication-ready results\n\n---\n\n## 📊 Key Results Summary\n\n**Dataset**: Edge-IIoTset (150K samples, 3 protocol-type protected groups)  \n**Baselines**: Unregulated + Joint DP+Fair  \n**Statistical Rigor**: 5 independent seeds with 95% CI  \n\n| Metric | Baseline | **EAGF** | Δ | Improvement |\n|--------|----------|----------|-------|-------------|\n| **Accuracy** | 0.6481 ± 0.0251 | **0.6650 ± 0.0079** | +0.0168 | +2.6% |\n| **FPR Parity** | 0.4931 ± 0.0849 | **0.7709 ± 0.0573** | +0.2779 | **+56.4%** ✓ |\n| **Clarity** | 0.6918 ± 0.0432 | **0.7390 ± 0.0548** | +0.0472 | +6.8% |\n| **Privacy** | 0.2475 ± 0.0030 | **0.2482 ± 0.0025** | +0.0007 | Preserved ✓ |\n| **Accountability** | 0.0000 ± 0.0000 | **0.6667 ± 0.0000** | +0.6667 | Full coverage ✓ |\n| **Trust Index** | 0.3581 ± 0.0129 | **0.6062 ± 0.0108** | +0.2481 | **+69.3%** ✓ |\n\n### 🔬 Key Findings\n\n✅ **Fairness breakthrough**: FPR parity improved +56.4% across protocol-type groups (web, IoT MQTT, misc)  \n✅ **Trust Index surge**: Composite governance metric +69.3%, indicating strong multi-objective alignment  \n✅ **Privacy guarantee**: Differential privacy (ε=2.4) maintained with negligible DP-ε change  \n✅ **Edge deployment ready**: +0.2ms latency (~11%), +5.8MB memory—suitable for constrained IoT  \n✅ **Calibration stable**: ECE and Brier comparable (±0.05), no metric gaming  \n\n---\n\n## 📁 Repository Structure\n\n```\neagf/\n├── 📖 README.md                    # This file\n├── 📄 requirements.txt             # Dependencies (numpy, pandas, scikit-learn, fairlearn, pyyaml)\n├── 🔧 setup.py                     # Package setup\n│\n├── 🚀 run_eagf.py                  # Single-seed entry point\n├── 🚀 run_full_pipeline.py         # Multi-seed experiment runner (MAIN)\n│\n├── 🧠 src/\n│   ├── training/\n│   │   ├── eagf_trainer.py         # Main EAGF training loop with governance\n│   │   ├── fairness_loss.py         # Fairness penalty (FPR parity)\n│   │   └── pareto_trainer.py        # Pareto front exploration\n│   │\n│   ├── evaluation/\n│   │   ├── baseline.py             # Unregulated baseline + Joint DP+Fair\n│   │   ├── ablation.py             # Single-pillar ablation study\n│   │   ├── report_generator.py      # Multi-seed report + statistics\n│   │   ├── audit_logger.py         # Compliance audit trail\n│   │   ├── benchmark_suite.py      # System metrics (latency, memory, energy)\n│   │   └── statistics.py           # 95% CI, statistical tests\n│   │\n│   ├── metrics/\n│   │   ├── fairness.py             # FPR parity, recall parity, group metrics\n│   │   ├── privacy.py              # DP-SGD evaluation, privacy accounting\n│   │   ├── clarity.py              # SHAP-based explainability\n│   │   ├── accountability.py       # Audit coverage, compliance scoring\n│   │   └── trust_index.py          # Composite Trust Index aggregation\n│   │\n│   ├── utils/\n│   │   ├── data_loader.py          # Generic dataset loading\n│   │   ├── edge_iiot_loader.py     # Edge-IIoTset specific (protocol_type grouping)\n│   │   ├── real_data_loader.py     # Real dataset pipeline\n│   │   ├── preprocessing.py        # Feature engineering, normalization\n│   │   ├── reiot_simulator.py      # RE-IoT synthetic simulator (optional)\n│   │   ├── ahp.py                  # Analytic Hierarchy Process (Trust Index weights)\n│   │   └── visualisation.py        # Pareto, Trade-off plots\n│   │\n│   └── baselines/\n│       ├── aif360_dp_pipeline.py   # AIF360 fairness baseline\n│       └── joint_dp_fair_baseline.py # Combined DP + fairness baseline\n│\n├── ⚙️ configs/\n│   ├── reiot_real.yaml             # Main: Edge-IIoTset + EAGF governance (RECOMMENDED)\n│   ├── reiot_default.yaml          # Alternative RE-IoT config\n│   ├── biometric_default.yaml      # Biometric (secondary validation)\n│   ├── biometric_tuned_auto.yaml   # Tuned biometric\n│   ├── eagf_thresholds.yaml        # Governance thresholds\n│   └── compliance_checklist*.yaml  # Compliance templates\n│\n├── 📊 data/\n│   ├── README.md                   # Data documentation\n│   └── real_iot/\n│       └── edge_iiot.csv           # Edge-IIoTset (150K rows, 40 features) [USER PROVIDED]\n│\n├── 📓 notebooks/\n│   ├── 01_eagf_demo.ipynb          # Quick start demo\n│   ├── 02_statistical_analysis.ipynb # Multi-seed statistics\n│   ├── 03_reiot_fairness.ipynb     # Fairness deep-dive (protocol_type groups)\n│   ├── 04_pareto_front.ipynb       # Pareto front visualization\n│   └── 05_trust_index_sensitivity.ipynb # Sensitivity analysis\n│\n├── 🎨 figures/\n│   ├── pareto_front.png            # Accuracy vs. Fairness vs. Privacy\n│   ├── ti_vs_latency.png           # Trust Index vs. Inference Latency\n│   └── ablation_comparison.png     # Single-pillar vs. multi-pillar\n│\n├── 📋 docs/\n│   ├── metric_definitions.md       # Detailed metric documentation\n│   ├── regulatory_mapping.md       # Compliance + GDPR/CCPA alignment\n│   └── reproducibility.md          # Detailed reproducibility steps\n│\n├── 🧪 results/\n│   ├── final_report.txt            # ✨ MAIN DELIVERABLE—aggregated results\n│   ├── main_results.csv            # Baseline, EAGF, Joint metrics (5 seeds)\n│   ├── pareto_results.csv          # Pareto exploration (25 runs)\n│   └── [seed-specific subdirs]/     # Individual seed outputs\n│\n├── 🛠️ scripts/\n│   ├── run_all.sh                  # Full pipeline (Edge-IIoT + ablation)\n│   ├── run_reiot.sh                # Edge-IIoTset only\n│   ├── run_baseline.sh             # Baseline only\n│   ├── run_pareto_search.sh        # Pareto front exploration\n│   ├── sweep_three_stage.py        # Hyperparameter sweep\n│   └── verify_metrics.py           # Metric validation\n│\n├── ✅ tests/\n│   ├── test_data.py                # Data loading \u0026 preprocessing\n│   ├── test_metrics.py             # Metric computation\n│   ├── conftest.py                 # Pytest fixtures\n│   └── run_tests.py                # Test runner\n│\n├── 🐳 Dockerfile                   # Container setup\n├── 🌍 environment.yml              # Conda environment (optional)\n├── 📚 CONTRIBUTING.md              # Contribution guidelines\n├── 📜 LICENSE                      # MIT License\n├── 📝 CHANGELOG.md                 # Version history\n└── 📋 CITATION.cff                 # BibTeX citation metadata\n```\n\n---\n\n## 🖼️ Visualizations \u0026 Results\n\n### Figure 1: Pareto Front — Trade-off Analysis\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"figures/pareto_front.png\" alt=\"Pareto front: Accuracy vs Fairness vs Privacy\" width=\"90%\" /\u003e\n  \u003cbr\u003e\u003cem\u003eMulti-objective optimization frontier showing EAGF solutions (orange) vs. baseline (blue) across accuracy-fairness-privacy space.\u003c/em\u003e\n\u003c/p\u003e\n\n### Figure 2: Trust Index vs. Inference Latency\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"figures/ti_vs_latency.png\" alt=\"Trust Index vs inference latency comparison\" width=\"90%\" /\u003e\n  \u003cbr\u003e\u003cem\u003eSystem efficiency comparison: EAGF maintains high governance (TI=0.61) with minimal latency overhead (+0.2ms/sample).\u003c/em\u003e\n\u003c/p\u003e\n\n### Figure 3: Ablation Study — Pillar-by-Pillar Comparison\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"figures/figure3.png\" alt=\"Ablation comparison of EAGF pillars\" width=\"90%\" /\u003e\n  \u003cbr\u003e\u003cem\u003eImpact of each governance pillar on Trust Index. Multi-pillar integration significantly outperforms single-pillar approaches.\u003c/em\u003e\n\u003c/p\u003e\n\n---\n\n## 📓 Interactive Notebooks\n\nRun notebooks directly in Google Colab without local setup:\n\n| Notebook | Purpose | Badge |\n|----------|---------|-------|\n| **01_eagf_demo.ipynb** | 5-minute quick start | [![Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/aliakarma/eagf/blob/main/notebooks/01_eagf_demo.ipynb) |\n| **02_statistical_analysis.ipynb** | Multi-seed statistics, hypothesis tests | [![Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/aliakarma/eagf/blob/main/notebooks/02_statistical_analysis.ipynb) |\n| **03_reiot_fairness.ipynb** | Fairness deep-dive by protocol-type groups | [![Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/aliakarma/eagf/blob/main/notebooks/03_reiot_fairness.ipynb) |\n| **04_pareto_front.ipynb** | Interactive Pareto front exploration | [![Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/aliakarma/eagf/blob/main/notebooks/04_pareto_front.ipynb) |\n| **05_trust_index_sensitivity.ipynb** | Trust Index weight sensitivity analysis | [![Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/aliakarma/eagf/blob/main/notebooks/05_trust_index_sensitivity.ipynb) |\n\n---\n\n## ⚙️ Installation\n\n### Requirements\n\n- Python 3.9+\n- pip\n\n### Setup\n\n```bash\ngit clone https://github.com/aliakarma/eagf.git\ncd eagf\n\npython -m venv .venv\n\n# Windows\n.venv\\Scripts\\activate\n\n# Linux / macOS\nsource .venv/bin/activate\n\npip install -r requirements.txt\n```\n\n---\n\n## Dataset Setup\n\n### Edge-IIoTset (Required)\n\n**Dataset**: ML-EdgeIIoT-dataset.csv (real-world IoT anomaly detection)  \n**Source**: IEEE Access 2022 (Ferrag et al.)  \n**Size**: ~78 MB (157.8K raw rows)  \n**Features**: 40 network flow + protocol-specific attributes  \n**Labels**: Normal vs. Attack (imbalanced: 23.1K vs. 126.9K)  \n\n**Note**: EAGF uses real Edge-IIoTset data only. No synthetic fallback.\n\n### Setup Instructions\n\n**Option A: Manual Download (Recommended)**\n\n1. Download `ML-EdgeIIoT-dataset.csv` from [IEEE DataPort](https://dx.doi.org/10.21203/rs.3.rs-1433551/v1)\n2. Extract and place at:\n   ```\n   data/real_iot/edge_iiot.csv\n   ```\n\n**Option B: Verify Existing Data**\n\nIf you already have the dataset:\n\n```bash\n# Check file size (~78 MB)\nls -lh data/real_iot/edge_iiot.csv\n```\n\n---\n\n## 📂 Output Files \u0026 Deliverables\n\n| File | Description | Format |\n|------|-------------|--------|\n| **results/final_report.txt** | ✨ Main deliverable—aggregated metrics, statistics, validation gates | TXT |\n| **results/main_results.csv** | Summary table: baseline, EAGF, Joint DP+Fair across all metrics | CSV |\n| **results/pareto_results.csv** | Pareto search results (25 multi-objective runs with trade-off scores) | CSV |\n| **figures/pareto_front.png** | 3D visualization: accuracy vs. fairness vs. privacy | PNG |\n| **figures/ti_vs_latency.png** | 2D scatter: Trust Index vs. inference latency | PNG |\n| **figures/ablation_comparison.png** | Bar chart: pillar ablation study (single vs. multi-pillar) | PNG |\n| **[seed-specific]/predictions.json** | Per-sample predictions, confidences, fairness group info | JSON |\n| **[seed-specific]/metrics.json** | Detailed metrics for each seed | JSON |\n\n---\n\n## 🚀 Quick Start (Smoke Test)\n\nValidate the entire pipeline in ~5 minutes using a single seed:\n\n```bash\npython run_full_pipeline.py \\\n  --real_dataset edge_iiot \\\n  --config configs/reiot_real.yaml \\\n  --seeds 42 \\\n  --fast\n```\n\n**What happens**:\n- ✓ Loads Edge-IIoTset and validates data\n- ✓ Trains baseline + EAGF + Joint DP+Fair models (1 seed)\n- ✓ Computes fairness, privacy, clarity, accountability metrics\n- ✓ Generates `results/final_report.txt` with summary\n- ✓ Produces figures in `figures/`\n\n**Expected runtime**: ~5 min on CPU (Intel Core i7)\n\n---\n\n## 🏆 Full Experiment (Publication Results)\n\nReproduce final results with 5 independent seeds (statistical rigor):\n\n```bash\npython run_full_pipeline.py \\\n  --real_dataset edge_iiot \\\n  --config configs/reiot_real.yaml \\\n  --seeds 42 43 44 45 46\n```\n\n**Output**:\n- Mean ± std for all governance metrics\n- 95% confidence intervals\n- Pareto front visualization (25 multi-objective runs)\n- Final report with ablation analysis\n- Seed-specific detailed logs\n\n**Expected runtime**: ~10–15 min on CPU\n\n---\n\n## 🔬 Advanced: Pareto Front Search\n\nExplore the full accuracy-fairness-privacy trade-off surface:\n\n```bash\npython -c \"\nfrom src.training.pareto_trainer import ParetoTrainer\nfrom src.utils.edge_iiot_loader import EdgeIIoTLoader\n\nloader = EdgeIIoTLoader('data/real_iot/edge_iiot.csv')\nX_train, X_test, y_train, y_test, groups = loader.load()\n\ntrainer = ParetoTrainer(X_train, y_train, groups, seed=42)\ntrainer.search(n_objectives=3, n_runs=25)  # Explore 25 configurations\ntrainer.plot_pareto('figures/pareto_custom.png')\n\"\n```\n\n---\n\n## Key Results\n\n**Dataset**: Edge-IIoTset (150K samples, protocol-type protected groups)  \n**Baselines**: Unregulated model, Joint DP+Fair  \n**Seeds**: 5 independent runs  \n**Metrics**: Accuracy, Fairness (FPR Parity), Clarity, Privacy, Accountability, Trust Index\n\n### Summary (Mean ± Std)\n\n| Metric | Baseline | **EAGF** | Δ |\n|--------|----------|----------|-----|\n| **Accuracy** | 0.6481 ± 0.0251 | **0.6650 ± 0.0079** | +0.0168 (+2.6%) |\n| **FPR Parity** | 0.4931 ± 0.0849 | **0.7709 ± 0.0573** | +0.2779 (+56.4%) |\n| **Clarity** | 0.6918 ± 0.0432 | **0.7390 ± 0.0548** | +0.0472 (+6.8%) |\n| **Privacy** | 0.2475 ± 0.0030 | **0.2482 ± 0.0025** | +0.0007 (+0.3%, preserved) |\n| **Accountability** | 0.0000 ± 0.0000 | **0.6667 ± 0.0000** | +0.6667 ✓ |\n| **Trust Index** | 0.3581 ± 0.0129 | **0.6062 ± 0.0108** | +0.2481 (+69.3%) |\n\n### Key Findings\n\n- **Fairness via FPR Parity**: EAGF achieves +56.4% improvement in false positive rate fairness across protocol-type groups (web, IoT MQTT, misc). Disparities in false alarm rates reduced from 49.3% to 23% spread.\n- **Trust Index**: Composite governance metric improves by +69.3%, indicating strong multi-objective alignment.\n- **Privacy Preserved**: Differential privacy (ε=2.4) maintained with negligible change vs. baseline. No privacy regression.\n- **Minimal System Overhead**: Inference latency +0.2ms/sample (~11% increase); memory +5.8 MB. Suitable for edge deployment.\n- **Calibration Stability**: ECE and Brier scores comparable (within ±0.05), no metric gaming.\n\n---\n\n## 🏗️ Method Overview\n\n### Four-Pillar Governance Architecture\n\n```\n┌─────────────────────────────────────────────────────────┐\n│                   EAGF Framework                         │\n├─────────┬──────────┬──────────┬────────────────────────┤\n│ Clarity │ Fairness │ Privacy  │  Accountability        │\n├─────────┼──────────┼──────────┼────────────────────────┤\n│  SHAP   │ FPRP     │ DP-SGD   │  Audit Logging + Rules │\n│  Loss   │ Loss     │ Gradient │  Compliance Coverage   │\n└─────────┴──────────┴──────────┴────────────────────────┘\n                      ↓\n              Trust Index (TI)\n         Weighted Aggregation via AHP\n```\n\n### Key Components\n\n| Pillar | Metric | Implementation | Config |\n|--------|--------|-----------------|--------|\n| **Fairness** | FPR Parity | `src/metrics/fairness.py` | `lambda_rp: 0.2` |\n| **Privacy** | DP Accounting | `src/metrics/privacy.py` | `dp_epsilon: 2.4` |\n| **Clarity** | SHAP Sparsity | `src/metrics/clarity.py` | `lambda_c: 0.05` |\n| **Accountability** | Audit Coverage | `src/metrics/accountability.py` | Compliance rules |\n\n---\n\n## 📚 Reproducibility \u0026 Validation\n\n### Deterministic Execution\n\n- **Fixed seeds**: 42–46 (5 independent runs)\n- **Deterministic pipeline**: Reproducible to ±0.005 variance (NumPy/PyTorch seeds)\n- **No hidden preprocessing**: All transformations logged in `audit_logger.py`\n- **Hyperparameter justification**: See [configs/reiot_real.yaml](configs/reiot_real.yaml)\n\n### Validation Gates\n\nAll experiments must satisfy:\n- ✓ FPR Parity EAGF ≥ Baseline + 0.02 (fairness improvement)\n- ✓ Privacy EAGF ≥ Baseline (no regression)\n- ✓ Accuracy drop ≤ 2% (stability requirement)\n- ✓ Trust Index EAGF \u003e Baseline (overall improvement)\n\n---\n\n## 📖 Documentation\n\n| File | Purpose |\n|------|---------|\n| [docs/metric_definitions.md](docs/metric_definitions.md) | Detailed fairness, privacy, clarity, accountability metrics |\n| [docs/regulatory_mapping.md](docs/regulatory_mapping.md) | GDPR, CCPA, ISO alignment |\n| [docs/reproducibility.md](docs/reproducibility.md) | Step-by-step reproducibility guide |\n\n---\n\n## 🔗 Related Work\n\n- **Fairness**: Hardt et al. (2016), Moritz et al. (2020)\n- **Privacy**: Abadi et al. (2016) DP-SGD, Kairouz et al. (2021) DP survey\n- **Explainability**: Lundberg \u0026 Lee (2017) SHAP\n- **IoT Security**: Ferrag et al. (2022) Edge-IIoTset\n\n---\n\n\n## 📜 License\n\nMIT License — See [LICENSE](LICENSE) for full terms.\n\n---\n\n## 🤝 Contributing\n\nContributions welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\n---\n\n## 💬 Support \u0026 Issues\n\nFor reproducibility help, issues, or questions:\n\n1. **Check diagnostics**: See `results/final_report.txt` for detailed error logs\n2. **Verify dataset**: Ensure `data/real_iot/edge_iiot.csv` exists (~78 MB)\n3. **Check environment**: \n   ```bash\n   python -m pip show scikit-learn fairlearn numpy pandas\n   ```\n4. **Open issue**: Include OS, Python version, full error trace, and reproducibility steps\n\n---\n\n## 📧 Contact\n\n- **Maintainer**: Ali Akarma\n- **Email**: [aliakarma974@gmail.com]\n- **Issues**: [GitHub Issues](https://github.com/aliakarma/eagf/issues)\n\n---\n\n**Last Updated**: March 2026 | Python 3.9+ | PyTorch 2.0+\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faliakarma%2Feagf","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faliakarma%2Feagf","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faliakarma%2Feagf/lists"}