limno 0.1.0__tar.gz

limno-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,56 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+      - run: pip install -e ".[dev]"
+      - run: ruff check .
+      - run: ruff format --check .
+      - run: mypy src
+
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest]
+        python-version: ["3.11", "3.12", "3.13", "3.14"]
+        include:
+          - os: windows-latest
+            python-version: "3.12"
+          - os: macos-latest
+            python-version: "3.12"
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+      - run: pip install -e ".[dev]"
+      - run: pytest --cov=limno --cov-report=term-missing
+
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install build twine
+      - run: python -m build
+      - run: twine check dist/*

limno-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,20 @@
+name: Publish
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  pypi:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install build
+      - run: python -m build
+      - uses: pypa/gh-action-pypi-publish@release/v1

limno-0.1.0/.gitignore

@@ -0,0 +1,14 @@
+__pycache__/
+*.py[cod]
+.venv/
+dist/
+build/
+*.egg-info/
+.coverage
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.ipynb_checkpoints/
+
+# Docs
+docs/_build/

limno-0.1.0/.readthedocs.yaml

@@ -0,0 +1,18 @@
+# Read the Docs configuration, see https://docs.readthedocs.io/en/stable/config-file/v2.html
+version: 2
+
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.12"
+
+sphinx:
+  configuration: docs/conf.py
+  fail_on_warning: true
+
+python:
+  install:
+    - method: pip
+      path: .
+      extras:
+        - docs

limno-0.1.0/AGENTS.md

@@ -0,0 +1,46 @@
+# AGENTS.md
+
+* Set up a virtual environment, then run `pip install -e ".[dev,docs]"` to install development
+  dependencies.
+    - Add `pip install -e ".[river]" matplotlib pandas jupyter` to run the notebooks.
+* Run doctests and unit tests with `pytest -q`. This runs `tests` and the doctests in `src`.
+* Run lint and type checks with `ruff check .` and `mypy src`.
+* Check notebooks execute with
+  `jupyter nbconvert --to notebook --execute --stdout notebooks/*.ipynb > /dev/null`.
+* Build documentation with `sphinx-build -W -b html docs docs/_build/html`.
+* Clean documentation with `rm -rf docs/_build`.
+* MUST run formatter `ruff format .` before committing code.
+* MUST ask the user before pushing to GitHub.
+* SHOULD add user-facing changes to the `Unreleased` section of `CHANGELOG.md`.
+
+## Design
+
+* Explainers MUST rely on the protocols in `limno.base`, not on a specific library. River models
+  and metrics satisfy them as they are. Other libraries get an adapter.
+* Heavy dependencies MUST be optional extras, imported inside the function that needs them, so
+  that `import limno` works without them.
+
+## Commit messages
+
+* SHOULD use conventional commit messages. You MAY introduce breaking changes, but MUST
+  NOT include `!` or `BREAKING CHANGE` in the commit message since we are pre v1.0.0.
+* MUST NOT add `Co-Authored-By: Claude <noreply@anthropic.com>` (or similar) to commit messages.
+* MUST add `Assisted-by: AGENT_NAME:MODEL_VERSION [TOOL1] [TOOL2] ...` to the end of
+  commit messages and PR descriptions.
+    * `AGENT_NAME` is the name of the harness (/tool/framework)
+    * `MODEL_VERSION` is the specific model version. SHOULD be as specific as possible
+       including model family, version, and size.
+    * `[TOOL1] [TOOL2]` are optional agent developer tools or MCP. SHOULD NOT include
+       basic developer tools.
+    * Example: `Assisted-by: claude-code:claude-opus-5.5 github-mcp-server`
+    * Example: `Assisted-by: copilot:gemini-3.7-flash`
+
+## Documentation
+
+* SHOULD use simplified technical english in documentation and comments.
+* SHOULD NOT use long words where a short one will do.
+* SHOULD use everyday words except where technical terms are required.
+* If it is possible to cut a word out, you SHOULD cut it out.
+* SHOULD avoid complex sentence structures.
+* Consider using commas or parenthesis over em-dash or removing the clause entirely.
+* Docstrings use the NumPy style, with code between single backticks.

limno-0.1.0/CHANGELOG.md

@@ -0,0 +1,35 @@
+# CHANGELOG
+
+
+
+## Unreleased
+
+
+
+## v0.1.0 (2026-11-11)
+
+### Feature
+
+* Add `lm.base` with the `Model`, `Metric` and `Tracker` protocols, and the `Explainer`, `ImportanceExplainer`, `Storage` and `Imputer` base classes
+
+* Add `lm.importance.PFI`, the incremental permutation feature importance (iPFI) of Fumagalli et al. (2023)
+
+* Add `lm.importance.SAGE`, the interventional version of incremental SAGE (iSAGE) of Muschalik et al. (2023)
+
+* Add `max_age` to `lm.importance.PFI`, which hides features that have stopped appearing
+
+* Add `groups` to `lm.importance.PFI` and `lm.importance.SAGE`, which treats some features as one
+
+* Add `lm.multioutput` with `PerOutput`, which gives the importances of each output of a model
+
+* Add `lm.storage` with `UniformReservoir` and `GeometricReservoir`
+
+* Add `lm.imputer` with `Marginal`
+
+* Add `lm.tracker` with `Mean` and `EWMean`
+
+### Documentation
+
+* Add a notebook on how `lm.importance.PFI` works
+
+* Add a notebook on how `lm.importance.SAGE` works

limno-0.1.0/CITATION.cff

@@ -0,0 +1,23 @@
+cff-version: 1.2.0
+message: "If you use limno in your research, please cite it as below."
+type: software
+title: "limno: explainable AI for data streams and continual learning"
+abstract: >-
+  limno is a Python library to explain models that learn from data streams, one
+  instance at a time. It follows the conventions of River.
+authors:
+  - family-names: "da Costa Garcia"
+    given-names: "Vitor"
+    email: vitorcostagarcia2006@gmail.com
+    orcid: "https://orcid.org/0009-0009-0772-8356"
+version: 0.1.0
+date-released: 2026-11-11
+license: BSD-3-Clause
+repository-code: "https://github.com/vitor-costa-garcia/limno"
+keywords:
+  - explainable AI
+  - data streams
+  - online learning
+  - incremental learning
+  - continual learning
+  - river

limno-0.1.0/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Vitor
+
+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.

limno-0.1.0/PKG-INFO

@@ -0,0 +1,121 @@
+Metadata-Version: 2.5
+Name: limno
+Version: 0.1.0
+Summary: Explainable AI for data streams and continual learning.
+Project-URL: Homepage, https://github.com/vitor-costa-garcia/limno
+Project-URL: Issues, https://github.com/vitor-costa-garcia/limno/issues
+Author-email: Vitor da Costa Garcia <vitorcostagarcia2006@gmail.com>
+License-Expression: BSD-3-Clause
+License-File: LICENSE
+Keywords: continual-learning,data-streams,explainable-ai,incremental-learning,online-learning,river,xai
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.11
+Provides-Extra: dev
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: river>=0.21; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: furo; extra == 'docs'
+Requires-Dist: myst-parser; extra == 'docs'
+Requires-Dist: sphinx; extra == 'docs'
+Provides-Extra: river
+Requires-Dist: river>=0.21; extra == 'river'
+Description-Content-Type: text/markdown
+
+# limno
+
+[![CI](https://github.com/vitor-costa-garcia/limno/actions/workflows/ci.yml/badge.svg)](https://github.com/vitor-costa-garcia/limno/actions/workflows/ci.yml)
+
+**Explainable AI for data streams and continual learning.**
+
+> limno is in early development: the API may change.
+
+## What is this?
+
+A model that learns from a stream keeps changing, and so do the reasons behind its predictions.
+Most explanation tools assume a fixed model and a fixed dataset, so they do not fit this setting.
+limno provides explanations that are computed one instance at a time and that follow the model as
+it learns. Limnology is the study of inland waters, and limno looks at what goes on inside a
+stream.
+
+limno follows [River](https://riverml.xyz)'s conventions and works with River's models, pipelines,
+metrics and statistics as they are. It complements River rather than replacing it. Other libraries,
+such as [CapyMOA](https://capymoa.org), are not supported yet, but explainers do not depend on
+River, so an adapter can add them later.
+
+## Features
+
+- **Incremental permutation feature importance** (`lm.importance.PFI`), from
+  [Fumagalli et al. (2023)](https://doi.org/10.1007/s10994-023-06385-y). It shows how much a model
+  relies on each feature, as the stream goes on.
+- **Incremental SAGE** (`lm.importance.SAGE`), from
+  [Muschalik et al. (2023)](https://doi.org/10.1007/978-3-031-43418-1_26). Its values add up to the
+  drop in loss between predicting the mean and using the model.
+- **Groups of features** (`groups=`), to measure features that only make sense together as one.
+- **Models with many outputs** (`lm.multioutput.PerOutput`), to see which features each output
+  relies on.
+- **River metrics as the loss.** Whether the model is asked for labels or probabilities depends on
+  the metric, as in River.
+- **Separate pieces** that can be swapped:
+  - Storages (`lm.storage`) keep past instances: `UniformReservoir` and `GeometricReservoir`.
+  - Imputers (`lm.imputer`) replace feature values: `Marginal`.
+  - Trackers (`lm.tracker`) keep running values: `Mean`, `EWMean`, or any of `river.stats`.
+- **Features can appear and disappear** along the stream, with no list of names to give upfront. A
+  feature that stops appearing is hidden after `max_age` instances.
+- **Reproducible runs** with a `seed`.
+- **A base class for your own explainers** (`lm.base.Explainer` and
+  `lm.base.ImportanceExplainer`).
+
+## Installation
+
+```bash
+pip install "limno[river]"
+```
+
+The `river` extra installs River. limno itself has no required dependencies, so
+`pip install limno` is enough for models and metrics from elsewhere.
+
+## Quickstart
+
+```python
+from river import datasets, linear_model, metrics, preprocessing
+
+import limno as lm
+
+model = preprocessing.StandardScaler() | linear_model.LogisticRegression()
+explainer = lm.importance.PFI(model, metrics.LogLoss(), seed=42)
+
+for x, y in datasets.Phishing():
+    explainer.learn_one(x, y)  # before the model learns, so the instance is new to it
+    model.learn_one(x, y)
+
+explainer.importances
+```
+
+```
+{'empty_server_form_handler': 0.177, 'popup_window': 0.11, 'https': 0.106, ...}
+```
+
+A positive value means that the model does better with the feature, and a value close to zero that
+it does not rely on it. The explainer never updates the model.
+
+## Notebooks
+
+The [notebooks](https://github.com/vitor-costa-garcia/limno/tree/main/notebooks) show limno in use
+with River. [How incremental PFI works](https://github.com/vitor-costa-garcia/limno/blob/main/notebooks/01_how_pfi_works.ipynb)
+and [How incremental SAGE works](https://github.com/vitor-costa-garcia/limno/blob/main/notebooks/02_how_sage_works.ipynb)
+explain the methods step by step.
+
+## Contributing and feedback
+
+Ideas, use cases and criticism are welcome through
+[GitHub issues](https://github.com/vitor-costa-garcia/limno/issues).
+
+## License
+
+BSD 3-Clause. See [LICENSE](https://github.com/vitor-costa-garcia/limno/blob/main/LICENSE).

limno-0.1.0/README.md

@@ -0,0 +1,92 @@
+# limno
+
+[![CI](https://github.com/vitor-costa-garcia/limno/actions/workflows/ci.yml/badge.svg)](https://github.com/vitor-costa-garcia/limno/actions/workflows/ci.yml)
+
+**Explainable AI for data streams and continual learning.**
+
+> limno is in early development: the API may change.
+
+## What is this?
+
+A model that learns from a stream keeps changing, and so do the reasons behind its predictions.
+Most explanation tools assume a fixed model and a fixed dataset, so they do not fit this setting.
+limno provides explanations that are computed one instance at a time and that follow the model as
+it learns. Limnology is the study of inland waters, and limno looks at what goes on inside a
+stream.
+
+limno follows [River](https://riverml.xyz)'s conventions and works with River's models, pipelines,
+metrics and statistics as they are. It complements River rather than replacing it. Other libraries,
+such as [CapyMOA](https://capymoa.org), are not supported yet, but explainers do not depend on
+River, so an adapter can add them later.
+
+## Features
+
+- **Incremental permutation feature importance** (`lm.importance.PFI`), from
+  [Fumagalli et al. (2023)](https://doi.org/10.1007/s10994-023-06385-y). It shows how much a model
+  relies on each feature, as the stream goes on.
+- **Incremental SAGE** (`lm.importance.SAGE`), from
+  [Muschalik et al. (2023)](https://doi.org/10.1007/978-3-031-43418-1_26). Its values add up to the
+  drop in loss between predicting the mean and using the model.
+- **Groups of features** (`groups=`), to measure features that only make sense together as one.
+- **Models with many outputs** (`lm.multioutput.PerOutput`), to see which features each output
+  relies on.
+- **River metrics as the loss.** Whether the model is asked for labels or probabilities depends on
+  the metric, as in River.
+- **Separate pieces** that can be swapped:
+  - Storages (`lm.storage`) keep past instances: `UniformReservoir` and `GeometricReservoir`.
+  - Imputers (`lm.imputer`) replace feature values: `Marginal`.
+  - Trackers (`lm.tracker`) keep running values: `Mean`, `EWMean`, or any of `river.stats`.
+- **Features can appear and disappear** along the stream, with no list of names to give upfront. A
+  feature that stops appearing is hidden after `max_age` instances.
+- **Reproducible runs** with a `seed`.
+- **A base class for your own explainers** (`lm.base.Explainer` and
+  `lm.base.ImportanceExplainer`).
+
+## Installation
+
+```bash
+pip install "limno[river]"
+```
+
+The `river` extra installs River. limno itself has no required dependencies, so
+`pip install limno` is enough for models and metrics from elsewhere.
+
+## Quickstart
+
+```python
+from river import datasets, linear_model, metrics, preprocessing
+
+import limno as lm
+
+model = preprocessing.StandardScaler() | linear_model.LogisticRegression()
+explainer = lm.importance.PFI(model, metrics.LogLoss(), seed=42)
+
+for x, y in datasets.Phishing():
+    explainer.learn_one(x, y)  # before the model learns, so the instance is new to it
+    model.learn_one(x, y)
+
+explainer.importances
+```
+
+```
+{'empty_server_form_handler': 0.177, 'popup_window': 0.11, 'https': 0.106, ...}
+```
+
+A positive value means that the model does better with the feature, and a value close to zero that
+it does not rely on it. The explainer never updates the model.
+
+## Notebooks
+
+The [notebooks](https://github.com/vitor-costa-garcia/limno/tree/main/notebooks) show limno in use
+with River. [How incremental PFI works](https://github.com/vitor-costa-garcia/limno/blob/main/notebooks/01_how_pfi_works.ipynb)
+and [How incremental SAGE works](https://github.com/vitor-costa-garcia/limno/blob/main/notebooks/02_how_sage_works.ipynb)
+explain the methods step by step.
+
+## Contributing and feedback
+
+Ideas, use cases and criticism are welcome through
+[GitHub issues](https://github.com/vitor-costa-garcia/limno/issues).
+
+## License
+
+BSD 3-Clause. See [LICENSE](https://github.com/vitor-costa-garcia/limno/blob/main/LICENSE).

limno-0.1.0/docs/api/base.rst

@@ -0,0 +1,4 @@
+``limno.base``
+==============
+
+.. automodule:: limno.base

limno-0.1.0/docs/api/importance.rst

@@ -0,0 +1,5 @@
+``limno.importance``
+====================
+
+.. automodule:: limno.importance
+   :inherited-members: ImportanceExplainer

limno-0.1.0/docs/api/imputer.rst

@@ -0,0 +1,4 @@
+``limno.imputer``
+=================
+
+.. automodule:: limno.imputer

limno-0.1.0/docs/api/index.md

@@ -0,0 +1,12 @@
+# API reference
+
+```{toctree}
+:maxdepth: 1
+
+importance
+multioutput
+storage
+imputer
+tracker
+base
+```

limno-0.1.0/docs/api/multioutput.rst

@@ -0,0 +1,4 @@
+``limno.multioutput``
+=====================
+
+.. automodule:: limno.multioutput

limno-0.1.0/docs/api/storage.rst

@@ -0,0 +1,4 @@
+``limno.storage``
+=================
+
+.. automodule:: limno.storage

limno-0.1.0/docs/api/tracker.rst

@@ -0,0 +1,4 @@
+``limno.tracker``
+=================
+
+.. automodule:: limno.tracker

limno-0.1.0/docs/conf.py

@@ -0,0 +1,36 @@
+"""Sphinx configuration."""
+
+import limno
+
+project = "limno"
+author = "Vitor da Costa Garcia"
+copyright = f"2026, {author}"
+release = limno.__version__
+version = ".".join(release.split(".")[:2])
+
+extensions = [
+    "myst_parser",
+    "sphinx.ext.autodoc",
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.napoleon",
+    "sphinx.ext.viewcode",
+]
+
+exclude_patterns = ["_build"]
+
+# The docstrings write code between single backticks, as in Markdown
+default_role = "py:obj"
+
+autodoc_default_options = {"members": True, "show-inheritance": True}
+autodoc_member_order = "bysource"
+autodoc_typehints = "description"
+
+napoleon_google_docstring = False
+napoleon_numpy_docstring = True
+
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3", None),
+}
+
+html_theme = "furo"
+html_title = "limno"

limno-0.1.0/docs/index.md

@@ -0,0 +1,20 @@
+# limno
+
+**Explainable AI for data streams and continual learning.**
+
+```{note}
+limno is in early development: the API may change.
+```
+
+A model that learns from a stream keeps changing, and so do the reasons behind its predictions.
+limno provides explanations that are computed one instance at a time and that follow the model as
+it learns. It follows [River](https://riverml.xyz)'s conventions and works with River's models,
+pipelines, metrics and statistics as they are.
+
+```{toctree}
+:maxdepth: 2
+
+installation
+quickstart
+api/index
+```

limno-0.1.0/docs/installation.md

@@ -0,0 +1,14 @@
+# Installation
+
+```bash
+pip install "limno[river]"
+```
+
+The `river` extra installs River 0.21 or later. limno itself has no required dependencies, so
+`pip install limno` is enough for models and metrics from elsewhere.
+
+To work on limno, install it from a clone:
+
+```bash
+pip install -e ".[dev,docs]"
+```