Add RSSSM: regime-switching sequential sampling models

.claude/skills/prepare-release/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: prepare-release
 description: >
-  Automate the HSSM pre-release workflow: update changelog, update docs announcement banner,
+  Automate the HSSM pre-release workflow: update changelog,
   build docs locally, and create a draft GitHub release. Use this skill whenever the user mentions
   "prepare release", "release prep", "pre-release checklist", "update changelog for release",
   or any variation of getting ready to publish a new version of HSSM. Also trigger when the user
@@ -14,7 +14,6 @@ This skill automates the pre-release checklist for the HSSM package. It assumes
 in `pyproject.toml` has already been bumped. The skill walks through four steps:
 
 1. Update the changelog (`docs/changelog.md`)
-2. Update the announcement banner (`docs/overrides/main.html`)
 3. Build docs locally to verify they compile
 4. Run the notebook check workflow in CI
 5. Create a draft GitHub release
@@ -80,17 +79,7 @@ Guidelines for writing the changelog:
 
 After user approval, insert the new version section into `docs/changelog.md` immediately after the `# Changelog` heading on line 1. Add a blank line before and after the new section.
 
-## Step 5: Update the announcement banner
-
-Edit `docs/overrides/main.html`. Find the line containing the version announcement (pattern: `v{OLD_VERSION} is released!`) and replace it with:
-
-```html
-<span class="right-margin"> v{VERSION} is released! </span>
-```
-
-Only change the version number — leave the surrounding HTML and Jinja2 template structure untouched.
-
-## Step 6: Build docs locally
+## Step 5: Build docs locally
 
 Run:
 
@@ -105,7 +94,7 @@ Check that the command exits with code 0. If it fails:
 
 If it succeeds, confirm to the user and move on.
 
-## Step 7: Run the notebook check workflow
+## Step 6: Run the notebook check workflow
 
 Trigger the `check_notebooks.yml` workflow on the current branch to verify all notebooks execute successfully:
 
@@ -125,7 +114,7 @@ Use `gh run watch <RUN_ID>` to stream the status, or poll with `gh run view <RUN
 - If the workflow **succeeds**, confirm to the user and proceed to the draft release.
 - If the workflow **fails**, show the user the failure details using `gh run view <RUN_ID> --log-failed` and help debug. Do NOT proceed to creating the release until notebooks pass.
 
-## Step 8: Create a draft GitHub release
+## Step 7: Create a draft GitHub release
 
 Run:
 
@@ -136,9 +125,9 @@ gh release create v{VERSION} --draft --title "v{VERSION}" --generate-notes --tar
 The `--draft` flag ensures nothing is published (and therefore no CI release pipeline is triggered).
 The `--generate-notes` flag uses GitHub's auto-generated release notes from merged PRs.
 
-## Step 9: Report
+## Step 8: Report
 
 Tell the user:
 - The draft release URL (from the `gh release create` output)
-- A summary of what was done: changelog updated, banner updated, docs build verified, draft release created
+- A summary of what was done: changelog updated, docs build verified, draft release created
 - Remind them that publishing the release will trigger the full CI pipeline (tests, PyPI publish, docs deploy)

.codegraph/.gitignore

@@ -0,0 +1,5 @@
+# CodeGraph data files — local to each machine, not for committing.
+# Ignore everything in .codegraph/ except this file itself, so transient
+# files (the database, daemon.pid, sockets, logs) never show up in git.
+*
+!.gitignore

.devcontainer/devcontainer.json

@@ -0,0 +1,31 @@
+{
+  "name": "HSSM",
+
+  // Reuse the runnable image's Dockerfile so the dev container and the published
+  // image share one definition (python 3.13, uv, graphviz, non-root `hssm` user).
+  // Building here (rather than pulling the image) means Codespaces works before the
+  // image is ever published. Swap for `"image": "ghcr.io/lnccbrown/hssm:latest"`
+  // once it's on GHCR if you'd rather pull than build.
+  "build": { "dockerfile": "../Dockerfile", "context": ".." },
+  "remoteUser": "hssm",
+
+  // Editable dev env on top of the image. `uv sync` installs the project + the
+  // default `dev` group (pytest, ruff, mypy, pre-commit) from uv.lock into .venv.
+  // ponytail: dev group only — `uv sync --group notebook` / `--group docs` are one
+  // command away when a contributor needs the heavy notebook/docs stacks.
+  // onCreateCommand runs during prebuilds, so the venv is baked in → fast startup.
+  "onCreateCommand": "uv sync",
+
+  "customizations": {
+    "vscode": {
+      "extensions": [
+        "ms-python.python",
+        "charliermarsh.ruff",
+        "ms-python.mypy-type-checker"
+      ],
+      "settings": {
+        "python.defaultInterpreterPath": ".venv/bin/python"
+      }
+    }
+  }
+}

.dockerignore

@@ -0,0 +1,16 @@
+# Keep the build context small. The Dockerfile only COPYs pyproject/README/LICENSE,
+# src, and docs/tutorials; everything else is noise.
+.git
+.github
+.venv
+**/__pycache__
+*.pyc
+*.pyo
+**/.ipynb_checkpoints
+tests
+.pytest_cache
+.ruff_cache
+.mypy_cache
+# Only docs/tutorials is copied into the image; drop the rest of docs/ from context.
+docs/*
+!docs/tutorials

.github/setup-env-notebooks/action.yml

@@ -8,25 +8,18 @@ inputs:
 runs:
   using: "composite"
   steps:
-    - name: Setup Python
-      uses: actions/setup-python@v6
-      with:
-        python-version: ${{ inputs.python-version }}
-
-    - name: Install BLAS and LAPACK
-      run: sudo apt-get update && sudo apt-get install -y libblas-dev liblapack-dev
-      shell: bash
-
     - name: Checkout repository
-      uses: actions/checkout@v6
+      uses: actions/checkout@v7
 
     - name: Install uv
-      uses: astral-sh/setup-uv@v7
+      uses: astral-sh/setup-uv@v9.0.0
       with:
         version: "latest"
+        python-version: ${{ inputs.python-version }}
         enable-cache: true
 
+    # (a stale `if: steps.cache.outputs.cache-hit` guard used to sit here —
+    # no step with id `cache` exists, so it always evaluated true)
     - name: Install hssm
-      if: steps.cache.outputs.cache-hit != 'true'
       run: uv sync --group notebook
       shell: bash

.github/setup-env/action.yml

@@ -8,25 +8,26 @@ inputs:
 runs:
   using: "composite"
   steps:
-    - name: Setup Python
-      uses: actions/setup-python@v6
-      with:
-        python-version: ${{ inputs.python-version }}
+    - name: Checkout repository
+      uses: actions/checkout@v7
 
+    # run_tests.yml sets PYTENSOR_FLAGS=blas__ldflags=... -lblas -llapack; the
+    # runner image ships only the runtime .so.3 objects, so without the -dev
+    # packages the linker cannot resolve those flags and PyTensor's C backend
+    # fails to compile any BLAS-using op.
     - name: Install BLAS and LAPACK
       run: sudo apt-get update && sudo apt-get install -y libblas-dev liblapack-dev
       shell: bash
 
-    - name: Checkout repository
-      uses: actions/checkout@v6
-
     - name: Install uv
-      uses: astral-sh/setup-uv@v7
+      uses: astral-sh/setup-uv@v9.0.0
       with:
         version: "latest"
+        python-version: ${{ inputs.python-version }}
         enable-cache: true
 
+    # (a stale `if: steps.cache.outputs.cache-hit` guard used to sit here —
+    # no step with id `cache` exists, so it always evaluated true)
     - name: Install hssm
-      if: steps.cache.outputs.cache-hit != 'true'
       run: uv sync
       shell: bash

.github/workflows/build_and_publish.yml

@@ -4,25 +4,16 @@ on:
   release:
     types:
       - published
+  workflow_dispatch:
 
 jobs:
   lint_and_typecheck:
     name: Lint and type-check
     uses: ./.github/workflows/linting_and_type_checking.yml
 
-  run_tests:
-    name: Run full test suite
-    uses: ./.github/workflows/run_tests.yml
-    with:
-      run_slow_tests: true
-
-  # check_notebooks:
-  #   name: Check notebooks
-  #   uses: ./.github/workflows/check_notebooks.yml
-
   publish:
     name: Build wheel and publish to test-PyPI, then PyPI, and publish docs
-    needs: [lint_and_typecheck, run_tests]
+    needs: [lint_and_typecheck]
     runs-on: ubuntu-latest
 
     strategy:
@@ -32,7 +23,7 @@ jobs:
 
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v6
+        uses: actions/checkout@v7
 
       - name: Setup environment
         uses: ./.github/setup-env

.github/workflows/build_docs.yml

@@ -1,25 +1,52 @@
-name: Build docs
+name: Docs
 
 on:
+  pull_request:
+    paths: ["docs/**", "mkdocs.yml", "pyproject.toml", "src/hssm/**"]
+  push:
+    branches: [main]
+    paths: ["docs/**", "mkdocs.yml", "pyproject.toml", "src/hssm/**"]
+  release:
+    types: [published]
+  schedule:
+    - cron: "50 5 * * 1" # weekly link check (Monday, off-peak UTC)
   workflow_dispatch:
 
+permissions:
+  contents: read
+
 jobs:
-  build_docs:
+  build:
+    if: github.event_name != 'schedule'
     runs-on: ubuntu-latest
-
-    strategy:
-      fail-fast: true
-      matrix:
-        python-version: ["3.13"]
-
     steps:
-      - name: Checkout repository
-        uses: actions/checkout@v6
-
-      - name: Setup environment
-        uses: ./.github/setup-env
+      - uses: actions/checkout@v7
+      - uses: ./.github/setup-env
         with:
-          python-version: ${{ matrix.python-version }}
+          python-version: "3.13"
+      - name: Build docs (strict)
+        run: uv run --group notebook --group docs mkdocs build --strict
 
-      - name: Run mkdocs
+  deploy:
+    if: github.event_name == 'release' || (github.event_name == 'push' && github.ref == 'refs/heads/main') || github.event_name == 'workflow_dispatch'
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v7
+      - uses: ./.github/setup-env
+        with:
+          python-version: "3.13"
+      - name: Deploy docs
         run: uv run --group notebook --group docs mkdocs gh-deploy --force
+
+  linkcheck:
+    if: github.event_name == 'schedule' || github.event_name == 'workflow_dispatch'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: lycheeverse/lychee-action@v2
+        with:
+          args: --cache --max-cache-age 1d --no-progress './docs/**/*.md' 'README.md'
+          fail: true

.github/workflows/check_notebooks.yml

@@ -2,22 +2,26 @@ name: Check notebooks
 
 on:
   workflow_dispatch:
+  workflow_call:  # Called by drift.yml (monthly notebook drift run)
 
 jobs:
   check_notebooks:
     runs-on: ubuntu-latest
     if: ${{ ! contains(github.event.head_commit.message, '[skip fast tests]') }}
-    env:
-      PYTENSOR_FLAGS: "blas__ldflags=-L/usr/lib/x86_64-linux-gnu -lblas -llapack"
 
+    name: Check notebooks (shard ${{ matrix.shard }})
     strategy:
-      fail-fast: true
+      # Shards partition the ~37 executed notebooks so no single job can hit
+      # the 6-hour limit; fail-fast off so a drift run reports the full blast
+      # radius, not just the first broken shard.
+      fail-fast: false
       matrix:
-        python-version: ["3.12"]
+        python-version: ["3.13"]
+        shard: [0, 1, 2, 3]
 
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v6
+        uses: actions/checkout@v7
 
       - name: Setup environment
         uses: ./.github/setup-env-notebooks
@@ -27,18 +31,27 @@ jobs:
       - name: Run notebooks
         run: |
           echo "Running notebooks with Python ${{ matrix.python-version }}"
-          # List of notebooks to skip (temporarily)
+          # List of notebooks to skip (temporarily). Entries must be the
+          # full find-produced path — bare filenames never match the loop
+          # comparison (the two workshop notebooks executed for months while
+          # "skipped").
           SKIP_NOTEBOOKS=(
             "docs/tutorials/tutorial_bayeux.ipynb"
-            "rlssm_rlwm_model.ipynb"
-            "rlssm_tutorial.ipynb"
-            "add_custom_rlssm_model.ipynb"
-            "hssm_tutorial_workshop_1.ipynb"
-            "hssm_tutorial_workshop_2.ipynb"
+            "docs/tutorials/hsgp_regression.ipynb"
+            "docs/tutorials/hssm_tutorial_workshop_1.ipynb"
+            "docs/tutorials/hssm_tutorial_workshop_2.ipynb"
+            "docs/tutorials/rsssm_regime_switching.ipynb"
+            "docs/tutorials/rsssm_k3.ipynb"
           )
 
           EXIT_CODE=0
-          for notebook in $(find docs -name "*.ipynb"); do
+          INDEX=0
+          for notebook in $(find docs -name "*.ipynb" | sort); do
+            THIS_INDEX=$INDEX
+            INDEX=$((INDEX + 1))
+            if [ $((THIS_INDEX % 4)) -ne ${{ matrix.shard }} ]; then
+              continue
+            fi
             # Check if notebook is in skip list
             SKIP=false
             for skip_nb in "${SKIP_NOTEBOOKS[@]}"; do
@@ -61,5 +74,3 @@ jobs:
             fi
           done
           exit $EXIT_CODE
-        env:
-          PYTENSOR_FLAGS: ${{ env.PYTENSOR_FLAGS }}