interox 0.1.0__tar.gz

interox-0.1.0/.gitignore

@@ -0,0 +1,18 @@
+# Python
+__pycache__/
+*.py[cod]
+.venv/
+.python-version
+dist/
+build/
+*.egg-info/
+
+# Test / type-check artefacts
+.pytest_cache/
+.mypy_cache/
+
+# Frontend
+js/node_modules/
+
+# NOTE: interox/static/*.js is committed on purpose -- these are the built
+# bundles the widgets load at import, so `pip install interox` needs no Node.

interox-0.1.0/PKG-INFO

@@ -0,0 +1,189 @@
+Metadata-Version: 2.5
+Name: interox
+Version: 0.1.0
+Summary: Interactive, rule-based outcome explanation for process-mining case logs, as notebook widgets
+Project-URL: Homepage, https://github.com/aaronkurz/interox
+Project-URL: Repository, https://github.com/aaronkurz/interox
+Project-URL: Issues, https://github.com/aaronkurz/interox/issues
+Author: Aaron Kurz
+Keywords: anywidget,case-log,explainability,jupyter,marimo,process-mining,rule-induction
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: Jupyter
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Requires-Python: >=3.13
+Requires-Dist: anywidget<0.12,>=0.11
+Requires-Dist: coolname>=5.0
+Requires-Dist: eclear<0.2,>=0.1.0
+Requires-Dist: numpy>=2.0
+Requires-Dist: pandas<4,>=3.0
+Requires-Dist: rulelearn-ripper-interactive<0.3,>=0.2.3
+Requires-Dist: scikit-learn>=1.5
+Requires-Dist: traitlets>=5.14
+Description-Content-Type: text/markdown
+
+# interox
+
+Interactive outcome explanation for process-mining case logs.
+
+`interox` helps you find out *why* some cases of a process end the way they do.
+You hand it a case log and a boolean outcome; it suggests DNF rules (via a fork
+of RIPPER rule induction) that tell the outcome cases apart from the rest, and
+gives you notebook widgets to inspect, store, edit and build rules until the
+outcome is explained.
+
+```bash
+uv add interox        # or: pip install interox
+```
+
+The widgets ship pre-built inside the package, so using interox needs no Node
+or JavaScript toolchain.
+
+## Use
+
+```python
+from interox import InterOX
+
+iox = InterOX(outcome, case_log)   # outcome: bool Series, case_log: DataFrame, same index
+
+iox.get_exp_status()               # how much of the outcome the stored rules explain
+iox.get_suggested_ruleset()        # induced suggestions, as a table widget
+iox.get_stored_ruleset()           # the rules you kept
+iox.get_rule_builder()             # build a rule from scratch
+```
+
+Rendering needs a notebook that speaks [anywidget](https://anywidget.dev):
+marimo, Jupyter, VS Code. The API reference is generated from the docstrings:
+
+```bash
+uv run pdoc interox
+```
+
+A complete walkthrough on a public event log lives in
+[interox-nodebook-sepsis](https://github.com/aaronkurz/interox-nodebook-sepsis).
+
+## Requirements
+
+Python 3.13+ and pandas 3. Case-log enrichment comes from
+[eclear](https://pypi.org/project/eclear/) and rule induction from
+[rulelearn-ripper-interactive](https://pypi.org/project/rulelearn-ripper-interactive/)
+(imported as `rulelearn_ri`); both install as dependencies.
+
+## Development
+
+Everything Python goes through uv:
+
+```bash
+uv sync                # creates .venv with interox (editable) + the dev group
+./code-check.sh        # pylint + mypy + pytest
+```
+
+The widgets are React 18 + TypeScript in `js/`, bundled with esbuild into
+`interox/static/*.js`:
+
+```bash
+cd js
+npm ci                 # install React, esbuild, TypeScript tooling
+npm run build          # minified production bundles → ../interox/static/
+npm run dev            # watch mode, unminified, for working on a widget
+npm run typecheck      # esbuild does not typecheck; run this separately
+```
+
+See [DEVELOPMENT.md](DEVELOPMENT.md) for the architecture,
+[DECISIONS.md](DECISIONS.md) for why it is shaped this way, and
+[ubiquitous-language.md](ubiquitous-language.md) for the agreed vocabulary.
+
+### How the compiled widgets get into the package
+
+Each widget class points `_esm` at a file next to it, e.g.
+`pathlib.Path(__file__).parent / "static" / "rule_builder.js"`. anywidget reads
+that file when the widget is created, so the bundle has to be *inside* the
+installed package. Two things make sure it is:
+
+- `interox/static/*.js` is **committed on purpose** (the same choice as eclear).
+  Whatever is in git is what a build from a clean checkout ships, and a notebook
+  user never runs npm.
+- `[tool.hatch.build.targets.wheel] packages = ["interox"]` puts the whole
+  `interox/` directory, `static/` included, into the wheel. `js/` and `tests/`
+  stay out of the wheel; the sdist carries them so it can be rebuilt.
+
+So the rule is: **whenever anything under `js/src` changes, run
+`npm run build` and commit the regenerated `interox/static/*.js` together with
+the source change.** A stale bundle is the one packaging mistake that goes
+unnoticed until someone opens a notebook.
+
+## Releasing to PyPI
+
+Run from the repo root. Nothing here is automated: an upload is irreversible,
+so each step is yours to run.
+
+**1. Rebuild the widgets and re-verify** against exactly what you will ship:
+
+```bash
+(cd js && npm ci && npm run typecheck && npm run build)
+git status --short interox/static    # changed bundles? commit them first
+./code-check.sh
+```
+
+**2. Bump the version** in `pyproject.toml` (`version = "0.1.0"`). A version
+number can never be reused on PyPI, even after deleting the release.
+
+**3. Build the distributions:**
+
+```bash
+rm -rf dist/
+uv build
+uvx twine check dist/*
+unzip -l dist/interox-*.whl
+```
+
+The wheel listing must contain the four bundles
+`interox/static/{rule_detail,ruleset_table,explanation_status,rule_builder}.js`
+and must **not** contain `js/`, `node_modules` or `tests/`.
+
+**4. Smoke-test the built wheel** from a directory that is *not* this repo,
+otherwise Python imports the local `interox/` folder and you have tested
+nothing:
+
+```bash
+cd /tmp
+uv run --isolated --no-project --with ~/Developer/interox/dist/interox-0.1.0-py3-none-any.whl \
+  python -c "import interox, interox.rule_builder_widget as w; print(interox.__file__); print(len(str(w.RuleBuilderWidget._esm)))"
+```
+
+The path must be inside a `site-packages`, and the length must be well above
+zero: that is the bundle anywidget will send to the notebook.
+
+**5. Dry run on TestPyPI** (separate site, separate account and token:
+<https://test.pypi.org/manage/account/token/>):
+
+```bash
+uv publish --publish-url https://test.pypi.org/legacy/
+cd /tmp
+uv run --isolated --no-project \
+  --index https://test.pypi.org/simple/ --index-strategy unsafe-best-match \
+  --with interox python -c "import interox; print(interox.__file__)"
+```
+
+The extra index flags are needed because the dependencies come from real PyPI.
+
+**6. Publish for real.** Create a token at <https://pypi.org/manage/account/token/>.
+For a project that does not exist yet it must be **account-scoped**; after the
+first upload, replace it with a project-scoped one.
+
+```bash
+read -rs UV_PUBLISH_TOKEN && export UV_PUBLISH_TOKEN && uv publish
+```
+
+**7. Tag the release:**
+
+```bash
+git tag v0.1.0
+git push origin main --tags
+```
+
+Later, PyPI trusted publishing (a GitHub Actions workflow that uploads on a
+pushed tag, no stored token) removes the token step:
+<https://pypi.org/manage/project/interox/settings/publishing/>.

interox-0.1.0/README.md

@@ -0,0 +1,163 @@
+# interox
+
+Interactive outcome explanation for process-mining case logs.
+
+`interox` helps you find out *why* some cases of a process end the way they do.
+You hand it a case log and a boolean outcome; it suggests DNF rules (via a fork
+of RIPPER rule induction) that tell the outcome cases apart from the rest, and
+gives you notebook widgets to inspect, store, edit and build rules until the
+outcome is explained.
+
+```bash
+uv add interox        # or: pip install interox
+```
+
+The widgets ship pre-built inside the package, so using interox needs no Node
+or JavaScript toolchain.
+
+## Use
+
+```python
+from interox import InterOX
+
+iox = InterOX(outcome, case_log)   # outcome: bool Series, case_log: DataFrame, same index
+
+iox.get_exp_status()               # how much of the outcome the stored rules explain
+iox.get_suggested_ruleset()        # induced suggestions, as a table widget
+iox.get_stored_ruleset()           # the rules you kept
+iox.get_rule_builder()             # build a rule from scratch
+```
+
+Rendering needs a notebook that speaks [anywidget](https://anywidget.dev):
+marimo, Jupyter, VS Code. The API reference is generated from the docstrings:
+
+```bash
+uv run pdoc interox
+```
+
+A complete walkthrough on a public event log lives in
+[interox-nodebook-sepsis](https://github.com/aaronkurz/interox-nodebook-sepsis).
+
+## Requirements
+
+Python 3.13+ and pandas 3. Case-log enrichment comes from
+[eclear](https://pypi.org/project/eclear/) and rule induction from
+[rulelearn-ripper-interactive](https://pypi.org/project/rulelearn-ripper-interactive/)
+(imported as `rulelearn_ri`); both install as dependencies.
+
+## Development
+
+Everything Python goes through uv:
+
+```bash
+uv sync                # creates .venv with interox (editable) + the dev group
+./code-check.sh        # pylint + mypy + pytest
+```
+
+The widgets are React 18 + TypeScript in `js/`, bundled with esbuild into
+`interox/static/*.js`:
+
+```bash
+cd js
+npm ci                 # install React, esbuild, TypeScript tooling
+npm run build          # minified production bundles → ../interox/static/
+npm run dev            # watch mode, unminified, for working on a widget
+npm run typecheck      # esbuild does not typecheck; run this separately
+```
+
+See [DEVELOPMENT.md](DEVELOPMENT.md) for the architecture,
+[DECISIONS.md](DECISIONS.md) for why it is shaped this way, and
+[ubiquitous-language.md](ubiquitous-language.md) for the agreed vocabulary.
+
+### How the compiled widgets get into the package
+
+Each widget class points `_esm` at a file next to it, e.g.
+`pathlib.Path(__file__).parent / "static" / "rule_builder.js"`. anywidget reads
+that file when the widget is created, so the bundle has to be *inside* the
+installed package. Two things make sure it is:
+
+- `interox/static/*.js` is **committed on purpose** (the same choice as eclear).
+  Whatever is in git is what a build from a clean checkout ships, and a notebook
+  user never runs npm.
+- `[tool.hatch.build.targets.wheel] packages = ["interox"]` puts the whole
+  `interox/` directory, `static/` included, into the wheel. `js/` and `tests/`
+  stay out of the wheel; the sdist carries them so it can be rebuilt.
+
+So the rule is: **whenever anything under `js/src` changes, run
+`npm run build` and commit the regenerated `interox/static/*.js` together with
+the source change.** A stale bundle is the one packaging mistake that goes
+unnoticed until someone opens a notebook.
+
+## Releasing to PyPI
+
+Run from the repo root. Nothing here is automated: an upload is irreversible,
+so each step is yours to run.
+
+**1. Rebuild the widgets and re-verify** against exactly what you will ship:
+
+```bash
+(cd js && npm ci && npm run typecheck && npm run build)
+git status --short interox/static    # changed bundles? commit them first
+./code-check.sh
+```
+
+**2. Bump the version** in `pyproject.toml` (`version = "0.1.0"`). A version
+number can never be reused on PyPI, even after deleting the release.
+
+**3. Build the distributions:**
+
+```bash
+rm -rf dist/
+uv build
+uvx twine check dist/*
+unzip -l dist/interox-*.whl
+```
+
+The wheel listing must contain the four bundles
+`interox/static/{rule_detail,ruleset_table,explanation_status,rule_builder}.js`
+and must **not** contain `js/`, `node_modules` or `tests/`.
+
+**4. Smoke-test the built wheel** from a directory that is *not* this repo,
+otherwise Python imports the local `interox/` folder and you have tested
+nothing:
+
+```bash
+cd /tmp
+uv run --isolated --no-project --with ~/Developer/interox/dist/interox-0.1.0-py3-none-any.whl \
+  python -c "import interox, interox.rule_builder_widget as w; print(interox.__file__); print(len(str(w.RuleBuilderWidget._esm)))"
+```
+
+The path must be inside a `site-packages`, and the length must be well above
+zero: that is the bundle anywidget will send to the notebook.
+
+**5. Dry run on TestPyPI** (separate site, separate account and token:
+<https://test.pypi.org/manage/account/token/>):
+
+```bash
+uv publish --publish-url https://test.pypi.org/legacy/
+cd /tmp
+uv run --isolated --no-project \
+  --index https://test.pypi.org/simple/ --index-strategy unsafe-best-match \
+  --with interox python -c "import interox; print(interox.__file__)"
+```
+
+The extra index flags are needed because the dependencies come from real PyPI.
+
+**6. Publish for real.** Create a token at <https://pypi.org/manage/account/token/>.
+For a project that does not exist yet it must be **account-scoped**; after the
+first upload, replace it with a project-scoped one.
+
+```bash
+read -rs UV_PUBLISH_TOKEN && export UV_PUBLISH_TOKEN && uv publish
+```
+
+**7. Tag the release:**
+
+```bash
+git tag v0.1.0
+git push origin main --tags
+```
+
+Later, PyPI trusted publishing (a GitHub Actions workflow that uploads on a
+pushed tag, no stored token) removes the token step:
+<https://pypi.org/manage/project/interox/settings/publishing/>.

interox-0.1.0/interox/__init__.py

@@ -0,0 +1,37 @@
+"""
+# InterOX: Interactive Outcome Explanation for Case Logs
+
+`interox` exposes the `InterOX` class, which supports iterative, rule-based
+outcome explanation over a case log. The workflow is typically:
+
+1. Inspect explanation progress.
+2. Compare stored and suggested rules.
+3. Store rules that improve coverage.
+4. Optionally hide or unhide features and re-induce suggestions.
+
+Start here
+----------
+- `InterOX.get_exp_status` — where the explanation stands.
+- `InterOX.get_stored_ruleset` / `InterOX.get_suggested_ruleset` — the two
+  rulesets, with metrics, as table widgets.
+- `InterOX.get_rule_builder` — build a rule from scratch instead of taking a
+  suggested one.
+- `InterOX.send_rule_to_builder` — take a suggested rule into that builder to
+  adjust it before storing (the ✎ button on a suggested row).
+- `InterOX.store_rule_by_id` / `InterOX.remove_rule_by_id` — change the stored
+  ruleset; both re-induce suggestions.
+
+A rule is addressed by its **stable id**, which survives re-induction and
+reordering: prefer the `*_by_id` methods over the positional ones of the same
+name. `InterOX.get_stored_rule_options` maps rule names to those ids.
+
+The rest of the class -- rule detail widgets, annotations, hidden features, and
+the `get_*_case_log` / `get_data_*` accessors for analysis outside the provided
+widgets -- is documented on the methods themselves, below.
+"""
+import logging
+from .interox import InterOX
+
+logging.getLogger(__name__).addHandler(logging.NullHandler())
+
+__all__ = ["InterOX"]

interox-0.1.0/interox/explanation_status_widget.py

@@ -0,0 +1,22 @@
+# pylint: disable=missing-module-docstring
+import pathlib
+import anywidget
+import traitlets
+
+
+class ExplanationStatusWidget(anywidget.AnyWidget): # pylint: disable=too-few-public-methods, abstract-method
+    """A widget for displaying the status of an outcome explanation
+    in terms of remaining (FN), explained (TP) and wrongly claimed (FP) cases,
+    the negatives the explanation leaves alone (TN), and the number of rules the
+    explanation is currently made of.
+
+    The four case counts partition the case log, which lets the frontend draw
+    the flow from the case log through the rule set to the prediction. All
+    traits are Python-owned; the frontend never writes back."""
+    _esm = pathlib.Path(__file__).parent / "static" / "explanation_status.js"
+
+    cases_tbe = traitlets.Int(default_value=0).tag(sync=True)
+    exp_tp = traitlets.Int(default_value=0).tag(sync=True)
+    exp_fp = traitlets.Int(default_value=0).tag(sync=True)
+    exp_tn = traitlets.Int(default_value=0).tag(sync=True)
+    stored_rules = traitlets.Int(default_value=0).tag(sync=True)

interox-0.1.0/interox/helpers.py

@@ -0,0 +1,131 @@
+"""Supporting functions for InterOX."""
+import operator
+from collections import defaultdict
+from typing import Any, Callable, Dict, List, Tuple
+import logging
+from rulelearn_ri.trxf.core import Conjunction, DnfRuleSet, Feature
+from rulelearn_ri.trxf.core.predicate import Relation
+from pandas import Series
+
+logger = logging.getLogger(__name__)
+
+#: The comparison each trxf relation stands for. Rule evaluation compares values
+#: directly rather than rendering them into an expression to `eval`, so a value
+#: is only ever compared, never parsed.
+_RELATION_OPS = {
+    Relation.EQ: operator.eq,
+    Relation.NEQ: operator.ne,
+    Relation.LT: operator.lt,
+    Relation.LE: operator.le,
+    Relation.GT: operator.gt,
+    Relation.GE: operator.ge,
+}
+
+
+def is_usable_feature_name(name) -> bool:
+    """Whether a column name can carry a rule condition.
+
+    `trxf` parses a feature name as an arithmetic expression, so a name is only
+    usable if it happens to be a valid one. Most punctuation survives -- `.`,
+    `:` and `::` are absorbed into a single token -- but `+ - * /` and
+    parentheses are read as operators, and a name that then fails to parse
+    (`*.concept:name::append`, `Payment_(late)::count`) cannot become a
+    `Feature` at all.
+
+    The failure modes are varied enough (`ValueError` from the expression
+    validator, `TokenError` from the tokenizer, `IndexError` from an unbalanced
+    parenthesis) that the only useful question is whether construction works.
+    """
+    try:
+        Feature(str(name))
+        return True
+    except Exception:  # pylint: disable=broad-except
+        return False
+
+
+def rule_to_lambda(rule: Conjunction,
+                   skip_feature=None,
+                   only_feature=None) -> Callable[[Series], bool]:
+    """Convert a rule (conjunction of predicates) to a lambda function
+    that evaluates the rule on a case.
+
+    A predicate becomes a column lookup and a comparison against the value the
+    predicate carries, whatever that value is. Nothing is rendered into source
+    text, so a category that looks like a number (`'nan'`, `'1e3'`), a value
+    holding a quote, and a column name holding an apostrophe all compare as
+    themselves. An empty conjunction -- every predicate filtered out, or none to
+    begin with -- matches every case.
+
+    Raises:
+        KeyError: When evaluating a case that has no column for a predicate's
+            feature.
+    """
+    if skip_feature is not None and only_feature is not None:
+        raise ValueError("skip_feature and only_feature are mutually exclusive")
+    tests: List[Tuple[str, Callable[[Any, Any], bool], Any]] = []
+    for predicate in rule.predicates:
+        feature = str(predicate.feature)
+        if skip_feature is not None and feature == skip_feature:
+            continue
+        if only_feature is not None and feature != only_feature:
+            continue
+        logger.debug("Processing predicate: %s %s %s",
+                     feature, predicate.relation.value, predicate.value)
+        try:
+            op = _RELATION_OPS[predicate.relation]
+        except KeyError as exc:
+            raise ValueError(f'Unknown relation {predicate.relation!r}') from exc
+        tests.append((feature, op, predicate.value))
+
+    return lambda case: all(op(case[feature], value) for feature, op, value in tests)
+
+
+def conjunction_to_conditions(conjunction: Conjunction) -> List[Dict[str, Any]]:
+    """Convert a rule into the condition list the rule builder canvas speaks.
+
+    The builder holds at most one condition per attribute, so the predicates are
+    grouped by feature first: a GE/LE pair on the same feature is the two sides
+    of one `range` condition, and a lone bound keeps its own operator. Predicates
+    beyond the first of each relation on a feature are dropped -- the canvas has
+    nowhere to put them. So are whole relations the canvas cannot express: NEQ,
+    LT and GT have no branch here, because a categorical condition is `==` only
+    (RIPPER induces no negation) and a numeric one is an inclusive bound. Note
+    this is narrower than `_RELATION_OPS` above, which still evaluates all six --
+    a rule can carry a relation the builder would not let you author.
+
+    This is the inverse of `RuleBuilderWidget._conditions_to_predicates`, and it
+    is what lets an already-induced rule be loaded back into the builder (see
+    `InterOX.send_rule_to_builder`).
+    """
+    by_attr: Dict[str, List[Any]] = defaultdict(list)
+    for predicate in conjunction.predicates:
+        # `str`, as in `rule_to_lambda`: a predicate's feature is a `Feature` when
+        # it comes from the inducer but a bare column name when it was built by
+        # hand, and both render as the column name.
+        by_attr[str(predicate.feature)].append(predicate)
+
+    conditions: List[Dict[str, Any]] = []
+    for attr_name, preds in by_attr.items():
+        ge = next((p for p in preds if p.relation == Relation.GE), None)
+        le = next((p for p in preds if p.relation == Relation.LE), None)
+        eq = next((p for p in preds if p.relation == Relation.EQ), None)
+        if ge and le:
+            conditions.append({'attr': attr_name, 'op': 'range',
+                               'lo': float(ge.value), 'hi': float(le.value)})
+        elif ge:
+            conditions.append({'attr': attr_name, 'op': '>=', 'value': float(ge.value)})
+        elif le:
+            conditions.append({'attr': attr_name, 'op': '<=', 'value': float(le.value)})
+        elif eq:
+            conditions.append({'attr': attr_name, 'op': '==', 'value': str(eq.value)})
+    return conditions
+
+
+def ruleset_to_lambda(ruleset: DnfRuleSet, skip_feature=None) -> Callable[[Series], bool]:
+    """Convert a ruleset (disjunction of conjunctions) to a lambda function
+    that evaluates the ruleset on a case."""
+    rule_lambdas = []
+    for conji in ruleset.conjunctions:
+        rule_lambdas.append(rule_to_lambda(conji, skip_feature))
+
+    return lambda case: any(rule_lambda(case) for rule_lambda in rule_lambdas)