Merge pull request #40 from TATP-233/chore/dev-tooling-upgrade

Chore/dev tooling upgrade

Author: TATP-233

.github/workflows/ci.yml

@@ -2,16 +2,29 @@ name: CI
 
 on:
   push:
-    branches: [ main ]
+    branches: [main]
+    paths-ignore:
+      - "*.md"
+      - "CONTRIBUTING.md"
+      - "CLAUDE.md"
+      - "LICENSE"
   pull_request:
-    branches: [ main ]
+    branches: [main]
+    paths-ignore:
+      - "*.md"
+      - "CONTRIBUTING.md"
+      - "CLAUDE.md"
+      - "LICENSE"
+
+env:
+  UV_FROZEN: "1"
 
 jobs:
   lint:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - uses: astral-sh/setup-uv@v5
+      - uses: astral-sh/setup-uv@v6
         with:
           enable-cache: true
       - name: Lint with ruff
@@ -23,25 +36,28 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - uses: astral-sh/setup-uv@v5
+      - uses: astral-sh/setup-uv@v6
         with:
           enable-cache: true
       - name: Install dependencies
         run: uv sync --extra dev
-      - name: Type check
+      - name: mypy
         run: uv run mypy unilab
+      - name: pyright
+        run: uv run pyright
 
   test:
     strategy:
       matrix:
         os: [ubuntu-latest, macos-latest]
-        python-version: ['3.10', '3.11', '3.12']
+        python-version: ['3.10', '3.11', '3.12', '3.13']
     runs-on: ${{ matrix.os }}
     steps:
       - uses: actions/checkout@v4
-      - uses: astral-sh/setup-uv@v5
+      - uses: astral-sh/setup-uv@v6
         with:
           enable-cache: true
+          python-version: ${{ matrix.python-version }}
       - name: Install dependencies (Linux)
         if: runner.os == 'Linux'
         run: |

.pre-commit-config.yaml

@@ -1,14 +1,12 @@
 repos:
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.8.4
+    rev: v0.14.14
     hooks:
       - id: ruff
         args: [--fix]
       - id: ruff-format
 
-  - repo: https://github.com/pre-commit/mirrors-mypy
-    rev: v1.14.0
+  - repo: https://github.com/RobertCraigie/pyright-python
+    rev: v1.1.408
     hooks:
-      - id: mypy
-        additional_dependencies: [types-all]
-        args: [--ignore-missing-imports]
+      - id: pyright

CLAUDE.md

@@ -30,7 +30,7 @@ uv sync --extra dev --extra cu124
 
 ```bash
 make format     # Format and lint code (ruff format + ruff check --fix)
-make type       # Type check with mypy
+make type       # Type check with mypy + pyright
 make check      # make format && make type
 make test       # Run all non-slow tests (default)
 make test-cov   # Run non-slow tests with coverage report
@@ -47,6 +47,7 @@ uv run ruff check --fix
 
 # Type check
 uv run mypy unilab
+uv run pyright
 
 # Test (non-slow)
 uv run pytest -m "not slow"

CONTRIBUTING.md

@@ -9,13 +9,13 @@
 ## 开发规范
 
 - **Always use `uv run`**，不要直接使用 `python`
-- 提交前必须通过 `make check`（ruff lint + mypy）
+- 提交前必须通过 `make check`（ruff lint + mypy + pyright）
 
 ## 常用命令
 
 ```bash
 make format      # ruff format + ruff check --fix
-make type        # mypy unilab
+make type        # mypy unilab + pyright
 make check       # format + type（提交前必跑）
 make test        # 非 slow 单元测试
 make test-cov    # 非 slow 测试 + 覆盖率报告
@@ -94,12 +94,14 @@ Push / PR 到 `main` 时自动触发三个 job：
 | Job | 内容 | 失败即阻断 |
 |-----|------|-----------|
 | `lint` | `ruff check` + `ruff format --check` | ✅ |
-| `typecheck` | `mypy unilab` | ✅ |
-| `test` | `pytest -m "not slow" --cov` (matrix: ubuntu+macos × py3.10/3.11/3.12) | ✅ |
+| `typecheck` | `mypy unilab` + `pyright` | ✅ |
+| `test` | `pytest -m "not slow" --cov` (matrix: ubuntu+macos × py3.10/3.11/3.12/3.13) | ✅ |
+
+纯文档改动（`*.md`、`LICENSE`）不触发 CI。
 
 ## Pull Request 流程
 
-1. 本地运行 `make check` 确保 lint/mypy 通过
+1. 本地运行 `make check` 确保 lint/mypy/pyright 通过
 2. 本地运行 `make test` 确保单元测试通过
 3. 若改动了 IPC / Runner / Config，补充或更新对应测试
 4. 提交 PR 到 `main` 分支，等待 CI 全绿

Makefile

@@ -10,6 +10,7 @@ format:
 .PHONY: type
 type:
 	uv run mypy unilab
+	uv run pyright
 
 .PHONY: check
 check: format type

benchmark/benchmark_postprocess.py

@@ -14,7 +14,6 @@
 import mlx.core as mx
 import numpy as np
 import torch
-
 from unilab.base import registry
 
 try:

pyproject.toml

@@ -7,7 +7,7 @@ name = "unilab"
 version = "0.1.0"
 description = "Universal Lab for Robot Learning"
 readme = "README.md"
-requires-python = ">=3.10,<3.13"
+requires-python = ">=3.10,<3.14"
 dependencies = [
     "numpy",
     "torch",
@@ -28,14 +28,14 @@ dependencies = [
 ]
 
 [project.optional-dependencies]
-dev = ["pytest", "pytest-cov", "ruff", "mypy"]
+dev = ["pytest", "pytest-cov", "ruff", "mypy", "pyright>=1.1.408"]
 cu124 = [
     # Keep compatibility with documented Linux CUDA installation command.
 ]
 motrix = ["motrixsim==0.6.0"]
 
 [dependency-groups]
-dev = ["pytest", "pytest-cov", "ruff", "mypy"]
+dev = ["pytest", "pytest-cov", "ruff", "mypy", "pyright>=1.1.408"]
 
 [[tool.uv.index]]
 name = "test-pypi"
@@ -51,6 +51,7 @@ packages = ["unilab"]
 [tool.ruff]
 line-length = 100
 target-version = "py310"
+src = ["unilab"]
 
 [tool.ruff.lint]
 select = ["E", "F", "I", "N", "W"]
@@ -83,7 +84,24 @@ addopts = "--tb=short"
 
 [tool.coverage.run]
 source = ["unilab"]
-omit = ["unilab/algos/torch/rsl_rl/*"]
+omit = ["*/rsl_rl/*"]
 
 [tool.coverage.report]
 exclude_lines = ["pragma: no cover", "if TYPE_CHECKING:"]
+
+[tool.pyright]
+pythonVersion = "3.10"
+venvPath = "."
+venv = ".venv"
+include = ["unilab"]
+exclude = [
+    "unilab/algos/torch/rsl_rl/",        # vendored third-party
+    "unilab/algos/mlx/",                  # MLX stubs incomplete, macOS-only
+    "unilab/algos/torch/common/ane_*",    # Apple Neural Engine, macOS-only
+    "unilab/base/backend/",               # mujoco-uni stubs mismatch; optional backends
+    "unilab/envs/",                       # mujoco-uni internal API, stubs mismatch
+    "unilab/utils/render_many.py",        # direct mujoco C bindings
+    "unilab/utils/hardware_monitor.py",   # optional pynvml/psutil deps
+]
+reportMissingImports = "warning"
+reportMissingModuleSource = "none"

scripts/train_appo.py

@@ -48,7 +48,6 @@ def play_appo(args, rl_cfg):
     import numpy as np
     from rsl_rl.utils import resolve_callable
     from tensordict import TensorDict
-
     from unilab.base import registry
     from unilab.utils import render_many
     from unilab.utils.rsl_rl_compat import convert_config_v3_to_v4, is_rsl_rl_v4, is_rsl_rl_v5

scripts/train_mlx_ppo.py

@@ -159,7 +159,6 @@ def play_mlx_ppo(args, cfg, dtype, use_fp16, resolved_sim_backend, task_log_root
     """Play mode for MLX PPO."""
     import mlx.core as mx
     import numpy as np
-
     from unilab.base import registry
 
     play_model_dtype = mx.float32 if use_fp16 else dtype

scripts/train_offpolicy.py

@@ -212,7 +212,6 @@ def play_offpolicy(algo_name: str, args, cfg) -> None:
     import mediapy as media
     import numpy as np
     import torch
-
     from unilab.base import registry
     from unilab.utils import render_many
     from unilab.utils.algo_utils import build_actor