loop-autopsy 0.1.0__tar.gz

loop_autopsy-0.1.0/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 NATHANAEL George Steindhart, SETIAWAN Matthew Henson,
+LATHIF Muhammad Akmal, KWAN Kendrick Matthew, HANDAYA Clement Steward
+
+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.

loop_autopsy-0.1.0/PKG-INFO

@@ -0,0 +1,230 @@
+Metadata-Version: 2.4
+Name: loop-autopsy
+Version: 0.1.0
+Summary: Stops runaway loops in Jupyter and shows the evidence for why they never ended.
+Author: NATHANAEL George Steindhart, SETIAWAN Matthew Henson, LATHIF Muhammad Akmal, KWAN Kendrick Matthew, HANDAYA Clement Steward
+License: MIT
+Project-URL: Homepage, https://github.com/Geoeoeo217/loop-autopsy
+Project-URL: Repository, https://github.com/Geoeoeo217/loop-autopsy
+Project-URL: Documentation, https://github.com/Geoeoeo217/loop-autopsy#readme
+Keywords: jupyter,ipython,education,infinite-loop,debugging,beginners
+Classifier: Framework :: IPython
+Classifier: Framework :: Jupyter
+Classifier: Intended Audience :: Education
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Education
+Classifier: Topic :: Software Development :: Debuggers
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: ipython>=7.0
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Dynamic: license-file
+
+# loop-autopsy
+
+**Stops runaway loops in Jupyter and shows the evidence for why they never ended.**
+
+```python
+%load_ext loop_autopsy
+
+count = 1
+while count <= 5:
+    print(count)
+```
+
+Instead of freezing the notebook, the loop is stopped after 3 rounds and you get:
+
+![A loop-autopsy report for a stuck loop](https://raw.githubusercontent.com/Geoeoeo217/loop-autopsy/main/docs/report.png)
+
+```
+Loop autopsy — stuck loop (line 2)
+    while count <= 5:
+
+Nothing changed between rounds: `count = 1` stayed exactly the same, so the
+condition `count <= 5` is True every time and the loop can never end.
+
+Last rounds checked:
+round  count (same)
+-----  ------------
+1      1
+2      1
+3      1
+
+Hint: Add a line inside the loop that changes `count` so that `count <= 5`
+eventually becomes False (for example `count += 1`).
+```
+
+---
+
+## Motivation
+
+Every beginner writes an infinite loop. In a notebook on a shared JupyterHub this
+is worse than it sounds:
+
+- the cell hangs with no explanation, and the only remedy is the stop button ■;
+- a `print` inside the loop floods the browser with output until the tab freezes;
+- the loop keeps using CPU and memory on a server shared by the whole class.
+
+Pressing ■ stops the loop but teaches nothing. The student still does not know
+*which* variable failed to change or *why* the condition never became False.
+
+## Innovation
+
+loop-autopsy watches loops **while they run** and stops them only when it can
+**prove** they will never end. Then it shows the evidence.
+
+| | Stops a stuck loop? | Explains *why*? | When? |
+|---|---|---|---|
+| Stop button ■ | yes (you press it) | no | whenever you notice |
+| Timeout decorators (e.g. `wrapt_timeout_decorator`) | yes, after a fixed time | no | after the time limit |
+| Error explainers (e.g. `friendly-traceback`) | no | explains *errors*, but an infinite loop raises none | after a crash |
+| Memory monitors (e.g. `jupyter-resource-usage`) | no | no | shows totals only |
+| **loop-autopsy** | **yes, automatically** | **yes, with a replay table** | **during the loop, often after 3 rounds** |
+
+How it works, in short:
+
+1. An IPython **AST transformer** (it edits the code's syntax tree before it runs)
+   adds a tiny check to every `while` and `for` loop you type in a cell.
+2. Each check takes a **fingerprint** of the loop's variables. If a deterministic
+   loop comes back to an *exactly identical* state, it must repeat forever: that
+   is a proof, not a guess.
+3. Further rules catch a counter moving *away* from its target, a `!=` condition
+   that jumps over its stop value (`0.1 + 0.1 + ...` never equals `1.0`), a list
+   that grows while you loop over it, and memory running out.
+4. Anything it cannot prove falls back to an honest time limit. No AI model, no
+   internet, and the same result every time.
+
+Every rule and its numbers are listed below, and every number can be changed (see Settings).
+
+## What it detects
+
+| Pattern | Example | Stopped after |
+|---|---|---|
+| **Stuck**: nothing changes | `while count <= 5: print(count)` | 3 rounds |
+| **Cycle**: values go round in a circle | `while a < 5: a = (a + 1) % 3` | about 2 cycles |
+| **Wrong direction** | `while i < 10: i -= 1` | 500 checks |
+| **Jumped over** the stop value | `while x != 1.0: x += 0.1` | about 100 checks |
+| **Growing list** in a `for` loop | `for n in nums: nums.append(n)` | 2,000 rounds |
+| **Memory** about to run out | a loop filling a huge list | at 85% of the limit |
+| **Too long** (fallback) | anything else | 60 s |
+
+Plus two extras:
+
+- **Press ■ yourself** and you still get the replay table, showing which
+  variables never changed.
+- **Cell health bar**: time, memory and loops for a cell, coloured green / yellow /
+  red. It warns when memory passes 75% of your limit and names the biggest
+  variables (pandas and NumPy aware). It also mutes output after 1,000 printed
+  lines so the browser stays responsive.
+
+## Example use cases
+
+- **Students** in an intro course: load it once at the top of every notebook and
+  never lose a session to a frozen loop again.
+- **Instructors** on JupyterHub: load it for everyone (see below) to protect the
+  shared server and turn every infinite loop into a mini-lesson.
+- **Teaching assistants**: the replay table shows at a glance what went wrong in
+  a student's loop.
+- **Data notebooks**: the health bar shows which cell is slow or memory-hungry.
+
+## Setup
+
+```bash
+pip install loop-autopsy
+```
+
+The only requirement is IPython (already present in Jupyter). Python 3.9+.
+
+In a notebook:
+
+```python
+%load_ext loop_autopsy
+```
+
+**For instructors**: to turn it on for every notebook, add this to the IPython
+profile (`~/.ipython/profile_default/ipython_config.py`):
+
+```python
+c.InteractiveShellApp.extensions = ["loop_autopsy"]
+```
+
+## Usage
+
+| Command | Effect |
+|---|---|
+| `%autopsy` | status and settings |
+| `%autopsy on` / `off` | start / stop watching loops |
+| `%autopsy last` | show the last report again |
+| `%autopsy heatmap on` / `off` / `auto` | cell health bar (`auto` = only when a cell is slow or memory-heavy) |
+| `%autopsy config time_limit=120` | change a setting (see Settings below) |
+| `%%autopsy off` | first line of a cell: run that cell without watching |
+| `%autopsy help` | help |
+
+Cells that use `%timeit` / `%%timeit` are never watched, so timings stay accurate.
+Loops inside generators (`yield`) are left alone, because infinite generators are
+normal.
+
+Try [examples/demo.ipynb](examples/demo.ipynb) for every feature in one notebook.
+
+## Settings
+
+Change any of these with `%autopsy config key=value` (for example `%autopsy config time_limit=120`).
+
+| Setting | Default | Meaning |
+|---|---|---|
+| `time_limit` | 60 | seconds before a loop that cannot be proven stuck is stopped (0 = never) |
+| `direction_after` | 500 | checks in a row moving away from the stop value before "wrong direction" |
+| `jump_after` | 100 | checks in a row after jumping over a `!=` stop value |
+| `growth_after` | 2000 | rounds before a growing list in a `for` loop is reported |
+| `memory_stop` | 0.85 | stop a loop when memory reaches this fraction of the limit |
+| `memory_warn` | 0.75 | health bar warning at this fraction of the limit |
+| `max_output_lines` | 1000 | printed lines per cell before output is muted (0 = off) |
+| `replay_rows` | 6 | rows in the replay table |
+| `max_watched` | 25 | variables watched per loop |
+| `heatmap` | `auto` | `on`, `off` or `auto` |
+| `time_yellow` / `time_red` | 1.0 / 10.0 | seconds for a yellow / red health bar |
+| `mem_yellow` / `mem_red` | 0.50 / 0.80 | memory fraction for a yellow / red health bar |
+
+The memory limit is read from JupyterHub's `MEM_LIMIT` setting, then the container's
+memory limit, then the computer's total RAM.
+
+## Limitations (honest list)
+
+- No tool can detect *every* infinite loop (the halting problem). loop-autopsy
+  only reports a stuck, cycling, wrong-direction or jumped-over loop when it can
+  prove it; everything else gets the time limit.
+- Loops that call your own functions or modules such as `random` cannot be proven
+  stuck (those calls might change hidden state), so they rely on the time limit.
+- Only code typed in notebook cells is watched, not code inside imported modules.
+- Watching adds a small cost to each loop round (roughly 0.1–0.2 µs per round on
+  simple loops). Use `%%autopsy off` for heavy number crunching.
+- A bare `except:` inside a loop can catch the stop signal, just as it catches ■.
+
+## Development
+
+```bash
+git clone https://github.com/Geoeoeo217/loop-autopsy
+cd loop-autopsy
+pip install -e ".[test]"
+pytest
+```
+
+## Team
+
+Built by a team of five for CS1302 (Introduction to Computer Programming).
+
+| Member | Part |
+|---|---|
+| NATHANAEL George Steindhart | project lead: loop rewriting (`transformer.py`), run-time glue (`monitor.py`), magics, packaging |
+| SETIAWAN Matthew Henson | detection rules: stuck, cycle, wrong direction, jumped over, time limit (`detectors.py`) |
+| LATHIF Muhammad Akmal | memory and growing-list rules (`growth.py`) |
+| KWAN Kendrick Matthew | replay table and reports (`report.py`) |
+| HANDAYA Clement Steward | cell health bar and output guard (`heatmap.py`) |
+
+
+## License
+
+MIT

loop_autopsy-0.1.0/README.md

@@ -0,0 +1,205 @@
+# loop-autopsy
+
+**Stops runaway loops in Jupyter and shows the evidence for why they never ended.**
+
+```python
+%load_ext loop_autopsy
+
+count = 1
+while count <= 5:
+    print(count)
+```
+
+Instead of freezing the notebook, the loop is stopped after 3 rounds and you get:
+
+![A loop-autopsy report for a stuck loop](https://raw.githubusercontent.com/Geoeoeo217/loop-autopsy/main/docs/report.png)
+
+```
+Loop autopsy — stuck loop (line 2)
+    while count <= 5:
+
+Nothing changed between rounds: `count = 1` stayed exactly the same, so the
+condition `count <= 5` is True every time and the loop can never end.
+
+Last rounds checked:
+round  count (same)
+-----  ------------
+1      1
+2      1
+3      1
+
+Hint: Add a line inside the loop that changes `count` so that `count <= 5`
+eventually becomes False (for example `count += 1`).
+```
+
+---
+
+## Motivation
+
+Every beginner writes an infinite loop. In a notebook on a shared JupyterHub this
+is worse than it sounds:
+
+- the cell hangs with no explanation, and the only remedy is the stop button ■;
+- a `print` inside the loop floods the browser with output until the tab freezes;
+- the loop keeps using CPU and memory on a server shared by the whole class.
+
+Pressing ■ stops the loop but teaches nothing. The student still does not know
+*which* variable failed to change or *why* the condition never became False.
+
+## Innovation
+
+loop-autopsy watches loops **while they run** and stops them only when it can
+**prove** they will never end. Then it shows the evidence.
+
+| | Stops a stuck loop? | Explains *why*? | When? |
+|---|---|---|---|
+| Stop button ■ | yes (you press it) | no | whenever you notice |
+| Timeout decorators (e.g. `wrapt_timeout_decorator`) | yes, after a fixed time | no | after the time limit |
+| Error explainers (e.g. `friendly-traceback`) | no | explains *errors*, but an infinite loop raises none | after a crash |
+| Memory monitors (e.g. `jupyter-resource-usage`) | no | no | shows totals only |
+| **loop-autopsy** | **yes, automatically** | **yes, with a replay table** | **during the loop, often after 3 rounds** |
+
+How it works, in short:
+
+1. An IPython **AST transformer** (it edits the code's syntax tree before it runs)
+   adds a tiny check to every `while` and `for` loop you type in a cell.
+2. Each check takes a **fingerprint** of the loop's variables. If a deterministic
+   loop comes back to an *exactly identical* state, it must repeat forever: that
+   is a proof, not a guess.
+3. Further rules catch a counter moving *away* from its target, a `!=` condition
+   that jumps over its stop value (`0.1 + 0.1 + ...` never equals `1.0`), a list
+   that grows while you loop over it, and memory running out.
+4. Anything it cannot prove falls back to an honest time limit. No AI model, no
+   internet, and the same result every time.
+
+Every rule and its numbers are listed below, and every number can be changed (see Settings).
+
+## What it detects
+
+| Pattern | Example | Stopped after |
+|---|---|---|
+| **Stuck**: nothing changes | `while count <= 5: print(count)` | 3 rounds |
+| **Cycle**: values go round in a circle | `while a < 5: a = (a + 1) % 3` | about 2 cycles |
+| **Wrong direction** | `while i < 10: i -= 1` | 500 checks |
+| **Jumped over** the stop value | `while x != 1.0: x += 0.1` | about 100 checks |
+| **Growing list** in a `for` loop | `for n in nums: nums.append(n)` | 2,000 rounds |
+| **Memory** about to run out | a loop filling a huge list | at 85% of the limit |
+| **Too long** (fallback) | anything else | 60 s |
+
+Plus two extras:
+
+- **Press ■ yourself** and you still get the replay table, showing which
+  variables never changed.
+- **Cell health bar**: time, memory and loops for a cell, coloured green / yellow /
+  red. It warns when memory passes 75% of your limit and names the biggest
+  variables (pandas and NumPy aware). It also mutes output after 1,000 printed
+  lines so the browser stays responsive.
+
+## Example use cases
+
+- **Students** in an intro course: load it once at the top of every notebook and
+  never lose a session to a frozen loop again.
+- **Instructors** on JupyterHub: load it for everyone (see below) to protect the
+  shared server and turn every infinite loop into a mini-lesson.
+- **Teaching assistants**: the replay table shows at a glance what went wrong in
+  a student's loop.
+- **Data notebooks**: the health bar shows which cell is slow or memory-hungry.
+
+## Setup
+
+```bash
+pip install loop-autopsy
+```
+
+The only requirement is IPython (already present in Jupyter). Python 3.9+.
+
+In a notebook:
+
+```python
+%load_ext loop_autopsy
+```
+
+**For instructors**: to turn it on for every notebook, add this to the IPython
+profile (`~/.ipython/profile_default/ipython_config.py`):
+
+```python
+c.InteractiveShellApp.extensions = ["loop_autopsy"]
+```
+
+## Usage
+
+| Command | Effect |
+|---|---|
+| `%autopsy` | status and settings |
+| `%autopsy on` / `off` | start / stop watching loops |
+| `%autopsy last` | show the last report again |
+| `%autopsy heatmap on` / `off` / `auto` | cell health bar (`auto` = only when a cell is slow or memory-heavy) |
+| `%autopsy config time_limit=120` | change a setting (see Settings below) |
+| `%%autopsy off` | first line of a cell: run that cell without watching |
+| `%autopsy help` | help |
+
+Cells that use `%timeit` / `%%timeit` are never watched, so timings stay accurate.
+Loops inside generators (`yield`) are left alone, because infinite generators are
+normal.
+
+Try [examples/demo.ipynb](examples/demo.ipynb) for every feature in one notebook.
+
+## Settings
+
+Change any of these with `%autopsy config key=value` (for example `%autopsy config time_limit=120`).
+
+| Setting | Default | Meaning |
+|---|---|---|
+| `time_limit` | 60 | seconds before a loop that cannot be proven stuck is stopped (0 = never) |
+| `direction_after` | 500 | checks in a row moving away from the stop value before "wrong direction" |
+| `jump_after` | 100 | checks in a row after jumping over a `!=` stop value |
+| `growth_after` | 2000 | rounds before a growing list in a `for` loop is reported |
+| `memory_stop` | 0.85 | stop a loop when memory reaches this fraction of the limit |
+| `memory_warn` | 0.75 | health bar warning at this fraction of the limit |
+| `max_output_lines` | 1000 | printed lines per cell before output is muted (0 = off) |
+| `replay_rows` | 6 | rows in the replay table |
+| `max_watched` | 25 | variables watched per loop |
+| `heatmap` | `auto` | `on`, `off` or `auto` |
+| `time_yellow` / `time_red` | 1.0 / 10.0 | seconds for a yellow / red health bar |
+| `mem_yellow` / `mem_red` | 0.50 / 0.80 | memory fraction for a yellow / red health bar |
+
+The memory limit is read from JupyterHub's `MEM_LIMIT` setting, then the container's
+memory limit, then the computer's total RAM.
+
+## Limitations (honest list)
+
+- No tool can detect *every* infinite loop (the halting problem). loop-autopsy
+  only reports a stuck, cycling, wrong-direction or jumped-over loop when it can
+  prove it; everything else gets the time limit.
+- Loops that call your own functions or modules such as `random` cannot be proven
+  stuck (those calls might change hidden state), so they rely on the time limit.
+- Only code typed in notebook cells is watched, not code inside imported modules.
+- Watching adds a small cost to each loop round (roughly 0.1–0.2 µs per round on
+  simple loops). Use `%%autopsy off` for heavy number crunching.
+- A bare `except:` inside a loop can catch the stop signal, just as it catches ■.
+
+## Development
+
+```bash
+git clone https://github.com/Geoeoeo217/loop-autopsy
+cd loop-autopsy
+pip install -e ".[test]"
+pytest
+```
+
+## Team
+
+Built by a team of five for CS1302 (Introduction to Computer Programming).
+
+| Member | Part |
+|---|---|
+| NATHANAEL George Steindhart | project lead: loop rewriting (`transformer.py`), run-time glue (`monitor.py`), magics, packaging |
+| SETIAWAN Matthew Henson | detection rules: stuck, cycle, wrong direction, jumped over, time limit (`detectors.py`) |
+| LATHIF Muhammad Akmal | memory and growing-list rules (`growth.py`) |
+| KWAN Kendrick Matthew | replay table and reports (`report.py`) |
+| HANDAYA Clement Steward | cell health bar and output guard (`heatmap.py`) |
+
+
+## License
+
+MIT

loop_autopsy-0.1.0/pyproject.toml

@@ -0,0 +1,44 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "loop-autopsy"
+version = "0.1.0"
+description = "Stops runaway loops in Jupyter and shows the evidence for why they never ended."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [
+    { name = "NATHANAEL George Steindhart" },
+    { name = "SETIAWAN Matthew Henson" },
+    { name = "LATHIF Muhammad Akmal" },
+    { name = "KWAN Kendrick Matthew" },
+    { name = "HANDAYA Clement Steward" },
+]
+keywords = ["jupyter", "ipython", "education", "infinite-loop", "debugging", "beginners"]
+classifiers = [
+    "Framework :: IPython",
+    "Framework :: Jupyter",
+    "Intended Audience :: Education",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Education",
+    "Topic :: Software Development :: Debuggers",
+]
+dependencies = ["ipython>=7.0"]
+
+[project.optional-dependencies]
+test = ["pytest"]
+
+[project.urls]
+Homepage = "https://github.com/Geoeoeo217/loop-autopsy"
+Repository = "https://github.com/Geoeoeo217/loop-autopsy"
+Documentation = "https://github.com/Geoeoeo217/loop-autopsy#readme"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["tests"]

loop_autopsy-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

loop_autopsy-0.1.0/src/loop_autopsy/__init__.py

@@ -0,0 +1,57 @@
+"""loop-autopsy: stops runaway loops in Jupyter and shows the evidence for why
+they never ended.
+
+Usage in a notebook::
+
+    %load_ext loop_autopsy
+"""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"
+
+from .config import Finding, LoopStopped, Settings  # noqa: F401
+
+_LOADED: dict = {}
+
+
+def load_ipython_extension(ip) -> None:
+    from .heatmap import CellHealth
+    from .magics import AutopsyMagics
+    from .monitor import Monitor
+    from .report import display_report
+    from .transformer import RUNTIME_NAME, LoopTransformer
+
+    if id(ip) in _LOADED:
+        print("loop-autopsy is already loaded. Use %autopsy help for options.")
+        return
+    settings = Settings()
+    monitor = Monitor(ip, settings)
+    transformer = LoopTransformer(monitor.register, lambda: settings.max_watched, monitor.is_paused)
+    health = CellHealth(ip, settings, monitor.stats, show=display_report)
+
+    ip.user_ns[RUNTIME_NAME] = monitor
+    ip.user_ns_hidden[RUNTIME_NAME] = monitor  # keep it out of %who / %whos
+    ip.ast_transformers.append(transformer)
+    ip.events.register("pre_run_cell", monitor.pre_run_cell)
+    health.register()
+    monitor.install_exception_handler()
+    ip.register_magics(AutopsyMagics(ip, monitor))
+    _LOADED[id(ip)] = (monitor, transformer, health)
+    print(f"loop-autopsy {__version__} is watching your loops. Type %autopsy help for options.")
+
+
+def unload_ipython_extension(ip) -> None:
+    entry = _LOADED.pop(id(ip), None)
+    if entry is None:
+        return
+    monitor, transformer, health = entry
+    monitor.enabled = False  # functions instrumented earlier keep working, unwatched
+    if transformer in ip.ast_transformers:
+        ip.ast_transformers.remove(transformer)
+    try:
+        ip.events.unregister("pre_run_cell", monitor.pre_run_cell)
+    except ValueError:
+        pass
+    health.unregister()
+    monitor.remove_exception_handler()

loop_autopsy-0.1.0/src/loop_autopsy/config.py

@@ -0,0 +1,109 @@
+from __future__ import annotations
+
+from collections import deque
+from dataclasses import dataclass, field, fields
+from typing import Any, Optional, Tuple
+
+
+class LoopStopped(BaseException):
+    """Raised inside a watched loop to stop it.
+
+    It derives from BaseException (like KeyboardInterrupt) so that a normal
+    ``except Exception:`` block inside the student's loop cannot swallow it.
+    """
+
+    def __init__(self, finding: "Finding"):
+        super().__init__(finding.title)
+        self.finding = finding
+
+
+@dataclass
+class Finding:
+    """What a detection rule proved about a loop."""
+
+    kind: str  # stuck | cycle | wrong_direction | jumped_over | growing_iterable | memory | time_limit
+    title: str
+    explanation: str
+    hint: str
+    culprits: Tuple[str, ...] = ()
+
+
+@dataclass
+class LoopInfo:
+    """Static facts about one loop, collected when the cell is transformed."""
+
+    loop_id: int
+    kind: str  # "while" | "for"
+    lineno: int
+    header: str
+    test_src: str = ""
+    cond_names: Tuple[str, ...] = ()
+    watched: Tuple[str, ...] = ()
+    compare: Optional[tuple] = None  # (left, op, right); side = ("name", n) | ("const", v)
+    iter_name: Optional[str] = None
+    receivers: Tuple[str, ...] = ()  # names used as ``name.method(...)``; checked at run time
+    repeat_safe: bool = True
+    waits_for_user: bool = False
+
+
+@dataclass
+class LoopState:
+    """Run-time record of one execution of a loop."""
+
+    info: LoopInfo
+    started: float
+    replay_rows: int = 6
+    rounds: int = 0
+    checks: int = 0
+    stride: int = 1
+    next_check: int = 1
+    last_check: float = 0.0
+    history: deque = field(default_factory=deque)
+    scratch: dict = field(default_factory=dict)
+    stopped: Optional[Finding] = None
+
+    def __post_init__(self):
+        self.history = deque(maxlen=max(1, self.replay_rows))
+        self.last_check = self.started
+
+
+@dataclass
+class Settings:
+    """User-adjustable settings (``%autopsy config key=value``)."""
+
+    time_limit: float = 60.0
+    direction_after: int = 500
+    jump_after: int = 100
+    growth_after: int = 2000
+    memory_stop: float = 0.85
+    memory_warn: float = 0.75
+    max_output_lines: int = 1000
+    replay_rows: int = 6
+    max_watched: int = 25
+    heatmap: str = "auto"  # on | off | auto
+    time_yellow: float = 1.0
+    time_red: float = 10.0
+    mem_yellow: float = 0.50
+    mem_red: float = 0.80
+
+    def update(self, key: str, raw: str) -> Any:
+        """Set ``key`` from a string such as ``"30"``; returns the new value."""
+        names = {f.name: f for f in fields(self)}
+        if key not in names:
+            raise KeyError(f"unknown setting {key!r}; choose from: {', '.join(names)}")
+        current = getattr(self, key)
+        if isinstance(current, str):
+            value: Any = raw.strip().strip("'\"").lower()
+            if key == "heatmap" and value not in ("on", "off", "auto"):
+                raise ValueError("heatmap must be on, off or auto")
+        elif isinstance(current, int) and not isinstance(current, bool):
+            value = int(float(raw))
+        else:
+            value = float(raw)
+        if isinstance(value, (int, float)) and value < 0:
+            raise ValueError(f"{key} cannot be negative")
+        setattr(self, key, value)
+        return value
+
+    def as_dict(self) -> dict:
+        return {f.name: getattr(self, f.name) for f in fields(self)}