chore: 🔧 root-level AGENTS.md, Python 3.11 support and prek

.devcontainer/postStartCommand.sh

@@ -4,5 +4,5 @@
 # install project with all dependencies (no GPU extras in devcontainer)
 uv sync --all-groups
 
-# install pre-commit hooks
-uv run pre-commit install --install-hooks
+# install the git hook shims
+uv run prek install --prepare-hooks

.github/copilot-instructions.md

@@ -0,0 +1 @@
+../AGENTS.md

.github/workflows/lint.yml

@@ -15,12 +15,12 @@ jobs:
       - name: Check out repository
         uses: actions/checkout@v7
         with:
-          # grab the history of the PR, so we can run pre-commit on a commit range
+          # grab the history of the PR, so we can run prek on a commit range
           fetch-depth: 0
 
-      - name: Run pre-commit for linting
-        uses: pre-commit/action@v3.0.1
+      - name: Run prek for linting
+        uses: j178/prek-action@v3.0.0
         env:
           RUFF_OUTPUT_FORMAT: github
         with:
-          extra_args: --from-ref ${{ github.event.pull_request.base.sha }} --to-ref ${{ github.event.pull_request.head.sha }}
+          extra-args: --from-ref ${{ github.event.pull_request.base.sha }} --to-ref ${{ github.event.pull_request.head.sha }}

.github/workflows/test.yml

@@ -42,7 +42,7 @@ jobs:
           - ubuntu-latest
           - gpu-runner
         python-version:
-          - "3.12"
+          - "3.11"
           - "3.14"
         test-group:
           - "not slow and not perf"
@@ -128,6 +128,24 @@ jobs:
             coverage-*.xml
           retention-days: 1
 
+  test-matrix:
+    # The ruleset requires a check named after this workflow, but the matrix
+    # only ever reports per-combination names. This job publishes that name and
+    # keeps it independent of the matrix dimensions.
+    name: Test src_method
+    if: always()
+    needs: test
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Report the matrix result
+        run: |
+          echo "test: ${{ needs.test.result }}"
+          case "${{ needs.test.result }}" in
+            success|skipped) ;;
+            *) exit 1 ;;
+          esac
+
   benchmark:
     # Fails on a median slowdown of more than 25%. The threshold is wide
     # because this runs on a shared runner, where no-op PRs have drifted by

.github/workflows/update-ruff.yml

@@ -48,11 +48,11 @@ jobs:
             sed -i -E "s/ruff==([0-9]+\.[0-9]+\.[0-9]+)/ruff==${{ env.RUFF_VERSION }}/" pyproject.toml
           fi
 
-      - name: Update ruff version in .pre-commit-config.yaml
+      - name: Update ruff version in prek.toml
         if: env.NEEDS_UPDATE == 'true'
         run: |
-          if grep -q "https://github.com/astral-sh/ruff-pre-commit" .pre-commit-config.yaml; then
-            sed -i -E "/repo: https:\/\/github.com\/astral-sh\/ruff-pre-commit/,/rev:/ s/rev: v([0-9]+\.[0-9]+\.[0-9]+)/rev: v${{ env.RUFF_VERSION }}/" .pre-commit-config.yaml
+          if grep -q "https://github.com/astral-sh/ruff-pre-commit" prek.toml; then
+            sed -i -E '/repo = "https:\/\/github.com\/astral-sh\/ruff-pre-commit"/,/^rev = / s/^rev = "v[0-9]+\.[0-9]+\.[0-9]+"/rev = "v${{ env.RUFF_VERSION }}"/' prek.toml
           fi
 
       - name: Install the latest version of uv
@@ -96,7 +96,7 @@ jobs:
 
             Changes:
             - Updated version in `pyproject.toml`
-            - Updated version in `.pre-commit-config.yaml`
+            - Updated version in `prek.toml`
             - Ran `ruff format` on the codebase
             ${{ env.RUFF_CHECK_FAILED == 'true' && '- Attempted to run `ruff check --fix` on the codebase' || '- Ran `ruff check --fix` on the codebase' }}
 
@@ -109,5 +109,5 @@ jobs:
             dependencies
           add-paths: |
             pyproject.toml
-            .pre-commit-config.yaml
+            prek.toml
             **/*.py

AGENTS.md

@@ -0,0 +1,80 @@
+# src_method agent guide
+
+A pure-Python implementation of Successive Randomized Compression (SRC) for
+tensor networks. `apply` contracts and compresses MPO-MPS and MPO-MPO products,
+`compress` truncates a single MPO or MPS. Trains are plain lists of per-site
+NumPy arrays; MPS against MPO is inferred from the rank of the first site
+tensor, so there is no wrapper type.
+
+## Rules
+
+- Target Python 3.11-3.14. Type hints everywhere, `from __future__ import
+  annotations` at the top of every module.
+- Google-style docstrings without types (types live in the signature) on every
+  public function, class and module.
+- `ruff` is the source of truth for style: the formatter wraps at 88 columns
+  (`E501` only fires past 120), 4-space indent, the rule set in
+  `pyproject.toml`. Do not hand-format around it.
+- `snake_case` for functions and variables, `CamelCase` for classes. `N803` and
+  `N806` are off so that matrices can keep their mathematical names (`Q`, `R`,
+  `A`); that licence does not extend to anything else.
+- Comment invariants, contracts and non-obvious numerical choices only. Never
+  narrate the code.
+- Backend-agnostic code: go through `src_method.utils._backend` instead of
+  importing `numpy` or `cupy` directly in the algorithms, so CPU and GPU paths
+  stay in sync.
+- Log with `structlog` via `src_method.utils.logging_config`, never `print`.
+- **Run `uv run prek run --all-files` and the relevant tests before
+  pushing, and fix every finding.** `lint.yml` runs the same hooks in CI, so a
+  skipped lint is a red PR.
+- Changes to the API or to user-facing behavior -- developers included, e.g.
+  workflows or test layout -- belong in the docs and, when relevant, in
+  `README.md`. `docs/developer-guide/` covers versioning, dependencies and how
+  to write tests; read it before changing any of those.
+
+## Git and PRs
+
+- Commits and PR titles: `<type>(<optional scope>): <gitmoji> <description>`.
+  Types: `feat` (minor), `fix` (patch), `docs`, `style`, `refactor`, `test`,
+  `chore`; `!` for breaking changes.
+- Agent commits carry `Assisted-by: <harness>:<model>` and no `Co-authored-by`.
+- Prefix agent-authored PR descriptions and comments with
+  `:robot: _AI text below_ :robot:`.
+
+## Layout
+
+Package `src/src_method/`: `apply.py` and `compress.py` are the public entry
+points, `_tensor_train.py` holds the shared train helpers, `utils/_backend.py`
+the NumPy/CuPy dispatch and `utils/linalg.py` the decompositions. Tests in
+`tests/`, benchmarks in `benches/` with recorded results in
+`baseline-benchmarks/`, MkDocs sources in `docs/`, throwaway scripts in
+`sandbox/`.
+
+`src/src_method/_version.py` is generated by `hatch-vcs` -- never edit it.
+
+## Commands
+
+We use `uv` for environment management.
+
+```bash
+uv sync --all-groups --all-extras
+uv run prek install --prepare-hooks
+uv run pytest -m "not slow"    # fast suite
+uv run pytest                  # everything
+uv run ruff check src/ tests/
+uv run mkdocs serve
+```
+
+## Notes
+
+- `filterwarnings = ["error"]` is on: a stray warning fails the suite. Networks
+  with fewer than three sites intentionally warn and fall back to an exact SVD,
+  so those tests must assert the warning.
+- Markers: `slow` (>=1 minute) and `perf` (benchmark). Mark anything long, the
+  PR suite runs `-m "not slow"`.
+- GPU tests in `tests/test_gpu_backend.py` skip without CuPy; the GPU extras are
+  `gpu-nvidia` (CUDA) and `gpu-rocm`.
+- Array layouts follow the `quimb` conventions: MPO bulk tensors are
+  `('l', 'r', 'u', 'd')`, MPS bulk tensors `('l', 'r', 'u')`, boundary tensors
+  drop the outer bond index.
+- `apply` and `compress` are pure; never mutate the input arrays.

CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

CONTRIBUTING.md

@@ -24,18 +24,21 @@ of sites, the `dtype`, and the error metric you used.
 ## Development setup
 
 The repository ships a [Dev Container](https://containers.dev/) configuration
-that installs every dependency and the `pre-commit` hooks for you. If you would
+that installs every dependency and the git hooks for you. If you would
 rather set things up by hand, you need [`uv`](https://docs.astral.sh/uv/):
 
 ```bash
 uv sync --all-groups --all-extras
-uv run pre-commit install --install-hooks
+uv run prek install --prepare-hooks
 ```
 
+If your clone still carries the old `pre-commit` shims, add `--force` to
+replace them.
+
 ## Quality gates
 
-All of these must pass before a pull request can be merged; `pre-commit` runs
-the first two automatically.
+All of these must pass before a pull request can be merged;
+[`prek`](https://github.com/j178/prek) runs the first two automatically.
 
 ```bash
 uv run ruff check src/ tests/       # lint
@@ -59,7 +62,7 @@ accuracy, not just the shapes.
 
 ## Code style
 
-The project targets Python 3.12+ and is checked with `ruff` under a strict rule
+The project targets Python 3.11+ and is checked with `ruff` under a strict rule
 set. Public functions carry type hints and Google-style docstrings without type
 annotations in the argument list. Keep lines within the configured limit and
 prefer clear code over clever code.

README.md

@@ -108,7 +108,7 @@ Once the code is locally available, you can open its containing folder in
 [Visual Studio Code]. The editor will then set up the [DevContainer] for you.
 The first time you open the folder the startup will take a few minutes. Once the
 process is done, you will have _all_ project dependencies installed, including
-`pre-commit` hooks.
+the git hooks.
 [Visual Studio Code] will be already configured with all the extensions helpful for Python development.
 
 > [!TIP]
@@ -140,8 +140,8 @@ If you use [direnv], the provided `.envrc` enters the shell automatically:
 direnv allow
 ```
 
-Unlike the DevContainer, the Nix shell does not install the `pre-commit` hooks for
-you. Run `pre-commit install --install-hooks` once after the first `nix develop`.
+Unlike the DevContainer, the Nix shell does not install the git hooks for
+you. Run `prek install --prepare-hooks` once after the first `nix develop`.
 
 ## Documentation
 

docs/index.md

@@ -89,7 +89,7 @@ Once the code is locally available, you can open its containing folder in
 [Visual Studio Code]. The editor will then set up the [DevContainer] for you.
 The first time you open the folder the startup will take a few minutes. Once the
 process is done, you will have _all_ project dependencies installed, including
-`pre-commit` hooks.
+the git hooks.
 [Visual Studio Code] will be already configured with all the extensions helpful for Python development.
 
 **Note** that the order in which Visual Studio Code loads the extensions in the