greencalculus 0.1.0__tar.gz

greencalculus-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 GreenCalculus
+
+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.

greencalculus-0.1.0/PKG-INFO

@@ -0,0 +1,111 @@
+Metadata-Version: 2.4
+Name: greencalculus
+Version: 0.1.0
+Summary: The carbon-accounting API — sourced emission factors and audit-traced calculations, every value traceable to its source.
+Author-email: GreenCalculus <jeremiah@greencalculus.com>
+License: MIT
+Project-URL: Homepage, https://greencalculus.com/developers
+Project-URL: Documentation, https://greencalculus.com/developers/docs
+Project-URL: Source, https://github.com/jeremiahsay/greencalculus-sdk
+Keywords: carbon,emissions,co2,co2e,ghg,greenhouse-gas,emission-factors,esg,pcaf,climate,sustainability,carbon-accounting,scope-3,embodied-carbon,defra,ipcc
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# greencalculus
+
+The official Python client for the [GreenCalculus API](https://greencalculus.com/developers) — sourced greenhouse-gas emission factors and audit-traced calculations. Every value comes back with its source cell and data version, so you hand back citable numbers, not guesses.
+
+Zero third-party dependencies (standard library only).
+
+## Install
+
+```bash
+pip install greencalculus
+```
+
+## Quickstart
+
+Get a free API key (1,000 calls/month, no card) at **[greencalculus.com/developers](https://greencalculus.com/developers)**.
+
+```python
+from greencalculus import GreenCalculus
+
+gc = GreenCalculus(api_key="gc_live_...")
+
+# A sourced emission factor. value & unit are at the top level for convenience;
+# the full sourced row (source cell, gas, GWP set) stays under ["factor"].
+f = gc.factor("grid.gbr.electricity.location_based")
+print(f["value"], f["unit"])          # 0.13096 kg CO2e per kWh
+print(f["factor"]["source"]["id"])    # DEFRA_2026
+
+# An audit-traced calculation — the full working, not just a total
+r = gc.ghg_activity(
+    activity={"value": 1000, "unit": "kWh"},
+    factor_key="grid.gbr.electricity.location_based",
+)
+print(r["emissions"]["value"], r["emissions"]["unit"])
+print(r["source"]["id"])                            # e.g. EMBER_YEARLY_ELECTRICITY_2025
+
+# Plain language -> the right factor, with a confidence score
+m = gc.resolve("UK grid electricity")
+```
+
+## Calculations
+
+Every engine returns the formula, the source, the data version, and a deterministic receipt.
+
+```python
+gc.pcaf(asset_class="listed_equity_corporate_bonds", holdings=[{
+    "outstanding_amount": 1_000_000,
+    "denominator": {"type": "evic", "value": 2_500_000_000_000},
+    "company_emissions": {"value": 20_000_000},
+    "data_quality_score": 2,
+}])
+
+gc.embodied(materials=[{
+    "material_key": "materials.concrete.ready_mix.c8_10",
+    "quantity": {"value": 50, "unit": "m3"},
+    "boundary": "A1-C",
+}])
+
+gc.freight(mass={"value": 1, "unit": "tonne"},
+           distance={"value": 100, "unit": "km"},
+           factor_key="freight.rail.tonne_km")
+```
+
+Also available: `electricity`, `spend_based`, `business_travel`, and `batch(calculations=[...])`. Any methodology works via `gc.calculate("<methodology>", **body)`.
+
+## Reproducibility
+
+Pin any factor to a past data version so a figure reproduces exactly in an audit:
+
+```python
+gc.factor("grid.gbr.electricity.location_based", as_of="2026.111")
+```
+
+## Errors
+
+```python
+from greencalculus import GreenCalculusError
+
+try:
+    gc.factor("does.not.exist")
+except GreenCalculusError as e:
+    print(e.status, e.code, e.message)
+```
+
+## Links
+
+- Docs: https://greencalculus.com/developers/docs
+- Data rights & continuity: https://greencalculus.com/developers/trust
+- MCP server (agents): `mcp.greencalculus.com`
+
+MIT licensed.

greencalculus-0.1.0/README.md

@@ -0,0 +1,90 @@
+# greencalculus
+
+The official Python client for the [GreenCalculus API](https://greencalculus.com/developers) — sourced greenhouse-gas emission factors and audit-traced calculations. Every value comes back with its source cell and data version, so you hand back citable numbers, not guesses.
+
+Zero third-party dependencies (standard library only).
+
+## Install
+
+```bash
+pip install greencalculus
+```
+
+## Quickstart
+
+Get a free API key (1,000 calls/month, no card) at **[greencalculus.com/developers](https://greencalculus.com/developers)**.
+
+```python
+from greencalculus import GreenCalculus
+
+gc = GreenCalculus(api_key="gc_live_...")
+
+# A sourced emission factor. value & unit are at the top level for convenience;
+# the full sourced row (source cell, gas, GWP set) stays under ["factor"].
+f = gc.factor("grid.gbr.electricity.location_based")
+print(f["value"], f["unit"])          # 0.13096 kg CO2e per kWh
+print(f["factor"]["source"]["id"])    # DEFRA_2026
+
+# An audit-traced calculation — the full working, not just a total
+r = gc.ghg_activity(
+    activity={"value": 1000, "unit": "kWh"},
+    factor_key="grid.gbr.electricity.location_based",
+)
+print(r["emissions"]["value"], r["emissions"]["unit"])
+print(r["source"]["id"])                            # e.g. EMBER_YEARLY_ELECTRICITY_2025
+
+# Plain language -> the right factor, with a confidence score
+m = gc.resolve("UK grid electricity")
+```
+
+## Calculations
+
+Every engine returns the formula, the source, the data version, and a deterministic receipt.
+
+```python
+gc.pcaf(asset_class="listed_equity_corporate_bonds", holdings=[{
+    "outstanding_amount": 1_000_000,
+    "denominator": {"type": "evic", "value": 2_500_000_000_000},
+    "company_emissions": {"value": 20_000_000},
+    "data_quality_score": 2,
+}])
+
+gc.embodied(materials=[{
+    "material_key": "materials.concrete.ready_mix.c8_10",
+    "quantity": {"value": 50, "unit": "m3"},
+    "boundary": "A1-C",
+}])
+
+gc.freight(mass={"value": 1, "unit": "tonne"},
+           distance={"value": 100, "unit": "km"},
+           factor_key="freight.rail.tonne_km")
+```
+
+Also available: `electricity`, `spend_based`, `business_travel`, and `batch(calculations=[...])`. Any methodology works via `gc.calculate("<methodology>", **body)`.
+
+## Reproducibility
+
+Pin any factor to a past data version so a figure reproduces exactly in an audit:
+
+```python
+gc.factor("grid.gbr.electricity.location_based", as_of="2026.111")
+```
+
+## Errors
+
+```python
+from greencalculus import GreenCalculusError
+
+try:
+    gc.factor("does.not.exist")
+except GreenCalculusError as e:
+    print(e.status, e.code, e.message)
+```
+
+## Links
+
+- Docs: https://greencalculus.com/developers/docs
+- Data rights & continuity: https://greencalculus.com/developers/trust
+- MCP server (agents): `mcp.greencalculus.com`
+
+MIT licensed.

greencalculus-0.1.0/greencalculus/__init__.py

@@ -0,0 +1,155 @@
+"""GreenCalculus — the carbon-accounting API.
+
+Sourced greenhouse-gas emission factors and audit-traced calculations, every
+value traceable to its source cell and data version.
+
+    from greencalculus import GreenCalculus
+
+    gc = GreenCalculus(api_key="gc_live_...")           # free key: greencalculus.com/developers
+
+    # a sourced factor
+    f = gc.factor("grid.gbr.electricity.location_based")
+    print(f["factor"]["value"], f["factor"]["unit"])
+
+    # an audit-traced calculation
+    r = gc.ghg_activity(activity={"value": 1000, "unit": "kWh"},
+                        factor_key="grid.gbr.electricity.location_based")
+    print(r["emissions"]["value"], r["emissions"]["unit"])
+
+    # plain language -> the right factor
+    m = gc.resolve("UK grid electricity")
+
+Zero third-party dependencies (standard library only).
+"""
+from __future__ import annotations
+
+import json as _json
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import Any, Dict, List, Optional
+
+__version__ = "0.1.0"
+__all__ = ["GreenCalculus", "GreenCalculusError"]
+
+DEFAULT_BASE_URL = "https://api.greencalculus.com"
+
+
+class GreenCalculusError(Exception):
+    """Raised when the API returns a non-2xx response."""
+
+    def __init__(self, status: int, code: str, message: str) -> None:
+        self.status = status
+        self.code = code
+        self.message = message
+        super().__init__(f"[{status} {code}] {message}")
+
+
+class GreenCalculus:
+    """A thin, typed client for the GreenCalculus API."""
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = 30.0,
+    ) -> None:
+        if not api_key:
+            raise ValueError(
+                "api_key is required — get a free one at https://greencalculus.com/developers"
+            )
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+
+    # ── transport ────────────────────────────────────────────────────────
+    def _request(
+        self,
+        method: str,
+        path: str,
+        params: Optional[Dict[str, Any]] = None,
+        body: Optional[Dict[str, Any]] = None,
+    ) -> Dict[str, Any]:
+        url = self.base_url + path
+        if params:
+            clean = {k: v for k, v in params.items() if v is not None}
+            if clean:
+                url += "?" + urllib.parse.urlencode(clean)
+        data = _json.dumps(body).encode("utf-8") if body is not None else None
+        req = urllib.request.Request(
+            url,
+            data=data,
+            method=method,
+            headers={
+                "Authorization": f"Bearer {self.api_key}",
+                "Content-Type": "application/json",
+                "Accept": "application/json",
+                "User-Agent": f"greencalculus-python/{__version__}",
+            },
+        )
+        try:
+            with urllib.request.urlopen(req, timeout=self.timeout) as resp:
+                return _json.loads(resp.read().decode("utf-8"))
+        except urllib.error.HTTPError as exc:
+            err: Dict[str, Any] = {}
+            try:
+                err = _json.loads(exc.read().decode("utf-8")).get("error", {})
+            except Exception:
+                pass
+            raise GreenCalculusError(
+                exc.code, err.get("code", "http_error"), err.get("message", str(exc))
+            ) from None
+
+    # ── factors ──────────────────────────────────────────────────────────
+    def factor(self, key: str, as_of: Optional[str] = None) -> Dict[str, Any]:
+        """Look up a single emission factor by its canonical key.
+
+        Pass ``as_of="2026.111"`` to pin a past data version for reproducibility.
+        """
+        return self._request(
+            "GET", "/v1/factors/" + urllib.parse.quote(key, safe=""), params={"as_of": as_of}
+        )
+
+    def resolve(self, description: str, **kwargs: Any) -> Dict[str, Any]:
+        """Resolve a plain-language description to the best-matched factor(s),
+        each with a confidence score."""
+        return self._request("POST", "/v1/calculate/resolve", body={"description": description, **kwargs})
+
+    # ── calculations ─────────────────────────────────────────────────────
+    def calculate(self, methodology: str, **body: Any) -> Dict[str, Any]:
+        """Run a calculation. ``methodology`` is one of: ghg-activity, pcaf,
+        embodied, electricity, freight, spend-based, business-travel, batch."""
+        return self._request("POST", "/v1/calculate/" + methodology, body=body)
+
+    def ghg_activity(self, **body: Any) -> Dict[str, Any]:
+        """GHG Protocol activity-based emissions (activity x factor)."""
+        return self.calculate("ghg-activity", **body)
+
+    def pcaf(self, **body: Any) -> Dict[str, Any]:
+        """PCAF financed emissions."""
+        return self.calculate("pcaf", **body)
+
+    def embodied(self, **body: Any) -> Dict[str, Any]:
+        """EN 15978 embodied carbon."""
+        return self.calculate("embodied", **body)
+
+    def electricity(self, **body: Any) -> Dict[str, Any]:
+        """Scope 2 electricity (location/market based)."""
+        return self.calculate("electricity", **body)
+
+    def freight(self, **body: Any) -> Dict[str, Any]:
+        """Freight / logistics (mass x distance)."""
+        return self.calculate("freight", **body)
+
+    def spend_based(self, **body: Any) -> Dict[str, Any]:
+        """Spend-based EEIO estimation."""
+        return self.calculate("spend-based", **body)
+
+    def business_travel(self, **body: Any) -> Dict[str, Any]:
+        """Business travel (passenger transport)."""
+        return self.calculate("business-travel", **body)
+
+    def batch(self, items: List[Dict[str, Any]]) -> Dict[str, Any]:
+        """Run many calculations in one request. Each item names a `methodology`
+        and carries that methodology's own arguments."""
+        return self.calculate("batch", items=items)

greencalculus-0.1.0/greencalculus.egg-info/PKG-INFO

@@ -0,0 +1,111 @@
+Metadata-Version: 2.4
+Name: greencalculus
+Version: 0.1.0
+Summary: The carbon-accounting API — sourced emission factors and audit-traced calculations, every value traceable to its source.
+Author-email: GreenCalculus <jeremiah@greencalculus.com>
+License: MIT
+Project-URL: Homepage, https://greencalculus.com/developers
+Project-URL: Documentation, https://greencalculus.com/developers/docs
+Project-URL: Source, https://github.com/jeremiahsay/greencalculus-sdk
+Keywords: carbon,emissions,co2,co2e,ghg,greenhouse-gas,emission-factors,esg,pcaf,climate,sustainability,carbon-accounting,scope-3,embodied-carbon,defra,ipcc
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# greencalculus
+
+The official Python client for the [GreenCalculus API](https://greencalculus.com/developers) — sourced greenhouse-gas emission factors and audit-traced calculations. Every value comes back with its source cell and data version, so you hand back citable numbers, not guesses.
+
+Zero third-party dependencies (standard library only).
+
+## Install
+
+```bash
+pip install greencalculus
+```
+
+## Quickstart
+
+Get a free API key (1,000 calls/month, no card) at **[greencalculus.com/developers](https://greencalculus.com/developers)**.
+
+```python
+from greencalculus import GreenCalculus
+
+gc = GreenCalculus(api_key="gc_live_...")
+
+# A sourced emission factor. value & unit are at the top level for convenience;
+# the full sourced row (source cell, gas, GWP set) stays under ["factor"].
+f = gc.factor("grid.gbr.electricity.location_based")
+print(f["value"], f["unit"])          # 0.13096 kg CO2e per kWh
+print(f["factor"]["source"]["id"])    # DEFRA_2026
+
+# An audit-traced calculation — the full working, not just a total
+r = gc.ghg_activity(
+    activity={"value": 1000, "unit": "kWh"},
+    factor_key="grid.gbr.electricity.location_based",
+)
+print(r["emissions"]["value"], r["emissions"]["unit"])
+print(r["source"]["id"])                            # e.g. EMBER_YEARLY_ELECTRICITY_2025
+
+# Plain language -> the right factor, with a confidence score
+m = gc.resolve("UK grid electricity")
+```
+
+## Calculations
+
+Every engine returns the formula, the source, the data version, and a deterministic receipt.
+
+```python
+gc.pcaf(asset_class="listed_equity_corporate_bonds", holdings=[{
+    "outstanding_amount": 1_000_000,
+    "denominator": {"type": "evic", "value": 2_500_000_000_000},
+    "company_emissions": {"value": 20_000_000},
+    "data_quality_score": 2,
+}])
+
+gc.embodied(materials=[{
+    "material_key": "materials.concrete.ready_mix.c8_10",
+    "quantity": {"value": 50, "unit": "m3"},
+    "boundary": "A1-C",
+}])
+
+gc.freight(mass={"value": 1, "unit": "tonne"},
+           distance={"value": 100, "unit": "km"},
+           factor_key="freight.rail.tonne_km")
+```
+
+Also available: `electricity`, `spend_based`, `business_travel`, and `batch(calculations=[...])`. Any methodology works via `gc.calculate("<methodology>", **body)`.
+
+## Reproducibility
+
+Pin any factor to a past data version so a figure reproduces exactly in an audit:
+
+```python
+gc.factor("grid.gbr.electricity.location_based", as_of="2026.111")
+```
+
+## Errors
+
+```python
+from greencalculus import GreenCalculusError
+
+try:
+    gc.factor("does.not.exist")
+except GreenCalculusError as e:
+    print(e.status, e.code, e.message)
+```
+
+## Links
+
+- Docs: https://greencalculus.com/developers/docs
+- Data rights & continuity: https://greencalculus.com/developers/trust
+- MCP server (agents): `mcp.greencalculus.com`
+
+MIT licensed.

greencalculus-0.1.0/greencalculus.egg-info/SOURCES.txt

@@ -0,0 +1,8 @@
+LICENSE
+README.md
+pyproject.toml
+greencalculus/__init__.py
+greencalculus.egg-info/PKG-INFO
+greencalculus.egg-info/SOURCES.txt
+greencalculus.egg-info/dependency_links.txt
+greencalculus.egg-info/top_level.txt

greencalculus-0.1.0/greencalculus.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

greencalculus-0.1.0/greencalculus.egg-info/top_level.txt

@@ -0,0 +1 @@
+greencalculus

greencalculus-0.1.0/pyproject.toml

@@ -0,0 +1,35 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "greencalculus"
+version = "0.1.0"
+description = "The carbon-accounting API — sourced emission factors and audit-traced calculations, every value traceable to its source."
+readme = "README.md"
+requires-python = ">=3.8"
+license = { text = "MIT" }
+authors = [{ name = "GreenCalculus", email = "jeremiah@greencalculus.com" }]
+keywords = [
+  "carbon", "emissions", "co2", "co2e", "ghg", "greenhouse-gas",
+  "emission-factors", "esg", "pcaf", "climate", "sustainability",
+  "carbon-accounting", "scope-3", "embodied-carbon", "defra", "ipcc",
+]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Topic :: Scientific/Engineering",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://greencalculus.com/developers"
+Documentation = "https://greencalculus.com/developers/docs"
+Source = "https://github.com/jeremiahsay/greencalculus-sdk"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["greencalculus*"]

greencalculus-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+