Metadata-Version: 2.1
Name: CarbonIQ
Version: 0.1.5
Summary: A Python package that monitors and tracks the carbon emissions of scripts and applications. It provides insights into the environmental impact of code by analyzing resource usage such as CPU, memory, disk I/O, network, and GPU utilization.
Home-page: https://github.com/ashikrafi/CarbonIQ
Author: Md Ashikur Rahman
Author-email: mdashikur.rafi@gmail.com
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.6
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pynvml
Requires-Dist: psutil


# **CarbonIQ**

**CarbonIQ** is a Python package that monitors and tracks the carbon emissions of scripts and applications. It provides insights into the environmental impact of code by analyzing resource usage such as CPU, memory, disk I/O, network, and GPU utilization.

---

## **Key Features**
- **Comprehensive Resource Tracking**:
  - Tracks energy usage for CPU, memory, disk, and network I/O.
  - Monitors GPU resource utilization via NVIDIA Management Library (NVML).

- **Real-Time Emission Factor Integration**:
  - Dynamically fetches carbon intensity data with live updates (optional).

- **Detailed Execution Summaries**:
  - Generates energy consumption breakdowns and carbon emissions estimates.
  - Includes a gamified badge system to encourage eco-friendly development.

- **Flexible Integration**:
  - Supports usage in functions, API calls, and entire workflows.

- **Platform-Agnostic**:
  - Works seamlessly across operating systems with Python 3.6+.

---

## **Installation**
Install CarbonIQ using `pip`:

```bash
pip install carboniq
```

To disable dependency caching during installation:

```bash
pip install --no-cache-dir --upgrade carboniq
```

---

## **Usage**

### **1. Profiling a Function**
Wrap your function with the `@carbon_profiler` decorator to profile its resource usage:

```python
from carboniq.emissions import carbon_profiler

@carbon_profiler(real_time=True)
def example_function():
    # Perform a computationally heavy task
    result = sum(i ** 2 for i in range(1000000))
    return result

example_function()
```

---

### **2. Profiling an API Call**
Use the decorator for profiling API requests to measure their environmental footprint:

```python
from carboniq.emissions import carbon_profiler
import requests

@carbon_profiler(real_time=True)
def fetch_data_from_api():
    response = requests.get("https://jsonplaceholder.typicode.com/posts")
    return response.json()

fetch_data_from_api()
```

---

### **3. Profiling a Workflow**
CarbonIQ can also profile loops or workflows, such as while loops or batch operations:

```python
from carboniq.emissions import carbon_profiler

@carbon_profiler(real_time=False)
def batch_processing():
    count = 0
    while count < 5:
        # Simulate a task
        print(f"Processing batch {count + 1}")
        count += 1

batch_processing()
```

---

### **4. Profiling Real-Time Tasks**
CarbonIQ is effective for long-running tasks like monitoring server performance:

```python
from carboniq.emissions import carbon_profiler
import time

@carbon_profiler(real_time=True)
def monitor_server():
    print("Monitoring server resources...")
    time.sleep(10)  # Simulate a 10-second monitoring task

monitor_server()
```

---

## **Sample Output**
Below is an example of the detailed summary generated by CarbonIQ after profiling a function:

```
=== CarbonIQ Emission Summary ===
File Path: /Projects/Profiling/example.py
Line Number: 120
Function Name: example_function
Execution Time: 0.013985 seconds
CPU Energy: 0.000003 kWh
Memory Used: 0.593750 MB
Disk I/O: 0.000000 MB
Network I/O: 0.003004 MB
GPU Utilization: 0.000000 %
GPU Memory Used: 0.000000 MB
Total Energy Consumed: 0.000064 kWh
Estimated Emissions: 0.000030 kg CO2
Badge Earned: 🌱 Carbon Saver (Outstanding eco-efficiency!)

=== Badge Ranges ===
🌱 Carbon Saver: 0.0 - 0.01 kg CO2 (Outstanding eco-efficiency!)
🌍 Eco-Friendly Coder: 0.01 - 0.1 kg CO2 (Good environmental performance.)
🛠️ Code Efficiently Next Time: 0.1 - inf kg CO2 (Optimization needed.)
=================================
```

This output includes:
- **Execution Metrics**: Tracks execution time, memory usage, disk/network I/O, and GPU utilization.
- **Energy Consumption**: Summarizes the energy used by the CPU, memory, GPU, and I/O operations.
- **Carbon Emissions**: Provides an estimate of emissions in kg CO₂.
- **Badge System**: Rewards eco-friendly practices with badges and highlights areas for improvement.

---

## **Real-Time Emissions Tracking**
To enable real-time tracking of carbon emissions using live grid intensity data:
1. Use the `real_time=True` argument in the `@carbon_profiler` decorator.
2. Ensure an active internet connection for fetching live emission factors from the [ElectricityMap API](https://electricitymap.org/).

---

## **System Requirements**
- **Python Version**: 3.6 or higher.
- **Optional NVIDIA GPU Tracking**:
  - Requires the `pynvml` library and NVIDIA drivers.

---

## **Contributing**
We welcome contributions to CarbonIQ! To contribute:
1. Fork the repository: [CarbonIQ Repository](https://github.com/ashikrafi/CarbonIQ).
2. Create a new branch for your feature or bug fix.
3. Submit a pull request detailing your changes.

---

## **License**
This project is licensed under the **MIT License**. See the [LICENSE](LICENSE) file for more details.

---

## **Contact**
**Author**: Md Ashikur Rahman  
**Email**: [mdashikur.rafi@gmail.com](mailto:mdashikur.rafi@gmail.com)  
**GitHub**: [ashikrafi](https://github.com/ashikrafi)

---

By integrating CarbonIQ into your development process, you contribute to sustainable software practices and reduce the environmental impact of your applications.
