SuperGLM

https://github.com/strudeldoodles/superglm
Admin
SuperGLM is a Python library for penalized generalized linear models designed for insurance pricing,...
Tokens:429,448
Snippets:4,539
Trust Score:3.4
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install SuperGLM

Source: https://github.com/strudeldoodles/superglm/blob/master/README.md

Standard installation command for the library.

```bash
pip install superglm
```

--------------------------------

### Run Frontend Guide Test

Source: https://github.com/strudeldoodles/superglm/blob/master/docs/superpowers/plans/2026-07-11-editor-integration-docs.md

Execute the focused test to verify the developer guide structure.

```bash
rtk test uv run pytest tests/test_editor.py -k frontend_guide_for_python_developers -q
```

--------------------------------

### Install optional dependencies

Source: https://github.com/strudeldoodles/superglm/blob/master/docs/getting-started/installation.md

Commands to install extra features for interactive plotting or benchmarking.

```bash
# Interactive Plotly charts
pip install "superglm[plotting]"

# Benchmarking (glum, statsmodels, pyarrow)
pip install "superglm[bench]"
```

--------------------------------

### Perform a development installation

Source: https://github.com/strudeldoodles/superglm/blob/master/docs/getting-started/installation.md

Clone the repository and sync dependencies for local development.

```bash
git clone https://github.com/StrudelDoodleS/superglm.git
cd superglm
uv sync --extra dev --extra bench --extra plotting
```

--------------------------------

### Commit documentation updates

Source: https://github.com/strudeldoodles/superglm/blob/master/docs/superpowers/plans/2026-07-26-credibility-release-safety-review.md

Stage and commit changes to the quickstart documentation if modifications were made.

```bash
rtk git add docs/getting-started/quickstart.md
rtk git commit -m "Document credibility release contracts"
```

--------------------------------

### Install Polars backend

Source: https://github.com/strudeldoodles/superglm/blob/master/docs/getting-started/installation.md

Optional installation for Polars DataFrame support.

```bash
pip install polars
```

--------------------------------

### Initialize State Module

Source: https://github.com/strudeldoodles/superglm/blob/master/docs/superpowers/plans/2026-07-26-structured-solver-package-extraction.md

Boilerplate imports and setup for the new state module.

```python
"""Retained support and linear-system state for structured fits."""

from __future__ import annotations

from dataclasses import dataclass
from typing import TYPE_CHECKING

import numpy as np
from numpy.typing import NDArray

from superglm.solvers._structured.factors import (
    BlockSchurFactor,
    ProfiledBlockSchurFactor,
    ProfiledScalarSchurFactor,
    ScalarSchurFactor,
)
from superglm.solvers._structured.moments import (
    BlockStructuredSystem,
    ScalarStructuredSystem,
    SumToZeroBlockStructuredSystem,
)
from superglm.solvers._structured.operators import (
    BlockSymmetricOperator,
    CenteredBlockOperator,
    SumToZeroBlockOperator,
    SymmetricBlockOperator,
)

if TYPE_CHECKING:
    from superglm.solvers.sum_to_zero import (
        ProfiledSumToZeroBlockFactor,
        SumToZeroBlockFactor,
    )
```

--------------------------------

### Install Playwright Dependencies

Source: https://github.com/strudeldoodles/superglm/blob/master/docs/superpowers/plans/2026-07-11-editor-refit-evidence.md

Commands to sync development dependencies and install the Chromium browser.

```bash
rtk uv sync --extra dev
rtk uv run playwright install chromium
```

--------------------------------

### Initialize Assembly Module

Source: https://github.com/strudeldoodles/superglm/blob/master/docs/superpowers/plans/2026-07-26-structured-solver-package-extraction.md

Boilerplate imports and setup for the new assembly module.

```python
"""Penalty assembly and cached solves for structured systems."""

from __future__ import annotations

from dataclasses import dataclass
from typing import TYPE_CHECKING

import numpy as np
from numpy.typing import NDArray

from superglm.group_matrix import (
    FactorSmoothGroupMatrix,
    GroupMatrix,
    RandomEffectGroupMatrix,
)
from superglm.solvers._structured.factors import (
    BlockSchurFactor,
    ProfiledBlockSchurFactor,
    ProfiledScalarSchurFactor,
    ScalarSchurFactor,
)
from superglm.solvers._structured.moments import (
    BlockStructuredSystem,
    ScalarStructuredSystem,
    SumToZeroBlockStructuredSystem,
)
from superglm.solvers._structured.operators import (
    BlockSymmetricOperator,
    SumToZeroBlockOperator,
    SymmetricBlockOperator,
)
from superglm.solvers.hessian_factor import _component_indices
from superglm.types import GroupSlice, PenaltyComponent

if TYPE_CHECKING:
    from superglm.solvers.sum_to_zero import ProfiledSumToZeroBlockFactor
```

--------------------------------

### Import required libraries and setup

Source: https://github.com/strudeldoodles/superglm/blob/master/docs/notebooks/ordered_categorical_smoothing.ipynb

Initializes necessary imports for data manipulation, plotting, and SuperGLM modeling.

```python
from pathlib import Path

import matplotlib.pyplot as plt
import numpy as np
import pandas as pd
from scipy.stats import norm

from superglm import Categorical, OrderedCategorical, Poisson, Spline, SuperGLM
from superglm.plotting.common import (
    _EXP_EDGE,
    _EXP_EDGE_LW,
    _EXP_FILL,
    _REF_COLOR,
    _REF_LW,
)

z = norm.ppf(0.975)
```

--------------------------------

### Document shorthand migration compatibility

Source: https://github.com/strudeldoodles/superglm/blob/master/docs/superpowers/plans/2026-07-26-credibility-release-safety-review.md

Use this text in the quickstart documentation to inform users about the transition from the legacy splines keyword to explicit feature specifications.

```markdown
Auto-detection remains available for compatibility, but explicit feature
specs are the canonical API. Passing the legacy `splines` keyword emits a
`FutureWarning`; calls continue to run during the 0.15 compatibility window,
including with `n_knots`, `degree`, and `categorical_base`. Warning-as-error
environments should migrate named smooths to
`features={"column": Spline(kind="ps")}` before upgrading.
```

--------------------------------

### Install Editor Dependencies

Source: https://github.com/strudeldoodles/superglm/blob/master/docs/notebooks/editor_demo.ipynb

Install the necessary development dependencies for the editor module.

```bash
uv sync --extra dev
```

--------------------------------

### Run Frontend and Browser Tests

Source: https://github.com/strudeldoodles/superglm/blob/master/docs/superpowers/plans/2026-07-11-editor-integration-docs.md

Commands to execute frontend dependency installation, unit tests, type checking, and browser-based integration tests.

```bash
rtk npm ci
rtk npm run test:frontend
rtk npm run typecheck:frontend
rtk test uv run pytest tests/test_editor_browser.py -m browser --run-browser -q
```

--------------------------------

### Document Summary Options

Source: https://github.com/strudeldoodles/superglm/blob/master/docs/superpowers/plans/2026-07-22-summary-categorical-level-display.md

Example usage of the summary method with different level display configurations.

```python
print(model.summary())                           # exact original levels, expanded
print(model.summary(level_display="grouped"))   # one row per fitted group + legend
```

--------------------------------

### SuperGLM Usage Examples

Source: https://github.com/strudeldoodles/superglm/blob/master/docs/superpowers/plans/2026-07-21-explicit-selection-penalty-and-tweedie-ci.md

Examples demonstrating explicit selection penalty configuration and CI estimation.

```python
SuperGLM()                                  # no sparse selection
SuperGLM(selection_penalty="auto")         # explicit calibration
SuperGLM(selection_penalty=0.05)           # fixed strength
model.estimate_p(X, y, ci_alpha=0.05)      # CI cached for model.summary(alpha=0.05)
```

--------------------------------

### Install unreleased development version

Source: https://github.com/strudeldoodles/superglm/blob/master/docs/getting-started/installation.md

Install the latest code directly from the GitHub repository.

```bash
pip install "superglm @ git+https://github.com/StrudelDoodleS/superglm.git"
```

--------------------------------

### Install SuperGLM with Plotting

Source: https://github.com/strudeldoodles/superglm/blob/master/README.md

Installation command including optional Plotly-based interactive chart dependencies.

```bash
pip install "superglm[plotting]"
```

--------------------------------

### Model output examples

Source: https://github.com/strudeldoodles/superglm/blob/master/docs/notebooks/ordered_categorical_smoothing.ipynb

Displays the expected output for the fitted models.

```text
B-spline:          edf = 10.4
```

```text
Cubic regression:  edf = 8.4
```

```text
Raw categorical:   18 levels
```

--------------------------------

### Run browser tests via CLI

Source: https://github.com/strudeldoodles/superglm/blob/master/docs/superpowers/plans/2026-07-11-editor-workspace-axis.md

Commands to install dependencies and execute the browser-based test suite.

```bash
rtk uv sync --extra dev
rtk uv run playwright install chromium
rtk uv run pytest tests/editor/test_editor_workspace_browser.py --run-browser -q
```

--------------------------------

### Run Documentation Content Tests

Source: https://github.com/strudeldoodles/superglm/blob/master/docs/superpowers/plans/2026-07-11-editor-integration-docs.md

Execute the test suite to validate the analyst editor guide content.

```bash
rtk test uv run pytest tests/test_editor.py -k analyst_editor_guide -q
```

--------------------------------

### SuperGLM Model Initialization

Source: https://github.com/strudeldoodles/superglm/blob/master/docs/superpowers/plans/2026-07-25-factor-smooth-sz.md

Example of initializing a SuperGLM model using the updated feature specification.

```python
model = SuperGLM(
    family="poisson",
    features={
        "DrivAge": Spline(),
        "VehAge": Spline(),
        "BonusMalus": Spline(),
    },
)
```

--------------------------------

### Initialize Spline features

Source: https://github.com/strudeldoodles/superglm/blob/master/docs/guide/features.md

Examples of initializing various spline types with different basis sizes and penalty configurations.

```python
Spline(kind="ps", k=14)                   # default P-spline choice
Spline(kind="bs", k=14)                   # integrated-derivative B-spline smooth
Spline(kind="cr", k=10)                   # cubic regression spline
Spline(kind="ns", k=10)                   # natural spline
Spline(kind="ps", k=14, select=True)      # REML + double-penalty shrinkage
Spline(kind="cr", k=12, m=(1, 2))         # multi-order penalty
```

--------------------------------

### Canonical SZ Factor Smooth Example

Source: https://github.com/strudeldoodles/superglm/blob/master/docs/superpowers/plans/2026-07-25-factor-smooth-sz.md

Demonstrates the usage of FactorSmooth with the sum-to-zero (SZ) basis.

```python
model = SuperGLM(
    family="poisson",
    features={"age": Spline(kind="ps", k=7, m=2)},
    interactions=[
        FactorSmooth("age", group="region", basis="sz", kind="ps", k=6, m=2)
    ],
).fit_reml(X, y)
```

--------------------------------

### Implement Fit State Primitives

Source: https://github.com/strudeldoodles/superglm/blob/master/docs/superpowers/plans/2026-07-17-transactional-fit-state.md

Core data structures and installation logic for managing model fit states and workspaces.

```python
@dataclass(frozen=True)
class FitState:
    revision: int
    selection_penalty: float
    distribution: Distribution
    projections: Mapping[str, object]
    retained: bool
    repair_revision: int = 0


@dataclass
class FitWorkspace:
    model: object
    mode: str
    validated_inputs: ValidatedFitInput | None
    previous_revision: int

    @classmethod
    def start(cls, public_model, *, mode, validated_inputs):
        work_model = public_model._config.materialize(type(public_model))
        return cls(work_model, mode, validated_inputs, public_model._fit_revision)


@dataclass(frozen=True)
class FitCandidate:
    state: FitState
    prepared_model_dict: dict[str, object]


def _install_fit_state(model, candidate):
    model.__dict__ = candidate.prepared_model_dict
```

--------------------------------

### Run Full Test Suite and Commit

Source: https://github.com/strudeldoodles/superglm/blob/master/docs/superpowers/plans/2026-07-25-factor-smooth-sz.md

Execute the full test suite, run linting, and commit the changes.

```bash
rtk uv run pytest tests/test_factor_smooth_sz_penalties.py tests/test_factor_smooth_penalties.py tests/test_multi_penalty.py tests/test_penalties.py -q
rtk uv run ruff check src/superglm/types.py src/superglm/solvers/hessian_factor.py src/superglm/reml/penalty_algebra.py tests/test_factor_smooth_sz_penalties.py
rtk git add src/superglm/types.py src/superglm/solvers/hessian_factor.py src/superglm/reml/penalty_algebra.py tests/test_factor_smooth_sz_penalties.py tests/test_factor_smooth_penalties.py
rtk git commit -m "Add compact SZ penalty algebra"
```

--------------------------------

### Run Full Test Suite and Commit

Source: https://github.com/strudeldoodles/superglm/blob/master/docs/superpowers/plans/2026-07-25-factor-smooth-sz.md

Execute all relevant tests, run linting, and commit the changes.

```bash
rtk uv run pytest tests/test_factor_smooth_sz_matrix.py tests/test_factor_smooth_matrix.py tests/test_factor_smooth_discrete.py -q
rtk uv run ruff check src/superglm/dm_builder.py src/superglm/_group_matrix/_group_matrix_core.py tests/test_factor_smooth_sz_matrix.py
rtk git add src/superglm/dm_builder.py src/superglm/_group_matrix/_group_matrix_core.py tests/test_factor_smooth_sz_matrix.py tests/test_factor_smooth_matrix.py tests/test_factor_smooth_discrete.py
rtk git commit -m "Add compact SZ matrix operations"
```

--------------------------------

### Run full repository and package gates

Source: https://github.com/strudeldoodles/superglm/blob/master/docs/superpowers/plans/2026-07-27-structured-diagnostics-compactness.md

Execute the full test suite, build the package, and run the repository smoke test.

```bash
rtk pytest tests/
rtk proxy uv build
rtk proxy uv run python run_test.py
```

--------------------------------

### Define Developer Guide Requirements

Source: https://github.com/strudeldoodles/superglm/blob/master/docs/superpowers/plans/2026-07-11-editor-integration-docs.md

List of required sections and commands for the developer guide validation test.

```python
required = [
    "## Mental Model for Python Developers",
    "## Authoritative Python State",
    "## Browser Store, Actions, and Selectors",
    "## JSON Requests and Semantic Revisions",
    "## DOM Events and Focus",
    "## CSS Grid, Flexbox, and Breakpoints",
    "## SVG Coordinates and Plot Geometry",
    "## Add a Tool Mode",
    "## Add a Curve Operation",
    "## Add an Inspector Panel",
    "## Add a FastAPI Route",
    "## Add a Metric",
    "## Add a Browser Regression Test",
    "rtk npm run test:frontend",
    "rtk npm run typecheck:frontend",
]
```

--------------------------------

### Import SuperGLM and Dependencies

Source: https://github.com/strudeldoodles/superglm/blob/master/docs/notebooks/editor_demo.ipynb

Initialize the environment by importing required libraries and the SuperGLM editor session.

```python
import sys
from pathlib import Path

import matplotlib.pyplot as plt
import numpy as np
import pandas as pd
from sklearn.model_selection import KFold, train_test_split

from superglm import (
    Categorical,
    Numeric,
    OrderedCategorical,
    Spline,
    SuperGLM,
    cross_validate,
    families,
    generate_tweedie_cpg,
)
from superglm.editor import EditorSession

print(sys.executable)
```

--------------------------------

### Execute documentation and browser gate tests

Source: https://github.com/strudeldoodles/superglm/blob/master/docs/superpowers/plans/2026-07-11-editor-modernization-program.md

Run this command to verify documentation navigation, browser suite compatibility in Chromium, and frontend module integrity.

```bash
rtk test uv run mkdocs build --strict
rtk test uv run pytest tests/test_editor_browser.py tests/editor/ -m browser --run-browser -q
rtk npm run test:frontend
rtk npm run typecheck:frontend
```

--------------------------------

### Development Environment and Testing Commands

Source: https://github.com/strudeldoodles/superglm/blob/master/AGENTS.md

Commands for setting up the development environment and executing standard test suites.

```bash
uv sync --python 3.13 --extra dev
```

```bash
uv run pytest tests/ -q
```

```bash
uv run pytest tests/ -q -m "not slow"
```

```bash
uv run ruff check src/ tests/
```

```bash
uv run ruff format --check src/ tests/
```

```bash
uv lock --check
```

```bash
uv pip check
```

```bash
uv run python run_test.py
```

--------------------------------

### Run Focused Tests and Build

Source: https://github.com/strudeldoodles/superglm/blob/master/docs/superpowers/plans/2026-07-21-release-manager-policy.md

Execute tests and documentation build to verify release management changes.

```bash
rtk proxy uv sync --python 3.13 --extra dev --group docs --extra plotting
rtk test uv run --python 3.13 pytest tests/test_release_management.py -q
rtk test uv run --python 3.13 mkdocs build --strict
rtk git diff --check
```

--------------------------------

### API Response Structure

Source: https://github.com/strudeldoodles/superglm/blob/master/docs/superpowers/plans/2026-07-11-editor-integration-docs.md

Example JSON response structure for authoritative state mutations.

```json
{
  "state": {"model_revision": 12, "terms": {}, "selection": {}, "history": {}},
  "summary": {"available": true, "compact": {}},
  "timing": {"fit_ms": 780.0, "state_ms": 10.5, "summary_ms": 54.3}
}
```

--------------------------------

### Build and inspect the wheel

Source: https://github.com/strudeldoodles/superglm/blob/master/docs/superpowers/plans/2026-07-12-editor-export-and-ordered-inference.md

Builds the package and verifies that the correct assets are included in the distribution wheel.

```bash
rtk proxy uv build
rtk proxy sh -c 'wheel=$(ls -t dist/superglm-*.whl | head -n 1); unzip -l "$wheel"' | rtk proxy rg "editor/app|spline_diagnostics|\.superglm-debug"
```

--------------------------------

### Rating Table Offset Structure

Source: https://github.com/strudeldoodles/superglm/blob/master/docs/guide/deployment.md

Example of the raw source-aware offset table structure.

```text
Term    Relativity    Weight
12      1.0           ...
36      3.0           ...
```

--------------------------------

### Run All Tests Command

Source: https://github.com/strudeldoodles/superglm/blob/master/docs/superpowers/plans/2026-07-28-support-compressed-gram.md

Executes the full test suite for support compression.

```bash
uv run pytest tests/test_support_compression.py -v
```

--------------------------------

### Implement Responsive Drawer and Short Window Styles

Source: https://github.com/strudeldoodles/superglm/blob/master/docs/superpowers/plans/2026-07-11-editor-workspace-axis.md

Media queries to handle narrow screen inspector drawers and short window height adjustments.

```css
@media (max-width: 999px) {
  .editor-workspace {
    grid-template-columns: var(--tool-rail-width) minmax(0, 1fr);
  }

  .inspector {
    position: fixed;
    top: 8px;
    right: 8px;
    bottom: 8px;
    z-index: 61;
    width: min(390px, calc(100vw - var(--tool-rail-width) - 28px));
    min-width: 0;
    box-shadow: 0 18px 50px rgba(31, 35, 40, 0.24);
    transform: translateX(calc(100% + 20px));
    visibility: hidden;
    transition: transform 140ms ease, visibility 0s linear 140ms;
  }

  .inspector[data-open="true"] {
    transform: translateX(0);
    visibility: visible;
    transition-delay: 0s;
  }

  .inspector-close {
    display: inline-flex;
  }

  .inspector-scrim {
    position: fixed;
    inset: 0;
    z-index: 60;
    width: 100%;
    height: 100%;
    border: 0;
    background: rgba(31, 35, 40, 0.22);
  }
}

@media (max-height: 620px) {
  .app-shell {
    min-height: 0;
  }

  .editor-workspace,
  .plot-column {
    min-height: max-content;
  }

  .plot-column {
    grid-template-rows: auto 360px auto;
  }

}

@media (min-width: 1000px) and (max-height: 620px) {
  .inspector {
    min-height: 430px;
  }
}
```

--------------------------------

### Run Full Test Suite and Linting

Source: https://github.com/strudeldoodles/superglm/blob/master/docs/superpowers/plans/2026-07-30-rfc13-behavioural-batch.md

Commands to execute tests and verify code formatting.

```bash
uv run pytest tests/ -q
```

```bash
uv run ruff check src tests && uv run ruff format --check src tests
```

--------------------------------

### Define structural impact message

Source: https://github.com/strudeldoodles/superglm/blob/master/docs/superpowers/plans/2026-07-11-editor-refit-evidence.md

Example of the required text format for the structural confirmation dialog.

```text
Collapse levels B, C in region? This refit clears 2 manual edit history entries.
```

--------------------------------

### Define style file placeholders

Source: https://github.com/strudeldoodles/superglm/blob/master/docs/superpowers/plans/2026-07-11-editor-workspace-axis.md

Initializes the shell, chart, and panel CSS files with responsibility comments.

```css
/* shell.css: app bar, context bar, workspace grid, tool rail, and responsive shell. */
```

```css
/* chart.css: chart surface, SVG axis, selection palette, and shared popover. */
```

```css
/* panels.css: inspector, help, advanced controls, metrics, and reports. */
```

--------------------------------

### Initialize evidence coordinator

Source: https://github.com/strudeldoodles/superglm/blob/master/docs/superpowers/plans/2026-07-11-editor-refit-evidence.md

Setup for the evaluation cache and evidence coordinator within the widget constructor.

```python
self._evaluation_cache = EvaluationCache()
self._evidence = EvidenceCoordinator(f"editor-evidence-{id(self):x}")
```

--------------------------------

### Build and Commit Documentation

Source: https://github.com/strudeldoodles/superglm/blob/master/docs/superpowers/plans/2026-07-25-factor-smooth-sz.md

Commands to verify documentation integrity, build the site, and commit changes.

```bash
rtk uv run pytest tests/test_factor_smooth_sz_feature.py -q
rtk uv run mkdocs build --strict
rtk git add src/superglm/__init__.py docs/getting-started/quickstart.md docs/guide/interactions.md docs/guide/credibility.md docs/guide/fitting.md docs/api/features.md docs/api/inference.md tests/test_factor_smooth_sz_feature.py
rtk git commit -m "Document unified FS and SZ smooths"
```

--------------------------------

### Typed payload implementation start

Source: https://github.com/strudeldoodles/superglm/blob/master/docs/superpowers/plans/2026-07-12-editor-export-and-ordered-inference.md

Initial imports for the typed payload implementation in the export module.

```python
from __future__ import annotations
```

--------------------------------

### Run Full Verification and Linting

Source: https://github.com/strudeldoodles/superglm/blob/master/docs/superpowers/plans/2026-07-24-random-effect-structured-schur.md

Execute the full test suite and run ruff checks on the newly implemented files.

```bash
rtk uv run pytest tests/test_random_effect_inference.py tests/test_relativities.py \
  tests/test_model_tests.py -q
rtk uv run ruff check src/superglm/inference/random_effects.py \
  src/superglm/model/api.py src/superglm/model/report_ops.py
```

--------------------------------

### Verify TypeScript Installation

Source: https://github.com/strudeldoodles/superglm/blob/master/docs/superpowers/plans/2026-07-11-editor-workspace-axis.md

Confirm the locked TypeScript version is accessible via the npm execution environment.

```bash
rtk npm exec tsc -- --version
```

--------------------------------

### Run full test suite

Source: https://github.com/strudeldoodles/superglm/blob/master/docs/superpowers/plans/2026-07-27-structured-diagnostics-compactness.md

Verify that ordinary models still refit correctly while REML-only models fail as expected.

```bash
rtk pytest tests/test_refit.py
rtk pytest tests/test_random_effect_inference.py -k "drop1 or refit"
```

--------------------------------

### Smoke Test Built Wheel

Source: https://github.com/strudeldoodles/superglm/blob/master/docs/superpowers/plans/2026-07-21-release-manager-policy.md

Verify the installation and basic functionality of the built wheel in an isolated environment.

```bash
rtk proxy uv venv --python 3.13 /tmp/superglm-release-manager-smoke
rtk proxy uv pip install --python /tmp/superglm-release-manager-smoke/bin/python dist/*.whl
rtk proxy /tmp/superglm-release-manager-smoke/bin/python -c 'import superglm; from superglm.editor.server import create_editor_app; assert callable(create_editor_app); print(superglm.__version__)'
```

--------------------------------

### Commit reporting and documentation changes

Source: https://github.com/strudeldoodles/superglm/blob/master/docs/superpowers/plans/2026-08-11-categorical-level-universe.md

Stage and commit changes related to reporting, guide documentation, and the changelog.

```bash
git add -A src/superglm docs/guide CHANGELOG.md tests
git commit -m "Reporting, guide docs, and changelog for level universes"
```

--------------------------------

### Build and Verify Artifacts

Source: https://github.com/strudeldoodles/superglm/blob/master/docs/superpowers/plans/2026-07-21-explicit-selection-penalty-and-tweedie-ci.md

Build project artifacts and verify contents.

```bash
rtk uv build
rtk uv run python scripts/verify_release_artifacts.py dist
```

--------------------------------

### Static Analysis and Dependency Checks

Source: https://github.com/strudeldoodles/superglm/blob/master/docs/superpowers/plans/2026-07-21-explicit-selection-penalty-and-tweedie-ci.md

Run linting, formatting, and dependency verification tools.

```bash
rtk ruff check src/ tests/
rtk ruff format --check src/ tests/
rtk uv lock --check
rtk uv pip check
rtk test uv run ty check src/superglm
```

--------------------------------

### Assert Documentation Content Requirements

Source: https://github.com/strudeldoodles/superglm/blob/master/docs/superpowers/plans/2026-07-11-editor-integration-docs.md

Verify that the analyst guide contains all mandatory headings and operation terms.

```python
required = [
    "# Editing a Fitted Model",
    "## Open the Editor",
    "## Select, Move, Zoom, and Handles",
    "## Curve Selection Operations",
    "Straighten selection",
    "## Group and Ungroup Categorical Levels",
    "## Undo, Redo, and Recovery",
    "## Evidence Freshness",
    "## Save and Export",
    "## Keyboard Shortcuts",
]
assert all(text in guide for text in required)
```

--------------------------------

### Reproduce screening benchmarks

Source: https://github.com/strudeldoodles/superglm/blob/master/docs/guide/screening-evaluation.md

Execute the screening worth gate benchmark using the uv package manager.

```bash
uv run python benchmarks/screening_worth_gate.py
```

--------------------------------

### Run Frontend and Backend Tests

Source: https://github.com/strudeldoodles/superglm/blob/master/docs/superpowers/plans/2026-07-11-editor-refit-evidence.md

Commands to execute frontend and backend tests for structural refits.

```bash
rtk npm run test:frontend
rtk pytest tests/test_editor.py -k "structural_refits_show_busy or collapse_levels or uncollapse" -q
```

--------------------------------

### Configure multi-order penalties

Source: https://github.com/strudeldoodles/superglm/blob/master/docs/guide/features.md

Examples of using the m parameter to apply single or multiple penalty components to spline terms.

```python
Spline(kind="cr", k=12, m=2)
Spline(kind="cr", k=12, m=(1, 2))
Spline(kind="ps", k=14, m=(2, 3))
```

--------------------------------

### Run API documentation checks and test suite

Source: https://github.com/strudeldoodles/superglm/blob/master/docs/superpowers/plans/2026-07-31-mixed-interaction-screening.md

Executes the API documentation checker followed by the full test suite.

```bash
uv run python scripts/check_api_docs.py && uv run pytest tests/ -q
```

--------------------------------

### Commit Frontend Documentation Changes

Source: https://github.com/strudeldoodles/superglm/blob/master/docs/superpowers/plans/2026-07-11-editor-integration-docs.md

Stages and commits updates to the editor frontend developer guide and associated tests.

```bash
rtk git add docs/editor_frontend.md tests/test_editor.py
rtk git commit -m "Expand the editor frontend developer guide"
```

--------------------------------

### Run Static and Packaging Checks

Source: https://github.com/strudeldoodles/superglm/blob/master/docs/superpowers/plans/2026-07-12-panel-local-editor-rendering.md

Execute linting, formatting, documentation, and build verification checks.

```bash
rtk ruff check src/ tests/
rtk test uv run ruff format --check src/ tests/
rtk git diff --check
rtk test uv run --group docs --extra plotting mkdocs build --strict
rtk test uv build
```

--------------------------------

### Run Full Test Suite

Source: https://github.com/strudeldoodles/superglm/blob/master/docs/superpowers/plans/2026-07-25-discrete-reml-terminal-coherence.md

Executes all tests in the repository.

```bash
rtk pytest tests/ -q
```

--------------------------------

### Canonical SZ Model Configuration

Source: https://github.com/strudeldoodles/superglm/blob/master/docs/superpowers/specs/2026-07-25-factor-smooth-sz-design.md

Example of configuring a SuperGLM model using the FactorSmooth SZ basis for interaction terms.

```python
SuperGLM(
    features={"age": Spline(kind="ps", k=6, m=2)},
    interactions=[
        FactorSmooth("age", group="region", basis="sz", kind="ps", k=6, m=2)
    ],
)
```

--------------------------------

### Verify release artifacts

Source: https://github.com/strudeldoodles/superglm/blob/master/docs/superpowers/plans/2026-07-26-credibility-release-safety-review.md

Build the package and run verification scripts to ensure API documentation and smoke tests pass.

```bash
rtk proxy uv build
rtk proxy uv run python scripts/verify_release_artifacts.py
rtk proxy uv run python scripts/check_api_docs.py
rtk proxy uv run python run_test.py
```

--------------------------------

### Grouped View Legend Format

Source: https://github.com/strudeldoodles/superglm/blob/master/docs/superpowers/specs/2026-07-22-summary-categorical-level-display-design.md

Example of the legend displayed in grouped view to map group IDs to their constituent levels.

```text
Level groups (territory): G1 = B, C; G2 = D, E
```

--------------------------------

### Run Focused and Complete Test Suites

Source: https://github.com/strudeldoodles/superglm/blob/master/docs/superpowers/plans/2026-07-21-release-manager-policy.md

Execute these commands to verify release management logic and the full test suite.

```bash
rtk test uv run --python 3.13 pytest tests/test_release_management.py tests/test_supply_chain_governance.py tests/test_release_packaging.py -q
rtk test uv run --python 3.13 pytest tests/ -q
```

--------------------------------

### Commit Release Guidance

Source: https://github.com/strudeldoodles/superglm/blob/master/docs/superpowers/plans/2026-07-21-release-manager-policy.md

Commit the updated documentation and configuration files.

```bash
rtk git add .gitignore AGENTS.md .github/PULL_REQUEST_TEMPLATE.md docs/development/releases.md mkdocs.yml tests/test_release_management.py
rtk git commit -m "Document governed release impact workflow"
```

--------------------------------

### Document trace and profile plot usage

Source: https://github.com/strudeldoodles/superglm/blob/master/docs/superpowers/plans/2026-07-17-tweedie-trace-plot.md

Example usage for documentation showing the difference between cached and dense plotting methods.

```python
result.trace_plot()    # cached search evaluations; performs no new fits
result.profile_plot()  # dense profile curve; performs additional fixed-p fits
```

--------------------------------

### Define and Fit a Spline-based Pricing Model

Source: https://github.com/strudeldoodles/superglm/blob/master/README.md

Example of defining feature specifications and fitting a Poisson model using REML.

```python
from superglm import Categorical, Numeric, Spline, SuperGLM

features = {
    "DrivAge": Spline(kind="ps", k=14, knot_strategy="quantile_rows"),
    "VehAge": Spline(kind="cr", k=10, knot_strategy="quantile_rows"),
    "BonusMalus": Spline(kind="cr", k=12, knot_strategy="quantile_tempered"),
    "Area": Categorical(base="most_exposed"),
    "LogDensity": Numeric(),
}

model = SuperGLM(
    family="poisson",
    selection_penalty=0.0,
    features=features,
)
model.fit_reml(train_df, y_train, sample_weight=exposure_train, max_reml_iter=30)

mu_holdout = model.predict(holdout_df)
print(model.summary())
```

--------------------------------

### Run full verification suite

Source: https://github.com/strudeldoodles/superglm/blob/master/docs/superpowers/plans/2026-07-12-incremental-selection-rendering.md

Execute the complete test suite, linting, and formatting checks to verify the fix.

```bash
rtk npm run check:frontend
rtk proxy uv run --extra dev pytest tests/test_editor_browser.py tests/editor/ --run-browser -q
rtk proxy uv run pytest tests/test_editor.py tests/test_editor_evaluation_cache.py \
  tests/test_editor_evidence.py -q
rtk ruff check src/ tests/
rtk test uv run ruff format --check src/ tests/
rtk git diff --check
```

--------------------------------

### Record Baseline Tests and Linting

Source: https://github.com/strudeldoodles/superglm/blob/master/docs/superpowers/plans/2026-07-11-editor-modernization-program.md

Executes the test suite and linting tools to establish a clean baseline before starting implementation.

```bash
rtk test uv run pytest tests/test_editor.py -q
rtk ruff check src/superglm/editor tests/test_editor.py
```

--------------------------------

### Build and smoke-test package

Source: https://github.com/strudeldoodles/superglm/blob/master/docs/superpowers/plans/2026-07-27-pr165-release-review-remediation.md

Builds the distribution and runs a smoke test script.

```bash
rtk proxy uv build
rtk proxy uv run python run_test.py
```

--------------------------------

### Configure CI Frontend Job

Source: https://github.com/strudeldoodles/superglm/blob/master/docs/superpowers/plans/2026-07-11-editor-foundation-state.md

YAML configuration for a dedicated frontend CI job that installs dependencies and runs browser tests.

```yaml
  frontend:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0
      - uses: actions/setup-node@a0853c24544627f65ddf259abe73b1d18a591444
        with:
          node-version: "24"
          cache: npm
      - name: Install uv
        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39
      - name: Set up Python
        run: uv python install 3.13
      - name: Install dependencies
        run: uv sync --python 3.13 --extra dev
      - name: Install frontend dependencies
        run: npm ci
      - name: Check frontend modules
        run: npm run check:frontend
      - name: Install Chromium
        run: uv run playwright install --with-deps chromium
      - name: Browser tests
        run: uv run pytest tests/test_editor_browser.py -m browser --run-browser -q
```

--------------------------------

### Generate Screenshot and Build Docs

Source: https://github.com/strudeldoodles/superglm/blob/master/docs/superpowers/plans/2026-07-11-editor-integration-docs.md

Executes the screenshot capture script and verifies the documentation build.

```bash
rtk test uv run python scripts/capture_editor_screenshot.py
rtk test uv run mkdocs build --strict
```

--------------------------------

### Define browser-editor CI job

Source: https://github.com/strudeldoodles/superglm/blob/master/docs/superpowers/plans/2026-07-11-editor-integration-docs.md

Add this job to CI workflow files to install dependencies, Chromium, and execute browser tests.

```yaml
      - name: Install dependencies
        run: uv sync --extra dev --extra browser
      - name: Install Chromium
        run: uv run playwright install --with-deps chromium
      - name: Browser editor tests
        run: uv run pytest tests/test_editor_browser.py -m browser --run-browser -q
      - name: Frontend checks
        run: npm ci && npm run check:frontend
```

--------------------------------

### Expanded View Categorical Table Format

Source: https://github.com/strudeldoodles/superglm/blob/master/docs/superpowers/specs/2026-07-22-summary-categorical-level-display-design.md

Example of the expanded view output showing individual levels and their associated group IDs.

```text
Term                 Level group    Estimate    SE       p
territory[A]                        0.0000      ref      --
territory[B]         G1             0.1840      0.0520   0.001
territory[C]         G1             0.1840      0.0520   0.001
territory[D]         G2            -0.0920      0.0410   0.025
territory[E]         G2            -0.0920      0.0410   0.025
```

--------------------------------

### Run release packaging gates

Source: https://github.com/strudeldoodles/superglm/blob/master/docs/superpowers/plans/2026-07-26-structured-solver-package-extraction.md

Verifies release metadata, builds the package, and checks artifacts for compliance.

```bash
rtk pytest \
  tests/test_version_metadata.py \
  tests/test_release_management.py \
  tests/test_release_packaging.py \
  tests/test_supply_chain_governance.py -q
rtk proxy uv build
rtk proxy uv run twine check dist/*
rtk proxy uv run check-wheel-contents dist/*.whl
rtk proxy uv run python scripts/verify_release_artifacts.py dist/*
```

--------------------------------

### Wrapper and Documentation Test Commands

Source: https://github.com/strudeldoodles/superglm/blob/master/docs/superpowers/plans/2026-07-21-explicit-selection-penalty-and-tweedie-ci.md

Commands to execute wrapper tests, documentation builds, and linting.

```bash
rtk test uv run pytest tests/test_sklearn.py tests/test_tweedie_profile_docs.py -q
rtk uv sync --python /usr/bin/python3.14 --group docs --extra plotting
rtk test uv run mkdocs build --strict
rtk ruff check src/superglm/sklearn.py tests/test_sklearn.py
```

--------------------------------

### Configure CaseConfig for SZ Factor Basis

Source: https://github.com/strudeldoodles/superglm/blob/master/docs/superpowers/plans/2026-07-25-factor-smooth-sz.md

Example of setting up a CaseConfig object with the 'sz' factor basis for testing structured credibility.

```python
config = CaseConfig(
    n=600,
    levels=20,
    family="poisson",
    discrete=True,
    random_effects=0,
    secondary_levels=None,
    small_width=2,
    weights="nonuniform",
    seed=919,
    structured_term="factor_smooth",
    block_size=6,
    global_spline=True,
    factor_basis="sz",
)
prepared = prepare_case(config)
model = _new_model(prepared, "structured")
term = model._interaction_specs["curve_x:curve_group:sz"]
assert term.basis == "sz"
assert config.dominant_width == 114
assert "sz_k6" in config.slug
```

--------------------------------

### Fit a model with explicit features and REML

Source: https://github.com/strudeldoodles/superglm/blob/master/docs/getting-started/quickstart.md

The recommended starting point for pricing models using spline terms and REML estimation.

```python
from superglm import Categorical, Numeric, Spline, SuperGLM

features = {
    "DrivAge": Spline(kind="ps", k=14, knot_strategy="quantile_rows"),
    "VehAge": Spline(kind="cr", k=10, knot_strategy="quantile_rows"),
    "BonusMalus": Spline(kind="cr", k=12, knot_strategy="quantile_tempered"),
    "Area": Categorical(base="most_exposed"),
    "LogDensity": Numeric(),
}

model = SuperGLM(
    family="poisson",
    selection_penalty=0.0,
    features=features,
)
model.fit_reml(df, y, sample_weight=exposure, max_reml_iter=30)

predictions = model.predict(df)
print(model.summary())
```

--------------------------------

### Verify Factor Smooth Matrix Implementation

Source: https://github.com/strudeldoodles/superglm/blob/master/docs/superpowers/plans/2026-07-24-factor-smooth-block-schur.md

Run the test suite to verify the implementation of factor-smooth matrices and matrix execution plans.

```bash
uv run pytest tests/test_factor_smooth_matrix.py -q
uv run pytest tests/test_matrix_execution_plan.py tests/test_group_matrix_algebra.py -q
```

--------------------------------

### Verify Primitive Implementation

Source: https://github.com/strudeldoodles/superglm/blob/master/docs/superpowers/plans/2026-07-17-transactional-fit-state.md

Command to run the primitive tests and verify allocation behavior.

```bash
rtk uv run pytest tests/test_fit_transactions.py::test_workspace_does_not_alias_previous_fitted_state tests/test_fit_transactions.py::test_install_is_one_revision_swap -q
```

--------------------------------

### Per-unit offset block structure

Source: https://github.com/strudeldoodles/superglm/blob/master/docs/guide/results.md

Example of a per-unit block output, which consists of a single row applied by multiplying the named column by its Relativity.

```text
SumInsured | Relativity | Weight
per_unit   | 1.0        | 6000.0
```

--------------------------------

### Configure model weights and offsets

Source: https://github.com/strudeldoodles/superglm/blob/master/README.md

Demonstrates the difference between using offsets for count targets and sample weights for rate targets.

```python
import numpy as np

# Raw count target: offset absorbs exposure, model estimates a rate
model.fit(df, claim_counts, offset=np.log(exposure))

# Rate target: sample_weight carries exposure
model.fit(df, claim_rate, sample_weight=exposure)
```

--------------------------------

### Documenting large-(n) behavior in credibility guide

Source: https://github.com/strudeldoodles/superglm/blob/master/docs/superpowers/plans/2026-07-26-credibility-release-safety-review.md

Add this markdown snippet to the current-scope section of docs/guide/credibility.md to clarify memory and construction policies.

```markdown
- Discrete FS/SZ constructs the normal `m <= 2` marginal in bounded QR
  chunks before evaluating the final support basis. FS declarations with
  asymmetric null-component policies or `m > 2` retain a reduced-memory dense
  compatibility construction so those custom penalty coordinates do not
  change silently.
```

--------------------------------

### Run Full Frontend Test Suite

Source: https://github.com/strudeldoodles/superglm/blob/master/docs/superpowers/plans/2026-07-12-incremental-selection-rendering.md

Commands to run all frontend tests and verify type safety.

```bash
rtk proxy node --test tests/editor_frontend/store.test.js tests/editor_frontend/actions.test.js
rtk npm run typecheck:frontend
```

--------------------------------

### Running Frontend Summary Tests

Source: https://github.com/strudeldoodles/superglm/blob/master/docs/superpowers/plans/2026-07-22-summary-categorical-level-display.md

Execute the specific test file for the editor frontend summary.

```bash
rtk test node --test tests/editor_frontend/summary.test.js
```

--------------------------------

### Test Case for Cold Final Attempt

Source: https://github.com/strudeldoodles/superglm/blob/master/docs/superpowers/plans/2026-07-31-scop-cold-certification-retry.md

A regression test that mocks the certification process to verify that the fourth retry attempt initiates with a cold start.

```python
    def test_a_failed_certification_gets_a_cold_final_attempt(self, monkeypatch):
        """The final retry rung drops the warm start, not just the tolerance.

        The two tolerance rungs re-fit from the mode that just failed. Once the
        inner fit has converged tighter than the bar, that reproduces the same
        mode bit-identically -- measured on the fit this exists for, three
        attempts all returned 1.3792e-06 against a bar of 7.1463e-08. Only a
        different starting point can move it, so the last rung starts cold.

        Certification is forced to reject the first three attempts, so the fit
        can only succeed if a fourth exists. The warm/cold pattern is asserted
        too: a fourth attempt that also warm-started would not be the fix.
        """
        warm_starts: list[bool] = []
        checks = {"n": 0}

        real_fit = scop_efs_module._fit_scop_reml_mode
        real_relative = scop_efs_module._scop_mode_newton_relative

        def recording_fit(context, lambdas, **kwargs):
            warm_starts.append(kwargs.get("beta_init") is not None)
            return real_fit(context, lambdas, **kwargs)

        def reject_first_three(mode):
            checks["n"] += 1
            if checks["n"] <= 3:
                return 1.0  # far above any achievable tolerance
            return real_relative(mode)

        monkeypatch.setattr(scop_efs_module, "_fit_scop_reml_mode", recording_fit)
        monkeypatch.setattr(
            scop_efs_module, "_scop_mode_newton_relative", reject_first_three
        )

        rng = np.random.default_rng(0)
        n = 200
        x = np.sort(rng.uniform(0, 1, n))
        y = np.round(np.exp(1.0 + 1.5 * x)).astype(float)
        frame = pd.DataFrame({"x": x})
        model = SuperGLM(
            family="poisson",
            selection_penalty=0.0,
            discrete=True,
            features={
                "x": PSpline(n_knots=8, penalty="ssp", constraint=Constraint.fit.increasing)
            },
        )
        model.fit_reml(frame, y, max_reml_iter=5)

        assert checks["n"] >= 4, "the ladder must reach a fourth attempt"
        assert warm_starts[1] is True, "rung 1 warm-starts"
        assert warm_starts[2] is True, "rung 2 warm-starts"
        assert warm_starts[3] is False, "the final rung must start cold"
```

--------------------------------

### Execute local build and inspection commands

Source: https://github.com/strudeldoodles/superglm/blob/master/docs/superpowers/plans/2026-07-11-editor-foundation-state.md

Commands to build the project and verify the contents of the generated wheel files.

```bash
rtk uvx --from 'build==1.2.2.post1' python -m build
```

```bash
rtk uvx --from 'check-wheel-contents==0.6.3' check-wheel-contents dist/*.whl
```

--------------------------------

### Configure Advanced Penalty Objects

Source: https://github.com/strudeldoodles/superglm/blob/master/README.md

Apply low-level penalty objects such as GroupElasticNet during model initialization. This is an advanced feature and should not be used as the default starting point.

```python
from superglm import GroupElasticNet

penalty = GroupElasticNet(lambda1=0.01, alpha=0.5)
model = SuperGLM(family="poisson", penalty=penalty, features=features)
```

--------------------------------

### Run test suite

Source: https://github.com/strudeldoodles/superglm/blob/master/docs/superpowers/plans/2026-07-31-scop-candidate-step-backoff.md

Execute the specific test class and the full test file.

```bash
cd /home/max/projects/superglm && uv run pytest \
    "tests/test_scop_efs.py::TestCandidateStepBackoff" -q -p no:randomly && \
uv run pytest tests/test_scop_efs.py -q -p no:randomly
```

--------------------------------

### Test Structural Envelope Commit Ordering

Source: https://github.com/strudeldoodles/superglm/blob/master/docs/superpowers/plans/2026-07-11-editor-refit-evidence.md

Unit test to verify that structural mutations commit state without triggering an additional GET request.

```javascript
const envelope = {
  state: snapshot(7),
  summary: { available: true, source: "in_force" },
  timing: { fit_ms: 10, state_ms: 2, summary_ms: 1 }
};

test("structural envelope commits primary state once without GET state", async () => {
  const calls = [];
  const store = createEditorStore(createInitialEditorState(snapshot(6)));
  const actions = createEditorActions({
    store,
    client: {
      postJSON: async () => { calls.push("post"); return envelope; },
      getState: async () => { throw new Error("GET state must not run"); }
    },
    waitForPaint: async () => { calls.push("paint"); }
  });
  store.subscribe(
    state => state.remote.snapshot?.model_revision,
    () => calls.push("commit")
  );
  const result = await actions.executeStructuralMutation({
    name: "collapse levels",
    path: "/collapse_levels",
    payload: { term: "region", method: "auto" },
    waitForSecondary: async () => { calls.push("evidence"); }
  });
  calls.push(store.getState().request.mutation.status);
  assert.equal(result.ok, true);
  assert.equal(store.getState().remote.summary.source, "in_force");
  assert.deepEqual(calls, ["post", "commit", "paint", "evidence", "idle"]);
});
```

--------------------------------

### Piecewise Cubic Spline Export Format

Source: https://github.com/strudeldoodles/superglm/blob/master/docs/guide/deployment.md

Example of the piecewise cubic spline data structure, which includes coefficients for evaluating the curve within bounded intervals.

```text
DrivAge                     Relativity   Weight     a          b          c          d
[-inf, 18.0)                  3.312618      0.00    1.197739   0          0          0
[18.0, 25.363636363636363)    3.312618   2896.43    1.197739  -0.401915  -1.095004   0.570373
...
[99.0, inf)                   2.783720      8.65    1.023788   0          0          0
```

--------------------------------

### Initialize layout module imports

Source: https://github.com/strudeldoodles/superglm/blob/master/docs/superpowers/plans/2026-07-26-structured-solver-package-extraction.md

Required imports for the new layout module.

```python
"""Coefficient layouts and design products for structured systems."""

from __future__ import annotations

from dataclasses import dataclass, replace

import numpy as np
from numpy.typing import NDArray

from superglm._group_matrix._group_matrix_execution import MatrixExecutionPlan
from superglm.group_matrix import (
    DenseGroupMatrix,
    DesignMatrix,
    FactorSmoothGroupMatrix,
    GroupMatrix,
    RandomEffectGroupMatrix,
)
from superglm.types import GroupSlice
```

--------------------------------

### Define Fit State and Workspace Tests

Source: https://github.com/strudeldoodles/superglm/blob/master/docs/superpowers/plans/2026-07-17-transactional-fit-state.md

Tests to verify that the workspace does not alias the previous fitted state and that state installation performs a single atomic revision swap.

```python
def test_workspace_does_not_alias_previous_fitted_state(fitted_model):
    previous = fitted_model._fit_state
    workspace = FitWorkspace.start(fitted_model, mode="fit", validated_inputs=None)
    assert workspace.model._specs is not fitted_model._specs
    assert workspace.model._groups is not fitted_model._groups
    assert workspace.model._dm is None
    assert fitted_model._fit_state is previous


def test_install_is_one_revision_swap(fitted_model):
    workspace = FitWorkspace.start(fitted_model, mode="fit", validated_inputs=None)
    candidate = make_minimal_candidate(workspace, fitted_model._fit_revision + 1)
    old_dict = fitted_model.__dict__
    _install_fit_state(fitted_model, candidate)
    assert fitted_model._fit_state is candidate.state
    assert fitted_model._fit_revision == candidate.state.revision
    assert fitted_model.__dict__ is not old_dict
```

--------------------------------

### Run Frontend Tests and Checks

Source: https://github.com/strudeldoodles/superglm/blob/master/docs/editor_frontend.md

Executes the test and type-checking suites for the frontend using the rtk command-line tool.

```bash
rtk npm run test:frontend
rtk npm run typecheck:frontend
rtk pytest tests/editor/test_editor_refit_browser.py -m browser --run-browser -q
```

--------------------------------

### Execute static analysis and formatting

Source: https://github.com/strudeldoodles/superglm/blob/master/docs/superpowers/plans/2026-07-26-credibility-release-safety-review.md

Run ruff formatting, linting, and mypy type checking across the source, tests, and benchmarks.

```bash
rtk proxy uv run ruff format src/superglm/solvers/_structured/selection.py src/superglm/solvers/_structured/state.py src/superglm/export/rating_tables.py src/superglm/dm_builder.py src/superglm/model/base.py src/superglm/model/fit_state.py src/superglm/model/fit_ops.py src/superglm/model/fit_data_guard.py src/superglm/_reporting_state.py src/superglm/model/reml_finalize.py src/superglm/features/random_effect.py src/superglm/features/factor_smooth.py src/superglm/inference/_term_covariance.py src/superglm/inference/_term_ops.py src/superglm/inference/_term_model_ops.py src/superglm/inference/random_effects.py src/superglm/inference/factor_smooths.py tests/test_structured_allocations.py tests/test_factor_smooth_structured_parity.py tests/test_rating_table_export.py tests/test_factor_smooth_feature.py tests/test_interactions.py tests/test_plot_api.py tests/test_drop1.py tests/test_random_effect_inference.py tests/test_factor_smooth_inference.py tests/test_factor_smooth_sz_inference.py tests/test_fit_data_guard.py tests/test_factor_smooth_discrete.py benchmarks/profile_factor_smooth_construction.py
rtk ruff check src/ tests/ benchmarks/profile_factor_smooth_construction.py
rtk mypy src/
```

--------------------------------

### Verify Terminal and Failure Events

Source: https://github.com/strudeldoodles/superglm/blob/master/docs/superpowers/plans/2026-07-17-authoritative-fit-trace.md

Tests to ensure private and public terminal events match installed results and that failed runs do not overwrite previous terminal states.

```python
def test_private_and_public_terminals_match_installed_results(canonical_fit_trace):
    model, events = canonical_fit_trace
    private = next(e for e in events if e.purpose == "private_terminal")
    public = next(e for e in events if e.purpose == "public_terminal")
    np.testing.assert_allclose(private.payload["beta"], model._solver_result.beta)
    np.testing.assert_allclose(public.payload["beta"], model.result.beta)
    assert private.payload["state_space"] == "solver"
    assert public.payload["state_space"] == "public_canonical"


def test_failed_run_cannot_replace_previous_terminal(fitted_model, failure_injector):
    prior_revision = fitted_model._fit_revision
    with pytest.raises(InjectedFitFailure):
        failure_injector.refit(fitted_model)
    assert fitted_model._fit_revision == prior_revision
```

--------------------------------

### Run integration verification

Source: https://github.com/strudeldoodles/superglm/blob/master/docs/superpowers/plans/2026-07-11-editor-integration-docs.md

Execute the full suite of integration tests and checks for phase acceptance.

```bash
rtk test uv run pytest tests/test_editor.py tests/test_editor_browser.py tests/editor/ --run-browser -q
rtk npm run test:frontend
rtk npm run typecheck:frontend
rtk test uv run mkdocs build --strict
rtk ruff check src/superglm/editor tests/test_editor.py tests/test_editor_browser.py scripts/capture_editor_screenshot.py
```

--------------------------------

### Run Store Tests

Source: https://github.com/strudeldoodles/superglm/blob/master/docs/superpowers/plans/2026-07-12-incremental-selection-rendering.md

Command to execute the store test suite.

```bash
rtk proxy node --test tests/editor_frontend/store.test.js
```

--------------------------------

### Run Frontend Tests

Source: https://github.com/strudeldoodles/superglm/blob/master/docs/superpowers/plans/2026-07-11-editor-integration-docs.md

Command to execute the alert frontend unit tests.

```bash
rtk node --test tests/editor_frontend/alerts.test.js
```

--------------------------------

### Run verification and linting

Source: https://github.com/strudeldoodles/superglm/blob/master/docs/superpowers/plans/2026-07-24-factor-smooth-block-schur.md

Execute formatting, static analysis, and test suites.

```bash
uv run ruff format src/ tests/ benchmarks/
uv run ruff check src/ tests/ benchmarks/
uv run mypy src/
uv run pytest tests/ -q
uv run python run_test.py
git diff --check
```

--------------------------------

### Commit Implementation Plan

Source: https://github.com/strudeldoodles/superglm/blob/master/docs/superpowers/plans/2026-07-31-scop-candidate-step-backoff.md

Forces the addition of the plan file to the repository and commits it with a descriptive message.

```bash
cd /home/max/projects/superglm && \
git add -f docs/superpowers/plans/2026-07-31-scop-candidate-step-backoff.md && \
git commit -m "Add the implementation plan for the candidate-site step backoff" && \
git log --stat -1
```
Tokens:
Raw