Adopt PDM and pytest

.github/workflows/quality.yml

@@ -0,0 +1,48 @@
+name: Quality
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    types: [opened, synchronize, reopened, ready_for_review]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: quality-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  quality:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: pdm-project/setup-pdm@v4
+        with:
+          python-version: "3.12"
+          version: "2.29.2"
+          cache: true
+      - run: pdm install --check --no-default --no-self -G quality
+      - run: make lint
+      - run: make build
+
+  tests:
+    runs-on: ubuntu-24.04
+    env:
+      HF_HUB_OFFLINE: "1"
+      TRANSFORMERS_OFFLINE: "1"
+    steps:
+      - uses: actions/checkout@v7
+      - name: Make room for the locked ROCm runtime
+        # Torch alone occupies about 14 GiB; these SDKs are unused by this job.
+        run: sudo rm -rf /usr/local/lib/android /usr/share/dotnet
+      - uses: pdm-project/setup-pdm@v4
+        with:
+          python-version: "3.12"
+          version: "2.29.2"
+      - run: pdm --no-cache install --check -G train -G agent -G quality
+      - run: pdm run typecheck
+      - name: Run pytest
+        run: make test

.github/workflows/website.yml

@@ -10,6 +10,10 @@ on:
       - "assets/dohnuts-logo.png"
       - "results/**"
       - "pyproject.toml"
+      - "pdm.lock"
+      - "pdm.toml"
+      - "Makefile"
+      - ".python-version"
       - "LICENSE"
       - "NOTICE"
       - ".github/workflows/website.yml"
@@ -23,6 +27,10 @@ on:
       - "assets/dohnuts-logo.png"
       - "results/**"
       - "pyproject.toml"
+      - "pdm.lock"
+      - "pdm.toml"
+      - "Makefile"
+      - ".python-version"
       - "LICENSE"
       - "NOTICE"
       - ".github/workflows/website.yml"
@@ -36,13 +44,13 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v7
-      - uses: actions/setup-python@v7
+      - uses: pdm-project/setup-pdm@v4
         with:
           python-version: "3.12"
-          cache: pip
-          cache-dependency-path: docs/requirements.txt
-      - run: python -m pip install -r docs/requirements.txt
-      - run: python -m sphinx -b html -W --keep-going -d build/doctrees -c docs . build/site
+          version: "2.29.2"
+          cache: true
+      - run: make docs-install
+      - run: make docs
       - uses: actions/upload-pages-artifact@v4
         with:
           path: build/site

.gitignore

@@ -1,5 +1,7 @@
 # Local environments and caches
 .venv/
+.pdm-python
+__pypackages__/
 __pycache__/
 .pytest_cache/
 .ruff_cache/

.pre-commit-config.yaml

@@ -0,0 +1,13 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: check-case-conflict
+      - id: check-merge-conflict
+      - id: check-toml
+      - id: check-yaml
+      - id: check-json
+      - id: end-of-file-fixer
+        exclude: ^(data/manifests/|docs/figures/|results/)
+      - id: trailing-whitespace
+        exclude: ^(data/manifests/|docs/figures/|results/)

.python-version

@@ -0,0 +1 @@
+3.12

Makefile

@@ -0,0 +1,39 @@
+.DEFAULT_GOAL := help
+
+.PHONY: help install lock lint check format test build docs-install docs docs-preview
+
+help: ## Show available targets
+	@awk 'BEGIN {FS = ":.*## "}; /^[a-zA-Z0-9_-]+:.*## / {printf "%-18s %s\n", $$1, $$2}' $(MAKEFILE_LIST)
+
+install: ## Install locked runtime, training, agent, and quality dependencies
+	pdm install --check -G train -G agent -G quality
+
+lock: ## Resolve all groups for the recorded Python 3.12 environment
+	pdm lock -G:all --python "==3.12.*"
+
+lint: ## Verify the lock, repository hygiene, and Python lint/formatting
+	pdm lock --check
+	pdm run prek run --all-files
+	pdm run lint
+	pdm run format-check
+
+check: lint ## Run all quality checks, including types against installed dependencies
+	pdm run typecheck
+
+format: ## Format Python code
+	pdm run format
+
+test: ## Run pytest without loading model weights
+	pdm run test
+
+build: ## Build the source distribution and wheel
+	pdm build
+
+docs-install: ## Install only the locked documentation dependencies
+	pdm install --check --no-default --no-self -G docs
+
+docs: ## Build the static website with warnings treated as errors
+	pdm run docs
+
+docs-preview: docs ## Serve the built website on localhost:8000
+	pdm run docs-serve

README.md

@@ -52,7 +52,7 @@ One workflow prepares the public-data mixture, trains with joint RLCD and
 cross-entropy, selects a checkpoint, calibrates it, and runs the evaluations:
 
 ```bash
-.venv/bin/python scripts/run_experiment.py
+pdm run python scripts/run_experiment.py
 ```
 
 The [training guide](docs/run-experiment.md) covers setup and resuming a run.

docs/README.md

@@ -23,13 +23,14 @@
 The [behavior and regression tests](design.md#behavior-and-regression-tests)
 cover the prediction interface and known failure cases.
 
-For website contributors, see [Build the website](website.md).
+For contributors, see [Development](development.md) and [Build the website](website.md).
 
 ```{toctree}
 :hidden:
 
 Installation and inference <inference>
 Agent integration <bub-agent>
 Training and evaluation <run-experiment>
+Development <development>
 Build the website <website>
 ```

docs/bub-agent.md

@@ -7,6 +7,10 @@ to provide one batch decision tool and persistent session tapes.
 
 Follow the [runtime and checkpoint setup](inference.md) first.
 
+```bash
+pdm install --check --prod -G agent
+```
+
 ```python
 from pathlib import Path
 
@@ -18,6 +22,7 @@ framework, agent = create_agent(
     predictor, workspace=Path.cwd(), tape_directory=Path("runs/agent-tapes")
 )
 
+
 async def decide():
     command = ',dohnuts.decide state=\'{"message":"Please refund this invoice."}\' '
     command += 'questions=\'{"refund":{"type":"noul","instructions":"Is a refund requested?"}}\''

docs/compute-efficiency.md

@@ -104,7 +104,7 @@ exact training ETA. Hardware microbenchmark throughput is not API throughput.
 ## Measurement
 
 ```bash
-.venv/bin/python scripts/benchmark.py dohnuts --checkpoint runs/v1/checkpoint --output runs/v1/benchmarks/dohnuts.jsonl
+pdm run python scripts/benchmark.py dohnuts --checkpoint runs/v1/checkpoint --output runs/v1/benchmarks/dohnuts.jsonl
 ```
 
 The benchmark measures complete prediction calls over text and image workloads,

docs/conf.py

@@ -1,8 +1,7 @@
 """Build the static website from the repository's existing Markdown."""
 
-from pathlib import Path
 import tomllib
-
+from pathlib import Path
 
 metadata = tomllib.loads((Path(__file__).parents[1] / "pyproject.toml").read_text())
 project = "Dohnuts"

docs/design.md

@@ -78,7 +78,7 @@ identical screenshots crossed splits under different source IDs. Run them when
 changing the corresponding behavior:
 
 ```bash
-.venv/bin/python -m unittest discover -s tests
+make test
 ```
 
 Tests assert observable behavior or a known failure case. Internal allocation,

docs/development.md

@@ -0,0 +1,75 @@
+# Development
+
+Use Python 3.12 and [PDM](https://pdm-project.org/en/latest/#installation) 2.29.2
+or a newer 2.x release. The runtime targets the Linux/ROCm environment documented
+in the [inference guide](inference.md). The quality and documentation groups can
+be installed without model dependencies.
+
+```bash
+pdm use 3.12
+make install
+make check
+make test
+make build
+```
+
+`make install` installs the runtime, training and agent dependencies, and quality
+tools. For editing documentation only, use `make docs-install`.
+Run `make help` to see the available targets.
+
+## Dependencies
+
+`pyproject.toml` owns the package metadata, dependencies, tool settings, and PDM
+commands. `pdm.lock` records the resolution for Python 3.12, including the pinned
+Bub Git revision and the ROCm package artifacts. The published experiment's
+environment snapshot remains historical evidence, not an installation input.
+
+| Selection | Purpose |
+| --- | --- |
+| Default dependencies | Model runtime |
+| `train` extra | Training, evaluation, and the unit tests' data dependencies |
+| `agent` extra | The pinned Bub SDK integration |
+| `quality` group | Ruff, ty, prek, and pytest |
+| `docs` group | Sphinx, Furo, and MyST |
+| `plot` group | Rendering saved evaluation results |
+
+After changing dependencies, run `make lock`, review the lock diff, and install
+the relevant groups with `pdm install --check`. CI refuses a missing or stale
+lock rather than resolving different versions. Avoid replacing a trained run's
+environment while it is active.
+
+Keep `use_uv = false` in `pdm.toml`: PDM's experimental uv mode does not support
+the package-to-index bindings used for ROCm. Other packages resolve from PyPI.
+
+## Checks and builds
+
+`make check` verifies the lock, repository hygiene, Ruff lint and formatting,
+and ty checks for `src` against the installed dependencies. `make lint` runs the
+checks that only need the `quality` group. `pdm run prek install` optionally
+installs the same hygiene hooks locally; installing hooks is not required to run
+the checks.
+
+`make test` runs pytest, including the pinned RLCD loss and
+gradient values, prefix-cache updates and gradients, calibration metrics, and
+data-split isolation. It does not load
+model weights, download data, or prove GPU training/inference acceptance. CI runs
+these tests with Hugging Face access disabled. GPU acceptance remains a separate
+step for changes to execution or training.
+
+Run an individual file or case with `pdm run pytest tests/test_rlcd.py` or
+`pdm run pytest -k gradients`. Test discovery is limited to `tests/` in
+`pyproject.toml`.
+
+The test job installs the same locked ROCm wheels, checks types, and runs the tests
+on CPU. It removes unused Android and .NET SDKs from its temporary Ubuntu runner to make
+room for Torch, and skips the large dependency cache. Quality and website jobs
+do not install the model runtime.
+
+`make build` uses `pdm-backend` to produce a wheel and source distribution in
+`dist/`. Local model weights, datasets, caches, and experiment runs are excluded.
+The CI build does not publish packages. Website validation and deployment use
+the separate [website workflow](website.md).
+
+The Make targets and separated quality/test jobs adapt the relevant parts of
+[Bub's Makefile](https://github.com/bubbuild/bub/blob/main/Makefile) and
+[CI](https://github.com/bubbuild/bub/blob/main/.github/workflows/main.yml).

docs/figures/README.md

@@ -58,7 +58,7 @@ The figures are available as SVG. Captions document each evaluation protocol. On
 Follow the [plotting setup](../local-benchmarks.md#model-card-figures), then run from the repository root:
 
 ```sh
-.cache/plot-venv/bin/python scripts/plot_model_card.py --run runs/v1
+pdm run python scripts/plot_model_card.py --run runs/v1
 ```
 
 The command writes PNG, SVG, and PDF figures to the experiment output directory.

docs/inference.md

@@ -1,24 +1,30 @@
 # Installation and inference
 
 The measured runtime uses Python 3.12, PyTorch 2.9.1 with ROCm 6.4, and an
-AMD Radeon RX 7900 XTX. Install from source with the ROCm wheels first:
+AMD Radeon RX 7900 XTX. Install [PDM](https://pdm-project.org/en/latest/#installation)
+2.29.2 or a newer 2.x release, then install from source:
 
 ```bash
 git clone https://github.com/PsiACE/dohnuts.git
 cd dohnuts
-uv venv --python 3.12
-uv pip install --python .venv/bin/python torch==2.9.1 torchvision==0.24.1 --index-url https://download.pytorch.org/whl/rocm6.4
-uv pip install --python .venv/bin/python -e .
+pdm use 3.12
+pdm install --check --prod
 ```
 
+The lock file targets Python 3.12. The package sources in `pyproject.toml` bind
+PyTorch, torchvision, and PyTorch's Triton runtime to the ROCm 6.4 index.
+Keep PDM's native resolver enabled: its experimental uv resolver does not support
+these package-to-index bindings. See [development](development.md) for dependency
+groups, checks, and updating the lock.
+
 ## Load a checkpoint
 
 Load the model by its Hugging Face repository ID. The loader downloads the
 decision weights and the exact Qwen3.5-0.8B revision recorded in the checkpoint.
 Downloads use the Hugging Face cache and are reused by later calls. Both
 repositories are public; downloading them does not require a Hugging Face login.
 
-Run Python examples with `.venv/bin/python` from the repository root:
+Run Python examples with `pdm run python` from the repository root:
 
 ```python
 from dohnuts.predictor import Predictor

docs/local-benchmarks.md

@@ -34,7 +34,7 @@ pinned at `e105a48f8cdb7f3babb3594424f73e5d7bdc97b9`. Its public tasks contain
 534-item leaderboard are not distributed, including the entire judge tier.
 
 ```bash
-.venv/bin/python scripts/run_jevbench.py
+pdm run python scripts/run_jevbench.py
 ```
 
 Each task receives one serial `Predictor.predict` call with its original state,
@@ -61,9 +61,9 @@ measurements in its comparison chart. Run them on the exported Dohnuts checkpoin
 ```bash
 git clone --branch research https://github.com/NandhaKishorM/laya.git .cache/upstream/laya-research
 git -C .cache/upstream/laya-research checkout --detach 28d43add7e47ce502489c9433310d55276c64e0f
-uv pip install --python .venv/bin/python datasets==5.0.1
-.venv/bin/python scripts/prepare_laya_benchmark.py
-.venv/bin/python scripts/run_laya_benchmark.py
+pdm install --check --prod -G train
+pdm run python scripts/prepare_laya_benchmark.py
+pdm run python scripts/run_laya_benchmark.py
 ```
 
 Preparation preserves the upstream builders, seed 13, candidate order, and
@@ -102,13 +102,12 @@ and paired JevBench outcomes. The reference checkpoints are Laya multilingual
 and Laya Vision. The English Laya entry in JevBench's published results is a
 different checkpoint and must not be relabeled as Laya multilingual.
 
-Install plotting tools in a separate environment to keep the training runtime
-unchanged, then render the completed run:
+Install the locked plotting group, then render the completed run. This group
+does not require model dependencies:
 
 ```bash
-uv venv --python 3.12 .cache/plot-venv
-uv pip install --python .cache/plot-venv/bin/python matplotlib==3.11.2 numpy==2.5.3
-.cache/plot-venv/bin/python scripts/plot_model_card.py --run runs/v1
+pdm install --check --no-default --no-self -G plot
+pdm run python scripts/plot_model_card.py --run runs/v1
 ```
 
 `runs/v1/figures/README.md` indexes the PNG, SVG and PDF figures. The directory