hestia-earth-plugin 0.1.1__tar.gz

hestia_earth_plugin-0.1.1/.gitignore

@@ -0,0 +1,32 @@
+.DS_Store
+node_modules/
+__pycache__/
+*.pyc
+.pytest_cache/
+.coverage
+coverage.xml
+htmlcov/
+build/
+dist/
+*.egg-info/
+
+# Local secrets — the plugin's config lives in the user's home folder, never here
+.env
+*.env
+
+# Docs build output
+site/
+public/
+
+# Local docs/dev virtualenv
+.venv/
+
+# Generated by scripts/build-skill-catalogue.py
+docs/skills.md
+
+# Copied from CONTRIBUTING.md by scripts/serve-docs.sh
+docs/contributing.md
+
+# Never commit a debugged node's data
+*.jlog
+*.zip

hestia_earth_plugin-0.1.1/LICENSE

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

hestia_earth_plugin-0.1.1/PKG-INFO

@@ -0,0 +1,123 @@
+Metadata-Version: 2.5
+Name: hestia-earth-plugin
+Version: 0.1.1
+Summary: HESTIA skills for AI coding assistants — debug a HESTIA model on a real node from Claude Code, Codex or Antigravity.
+Project-URL: Homepage, https://hestia-earth.gitlab.io/hestia-plugin/
+Project-URL: Repository, https://gitlab.com/hestia-earth/hestia-plugin
+Project-URL: Issues, https://gitlab.com/hestia-earth/hestia-plugin/-/issues
+Author: HESTIA
+License: MIT License
+        
+        Copyright (c) HESTIA
+        
+        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: agent,antigravity,claude,codex,hestia,lca,skill
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.10
+Requires-Dist: hestia-earth-utils>=0.17
+Requires-Dist: requests>=2.28
+Provides-Extra: dev
+Requires-Dist: black; extra == 'dev'
+Requires-Dist: flake8; extra == 'dev'
+Requires-Dist: flake8-print; extra == 'dev'
+Requires-Dist: hestia-earth-aggregation; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Provides-Extra: models
+Requires-Dist: hestia-earth-models>=0.80; extra == 'models'
+Requires-Dist: hestia-earth-orchestrator>=0.6; extra == 'models'
+Description-Content-Type: text/markdown
+
+# HESTIA plugin
+
+HESTIA skills for AI coding assistants. Ask Claude Code, Codex or Antigravity a question about
+HESTIA data — why a model failed on your Cycle, where an aggregated number came from — and get an
+answer built from what HESTIA actually computed rather than from guesswork.
+
+**This is public.** It is published to PyPI as `hestia-earth-plugin`, and works against the public
+HESTIA API, the public data downloads and the public `hestia-engine-models` repository — no
+checkout, no internal access and no credential is required to use it.
+
+```bash
+pip install hestia-earth-plugin    # or: uv tool install hestia-earth-plugin
+hestia-plugin install              # register the skills with your assistant
+```
+
+Then open your assistant and ask.
+
+Until the first release lands on PyPI, install from the repository instead:
+`pip install git+https://gitlab.com/hestia-earth/hestia-plugin.git`.
+
+## The skills
+
+| | |
+| --- | --- |
+| **`/debug-model`** | Why a model failed on a Cycle, Site or ImpactAssessment, or why a value is what it is. Reads the run log the platform stored, checks the model's documented formula against it, and walks the failure upstream to the root cause. |
+| **`/debug-aggregation`** | Where a number on an aggregation page came from. Rebuilds the weighted mean from the underlying-data download, and names the step — zero-filling, sub-system weighting — that moved it. |
+
+More are being moved across; the [Skills](https://hestia-earth.gitlab.io/hestia-plugin/skills/)
+page is generated from the skills themselves, so it is always the current list.
+
+## Documentation
+
+**<https://hestia-earth.gitlab.io/hestia-plugin>**
+
+- **[Install](https://hestia-earth.gitlab.io/hestia-plugin/)** — every assistant it supports, and where each one reads its skills
+- **[Configure](https://hestia-earth.gitlab.io/hestia-plugin/configure/)** — what a HESTIA API token buys you, and what works without one
+- **[Skills](https://hestia-earth.gitlab.io/hestia-plugin/skills/)** — the full catalogue, generated from the skills themselves
+- **[How it works](https://hestia-earth.gitlab.io/hestia-plugin/how-it-works/)** — the division of labour between the assistant and the tools, and what each skill reads
+- **[Troubleshooting](https://hestia-earth.gitlab.io/hestia-plugin/troubleshooting/)**
+- **[Contributing](https://hestia-earth.gitlab.io/hestia-plugin/contributing/)** — adding a skill, and what must never be committed
+
+Kept there rather than here so each thing is written down once: the install steps lived in
+both places until they disagreed.
+
+## Working on the plugin
+
+Each skill is a folder in `skills/` — a `SKILL.md` your assistant reads, and any `knowledge/`
+playbooks it consults before diagnosing anything. The deterministic tools they call are in
+`src/hestia_earth/plugin/`, one package per skill; nothing there talks to an LLM.
+
+```bash
+pip install -e '.[dev,models]'
+pytest && black src tests && flake8
+hestia-plugin install          # re-run after every change to a SKILL.md
+```
+
+To preview a docs change:
+
+```bash
+scripts/serve-docs.sh          # http://127.0.0.1:8000, rebuilding as you edit
+scripts/serve-docs.sh --build  # one-shot --strict build, the same gate CI runs
+```
+
+It creates a `.venv` on first run and builds the two generated pages — `docs/skills.md` and
+`docs/contributing.md` are git-ignored.
+
+Merge requests target `master`. The rest — commits, playbooks — is in
+[CONTRIBUTING.md](CONTRIBUTING.md), which is also the source of the Contributing page.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

hestia_earth_plugin-0.1.1/README.md

@@ -0,0 +1,72 @@
+# HESTIA plugin
+
+HESTIA skills for AI coding assistants. Ask Claude Code, Codex or Antigravity a question about
+HESTIA data — why a model failed on your Cycle, where an aggregated number came from — and get an
+answer built from what HESTIA actually computed rather than from guesswork.
+
+**This is public.** It is published to PyPI as `hestia-earth-plugin`, and works against the public
+HESTIA API, the public data downloads and the public `hestia-engine-models` repository — no
+checkout, no internal access and no credential is required to use it.
+
+```bash
+pip install hestia-earth-plugin    # or: uv tool install hestia-earth-plugin
+hestia-plugin install              # register the skills with your assistant
+```
+
+Then open your assistant and ask.
+
+Until the first release lands on PyPI, install from the repository instead:
+`pip install git+https://gitlab.com/hestia-earth/hestia-plugin.git`.
+
+## The skills
+
+| | |
+| --- | --- |
+| **`/debug-model`** | Why a model failed on a Cycle, Site or ImpactAssessment, or why a value is what it is. Reads the run log the platform stored, checks the model's documented formula against it, and walks the failure upstream to the root cause. |
+| **`/debug-aggregation`** | Where a number on an aggregation page came from. Rebuilds the weighted mean from the underlying-data download, and names the step — zero-filling, sub-system weighting — that moved it. |
+
+More are being moved across; the [Skills](https://hestia-earth.gitlab.io/hestia-plugin/skills/)
+page is generated from the skills themselves, so it is always the current list.
+
+## Documentation
+
+**<https://hestia-earth.gitlab.io/hestia-plugin>**
+
+- **[Install](https://hestia-earth.gitlab.io/hestia-plugin/)** — every assistant it supports, and where each one reads its skills
+- **[Configure](https://hestia-earth.gitlab.io/hestia-plugin/configure/)** — what a HESTIA API token buys you, and what works without one
+- **[Skills](https://hestia-earth.gitlab.io/hestia-plugin/skills/)** — the full catalogue, generated from the skills themselves
+- **[How it works](https://hestia-earth.gitlab.io/hestia-plugin/how-it-works/)** — the division of labour between the assistant and the tools, and what each skill reads
+- **[Troubleshooting](https://hestia-earth.gitlab.io/hestia-plugin/troubleshooting/)**
+- **[Contributing](https://hestia-earth.gitlab.io/hestia-plugin/contributing/)** — adding a skill, and what must never be committed
+
+Kept there rather than here so each thing is written down once: the install steps lived in
+both places until they disagreed.
+
+## Working on the plugin
+
+Each skill is a folder in `skills/` — a `SKILL.md` your assistant reads, and any `knowledge/`
+playbooks it consults before diagnosing anything. The deterministic tools they call are in
+`src/hestia_earth/plugin/`, one package per skill; nothing there talks to an LLM.
+
+```bash
+pip install -e '.[dev,models]'
+pytest && black src tests && flake8
+hestia-plugin install          # re-run after every change to a SKILL.md
+```
+
+To preview a docs change:
+
+```bash
+scripts/serve-docs.sh          # http://127.0.0.1:8000, rebuilding as you edit
+scripts/serve-docs.sh --build  # one-shot --strict build, the same gate CI runs
+```
+
+It creates a `.venv` on first run and builds the two generated pages — `docs/skills.md` and
+`docs/contributing.md` are git-ignored.
+
+Merge requests target `master`. The rest — commits, playbooks — is in
+[CONTRIBUTING.md](CONTRIBUTING.md), which is also the source of the Contributing page.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

hestia_earth_plugin-0.1.1/pyproject.toml

@@ -0,0 +1,75 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "hestia-earth-plugin"
+dynamic = ["version"]
+description = "HESTIA skills for AI coding assistants — debug a HESTIA model on a real node from Claude Code, Codex or Antigravity."
+readme = "README.md"
+license = { file = "LICENSE" }
+requires-python = ">=3.10"
+authors = [{ name = "HESTIA" }]
+keywords = ["hestia", "agent", "skill", "claude", "codex", "antigravity", "lca"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Science/Research",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Topic :: Scientific/Engineering",
+]
+dependencies = [
+  "requests>=2.28",
+  "hestia-earth-utils>=0.17",
+]
+
+[project.optional-dependencies]
+# Everything needed to re-run the models locally, rather than reading the log the
+# platform already produced. Heavy (pandas, shapely, …), so it is opt-in.
+models = [
+  "hestia-earth-models>=0.80",
+  "hestia-earth-orchestrator>=0.6",
+]
+dev = [
+  "black",
+  "flake8",
+  # the fleet lints with flake8-print; ours ignores T201 on purpose (see .flake8),
+  # and installing the plugin is what keeps that decision visible rather than moot
+  "flake8-print",
+  "pytest",
+  "pytest-cov",
+  # test_split asserts the ported phase ratios still match the engine's own. That
+  # guard is only worth having if it runs in CI, so the engine is a test dependency
+  # rather than something the test skips when it is absent.
+  "hestia-earth-aggregation",
+]
+
+[project.scripts]
+hestia-plugin = "hestia_earth.plugin.cli:main"
+
+[project.urls]
+Homepage = "https://hestia-earth.gitlab.io/hestia-plugin/"
+Repository = "https://gitlab.com/hestia-earth/hestia-plugin"
+Issues = "https://gitlab.com/hestia-earth/hestia-plugin/-/issues"
+
+[tool.hatch.version]
+path = "src/hestia_earth/plugin/version.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/hestia_earth"]
+
+# The skills are the product; they live at the repo root so Claude Code can load the
+# repository directly as a plugin, and are folded into the wheel so a pip install can
+# register them with any host.
+[tool.hatch.build.targets.wheel.force-include]
+"skills" = "hestia_earth/plugin/skills"
+
+[tool.hatch.build.targets.sdist]
+include = ["src", "skills", "tests", "README.md", "LICENSE", "pyproject.toml"]
+
+[tool.black]
+line-length = 88
+target-version = ["py310"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

hestia_earth_plugin-0.1.1/skills/debug-aggregation/SKILL.md

@@ -0,0 +1,173 @@
+---
+name: debug-aggregation
+description: Explain how a value on a HESTIA aggregation page was calculated — which underlying Cycles contributed, how zero-filling and sub-system weighting moved the result, and whether the value was averaged at all. Works from the "Download the underlying datasets" archive. Use when someone asks where an aggregated number came from, or why it looks too low, too high, or unlike the values they can see.
+---
+
+# Debug an aggregated value
+
+Answer "where did this number come from?" for a value on an aggregation page.
+
+An aggregated value is a weighted mean of values that are **not stored** alongside it, so
+nothing on the page explains it. Everything needed is in the underlying-data download, and
+`hestia-plugin debug-aggregation split` extracts it. **This skill's job is the
+interpretation**: turn the tool's output into a formula the reader can follow, with the real
+numbers in it, and say which step accounts for the gap between "the values I can see" and
+"the value that was published".
+
+Nothing here needs a token or a checkout — the archive is a public download, and the
+glossary lookups and `/terms/<id>` it consults are public too.
+
+The user-facing version of this is the guide's
+[Debugging](https://www.hestia.earth/guide/) page. If a run teaches you something durable,
+it belongs there as well as here.
+
+## Input
+
+`/debug-aggregation <path-to.zip> <termId>` — e.g. `/debug-aggregation "Oil palm, fruit.zip" diesel`.
+
+- **The archive** is what the aggregation page's **Download the underlying datasets** gives you,
+  taken as **CSV (Compacted)**. Accept a `.zip`, or a single compacted CSV.
+- **The Term** is a Term **id**, not a name: `diesel`, not `Diesel`. If the user gives a name,
+  convert it (lower camel case) and say what you used.
+
+**With no arguments, ask — do not guess.** Two questions, in this order:
+1. **Which archive?** Ask the user to point at the `.zip`. If they have not downloaded one, tell
+   them: open the aggregation on the platform → download → **Download the underlying datasets** →
+   **CSV (Compacted)**. Stop until you have a path.
+2. **What would you like to know?** Offer the three things this can answer, since the right command
+   differs:
+   - *why is one value what it is* → a Term id, the main case;
+   - *which Cycles are in which sub-aggregation* → the split, no Term needed;
+   - *a Site measurement or management value* → needs `--node-type Site`.
+
+Given only an archive and no Term, run the split (below) and show the groups, then ask which Term.
+
+## Steps
+
+### 1. Run the tool
+
+```bash
+# the split: which Cycle is in which sub-aggregation
+hestia-plugin debug-aggregation split --filepath "<archive>" --dest-folder <scratch>
+
+# one Term, the main case
+hestia-plugin debug-aggregation split --filepath "<archive>" --term <termId>
+
+# a Site measurement or management Term
+hestia-plugin debug-aggregation split --filepath "<archive>" --term <termId> --node-type Site
+```
+
+Write the group CSVs to a scratch directory, never into a repository — the archive is the
+user's data.
+
+**Completeness is usually derived for you.** Emissions take the completeness of the Inputs they
+carry, and the tool works that out. For an **input or product** it cannot, so it prints the areas
+in the file — pick the matching one and re-run with `--completeness <area>`
+(`ureaKgN` → `fertiliser`, `diesel` → `electricityFuel`, `seed` → `seed`). Without it you get the
+values and the groups but not the zero-filling, which is usually the whole answer.
+
+A Term can appear as **several blank nodes** and the tool reports each separately — that is
+correct, not duplication (see "Why a Term appears more than once").
+
+### 2. Read the numbers before writing anything
+
+From the output, for each blank node:
+- `N nodes, R reporting a value` — how many Cycles/Sites reported anything;
+- the per-group table — each sub-aggregation's count and mean;
+- `complete for <area>: C` — the Cycles the value was averaged over, and the split of that into
+  reporting and zero-filled;
+- `published by the aggregation: P over O observations`;
+- the reconstruction table — the weights and the rebuilt total.
+
+**`observations` is the first thing to check.** Present means the node was averaged and is
+rebuildable. **Absent means it was recalculated** from the aggregated data rather than averaged —
+background emissions are computed afresh from the aggregated Inputs once the aggregated Cycle
+exists. There is nothing in the download to rebuild those from; say so plainly and stop rather than
+presenting a total that cannot match.
+
+### 3. Write the explanation as a formula with the numbers in it
+
+The published value is the **weighted mean of the zero-filled group means**:
+
+$$P = \sum_{g} w_g \times \frac{\sum_{i \in g} v_i}{C_g}$$
+
+- $v_i$ — the values the Cycles in group $g$ actually reported;
+- $C_g$ — the Cycles in $g$ **complete** for the Term's completeness area, not the number that
+  reported. The difference is the zero-filling;
+- $w_g$ — the sub-system weight, from the aggregated Cycle's `description`;
+- $\sum_g C_g$ is the Term's published `observations`.
+
+Then substitute. A good answer walks the three steps and names what each one costs, e.g.:
+
+> **`ureaKgN`, published `29.56` kg N.**
+>
+> 1. **22 of the 35 Cycles report Urea**, averaging `105.1`. That is the figure you would get from
+>    the download unaided, and it is 3.6× the published value.
+> 2. **All 35 are complete for `fertiliser`**, so the 13 reporting nothing each contribute a `0`:
+>    `2312.5 / 35 = 66.07`. This is why `observations` is 35 and not 22.
+> 3. **The two sub-systems are weighted very differently** — irrigated `0.23%`, rainfed `99.77%`,
+>    from the country's irrigated area rather than from how many Cycles are in each group. The
+>    irrigated group holds 22 of the 35 Cycles and the higher mean (`87.72`) but almost none of the
+>    weight: `0.0023 × 87.72 + 0.9977 × 29.43 = 29.56`. ✓
+
+Rules for this section:
+- **Substitute real numbers** — a formula with symbols alone is not an answer.
+- **Name the step that did the work.** Usually it is one of zero-filling or weighting; say which.
+- **Say when it does not match**, and what is missing, rather than fudging. The tool prints the
+  percentage off.
+- Keep the arithmetic checkable — show the products, not just the result.
+
+### 4. Answer what was actually asked
+
+Two other shapes come up, and both are usually about a value that looks wrong:
+
+- **"Which Cycle caused this?"** — the per-Cycle list is sorted by value, so the outlier is at the
+  top. Give its `@id`, its group, and the links: `https://www.hestia.earth/cycle/<id>`, its Site via
+  `site.@id`, its Source via `defaultSource.@id`. A Site is worth checking when the outlier is a
+  measurement or land cover, since several Cycles can share one Site.
+- **"Why is this so much lower than the values I see?"** — nearly always zero-filling. Give the
+  reporting mean and the complete-set mean side by side, and the count of Cycles that contributed a
+  `0`.
+
+## Why a Term appears more than once
+
+The compacted download qualifies a Term by the blank node it belongs to. Some qualifiers survive
+aggregation and some do not, so the tool combines the ones that are dropped and keeps the rest
+apart — matching what the aggregation publishes:
+
+| Qualifier | Carried? | Consequence |
+| --- | --- | --- |
+| `operation`, `method`, `methodClassification` | dropped | combined into one node |
+| `inputs` (on an emission) | carried | one node per causing Input |
+| `depthLower` / `depthUpper` | carried | measurements aggregate per depth interval |
+| `startDate` / `endDate` | carried | management is re-dated per aggregation period |
+
+So `diesel` legitimately reports several nodes, and `clayContent` reports one per depth. Explain the
+one the user asked about; do not average them together.
+
+## Things that will trip you up
+
+- **The archive contains the aggregated node itself** (`aggregated = True`). It is the published
+  result, not an input to it. The tool excludes it and uses it as the source of the published
+  value, `observations` and the weights.
+- **The underlying Cycles keep changing.** A download taken today may not reproduce a value computed
+  months ago — check the Cycles' `updatedAt` against the aggregation's creation date before
+  concluding the arithmetic is wrong. If they have moved, say so and suggest a
+  [data release](https://www.hestia.earth/guide/guide-accessing-data-data-releases) from around the
+  aggregation's date.
+- **A missing value is `-`, not blank**, and booleans are `True`/`False`.
+- **Plantation crops split on a third axis** (productive / preparation / non-productive). Those
+  phases are not sub-systems, so the `description` carries no weight for them and the reconstruction
+  stops after zero-filling. Say that rather than reporting a mismatch.
+- **Primary products are rescaled** to the HESTIA default `dryMatter` before averaging. The tool
+  fetches the default and applies it; a product with no `dryMatter` property is not rescaled.
+
+## Guardrails
+
+- Do not invent numbers. Every figure in the explanation comes from the tool's output or from
+  arithmetic you show.
+- Do not present a reconstruction for a node with no `observations` — it was recalculated, not
+  averaged.
+- If the archive has no file for the node type asked about, say which files it does contain.
+- Keep the answer to the value asked about. Note other oddities separately rather than expanding the
+  investigation unasked.