cds-interpret 0.1.0__tar.gz

cds_interpret-0.1.0/.gitignore

@@ -0,0 +1,29 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.venv/
+venv/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+
+# what the toolkit writes when you use it
+cds-demo/
+recordings/
+runs/
+*.html
+!docs/**/*.html
+examples/rlbot_demo_bot/recordings/
+
+# editors and OS
+.vscode/
+.idea/
+.DS_Store
+Thumbs.db
+
+collision_meshes/

cds_interpret-0.1.0/CHANGELOG.md

@@ -0,0 +1,85 @@
+# Changelog
+
+All notable changes to cds-interpret are written down here. The project follows
+[Semantic Versioning](https://semver.org); before 1.0, minor versions may change the API (each change is listed).
+
+## [0.1.0] - 2026-10-17
+
+The first public version: the interpretability toolkit of the Cat Distribution System, on its own, for any PyTorch
+Rocket League bot.
+
+### Added
+
+- **Bring your own policy** (`Policy`): any eager PyTorch network, a function from game state to its input, its
+  action table and what its output means (logits, probabilities, log-probabilities or continuous controls).
+  `eager_copy` turns a TorchScript MLP back into hookable modules; `lookup_table()` builds the common 90-action
+  table; `describe_action` says an action in words.
+- **Game state** (`Frames`) from RLGym v1 / v2 states, RLBot v5 packets or plain arrays, and back to RLGym v2 states
+  (`cds_interpret.rlgym`, with `obs_fn` to run any RLGym ObsBuilder on any moment).
+- **Concept labels** for any bot's moments, from the game state alone: the ball's landing, time to the ball, last man
+  back, goal side, threats and shots, demolition chances, kickoffs, car state - and future labels from recorded play
+  (a shot, a touch, a demolition, a goal for or against soon; an `outlook` for bots without a critic).
+  `register_label` adds your own.
+- **Recorders**: `record.rocketsim` (your bot in RocketSim against itself, another policy or a scripted player, with
+  RocketSim's ball prediction for the labels), `record.with_recorder` (your RLBot v5 bot class records the real game,
+  unchanged) and `record.rlgym` (your own RLGym v2 environment). `Moments` save and load as `.npy` column shards.
+- **Probes** with game-wise held-out scores, the raw-input and random-network baselines, and steadiness numbers for
+  probes shown live (weight norm, noise sensitivity, jitter against the label's own); the penalty acts on one scale
+  for the whole layer by default, so a near-silent unit cannot earn a giant weight.
+- **Sparse autoencoders** (top-k, with AuxK), their checks (variance explained, the policy run on the reconstruction)
+  and feature analysis (label relations, name guesses, strongest distinct moments, firing thresholds,
+  `causal_targets`).
+- **Edits** for causal tests: replace with an SAE's reconstruction, ablate or scale features, clamp, steer, project
+  out or scale a probe's direction, mean-ablate; their effect on the policy (`edit_effect`), `editing(...)` for
+  whole games, and `bootstrap_share` / `rate_ratio_ci` for intervals.
+- **`Study`**: the whole flow in a few calls, and an HTML **report** (light and dark, no internet needed) whose
+  sections are extensible (`report.section`).
+- **The live thoughts overlay** for any RLBot v5 bot (`overlay.with_thoughts`): the outlook, the next move and how
+  sure it is, the features firing (held 0.6 s), probes as bars, and where the network thinks the ball will land.
+  Display only: read-only hooks, a low-priority worker process that is never sent anything before it is ready and
+  is written to by a thread of its own, nothing drawn on a decision's tick. Packs are plain `.npz` files.
+- **A panel you design yourself**: rows, names, colours, firing thresholds, hold time, position, width, smoothing,
+  title and markers in a small TOML file, without touching library code (`cds-interpret panel` writes an example of
+  every option, which draws the default panel), plus Python hooks for rows and markers of your own. Mistakes show
+  when the file loads, with where they are and what you probably meant; `cds-interpret check-panel` (and the overlay
+  at start) lists rows and styles naming probes or features the pack doesn't have.
+- **Naming features, end to end** (`names`): suggested names from the labels with warnings (a feature that fires
+  mostly at kickoffs, say), each different suggestion before any repeats, a gallery page of each feature's strongest
+  moments, a names file you confirm names in (with each feature's sizes, so thresholds can be picked), and
+  `Study.check_feature` (turn a feature off and up and see what the bot does differently - by number or by name)
+  and `make_pack(names=...)`. Names stay on their features: `Study.features` is seeded, `FeatureSet.save` /
+  `Study.load_features` keep a dictionary for good, and a names file records its dictionary's code
+  (`sae.fingerprint`) and refuses to go on any other. A threshold the feature never reaches is refused too.
+- **Tracking** a concept across training snapshots.
+- **Following a bot through its training** (`emergence`): its dispositions on a fixed bank of moments (the action
+  classes it puts its probability on in a demo chance, an aerial chance, a 50/50 ...), its habits in recorded games
+  with intervals (demolitions, air and wall play, flip resets, hard hits, kickoffs and kickoff goals, the goal share in
+  open play, contact), the health of its
+  layers (dead / dormant units, effective rank, CKA to another snapshot, weight norms) and the critic's calibration
+  against the next goal, and `interval_changes` for what moved beyond its intervals since the last snapshot.
+  `docs/howto/track-training.md`.
+- **Choosing what to practise** (`curriculum`): a situation map for both sides of recorded games (how often each side
+  is in each situation, and what follows), what is over-represented before the goals a bot concedes (`enrichment`),
+  a small `kmeans` to group those moments and `eta_squared` to compare descriptions of a state.
+- **Friendly by default**: plain-words errors that say what to do (with "did you mean" for layers and labels),
+  probes scored only when the held-out games have enough examples (and the skipped ones listed with the reason),
+  recordings that are never mixed up by accident (`if_exists`, with `"reuse"` for scripts you run again), a probe
+  table that separates what the network worked out from what its input already gave, and a step-by-step demo whose
+  edits come with a random-direction control.
+- **What a decision rests on** (`attribution`, `Study.attribution`, a report section): the ball, the bot's car and
+  boost, the opponents and the team-mates swapped for another moment's through the bot's own obs function, every
+  combination run, exact Shapley shares, and a faithfulness score for any ranking (1 = the best possible order).
+  `docs/howto/what-decisions-rest-on.md`.
+- **What each feature makes the bot do** (`effects`): every active feature removed on its own, its change in each
+  control and in the chosen action; the features a decision rests on; rankings scored by removing them together;
+  attribution patching as the cheap estimate. `hooks.tail` gives the network after a layer.
+- **Checks for the tools themselves** (`docs/howto/check-your-tools.md`): `sae.downstream_check`, `sae.finetune_kl`
+  and a KL term in `train_sae` (a dictionary faithful to the decisions), `sae.BatchTopKSAE`, `dict_eval` (seed
+  stability by decoder and by firing, single-feature label detection, liveness), `erasure` (LEACE with a same-rank
+  placebo: does the policy use what a probe reads?), `probes.mlp_probe`, and `readout` (calibrated gauges -
+  `calibrate_pack_probe` - smoothing with its measured lag, flag flicker).
+- **A crosscoder over training snapshots** (`crosscoder`): one dictionary over the same layer of several snapshots;
+  each feature's decoder norm per snapshot says when it is there.
+- **The demo bot**: a tiny network trained to imitate a scripted player, so everything runs without anyone's weights;
+  `cds-interpret demo` runs the whole tour and `cds-interpret doctor` says what is ready. A complete RLBot v5 bot
+  folder for it in `examples/rlbot_demo_bot`.

cds_interpret-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,109 @@
+# Contributing to cds-interpret
+
+Thank you for wanting to make it better. New techniques, new labels, new recorders, fixes, docs and examples are all
+welcome. This page says how the code is laid out, where new things slot in, and what a change needs before it is
+merged.
+
+## Set up
+
+```bash
+git clone https://github.com/adventure-gpt/cds-interpret
+cd cds-interpret
+python -m venv .venv && . .venv/bin/activate          # Windows: .venv\Scripts\activate
+pip install torch --index-url https://download.pytorch.org/whl/cpu   # a CPU build is all the tests need
+pip install -e ".[sim,rlgym,rlbot]" pytest ruff mypy  # rlgym needs Python 3.11-3.12
+pytest                                                # about two minutes on a laptop CPU
+ruff check src tests scripts examples
+```
+
+The tests that need RocketSim's collision meshes or RLBot skip themselves when those are missing; CI runs them on
+Python 3.12 with every extra installed.
+
+## How the package is laid out
+
+One module per technique, each usable on its own with plain arrays and tensors; `Study` ties them together.
+
+| module | what it is |
+|---|---|
+| `frames.py` | `Frames`, the one game-state format, and its adapters (RLGym, RLBot, arrays) |
+| `labels.py` | concept labels from game state, future labels, and the label registry |
+| `policy.py` | `Policy` (bring your own network), action tables, `eager_copy` |
+| `hooks.py` | `LayerTap` and friends: reading and editing layers through forward hooks |
+| `moments.py`, `store.py` | recorded moments and the column store under them |
+| `record/` | one module per source: `sim.py` (RocketSim), `rlbot.py` (the real game), `rlgym_env.py`, `scripted.py` |
+| `probes.py` | linear probes, held-out metrics, steadiness |
+| `sae.py` | top-k sparse autoencoders |
+| `intervene.py` | edits and their effect on the policy |
+| `analysis.py` | features against labels, top moments, causal target selection |
+| `names.py` | suggested feature names, the names file |
+| `behavior.py` | habit counts from game state alone |
+| `tracking.py` | probes across training snapshots |
+| `emergence.py` | habits, dispositions and layer health, snapshot after snapshot |
+| `curriculum.py` | situations, outcomes and enrichment: what to practise next |
+| `study.py` | `Study`, `ProbeResults`, `FeatureSet`: the high-level flow |
+| `report.py` | the HTML report and its section registry |
+| `viz/` | dependency-free SVG charts, field drawings, the feature gallery |
+| `overlay/` | the live thoughts overlay: `pack.py` (what is read), `panel.py` (how it is drawn, and its TOML config), `worker.py`, `bot.py` |
+| `demo/` | the demo bot and the tour |
+| `_rlbot.py` | what the RLBot recorder and the overlay share |
+
+## Where new things slot in
+
+- **A new technique** (say, attribution or a new kind of probe): a new module next to `probes.py` / `sae.py` that
+  works on arrays and tensors and knows nothing of `Study`. Then, if it belongs in the everyday flow, a small
+  `Study` method that calls it on `self.activations(layer)`, `self.labels`, `self.train` / `self.test`, and a report
+  section:
+
+  ```python
+  from cds_interpret.report import section
+
+  @section("Attributions", order=35)          # built-in sections: 0, 10, 20, 30, 40, 50, 90
+  def _attributions(study):
+      res = getattr(study, "attribution_results", None)
+      return "" if res is None else render(res)  # return "" to leave the section out
+  ```
+
+- **A new label**: `labels.register_label("name", kind="bin" | "reg", doc="...")` on a function of a `LabelInput`
+  (frames, the car of each moment, team-frame positions, the ball's path, the built-in labels). A label that every
+  bot needs belongs in `concept_labels` itself, with a line in the module docstring's table, `LABEL_KIND` and
+  `LABEL_DOC`, and a test with a hand-made moment.
+- **A new recorder** (another simulator, replays): a module in `record/` that fills a
+  `record._builder.Recording` - `add_step` for every decision step (all cars, with events), `add_moment` for the
+  moments the bot decided at - and returns `recording.finish()`. Labels and future labels then come for free.
+- **A new edit**: a function in `intervene.py` returning `edit(x) -> x'`; `edit_effect` and `editing` work with it
+  unchanged.
+- **The overlay**: what is read lives in the pack (`overlay/pack.py`); how it is drawn in `overlay/panel.py`. A new
+  kind of panel row is a branch in `Panel._row`, a name in `ROW_KINDS`, a line in `panel_example.toml` and a row in
+  `docs/howto/customize-the-panel.md`. Keep the rules of `overlay/bot.py`: read-only hooks, the work after the
+  controls are sent, nothing that can block the bot.
+
+## What a change needs
+
+- **Tests** for the new behaviour, on tiny hand-made inputs where possible (`tests/conftest.py` has helpers). A
+  read-only hook must leave a network's outputs bit for bit the same - test it when you add one.
+- **Type hints** on public functions, and a docstring that says what goes in and what comes out (shapes in
+  brackets: `[N, D]`).
+- **Friendly errors**: raise `CDSInterpretError` (or `ShapeError`, `LayerNotFound`, `MissingDependency`) with a
+  message in plain words that says what went wrong and what to do, like the docs; import optional packages through
+  `errors.require`.
+- **Friendly docs**: lead with what the reader gets, then a snippet that runs and the output it prints, then the
+  explanation. Plain words and short sentences; explain a term the first time it appears.
+- **Safe defaults**: CPU, small threads, nothing written outside the paths a user gives, no pickled code in files
+  meant to be shared (`torch.load(..., weights_only=True)`, `np.load(..., allow_pickle=False)`).
+- **Docs**: the how-to that covers it, `docs/api.md`, and a line in `CHANGELOG.md` under "not yet released".
+- `ruff check` clean, `pytest` green.
+- Nothing from other people's bots: no other authors' code, weights, ports or replays, and no machine-specific paths
+  or personal data in code, tests, docs or commit messages.
+
+## Working on the same branch as others
+
+Several people may be porting improvements at the same time. Pull before you push
+(`git pull --rebase`), keep commits small and about one thing, and say in the message what changed and why.
+
+## Releasing (maintainers)
+
+1. Move the "not yet released" section of `CHANGELOG.md` under the new version and date; set
+   `src/cds_interpret/_version.py`.
+2. `python -m build` and check the wheel installs in a clean environment (`pip install dist/*.whl`;
+   `cds-interpret demo`).
+3. Tag `vX.Y.Z` and push the tag.

cds_interpret-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 adventure-gpt
+
+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.

cds_interpret-0.1.0/PKG-INFO

@@ -0,0 +1,194 @@
+Metadata-Version: 2.5
+Name: cds-interpret
+Version: 0.1.0
+Summary: Look inside any PyTorch Rocket League bot: concept labels, robust probes, sparse-autoencoder features, causal tests and a live in-game thoughts overlay
+Project-URL: Homepage, https://github.com/adventure-gpt/cds-interpret
+Project-URL: Documentation, https://github.com/adventure-gpt/cds-interpret/tree/main/docs
+Project-URL: Changelog, https://github.com/adventure-gpt/cds-interpret/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/adventure-gpt/cds-interpret/issues
+Author: adventure-gpt
+License-Expression: MIT
+License-File: LICENSE
+License-File: THIRD_PARTY.md
+Keywords: interpretability,mechanistic-interpretability,probing,pytorch,reinforcement-learning,rlbot,rlgym,rocket-league,rocketsim,sparse-autoencoder
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+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 :: Artificial Intelligence
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: numpy>=1.24
+Requires-Dist: torch>=2.1
+Provides-Extra: all
+Requires-Dist: rlbot>=2.0.0b54; extra == 'all'
+Requires-Dist: rlgym-api>=2.0; (python_version < '3.13') and extra == 'all'
+Requires-Dist: rlgym-rocket-league[sim]>=2.0; (python_version < '3.13') and extra == 'all'
+Requires-Dist: rocketsim>=2.1; extra == 'all'
+Provides-Extra: rlbot
+Requires-Dist: rlbot>=2.0.0b54; extra == 'rlbot'
+Provides-Extra: rlgym
+Requires-Dist: rlgym-api>=2.0; (python_version < '3.13') and extra == 'rlgym'
+Requires-Dist: rlgym-rocket-league[sim]>=2.0; (python_version < '3.13') and extra == 'rlgym'
+Provides-Extra: sim
+Requires-Dist: rocketsim>=2.1; extra == 'sim'
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="assets/banner.png" alt="Cat Distribution System - with an interpretability toolkit" width="100%">
+</p>
+
+# CDS-interpret
+
+**See what your Rocket League bot is thinking.**
+
+Your bot's brain is a neural network: thousands of numbers that somehow turn into saves, shots and demos. CDS-interpret
+lets you look inside it. You can ask it questions ("does it know the ball is about to go in my goal?"), find the ideas
+it has learned on its own, switch one off to see what changes - and watch all of it live, on screen, while it plays.
+
+<p align="center">
+  <img src="assets/overlay-panel.svg" alt="The thoughts panel: outlook, next move, what it is noticing, and a few readings" width="300">
+  <br><sub>The thoughts panel, drawn in the corner of the screen during a match. (Shown here outside the game.)</sub>
+</p>
+
+CDS-interpret is the interpretability toolkit from the Cat Distribution System (CDS), published on its own while the
+bigger CDS framework is still being finished. It works with **any bot whose brain is a PyTorch network** - one trained
+with RLGym (the Python toolkit most Rocket League bots are trained with), rlgym-ppo, a C++ trainer whose network you
+can load into PyTorch, or your own code - and shows its thoughts live in RLBot, the framework that runs bots in the
+real game. It runs on an ordinary CPU; no GPU needed.
+
+## Try it in five minutes
+
+You need Python 3.11 or newer. The first install also downloads PyTorch, which takes a while; the five minutes start
+after that.
+
+```bash
+python -m venv .venv
+.venv\Scripts\activate            # on macOS / Linux: source .venv/bin/activate
+pip install "cds-interpret[rlgym,rlbot] @ git+https://github.com/adventure-gpt/cds-interpret"
+cds-interpret demo
+```
+
+(On Linux, pip picks PyTorch's GPU build, several GB. For the small CPU build, run
+`pip install torch --index-url https://download.pytorch.org/whl/cpu` before the line above.)
+
+The demo takes a tiny built-in bot, records a few games of it in RocketSim (a fast Rocket League simulator), and
+looks inside it. In a few minutes you'll see something like this:
+
+```text
+Step 2 of 4 - asking every layer questions about the game (probes)
+  concept                            layer      score  input  random  measure steady
+  Worked out by the network (at least 0.05 better than both):
+  ball_dist (distance to the ball)   body.1      0.89  -0.04    0.50  R2      yes
+  ...
+Step 4 of 4 - switching ideas off to see whether the bot uses them (edits)
+  'goal_side' probe direction removed at body.3: the bot's choice changes on 15% of moments (KL 0.125)
+  a random direction removed at body.3 (the control; 3 tries): the bot's choice changes on 10% of moments (KL 0.022)
+  ...
+All done. The full picture - every probe, the features with their moments drawn on the field, the edits - is in
+cds-demo\report.html
+```
+
+How to read it: each row asks the bot one question, here "how far away is the ball?". **score** is how well its best
+layer answers, on games it never learned from (for a number that's R2: 0 is a guess, 1 perfect; for a yes / no
+question, AUROC: 0.5 is a guess, 1 perfect). **input** and **random** ask the same question of the bot's raw input and
+of a copy of the network with random weights - so 0.89 against -0.04 and 0.50 means the network worked the distance
+out for itself. In step 4, **KL** measures how far the bot's choices moved when an idea was switched off (0 is not at
+all): removing the "goal side" direction moves them about six times as much as removing a random one.
+
+Open `cds-demo/report.html` in your browser. It shows what the bot knows, the ideas it uses, and moments from its games
+drawn from above.
+
+On Python 3.13, leave out `rlgym` (`pip install "cds-interpret[rlbot] @ git+..."`): RLGym doesn't support 3.13 yet,
+so the demo uses random game moments instead of recorded games. Everything else works.
+
+## Then on your own bot
+
+Tell the toolkit three things about your bot: its network, how it builds its input from the game, and its list of
+actions.
+
+```python
+import cds_interpret as ci
+
+policy = ci.Policy(
+    my_network,                       # your torch.nn.Module
+    obs=my_obs,                       # my_obs(frames, me): your bot's input, built from the game state
+    actions=ci.lookup_table(),        # the controls behind each action number (or your bot's own table)
+)
+moments = ci.record.rocketsim(policy, games=20, seconds=120)   # watch it play 20 games
+study = ci.Study(policy, moments)
+print(study.probes().summary())       # what each layer knows
+study.report("my-bot.html")           # everything, on one page
+```
+
+Don't want to write `my_obs`? Record your bot in the real game instead; the recorder keeps the exact inputs your
+network saw. The [quickstart](docs/quickstart.md) walks through both ways, step by step.
+
+## What you can do with it
+
+- **Ask your bot questions.** A *probe* is a small readout that asks the network one question, like "will the ball
+  land near me?" or "am I first to the ball?". The toolkit asks dozens of them at every layer, scores the answers on
+  games it never trained on, and asks the same of the bot's raw input and of a random copy of the network - so you
+  learn what the network *worked out*, not what was already in its input.
+- **Find the ideas it uses.** A *sparse autoencoder* is a tool that finds the separate ideas a network uses - one for
+  "lined up for a shot", another for "about to lose the ball". The toolkit suggests a name for each idea from the
+  game, draws its strongest moments on the field, and keeps your confirmed names in a small names file.
+  [Name your bot's features](docs/howto/name-features.md).
+- **Check that it really uses them.** Switch an idea off, or turn it up, and see what the bot does differently - on
+  recorded moments, or over whole games with a proper error bar.
+- **Watch it think, live.** Wrap your RLBot bot in one line and its thoughts appear on screen while it plays: its
+  outlook, its next move and how sure it is, what it is noticing, where it thinks the ball will land. It reads your
+  network without changing it, so your bot plays exactly the same.
+- **Design your own panel.** Pick the rows, names, colours, size and position in a small TOML file, or draw your own
+  rows in Python. [Customize the panel](docs/howto/customize-the-panel.md).
+- **Record games three ways.** In RocketSim against itself or a scripted opponent, in the real game through RLBot, or
+  in your own RLGym environment.
+- **See what a decision rests on.** Was it the ball, its own car or the opponent? Which of its ideas tipped it?
+  Shapley values - a fair way of splitting credit between things that act together - say, with a score for how far
+  to trust the answer.
+  [See what a decision rests on](docs/howto/what-decisions-rest-on.md).
+- **See what your bot learns between checkpoints.** What each new checkpoint picked up, in its habits and in its
+  choices on the same moments; how healthy its layers are; and which situations it should practise next.
+  [Follow a bot through training](docs/howto/track-training.md).
+- **Check your tools.** Every technique has a quiet way to mislead; the toolkit measures each one - autoencoders
+  true to the bot's choices, features that a second run finds again, probes the bot really uses, and panel readings
+  whose 40% really means 40%.
+  [Check your tools](docs/howto/check-your-tools.md).
+- **Share what you find.** Every study becomes one HTML page with charts and field drawings, light and dark.
+
+## Documentation
+
+| | |
+|---|---|
+| [Quickstart](docs/quickstart.md) | five minutes on the demo bot, then your own |
+| [How it works](docs/concepts.md) | the ideas behind it, in plain words |
+| [Bring your own bot](docs/howto/bring-your-own-policy.md) | wrapping any network: actor-critics, TorchScript, RLGym observations |
+| [Record games](docs/howto/record-moments.md) | RocketSim, the real game, your RLGym env, your own data |
+| [Ask questions with probes](docs/howto/probes.md) | probing layers, and probes steady enough to show live |
+| [Find the ideas it uses](docs/howto/sae-features.md) | sparse autoencoders and their features |
+| [Name your bot's features](docs/howto/name-features.md) | from numbers to names you trust, end to end |
+| [Test what it relies on](docs/howto/causal-tests.md) | switching ideas off and up, in moments and in games |
+| [See what a decision rests on](docs/howto/what-decisions-rest-on.md) | the ball, its car, the opponents; and what each feature does |
+| [Check your tools](docs/howto/check-your-tools.md) | how to tell when a technique is misleading you |
+| [Watch it think in RLBot](docs/howto/overlay.md) | the live thoughts overlay |
+| [Customize the panel](docs/howto/customize-the-panel.md) | every option of the panel's TOML file, and Python hooks |
+| [Reports and drawings](docs/howto/figures.md) | the HTML page, its sections, the drawings |
+| [See what it learns between checkpoints](docs/howto/track-training.md) | checkpoint after checkpoint, and what to practise next |
+| [Labels](docs/labels.md) | every game-state fact the toolkit works out, and adding your own |
+| [Coming from rlgym-ppo or GigaLearn](docs/coming-from.md) | where the things you know fit |
+| [API reference](docs/api.md) | every function and class |
+| [When something goes wrong](docs/troubleshooting.md) | error messages and what to do |
+
+## Contributing
+
+New techniques, labels, recorders, fixes and docs are all welcome. [CONTRIBUTING.md](CONTRIBUTING.md) explains where
+new things slot in. Changes are listed in [CHANGELOG.md](CHANGELOG.md).
+
+## License
+
+MIT - see [LICENSE](LICENSE). The libraries it uses keep their own licenses: see [THIRD_PARTY.md](THIRD_PARTY.md).
+Rocket League is a trademark of Psyonix. This project is not affiliated with Psyonix, Epic Games, RLBot or RLGym.

cds_interpret-0.1.0/README.md

@@ -0,0 +1,154 @@
+<p align="center">
+  <img src="assets/banner.png" alt="Cat Distribution System - with an interpretability toolkit" width="100%">
+</p>
+
+# CDS-interpret
+
+**See what your Rocket League bot is thinking.**
+
+Your bot's brain is a neural network: thousands of numbers that somehow turn into saves, shots and demos. CDS-interpret
+lets you look inside it. You can ask it questions ("does it know the ball is about to go in my goal?"), find the ideas
+it has learned on its own, switch one off to see what changes - and watch all of it live, on screen, while it plays.
+
+<p align="center">
+  <img src="assets/overlay-panel.svg" alt="The thoughts panel: outlook, next move, what it is noticing, and a few readings" width="300">
+  <br><sub>The thoughts panel, drawn in the corner of the screen during a match. (Shown here outside the game.)</sub>
+</p>
+
+CDS-interpret is the interpretability toolkit from the Cat Distribution System (CDS), published on its own while the
+bigger CDS framework is still being finished. It works with **any bot whose brain is a PyTorch network** - one trained
+with RLGym (the Python toolkit most Rocket League bots are trained with), rlgym-ppo, a C++ trainer whose network you
+can load into PyTorch, or your own code - and shows its thoughts live in RLBot, the framework that runs bots in the
+real game. It runs on an ordinary CPU; no GPU needed.
+
+## Try it in five minutes
+
+You need Python 3.11 or newer. The first install also downloads PyTorch, which takes a while; the five minutes start
+after that.
+
+```bash
+python -m venv .venv
+.venv\Scripts\activate            # on macOS / Linux: source .venv/bin/activate
+pip install "cds-interpret[rlgym,rlbot] @ git+https://github.com/adventure-gpt/cds-interpret"
+cds-interpret demo
+```
+
+(On Linux, pip picks PyTorch's GPU build, several GB. For the small CPU build, run
+`pip install torch --index-url https://download.pytorch.org/whl/cpu` before the line above.)
+
+The demo takes a tiny built-in bot, records a few games of it in RocketSim (a fast Rocket League simulator), and
+looks inside it. In a few minutes you'll see something like this:
+
+```text
+Step 2 of 4 - asking every layer questions about the game (probes)
+  concept                            layer      score  input  random  measure steady
+  Worked out by the network (at least 0.05 better than both):
+  ball_dist (distance to the ball)   body.1      0.89  -0.04    0.50  R2      yes
+  ...
+Step 4 of 4 - switching ideas off to see whether the bot uses them (edits)
+  'goal_side' probe direction removed at body.3: the bot's choice changes on 15% of moments (KL 0.125)
+  a random direction removed at body.3 (the control; 3 tries): the bot's choice changes on 10% of moments (KL 0.022)
+  ...
+All done. The full picture - every probe, the features with their moments drawn on the field, the edits - is in
+cds-demo\report.html
+```
+
+How to read it: each row asks the bot one question, here "how far away is the ball?". **score** is how well its best
+layer answers, on games it never learned from (for a number that's R2: 0 is a guess, 1 perfect; for a yes / no
+question, AUROC: 0.5 is a guess, 1 perfect). **input** and **random** ask the same question of the bot's raw input and
+of a copy of the network with random weights - so 0.89 against -0.04 and 0.50 means the network worked the distance
+out for itself. In step 4, **KL** measures how far the bot's choices moved when an idea was switched off (0 is not at
+all): removing the "goal side" direction moves them about six times as much as removing a random one.
+
+Open `cds-demo/report.html` in your browser. It shows what the bot knows, the ideas it uses, and moments from its games
+drawn from above.
+
+On Python 3.13, leave out `rlgym` (`pip install "cds-interpret[rlbot] @ git+..."`): RLGym doesn't support 3.13 yet,
+so the demo uses random game moments instead of recorded games. Everything else works.
+
+## Then on your own bot
+
+Tell the toolkit three things about your bot: its network, how it builds its input from the game, and its list of
+actions.
+
+```python
+import cds_interpret as ci
+
+policy = ci.Policy(
+    my_network,                       # your torch.nn.Module
+    obs=my_obs,                       # my_obs(frames, me): your bot's input, built from the game state
+    actions=ci.lookup_table(),        # the controls behind each action number (or your bot's own table)
+)
+moments = ci.record.rocketsim(policy, games=20, seconds=120)   # watch it play 20 games
+study = ci.Study(policy, moments)
+print(study.probes().summary())       # what each layer knows
+study.report("my-bot.html")           # everything, on one page
+```
+
+Don't want to write `my_obs`? Record your bot in the real game instead; the recorder keeps the exact inputs your
+network saw. The [quickstart](docs/quickstart.md) walks through both ways, step by step.
+
+## What you can do with it
+
+- **Ask your bot questions.** A *probe* is a small readout that asks the network one question, like "will the ball
+  land near me?" or "am I first to the ball?". The toolkit asks dozens of them at every layer, scores the answers on
+  games it never trained on, and asks the same of the bot's raw input and of a random copy of the network - so you
+  learn what the network *worked out*, not what was already in its input.
+- **Find the ideas it uses.** A *sparse autoencoder* is a tool that finds the separate ideas a network uses - one for
+  "lined up for a shot", another for "about to lose the ball". The toolkit suggests a name for each idea from the
+  game, draws its strongest moments on the field, and keeps your confirmed names in a small names file.
+  [Name your bot's features](docs/howto/name-features.md).
+- **Check that it really uses them.** Switch an idea off, or turn it up, and see what the bot does differently - on
+  recorded moments, or over whole games with a proper error bar.
+- **Watch it think, live.** Wrap your RLBot bot in one line and its thoughts appear on screen while it plays: its
+  outlook, its next move and how sure it is, what it is noticing, where it thinks the ball will land. It reads your
+  network without changing it, so your bot plays exactly the same.
+- **Design your own panel.** Pick the rows, names, colours, size and position in a small TOML file, or draw your own
+  rows in Python. [Customize the panel](docs/howto/customize-the-panel.md).
+- **Record games three ways.** In RocketSim against itself or a scripted opponent, in the real game through RLBot, or
+  in your own RLGym environment.
+- **See what a decision rests on.** Was it the ball, its own car or the opponent? Which of its ideas tipped it?
+  Shapley values - a fair way of splitting credit between things that act together - say, with a score for how far
+  to trust the answer.
+  [See what a decision rests on](docs/howto/what-decisions-rest-on.md).
+- **See what your bot learns between checkpoints.** What each new checkpoint picked up, in its habits and in its
+  choices on the same moments; how healthy its layers are; and which situations it should practise next.
+  [Follow a bot through training](docs/howto/track-training.md).
+- **Check your tools.** Every technique has a quiet way to mislead; the toolkit measures each one - autoencoders
+  true to the bot's choices, features that a second run finds again, probes the bot really uses, and panel readings
+  whose 40% really means 40%.
+  [Check your tools](docs/howto/check-your-tools.md).
+- **Share what you find.** Every study becomes one HTML page with charts and field drawings, light and dark.
+
+## Documentation
+
+| | |
+|---|---|
+| [Quickstart](docs/quickstart.md) | five minutes on the demo bot, then your own |
+| [How it works](docs/concepts.md) | the ideas behind it, in plain words |
+| [Bring your own bot](docs/howto/bring-your-own-policy.md) | wrapping any network: actor-critics, TorchScript, RLGym observations |
+| [Record games](docs/howto/record-moments.md) | RocketSim, the real game, your RLGym env, your own data |
+| [Ask questions with probes](docs/howto/probes.md) | probing layers, and probes steady enough to show live |
+| [Find the ideas it uses](docs/howto/sae-features.md) | sparse autoencoders and their features |
+| [Name your bot's features](docs/howto/name-features.md) | from numbers to names you trust, end to end |
+| [Test what it relies on](docs/howto/causal-tests.md) | switching ideas off and up, in moments and in games |
+| [See what a decision rests on](docs/howto/what-decisions-rest-on.md) | the ball, its car, the opponents; and what each feature does |
+| [Check your tools](docs/howto/check-your-tools.md) | how to tell when a technique is misleading you |
+| [Watch it think in RLBot](docs/howto/overlay.md) | the live thoughts overlay |
+| [Customize the panel](docs/howto/customize-the-panel.md) | every option of the panel's TOML file, and Python hooks |
+| [Reports and drawings](docs/howto/figures.md) | the HTML page, its sections, the drawings |
+| [See what it learns between checkpoints](docs/howto/track-training.md) | checkpoint after checkpoint, and what to practise next |
+| [Labels](docs/labels.md) | every game-state fact the toolkit works out, and adding your own |
+| [Coming from rlgym-ppo or GigaLearn](docs/coming-from.md) | where the things you know fit |
+| [API reference](docs/api.md) | every function and class |
+| [When something goes wrong](docs/troubleshooting.md) | error messages and what to do |
+
+## Contributing
+
+New techniques, labels, recorders, fixes and docs are all welcome. [CONTRIBUTING.md](CONTRIBUTING.md) explains where
+new things slot in. Changes are listed in [CHANGELOG.md](CHANGELOG.md).
+
+## License
+
+MIT - see [LICENSE](LICENSE). The libraries it uses keep their own licenses: see [THIRD_PARTY.md](THIRD_PARTY.md).
+Rocket League is a trademark of Psyonix. This project is not affiliated with Psyonix, Epic Games, RLBot or RLGym.

cds_interpret-0.1.0/THIRD_PARTY.md

@@ -0,0 +1,33 @@
+# Third-party software and notices
+
+cds-interpret's own code, documentation and demo weights are under the MIT license (`LICENSE`, copyright
+adventure-gpt). No third-party code is carried in this repository. The projects below are dependencies installed by
+pip (or by you), each under its own license, and nothing of theirs is redistributed here.
+
+## Dependencies
+
+| project | license | used for | installed by |
+|---|---|---|---|
+| [PyTorch](https://pytorch.org) | BSD-3-Clause | networks, hooks, sparse autoencoders | always |
+| [NumPy](https://numpy.org) | BSD-3-Clause | arrays, labels, probes | always |
+| [RocketSim](https://github.com/ZealanL/RocketSim) (the `rocketsim` Python package) by ZealanL | MIT | recording games in a simulator | the `sim` extra |
+| [RLGym](https://rlgym.org) (`rlgym-api`, `rlgym-rocket-league`) | Apache-2.0 | the RLGym v2 bridges and the RLGym recorder; its simulator package also ships RocketSim's collision meshes | the `rlgym` extra |
+| [RLBot](https://rlbot.org) (`rlbot`, `rlbot_flatbuffers`) | MIT | the live thoughts overlay and recording in the real game | the `rlbot` extra |
+
+Development only: [pytest](https://pytest.org) (MIT), [Ruff](https://docs.astral.sh/ruff/) (MIT),
+[mypy](https://mypy-lang.org) (MIT), [Hatchling](https://hatch.pypa.io) (MIT).
+
+## Notes
+
+- **Collision meshes.** RocketSim needs Rocket League's arena collision meshes. They are game assets: this
+  repository does not carry them. Use the copy your own install of `rlgym-rocket-league` brings, or dump them from
+  your own copy of the game.
+- **Fair play.** RocketSim's author asks that it be used for machine learning and hobby projects that respect
+  Rocket League's terms of use, never to sell a playable clone, and never to cheat in online matches. The same goes
+  for anything built with this toolkit.
+- **The action table.** `cds_interpret.lookup_table()` builds a discrete action table in the layout that is common
+  across Rocket League bots; it is this project's own code. A bot trained with another table should pass that table.
+- **The demo bot.** Its network (`src/cds_interpret/demo/demo_policy.pt`) was trained by this project's
+  `scripts/train_demo_policy.py` to imitate this project's scripted player; it contains no other bot's weights.
+- Rocket League is a trademark of Psyonix, LLC. This project is not affiliated with or endorsed by Psyonix, Epic
+  Games, RLBot or RLGym.

cds_interpret-0.1.0/assets/overlay-panel.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="9 304 354 365" width="496" role="img" aria-label="The thoughts overlay's panel"><defs><linearGradient id="bg" x1="0" y1="0" x2="1" y2="1"><stop offset="0" stop-color="#3b5a7a"/><stop offset="1" stop-color="#1d2b3a"/></linearGradient></defs><rect x="9" y="304" width="354" height="365" fill="url(#bg)" rx="10"/><g font-family="Consolas, Menlo, 'DejaVu Sans Mono', monospace"><rect x="23.0" y="317.5" width="326.4" height="337.1" fill="rgb(0,0,0)" fill-opacity="0.69"/><text x="34.6" y="343.2" font-size="20.4" text-anchor="start" fill="rgb(255,255,255)">DEMO BOT&#x27;S MIND</text><text x="34.6" y="375.1" font-size="17.0" text-anchor="start" fill="rgb(215,215,215)">Outlook</text><text x="337.9" y="375.1" font-size="17.0" text-anchor="end" fill="rgb(90,220,120)">good</text><rect x="34.6" y="389.3" width="303.4" height="9.7" fill="rgb(70,70,70)" fill-opacity="0.86"/><rect x="186.2" y="389.3" width="83.4" height="9.7" fill="rgb(90,220,120)" fill-opacity="1.00"/><rect x="184.7" y="386.1" width="3.1" height="16.2" fill="rgb(255,255,255)" fill-opacity="1.00"/><text x="34.6" y="426.1" font-size="17.0" text-anchor="start" fill="rgb(215,215,215)">Next move</text><text x="337.9" y="426.1" font-size="17.0" text-anchor="end" fill="rgb(255,255,255)">81%</text><text x="49.9" y="454.2" font-size="17.0" text-anchor="start" fill="rgb(255,255,255)">throttle, steer right, boost</text><text x="34.6" y="487.9" font-size="17.0" text-anchor="start" fill="rgb(215,215,215)">Noticing</text><text x="42.2" y="515.9" font-size="17.0" text-anchor="start" fill="rgb(255,196,64)">&gt; lined up for a shot</text><text x="34.6" y="549.6" font-size="17.0" text-anchor="start" fill="rgb(215,215,215)">Threat on goal</text><text x="337.9" y="549.6" font-size="17.0" text-anchor="end" fill="rgb(255,255,255)">8%</text><rect x="34.6" y="563.9" width="303.4" height="9.7" fill="rgb(70,70,70)" fill-opacity="0.86"/><rect x="34.6" y="563.9" width="24.3" height="9.7" fill="rgb(240,90,80)" fill-opacity="1.00"/><text x="34.6" y="595.0" font-size="17.0" text-anchor="start" fill="rgb(215,215,215)">First to the ball</text><text x="337.9" y="595.0" font-size="17.0" text-anchor="end" fill="rgb(255,255,255)">74%</text><rect x="34.6" y="609.2" width="303.4" height="9.7" fill="rgb(70,70,70)" fill-opacity="0.86"/><rect x="34.6" y="609.2" width="224.5" height="9.7" fill="rgb(90,220,120)" fill-opacity="1.00"/><text x="34.6" y="640.3" font-size="17.0" text-anchor="start" fill="rgb(215,215,215)">Time to the ball</text><text x="337.9" y="640.3" font-size="17.0" text-anchor="end" fill="rgb(255,255,255)">0.9 s</text></g></svg>