Metadata-Version: 2.5
Name: hestia-earth-plugin
Version: 0.1.2
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).
