|
1 | 1 | # AGENTS.md |
2 | 2 |
|
3 | | -Guidance for Claude Code when working in this repository. |
4 | | - |
5 | | -## Project Overview |
6 | | - |
7 | | -`shapiq` is a Python library for computing Shapley Interactions for Machine Learning. The repo hosts **two separate installable packages**: |
8 | | -- `shapiq` in `src/shapiq/` — the core library |
9 | | -- `shapiq_games` in `src/shapiq_games/` — optional benchmark games (requires extra ML deps via `uv sync --group all_ml`) |
10 | | - |
11 | | -## Commands |
12 | | - |
13 | | -```sh |
14 | | -# Setup |
15 | | -uv sync # dev dependencies (test + lint + all_ml) |
16 | | - |
17 | | -# Testing |
18 | | -uv run pytest tests/shapiq |
19 | | -uv run pytest tests/shapiq_games -n logical |
20 | | -uv run pytest tests/shapiq/tests_unit/test_interaction_values.py # single file |
21 | | - |
22 | | -# Quality (run before every commit) |
23 | | -uv run pre-commit run --all-files |
24 | | -uv run ty check # type check src/shapiq/ only |
25 | | - |
26 | | -# Docs |
27 | | -uv run sphinx-build -b html docs/source docs/build/html |
28 | | -``` |
29 | | - |
30 | | -## Package Structure |
31 | | - |
32 | | -``` |
33 | | -src/ |
34 | | -├── shapiq/ |
35 | | -│ ├── interaction_values.py # InteractionValues — central output type |
36 | | -│ ├── game.py # Base Game class |
37 | | -│ ├── approximator/ # Approximation algorithms (base.py + subdirs) |
38 | | -│ ├── explainer/ |
39 | | -│ │ ├── tabular.py # TabularExplainer — main user-facing class |
40 | | -│ │ ├── tree/ |
41 | | -│ │ └── product_kernel/ |
42 | | -│ ├── imputer/ # MarginalImputer is the default |
43 | | -│ ├── game_theory/ |
44 | | -│ │ ├── exact.py |
45 | | -│ │ ├── indices.py # ALL_AVAILABLE_CONCEPTS — index registry |
46 | | -│ │ └── moebius_converter.py |
47 | | -│ ├── plot/ |
48 | | -│ └── utils/ |
49 | | -└── shapiq_games/ |
50 | | - ├── benchmark/ |
51 | | - ├── synthetic/ |
52 | | - └── tabular/ |
53 | | -``` |
54 | | - |
55 | | -## Code Style |
56 | | - |
57 | | -- **All files** must start with `from __future__ import annotations` — `isort` enforces this |
58 | | -- `ruff` with `black` style, line length 100, Google-style docstrings |
59 | | -- Uppercase `X` in function signatures is allowed (ML convention) |
60 | | - |
61 | | -## Key Rules |
62 | | - |
63 | | -- **Do not** add ML-heavy dependencies to `shapiq` core — they belong in `shapiq_games` |
64 | | -- Use existing fixtures in `tests/shapiq/fixtures/` rather than duplicating setup |
65 | | -- `ty` type checking runs on `src/shapiq/` only; tests are excluded |
| 3 | +This role of this file is to describe common mistakes and confusion points that agents might encounter as they work in this project. If you ever encounter something in the project that surprises you, please alert the developer working with you and indicate that this is the case in the Agent.md file to help prevent future agents from having the same issue. |
0 commit comments