crbonfree 0.1.0__tar.gz

crbonfree-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,25 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.x'
+
+      - name: Install package with dev extras
+        run: pip install -e ".[dev]"
+
+      - name: Lint
+        run: python -m ruff check
+
+      - name: Test
+        run: python -m pytest

crbonfree-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,72 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags: ['v*']
+
+permissions:
+  contents: read
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write   # required for PyPI Trusted Publishing (OIDC)
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.x'
+
+      - name: Guard — generated client must be present
+        # src/crbonfree/__init__.py ships as a placeholder before the first
+        # generation, so an empty-dir check isn't enough — require real
+        # generated modules (any .py beyond __init__.py) before publishing.
+        run: |
+          generated=$(find src/crbonfree -name '*.py' ! -name '__init__.py' | head -1)
+          if [ -z "$generated" ]; then
+            echo "::error::src/crbonfree/ contains only the placeholder __init__.py. The generated client is produced by sync-spec.yml and merged before tagging a release. Refusing to publish an empty package."
+            exit 1
+          fi
+
+      - name: Install build dependencies
+        run: pip install build
+
+      - name: Install package with dev extras
+        run: pip install -e ".[dev]"
+
+      - name: Set version from tag
+        run: |
+          VERSION="${GITHUB_REF#refs/tags/v}"
+          python - "$VERSION" <<'EOF'
+          import re, sys
+          version = sys.argv[1]
+          path = "pyproject.toml"
+          with open(path, "r", encoding="utf-8") as f:
+              content = f.read()
+          new_content, count = re.subn(
+              r'(?m)^(version\s*=\s*)"[^"]*"',
+              r'\g<1>"%s"' % version,
+              content,
+              count=1,
+          )
+          if count == 0:
+              sys.exit(
+                  "Could not find a `version = \"...\"` line under [project] in "
+                  "pyproject.toml. The version field must be a static string."
+              )
+          with open(path, "w", encoding="utf-8") as f:
+              f.write(new_content)
+          print("Set version to %s" % version)
+          EOF
+
+      - name: Build distribution
+        run: python -m build
+
+      - name: Test
+        run: python -m pytest
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

crbonfree-0.1.0/.github/workflows/sync-spec.yml

@@ -0,0 +1,56 @@
+name: Sync OpenAPI spec
+
+on:
+  schedule:
+    - cron: '0 6 * * *'   # daily 06:00 UTC
+  workflow_dispatch:
+
+jobs:
+  sync:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.x'
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+
+      - name: Download latest backend spec
+        # carbon-offset-backend is a PRIVATE repo, so the default GITHUB_TOKEN
+        # (scoped to THIS repo) can't read its releases. Use a dedicated
+        # fine-grained PAT with read access to that repo's contents, stored as
+        # the BACKEND_SPEC_TOKEN secret. `gh release download` handles the
+        # asset redirect + auth correctly (no token leaked into argv).
+        env:
+          GH_TOKEN: ${{ secrets.BACKEND_SPEC_TOKEN }}
+        run: |
+          gh release download openapi-latest \
+            --repo Crbon-Labs-Inc/carbon-offset-backend \
+            --pattern 'openapi.json' \
+            --output fern/openapi/openapi.json \
+            --clobber
+
+      - name: Re-apply Fern SDK extensions
+        run: python scripts/apply_fern_extensions.py
+
+      - name: Install Fern CLI
+        run: npm install -g fern-api@5.37.0
+
+      - name: Regenerate SDK
+        run: fern generate --group python-sdk --local
+
+      - name: Open PR if changed
+        uses: peter-evans/create-pull-request@v6
+        with:
+          title: 'chore: sync OpenAPI spec from backend'
+          branch: spec-sync/${{ github.run_id }}
+          commit-message: 'chore: regenerate SDK from latest backend spec'
+          body: 'Automated daily spec sync. Review the diff and merge if CI passes.'
+          delete-branch: true

crbonfree-0.1.0/.gitignore

@@ -0,0 +1,43 @@
+# Byte-compiled / optimized / cache
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution / packaging
+build/
+dist/
+*.egg-info/
+*.egg
+.eggs/
+wheels/
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Tooling caches
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.tox/
+.cache/
+
+# Coverage
+.coverage
+.coverage.*
+htmlcov/
+coverage.xml
+
+# Editors / OS
+.idea/
+.vscode/
+*.swp
+.DS_Store
+
+# NOTE: src/crbonfree/ is Fern-generated but COMMITTED — do not ignore it.
+# Fern's local-file-system output drops package-level metadata (its own
+# pyproject/README) alongside the client; our root pyproject.toml is
+# authoritative, so don't commit the generated duplicates.
+src/crbonfree/pyproject.toml
+src/crbonfree/README.md

crbonfree-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Crbon Labs Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

crbonfree-0.1.0/PKG-INFO

@@ -0,0 +1,151 @@
+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>

crbonfree-0.1.0/README.md

@@ -0,0 +1,119 @@
+<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>

crbonfree-0.1.0/examples/quickstart.py

@@ -0,0 +1,35 @@
+"""Minimal CrbonFree quickstart.
+
+Run with an API key in the environment:
+
+    export CRBONFREE_API_KEY="ck_live_..."
+    python examples/quickstart.py
+
+or pass it explicitly to the client below.
+"""
+
+import asyncio
+import os
+
+from crbonfree import AsyncCrbonFree, CrbonFree
+
+API_KEY = os.environ.get("CRBONFREE_API_KEY", "ck_live_...")
+
+
+def sync_example() -> None:
+    crbon = CrbonFree(api_key=API_KEY)
+
+    summary = crbon.telemetry.get_summary()
+    print(f"{summary.data.total_co2_kg} kg CO2 from your AI usage")
+
+
+async def async_example() -> None:
+    crbon = AsyncCrbonFree(api_key=API_KEY)
+
+    summary = await crbon.telemetry.get_summary()
+    print(f"{summary.data.total_co2_kg} kg CO2 from your AI usage")
+
+
+if __name__ == "__main__":
+    sync_example()
+    asyncio.run(async_example())

crbonfree-0.1.0/fern/fern.config.json

@@ -0,0 +1,4 @@
+{
+  "organization": "carbonlabs",
+  "version": "5.37.0"
+}

crbonfree-0.1.0/fern/generators.yml

@@ -0,0 +1,16 @@
+api:
+  specs:
+    - openapi: ./openapi/openapi.json
+groups:
+  python-sdk:
+    generators:
+      - name: fernapi/fern-python-sdk
+        version: 5.14.6
+        output:
+          location: local-file-system
+          path: ../src/crbonfree
+        config:
+          package_name: crbonfree
+          client_class_name: CrbonFree
+          pydantic_config:
+            version: v2