Add ty linter. (#493)

* add MANIFEST.in

* add MANIFEST.in

* updated MANIFEST.in and python-publish.yml workflow

* updated CHANGELOG.md

* updated shapiq-games warning

* migrate type checker from pyright to ty and fix all type errors

Replace pyright with Astral's ty (Rust-based, 10-100x faster) across the
entire project: update pyproject.toml dependency group, replace [tool.pyright]
config with [tool.ty] sections, swap the pre-commit hook to a local ty hook,
and update CLAUDE.md references.

Fix all resulting type errors across 30+ source files: align override
signatures (approximate, explain_function) with base class, replace
pyright-specific ignore comments with ty-compatible ones, annotate ambiguous
types (decoder_args, bounds_players, coalition_lookup), and add targeted
type: ignore directives for unresolvable stubs (lightgbm, matplotlib internals).

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: mmschlk

.pre-commit-config.yaml

@@ -17,8 +17,11 @@ repos:
         args: [--fix, --exit-non-zero-on-fix, --no-cache]
       - id: ruff-format
 
-  - repo: https://github.com/RobertCraigie/pyright-python
-    rev: v1.1.404
+  - repo: local
     hooks:
-    - id: pyright
-      args: [--verbose, --venvpath=.]
+      - id: ty
+        name: ty
+        entry: uv run ty check
+        language: system
+        pass_filenames: false
+        types: [python]

CLAUDE.md

@@ -0,0 +1,149 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+`shapiq` is a Python library for computing Shapley Interactions for Machine Learning. It approximates any-order Shapley interactions, benchmarks game-theoretical algorithms, and explains feature interactions in model predictions. The repo contains two importable packages: `shapiq` (core) and `shapiq_games` (benchmark games).
+
+## Development Setup
+
+This project uses `uv` for package management.
+
+```sh
+# Install dev dependencies (test + lint + all_ml)
+uv sync
+
+# Install only test dependencies
+uv sync --group test
+
+# Install lint tools
+uv sync --group lint
+```
+
+## Commands
+
+### Testing
+
+```sh
+# Run all shapiq unit tests
+uv run pytest tests/shapiq
+
+# Run all shapiq_games tests (parallel)
+uv run pytest tests/shapiq_games -n logical
+
+# Run a single test file
+uv run pytest tests/shapiq/tests_unit/test_interaction_values.py
+
+# Run with coverage
+uv run pytest tests/shapiq --cov=shapiq --cov-report=xml -n logical
+```
+
+### Linting and Code Quality
+
+```sh
+# Run all pre-commit hooks (ruff lint + format + ty)
+uv run pre-commit run --all-files
+
+# Run ruff linter only
+uv run ruff check src/ tests/ --fix
+
+# Run ruff formatter only
+uv run ruff format src/ tests/
+
+# Run type checking
+uv run ty check
+```
+
+### Documentation
+
+```sh
+uv sync --no-dev --group docs
+uv run sphinx-build -b html docs/source docs/build/html
+```
+
+## Code Architecture
+
+### Package Structure
+
+```
+src/
+├── shapiq/              # Core package
+│   ├── interaction_values.py   # InteractionValues data class (central output type)
+│   ├── game.py                 # Base Game class for cooperative games
+│   ├── approximator/           # Approximation algorithms
+│   │   ├── base.py             # Approximator base class
+│   │   ├── marginals/          # Owen, Stratified sampling
+│   │   ├── montecarlo/         # SHAPIQ, SVARM, SVARMIQ, UnbiasedKernelSHAP
+│   │   ├── permutation/        # Permutation sampling for SII, STII, SV
+│   │   ├── regression/         # KernelSHAP, KernelSHAPIQ, RegressionFSII/FBII
+│   │   └── sparse/             # SPEX, ProxySPEX (for large feature spaces)
+│   ├── explainer/              # High-level explainer interfaces
+│   │   ├── tabular.py          # TabularExplainer (main user-facing class)
+│   │   ├── tree/               # TreeExplainer with model-specific conversions
+│   │   └── product_kernel/     # ProductKernelExplainer
+│   ├── imputer/                # Imputation strategies for missing features
+│   │   ├── marginal_imputer.py # MarginalImputer (most common)
+│   │   ├── baseline_imputer.py
+│   │   ├── gaussian_imputer.py
+│   │   └── tabpfn_imputer.py
+│   ├── game_theory/            # Mathematical game-theory utilities
+│   │   ├── exact.py            # ExactComputer for exact interaction values
+│   │   ├── indices.py          # ALL_AVAILABLE_CONCEPTS index registry
+│   │   ├── moebius_converter.py
+│   │   └── aggregation.py
+│   ├── plot/                   # Visualization functions
+│   └── utils/                  # Shared utilities (sets, saving, typing)
+└── shapiq_games/        # Benchmark games package (separate from shapiq)
+    ├── benchmark/       # Pre-defined benchmark games per use-case
+    ├── synthetic/       # Synthetic game functions
+    └── tabular/         # Tabular ML games
+```
+
+### Core Data Flow
+
+1. **Game** (`game.py`): Wraps any callable as a cooperative game. Subclasses implement `value_function(coalitions) -> np.ndarray`. Takes a boolean coalition matrix and returns scalar game values.
+
+2. **Approximator** (`approximator/`): Takes a `Game` and a budget, calls `approximate(budget, game)` → returns `InteractionValues`. All approximators inherit from `Approximator` base class.
+
+3. **InteractionValues** (`interaction_values.py`): Central data class storing interaction scores as a numpy array with an `interaction_lookup` dict mapping coalition tuples → array indices. Supports arithmetic operations between instances.
+
+4. **Explainer** (`explainer/`): High-level interface combining an ML model + data + an `Imputer` into a `Game`, then calling an `Approximator`. `Explainer.explain(x)` → `InteractionValues`.
+
+5. **Imputer** (`imputer/`): Converts ML model + data into a game by handling missing features. `MarginalImputer` is the default for tabular data.
+
+### Interaction Indices
+
+Available indices are defined in `game_theory/indices.py` (`ALL_AVAILABLE_CONCEPTS`). Key ones:
+- `SV` – Shapley Values (order 1 only)
+- `SII` – Shapley Interaction Index
+- `k-SII` – k-Shapley Interaction Index (most common for explanations)
+- `STII` – Shapley-Taylor Interaction Index
+- `FSII` – Faithful Shapley Interaction Index
+- `FBII` – Faithful Banzhaf Interaction Index
+- `BV` – Banzhaf Values
+
+### Code Style
+
+- **Formatter/Linter**: `ruff` with `black` style, line length 100, Google-style docstrings
+- **Type checking**: `ty` (checks `src/shapiq/`, excluded for tests)
+- **All files** must start with `from __future__ import annotations`
+- `isort` is configured with `required-imports = ["from __future__ import annotations"]`
+- Variable names `X` (uppercase) in functions are allowed (common in ML code)
+- Test files live in `tests/shapiq/` and `tests/shapiq_games/` with separate conftest files
+
+### Test Organization
+
+- `tests/shapiq/tests_unit/` – Unit tests per module
+- `tests/shapiq/tests_integration_tests/` – Integration tests
+- `tests/shapiq/tests_deprecation/` – Deprecation behavior tests
+- `tests/shapiq/fixtures/` – Shared pytest fixtures (data, games, models, interaction values)
+- `tests/shapiq_games/` – Tests for the `shapiq_games` package
+
+### Two-Package Setup
+
+The repo hosts two installable packages:
+- `shapiq` in `src/shapiq/` — the core library
+- `shapiq_games` in `src/shapiq_games/` — optional benchmark games requiring extra ML dependencies (`torch`, `transformers`, `tabpfn`)
+
+`shapiq_games` requires `uv sync --group all_ml` for full functionality.

pyproject.toml

@@ -207,6 +207,15 @@ exclude = [
 [tool.ruff.lint.pydocstyle]
 convention = "google"
 
+[tool.ty.src]
+include = ["src/shapiq"]
+exclude = ["tests", "docs", "benchmark", "scripts", "src/shapiq_games"]
+
+[tool.ty.environment]
+python-version = "3.10"
+python = "./.venv"
+python-platform = "linux"
+
 [tool.ruff.lint.isort]
 known-first-party = ["shapiq"]
 extra-standard-library = ["typing_extensions"]
@@ -215,15 +224,6 @@ force-wrap-aliases = true
 no-lines-before = ["future"]
 required-imports = ["from __future__ import annotations"]
 
-[tool.pyright]
-include = ["src/shapiq"]
-exclude = ["tests", "docs", "benchmark", "scripts", "src/shapiq_games"]
-venv = ".venv"
-pythonVersion = "3.10"
-defineConstant = { DEBUG = true }
-reportMissingImports = "error"
-reportMissingTypeStubs = false
-pythonPlatform = "Linux"
 
 [dependency-groups]
 all_ml = [
@@ -246,7 +246,7 @@ test = [
 lint = [
     "ruff>=0.14.1",       # for linting
     "pre-commit>=4.3.0",  # for running the linters pre-commit hooks
-    "pyright>=1.1.402",   # for type checking
+    "ty>=0.0.21",         # for type checking
 ]
 docs = [
     "sphinx>=8.0.0",            # documentation generator

src/shapiq/approximator/base.py

@@ -179,7 +179,6 @@ def approximate(
         self,
         budget: int,
         game: Game | Callable[[np.ndarray], np.ndarray],
-        *args: Any,
         **kwargs: Any,
     ) -> InteractionValues:
         """Approximates the interaction values.

src/shapiq/approximator/montecarlo/base.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, Literal, TypeVar, get_args
+from typing import TYPE_CHECKING, Any, Literal, TypeVar, get_args
 
 import numpy as np
 from scipy.special import binom, factorial
@@ -14,6 +14,7 @@
 if TYPE_CHECKING:
     from collections.abc import Callable
 
+    from shapiq.game import Game
     from shapiq.typing import FloatVector
 
 ValidMonteCarloIndices = Literal["k-SII", "SII", "STII", "FSII", "FBII", "SV", "CHII", "BII", "BV"]
@@ -38,7 +39,7 @@ def __init__(
         self,
         n: int,
         max_order: int,
-        index: TIndices = "k-SII",
+        index: ValidMonteCarloIndices = "k-SII",
         *,
         stratify_coalition_size: bool = True,
         stratify_intersection: bool = True,
@@ -91,13 +92,15 @@ def __init__(
     def approximate(
         self,
         budget: int,
-        game: Callable[[np.ndarray], np.ndarray],
+        game: Game | Callable[[np.ndarray], np.ndarray],
+        **kwargs: Any,  # noqa: ARG002
     ) -> InteractionValues:
         """Approximates the Shapley interaction values using Monte Carlo sampling.
 
         Args:
             budget: The budget for the approximation.
             game: The game function that returns the values for the coalitions.
+            **kwargs: Additional keyword arguments (unused).
 
         Returns:
             The approximated Shapley interaction values.

src/shapiq/approximator/montecarlo/shapiq.py

@@ -52,7 +52,7 @@ def __init__(
         self,
         n: int,
         max_order: int = 2,
-        index: TIndices = "k-SII",
+        index: ValidMonteCarloIndices = "k-SII",
         *,
         top_order: bool = False,
         sampling_weights: FloatVector | None = None,

src/shapiq/approximator/permutation/sii.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, Literal, get_args
+from typing import TYPE_CHECKING, Any, Literal, get_args
 
 import numpy as np
 
@@ -13,6 +13,8 @@
 if TYPE_CHECKING:
     from collections.abc import Callable
 
+    from shapiq.game import Game
+
 ValidPermutationSIIIndices = Literal["SII", "k-SII"]
 
 
@@ -99,15 +101,17 @@ def _compute_order_iterator(self) -> np.ndarray:
     def approximate(
         self,
         budget: int,
-        game: Callable[[np.ndarray], np.ndarray],
+        game: Game | Callable[[np.ndarray], np.ndarray],
         batch_size: int | None = 5,
+        **kwargs: Any,  # noqa: ARG002
     ) -> InteractionValues:
         """Approximates the interaction values.
 
         Args:
             budget: The budget for the approximation.
             game: The game function as a callable that takes a set of players and returns the value.
             batch_size: The size of the batch. If ``None``, the batch size is set to ``1``. Defaults to ``5``.
+            **kwargs: Additional keyword arguments (unused).
 
         Returns:
             InteractionValues: The estimated interaction values.

src/shapiq/approximator/permutation/stii.py

@@ -15,6 +15,8 @@
 if TYPE_CHECKING:
     from collections.abc import Callable
 
+    from shapiq.game import Game
+
 ValidPermutationSTIIIndices = Literal["STII"]
 
 
@@ -89,9 +91,8 @@ def __init__(
     def approximate(
         self,
         budget: int,
-        game: Callable[[np.ndarray], np.ndarray],
+        game: Game | Callable[[np.ndarray], np.ndarray],
         batch_size: int = 1,
-        *args: Any,  # noqa: ARG002
         **kwargs: Any,  # noqa: ARG002
     ) -> InteractionValues:
         """Approximates the interaction values.

src/shapiq/approximator/permutation/sv.py

@@ -67,7 +67,6 @@ def approximate(
         budget: int,
         game: Game | Callable[[np.ndarray], np.ndarray],
         batch_size: int | None = 5,
-        *args: Any,  # noqa: ARG002
         **kwargs: Any,  # noqa: ARG002
     ) -> InteractionValues:
         """Approximates the Shapley values using ApproShapley.

src/shapiq/approximator/regression/base.py

@@ -16,6 +16,7 @@
 if TYPE_CHECKING:
     from collections.abc import Callable
 
+    from shapiq.game import Game
     from shapiq.typing import CoalitionMatrix, FloatVector
 
 
@@ -123,7 +124,7 @@ def _init_kernel_weights(self, interaction_size: int) -> FloatVector:
     def approximate(
         self,
         budget: int,
-        game: Callable[[np.ndarray], np.ndarray],
+        game: Game | Callable[[np.ndarray], np.ndarray],
         *args: Any | None,  # noqa: ARG002
         **kwargs: Any,  # noqa: ARG002
     ) -> InteractionValues: