pu-toolbox 1.0.0__tar.gz

pu_toolbox-1.0.0/.github/pull_request_template.md

@@ -0,0 +1,37 @@
+## 变更目的
+
+<!-- 说明问题、用户影响和本 PR 的边界。 -->
+
+## 主要修改
+
+<!-- 列出公共 API、算法、测试、文档或 benchmark 的关键变化。 -->
+
+## 验证
+
+- [ ] `python -m pytest -q`
+- [ ] `python scripts/check_format.py`（ruff check + format --check）
+- [ ] `python scripts/check_test_quality.py`
+- [ ] `python scripts/check_doc_links.py`
+- [ ] `python scripts/check_project_metadata.py`
+- [ ] `python scripts/check_math_rendering.py`
+- [ ] `python scripts/check_skill_sync.py`
+- [ ] `uv build`
+- [ ] `git diff --check`
+
+## 论文与实验边界
+
+- [ ] 不涉及论文算法或 benchmark
+- [ ] 已说明 official / clean-room / paper-like 状态
+- [ ] 配置、seed、数据来源和生成命令可以追溯
+- [ ] 未使用测试真值选择超参数、类先验或阈值
+
+## 兼容性与管理
+
+- [ ] 公共 API 和 registry metadata 已同步
+- [ ] 可选依赖缺失时基础导入仍可用
+- [ ] README、架构、目录结构和进度清单按需更新
+- [ ] 未提交凭据、本地环境文件或无关生成产物
+
+## 剩余风险
+
+<!-- 写明未覆盖的平台、依赖、数据、GPU 或复现风险。 -->

pu_toolbox-1.0.0/.github/workflows/nightly.yml

@@ -0,0 +1,44 @@
+name: nightly
+
+on:
+  schedule:
+    - cron: "23 3 * * 1" # every Monday 03:23 UTC (off-round minute)
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  slow-tests:
+    name: Slow tests (${{ matrix.os }}, Python ${{ matrix.python-version }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        python-version: ["3.10", "3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v5.1.0
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v9.0.0
+        with:
+          enable-cache: true
+          cache-dependency-glob: pyproject.toml
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v6.3.0
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        shell: bash
+        run: uv sync --python "${{ matrix.python-version }}" --extra dev --extra torch
+
+      - name: Verify matrix interpreter
+        shell: bash
+        run: uv run --python "${{ matrix.python-version }}" python -c "import sys; assert sys.version_info[:2] == tuple(map(int, '${{ matrix.python-version }}'.split('.')))"
+
+      - name: Run slow + e2e tests
+        shell: bash
+        run: uv run --python "${{ matrix.python-version }}" pytest tests/ -m "slow or e2e" -v

pu_toolbox-1.0.0/.github/workflows/tests.yml

@@ -0,0 +1,125 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  tests:
+    name: Tests (${{ matrix.os }}, Python ${{ matrix.python-version }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        python-version: ["3.10", "3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v5.1.0
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v9.0.0
+        with:
+          enable-cache: true
+          cache-dependency-glob: pyproject.toml
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v6.3.0
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        shell: bash
+        run: uv sync --python "${{ matrix.python-version }}" --extra dev --extra torch
+
+      - name: Verify matrix interpreter
+        shell: bash
+        run: uv run --python "${{ matrix.python-version }}" python -c "import sys; assert sys.version_info[:2] == tuple(map(int, '${{ matrix.python-version }}'.split('.')))"
+
+      - name: Run fast tests (unit + integration; e2e runs nightly)
+        shell: bash
+        run: uv run --python "${{ matrix.python-version }}" pytest tests/ -m "not slow and not e2e"
+
+  quality:
+    name: Static quality gates
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v5.1.0
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v9.0.0
+        with:
+          enable-cache: true
+          cache-dependency-glob: pyproject.toml
+
+      - name: Set up Python 3.11
+        uses: actions/setup-python@v6.3.0
+        with:
+          python-version: "3.11"
+
+      - name: Install development dependencies
+        run: uv sync --python "3.11" --extra dev
+
+      - name: Format gate (ruff check + format --check)
+        run: uv run --python "3.11" python scripts/check_format.py
+
+      - name: Test quality gate
+        run: uv run --python "3.11" python scripts/check_test_quality.py
+
+      - name: Doc consistency check
+        run: uv run --python "3.11" python scripts/check_doc_links.py
+
+      - name: Project metadata consistency check
+        run: uv run --python "3.11" python scripts/check_project_metadata.py
+
+      - name: Method card MathJax rendering check
+        run: uv run --python "3.11" python scripts/check_math_rendering.py
+
+      - name: Skill sync check
+        run: uv run --python "3.11" python scripts/check_skill_sync.py
+
+  package:
+    name: Build and install wheel
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v5.1.0
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v9.0.0
+        with:
+          enable-cache: true
+          cache-dependency-glob: pyproject.toml
+
+      - name: Set up Python 3.11
+        uses: actions/setup-python@v6.3.0
+        with:
+          python-version: "3.11"
+
+      - name: Build source and wheel distributions
+        run: uv build
+
+      - name: Install wheel in an isolated environment
+        run: |
+          uv venv --python "3.11" .wheel-venv
+          uv pip install --python .wheel-venv/bin/python dist/*.whl
+
+      - name: Smoke-test installed wheel outside the checkout
+        run: |
+          cd /tmp
+          "$GITHUB_WORKSPACE/.wheel-venv/bin/python" -c "import pu_toolbox; from pu_toolbox.diagnostics import build_diagnostic_report; from pu_toolbox.registry import register_all_builtin_methods, list_algorithms; register_all_builtin_methods(); assert len(list_algorithms()) > 0; assert pu_toolbox.__version__"
+
+      - name: Smoke-test console script entry point
+        run: |
+          cd /tmp
+          "$GITHUB_WORKSPACE/.wheel-venv/bin/pu-toolbox" list-methods >/dev/null
+          "$GITHUB_WORKSPACE/.wheel-venv/bin/pu-toolbox" list-priors >/dev/null

pu_toolbox-1.0.0/.gitignore

@@ -0,0 +1,67 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+*.egg
+.eggs/
+*.whl
+
+# Virtual environments
+.venv/
+.wheel-venv/
+venv/
+
+# Local environment and credentials
+.env
+.env.*
+!.env.example
+id_rsa
+id_rsa.pub
+id_ed25519
+id_ed25519.pub
+*.pem
+*.key
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Jupyter
+.ipynb_checkpoints/
+
+# Project-specific Claude Code config (not for distribution)
+CLAUDE.md
+
+# UV
+uv.lock
+.claude/*
+!.claude/skills/
+!.claude/skills/pu-workflow/
+.claude/skills/dev-workflow/
+
+# CLI demo / run artifacts (intermediate outputs)
+demo_data/
+results*/
+!benchmarks/assigned_methods/results/
+!benchmarks/assigned_methods/results/**
+
+# Local one-off plans (never for distribution)
+.superpowers/
+
+# 本地开发参考(不共享远程)
+docs/superpowers/

pu_toolbox-1.0.0/.python-version

@@ -0,0 +1 @@
+3.11

pu_toolbox-1.0.0/CONTRIBUTING.md

@@ -0,0 +1,125 @@
+# Contributing
+
+本文档定义 PU Learning Toolbox 的代码、论文方法、benchmark 和项目状态管理流程。
+
+## 1. 权威来源
+
+发生冲突时按以下顺序处理：
+
+1. `pyproject.toml`：Python、运行依赖、可选依赖和工具配置。
+2. `docs/project_management/process_checklist.md`：当前任务完成状态。
+3. `docs/dev/project_structure.md`：目录结构。
+4. `docs/dev/architecture.md`：公共 API、依赖方向和数据流。
+5. `docs/dev/roadmap.md`：高层版本路线，不覆盖进度清单。
+6. `requirements.txt`：开发环境快照，仅用于问题复查，不是安装规范。
+
+Method Card 描述论文、公式、实现边界和复现规格，但不能单独证明算法或论文复现已经完成。
+
+## 2. 开发环境
+
+项目支持 Python 3.10、3.11 和 3.12，推荐使用 3.11。
+
+```bash
+uv venv --python 3.11
+uv sync --python 3.11 --extra dev --extra torch
+```
+
+不使用 uv 时：
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+python -m pip install -e ".[dev,torch]"
+```
+
+依赖策略：
+
+- 可安装依赖只在 `pyproject.toml` 维护。
+- 本项目是 library，CI 需要验证声明范围内的最新可解析依赖，因此不提交 `uv.lock`。
+- `requirements.txt` 是一次开发环境的精确快照，不用于 CI，也不要与 `pyproject.toml` 手工双向同步。
+- 新增仅开发期工具放入 `dev`；模型运行依赖放入对应 runtime extra。
+
+## 3. 分支与提交
+
+不要直接在 `main` 上开发。每个独立变更使用一个分支：
+
+```bash
+git switch main
+git pull --ff-only origin main
+git switch -c feature/<short-name>
+```
+
+推荐提交前缀：`feat:`、`fix:`、`test:`、`docs:`、`ci:`、`refactor:`、`chore:`。
+
+一个 PR 应只处理一个清晰主题。不要混入无关重构、生成文件或本地配置；不得提交 SSH 私钥、token、`.env` 或数据访问凭据。
+
+## 4. 公共 API 规则
+
+- 标签必须通过公共规范化/校验接口处理，PU 公共表示为 `{1, 0}`。
+- 分类器遵循 `BasePUClassifier`；类先验估计器遵循 `BasePriorEstimator`。
+- 新增方法必须登记 registry metadata，并明确 assumption、scenario、backend、source status 和 implementation status。
+- 可选依赖不得让基础包导入失败；缺少依赖时应延迟导入并给出可行动错误。
+- `api_only` 不得伪装成可训练实现；clean-room 核心不得标为官方数值复现。
+- 破坏性 API 修改必须更新架构、示例、测试和版本说明。
+
+## 5. 测试与质量门禁
+
+提交前运行：
+
+```bash
+python -m pytest -q
+python scripts/check_format.py       # ruff check + ruff format --check（全目录）
+python scripts/check_test_quality.py
+python scripts/check_doc_links.py
+python scripts/check_project_metadata.py
+python scripts/check_math_rendering.py
+python scripts/check_skill_sync.py
+uv build
+git diff --check
+```
+
+测试应按风险选择 marker：
+
+- `unit`：局部行为、参数和边界。
+- `math`：手工可计算的公式 golden test。
+- `property`：数学不变量。
+- `contract`：所有 native estimator 共享的 API 契约。
+- `paper`：依赖论文数据、源码或配置的复现实验。
+- `slow`：不适合每次本地反馈的测试。
+
+每个普通测试文件最多 15 个测试方法，并覆盖 basic、param、edge、deterministic 全部四类（缺任一分类即门禁失败，严格模式为本地与 CI 共同默认）；具体规则由 `scripts/check_test_quality.py` 执行。
+
+## 6. 论文方法和 benchmark
+
+状态必须严格区分：
+
+- **Method Card 完成**：论文内容和接口规格已整理。
+- **native/clean-room 完成**：本项目独立实现可运行，并通过代码测试。
+- **paper-like 完成**：按论文规格设计实验，但可能使用替代数据或现代环境。
+- **官方复现完成**：官方数据、源码/配置、历史环境和统计协议均已锁定并实际运行。
+
+Benchmark runner、配置、来源锁和结果应一起更新。提交结果 CSV/manifest 时必须能够由仓库内配置和命令重新生成，并在 README 中说明 seed 数、数据来源和环境限制。
+
+禁止使用测试集真值选择类先验、阈值或超参数。合成数据中的 `y_true` 和 propensity 只用于评价或明确标记的 oracle sensitivity。
+
+## 7. 文档与进度
+
+完成任务时至少检查：
+
+- `README.md` 的用户入口和测试数量。
+- `docs/README.md` 的文档索引。
+- `docs/dev/architecture.md` 的 API 和依赖方向。
+- `docs/dev/project_structure.md` 的真实文件结构。
+- `docs/project_management/process_checklist.md` 的勾选与发布状态。
+
+不要一次性把所有待办标记完成。只有代码、测试、文档和要求的实际实验都完成后才能勾选对应任务。
+
+## 8. Pull Request
+
+推送功能分支后创建 PR：
+
+```bash
+git push -u origin feature/<short-name>
+```
+
+PR 描述应包含问题、实现边界、验证命令、实验产物和未解决风险。CI 的 Python 矩阵、静态质量门禁及 wheel 安装冒烟全部通过后再合并。

pu_toolbox-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 shuidisjtu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECT WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pu_toolbox-1.0.0/PKG-INFO

@@ -0,0 +1,186 @@
+Metadata-Version: 2.4
+Name: pu-toolbox
+Version: 1.0.0
+Summary: Positive-Unlabeled Learning Python Toolbox — sklearn-compatible
+Project-URL: Repository, https://github.com/shuidisjtu/pu-learning-toolbox
+Author: shuidisjtu
+License: MIT License
+        
+        Copyright (c) 2026 shuidisjtu
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECT WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: machine-learning,positive-unlabeled,pu-learning,scikit-learn
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Requires-Dist: numpy>=1.24
+Requires-Dist: pandas>=2.0
+Requires-Dist: scikit-learn>=1.3
+Requires-Dist: scipy>=1.10
+Provides-Extra: all
+Requires-Dist: densratio==0.3.0; extra == 'all'
+Requires-Dist: lightning>=2.0; extra == 'all'
+Requires-Dist: torch>=2.0; extra == 'all'
+Requires-Dist: torchvision>=0.15; extra == 'all'
+Requires-Dist: tqdm>=4.0; extra == 'all'
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.3; extra == 'dev'
+Requires-Dist: tomli>=2.0; (python_version < '3.11') and extra == 'dev'
+Provides-Extra: research
+Requires-Dist: densratio==0.3.0; extra == 'research'
+Requires-Dist: lightning>=2.0; extra == 'research'
+Requires-Dist: torch>=2.0; extra == 'research'
+Requires-Dist: torchvision>=0.15; extra == 'research'
+Requires-Dist: tqdm>=4.0; extra == 'research'
+Provides-Extra: torch
+Requires-Dist: torch>=2.0; extra == 'torch'
+Description-Content-Type: text/markdown
+
+[English](README.md) | [中文](README.zh-CN.md)
+
+# PU Learning Toolbox
+
+**Positive-Unlabeled learning in Python** -- sklearn-compatible API, 17 research paper methods, SCAR & SAR support.
+
+![Python](https://img.shields.io/badge/python-%3E%3D3.10-blue)
+![Status](https://img.shields.io/badge/status-1.0.0-blue)
+![License](https://img.shields.io/badge/license-MIT-green)
+
+## Features
+
+- **17 algorithms** from recent PU learning research, all native clean-room implementations ([method cards](docs/research/method_cards/))
+- **sklearn-compatible API** -- `fit(X, y)` / `predict(X)` / `decision_function(X)`, works with pipelines and cross-validation
+- **SCAR & SAR** -- constant and instance-dependent labeling mechanisms, with a data simulator
+- **Data profiling + recommender** -- automatic quality checks, SCAR/SAR evidence, and a 7-dimension scoring recommender that picks the method for your data
+- **Auditable pipeline** -- one-call `PUPipeline` (profile -> prior -> train -> PU-stratified CV -> evaluate) plus structured diagnostic reports and prior/propensity sensitivity analysis
+- **CLI** -- `pu-toolbox` turns the whole pipeline into terminal commands
+
+## Quick Start
+
+> **Note**: Not yet published on PyPI. Install from source.
+
+```bash
+git clone https://github.com/shuidisjtu/pu-learning-toolbox.git
+cd pu-learning-toolbox
+pip install -e .          # core dependencies
+pip install -e ".[torch]" # + PyTorch-based methods (nnPU, Dist-PU, Self-PU, ...)
+```
+
+### Installation environments
+
+Any Python interpreter >= 3.10 works: the package is a pure-Python universal
+wheel with no compiled extensions, so the interpreter source does not matter.
+Notes per environment:
+
+- **venv / uv** (recommended): standard isolated environments, nothing special.
+- **System Python** (python.org / Ubuntu / Homebrew): must be >= 3.10.
+  Ubuntu 22.04+ and Debian 12+ block `pip install` into the system environment
+  (PEP 668) -- create a venv instead.
+- **Anaconda / Miniconda**: `pip install pu-toolbox` inside a conda env
+  (the package is PyPI-only; `conda install` will not find it). If you already
+  installed torch via conda, a plain `pip install pu-toolbox` (without the
+  `[torch]` extra) still enables the PyTorch-based methods -- torch is an
+  optional dependency loaded lazily.
+
+### Hello World
+
+```python
+import numpy as np
+from pu_toolbox.preprocessing import make_sar_dataset
+from pu_toolbox import PUPipeline
+
+# Synthetic PU data: some positives are labeled (1), rest are unlabeled (0)
+X, y_pu, y_true, _ = make_sar_dataset(
+    n_samples=1000, n_features=8, class_prior=0.3, random_state=42,
+)
+
+# One call: profile -> class prior -> train -> PU-stratified CV -> evaluate
+report = PUPipeline().fit_evaluate(X, y_pu, y_true=y_true)
+print(report.summary())
+```
+
+Full docs (Chinese): [docs/README.md](docs/README.md). More runnable examples: [`examples/minimal/`](examples/minimal/).
+
+## Command Line
+
+The `pu-toolbox` console command wraps the full pipeline. Full guide: [`docs/user/howto/cli.md`](docs/user/howto/cli.md).
+
+```bash
+# 1. Generate SCAR demo data (X.csv / y_pu.csv / y_true.csv)
+pu-toolbox make-demo-data --out-dir demo/ --n 200 --seed 42
+
+# 2. One-shot full pipeline run (auto mode picks the algorithm)
+pu-toolbox run --data demo/X.csv --labels demo/y_pu.csv --out-dir results/
+
+# 3. Inspect results
+#    results/report.md     full Markdown report
+#    results/report.json   strict JSON (no NaN), machine-readable
+```
+
+## Documentation
+
+Docs are split by audience; the full index is [`docs/README.md`](docs/README.md).
+
+| Entry | Content |
+|----------|---------|
+| [`docs/user/quickstart.md`](docs/user/quickstart.md) | 5-minute start (CLI + Python) |
+| [`docs/user/concepts/`](docs/user/concepts/) | PU problem, SCAR/SAR, method selection |
+| [`docs/user/howto/`](docs/user/howto/) | Task guides: simulation, profiling, pipeline, CLI, reports, sensitivity |
+| [`docs/user/reference/api.md`](docs/user/reference/api.md) | Precise API contract |
+| [`docs/dev/`](docs/dev/) | Contributor docs: architecture, structure, roadmap, compatibility |
+| [`docs/research/method_cards/`](docs/research/method_cards/) | Per-paper research cards |
+
+## AI workflow skill
+
+`pu-workflow` (Agent Skills open standard) drives the full PU analysis
+workflow — profiling, assumption diagnosis, method recommendation,
+training, and result interpretation — from natural language. Loaded
+natively by Claude Code / Cursor (`.claude/skills/`) and Codex / Gemini
+CLI / Windsurf (`.agents/skills/`).
+
+## Development
+
+```bash
+uv run pytest tests/ -v -m "not slow and not e2e"   # fast tests (e2e runs nightly)
+uv run ruff check pu_toolbox/               # lint
+uv run ruff format --check pu_toolbox/      # format check
+
+# Quality gates
+uv run python scripts/check_test_quality.py
+uv run python scripts/check_doc_links.py
+uv run python scripts/check_project_metadata.py
+uv run python scripts/check_math_rendering.py
+uv run python scripts/check_skill_sync.py
+uv run python scripts/check_format.py        # ruff check + format --check (full scope)
+```
+
+See [`CONTRIBUTING.md`](CONTRIBUTING.md) for contribution guidelines.
+
+## License
+
+MIT