bulanik 0.3.0__tar.gz

bulanik-0.3.0/.gitignore

@@ -0,0 +1,14 @@
+.venv/
+__pycache__/
+*.pyc
+.pytest_cache/
+.coverage
+htmlcov/
+dist/
+.superpowers/
+.hypothesis/
+*.egg-info/
+build/
+/site/
+/.cache/
+/benchmarks/.cache/

bulanik-0.3.0/CHANGELOG.md

@@ -0,0 +1,127 @@
+# Changelog
+
+All notable changes to bulanik are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project follows
+[Semantic Versioning](https://semver.org/).
+
+## [0.3.0] - 2026-11-05
+
+Interval-valued AHP and fuzzy versions of three more ranking methods. The public v0.2 API is unchanged apart from
+the two changes listed below.
+
+### Added
+
+- `ahp_interval_valued`: AHP over interval-valued orthopair comparison matrices, with the
+  `multiplicative` and `possibility` methods.
+- `fuzzy_codas`, `fuzzy_waspas` (with `combine="fuzzy"` or `combine="scores"`) and
+  `fuzzy_cocoso`, also reachable through `rank_fuzzy(method=...)`.
+- An `IVQROFN` score named `"defuzzified"` (q = 1).
+- Examples 23 and 24 (24 executed examples in all).
+
+### Changed
+
+- Crisp `codas` accepts zeros in benefit columns.
+- `ANFIS.fit` results differ from v0.2: `lr` is now the largest step tried, and hybrid training
+  solves the consequents once more per `fit`, so `history` values change.
+
+### Fixed
+
+- Crisp `cocoso` treats rounding-size gaps at a column extreme as zero.
+- `ANFIS.fit` kept gradient steps that raised the training error and could return a model far worse
+  than least squares alone, with no warning. A step that raises the error is now halved or dropped,
+  and hybrid training ends on solved consequents.
+
+[0.3.0]: https://github.com/tdelphi1981/bulanik/releases/tag/v0.3.0
+
+## [0.2.0] - 2026-11-04
+
+Interval-valued and interval type-2 numbers, six new ranking methods, new weighting
+methods, DEMATEL and three new figures. The public v0.1 API is unchanged: this release
+only adds names.
+
+### Added
+
+- Interval-valued numbers: `IVQROFN` (interval-valued q-rung orthopair) with the aliases
+  `IVIFN` (q = 1), `IVPFN` (q = 2) and `IVFFN` (q = 3), and `IVNeutrosophicFN` (interval
+  neutrosophic). Frozen and validated, with the algebraic and Einstein operator families,
+  scores, accuracies and distances. The aliases are separate classes: they neither compare
+  equal to nor mix with an `IVQROFN` of the same rung.
+- `IT2TrFN`: interval type-2 trapezoidal fuzzy numbers (upper and lower trapezoid with
+  heights, lower nested inside upper), with the arithmetic of Chen and Lee (2010a) and the
+  DTraT score of Kahraman et al. (2014).
+- Ranking methods: CODAS, COPRAS, MARCOS, CoCoSo, WISP and ELECTRE I (with net concordance
+  and discordance indices for a complete ranking), all registered in
+  `rank_fuzzy(method=...)`. Zero, negative and constant columns, and signed default
+  scores, raise a `ValueError` naming the method where the method cannot handle them
+  (constant columns are neutral in CoCoSo, CRITIC and COPRAS; ELECTRE and CoCoSo accept zeros
+  and negatives); a magnitude spread so large that a scaled entry underflows to 0 raises the
+  same way in CODAS, MARCOS and WISP.
+- Weighting methods: CRITIC (objective), PIPRECIA (crisp and `TFN` judgements, with an
+  optional inverse pass) and `ahp_fuzzy_numbers` (AHP over a comparison matrix of any one
+  fuzzy number kind). PIPRECIA requires every judgement `s_j` to lie in (0, 2) and names the
+  offending index otherwise.
+- DEMATEL: `dematel` for crisp or fuzzy direct-relation matrices, `cfcs` (Opricovic and
+  Tzeng 2003) to convert triangular matrices from several experts, and `DEMATELResult` with
+  `as_weights()` so the factor weights feed every ranking method. A singular or
+  ill-conditioned $I - N$ (spectral radius numerically 1) raises instead of returning a huge
+  total relation.
+- `bulanik.plot`: `dematel` (cause-effect diagram), `iv_orthopair` (interval rectangles over
+  the feasible region) and `it2_number` (upper and lower trapezoids with the footprint of
+  uncertainty).
+- Documentation: guide pages for interval-valued numbers, interval type-2 numbers, the new
+  ranking and weighting methods and DEMATEL; new gallery figures; API reference for all new
+  names; examples 18 to 22 (22 executed examples in all); the reference list extended to
+  every source cited in the v0.2 docstrings, each DOI checked against Crossref.
+
+### Changed
+
+- The dark categorical plot palette, slot 6 (green), is `#2ea32e` instead of `#008300`,
+  which was too dark on the slate surface. Figures that use the sixth colour change in dark
+  mode only.
+
+### Notes on sourcing
+
+- The 7-term interval type-2 linguistic scale in example 19 and in the gallery is
+  illustrative: it follows the style of the type-2 literature, and its values are not a
+  transcription of any published table.
+- The CRITIC tests are checked against values derived by hand from the published formulas,
+  not against a worked example printed in the paper.
+- The DEMATEL tests include a cross-check against the vignette of the R package `dematel`.
+
+[0.2.0]: https://github.com/tdelphi1981/bulanik/releases/tag/v0.2.0
+
+## [0.1.0] - 2026-11-03
+
+First release.
+
+### Added
+
+- Fuzzy numbers: triangular (`TFN`) and trapezoidal (`TrFN`); intuitionistic (`IFN`),
+  Pythagorean (`PFN`), Fermatean (`FFN`) and q-rung orthopair (`QROFN`); spherical
+  (`SphericalFN`), picture (`PictureFN`) and single-valued neutrosophic
+  (`NeutrosophicFN`). Immutable, validated on construction, with named operator
+  families (`algebraic`, `einstein`), scores, accuracies and distances.
+- Aggregation: weighted average and weighted geometric mean, and expert aggregation of
+  `[expert][alternative][criterion]` ratings.
+- Fuzzy sets: membership functions (triangular, trapezoidal, gaussian, bell, sigmoid,
+  linear ramps), linguistic variables, t-norms and t-conorms by name, and linguistic
+  scales (`SAATY_TFN`, `FUZZY_BWM_TFN` and illustrative IF/TFN scales).
+- Fuzzy inference: Mamdani, Sugeno (zero and first order) and Tsukamoto systems from
+  plain-text rules, with `explain` and a no-rule-fired policy.
+- Interval type-2 inference: interval type-2 membership functions and Mamdani and
+  Sugeno systems, with KM, EKM, Nie-Tan and BMM type reduction.
+- ANFIS: grid-partition first-order Sugeno ANFIS with hybrid (Jang) or gradient
+  training, exported to a Sugeno system.
+- MCDM: AHP, fuzzy AHP (Buckley), SWARA and entropy weights; best-worst consistency
+  indices (crisp and fuzzy); TOPSIS, VIKOR, WASPAS and EDAS on crisp matrices;
+  `DecisionMatrix` and `rank_fuzzy` for fuzzy-number matrices; Chen's fuzzy TOPSIS.
+- `bulanik.lumix` (extra `lumix`): linear best-worst method, Zimmermann fuzzy
+  programming and MCDM scores as LumiX data.
+- `bulanik.sezgi` (extra `sezgi`): nonlinear and fuzzy best-worst method and ANFIS
+  training with sezgi metaheuristics.
+- `bulanik.plot` (extra `plot`): figures for numbers, scales, inference, type-2 sets and
+  MCDM results in matching light and dark themes.
+- Documentation site (MkDocs Material) with a user guide, API reference, 17 executed
+  examples and a verified reference list; 17 runnable scripts in `examples/`.
+
+[0.1.0]: https://github.com/tdelphi1981/bulanik/releases/tag/v0.1.0

bulanik-0.3.0/CITATION.cff

@@ -0,0 +1,29 @@
+cff-version: 1.2.0
+message: >-
+  If you use bulanik in your research, please cite it using the metadata
+  below.
+type: software
+title: bulanik
+version: 0.3.0
+date-released: "2026-11-05"
+abstract: >-
+  Easy-to-use fuzzy numbers, fuzzy inference and fuzzy multi-criteria
+  decision making in pure Python, with optional bridges to LumiX and sezgi
+  and publication-quality figures.
+authors:
+  - family-names: Berber
+    given-names: Tolga
+    email: tolga.berber@fen.ktu.edu.tr
+    orcid: "https://orcid.org/0000-0002-6487-5581"
+    affiliation: "Department of Computer Science, Karadeniz Technical University"
+license: MIT
+repository-code: "https://github.com/tdelphi1981/bulanik"
+url: "https://tdelphi1981.github.io/bulanik/"
+keywords:
+  - fuzzy-logic
+  - fuzzy-inference
+  - fuzzy-numbers
+  - mcdm
+  - anfis
+  - optimization
+  - python

bulanik-0.3.0/CONTRIBUTING.md

@@ -0,0 +1,51 @@
+# Contributing to bulanik
+
+## Development setup
+
+```bash
+git clone https://github.com/tdelphi1981/bulanik
+cd bulanik
+uv sync            # dev group: pytest, hypothesis, coverage, matplotlib, lumix-opt, ortools, sezgi
+```
+
+## Tests
+
+```bash
+uv run python -m pytest -q
+```
+
+The suite runs every script in `examples/`. Coverage is measured only when you ask for
+it, and then it must stay at or above 95% (`fail_under` in `pyproject.toml`):
+
+```bash
+uv run python -m pytest -q --cov=bulanik
+```
+
+Do not run pytest with `-W error`: OR-Tools' SWIG bindings emit warnings that
+turn into crashes. Property tests use Hypothesis.
+
+## Documentation
+
+The site is MkDocs Material, sources in `docs/site/`, configuration in `mkdocs.yml`.
+
+```bash
+uv sync --group docs
+uv run mkdocs serve                # live preview
+uv run mkdocs build --strict       # must finish with zero warnings
+```
+
+`tests/test_docs.py` runs the strict build only when the docs group is installed
+(`uv sync --group docs`); without it the test is skipped. Deselect it with
+`-m "not docs"`. Building the site needs **Python 3.11 or newer** (the docs group pins a
+matplotlib release without Python 3.10 wheels) and **network access** (the privacy plugin
+downloads external assets such as the MathJax script). Python snippets in the docs are executed at
+build time with markdown-exec, so the output shown is real.
+
+## Style
+
+- Python 3.10+, type hints on public API, no runtime dependencies in the core.
+- Numbers and sets are immutable; invalid input raises a specific error, never returns silently.
+- Docstrings use Google style (`Args:`, `Returns:`, `Raises:`, `Examples:`).
+- Cited works need a verified reference: add them to `docs/site/about/references.md` with a
+  DOI that resolves (check it against Crossref or the publisher), never from memory.
+- Keep commits focused; do not change library behaviour in documentation commits.

bulanik-0.3.0/LICENSE

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

bulanik-0.3.0/PKG-INFO

@@ -0,0 +1,113 @@
+Metadata-Version: 2.5
+Name: bulanik
+Version: 0.3.0
+Summary: Easy-to-use fuzzy numbers, fuzzy inference and fuzzy MCDM, with LumiX and sezgi bridges
+Project-URL: Homepage, https://github.com/tdelphi1981/bulanik
+Project-URL: Documentation, https://tdelphi1981.github.io/bulanik/
+Project-URL: Repository, https://github.com/tdelphi1981/bulanik
+Project-URL: Issues, https://github.com/tdelphi1981/bulanik/issues
+Project-URL: Changelog, https://github.com/tdelphi1981/bulanik/blob/main/CHANGELOG.md
+Author-email: Tolga Berber <tolga.berber@fen.ktu.edu.tr>
+License: MIT
+License-File: LICENSE
+Keywords: fuzzy,fuzzy-inference,fuzzy-logic,mcdm,optimization
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+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 :: Mathematics
+Requires-Python: >=3.10
+Provides-Extra: lumix
+Requires-Dist: lumix-opt>=0.3.2; extra == 'lumix'
+Requires-Dist: ortools>=9.8; extra == 'lumix'
+Provides-Extra: plot
+Requires-Dist: matplotlib>=3.8; extra == 'plot'
+Provides-Extra: sezgi
+Requires-Dist: sezgi>=0.1.6; extra == 'sezgi'
+Description-Content-Type: text/markdown
+
+# bulanik
+
+Easy-to-use fuzzy numbers, fuzzy inference and fuzzy multi-criteria decision making
+(MCDM) in pure Python, with no runtime dependencies. *Bulanık* is Turkish for *fuzzy*.
+Optional bridges connect it to [LumiX](https://pypi.org/project/lumix-opt/) (optimization
+modelling) and [sezgi](https://github.com/tdelphi1981/sezgi) (metaheuristics), and an
+optional plotting module draws the results in a light and a dark theme.
+
+**Documentation:** <https://tdelphi1981.github.io/bulanik/>
+
+## Install
+
+```bash
+pip install bulanik                      # core, no runtime dependencies
+pip install "bulanik[lumix]"             # + the LumiX bridge (bulanik.lumix)
+pip install "bulanik[sezgi]"             # + the sezgi bridge (bulanik.sezgi)
+pip install "bulanik[plot]"              # + figures (bulanik.plot, needs matplotlib)
+pip install "bulanik[lumix,sezgi,plot]"  # everything
+```
+
+Python 3.10 to 3.13. For development, clone the repository and run `uv sync` (see
+[Contributing](https://github.com/tdelphi1981/bulanik/blob/main/CONTRIBUTING.md)).
+
+## Quickstart
+
+```python
+from bulanik import IFN, TFN
+from bulanik.aggregate import wa
+
+a, b = IFN(0.6, 0.3), IFN(0.5, 0.4)
+print(a + b)                          # IFN(mu=0.8, nu=0.12)
+print(a.add(b, ops="einstein"))       # the Einstein operator family
+print(wa([a, b], [0.7, 0.3]))         # weighted average
+print((TFN(1, 2, 3) + TFN(3, 4, 5)).score())   # crisp score for ranking
+```
+
+Every operator family, score and method is chosen by name (`ops="einstein"`,
+`score("normalized")`); an unknown name raises a `ValueError` that lists the valid ones.
+
+## What is in it
+
+- **Fuzzy numbers:** triangular and trapezoidal; intuitionistic, Pythagorean, Fermatean
+  and q-rung orthopair; spherical, picture and neutrosophic; their interval-valued
+  versions (`IVIFN`, `IVPFN`, `IVFFN`, `IVQROFN`, `IVNeutrosophicFN`) and interval type-2
+  trapezoidal numbers (`IT2TrFN`). Immutable and validated.
+- **Aggregation, sets and scales:** weighted average and geometric mean, expert
+  aggregation, membership functions, linguistic variables and linguistic scales.
+- **Fuzzy inference:** Mamdani, Sugeno and Tsukamoto systems from plain-text rules;
+  interval type-2 systems with KM, EKM, Nie-Tan and BMM type reduction; ANFIS.
+- **Decision making:** AHP, fuzzy AHP (also over any number kind), SWARA, entropy, CRITIC
+  and PIPRECIA weights; DEMATEL with CFCS; best-worst consistency; TOPSIS, VIKOR, WASPAS,
+  EDAS, CODAS, COPRAS, MARCOS, CoCoSo, WISP and ELECTRE, on crisp matrices or fuzzy
+  ratings (fuzzy CODAS, WASPAS and CoCoSo included), and Chen's fuzzy TOPSIS. Interval-valued
+  AHP (`ahp_interval_valued`) with the multiplicative and possibility methods.
+- **Bridges:** with LumiX, the linear best-worst method, Zimmermann fuzzy programming and
+  MCDM scores as optimization data; with sezgi, nonlinear and fuzzy BWM and ANFIS training.
+- **Figures:** `bulanik.plot` for numbers, scales, inference, rankings and DEMATEL.
+
+The [documentation](https://tdelphi1981.github.io/bulanik/) has a user guide, an API
+reference, and 24 runnable examples (also in [`examples/`](https://github.com/tdelphi1981/bulanik/tree/main/examples)).
+
+## Development
+
+```bash
+uv sync
+uv run python -m pytest -q
+```
+
+The dev group installs LumiX, OR-Tools, sezgi and matplotlib, so the bridge tests and
+every example run; without an extra, its tests and examples are skipped. Coverage is
+measured on the pure-Python core.
+
+## Citing
+
+Please cite bulanik using [`CITATION.cff`](https://github.com/tdelphi1981/bulanik/blob/main/CITATION.cff) (GitHub's "Cite this repository"),
+and the original papers behind the methods you use, listed with DOIs in the
+[references](https://tdelphi1981.github.io/bulanik/about/references.html).
+
+## License
+
+MIT. See [LICENSE](https://github.com/tdelphi1981/bulanik/blob/main/LICENSE).

bulanik-0.3.0/README.md

@@ -0,0 +1,81 @@
+# bulanik
+
+Easy-to-use fuzzy numbers, fuzzy inference and fuzzy multi-criteria decision making
+(MCDM) in pure Python, with no runtime dependencies. *Bulanık* is Turkish for *fuzzy*.
+Optional bridges connect it to [LumiX](https://pypi.org/project/lumix-opt/) (optimization
+modelling) and [sezgi](https://github.com/tdelphi1981/sezgi) (metaheuristics), and an
+optional plotting module draws the results in a light and a dark theme.
+
+**Documentation:** <https://tdelphi1981.github.io/bulanik/>
+
+## Install
+
+```bash
+pip install bulanik                      # core, no runtime dependencies
+pip install "bulanik[lumix]"             # + the LumiX bridge (bulanik.lumix)
+pip install "bulanik[sezgi]"             # + the sezgi bridge (bulanik.sezgi)
+pip install "bulanik[plot]"              # + figures (bulanik.plot, needs matplotlib)
+pip install "bulanik[lumix,sezgi,plot]"  # everything
+```
+
+Python 3.10 to 3.13. For development, clone the repository and run `uv sync` (see
+[Contributing](https://github.com/tdelphi1981/bulanik/blob/main/CONTRIBUTING.md)).
+
+## Quickstart
+
+```python
+from bulanik import IFN, TFN
+from bulanik.aggregate import wa
+
+a, b = IFN(0.6, 0.3), IFN(0.5, 0.4)
+print(a + b)                          # IFN(mu=0.8, nu=0.12)
+print(a.add(b, ops="einstein"))       # the Einstein operator family
+print(wa([a, b], [0.7, 0.3]))         # weighted average
+print((TFN(1, 2, 3) + TFN(3, 4, 5)).score())   # crisp score for ranking
+```
+
+Every operator family, score and method is chosen by name (`ops="einstein"`,
+`score("normalized")`); an unknown name raises a `ValueError` that lists the valid ones.
+
+## What is in it
+
+- **Fuzzy numbers:** triangular and trapezoidal; intuitionistic, Pythagorean, Fermatean
+  and q-rung orthopair; spherical, picture and neutrosophic; their interval-valued
+  versions (`IVIFN`, `IVPFN`, `IVFFN`, `IVQROFN`, `IVNeutrosophicFN`) and interval type-2
+  trapezoidal numbers (`IT2TrFN`). Immutable and validated.
+- **Aggregation, sets and scales:** weighted average and geometric mean, expert
+  aggregation, membership functions, linguistic variables and linguistic scales.
+- **Fuzzy inference:** Mamdani, Sugeno and Tsukamoto systems from plain-text rules;
+  interval type-2 systems with KM, EKM, Nie-Tan and BMM type reduction; ANFIS.
+- **Decision making:** AHP, fuzzy AHP (also over any number kind), SWARA, entropy, CRITIC
+  and PIPRECIA weights; DEMATEL with CFCS; best-worst consistency; TOPSIS, VIKOR, WASPAS,
+  EDAS, CODAS, COPRAS, MARCOS, CoCoSo, WISP and ELECTRE, on crisp matrices or fuzzy
+  ratings (fuzzy CODAS, WASPAS and CoCoSo included), and Chen's fuzzy TOPSIS. Interval-valued
+  AHP (`ahp_interval_valued`) with the multiplicative and possibility methods.
+- **Bridges:** with LumiX, the linear best-worst method, Zimmermann fuzzy programming and
+  MCDM scores as optimization data; with sezgi, nonlinear and fuzzy BWM and ANFIS training.
+- **Figures:** `bulanik.plot` for numbers, scales, inference, rankings and DEMATEL.
+
+The [documentation](https://tdelphi1981.github.io/bulanik/) has a user guide, an API
+reference, and 24 runnable examples (also in [`examples/`](https://github.com/tdelphi1981/bulanik/tree/main/examples)).
+
+## Development
+
+```bash
+uv sync
+uv run python -m pytest -q
+```
+
+The dev group installs LumiX, OR-Tools, sezgi and matplotlib, so the bridge tests and
+every example run; without an extra, its tests and examples are skipped. Coverage is
+measured on the pure-Python core.
+
+## Citing
+
+Please cite bulanik using [`CITATION.cff`](https://github.com/tdelphi1981/bulanik/blob/main/CITATION.cff) (GitHub's "Cite this repository"),
+and the original papers behind the methods you use, listed with DOIs in the
+[references](https://tdelphi1981.github.io/bulanik/about/references.html).
+
+## License
+
+MIT. See [LICENSE](https://github.com/tdelphi1981/bulanik/blob/main/LICENSE).

bulanik-0.3.0/conftest.py

@@ -0,0 +1,32 @@
+"""Root pytest configuration: doctest collection over ``src/bulanik``.
+
+``bulanik.lumix`` and ``bulanik.sezgi`` import optional extras at module level,
+so collecting their doctests would fail without the extra. Skip a bridge module
+when its dependencies are not importable; likewise ``bulanik.plot`` without
+matplotlib. With matplotlib, doctests and tests draw on the non-interactive
+Agg backend and every figure is closed after each test.
+"""
+
+import importlib.util
+
+import pytest
+
+collect_ignore = []
+
+if any(importlib.util.find_spec(m) is None for m in ("lumix", "ortools")):
+    collect_ignore.append("src/bulanik/lumix.py")
+if importlib.util.find_spec("sezgi") is None:
+    collect_ignore.append("src/bulanik/sezgi.py")
+if importlib.util.find_spec("matplotlib") is None:
+    collect_ignore.append("src/bulanik/plot")
+else:
+    import matplotlib
+
+    matplotlib.use("Agg")
+
+    @pytest.fixture(autouse=True)
+    def _close_matplotlib_figures():
+        yield
+        import matplotlib.pyplot as plt
+
+        plt.close("all")

bulanik-0.3.0/docs/scripts/_figutil.py

@@ -0,0 +1,177 @@
+"""Shared plumbing for the docs figure scripts.
+
+All plotting goes through `bulanik.plot`; this module only
+
+- renders a figure in both house themes and saves `<name>-light.svg` and
+  `<name>-dark.svg` into `docs/site/assets/figures/` with deterministic output
+  (fixed SVG id salt, no creation date), and
+- offers page-level layout helpers: multi-panel figures and annotations
+  (notes, brackets, arrows, markers) drawn with the active theme's tokens from
+  `bulanik.plot.current_theme()`.
+
+A figure is a function `draw() -> Figure | Axes` that runs inside the theme.
+"""
+
+from __future__ import annotations
+
+import io
+import os
+import re
+import sys
+from collections.abc import Callable, Mapping
+from pathlib import Path
+from typing import Any
+
+os.environ.setdefault("MPLBACKEND", "Agg")
+
+import matplotlib as mpl  # noqa: E402
+import matplotlib.pyplot as plt  # noqa: E402
+from matplotlib import patheffects  # noqa: E402
+from matplotlib.axes import Axes  # noqa: E402
+from matplotlib.figure import Figure  # noqa: E402
+
+from bulanik import plot  # noqa: E402
+
+FIGURES = Path(__file__).resolve().parents[1] / "site" / "assets" / "figures"
+THEMES = ("light", "dark")
+Draw = Callable[[], "Figure | Axes"]
+
+
+def tokens() -> Mapping[str, Any]:
+    """The active theme's tokens (`bulanik.plot.current_theme()`)."""
+    return plot.current_theme()
+
+
+def render(name: str, draw: Draw, out: Path = FIGURES) -> list[Path]:
+    """Draw the figure once per theme and save `<name>-<theme>.svg`."""
+    out.mkdir(parents=True, exist_ok=True)
+    paths = []
+    for mode in THEMES:
+        with plot.theme(mode), mpl.rc_context({"svg.hashsalt": f"bulanik-{name}"}):
+            res = draw()
+            fig = res.figure if isinstance(res, Axes) else res
+            path = out / f"{name}-{mode}.svg"
+            buffer = io.StringIO()
+            fig.savefig(buffer, format="svg", metadata={"Date": None, "Creator": "bulanik docs"})
+            plt.close(fig)
+            path.write_text(compact(buffer.getvalue()), encoding="utf-8")
+        paths.append(path)
+    return paths
+
+
+_DECIMALS = re.compile(r"(\d\.\d{2})\d+")
+_PATH_DATA = re.compile(r' d="[^"]*"')  # only path geometry; transforms keep full precision
+
+
+def compact(svg: str) -> str:
+    """Round path coordinates to 0.01 pt: invisible at any zoom, and the files shrink by ~40%.
+
+    Haloed labels are written as outline paths (not glyph references), so the
+    coordinate text dominates the file size.
+    """
+    return _PATH_DATA.sub(lambda m: _DECIMALS.sub(r"\1", m.group(0)), svg)
+
+
+def the_text(ax: Axes, *, startswith: str | None = None, equals: str | None = None):
+    """The one text of `ax` that matches; fail loudly on zero or several matches."""
+    found = [
+        t
+        for t in ax.texts
+        if (t.get_text().startswith(startswith) if startswith is not None else t.get_text() == equals)
+    ]
+    if len(found) != 1:
+        raise AssertionError(f"expected exactly one text matching {startswith or equals!r}, found {len(found)}")
+    return found[0]
+
+
+def run(figures: Mapping[str, Draw], argv: list[str] | None = None) -> None:
+    """Command-line entry: render all figures, or only the names given."""
+    names = (argv if argv is not None else sys.argv[1:]) or list(figures)
+    for name in names:
+        for path in render(name, figures[name]):
+            print(path.relative_to(Path.cwd()) if path.is_relative_to(Path.cwd()) else path)
+
+
+# -- layout ---------------------------------------------------------------------------
+
+
+def panels(nrows: int, ncols: int, *, figsize: tuple[float, float], **kw: Any) -> tuple[Figure, Any]:
+    """A constrained-layout figure with a grid of axes, in the active theme."""
+    fig, axes = plt.subplots(nrows, ncols, figsize=figsize, layout="constrained", **kw)
+    return fig, axes
+
+
+def halo(width: float = 3.0) -> list[Any]:
+    """Surface-coloured outline so lines never cut through a label."""
+    return [patheffects.withStroke(linewidth=width, foreground=tokens()["surface"], alpha=0.9)]
+
+
+def note(ax: Axes, x: float, y: float, text: str, *, ink: str = "text_secondary", size: float = 8.5, **kw: Any) -> Any:
+    """Annotation text in a text token (never a series colour), with a halo."""
+    kw.setdefault("ha", "center")
+    kw.setdefault("va", "bottom")
+    kw.setdefault("zorder", 9)
+    return ax.text(x, y, text, color=tokens()[ink], fontsize=size, path_effects=halo(), **kw)
+
+
+def bracket(ax: Axes, x0: float, x1: float, y: float, text: str, *, tick: float = 0.035, below: bool = False) -> None:
+    """A hairline bracket over [x0, x1] at height y with a centred label."""
+    t = tokens()
+    s = -1 if below else 1
+    ax.plot([x0, x0, x1, x1], [y - s * tick, y, y, y - s * tick], color=t["muted"], lw=0.8,
+            solid_joinstyle="miter", zorder=7, clip_on=False)
+    note(ax, (x0 + x1) / 2, y + s * 0.02, text, va="top" if below else "bottom", ink="text_secondary")
+
+
+def arrow(ax: Axes, start: tuple[float, float], end: tuple[float, float], color: str, *,
+          lw: float = 1.2, shrink: float = 6.0, alpha: float = 1.0, rad: float = 0.0,
+          shrink_end: float | None = None) -> None:
+    """A thin arrow in a series colour (a mark, so it may carry the hue).
+
+    `shrink_end` (points) stops the head short of the target marker; it defaults to `shrink`.
+    """
+    ax.annotate(
+        "", xy=end, xytext=start, zorder=6,
+        arrowprops=dict(arrowstyle="-|>,head_length=0.45,head_width=0.22", color=color, lw=lw,
+                        shrinkA=shrink, shrinkB=shrink if shrink_end is None else shrink_end, alpha=alpha,
+                        connectionstyle=f"arc3,rad={rad}"),
+    )
+
+
+def dot(ax: Axes, x: float, y: float, color: str, *, size: float = 8.0, marker: str = "o", zorder: float = 8) -> None:
+    """A marker with the house 2 px surface ring."""
+    ax.plot([x], [y], marker=marker, ms=size, mfc=color, mec=tokens()["surface"], mew=1.6,
+            linestyle="none", zorder=zorder, clip_on=False)
+
+
+def key(ax: Axes, items: list[tuple[str, str, str]], *, loc: str = "upper right", **kw: Any) -> Any:
+    """A compact legend: (marker, colour, text) per entry, text in ink tokens."""
+    from matplotlib.lines import Line2D
+
+    t = tokens()
+    handles = [
+        Line2D([], [], marker=m, linestyle="none", ms=7, mfc=c, mec=t["surface"], mew=1.4, label=s)
+        if m else Line2D([], [], color=c, lw=1.8, label=s)
+        for m, c, s in items
+    ]
+    kw.setdefault("fontsize", 8.5)
+    leg = ax.legend(handles=handles, loc=loc, frameon=False, labelcolor=t["text_secondary"],
+                    handletextpad=0.4, borderaxespad=0.3, **kw)
+    leg.set_zorder(10)
+    return leg
+
+
+def label(ax: Axes, x: float, y: float, text: str, *, dx: float = 7, dy: float = 0, ha: str = "left",
+          va: str = "center", size: float = 8.5, ink: str = "text_secondary") -> Any:
+    """Point label offset by (dx, dy) points, in a text token with a halo."""
+    return ax.annotate(text, (x, y), xytext=(dx, dy), textcoords="offset points", ha=ha, va=va,
+                       fontsize=size, color=tokens()[ink], path_effects=halo(), zorder=9)
+
+
+def callout(ax: Axes, xy: tuple[float, float], at: tuple[float, float], text: str, *, ha: str = "left",
+            va: str = "center", size: float = 8.5, ink: str = "text_secondary") -> Any:
+    """A label placed at data point `at`, tied to `xy` by a hairline leader."""
+    t = tokens()
+    return ax.annotate(text, xy, xytext=at, textcoords="data", ha=ha, va=va, fontsize=size, color=t[ink],
+                       path_effects=halo(), zorder=9,
+                       arrowprops=dict(arrowstyle="-", color=t["muted"], lw=0.6, shrinkA=3, shrinkB=6))