exege-core 0.6.0__tar.gz

exege_core-0.6.0/.gitignore

@@ -0,0 +1,26 @@
+# the site directory
+site
+
+# any cache
+.cache
+
+# python
+.venv/
+__pycache__/
+*.py[cod]
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+
+# throwaway output: toy archives, fitted bases, whatever is made while trying things
+scratch/
+
+# lock files and tool environments: nothing is pinned here, and CI resolves from
+# pyproject.toml, so a lock is one machine's answer and not the repo's
+uv.lock
+pixi.lock
+.pixi/
+poetry.lock
+pdm.lock
+Pipfile.lock
+conda-lock.yml

exege_core-0.6.0/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, E3SM AI Group
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

exege_core-0.6.0/NOTICE

@@ -0,0 +1,40 @@
+exege
+====
+
+This product is licensed under the BSD 3-Clause License; see LICENSE.
+
+Third-party notices
+-------------------
+
+exege.latents, exege.figures and exege.app grew out of the latent space
+visualiser for weather models,
+
+    https://github.com/ktempestuous/latent_space_visualiser_weather_models
+    Tempest, Beylich & Craig (2026), doi:10.1007/978-3-032-29915-4_10
+
+whose region selection, channel ranking, cosine-similarity and PCA views they
+reimplement, and whose SamudrACE exporter defines the latent-archive layout that
+exege.adapters.latent_archive reads. That work is distributed under the MIT
+License, reproduced here as it requires:
+
+    MIT License
+
+    Copyright (c) 2026 Kirsten
+
+    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.

exege_core-0.6.0/PKG-INFO

@@ -0,0 +1,120 @@
+Metadata-Version: 2.5
+Name: exege-core
+Version: 0.6.0
+Summary: Tools for understanding and evaluating scientific machine-learning models: the code, and only Click. `exege` is the full install.
+Project-URL: Homepage, https://mahf708.github.io/exege
+Project-URL: Documentation, https://mahf708.github.io/exege/
+Project-URL: Source, https://github.com/mahf708/exege
+Project-URL: Issues, https://github.com/mahf708/exege/issues
+Author: E3SM AI Group
+License-Expression: BSD-3-Clause
+License-File: LICENSE
+License-File: NOTICE
+Keywords: climate,e3sm,emulator,interpretability,machine-learning
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
+Requires-Python: >=3.11
+Requires-Dist: click>=8.1
+Provides-Extra: app
+Requires-Dist: cartopy>=0.23; extra == 'app'
+Requires-Dist: matplotlib>=3.7; extra == 'app'
+Requires-Dist: netcdf4>=1.6; extra == 'app'
+Requires-Dist: numpy>=1.24; extra == 'app'
+Requires-Dist: streamlit>=1.50; extra == 'app'
+Requires-Dist: xarray>=2023.1; extra == 'app'
+Provides-Extra: figures
+Requires-Dist: cartopy>=0.23; extra == 'figures'
+Requires-Dist: matplotlib>=3.7; extra == 'figures'
+Requires-Dist: netcdf4>=1.6; extra == 'figures'
+Requires-Dist: numpy>=1.24; extra == 'figures'
+Requires-Dist: xarray>=2023.1; extra == 'figures'
+Provides-Extra: hf
+Requires-Dist: huggingface-hub>=0.23; extra == 'hf'
+Requires-Dist: netcdf4>=1.6; extra == 'hf'
+Requires-Dist: numpy>=1.24; extra == 'hf'
+Requires-Dist: xarray>=2023.1; extra == 'hf'
+Provides-Extra: latents
+Requires-Dist: netcdf4>=1.6; extra == 'latents'
+Requires-Dist: numpy>=1.24; extra == 'latents'
+Requires-Dist: xarray>=2023.1; extra == 'latents'
+Provides-Extra: nn
+Requires-Dist: netcdf4>=1.6; extra == 'nn'
+Requires-Dist: numpy>=1.24; extra == 'nn'
+Requires-Dist: torch>=2.0; extra == 'nn'
+Requires-Dist: xarray>=2023.1; extra == 'nn'
+Description-Content-Type: text/markdown
+
+# exege
+
+Tools for understanding and evaluating scientific machine-learning models: what an
+emulator holds inside, sparse autoencoders trained on it, figures, and a local app over
+them. The name comes from the Greek stem *exēgē-*, associated with explanation and
+interpretation.
+
+> **Research tool.** `exege` is early. What is described here works; expect it to change.
+
+## Install
+
+This is the light install: the code, and only Click. Anything heavier sits behind an
+extra named after the subpackage that needs it:
+
+```console
+$ uv pip install 'exege-core[latents]'     # or: pip install 'exege-core[latents]'
+```
+
+For everything at once, install [exege](https://pypi.org/project/exege/) instead: it is
+this with every extra but `nn` (`pip install exege`, or `'exege[nn]'` to add torch). Both
+provide the same `import exege` and the same `exege` command.
+
+| Extra | Pulls | Gets you |
+| --- | --- | --- |
+| `latents` | numpy, xarray, netCDF4 | `exege.latents`: latent diagnostics on a grid |
+| `figures` | matplotlib, cartopy | `exege.figures`: maps and series figures (brings `latents`) |
+| `app` | streamlit | `exege app`: a local web app (brings `figures`) |
+| `nn` | torch | `exege.nn` and `exege nn`: sparse autoencoders (brings `latents`) |
+| `hf` | huggingface_hub | archives read from a Hugging Face repository, `hf://datasets/...` (brings `latents`) |
+
+A missing extra says so, with the command that fits how `exege` was installed.
+
+## Try it, with no model and no data
+
+A toy emulator writes a latent archive with nothing but numpy; everything else reads it
+like any other:
+
+```console
+$ exege latents toy scratch/toy/control
+$ exege latents info scratch/toy/control --mask-variable sst
+$ exege latents region scratch/toy/control --lat 10 --lon -114 --time 2 --centered --pcs 2
+$ exege latents fields scratch/toy/control --field precipitation --top 3
+$ exege nn sae scratch/toy/control --features 64 --k 4 --out scratch/toy/sae.npz   # needs exege-core[nn]
+$ exege app --latents scratch/toy                                                  # needs exege-core[app]
+```
+
+The CLI is a thin client of the Python API; anything it can do, a notebook can:
+
+```python
+from exege.latents import Region, analyze_region, open_source
+
+source = open_source("scratch/toy/control", mask_variable="sst")
+result = analyze_region(
+    source, time=2, layer=3, region=Region(lat=10, lon=-114, radius_km=1500), centered=True
+)
+result.ranking.channels  # the channels that respond most strongly there
+```
+
+## More
+
+- Documentation: <https://mahf708.github.io/exege/>
+- Source and issues: <https://github.com/mahf708/exege>
+
+BSD-3-Clause. `exege.latents`, `exege.figures` and `exege.app` grew out of
+the [latent space visualiser for weather models](https://github.com/ktempestuous/latent_space_visualiser_weather_models)
+(Tempest, Beylich & Craig 2026, arXiv:2604.20467, doi:10.1007/978-3-032-29915-4_10); see
+`NOTICE`. The sparse autoencoders follow MacMillan & Ouellette (2025, arXiv:2512.24440);
+the B-spline autoencoder of Cheon (2026, arXiv:2605.17493) is what `exege.nn` is
+heading for and does not implement yet.

exege_core-0.6.0/packages/exege/pyproject.toml

@@ -0,0 +1,44 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+# The full install: no code of its own, only exege-core with every extra but nn.
+# `import exege` and the `exege` command come from exege-core either way. The version
+# and the pin below move together with `exege.__version__`; tests/test_packaging.py
+# and the release workflow refuse any disagreement.
+[project]
+name = "exege"
+version = "0.6.0"
+description = "Tools for understanding and evaluating scientific machine-learning models: latent-space diagnostics, sparse autoencoders, figures, a local app"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "BSD-3-Clause"
+authors = [{ name = "E3SM AI Group" }]
+keywords = ["interpretability", "emulator", "climate", "e3sm", "machine-learning"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Atmospheric Science",
+]
+dependencies = ["exege-core[app,hf]==0.6.0"]
+
+[project.optional-dependencies]
+# torch is left out of the default: its build (CPU, CUDA) is the machine's business.
+nn = ["exege-core[nn]==0.6.0"]
+
+[project.urls]
+Homepage = "https://mahf708.github.io/exege"
+Documentation = "https://mahf708.github.io/exege/"
+Source = "https://github.com/mahf708/exege"
+Issues = "https://github.com/mahf708/exege/issues"
+
+[tool.uv.sources]
+exege-core = { workspace = true }
+
+# Nothing to package but the metadata.
+[tool.hatch.build.targets.wheel]
+bypass-selection = true

exege_core-0.6.0/pyproject.toml

@@ -0,0 +1,112 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "exege-core"
+dynamic = ["version"]
+description = "Tools for understanding and evaluating scientific machine-learning models: the code, and only Click. `exege` is the full install."
+# The repository's README is about the repository; this one is about the package, and is
+# the page PyPI shows.
+readme = "src/exege/README.md"
+requires-python = ">=3.11"
+license = "BSD-3-Clause"
+license-files = ["LICENSE", "NOTICE"]
+authors = [{ name = "E3SM AI Group" }]
+keywords = ["interpretability", "emulator", "climate", "e3sm", "machine-learning"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Atmospheric Science",
+]
+
+# Base tier stays deliberately tiny: see src/exege/AGENTS.md
+dependencies = ["click>=8.1"]
+
+# One extra per subpackage that needs more than the base tier, named after it, and
+# no others: "to use exege.latents, install exege-core[latents]" is the whole rule.
+# The `exege` distribution (packages/exege) is this with every extra but nn.
+[project.optional-dependencies]
+# xarray reads what the adapters read, and needs a backend to open NetCDF with;
+# netCDF4 is the one the rest of the E3SM/ACE stack already uses.
+latents = ["numpy>=1.24", "xarray>=2023.1", "netCDF4>=1.6"]
+# cartopy is for coastlines; without its data (no network) maps are still drawn.
+figures = ["matplotlib>=3.7", "cartopy>=0.23", "exege-core[latents]"]
+app = ["streamlit>=1.50", "exege-core[figures]"]
+# It trains on latents, so it brings that extra as figures does.
+nn = ["torch>=2.0", "exege-core[latents]"]
+# Reads a latent archive straight from a Hugging Face dataset repository (hf://datasets/...),
+# a file at a time.
+hf = ["huggingface_hub>=0.23", "exege-core[latents]"]
+
+# What a checkout gets and a wheel does not. uv installs the `dev` and `full` groups by
+# default, so `uv run exege ...`, `uv run pytest` and `uv run ruff check` work with no
+# flags, while an installed exege-core stays on the base tier until an extra is asked for.
+# `full` is every extra but torch, which is large and whose build (CPU, CUDA) is the
+# machine's business: ask for it with `uv sync --extra nn`. The base tier alone:
+#   uv sync --no-default-groups --group dev
+# and the guide site: `uv run --group docs mkdocs build --strict`.
+[dependency-groups]
+dev = ["pytest>=7.4", "ruff>=0.5"]
+full = ["exege-core[app]", "exege-core[hf]"]
+# mkdocs 2 drops the plugin system this site is built on.
+docs = ["mkdocs>=1.6,<2", "mkdocs-material[imaging]>=9.5"]
+
+[tool.uv]
+default-groups = ["dev", "full"]
+
+# packages/exege is the full install: no code, only this distribution and its extras.
+[tool.uv.workspace]
+members = ["packages/exege"]
+
+[project.scripts]
+exege = "exege._cli:main"
+
+# The only way an adapter is found, shipped or third-party alike, so one can ship in a
+# separate distribution without editing exege at all. After adding an entry here, run
+# `uv sync` so the installed metadata is refreshed.
+[project.entry-points."exege.adapters"]
+latent-archive = "exege.adapters.latent_archive:LatentArchive"
+bundle-dir = "exege.adapters.bundle_dir:BundleDir"
+toy-dynamics = "exege.adapters.toy_dynamics:ToyDynamics"
+
+[project.urls]
+Homepage = "https://mahf708.github.io/exege"
+Documentation = "https://mahf708.github.io/exege/"
+Source = "https://github.com/mahf708/exege"
+Issues = "https://github.com/mahf708/exege/issues"
+
+[tool.hatch.version]
+path = "src/exege/__init__.py"
+
+# A release holds the package, its tests and its licences: not the guide site, the run
+# configs or the notes for contributors that share this repository with it.
+[tool.hatch.build.targets.sdist]
+include = ["src/exege", "tests", "LICENSE", "NOTICE", "pyproject.toml"]
+exclude = ["AGENTS.md"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/exege"]
+exclude = ["AGENTS.md", "src/exege/README.md"]
+
+[tool.ruff]
+line-length = 100
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+# TID252 bans relative imports: the architecture tests read absolute ones.
+select = ["E", "F", "I", "UP", "B", "SIM", "TID252"]
+
+[tool.ruff.lint.flake8-tidy-imports]
+ban-relative-imports = "all"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"
+# A compiled wheel (netCDF4, cftime) built against older numpy headers says this on
+# import. numpy silences it itself; pytest resets the filters, so it is restated here.
+filterwarnings = ["ignore:numpy.ndarray size changed:RuntimeWarning"]

exege_core-0.6.0/src/exege/README.md

@@ -0,0 +1,69 @@
+# exege
+
+Tools for understanding and evaluating scientific machine-learning models: what an
+emulator holds inside, sparse autoencoders trained on it, figures, and a local app over
+them. The name comes from the Greek stem *exēgē-*, associated with explanation and
+interpretation.
+
+> **Research tool.** `exege` is early. What is described here works; expect it to change.
+
+## Install
+
+This is the light install: the code, and only Click. Anything heavier sits behind an
+extra named after the subpackage that needs it:
+
+```console
+$ uv pip install 'exege-core[latents]'     # or: pip install 'exege-core[latents]'
+```
+
+For everything at once, install [exege](https://pypi.org/project/exege/) instead: it is
+this with every extra but `nn` (`pip install exege`, or `'exege[nn]'` to add torch). Both
+provide the same `import exege` and the same `exege` command.
+
+| Extra | Pulls | Gets you |
+| --- | --- | --- |
+| `latents` | numpy, xarray, netCDF4 | `exege.latents`: latent diagnostics on a grid |
+| `figures` | matplotlib, cartopy | `exege.figures`: maps and series figures (brings `latents`) |
+| `app` | streamlit | `exege app`: a local web app (brings `figures`) |
+| `nn` | torch | `exege.nn` and `exege nn`: sparse autoencoders (brings `latents`) |
+| `hf` | huggingface_hub | archives read from a Hugging Face repository, `hf://datasets/...` (brings `latents`) |
+
+A missing extra says so, with the command that fits how `exege` was installed.
+
+## Try it, with no model and no data
+
+A toy emulator writes a latent archive with nothing but numpy; everything else reads it
+like any other:
+
+```console
+$ exege latents toy scratch/toy/control
+$ exege latents info scratch/toy/control --mask-variable sst
+$ exege latents region scratch/toy/control --lat 10 --lon -114 --time 2 --centered --pcs 2
+$ exege latents fields scratch/toy/control --field precipitation --top 3
+$ exege nn sae scratch/toy/control --features 64 --k 4 --out scratch/toy/sae.npz   # needs exege-core[nn]
+$ exege app --latents scratch/toy                                                  # needs exege-core[app]
+```
+
+The CLI is a thin client of the Python API; anything it can do, a notebook can:
+
+```python
+from exege.latents import Region, analyze_region, open_source
+
+source = open_source("scratch/toy/control", mask_variable="sst")
+result = analyze_region(
+    source, time=2, layer=3, region=Region(lat=10, lon=-114, radius_km=1500), centered=True
+)
+result.ranking.channels  # the channels that respond most strongly there
+```
+
+## More
+
+- Documentation: <https://mahf708.github.io/exege/>
+- Source and issues: <https://github.com/mahf708/exege>
+
+BSD-3-Clause. `exege.latents`, `exege.figures` and `exege.app` grew out of
+the [latent space visualiser for weather models](https://github.com/ktempestuous/latent_space_visualiser_weather_models)
+(Tempest, Beylich & Craig 2026, arXiv:2604.20467, doi:10.1007/978-3-032-29915-4_10); see
+`NOTICE`. The sparse autoencoders follow MacMillan & Ouellette (2025, arXiv:2512.24440);
+the B-spline autoencoder of Cheon (2026, arXiv:2605.17493) is what `exege.nn` is
+heading for and does not implement yet.

exege_core-0.6.0/src/exege/__init__.py

@@ -0,0 +1,17 @@
+"""exege -- tools for understanding and evaluating scientific machine-learning models.
+
+Domains, and the presentation downstream of them:
+
+- ``exege.latents``  what emulators hold inside: the latent space, on a grid
+- ``exege.nn``       torch modules trained on those latents: a sparse autoencoder
+- ``exege.figures``  figures of what ``latents`` computes, with no web framework
+- ``exege.app``      a local web app over all of the above; nothing imports it
+
+Everything framework-specific lives in ``exege.adapters``. See ``AGENTS.md``.
+"""
+
+from __future__ import annotations
+
+__version__ = "0.6.0"
+
+__all__ = ["__version__"]

exege_core-0.6.0/src/exege/_cli.py

@@ -0,0 +1,89 @@
+"""Top-level ``exege`` command.
+
+Subcommands load lazily, so ``exege --help`` and one command never pay for (or
+require) what stands behind another.
+"""
+
+from __future__ import annotations
+
+import logging
+import sys
+from importlib import import_module
+from importlib.metadata import entry_points
+
+import click
+
+from exege import __version__
+from exege.core.errors import ExegeError
+
+log = logging.getLogger(__name__)
+
+# Shipped commands, by import path. Listing them for --help imports every cli
+# module, so each must stay importable on the base tier: anything heavier is
+# imported inside the command that needs it (tests/test_purity.py holds them to it).
+_COMMANDS = {
+    "latents": "exege.latents.cli:latents",
+    "nn": "exege.nn.cli:nn",
+    "app": "exege.app.cli:app",
+}
+
+# A separate distribution adds a command by registering a ``click.Command``
+# under this entry-point group. Shipped names win a clash.
+_GROUP = "exege.commands"
+
+
+class _LazyGroup(click.Group):
+    def list_commands(self, ctx: click.Context) -> list[str]:
+        return sorted(set(_COMMANDS) | {ep.name for ep in entry_points(group=_GROUP)})
+
+    def get_command(self, ctx: click.Context, name: str) -> click.Command | None:
+        if name in _COMMANDS:
+            module, _, attr = _COMMANDS[name].partition(":")
+            return getattr(import_module(module), attr)
+        for ep in entry_points(group=_GROUP):
+            if ep.name == name:
+                try:
+                    return ep.load()
+                except Exception as exc:  # one broken plugin must not take --help down
+                    log.warning("could not load command %r from %s: %s", name, ep.value, exc)
+        return None
+
+    def invoke(self, ctx: click.Context) -> object:
+        """Deliberate errors read as one clear line, not a traceback -- here, so
+        that a test runner or an embedding program sees what a terminal does.
+        ``--debug`` keeps the traceback."""
+        try:
+            return super().invoke(ctx)
+        except ExegeError as exc:
+            if ctx.params.get("debug"):
+                raise
+            raise click.ClickException(str(exc)) from exc
+
+
+@click.group(cls=_LazyGroup)
+@click.version_option(__version__, prog_name="exege")
+@click.option("--debug", is_flag=True, help="Verbose logging.")
+def cli(debug: bool) -> None:
+    """Tools for understanding and evaluating scientific machine-learning models."""
+    logging.basicConfig(
+        level=logging.DEBUG if debug else logging.WARNING,
+        format="%(levelname)s %(name)s: %(message)s",
+    )
+
+
+def main() -> None:
+    try:
+        # Not standalone, so that an interrupt exits 130 without click's "Aborted!".
+        # click then *returns* the code of a `ctx.exit(n)` instead of exiting with it.
+        code = cli.main(standalone_mode=False)
+    except click.ClickException as exc:
+        exc.show()
+        sys.exit(exc.exit_code)
+    except click.Abort:
+        sys.exit(130)
+    if isinstance(code, int) and code:
+        sys.exit(code)
+
+
+if __name__ == "__main__":
+    main()

exege_core-0.6.0/src/exege/_render.py

@@ -0,0 +1,31 @@
+"""Plain-text rendering. Presentation only, and stdlib only."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Mapping, Sequence
+from typing import Any
+
+
+def _cell(value: Any) -> str:
+    return "-" if value is None or value == "" else str(value)
+
+
+def table(rows: Sequence[Mapping[str, Any]], columns: Iterable[str] | None = None) -> str:
+    """Left-aligned fixed-width table. Returns '' for no rows so callers can
+    distinguish 'nothing found' from 'a header with nothing under it'."""
+    if not rows:
+        return ""
+    cols = list(columns) if columns is not None else list(rows[0].keys())
+    widths = {c: max(len(c), *(len(_cell(r.get(c))) for r in rows)) for c in cols}
+    out = ["  ".join(c.upper().ljust(widths[c]) for c in cols).rstrip()]
+    for row in rows:
+        out.append("  ".join(_cell(row.get(c)).ljust(widths[c]) for c in cols).rstrip())
+    return "\n".join(out)
+
+
+def pairs(mapping: Mapping[str, Any]) -> str:
+    """Aligned ``key: value`` block."""
+    if not mapping:
+        return ""
+    width = max(len(k) for k in mapping)
+    return "\n".join(f"{k.ljust(width)}  {_cell(v)}" for k, v in mapping.items())

exege_core-0.6.0/src/exege/adapters/__init__.py

@@ -0,0 +1,6 @@
+"""Adapters: every assumption about a specific framework lives here.
+
+Adapters are resolved through the ``exege.adapters`` entry-point group, so a new
+system ships as a new module (or a separate distribution) and core never changes.
+Heavy dependencies belong here, behind an extra -- never in the base tier.
+"""