Bump ci to use python 3.13, modernize type hints

.azure-pipelines/gpu-tests.yml

@@ -48,7 +48,7 @@ jobs:
     strategy:
       matrix:
         PyTorch_latest:
-          image: speediedan/interpretune:py3.12-pt2.9.1-azpl-init
+          image: speediedan/interpretune:py3.13-pt2.9.1-azpl-init
           scope: ""
     timeoutInMinutes: 100
     cancelTimeoutInMinutes: 2

.github/ISSUE_TEMPLATE/bug_report.md

@@ -44,7 +44,7 @@ You can also fill out the list below manually.
 - TransformerLens Version (e.g., 2.16.1):
 - SAELens Version (e.g., 6.3.1):
 - Lightning Version (e.g., 2.5.1):
-- Python version (e.g., 3.12):
+- Python version (e.g., 3.13):
 - OS (e.g., Linux):
 - CUDA/cuDNN version:
 - GPU models and configuration:

.github/actions/install-ci-dependencies/action.yml

@@ -5,7 +5,7 @@ inputs:
   python_version:
     description: "Python version to use"
     required: false
-    default: "3.12"
+    default: "3.13"
   show_pip_list:
     description: "Whether to show package list output after installations"
     required: false

.github/actions/regen-ci-reqs/action.yml

@@ -4,7 +4,7 @@ inputs:
   python_version:
     description: 'Python version to setup'
     required: false
-    default: '3.12'
+    default: '3.13'
   ci_output_dir:
     description: Directory where regen writes CI output (defaults to requirements/ci)
     required: false

.github/copilot-instructions.md

@@ -5,7 +5,7 @@
 **Interpretune** is a flexible, powerful framework for collaborative AI world model analysis and tuning. This project is in **pre-MVP** stage - features and APIs are subject to change.
 
 **Key Technologies:**
-- Python 3.10+ (CI tests on 3.12)
+- Python 3.10+ (CI tests on 3.13)
 - PyTorch 2.7.1+ with transformers ecosystem
 - Core deps: transformer_lens >= 3.0.0 (TransformerBridge support), sae_lens, datasets, jsonargparse
 - Optional: PyTorch Lightning, W&B, circuit-tracer, neuronpedia
@@ -260,7 +260,7 @@ src/it_examples/            # Example experiments
 **File:** `.github/workflows/ci_test-full.yml`
 
 **Triggers:** Push/PR to main, changes to source/test files
-**Platforms:** Ubuntu 22.04, Windows 2022, macOS 14 (Python 3.12)
+**Platforms:** Ubuntu 22.04, Windows 2022, macOS 14 (Python 3.13)
 **Timeout:** 90 minutes
 
 **CI Process:**

.github/workflows/ci_test-full.yml

@@ -129,7 +129,7 @@ jobs:
           windows-2022,
           macos-14
           ]
-        python-version: ["3.12"]
+        python-version: ["3.13"]
     timeout-minutes: 90
     env:
       WANDB_API_KEY: ${{ secrets.WANDB_API_KEY }}

.github/workflows/copilot-setup-steps.yml

@@ -30,7 +30,7 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@v5
         with:
-          python-version: '3.12'
+          python-version: '3.13'
 
       - name: Install CI dependencies
         uses: ./.github/actions/install-ci-dependencies

.github/workflows/regen-ci-req-check.yml

@@ -19,7 +19,7 @@ jobs:
         uses: ./.github/actions/regen-ci-reqs
         id: regen_ci_reqs
         with:
-          python_version: '3.12'
+          python_version: '3.13'
           ci_output_dir: requirements/ci
           compare_paths: "requirements/ci/requirements.txt"
           patch_path: /tmp/regen_diff.patch

.github/workflows/regen-ci-req-report.yml

@@ -60,7 +60,7 @@ jobs:
         uses: ./.github/actions/regen-ci-reqs
         id: regen_ci_reqs
         with:
-          python_version: '3.12'
+          python_version: '3.13'
           ci_output_dir: requirements/ci
           compare_paths: "requirements/ci/requirements.txt"
           patch_path: /tmp/regen_diff.patch

.github/workflows/release_pypi.yml

@@ -65,7 +65,7 @@ jobs:
     - uses: actions/checkout@v4
     - uses: actions/setup-python@v5
       with:
-        python-version: '3.12'
+        python-version: '3.13'
 
     - name: Install dependencies
       run: >-

.github/workflows/type-check.yml

@@ -55,10 +55,10 @@ jobs:
       IT_USE_CT_COMMIT_PIN: "1"
     steps:
       - uses: actions/checkout@v4
-      - name: Set up Python 3.12
+      - name: Set up Python 3.13
         uses: actions/setup-python@v5
         with:
-          python-version: "3.12"
+          python-version: "3.13"
 
       - name: Reset caching
         id: set_time_period
@@ -75,9 +75,9 @@ jobs:
         uses: actions/cache@v4
         with:
           path: ${{ env.PIP_CACHE_DIR }}/wheels
-          key: ubuntu-22.04-pip-wheels-${{ steps.set_time_period.outputs.TIME_PERIOD }}-py3.12-${{ hashFiles('requirements/ci/requirements.txt') }}
+          key: ubuntu-22.04-pip-wheels-${{ steps.set_time_period.outputs.TIME_PERIOD }}-py3.13-${{ hashFiles('requirements/ci/requirements.txt') }}
           restore-keys: |
-            ubuntu-22.04-pip-wheels-${{ steps.set_time_period.outputs.TIME_PERIOD }}-py3.12-
+            ubuntu-22.04-pip-wheels-${{ steps.set_time_period.outputs.TIME_PERIOD }}-py3.13-
 
       - name: Install CI dependencies
         uses: ./.github/actions/install-ci-dependencies

dockers/base-cuda/Dockerfile

@@ -16,7 +16,7 @@ ARG OS_VER=ubuntu22.04
 
 FROM nvidia/cuda:${CUDA_VERSION}-devel-${OS_VER}
 
-ARG PYTHON_VERSION=3.12
+ARG PYTHON_VERSION=3.13
 ARG PYTORCH_VERSION=2.9.1
 ARG CUST_BUILD=0
 ARG MKL_THREADING_LAYER=GNU

dockers/docker_images_main.sh

@@ -43,7 +43,7 @@ maybe_build(){
 build_eval(){
 	# latest PyTorch image supported by release
 	# see CUDA_ARCHES_FULL_VERSION for the full version of the pytorch-provided toolkit
-	declare -A iv=(["cuda"]="12.8.1" ["python"]="3.12" ["pytorch"]="2.9.1" ["cust_build"]="1")
+	declare -A iv=(["cuda"]="12.8.1" ["python"]="3.13" ["pytorch"]="2.9.1" ["cust_build"]="1")
 	export latest_pt="base-cu${iv["cuda"]}-py${iv["python"]}-pt${iv["pytorch"]}"
 	export latest_azpl="py${iv["python"]}-pt${iv["pytorch"]}-azpl-init"
 	maybe_build iv "${latest_pt}" "${latest_azpl}"

dockers/docker_images_release.sh

@@ -41,7 +41,7 @@ maybe_build(){
 
 build_eval(){
 	# latest PyTorch image supported by release
-	declare -A iv=(["cuda"]="12.8.1" ["python"]="3.12" ["pytorch"]="2.9.1" ["cust_build"]="0")
+	declare -A iv=(["cuda"]="12.8.1" ["python"]="3.13" ["pytorch"]="2.9.1" ["cust_build"]="0")
 	export latest_pt="base-cu${iv["cuda"]}-py${iv["python"]}-pt${iv["pytorch"]}"
 	export latest_azpl="py${iv["python"]}-pt${iv["pytorch"]}-azpl-init"
 	maybe_build iv "${latest_pt}" "${latest_azpl}"

dockers/it-az-base/Dockerfile

@@ -10,7 +10,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-ARG PYTHON_VERSION=3.12
+ARG PYTHON_VERSION=3.13
 ARG PYTORCH_VERSION=2.9.1
 ARG CUST_BASE
 

pyproject.toml

@@ -28,6 +28,7 @@ classifiers = [
             "Programming Language :: Python :: 3.10",
             "Programming Language :: Python :: 3.11",
             "Programming Language :: Python :: 3.12",
+            "Programming Language :: Python :: 3.13",
 ]
 description = "A package to support LLM reasoning and interpretability experiments at a level of abstraction that is both powerfully flexible and convenient"
 readme = "README.md"
@@ -36,7 +37,7 @@ dependencies = [
     "transformers>=4.57.1",
     "tabulate >= 0.9.0",
     "datasets >= 4.0.0",
-    "jsonargparse[signatures] >= 4.35.0,<4.42.0",  # upstream regression with 4.42, replace this req once adding fts req
+    "jsonargparse[signatures] >= 4.35.0,<4.42.0",  # TODO: investigate upstream regression w/ 4.42, remove if fts is req
     # "finetuning-scheduler[possible_future_it_plugin] >= 2.5.0",
 ]
 
@@ -93,7 +94,7 @@ examples = [
 git-deps = [
     "circuit-tracer @ git+https://github.com/speediedan/circuit-tracer.git@004f1b2822eca3f0c1ddd2389e9105b3abffde87",
     "transformer-lens @ git+https://github.com/speediedan/TransformerLens.git@d35d01feb9cc076a091e41255e1c9f92de2af236",
-    "finetuning-scheduler @ git+https://github.com/speediedan/finetuning-scheduler.git@4aa64032c07acd34493a5c05929845bd011426c9",
+    "finetuning-scheduler @ git+https://github.com/speediedan/finetuning-scheduler.git@a96d8158ee92dddb3eb5203095ce9db98c137fd0",
     "sae_lens >= 6.3.1",
 ]
 

requirements/ci/requirements.txt

@@ -7,9 +7,7 @@ accelerate==1.12.0
 aiohappyeyeballs==2.6.1
     # via aiohttp
 aiohttp==3.13.3
-    # via
-    #   fsspec
-    #   papermill
+    # via fsspec
 aiosignal==1.4.0
     # via aiohttp
 annotated-types==0.7.0
@@ -86,7 +84,7 @@ cryptography==46.0.3 ; platform_machine != 'ppc64le' and platform_machine != 's3
     # via secretstorage
 cycler==0.12.1
     # via matplotlib
-datasets==4.4.2
+datasets==4.5.0
     # via
     #   interpretune (pyproject.toml)
     #   evaluate
@@ -137,7 +135,7 @@ fsspec[http]==2025.10.0
     #   evaluate
     #   huggingface-hub
     #   torch
-gdown==5.2.0
+gdown==5.2.1
     # via interpretune (pyproject.toml)
 gitdb==4.0.12
     # via gitpython
@@ -166,7 +164,7 @@ huggingface-hub[hf-xet]==0.36.0
     #   transformers
 id==1.5.0
     # via twine
-identify==2.6.15
+identify==2.6.16
     # via pre-commit
 idna==3.11
     # via
@@ -196,7 +194,7 @@ isoduration==20.11.0
     # via jsonschema
 jaraco-classes==3.4.0 ; platform_machine != 'ppc64le' and platform_machine != 's390x'
     # via keyring
-jaraco-context==6.0.2 ; platform_machine != 'ppc64le' and platform_machine != 's390x'
+jaraco-context==6.1.0 ; platform_machine != 'ppc64le' and platform_machine != 's390x'
     # via keyring
 jaraco-functools==4.4.0 ; platform_machine != 'ppc64le' and platform_machine != 's390x'
     # via keyring
@@ -254,9 +252,9 @@ jupyter-server==2.17.0
     #   jupyterlab-server
     #   notebook
     #   notebook-shim
-jupyter-server-terminals==0.5.3
+jupyter-server-terminals==0.5.4
     # via jupyter-server
-jupyterlab==4.5.1
+jupyterlab==4.5.2
     # via
     #   interpretune (pyproject.toml)
     #   notebook
@@ -348,13 +346,13 @@ nodeenv==1.10.0
     # via
     #   pre-commit
     #   pyright
-notebook==7.5.1
+notebook==7.5.2
     # via interpretune (pyproject.toml)
 notebook-shim==0.2.4
     # via
     #   jupyterlab
     #   notebook
-numpy==2.4.0
+numpy==2.4.1
     # via
     #   accelerate
     #   bitsandbytes
@@ -454,23 +452,23 @@ platformdirs==4.5.1
     #   jupyter-core
     #   virtualenv
     #   wandb
-plotly==6.5.1
+plotly==6.5.2
     # via interpretune (pyproject.toml)
 pluggy==1.6.0
     # via pytest
 pre-commit==4.5.1
     # via
     #   interpretune (pyproject.toml:dev)
     #   interpretune (pyproject.toml:test)
-prometheus-client==0.23.1
+prometheus-client==0.24.1
     # via jupyter-server
 prompt-toolkit==3.0.52
     # via ipython
 propcache==0.4.1
     # via
     #   aiohttp
     #   yarl
-protobuf==6.33.2
+protobuf==6.33.4
     # via
     #   tensorboard
     #   wandb
@@ -568,7 +566,7 @@ referencing==0.37.0
     #   jsonschema
     #   jsonschema-specifications
     #   jupyter-events
-regex==2025.11.3
+regex==2026.1.15
     # via transformers
 requests[socks]==2.32.5
     # via
@@ -611,11 +609,11 @@ safetensors==0.7.0
     #   transformers
 scikit-learn==1.8.0
     # via interpretune (pyproject.toml)
-scipy==1.16.3
+scipy==1.17.0
     # via scikit-learn
 secretstorage==3.5.0 ; platform_machine != 'ppc64le' and platform_machine != 's390x' and sys_platform == 'linux'
     # via keyring
-send2trash==2.0.0
+send2trash==2.1.0
     # via jupyter-server
 sentry-sdk==2.49.0
     # via wandb
@@ -697,7 +695,7 @@ traitlets==5.14.3
     #   nbclient
     #   nbconvert
     #   nbformat
-transformers==4.57.3
+transformers==4.57.5
     # via
     #   interpretune (pyproject.toml)
     #   peft
@@ -709,16 +707,12 @@ typeshed-client==2.8.2
     # via jsonargparse
 typing-extensions==4.15.0
     # via
-    #   aiosignal
-    #   anyio
     #   beautifulsoup4
     #   grpcio
     #   huggingface-hub
-    #   psycopg
     #   pydantic
     #   pydantic-core
     #   pyright
-    #   referencing
     #   torch
     #   typeshed-client
     #   typing-inspection
@@ -737,13 +731,13 @@ urllib3==2.6.3
     #   requests
     #   sentry-sdk
     #   twine
-uv==0.9.22
+uv==0.9.26
     # via
     #   interpretune (pyproject.toml:dev)
     #   interpretune (pyproject.toml:test)
 virtualenv==20.36.1
     # via pre-commit
-wandb==0.23.1
+wandb==0.24.0
     # via interpretune (pyproject.toml)
 wcwidth==0.2.14
     # via prompt-toolkit

scripts/build_it_env.sh

@@ -155,7 +155,7 @@ clear_activate_env(){
 base_env_build(){
     case ${target_env_name} in
         it_latest)
-            clear_activate_env python3.12
+            clear_activate_env python3.13
             if [[ -n ${torch_dev_ver} ]]; then
                 # temporarily remove torchvision until it supports cu128 in nightly binary
                 uv pip install ${uv_install_flags} --pre torch==2.10.0.${torch_dev_ver} --index-url https://download.pytorch.org/whl/nightly/cu128
@@ -166,7 +166,7 @@ base_env_build(){
             fi
             ;;
         it_release)
-            clear_activate_env python3.12
+            clear_activate_env python3.13
             uv pip install ${uv_install_flags} torch --index-url https://download.pytorch.org/whl/cu128
             ;;
         *)

src/interpretune/adapter_registry.py

@@ -9,7 +9,7 @@
 
 import logging
 import threading
-from typing import Any, Optional
+from typing import Any
 
 from interpretune.adapters.registration import CompositionRegistry
 
@@ -25,7 +25,7 @@ class LazyCompositionRegistry:
     """
 
     def __init__(self) -> None:
-        self._registry: Optional[CompositionRegistry] = None
+        self._registry: CompositionRegistry | None = None
         self._lock = threading.RLock()
 
     def _ensure_initialized(self) -> None: