treeig 0.2.0__tar.gz → 0.2.2__tar.gz

treeig-0.2.2/CHANGELOG.md

@@ -0,0 +1,33 @@
+# Changelog
+
+## 0.2.2
+
+- Change `TreeIGNumeric` and `make_scalar_fn` to derive classification scores
+  by default when no native margin exists: binary log odds or centered
+  multiclass log probabilities. `compute_numeric` inherits this default.
+  Callers requiring the former class-probability output must explicitly set
+  `probability_to_score=False`. Zero probabilities require an explicit
+  `probability_floor` for finite scores; no floor is chosen silently.
+
+- Add an agent documentation index, sitemap, canonical URLs, page descriptions,
+  and build checks for documentation discovery. Clarify exact versus numerical
+  model support, baseline guarantees, and related-project links.
+- Lead the README and documentation landing page with the piecewise-constant
+  gradient argument, and move the derivative-impulse figure above the fold.
+- State completeness precision relative to the fitted model's own arithmetic
+  rather than unqualified floating-point precision.
+
+## 0.2.1
+
+- Separate numerical jump-detection tolerance from absolute and relative completeness-warning tolerances; retain raw residual diagnostics.
+- Clarify jump-based fallback behavior, bundled-event completeness, and XGBoost prediction precision.
+- Check numeric regression tests with unexpected runtime warnings treated as errors in CI.
+
+## 0.2.0
+
+- Add optional `treeig.GPUTreeIG` prediction attribution with persistent CUDA model and weighted-baseline state and reusable observation buffers.
+- Keep CPU `TreeIG` as the default; load CUDA only when constructing `GPUTreeIG`.
+- Add the `cuda` installation extra, simulator equivalence tests, and GPU usage and benchmark documentation.
+- Correct GitHub project links and restrict release publishing to version tags.
+
+GPUTreeIG is part of `treeig`, not a separate distribution. GPU performance depends on the workload; existing T4 measurements are examples rather than guarantees.

{treeig-0.2.0 → treeig-0.2.2}/CITATION.cff

@@ -33,4 +33,4 @@ preferred-citation:
       given-names: "Ludger"
   title: "TreeIG: Exact Integrated Gradients for Tree-Based Models"
   year: 2026
-  url: https://github.com/LudgerHentschel/treeig
+  url: "https://www.ludgerhentschel.com/PDFs/Hentschel%20'26g.pdf"

{treeig-0.2.0 → treeig-0.2.2}/MANIFEST.in

@@ -1,4 +1,4 @@
 include LICENSE CITATION.cff CHANGELOG.md
 recursive-include benchmarks *.md *.py
-recursive-include docs *.svg *.md *.py *.txt
+recursive-include docs *.svg *.md *.py *.txt *.html
 prune docs/_build

{treeig-0.2.0 → treeig-0.2.2}/PKG-INFO

@@ -1,9 +1,10 @@
 Metadata-Version: 2.4
 Name: treeig
-Version: 0.2.0
+Version: 0.2.2
 Summary: Exact Integrated Gradients for tree ensembles.
 Author: Ludger Hentschel
 License-Expression: BSD-3-Clause
+Project-URL: Documentation, https://ludgerhentschel.github.io/treeig/
 Project-URL: Homepage, https://github.com/LudgerHentschel/treeig
 Project-URL: Repository, https://github.com/LudgerHentschel/treeig
 Project-URL: Issues, https://github.com/LudgerHentschel/treeig/issues
@@ -25,6 +26,7 @@ Requires-Dist: numpy>=1.24
 Requires-Dist: numba>=0.58
 Provides-Extra: docs
 Requires-Dist: sphinx<9,>=7; extra == "docs"
+Requires-Dist: sphinx-sitemap<3,>=2.6; extra == "docs"
 Requires-Dist: myst-parser<5,>=3; extra == "docs"
 Requires-Dist: pydata-sphinx-theme<0.17,>=0.16; extra == "docs"
 Provides-Extra: cuda
@@ -59,32 +61,51 @@ Dynamic: license-file
 # TreeIG
 
 [![PyPI version](https://img.shields.io/pypi/v/treeig.svg)](https://pypi.org/project/treeig/)
+[![Documentation](https://img.shields.io/badge/docs-user%20guide-blue)](https://ludgerhentschel.github.io/treeig/)
 
-TreeIG computes exact Integrated Gradients for tree-based models. It attributes
-the change in a model's scalar output from a baseline to an observation to the
-input features. For one baseline $x_0$,
+TreeIG is a Python package for Integrated Gradients feature attribution on
+supported numeric tree models. Install and import it as `treeig`. Given a fitted
+model, a baseline point or weighted background, and evaluation rows, `TreeIG`
+returns feature contributions and completeness diagnostics.
 
-$$\sum_j \phi_j = F(x) - F(x_0).$$
+**TreeIG computes exact Integrated Gradients for supported numeric tree models.
+A tree's gradient is zero almost everywhere; its integrated gradient is not.**
 
-TreeIG finds the split boundaries crossed along the straight-line path and sums
-their prediction jumps. For supported models, this avoids numerical integration
-and sampling. Weighted baseline distributions are supported as well.
+Check [supported models](https://ludgerhentschel.github.io/treeig/models.html) before choosing an interface.
+`TreeIG` uses exact structural split crossings; [TreeIGNumeric](https://ludgerhentschel.github.io/treeig/numeric.html)
+is a separately selected numerical fallback. Exact classification explains raw
+margins or logits. Exact parsing requires finite numeric inputs and does not
+support categorical splits or missing-value routing. Installing the CatBoost
+extra does not add an exact CatBoost backend.
 
-## Why Integrated Gradients works for trees
+Tree ensembles are piecewise constant, so $\nabla F = 0$ except on a
+measure-zero set of split boundaries. Numerical Integrated Gradients therefore
+recovers approximately nothing, which is why IG has largely been confined to
+differentiable models.
 
-A tree prediction is constant between splits, so its ordinary gradient is zero
-almost everywhere. But the prediction jumps at split boundaries. Those jumps
-are the contribution that an ordinary pointwise gradient misses: in the
-distributional interpretation, each jump is an impulse whose integral equals
-the jump's height.
+The pointwise gradient is not the full derivative. In the distributional sense,
+$F'$ carries an impulse at each split boundary whose integral equals the
+prediction jump there.
 
 ![A prediction step, its derivative impulse, and its integrated contribution](https://raw.githubusercontent.com/LudgerHentschel/treeig/main/docs/Figure_TreeGradient.svg)
 
 The top panel shows a single prediction step; the middle shows its derivative
 as an impulse at the split; the bottom shows the accumulated contribution.
-Integrating across the split recovers the prediction change. TreeIG applies
-this idea along the path from a baseline to an observation, assigning each
-crossing's jump to its split feature and summing across trees.
+Integrating across the split recovers the prediction change.
+
+TreeIG enumerates the boundaries crossed by the straight-line path from baseline
+to observation, assigns each jump to its split feature, and sums across trees.
+No quadrature and no sampling are involved, and completeness
+
+$$\sum_j \phi_j = F(x) - F(x_0)$$
+
+holds to the floating-point precision of the fitted model's own arithmetic.
+Weighted baseline distributions are supported directly.
+
+The method is developed in Ludger Hentschel's
+[**TreeIG: Exact Integrated Gradients for Tree-Based Models**](https://www.ludgerhentschel.com/PDFs/Hentschel%20'26g.pdf).
+It builds on Integrated Gradients introduced by Sundararajan, Taly, and Yan in
+[**Axiomatic Attribution for Deep Networks** (ICML 2017)](https://proceedings.mlr.press/v70/sundararajan17a.html).
 
 ## Installation
 
@@ -98,7 +119,9 @@ for plotting. The first attribution call includes Numba compilation.
 
 ## Quickstart
 
-With a fitted supported model and numeric evaluation data:
+This snippet assumes a fitted supported model and numeric evaluation data.
+For a standalone example that creates data, fits a model, and checks prediction
+reconstruction, start with [the complete quickstart](https://ludgerhentschel.github.io/treeig/getting-started.html).
 
 ```python
 from treeig import TreeIG
@@ -118,7 +141,7 @@ The baseline defines the comparison. For substantive attribution,
 [CBaseline](https://github.com/LudgerHentschel/cbaseline) is the recommended way
 to construct a prediction-neutral baseline distribution. TreeIG accepts its
 `Background` directly as `baseline=background`, or a matrix of rows with
-`baseline_weights`. See the [baseline guide](https://github.com/LudgerHentschel/treeig/blob/main/docs/baselines.md).
+`baseline_weights`. See the [baseline guide](https://ludgerhentschel.github.io/treeig/baselines.html).
 
 ## Model support and interpretation
 
@@ -129,32 +152,54 @@ splits and missing-value routing are not supported by the exact parser.
 
 `TreeIGNumeric` provides a numerical fallback for other piecewise-constant models,
 including numeric-input CatBoost and probability-only classifiers. Its resolution
-requires care. See [supported models](https://github.com/LudgerHentschel/treeig/blob/main/docs/models.md)
-and [the numerical guide](https://github.com/LudgerHentschel/treeig/blob/main/docs/numeric.md).
+requires care. For probability-only classifiers, it defaults to binary log odds
+or centered multiclass log scores; class probabilities require explicit
+`probability_to_score=False`. Zero probabilities require an explicit
+`probability_floor` for score conversion. A small completeness
+residual alone does not establish accurate individual feature allocations. See [supported models](https://ludgerhentschel.github.io/treeig/models.html)
+and [the numerical guide](https://ludgerhentschel.github.io/treeig/numeric.html).
 
 TreeIG and TreeSHAP answer different attribution questions. TreeIG can be fast
 on substantial attribution workloads, but relative speed depends on the model,
-baselines, and batch size. The [comparison and benchmarks](https://github.com/LudgerHentschel/treeig/blob/main/docs/comparison.md)
+baselines, and batch size. The [comparison and benchmarks](https://ludgerhentschel.github.io/treeig/comparison.html)
 explain the distinction and report measured examples.
 
 ## Documentation
 
-The [user guide](https://github.com/LudgerHentschel/treeig/blob/main/docs/index.md)
+For automated readers, [llms.txt](https://ludgerhentschel.github.io/treeig/llms.txt)
+maps the guides, complete examples, and rendered API reference.
+
+The [user guide](https://ludgerhentschel.github.io/treeig/)
 covers a complete runnable example, baseline distributions, classification,
 plots, loss attribution, numerical conventions, and performance. The Sphinx
 sources also build into searchable HTML with an API reference; see
-[building the documentation](https://github.com/LudgerHentschel/treeig/blob/main/docs/building.md).
+[building the documentation](https://ludgerhentschel.github.io/treeig/building.html).
 
 ## Optional GPU support
 
-`GPUTreeIG` is an optional CUDA backend within this package. CPU `TreeIG` remains
-the default; GPU performance depends on the workload. See
-[GPU documentation](https://github.com/LudgerHentschel/treeig/blob/main/docs/gpu.md)
+`TreeIG` is already fast enough for most applications and remains the default.
+When attribution speed matters and an NVIDIA GPU is available, `GPUTreeIG` can
+be materially faster; recorded T4 comparisons show roughly 9–20× speedups on
+the reported workloads. Performance depends on the problem. See
+[GPU documentation](https://ludgerhentschel.github.io/treeig/gpu.html)
 for installation and limitations.
 
+## Related projects
+
+| Package | When to use it |
+|---|---|
+| [UnifiedIG](https://ludgerhentschel.github.io/unifiedig/) (`unifiedig`) | A common Integrated Gradients interface across supported tree and smooth model families. |
+| [CBaseline](https://ludgerhentschel.github.io/cbaseline/) (`cbaseline`) | Construct empirical reference distributions; TreeIG accepts its backgrounds with their weights directly. |
+| [skgrad](https://ludgerhentschel.github.io/skgrad/) (`skgrad`) | Obtain analytic input gradients and Jacobians for supported smooth scikit-learn models. |
+
+Use TreeIG directly when you need its tree-specific attribution interface.
+See [the Integrated Gradients stack](https://ludgerhentschel.github.io/treeig/ig-stack.html)
+for how the packages compose and why output scales must agree.
+
 ## Citation and license
 
-If you use TreeIG in your work, please cite:
+If you use TreeIG in your work, please cite the
+[TreeIG paper](https://www.ludgerhentschel.com/PDFs/Hentschel%20'26g.pdf):
 
 ```bibtex
 @misc{hentschel2026treeig,
@@ -166,3 +211,5 @@ If you use TreeIG in your work, please cite:
 ```
 
 Released under the [BSD-3-Clause license](https://github.com/LudgerHentschel/treeig/blob/main/LICENSE).
+
+Release maintainers: see [Publishing releases](docs/publishing.md).

treeig-0.2.2/README.md

@@ -0,0 +1,155 @@
+# TreeIG
+
+[![PyPI version](https://img.shields.io/pypi/v/treeig.svg)](https://pypi.org/project/treeig/)
+[![Documentation](https://img.shields.io/badge/docs-user%20guide-blue)](https://ludgerhentschel.github.io/treeig/)
+
+TreeIG is a Python package for Integrated Gradients feature attribution on
+supported numeric tree models. Install and import it as `treeig`. Given a fitted
+model, a baseline point or weighted background, and evaluation rows, `TreeIG`
+returns feature contributions and completeness diagnostics.
+
+**TreeIG computes exact Integrated Gradients for supported numeric tree models.
+A tree's gradient is zero almost everywhere; its integrated gradient is not.**
+
+Check [supported models](https://ludgerhentschel.github.io/treeig/models.html) before choosing an interface.
+`TreeIG` uses exact structural split crossings; [TreeIGNumeric](https://ludgerhentschel.github.io/treeig/numeric.html)
+is a separately selected numerical fallback. Exact classification explains raw
+margins or logits. Exact parsing requires finite numeric inputs and does not
+support categorical splits or missing-value routing. Installing the CatBoost
+extra does not add an exact CatBoost backend.
+
+Tree ensembles are piecewise constant, so $\nabla F = 0$ except on a
+measure-zero set of split boundaries. Numerical Integrated Gradients therefore
+recovers approximately nothing, which is why IG has largely been confined to
+differentiable models.
+
+The pointwise gradient is not the full derivative. In the distributional sense,
+$F'$ carries an impulse at each split boundary whose integral equals the
+prediction jump there.
+
+![A prediction step, its derivative impulse, and its integrated contribution](https://raw.githubusercontent.com/LudgerHentschel/treeig/main/docs/Figure_TreeGradient.svg)
+
+The top panel shows a single prediction step; the middle shows its derivative
+as an impulse at the split; the bottom shows the accumulated contribution.
+Integrating across the split recovers the prediction change.
+
+TreeIG enumerates the boundaries crossed by the straight-line path from baseline
+to observation, assigns each jump to its split feature, and sums across trees.
+No quadrature and no sampling are involved, and completeness
+
+$$\sum_j \phi_j = F(x) - F(x_0)$$
+
+holds to the floating-point precision of the fitted model's own arithmetic.
+Weighted baseline distributions are supported directly.
+
+The method is developed in Ludger Hentschel's
+[**TreeIG: Exact Integrated Gradients for Tree-Based Models**](https://www.ludgerhentschel.com/PDFs/Hentschel%20'26g.pdf).
+It builds on Integrated Gradients introduced by Sundararajan, Taly, and Yan in
+[**Axiomatic Attribution for Deep Networks** (ICML 2017)](https://proceedings.mlr.press/v70/sundararajan17a.html).
+
+## Installation
+
+```bash
+pip install "treeig[sklearn]"
+```
+
+Requires Python 3.9 or later, NumPy, and Numba. Install the model library you use;
+extras include `sklearn`, `xgboost`, `lightgbm`, and `catboost`. SHAP is optional
+for plotting. The first attribution call includes Numba compilation.
+
+## Quickstart
+
+This snippet assumes a fitted supported model and numeric evaluation data.
+For a standalone example that creates data, fits a model, and checks prediction
+reconstruction, start with [the complete quickstart](https://ludgerhentschel.github.io/treeig/getting-started.html).
+
+```python
+from treeig import TreeIG
+
+# A representative training row provides a simple reference.
+ig = TreeIG(model, baseline=X_train[0])
+result = ig.explain(X_eval)
+phi = result.values
+print(result.max_abs_completeness_error)
+```
+
+`phi` has one row per observation and one column per feature. Positive values
+increase the explained output relative to the baseline; negative values decrease
+it. Use `ig.attribute(X_eval)` when only the attribution array is needed.
+
+The baseline defines the comparison. For substantive attribution,
+[CBaseline](https://github.com/LudgerHentschel/cbaseline) is the recommended way
+to construct a prediction-neutral baseline distribution. TreeIG accepts its
+`Background` directly as `baseline=background`, or a matrix of rows with
+`baseline_weights`. See the [baseline guide](https://ludgerhentschel.github.io/treeig/baselines.html).
+
+## Model support and interpretation
+
+Exact backends cover selected scikit-learn tree regressors and gradient boosting,
+XGBoost, and LightGBM. Regression explains predictions; classification explains
+raw margins, not probabilities. Inputs must be finite and numeric; categorical
+splits and missing-value routing are not supported by the exact parser.
+
+`TreeIGNumeric` provides a numerical fallback for other piecewise-constant models,
+including numeric-input CatBoost and probability-only classifiers. Its resolution
+requires care. For probability-only classifiers, it defaults to binary log odds
+or centered multiclass log scores; class probabilities require explicit
+`probability_to_score=False`. Zero probabilities require an explicit
+`probability_floor` for score conversion. A small completeness
+residual alone does not establish accurate individual feature allocations. See [supported models](https://ludgerhentschel.github.io/treeig/models.html)
+and [the numerical guide](https://ludgerhentschel.github.io/treeig/numeric.html).
+
+TreeIG and TreeSHAP answer different attribution questions. TreeIG can be fast
+on substantial attribution workloads, but relative speed depends on the model,
+baselines, and batch size. The [comparison and benchmarks](https://ludgerhentschel.github.io/treeig/comparison.html)
+explain the distinction and report measured examples.
+
+## Documentation
+
+For automated readers, [llms.txt](https://ludgerhentschel.github.io/treeig/llms.txt)
+maps the guides, complete examples, and rendered API reference.
+
+The [user guide](https://ludgerhentschel.github.io/treeig/)
+covers a complete runnable example, baseline distributions, classification,
+plots, loss attribution, numerical conventions, and performance. The Sphinx
+sources also build into searchable HTML with an API reference; see
+[building the documentation](https://ludgerhentschel.github.io/treeig/building.html).
+
+## Optional GPU support
+
+`TreeIG` is already fast enough for most applications and remains the default.
+When attribution speed matters and an NVIDIA GPU is available, `GPUTreeIG` can
+be materially faster; recorded T4 comparisons show roughly 9–20× speedups on
+the reported workloads. Performance depends on the problem. See
+[GPU documentation](https://ludgerhentschel.github.io/treeig/gpu.html)
+for installation and limitations.
+
+## Related projects
+
+| Package | When to use it |
+|---|---|
+| [UnifiedIG](https://ludgerhentschel.github.io/unifiedig/) (`unifiedig`) | A common Integrated Gradients interface across supported tree and smooth model families. |
+| [CBaseline](https://ludgerhentschel.github.io/cbaseline/) (`cbaseline`) | Construct empirical reference distributions; TreeIG accepts its backgrounds with their weights directly. |
+| [skgrad](https://ludgerhentschel.github.io/skgrad/) (`skgrad`) | Obtain analytic input gradients and Jacobians for supported smooth scikit-learn models. |
+
+Use TreeIG directly when you need its tree-specific attribution interface.
+See [the Integrated Gradients stack](https://ludgerhentschel.github.io/treeig/ig-stack.html)
+for how the packages compose and why output scales must agree.
+
+## Citation and license
+
+If you use TreeIG in your work, please cite the
+[TreeIG paper](https://www.ludgerhentschel.com/PDFs/Hentschel%20'26g.pdf):
+
+```bibtex
+@misc{hentschel2026treeig,
+  author = {Hentschel, Ludger},
+  title  = {{TreeIG}: Exact Integrated Gradients for Tree-Based Models},
+  year   = {2026},
+  url    = {https://www.ludgerhentschel.com/PDFs/Hentschel%20'26g.pdf},
+}
+```
+
+Released under the [BSD-3-Clause license](https://github.com/LudgerHentschel/treeig/blob/main/LICENSE).
+
+Release maintainers: see [Publishing releases](docs/publishing.md).

treeig-0.2.2/docs/_templates/documentation-nav.html

@@ -0,0 +1,8 @@
+{# Show the complete guide rather than only children of the active page. #}
+<nav class="bd-docs-nav bd-links" aria-label="Documentation navigation">
+  <p class="bd-links__title" role="heading" aria-level="1">Documentation</p>
+  <div class="bd-toc-item navbar-nav">
+    {{ generate_toctree_html("sidebar", startdepth=0, show_nav_level=1,
+         maxdepth=1, collapse=False, includehidden=True, titles_only=True) }}
+  </div>
+</nav>

{treeig-0.2.0 → treeig-0.2.2}/docs/api.md

@@ -1,3 +1,9 @@
+---
+myst:
+  html_meta:
+    description: "Look up TreeIG, TreeIGNumeric, Explanation, and public functions in the rendered API reference."
+---
+
 # API reference
 
 The primary interfaces are `TreeIG` for exact structural attribution,

{treeig-0.2.0 → treeig-0.2.2}/docs/baselines.md

@@ -1,3 +1,9 @@
+---
+myst:
+  html_meta:
+    description: "Choose TreeIG baseline points or weighted reference distributions, including CBaseline backgrounds."
+---
+
 # Choosing baselines and batching
 
 The baseline determines the question an attribution answers. With one baseline,
@@ -14,15 +20,18 @@ model need not satisfy $F(\sum_k w_k b_k)=\sum_k w_k F(b_k)$.
 
 For Integrated Gradients, the baseline determines the prediction contrast
 being explained. **[CBaseline](https://github.com/LudgerHentschel/cbaseline) is the
-preferred way to construct TreeIG baselines.** CBaseline produces empirical,
-prediction-neutral baseline *distributions* whose weighted mean model output is
-the chosen reference prediction. TreeIG then explains the model prediction
-relative to that reference level rather than relative to an arbitrary feature
-vector such as the feature-wise mean.
+preferred way to construct TreeIG baselines.** Its calibrated mode produces
+empirical baseline *distributions* whose weighted mean model output meets the
+chosen reference prediction within numerical tolerances, or raises on failure.
+Equal-weight selections approximate neutrality and report their residual.
+TreeIG explains the model prediction relative to the **achieved weighted mean**,
+so preserve both the rows and weights when passing a background.
 
 TreeIG accepts a CBaseline `Background` directly and evaluates its weighted
 baseline paths efficiently. See CBaseline for construction choices and the
-interpretation of the reference prediction `f0`.
+interpretation of the reference prediction `f0`: start with
+[background modes](https://ludgerhentschel.github.io/cbaseline/backgrounds.html)
+and [diagnostics](https://ludgerhentschel.github.io/cbaseline/diagnostics.html).
 
 A single representative observation, domain-specific neutral input, or fixed
 benchmark case is also supported. A sample mean is convenient for a first

treeig-0.2.2/docs/building.md

@@ -0,0 +1,45 @@
+# Building the documentation
+
+The documentation uses Sphinx, MyST Markdown, and the PyData Sphinx Theme.
+NumPy-style API docstrings are rendered with Sphinx's Napoleon extension.
+No custom theme or frontend build is needed.
+
+From the repository root, using Python 3.11 or later:
+
+```bash
+python -m pip install -e ".[docs]"
+python -m sphinx -W --keep-going -b html docs docs/_build/html
+python scripts/check_docs_discovery.py
+```
+
+Open `docs/_build/html/index.html` in a browser. Documentation dependencies are
+optional and do not change TreeIG's runtime requirements. The documentation CI
+builds HTML with warnings treated as errors and saves it as a downloadable
+artifact. On pushes to `main` (or a manual run on `main`), it also publishes
+the HTML to [GitHub Pages](https://ludgerhentschel.github.io/treeig/).
+Pull requests build the documentation without deploying it.
+
+For initial setup, open the repository's **Settings → Pages** and select
+**GitHub Actions** as the build and deployment source. Then push the workflow
+or run **Documentation** manually from the Actions tab. A successful `deploy`
+job publishes the site. No package version change or release tag is required.
+
+Edit the topic pages under `docs/`; keep the README focused on installation,
+a first example, and links into the guide. Version information comes from
+`pyproject.toml`. Generated HTML should not be committed.
+
+## Discovery files
+
+Maintain the repository-root `llms.txt` as an annotated map to the published
+site. Sphinx copies this single source through `html_extra_path`. Link to
+rendered API pages so readers receive expanded signatures and docstrings,
+rather than the autodoc instructions in raw Sphinx sources.
+
+`sphinx-sitemap` generates `sitemap.xml` using `html_baseurl`, which also supplies
+canonical page URLs. Important pages define descriptions in `myst.html_meta`
+YAML front matter. Keep `docs/requirements.txt` and the `docs` extra synchronized.
+
+The discovery check runs after the HTML build in CI. It checks the index copy,
+local targets, sitemap URLs, canonical links, descriptions, and expanded API and
+example content. After deployment, check the public `/treeig/llms.txt` and
+`/treeig/sitemap.xml` endpoints and external links in the index.

{treeig-0.2.0 → treeig-0.2.2}/docs/concepts.md

@@ -1,7 +1,19 @@
+---
+myst:
+  html_meta:
+    description: "Understand TreeIG numerical conventions, path crossings, and completeness."
+---
+
 # Attribution and interpretation
 
 ## Why TreeIG?
 
+The method is developed in Ludger Hentschel's
+[**TreeIG: Exact Integrated Gradients for Tree-Based Models**](https://www.ludgerhentschel.com/PDFs/Hentschel%20'26g.pdf).
+It builds on Integrated Gradients introduced by Sundararajan, Taly, and Yan in
+[**Axiomatic Attribution for Deep Networks** (ICML 2017)](https://proceedings.mlr.press/v70/sundararajan17a.html).
+
+
 Standard Integrated Gradients defines feature contributions by integrating
 model gradients along a straight-line path from a baseline input to the
 observation. Tree models are piecewise constant, so ordinary gradients are
@@ -71,6 +83,12 @@ TreeIG follows each backend's split-routing convention as closely as possible.
 - XGBoost numeric splits route left when `x[j] < threshold`
   using float32-style comparisons.
 
+XGBoost completeness comparisons against native raw predictions can show small
+residuals (around `1e-7` in tested models), consistent with differences in floating-point
+precision and accumulation between the native predictor and the attribution
+calculation. This is not a universal error bound or a numerical integration
+resolution; compare residuals relative to the scale of the explained output.
+
 Inputs must be finite numeric arrays. Missing-value routing is not currently
 implemented, so `NaN` and `Inf` values raise errors.
 

{treeig-0.2.0 → treeig-0.2.2}/docs/conf.py

@@ -8,13 +8,22 @@ project = "TreeIG"
 author = "Ludger Hentschel"
 copyright = "2026, Ludger Hentschel"
 release = tomllib.loads((ROOT / "pyproject.toml").read_text())["project"]["version"]
-extensions = ["myst_parser", "sphinx.ext.autodoc", "sphinx.ext.napoleon", "sphinx.ext.mathjax"]
+extensions = ["myst_parser", "sphinx.ext.autodoc", "sphinx.ext.napoleon", "sphinx.ext.mathjax", "sphinx_sitemap"]
 myst_enable_extensions = ["dollarmath"]
 myst_heading_anchors = 3
 exclude_patterns = ["_build"]
 html_theme = "pydata_sphinx_theme"
 html_title = f"TreeIG {release}"
-html_theme_options = {"github_url": "https://github.com/LudgerHentschel/treeig", "show_prev_next": True}
+html_theme_options = {"github_url": "https://github.com/LudgerHentschel/treeig", "show_prev_next": True, "navbar_center": []}
 html_static_path = []
 napoleon_numpy_docstring = True
 napoleon_google_docstring = False
+
+templates_path = ["_templates"]
+html_sidebars = {"**": ["documentation-nav.html"]}
+
+html_baseurl = "https://ludgerhentschel.github.io/treeig/"
+# Publish the single maintained repository index with the documentation.
+html_extra_path = ["../llms.txt"]
+sitemap_url_scheme = "{link}"
+sitemap_excludes = ["search.html", "genindex.html", "py-modindex.html"]

{treeig-0.2.0 → treeig-0.2.2}/docs/examples.md

@@ -1,3 +1,9 @@
+---
+myst:
+  html_meta:
+    description: "Run complete TreeIG examples for XGBoost regression and LightGBM multiclass margins."
+---
+
 # Worked examples
 
 These examples use synthetic data so they can run without downloading datasets.

{treeig-0.2.0 → treeig-0.2.2}/docs/explanations.md

@@ -1,3 +1,9 @@
+---
+myst:
+  html_meta:
+    description: "Interpret TreeIG feature contributions, classification targets, result shapes, and completeness diagnostics."
+---
+
 # Reading and plotting results
 
 ## Explanation objects and SHAP plots
@@ -78,8 +84,10 @@ ig = tig.TreeIG(model, baseline=x0, target=2)
 phi_class_2 = ig.attribute(X_eval)
 ```
 
-Exact TreeIG attributes raw class margins. TreeIGNumeric can use the explicit
-probability-derived score convention above when no native margin exists.
+Exact TreeIG attributes raw class margins. When no native margin exists,
+TreeIGNumeric defaults to binary log odds or centered multiclass log scores
+derived from probabilities. See [numerical classification conventions](numeric.md)
+for explicit floors at zero and the opt-in class-probability mode.
 
 ## Functional interface
 

{treeig-0.2.0 → treeig-0.2.2}/docs/getting-started.md

@@ -1,3 +1,9 @@
+---
+myst:
+  html_meta:
+    description: "Install TreeIG and run a complete regression example with fitted tree models, baseline inputs, and completeness checks."
+---
+
 # Getting started
 
 ## Installation

treeig-0.2.2/docs/gpu-benchmarks.md

@@ -0,0 +1,10 @@
+# CUDA benchmark notes
+
+These are the recorded experiments maintained in the repository's benchmark
+notes. See [GPUTreeIG](gpu.md) for installation and the summary comparisons.
+
+## Recorded experiments
+
+```{include} ../benchmarks/README.md
+:start-after: "## CUDA prediction attribution"
+```