Metadata-Version: 2.4
Name: crbonfree
Version: 0.1.0
Summary: Python SDK for the CrbonFree carbon-offset API
Project-URL: Homepage, https://crbonfree.com
Project-URL: Repository, https://github.com/Crbon-Labs-Inc/crbonfree-python-sdk
Project-URL: Issues, https://github.com/Crbon-Labs-Inc/crbonfree-python-sdk/issues
Author: Crbon Labs Inc.
Author-email: CrbonFree <support@crbonfree.com>
License: MIT
License-File: LICENSE
Keywords: ai,carbon,crbonfree,emissions,offset,sdk
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Typing :: Typed
Requires-Python: >=3.8
Requires-Dist: httpx>=0.23
Requires-Dist: pydantic>=2
Requires-Dist: typing-extensions>=4.0.0
Provides-Extra: dev
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Description-Content-Type: text/markdown

<p align="center">
  <strong>crbonfree</strong>
</p>

<p align="center">
  Measure and offset the carbon footprint of your AI workloads.<br />
  One SDK. Every major provider. Verified retirement receipts.
</p>

<p align="center">
  <a href="https://pypi.org/project/crbonfree/"><img src="https://img.shields.io/pypi/v/crbonfree.svg?style=flat-square" alt="PyPI" /></a>
  <a href="https://github.com/Crbon-Labs-Inc/crbonfree-python-sdk/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-green.svg?style=flat-square" alt="MIT" /></a>
  <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/Python-3.8+-3776ab.svg?style=flat-square&logo=python&logoColor=white" alt="Python" /></a>
  <a href="https://beta.crbonfree.com"><img src="https://img.shields.io/badge/CrbonFree-beta-047857.svg?style=flat-square" alt="CrbonFree" /></a>
</p>

<br />

```bash
pip install crbonfree
```

## What is CrbonFree?

CrbonFree meters the carbon emissions of your AI inference and turns them into
verifiable offsets. Connect your provider accounts, and we measure the
inference, give you the emissions data, and issue signed carbon retirement
receipts you can hand to auditors.

Works with **OpenAI, Anthropic, OpenRouter, AWS Bedrock, and growing.**

## Quickstart

### Authenticate with an API key

Pass your key directly to the client:

```python
from crbonfree import CrbonFree

crbon = CrbonFree(api_key="ck_live_...")

summary = crbon.telemetry.get_summary()
print(f"{summary.data.total_co2_kg} kg CO2 from your AI usage")
```

### Or read it from the environment

Keep the key out of your source by reading it from `CRBONFREE_API_KEY`:

```bash
export CRBONFREE_API_KEY="ck_live_..."
```

```python
import os
from crbonfree import CrbonFree

crbon = CrbonFree(api_key=os.environ["CRBONFREE_API_KEY"])

summary = crbon.telemetry.get_summary()
print(f"{summary.data.total_co2_kg} kg CO2 from your AI usage")
```

The API key is sent on every request as the `X-API-Key` header.

### Async

An async client ships alongside the sync one:

```python
import asyncio
from crbonfree import AsyncCrbonFree

async def main():
    crbon = AsyncCrbonFree(api_key="ck_live_...")
    summary = await crbon.telemetry.get_summary()
    print(f"{summary.data.total_co2_kg} kg CO2 from your AI usage")

asyncio.run(main())
```

## What you can do

| | Method | What it returns |
|---|---|---|
| **Measure** | `crbon.telemetry.get_summary()` | Total CO2, per-model rollups, daily chart |
| **Analyze** | `crbon.usage.get_breakdown()` | Which models cost the most carbon |
| **Organize** | `crbon.projects.list()` | Track emissions by project / team |
| **Prove** | `crbon.billing.list_receipts()` | Signed carbon retirement receipts |
| **Audit** | `crbon.billing.list_audit_packs()` | CSRD-ready compliance artifacts |
| **Manage** | `crbon.apikeys.create()` | Programmatic API key management |

## Pagination

Listing endpoints accept `page` and `limit` parameters directly:

```python
receipts = crbon.billing.list_receipts(page=1, limit=20)
for receipt in receipts.data:
    print(receipt.serial_number)
```

## What's next

Ergonomic auto-pagination helpers and a `crbonfree login` CLI for
zero-config, browser-based authentication are coming in a fast-follow release.

---

<p align="center">
  <a href="https://beta.crbonfree.com">Dashboard</a> &nbsp;·&nbsp;
  <a href="https://github.com/Crbon-Labs-Inc/crbonfree-python-sdk/issues">Issues</a> &nbsp;·&nbsp;
  <a href="https://crbonfree.com">Website</a>
</p>

<p align="center">
  <sub>MIT — Crbon Labs Inc.</sub>
</p>
