greenmining 1.0.5__tar.gz → 1.0.7__tar.gz

{greenmining-1.0.5 → greenmining-1.0.7}/CHANGELOG.md

@@ -84,7 +84,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Pattern matching engine
 - Green awareness detection
 - Data analysis and reporting
-- CLI interface with Click
 - Docker support with multi-stage builds
 - GitHub Actions CI/CD pipeline
 - PyPI publishing workflow

{greenmining-1.0.5/greenmining.egg-info → greenmining-1.0.7}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: greenmining
-Version: 1.0.5
-Summary: Analyze GitHub repositories to identify green software engineering patterns and energy-efficient practices
+Version: 1.0.7
+Summary: An empirical Python library for Mining Software Repositories (MSR) in Green IT research
 Author-email: Adam Bouafia <a.bouafia@student.vu.nl>
 License: MIT
 Project-URL: Homepage, https://github.com/adam-bouafia/greenmining
@@ -9,7 +9,7 @@ Project-URL: Documentation, https://github.com/adam-bouafia/greenmining#readme
 Project-URL: Repository, https://github.com/adam-bouafia/greenmining
 Project-URL: Issues, https://github.com/adam-bouafia/greenmining/issues
 Project-URL: Changelog, https://github.com/adam-bouafia/greenmining/blob/main/CHANGELOG.md
-Keywords: green-software,gsf,sustainability,carbon-footprint,microservices,mining,repository-analysis,energy-efficiency,github-analysis
+Keywords: green-software,gsf,msr,mining-software-repositories,green-it,sustainability,carbon-footprint,energy-efficiency,repository-analysis,github-analysis,pydriller,empirical-software-engineering
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
 Classifier: Intended Audience :: Science/Research
@@ -45,6 +45,11 @@ Requires-Dist: ruff>=0.1.9; extra == "dev"
 Requires-Dist: mypy>=1.8.0; extra == "dev"
 Requires-Dist: build>=1.0.5; extra == "dev"
 Requires-Dist: twine>=4.0.2; extra == "dev"
+Provides-Extra: energy
+Requires-Dist: psutil>=5.9.0; extra == "energy"
+Requires-Dist: codecarbon>=2.3.0; extra == "energy"
+Provides-Extra: dashboard
+Requires-Dist: flask>=3.0.0; extra == "dashboard"
 Provides-Extra: docs
 Requires-Dist: sphinx>=7.2.0; extra == "docs"
 Requires-Dist: sphinx-rtd-theme>=2.0.0; extra == "docs"
@@ -53,15 +58,30 @@ Dynamic: license-file
 
 # greenmining
 
-Green mining for microservices repositories.
+An empirical Python library for Mining Software Repositories (MSR) in Green IT research.
 
 [![PyPI](https://img.shields.io/pypi/v/greenmining)](https://pypi.org/project/greenmining/)
 [![Python](https://img.shields.io/pypi/pyversions/greenmining)](https://pypi.org/project/greenmining/)
 [![License](https://img.shields.io/github/license/adam-bouafia/greenmining)](LICENSE)
+[![Documentation](https://img.shields.io/badge/docs-readthedocs-blue)](https://greenmining.readthedocs.io/)
 
 ## Overview
 
-`greenmining` is a Python library for analyzing GitHub repositories to identify green software engineering practices and energy-efficient patterns. It detects sustainable software patterns across cloud, web, AI, database, networking, and general categories.
+`greenmining` is a research-grade Python library designed for **empirical Mining Software Repositories (MSR)** studies in **Green IT**. It enables researchers and practitioners to:
+
+- **Mine repositories at scale** - Fetch and analyze GitHub repositories via GraphQL API with configurable filters
+- **Batch analysis with parallelism** - Analyze multiple repositories concurrently with configurable worker pools
+- **Classify green commits** - Detect 122 sustainability patterns from the Green Software Foundation (GSF) catalog
+- **Analyze any repository by URL** - Direct PyDriller-based analysis with support for private repositories
+- **Measure energy consumption** - RAPL, CodeCarbon, and CPU Energy Meter backends for power profiling
+- **Carbon footprint reporting** - CO2 emissions calculation with 20+ country profiles and cloud region support
+- **Power regression detection** - Identify commits that increased energy consumption
+- **Method-level analysis** - Per-method complexity and metrics via Lizard integration
+- **Version power comparison** - Compare power consumption across software versions
+- **Generate research datasets** - Statistical analysis, temporal trends, and publication-ready reports
+- **Web dashboard** - Flask-based interactive visualization of analysis results
+
+Whether you're conducting MSR research, analyzing green software adoption, or measuring the energy footprint of codebases, GreenMining provides the empirical toolkit you need.
 
 ## Installation
 
@@ -310,7 +330,137 @@ print(f"Top patterns: {stats['top_patterns'][:5]}")
 aggregator.export_to_csv(results, "output.csv")
 ```
 
-#### Batch Analysis
+#### URL-Based Repository Analysis
+
+```python
+from greenmining.services.local_repo_analyzer import LocalRepoAnalyzer
+
+analyzer = LocalRepoAnalyzer(
+    max_commits=200,
+    cleanup_after=True,
+)
+
+result = analyzer.analyze_repository("https://github.com/pallets/flask")
+
+print(f"Repository: {result.name}")
+print(f"Commits analyzed: {result.total_commits}")
+print(f"Green-aware: {result.green_commits} ({result.green_commit_rate:.1%})")
+
+for commit in result.commits[:5]:
+    if commit.green_aware:
+        print(f"  {commit.message[:60]}...")
+```
+
+#### Batch Analysis with Parallelism
+
+```python
+from greenmining import analyze_repositories
+
+results = analyze_repositories(
+    urls=[
+        "https://github.com/kubernetes/kubernetes",
+        "https://github.com/istio/istio",
+        "https://github.com/envoyproxy/envoy",
+    ],
+    max_commits=100,
+    parallel_workers=3,
+    energy_tracking=True,
+    energy_backend="auto",
+)
+
+for result in results:
+    print(f"{result.name}: {result.green_commit_rate:.1%} green")
+```
+
+#### Private Repository Analysis
+
+```python
+from greenmining.services.local_repo_analyzer import LocalRepoAnalyzer
+
+# HTTPS with token
+analyzer = LocalRepoAnalyzer(github_token="ghp_xxxx")
+result = analyzer.analyze_repository("https://github.com/company/private-repo")
+
+# SSH with key
+analyzer = LocalRepoAnalyzer(ssh_key_path="~/.ssh/id_rsa")
+result = analyzer.analyze_repository("git@github.com:company/private-repo.git")
+```
+
+#### Power Regression Detection
+
+```python
+from greenmining.analyzers import PowerRegressionDetector
+
+detector = PowerRegressionDetector(
+    test_command="pytest tests/ -x",
+    energy_backend="rapl",
+    threshold_percent=5.0,
+    iterations=5,
+)
+
+regressions = detector.detect(
+    repo_path="/path/to/repo",
+    baseline_commit="v1.0.0",
+    target_commit="HEAD",
+)
+
+for regression in regressions:
+    print(f"Commit {regression.sha[:8]}: +{regression.power_increase:.1f}%")
+```
+
+#### Version Power Comparison
+
+```python
+from greenmining.analyzers import VersionPowerAnalyzer
+
+analyzer = VersionPowerAnalyzer(
+    test_command="pytest tests/",
+    energy_backend="rapl",
+    iterations=10,
+    warmup_iterations=2,
+)
+
+report = analyzer.analyze_versions(
+    repo_path="/path/to/repo",
+    versions=["v1.0", "v1.1", "v1.2", "v2.0"],
+)
+
+print(report.summary())
+print(f"Trend: {report.trend}")
+print(f"Most efficient: {report.most_efficient}")
+```
+
+#### Metrics-to-Power Correlation
+
+```python
+from greenmining.analyzers import MetricsPowerCorrelator
+
+correlator = MetricsPowerCorrelator()
+correlator.fit(
+    metrics=["complexity", "nloc", "code_churn"],
+    metrics_values={
+        "complexity": [10, 20, 30, 40],
+        "nloc": [100, 200, 300, 400],
+        "code_churn": [50, 100, 150, 200],
+    },
+    power_measurements=[5.0, 8.0, 12.0, 15.0],
+)
+
+print(f"Pearson: {correlator.pearson}")
+print(f"Spearman: {correlator.spearman}")
+print(f"Feature importance: {correlator.feature_importance}")
+```
+
+#### Web Dashboard
+
+```python
+from greenmining.dashboard import run_dashboard
+
+# Launch interactive dashboard (requires pip install greenmining[dashboard])
+run_dashboard(data_dir="./data", host="127.0.0.1", port=5000)
+```
+
+#### Pipeline Batch Analysis
 
 ```python
 from greenmining.controllers.repository_controller import RepositoryController
@@ -531,17 +681,24 @@ config = Config(
 
 ### Core Capabilities
 
-- **Pattern Detection**: Automatically identifies 122 sustainability patterns across 15 categories
-- **Keyword Analysis**: Scans commit messages using 321 green software keywords
-- **Custom Repository Fetching**: Fetch repositories with custom search keywords (not limited to microservices)
-- **Repository Analysis**: Analyzes repositories from GitHub with flexible filtering
-- **Batch Processing**: Analyze hundreds of repositories and thousands of commits
-- **Multi-format Output**: Generates Markdown reports, CSV exports, and JSON data
-- **Statistical Analysis**: Calculates green-awareness metrics, pattern distribution, and trends
+- **Pattern Detection**: 122 sustainability patterns across 15 categories from the GSF catalog
+- **Keyword Analysis**: 321 green software detection keywords
+- **Repository Fetching**: GraphQL API with date, star, and language filters
+- **URL-Based Analysis**: Direct PyDriller analysis from GitHub URLs (HTTPS and SSH)
+- **Batch Processing**: Parallel analysis of multiple repositories with configurable workers
+- **Private Repository Support**: Authentication via SSH keys or GitHub tokens
+- **Energy Measurement**: RAPL, CodeCarbon, and CPU Energy Meter backends
+- **Carbon Footprint Reporting**: CO2 emissions with 20+ country profiles and cloud region support (AWS, GCP, Azure)
+- **Power Regression Detection**: Identify commits that increased energy consumption
+- **Metrics-to-Power Correlation**: Pearson and Spearman analysis between code metrics and power
+- **Version Power Comparison**: Compare power consumption across software versions with trend detection
+- **Method-Level Analysis**: Per-method complexity metrics via Lizard integration
+- **Source Code Access**: Before/after source code for refactoring detection
+- **Full Process Metrics**: All 8 PyDriller process metrics (ChangeSet, CodeChurn, CommitsCount, ContributorsCount, ContributorsExperience, HistoryComplexity, HunksCount, LinesCount)
+- **Statistical Analysis**: Correlations, effect sizes, and temporal trends
+- **Multi-format Output**: Markdown reports, CSV exports, JSON data
+- **Web Dashboard**: Flask-based interactive visualization (`pip install greenmining[dashboard]`)
 - **Docker Support**: Pre-built images for containerized analysis
-- **Programmatic API**: Full Python API for custom workflows and integrations
-- **Clean Architecture**: Modular design with services layer (Fetcher, Extractor, Analyzer, Aggregator, Reports)
-- **Energy Measurement**: Real-time energy consumption tracking via RAPL (Linux) or CodeCarbon (cross-platform)
 
 ### Energy Measurement
 
@@ -553,38 +710,44 @@ greenmining includes built-in energy measurement capabilities for tracking the c
 |---------|----------|---------|--------------|
 | **RAPL** | Linux (Intel/AMD) | CPU/RAM energy (Joules) | `/sys/class/powercap/` access |
 | **CodeCarbon** | Cross-platform | Energy + Carbon emissions (gCO2) | `pip install codecarbon` |
+| **CPU Meter** | All platforms | Estimated CPU energy (Joules) | Optional: `pip install psutil` |
+| **Auto** | All platforms | Best available backend | Automatic detection |
 
 #### Python API
 
 ```python
-from greenmining.energy import RAPLEnergyMeter, CodeCarbonMeter
-
-# RAPL (Linux only)
-rapl = RAPLEnergyMeter()
-if rapl.is_available():
-    rapl.start()
-    # ... run analysis ...
-    result = rapl.stop()
-    print(f"Energy: {result.energy_joules:.2f} J")
-
-# CodeCarbon (cross-platform)
-cc = CodeCarbonMeter()
-if cc.is_available():
-    cc.start()
-    # ... run analysis ...
-    result = cc.stop()
-    print(f"Energy: {result.energy_joules:.2f} J")
-    print(f"Carbon: {result.carbon_grams:.4f} gCO2")
+from greenmining.energy import RAPLEnergyMeter, CPUEnergyMeter, get_energy_meter
+
+# Auto-detect best backend
+meter = get_energy_meter("auto")
+meter.start()
+# ... run analysis ...
+result = meter.stop()
+print(f"Energy: {result.joules:.2f} J")
+print(f"Power: {result.watts_avg:.2f} W")
+
+# Integrated energy tracking during analysis
+from greenmining.services.local_repo_analyzer import LocalRepoAnalyzer
+
+analyzer = LocalRepoAnalyzer(energy_tracking=True, energy_backend="auto")
+result = analyzer.analyze_repository("https://github.com/pallets/flask")
+print(f"Analysis energy: {result.energy_metrics['joules']:.2f} J")
 ```
 
-#### Experiment Results
+#### Carbon Footprint Reporting
 
-CodeCarbon was verified with a real experiment:
-- **Repository**: flask (pallets/flask)
-- **Commits analyzed**: 10
-- **Energy measured**: 160.6 J
-- **Carbon emissions**: 0.0119 gCO2
-- **Duration**: 11.28 seconds
+```python
+from greenmining.energy import CarbonReporter
+
+reporter = CarbonReporter(
+    country_iso="USA",
+    cloud_provider="aws",
+    region="us-east-1",
+)
+report = reporter.generate_report(total_joules=3600.0)
+print(f"CO2: {report.total_emissions_kg * 1000:.4f} grams")
+print(f"Equivalent: {report.tree_months:.2f} tree-months to offset")
+```
 
 ### Pattern Database
 
@@ -687,8 +850,14 @@ ruff check greenmining/ tests/
 - PyGithub >= 2.1.1
 - PyDriller >= 2.5
 - pandas >= 2.2.0
-- click >= 8.1.7
-- codecarbon >= 2.0.0 (optional, for cross-platform energy measurement)
+
+**Optional dependencies:**
+
+```bash
+pip install greenmining[energy]      # psutil, codecarbon (energy measurement)
+pip install greenmining[dashboard]   # flask (web dashboard)
+pip install greenmining[dev]         # pytest, black, ruff, mypy (development)
+```
 
 ## License
 

{greenmining-1.0.5 → greenmining-1.0.7}/README.md

@@ -1,14 +1,29 @@
 # greenmining
 
-Green mining for microservices repositories.
+An empirical Python library for Mining Software Repositories (MSR) in Green IT research.
 
 [![PyPI](https://img.shields.io/pypi/v/greenmining)](https://pypi.org/project/greenmining/)
 [![Python](https://img.shields.io/pypi/pyversions/greenmining)](https://pypi.org/project/greenmining/)
 [![License](https://img.shields.io/github/license/adam-bouafia/greenmining)](LICENSE)
+[![Documentation](https://img.shields.io/badge/docs-readthedocs-blue)](https://greenmining.readthedocs.io/)
 
 ## Overview
 
-`greenmining` is a Python library for analyzing GitHub repositories to identify green software engineering practices and energy-efficient patterns. It detects sustainable software patterns across cloud, web, AI, database, networking, and general categories.
+`greenmining` is a research-grade Python library designed for **empirical Mining Software Repositories (MSR)** studies in **Green IT**. It enables researchers and practitioners to:
+
+- **Mine repositories at scale** - Fetch and analyze GitHub repositories via GraphQL API with configurable filters
+- **Batch analysis with parallelism** - Analyze multiple repositories concurrently with configurable worker pools
+- **Classify green commits** - Detect 122 sustainability patterns from the Green Software Foundation (GSF) catalog
+- **Analyze any repository by URL** - Direct PyDriller-based analysis with support for private repositories
+- **Measure energy consumption** - RAPL, CodeCarbon, and CPU Energy Meter backends for power profiling
+- **Carbon footprint reporting** - CO2 emissions calculation with 20+ country profiles and cloud region support
+- **Power regression detection** - Identify commits that increased energy consumption
+- **Method-level analysis** - Per-method complexity and metrics via Lizard integration
+- **Version power comparison** - Compare power consumption across software versions
+- **Generate research datasets** - Statistical analysis, temporal trends, and publication-ready reports
+- **Web dashboard** - Flask-based interactive visualization of analysis results
+
+Whether you're conducting MSR research, analyzing green software adoption, or measuring the energy footprint of codebases, GreenMining provides the empirical toolkit you need.
 
 ## Installation
 
@@ -257,7 +272,137 @@ print(f"Top patterns: {stats['top_patterns'][:5]}")
 aggregator.export_to_csv(results, "output.csv")
 ```
 
-#### Batch Analysis
+#### URL-Based Repository Analysis
+
+```python
+from greenmining.services.local_repo_analyzer import LocalRepoAnalyzer
+
+analyzer = LocalRepoAnalyzer(
+    max_commits=200,
+    cleanup_after=True,
+)
+
+result = analyzer.analyze_repository("https://github.com/pallets/flask")
+
+print(f"Repository: {result.name}")
+print(f"Commits analyzed: {result.total_commits}")
+print(f"Green-aware: {result.green_commits} ({result.green_commit_rate:.1%})")
+
+for commit in result.commits[:5]:
+    if commit.green_aware:
+        print(f"  {commit.message[:60]}...")
+```
+
+#### Batch Analysis with Parallelism
+
+```python
+from greenmining import analyze_repositories
+
+results = analyze_repositories(
+    urls=[
+        "https://github.com/kubernetes/kubernetes",
+        "https://github.com/istio/istio",
+        "https://github.com/envoyproxy/envoy",
+    ],
+    max_commits=100,
+    parallel_workers=3,
+    energy_tracking=True,
+    energy_backend="auto",
+)
+
+for result in results:
+    print(f"{result.name}: {result.green_commit_rate:.1%} green")
+```
+
+#### Private Repository Analysis
+
+```python
+from greenmining.services.local_repo_analyzer import LocalRepoAnalyzer
+
+# HTTPS with token
+analyzer = LocalRepoAnalyzer(github_token="ghp_xxxx")
+result = analyzer.analyze_repository("https://github.com/company/private-repo")
+
+# SSH with key
+analyzer = LocalRepoAnalyzer(ssh_key_path="~/.ssh/id_rsa")
+result = analyzer.analyze_repository("git@github.com:company/private-repo.git")
+```
+
+#### Power Regression Detection
+
+```python
+from greenmining.analyzers import PowerRegressionDetector
+
+detector = PowerRegressionDetector(
+    test_command="pytest tests/ -x",
+    energy_backend="rapl",
+    threshold_percent=5.0,
+    iterations=5,
+)
+
+regressions = detector.detect(
+    repo_path="/path/to/repo",
+    baseline_commit="v1.0.0",
+    target_commit="HEAD",
+)
+
+for regression in regressions:
+    print(f"Commit {regression.sha[:8]}: +{regression.power_increase:.1f}%")
+```
+
+#### Version Power Comparison
+
+```python
+from greenmining.analyzers import VersionPowerAnalyzer
+
+analyzer = VersionPowerAnalyzer(
+    test_command="pytest tests/",
+    energy_backend="rapl",
+    iterations=10,
+    warmup_iterations=2,
+)
+
+report = analyzer.analyze_versions(
+    repo_path="/path/to/repo",
+    versions=["v1.0", "v1.1", "v1.2", "v2.0"],
+)
+
+print(report.summary())
+print(f"Trend: {report.trend}")
+print(f"Most efficient: {report.most_efficient}")
+```
+
+#### Metrics-to-Power Correlation
+
+```python
+from greenmining.analyzers import MetricsPowerCorrelator
+
+correlator = MetricsPowerCorrelator()
+correlator.fit(
+    metrics=["complexity", "nloc", "code_churn"],
+    metrics_values={
+        "complexity": [10, 20, 30, 40],
+        "nloc": [100, 200, 300, 400],
+        "code_churn": [50, 100, 150, 200],
+    },
+    power_measurements=[5.0, 8.0, 12.0, 15.0],
+)
+
+print(f"Pearson: {correlator.pearson}")
+print(f"Spearman: {correlator.spearman}")
+print(f"Feature importance: {correlator.feature_importance}")
+```
+
+#### Web Dashboard
+
+```python
+from greenmining.dashboard import run_dashboard
+
+# Launch interactive dashboard (requires pip install greenmining[dashboard])
+run_dashboard(data_dir="./data", host="127.0.0.1", port=5000)
+```
+
+#### Pipeline Batch Analysis
 
 ```python
 from greenmining.controllers.repository_controller import RepositoryController
@@ -478,17 +623,24 @@ config = Config(
 
 ### Core Capabilities
 
-- **Pattern Detection**: Automatically identifies 122 sustainability patterns across 15 categories
-- **Keyword Analysis**: Scans commit messages using 321 green software keywords
-- **Custom Repository Fetching**: Fetch repositories with custom search keywords (not limited to microservices)
-- **Repository Analysis**: Analyzes repositories from GitHub with flexible filtering
-- **Batch Processing**: Analyze hundreds of repositories and thousands of commits
-- **Multi-format Output**: Generates Markdown reports, CSV exports, and JSON data
-- **Statistical Analysis**: Calculates green-awareness metrics, pattern distribution, and trends
+- **Pattern Detection**: 122 sustainability patterns across 15 categories from the GSF catalog
+- **Keyword Analysis**: 321 green software detection keywords
+- **Repository Fetching**: GraphQL API with date, star, and language filters
+- **URL-Based Analysis**: Direct PyDriller analysis from GitHub URLs (HTTPS and SSH)
+- **Batch Processing**: Parallel analysis of multiple repositories with configurable workers
+- **Private Repository Support**: Authentication via SSH keys or GitHub tokens
+- **Energy Measurement**: RAPL, CodeCarbon, and CPU Energy Meter backends
+- **Carbon Footprint Reporting**: CO2 emissions with 20+ country profiles and cloud region support (AWS, GCP, Azure)
+- **Power Regression Detection**: Identify commits that increased energy consumption
+- **Metrics-to-Power Correlation**: Pearson and Spearman analysis between code metrics and power
+- **Version Power Comparison**: Compare power consumption across software versions with trend detection
+- **Method-Level Analysis**: Per-method complexity metrics via Lizard integration
+- **Source Code Access**: Before/after source code for refactoring detection
+- **Full Process Metrics**: All 8 PyDriller process metrics (ChangeSet, CodeChurn, CommitsCount, ContributorsCount, ContributorsExperience, HistoryComplexity, HunksCount, LinesCount)
+- **Statistical Analysis**: Correlations, effect sizes, and temporal trends
+- **Multi-format Output**: Markdown reports, CSV exports, JSON data
+- **Web Dashboard**: Flask-based interactive visualization (`pip install greenmining[dashboard]`)
 - **Docker Support**: Pre-built images for containerized analysis
-- **Programmatic API**: Full Python API for custom workflows and integrations
-- **Clean Architecture**: Modular design with services layer (Fetcher, Extractor, Analyzer, Aggregator, Reports)
-- **Energy Measurement**: Real-time energy consumption tracking via RAPL (Linux) or CodeCarbon (cross-platform)
 
 ### Energy Measurement
 
@@ -500,38 +652,44 @@ greenmining includes built-in energy measurement capabilities for tracking the c
 |---------|----------|---------|--------------|
 | **RAPL** | Linux (Intel/AMD) | CPU/RAM energy (Joules) | `/sys/class/powercap/` access |
 | **CodeCarbon** | Cross-platform | Energy + Carbon emissions (gCO2) | `pip install codecarbon` |
+| **CPU Meter** | All platforms | Estimated CPU energy (Joules) | Optional: `pip install psutil` |
+| **Auto** | All platforms | Best available backend | Automatic detection |
 
 #### Python API
 
 ```python
-from greenmining.energy import RAPLEnergyMeter, CodeCarbonMeter
-
-# RAPL (Linux only)
-rapl = RAPLEnergyMeter()
-if rapl.is_available():
-    rapl.start()
-    # ... run analysis ...
-    result = rapl.stop()
-    print(f"Energy: {result.energy_joules:.2f} J")
-
-# CodeCarbon (cross-platform)
-cc = CodeCarbonMeter()
-if cc.is_available():
-    cc.start()
-    # ... run analysis ...
-    result = cc.stop()
-    print(f"Energy: {result.energy_joules:.2f} J")
-    print(f"Carbon: {result.carbon_grams:.4f} gCO2")
+from greenmining.energy import RAPLEnergyMeter, CPUEnergyMeter, get_energy_meter
+
+# Auto-detect best backend
+meter = get_energy_meter("auto")
+meter.start()
+# ... run analysis ...
+result = meter.stop()
+print(f"Energy: {result.joules:.2f} J")
+print(f"Power: {result.watts_avg:.2f} W")
+
+# Integrated energy tracking during analysis
+from greenmining.services.local_repo_analyzer import LocalRepoAnalyzer
+
+analyzer = LocalRepoAnalyzer(energy_tracking=True, energy_backend="auto")
+result = analyzer.analyze_repository("https://github.com/pallets/flask")
+print(f"Analysis energy: {result.energy_metrics['joules']:.2f} J")
 ```
 
-#### Experiment Results
+#### Carbon Footprint Reporting
 
-CodeCarbon was verified with a real experiment:
-- **Repository**: flask (pallets/flask)
-- **Commits analyzed**: 10
-- **Energy measured**: 160.6 J
-- **Carbon emissions**: 0.0119 gCO2
-- **Duration**: 11.28 seconds
+```python
+from greenmining.energy import CarbonReporter
+
+reporter = CarbonReporter(
+    country_iso="USA",
+    cloud_provider="aws",
+    region="us-east-1",
+)
+report = reporter.generate_report(total_joules=3600.0)
+print(f"CO2: {report.total_emissions_kg * 1000:.4f} grams")
+print(f"Equivalent: {report.tree_months:.2f} tree-months to offset")
+```
 
 ### Pattern Database
 
@@ -634,8 +792,14 @@ ruff check greenmining/ tests/
 - PyGithub >= 2.1.1
 - PyDriller >= 2.5
 - pandas >= 2.2.0
-- click >= 8.1.7
-- codecarbon >= 2.0.0 (optional, for cross-platform energy measurement)
+
+**Optional dependencies:**
+
+```bash
+pip install greenmining[energy]      # psutil, codecarbon (energy measurement)
+pip install greenmining[dashboard]   # flask (web dashboard)
+pip install greenmining[dev]         # pytest, black, ruff, mypy (development)
+```
 
 ## License