soif-llm 0.1.0__tar.gz

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

@@ -0,0 +1,24 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install
+        run: pip install -e ".[dev]"
+      - name: Lint
+        run: ruff check .
+      - name: Test
+        run: pytest -q

soif_llm-0.1.0/.github/workflows/docs.yml

@@ -0,0 +1,51 @@
+name: Docs
+
+# Builds the MkDocs site and deploys it to GitHub Pages:
+# https://unchained-labs.github.io/soif/
+# Pages must be set to "GitHub Actions" as the source (configure-pages
+# attempts to enable it automatically on first run).
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Build site
+        run: |
+          pip install mkdocs-material
+          cp METHODOLOGY.md docs/methodology.md
+          cp integrations/claude-code/README.md docs/claude-code.md
+          mkdocs build
+      - uses: actions/configure-pages@v5
+        with:
+          enablement: true
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: site/
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4

soif_llm-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,48 @@
+name: Release to PyPI
+
+# Publishes soif-llm to PyPI via Trusted Publishing (OIDC, no API tokens).
+# One-time setup on pypi.org: add a "pending publisher" for project
+# `soif-llm`, owner `Unchained-Labs`, repo `soif`, workflow `release.yml`,
+# environment `pypi`. Then: create a GitHub release (or push a tag `v*`).
+
+on:
+  release:
+    types: [published]
+  push:
+    tags: ["v*"]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Build sdist and wheel
+        run: |
+          pip install build
+          python -m build
+      - name: Check metadata
+        run: |
+          pip install twine
+          twine check dist/*
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/soif-llm
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

soif_llm-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+.venv/
+__pycache__/
+*.egg-info/
+dist/
+.pytest_cache/
+.ruff_cache/
+site/
+docs/methodology.md
+docs/claude-code.md

soif_llm-0.1.0/LICENSE

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

soif_llm-0.1.0/METHODOLOGY.md

@@ -0,0 +1,140 @@
+# Methodology
+
+`soif` estimates the freshwater **consumed** (evaporated or otherwise removed from the
+local watershed — not merely withdrawn and returned) to serve an LLM response. This
+document explains the model, the factors, their sources, and the limits of the whole
+exercise. Factor values live in [`src/soif/factors.py`](https://github.com/Unchained-Labs/soif/blob/main/src/soif/factors.py) and are
+versioned via `FACTORS_VERSION`.
+
+## 1. The model
+
+Following the operational-water methodology of Ren et al. ([*Making AI Less "Thirsty"*,
+arXiv:2304.03271](https://arxiv.org/abs/2304.03271)), with an optional embodied adder:
+
+```
+E_it       = (output_tokens + reasoning_tokens
+              + 0.1 × input_tokens + 0.01 × cached_tokens) / 1000 × Wh_per_1k(tier)
+E_facility = E_it × PUE
+W_onsite   = E_it × WUE            # cooling-tower / evaporative cooling at the DC
+W_offsite  = E_facility × EWIF     # water consumed generating the electricity
+W_embodied = (W_onsite + W_offsite) × (lifecycle_multiplier − 1)
+W_total    = W_onsite + W_offsite + W_embodied
+```
+
+Units work out neatly: **1 L/kWh ≡ 1 mL/Wh**, so Wh × (L/kWh) yields millilitres.
+
+Every factor is a **(low, mid, high)** scenario triple and the triples are multiplied
+through, so the reported range is a best-case/central/worst-case *scenario spread*, not a
+statistical confidence interval. This is deliberate: public per-prompt figures disagree by
+~100× and pretending otherwise would be false precision.
+
+## 2. Energy per token
+
+Direct measurement is impossible from outside a provider, so `soif` buckets models into
+five **tiers by active parameter count** (MoE models count activated experts only), each
+with a server-side (IT) energy range per 1000 **output** tokens:
+
+| Tier | Active params | Wh / 1k output tokens (low/mid/high) | Examples |
+|---|---|---|---|
+| nano | < 3B | 0.02 / 0.06 / 0.15 | gemini-flash-lite, gpt-5-nano |
+| small | 3–15B | 0.06 / 0.20 / 0.50 | gpt-4o-mini, gemini-flash, llama-8b |
+| medium | 15–70B | 0.15 / 0.50 / 1.20 | claude-haiku, deepseek-v3 (~37B active) |
+| large | 70–250B | 0.30 / 0.80 / 2.00 | gpt-4o, claude-sonnet, mistral-large |
+| frontier | > 250B / premium | 0.80 / 2.00 / 5.00 | gpt-5, o3, claude-opus, grok |
+
+Calibration anchors:
+
+- **Epoch AI** estimates ~**0.3 Wh** for a typical GPT-4o query with ~500 output tokens
+  (server power, ex-PUE) → 0.6 Wh/1k, inside our *large* band (0.3–2.0, mid 0.8).
+  ([epoch.ai](https://epoch.ai/gradient-updates/how-much-energy-does-chatgpt-use))
+- **Google** measured **0.24 Wh** per *median* Gemini Apps prompt in May 2025 — full stack,
+  including idle machines and PUE ([arXiv:2508.15734](https://arxiv.org/abs/2508.15734)).
+  A small-tier 500-token response at mid scenario gives 0.10 Wh IT / 0.11 Wh facility;
+  the median production prompt plausibly sits between our small mid and high scenarios.
+- Prefill (input) tokens are batched and compute-bound rather than memory-bound; we charge
+  them **10%** of an output token, and **1%** for cache-read tokens. Reasoning/thinking
+  tokens are decode work and are charged at the full output rate.
+
+## 3. On-site water (WUE) and overhead (PUE)
+
+WUE = litres evaporated on-site per kWh of IT energy; PUE = facility/IT energy. Provider
+presets from public disclosures:
+
+| Provider preset | WUE L/kWh (low/mid/high) | PUE (low/mid/high) | Basis |
+|---|---|---|---|
+| aws | 0.10 / 0.18 / 0.40 | 1.10 / 1.15 / 1.25 | AWS reported fleet WUE 0.15–0.18 |
+| azure | 0.30 / 0.49 / 0.80 | 1.12 / 1.18 / 1.30 | Microsoft reported ~0.49 |
+| gcp | 0.90 / 1.10 / 1.40 | 1.09 / 1.10 / 1.15 | Google fleet ~1.1 L/kWh, PUE 1.10 |
+| average | 0.30 / 1.00 / 1.90 | 1.20 / 1.40 / 1.60 | industry surveys (Uptime ~1.56 PUE) |
+
+OpenAI models default to `azure`, Anthropic to `aws`, Google to `gcp`, open-weight and
+unknown models to `average`. Override with `provider=` or raw `wue=` / `pue=`.
+
+## 4. Off-site water (EWIF)
+
+Electricity generation consumes water (thermoelectric cooling, hydro reservoir
+evaporation). Regional consumption-weighted factors (L/kWh) follow Ren et al. / Macknick
+et al.; ranges are wide because grid mix and season dominate:
+
+| Region | EWIF L/kWh (low/mid/high) |
+|---|---|
+| world (default) | 0.40 / 1.50 / 3.20 |
+| us | 0.50 / 1.60 / 3.10 |
+| eu | 0.30 / 1.20 / 2.50 |
+| france | 0.50 / 1.50 / 3.00 |
+| nordics | 0.05 / 0.30 / 0.90 |
+| asia | 0.50 / 1.90 / 3.50 |
+| renewable (matched wind/solar PPA) | 0.001 / 0.10 / 0.50 |
+
+Note that "market-based" corporate accounting (buying renewable certificates) does not
+remove the physical water use of the local grid; `soif` models physical (location-based)
+water. Use `region="renewable"` only for genuinely co-located/matched supply.
+
+## 5. Embodied water
+
+Chip fabrication (ultra-pure water in fabs), server manufacturing, and data-center
+construction consume water that should be amortised over the hardware's useful life.
+Public data is thin; Mistral's Large 2 LCA — **45 mL per 400-token response**, lifecycle —
+implies embodied + upstream shares far exceeding operational water, while Google's
+operational figure is ~170× lower. `soif` applies a deliberately wide lifecycle
+multiplier of **1.1× / 1.5× / 3.0×** on operational water, reported separately and
+removable via `include_embodied=False`.
+
+## 6. Cross-checks against the literature
+
+For a ~500-token response, mid scenarios (embodied included):
+
+| Case | soif mid (range) | Published |
+|---|---|---|
+| gemini-2.5-flash, gcp | ≈0.4 mL (0.08–2.5) | Google: 0.26 mL (operational, median prompt) |
+| gpt-4o, azure/us | ≈1.4 mL (0.14–15) | Epoch: 0.3 Wh ⇒ ~0.5–1.5 mL depending on WUE/EWIF |
+| mistral-large, france | ≈1.5 mL (0.2–16) | Mistral LCA: 45 mL (full lifecycle, incl. training amortisation) |
+| GPT-3-era frontier, worst case | high tail 15–50 mL | Ren et al.: 10–50 mL per medium response |
+
+The spread between Google and Mistral is largely **scope** (operational vs. full
+lifecycle including amortised training, which `soif` does not include) and **methodology**
+(measured medians vs. LCA attribution). `soif`'s ranges are designed to bracket the
+defensible literature, with the mid scenario tracking measured operational figures plus a
+moderate embodied adder.
+
+## 7. What this is not
+
+- **Not a measurement.** Only providers can measure; everything here is estimation from
+  public data.
+- **Training and R&D amortisation are excluded** (Mistral includes them; Google excludes
+  them). They can dominate lifecycle numbers for low-traffic models.
+- **Water stress is not weighted.** A millilitre in a water-stressed basin matters more
+  than one in a rainy region; see "Not All Water Consumption Is Equal"
+  ([arXiv:2506.22773](https://arxiv.org/abs/2506.22773)) for a stress-weighted approach —
+  a good future extension.
+- **Factors age fast.** Hardware efficiency improved ~33× year-over-year in Google's
+  disclosure window. Check `FACTORS_VERSION`, and file an issue/PR when better data lands.
+
+## Sources
+
+- Li, Yang, Islam, Ren — *Making AI Less "Thirsty"* — [arXiv:2304.03271](https://arxiv.org/abs/2304.03271) / [CACM](https://cacm.acm.org/sustainability-and-computing/making-ai-less-thirsty/)
+- Google — *Measuring the environmental impact of delivering AI at Google scale* — [arXiv:2508.15734](https://arxiv.org/abs/2508.15734) / [blog](https://cloud.google.com/blog/products/infrastructure/measuring-the-environmental-impact-of-ai-inference)
+- Epoch AI — *How much energy does ChatGPT use?* — [epoch.ai](https://epoch.ai/gradient-updates/how-much-energy-does-chatgpt-use)
+- Mistral AI — *Our contribution to a global environmental standard for AI* (Large 2 LCA, with ADEME/Carbone 4) — see [coverage](https://www.deeplearning.ai/the-batch/french-ai-startup-discloses-full-lifecycle-consumption-and-emissions-for-mistral-large-2)
+- Macknick et al. — water consumption factors for electricity generation (NREL)
+- Provider sustainability reports: AWS water positive updates (WUE 0.15–0.18), Microsoft (~0.49), Google (fleet WUE ~1.1, PUE 1.10)

soif_llm-0.1.0/PKG-INFO

@@ -0,0 +1,211 @@
+Metadata-Version: 2.5
+Name: soif-llm
+Version: 0.1.0
+Summary: Estimate the water footprint of LLM prompts, the way you estimate their cost.
+Project-URL: Homepage, https://github.com/Unchained-Labs/soif
+Project-URL: Repository, https://github.com/Unchained-Labs/soif
+Project-URL: Issues, https://github.com/Unchained-Labs/soif/issues
+Author-email: Erwin Lejeune <erwin.lejeune15@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2026 Unchained Labs
+        
+        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.
+License-File: LICENSE
+Keywords: environment,footprint,green-ai,llm,sustainability,water,wue
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Provides-Extra: tokenizers
+Requires-Dist: tiktoken>=0.7; extra == 'tokenizers'
+Description-Content-Type: text/markdown
+
+# soif 💧
+
+> *soif* — French for **thirst**.
+
+**Estimate the water footprint of LLM prompts, the way you estimate their cost.**
+
+Every LLM answer evaporates real freshwater: data-center cooling towers (on-site) and the
+power plants feeding them (off-site) both consume it. Published per-prompt figures span two
+orders of magnitude — Google measured **0.26 mL** per median Gemini prompt, while Mistral's
+lifecycle analysis reports **45 mL** per 400-token Large 2 response. `soif` turns model +
+tokens + hosting assumptions into an honest **low / mid / high** water estimate with a fully
+documented, versioned methodology ([METHODOLOGY.md](METHODOLOGY.md)).
+
+- Pure Python, **zero runtime dependencies**, MIT-licensed.
+- Library API, CLI, SDK response adapters (OpenAI / Anthropic), a Claude Code hook, and
+  water-aware model routing for agent graphs.
+
+📚 **Docs: [unchained-labs.github.io/soif](https://unchained-labs.github.io/soif/)**
+
+## Install
+
+```bash
+pip install soif-llm                 # imports as `soif`; from a checkout: pip install .
+pip install "soif-llm[tokenizers]"   # optional: exact token counts via tiktoken
+```
+
+(The PyPI distribution is `soif-llm` — the bare name was taken — but the module is `soif`.)
+
+## Quick start
+
+```python
+import soif
+
+est = soif.estimate("gpt-4o", prompt="Explain retrieval-augmented generation.")
+print(est.humanize())
+# ~1.15 mL of water (23.0 drops); range 0.113 mL - 12.46 mL
+
+est.total_ml.mid        # millilitres, mid scenario
+est.onsite_ml           # cooling-tower evaporation at the data center
+est.offsite_ml          # water consumed generating the electricity
+est.embodied_ml         # amortised manufacturing (chips, servers, buildings)
+est.assumptions         # every default the estimate leaned on, spelled out
+```
+
+The **accurate path** is to feed real token usage from an API response — this captures
+actual output length, reasoning ("thinking") tokens, and cache hits:
+
+```python
+response = client.chat.completions.create(...)   # OpenAI — or Anthropic messages.create
+est = soif.from_response(response)
+```
+
+Reasoning models drink more — thinking tokens are output tokens:
+
+```python
+soif.estimate("gpt-5", output_tokens=500, reasoning_effort="high")
+soif.estimate("o3", output_tokens=500, reasoning_tokens=8000)   # from real usage
+```
+
+Control the hosting scenario:
+
+```python
+soif.estimate("llama-3.1-70b", output_tokens=500,
+              provider="aws", region="nordics",      # presets
+              include_embodied=False)                # operational water only
+soif.estimate("my-fine-tune", active_params_b=8, wue=0.2, pue=1.12, ewif=0.4)
+```
+
+## CLI
+
+```bash
+soif estimate "why is the sky blue?" --model claude-sonnet-4-5
+soif estimate -m gpt-4o -i 1200 -o 500 --json
+soif compare gpt-4o gpt-4o-mini gemini-2.5-flash claude-haiku-4-5 -o 500
+soif models
+```
+
+## Agent graphs: metering and minimising water across a chain
+
+Two primitives make water a first-class optimization target in agentic pipelines
+(LangGraph, hand-rolled DAGs, anything):
+
+**1. `Meter` — accumulate across nodes, with a soft budget:**
+
+```python
+meter = soif.Meter(budget_ml=50)
+
+def summarize_node(state):
+    resp = client.chat.completions.create(model=state["model"], ...)
+    meter.record(soif.from_response(resp))
+    if meter.over_budget:
+        state["model"] = "gpt-4o-mini"   # degrade later hops
+    return state
+
+print(meter.summary())
+# 7 call(s): ~18.2 mL of water (3.7 teaspoons); range ... — within budget (18.2/50.0 mL)
+```
+
+**2. `soif.optimize` — route each node to the least-thirsty capable model:**
+
+```python
+from soif import optimize
+
+optimize.pick_model(
+    ["gpt-4o", "gpt-4o-mini", "gemini-2.5-flash", "claude-sonnet-4-5"],
+    min_tier="small",              # capability floor for this node
+    input_tokens=2000, output_tokens=300,
+)
+# -> 'gemini-2.5-flash'... whichever mid-scenario estimate is lowest
+
+optimize.savings("claude-opus-4", "claude-haiku-4-5", output_tokens=500)
+# {'baseline_ml': ..., 'alternative_ml': ..., 'saved_ml': ..., 'saved_pct': ...}
+```
+
+Model choice is the big lever (~30× between tiers); after that: shorter outputs, prompt
+caching, modest reasoning effort, and low-water regions/providers.
+
+## Claude Code hook
+
+Get a water read-out for every session, computed from the transcript's *real* token usage
+— see [integrations/claude-code](integrations/claude-code/README.md). In short, add to
+`.claude/settings.json`:
+
+```json
+{
+  "hooks": {
+    "Stop": [
+      { "hooks": [{ "type": "command", "command": "soif claude-hook" }] }
+    ]
+  }
+}
+```
+
+After each turn: `soif: this session used ~4.31 mL of water (0.9 teaspoons); range ... across 12 model call(s).`
+
+## How it works (short version)
+
+```
+E_it       = tokens × Wh-per-token(model tier)        # server energy
+E_facility = E_it × PUE                               # + cooling/power overhead
+W_onsite   = E_it × WUE                               # cooling evaporation
+W_offsite  = E_facility × EWIF                        # power-plant water
+W_total    = (W_onsite + W_offsite) × lifecycle       # + embodied (optional)
+```
+
+Every factor is a *(low, mid, high)* triple propagated end-to-end, so the range reflects
+genuine uncertainty rather than false precision. Factors are versioned
+(`soif.factors.FACTORS_VERSION`) and calibrated against Google's measured Gemini numbers,
+Epoch AI's GPT-4o analysis, Mistral's Large 2 LCA, and Ren et al.'s methodology.
+**Read [METHODOLOGY.md](METHODOLOGY.md) before quoting numbers** — these are estimates,
+not measurements.
+
+## Contributing
+
+Factor updates (new disclosures, better WUE/PUE/EWIF data, new models) are the most
+valuable contributions — please include sources. `pip install -e ".[dev]" && pytest && ruff check .`
+
+## License
+
+MIT

soif_llm-0.1.0/README.md

@@ -0,0 +1,160 @@
+# soif 💧
+
+> *soif* — French for **thirst**.
+
+**Estimate the water footprint of LLM prompts, the way you estimate their cost.**
+
+Every LLM answer evaporates real freshwater: data-center cooling towers (on-site) and the
+power plants feeding them (off-site) both consume it. Published per-prompt figures span two
+orders of magnitude — Google measured **0.26 mL** per median Gemini prompt, while Mistral's
+lifecycle analysis reports **45 mL** per 400-token Large 2 response. `soif` turns model +
+tokens + hosting assumptions into an honest **low / mid / high** water estimate with a fully
+documented, versioned methodology ([METHODOLOGY.md](METHODOLOGY.md)).
+
+- Pure Python, **zero runtime dependencies**, MIT-licensed.
+- Library API, CLI, SDK response adapters (OpenAI / Anthropic), a Claude Code hook, and
+  water-aware model routing for agent graphs.
+
+📚 **Docs: [unchained-labs.github.io/soif](https://unchained-labs.github.io/soif/)**
+
+## Install
+
+```bash
+pip install soif-llm                 # imports as `soif`; from a checkout: pip install .
+pip install "soif-llm[tokenizers]"   # optional: exact token counts via tiktoken
+```
+
+(The PyPI distribution is `soif-llm` — the bare name was taken — but the module is `soif`.)
+
+## Quick start
+
+```python
+import soif
+
+est = soif.estimate("gpt-4o", prompt="Explain retrieval-augmented generation.")
+print(est.humanize())
+# ~1.15 mL of water (23.0 drops); range 0.113 mL - 12.46 mL
+
+est.total_ml.mid        # millilitres, mid scenario
+est.onsite_ml           # cooling-tower evaporation at the data center
+est.offsite_ml          # water consumed generating the electricity
+est.embodied_ml         # amortised manufacturing (chips, servers, buildings)
+est.assumptions         # every default the estimate leaned on, spelled out
+```
+
+The **accurate path** is to feed real token usage from an API response — this captures
+actual output length, reasoning ("thinking") tokens, and cache hits:
+
+```python
+response = client.chat.completions.create(...)   # OpenAI — or Anthropic messages.create
+est = soif.from_response(response)
+```
+
+Reasoning models drink more — thinking tokens are output tokens:
+
+```python
+soif.estimate("gpt-5", output_tokens=500, reasoning_effort="high")
+soif.estimate("o3", output_tokens=500, reasoning_tokens=8000)   # from real usage
+```
+
+Control the hosting scenario:
+
+```python
+soif.estimate("llama-3.1-70b", output_tokens=500,
+              provider="aws", region="nordics",      # presets
+              include_embodied=False)                # operational water only
+soif.estimate("my-fine-tune", active_params_b=8, wue=0.2, pue=1.12, ewif=0.4)
+```
+
+## CLI
+
+```bash
+soif estimate "why is the sky blue?" --model claude-sonnet-4-5
+soif estimate -m gpt-4o -i 1200 -o 500 --json
+soif compare gpt-4o gpt-4o-mini gemini-2.5-flash claude-haiku-4-5 -o 500
+soif models
+```
+
+## Agent graphs: metering and minimising water across a chain
+
+Two primitives make water a first-class optimization target in agentic pipelines
+(LangGraph, hand-rolled DAGs, anything):
+
+**1. `Meter` — accumulate across nodes, with a soft budget:**
+
+```python
+meter = soif.Meter(budget_ml=50)
+
+def summarize_node(state):
+    resp = client.chat.completions.create(model=state["model"], ...)
+    meter.record(soif.from_response(resp))
+    if meter.over_budget:
+        state["model"] = "gpt-4o-mini"   # degrade later hops
+    return state
+
+print(meter.summary())
+# 7 call(s): ~18.2 mL of water (3.7 teaspoons); range ... — within budget (18.2/50.0 mL)
+```
+
+**2. `soif.optimize` — route each node to the least-thirsty capable model:**
+
+```python
+from soif import optimize
+
+optimize.pick_model(
+    ["gpt-4o", "gpt-4o-mini", "gemini-2.5-flash", "claude-sonnet-4-5"],
+    min_tier="small",              # capability floor for this node
+    input_tokens=2000, output_tokens=300,
+)
+# -> 'gemini-2.5-flash'... whichever mid-scenario estimate is lowest
+
+optimize.savings("claude-opus-4", "claude-haiku-4-5", output_tokens=500)
+# {'baseline_ml': ..., 'alternative_ml': ..., 'saved_ml': ..., 'saved_pct': ...}
+```
+
+Model choice is the big lever (~30× between tiers); after that: shorter outputs, prompt
+caching, modest reasoning effort, and low-water regions/providers.
+
+## Claude Code hook
+
+Get a water read-out for every session, computed from the transcript's *real* token usage
+— see [integrations/claude-code](integrations/claude-code/README.md). In short, add to
+`.claude/settings.json`:
+
+```json
+{
+  "hooks": {
+    "Stop": [
+      { "hooks": [{ "type": "command", "command": "soif claude-hook" }] }
+    ]
+  }
+}
+```
+
+After each turn: `soif: this session used ~4.31 mL of water (0.9 teaspoons); range ... across 12 model call(s).`
+
+## How it works (short version)
+
+```
+E_it       = tokens × Wh-per-token(model tier)        # server energy
+E_facility = E_it × PUE                               # + cooling/power overhead
+W_onsite   = E_it × WUE                               # cooling evaporation
+W_offsite  = E_facility × EWIF                        # power-plant water
+W_total    = (W_onsite + W_offsite) × lifecycle       # + embodied (optional)
+```
+
+Every factor is a *(low, mid, high)* triple propagated end-to-end, so the range reflects
+genuine uncertainty rather than false precision. Factors are versioned
+(`soif.factors.FACTORS_VERSION`) and calibrated against Google's measured Gemini numbers,
+Epoch AI's GPT-4o analysis, Mistral's Large 2 LCA, and Ren et al.'s methodology.
+**Read [METHODOLOGY.md](METHODOLOGY.md) before quoting numbers** — these are estimates,
+not measurements.
+
+## Contributing
+
+Factor updates (new disclosures, better WUE/PUE/EWIF data, new models) are the most
+valuable contributions — please include sources. `pip install -e ".[dev]" && pytest && ruff check .`
+
+## License
+
+MIT