refactor(pi07): rename low_level_planner -> low_level (it's not a planner)

[shuheng-liu]

What this does

Closes #247.

The low-level component of π0.7 is a flow-matching action generator with FAST discrete-token prediction — not a planner. The high-level component IS a planner (predicts subtask strings autoregressively) and keeps its naming. This PR aligns the source-side naming with that distinction.

Renames

• src/opentau/policies/pi07/low_level_planner/ → src/opentau/policies/pi07/low_level/
• PI07LowLevelPlannerConfig → PI07LowLevelConfig
• PI07LowLevelPlannerPolicy → PI07LowLevelPolicy
• PI07LowLevelPlannerFlowMatching → PI07LowLevelFlowMatching
• TestPI07LowLevelPlannerAttentionLayout → TestPI07LowLevelAttentionLayout (in tests/policies/test_pi07_attention_layout.py)

Updated callers: factory.py, policies/__init__.py, gemma3_with_expert.py, plus the test suite (test_pi07_cpu.py, test_pi07_attention_layout.py, test_pi07_low_level.py, test_pi07_video_encoder_cpu.py, test_available.py). Docstrings that mentioned "low-level planner" were updated to "low-level component" for consistency.

Backward compatibility (deprecation shim)

The old low_level_planner/ path is preserved as a thin re-export shim that aliases the new classes under their old names and emits a DeprecationWarning at package-import time. This keeps existing user code, pickled checkpoints (config classes), and any draccus configs that pinned the old import path working through one release cycle.

The shim is exercised by tests/policies/test_pi07_low_level_shim.py:

• Verifies the warning fires on import.
• Verifies legacy PI07LowLevelPlanner* names are the same class objects as the new PI07LowLevel* names (so isinstance checks and pickled state survive).
• Verifies legacy make_att_2d_masks, pad_discrete_tokens, resize_with_pad, and the SpaceTime SigLIP encoder helpers still resolve.

Policy-type strings in factory.py (pi07_low_level, pi07_high_level) are unchanged, so draccus policy.type=pi07_low_level configs keep working without edits.

Out of scope

• The legacy pi07_paligemma/low_level_planner/ package and its PI07lowlevelPlannerConfig / PI07LowLevelPlannerPolicy classes are intentionally untouched — that's a separate retired package.
• High-level naming is preserved everywhere. High-level IS a planner.

Note on the diff

git mv followed by class-rename edits across both the moved directory and the new shim files breaks git's automatic rename detection (the new shim files at low_level_planner/ have low content similarity with the moved-and-renamed files at low_level/). The diff therefore looks like "delete low_level_planner/'s old content + add new low_level/ files + add small shim files at low_level_planner/" instead of one clean rename. History is best traced via the new path going forward.

How it was tested

• pre-commit run --all-files — clean.
• Targeted CPU tests covering the renamed code paths and the shim:

  pytest -m "not gpu" -n auto \
    tests/policies/test_pi07_attention_layout.py \
    tests/policies/test_pi07_cpu.py \
    tests/policies/test_pi07_video_encoder_cpu.py \
    tests/policies/test_pi07_low_level_shim.py \
    tests/test_available.py

  → 62 passed in 54s.
• Full PR-equivalent CPU suite (matching cpu_test.yml):

  LIBERO_CONFIG_PATH=$(pwd)/.github/assets/libero pytest -m "not gpu" -n auto \
    --ignore=tests/planner/test_planner.py \
    --ignore=tests/utils/test_libero_utils.py \
    --deselect=tests/envs/test_factory.py::TestMakeEnv::test_make_env_async_vector_env \
    --deselect=tests/envs/test_factory.py::TestMakeEnv::test_make_env_sync_vector_env \
    tests/

  → 903 passed, 13 skipped. Two pre-existing flakes in tests/utils/test_utils_benchmark.py (test_context_manager_usage, test_exception_handling) — both are tight timing assertions on time.sleep(0.05) with pytest.approx(0.05, abs=0.01). They reproducibly fail at ~0.06s under typical macOS scheduling load. Unrelated to this PR.

This is a pure rename with class identity preserved by aliases (verified by the shim test). No model / training-loop logic changes, so no GPU-specific regression risk; the nightly gpu_test.yml + regression_test.yml runs will catch any surprise breakage. Happy to trigger them manually before merge if preferred.

How to checkout & try? (for the reviewer)

git fetch origin && git checkout refactor/pi07-low-level-rename
uv sync --extra dev --extra libero
pre-commit run --all-files
LIBERO_CONFIG_PATH=$(pwd)/.github/assets/libero pytest -m "not gpu" -n auto \
  --ignore=tests/planner/test_planner.py \
  --ignore=tests/utils/test_libero_utils.py \
  --deselect=tests/envs/test_factory.py::TestMakeEnv::test_make_env_async_vector_env \
  --deselect=tests/envs/test_factory.py::TestMakeEnv::test_make_env_sync_vector_env \
  tests/

Quick smoke check on the deprecation shim:

pytest -sx tests/policies/test_pi07_low_level_shim.py
python -W default::DeprecationWarning -c "from opentau.policies.pi07.low_level_planner import configuration_pi07_low_level; print('ok')"
# expect a DeprecationWarning naming the new path and the class renames

Checklist

• I have added Google-style docstrings to important functions and ensured function parameters are typed.
• My PR includes policy-related changes.
  • If the above is checked: I have run the GPU pytests (pytest -m "gpu") and regression tests.

[claude]

Doc nit, scoped to the file the PR is renaming: this line still says "This planner uses SpaceTimeSiglip" — given the PR's whole point is that the low-level component is not a planner, and the class docstring just below (line 41) was correctly updated to "low-level component", this preceding module-docstring sentence was missed. (The class docstring at line 41-47 is fine; only the module-docstring sentence that introduces the file is stale.)

[claude]

[claude-review] summary for commit 1ce5b87

No blocking issues found.

• nit — PR description — the "Backward compatibility (deprecation shim)" section is stale; the shim was removed in f368478. The author flagged this in refactor(pi07): rename low_level_planner -> low_level (it's not a planner) #250 (comment).

Verification notes:

• Re-diffed each renamed file in pi07/low_level/ against the corresponding pre-PR pi07/low_level_planner/ file with PI07LowLevelPlanner→PI07LowLevel / low_level_planner→low_level substituted. After substitution the only differences are docstring text (Planner → Component/module) and one cosmetic line-rejoin in PI07LowLevelPolicy.__init__ — no semantic changes.
• Earlier doc nit (module docstring at configuration_pi07_low_level.py:19) was correctly fixed in ba72d9a; the prior review thread is resolved.
• No remaining low_level_planner / PI07LowLevelPlanner references anywhere outside pi07_paligemma/ (which is explicitly out of scope per the PR description and CLAUDE.md policies/ description).
• factory.py policy-type strings (pi07_low_level, pi07_high_level) are unchanged, so existing draccus configs keep working.
• gemma3_with_expert.py:416 correctly imports suppress_spacetime_temporal from the new path; remains a local lazy import (no circular-import concerns).
• available_policies in src/opentau/__init__.py:152 already lists "pi07_low_level" — tests/test_available.py (now importing PI07LowLevelPolicy from the new path) will catch any name drift.
• Pure refactor: no model/training-loop logic changes, so CLAUDE.md determinism / multi-GPU rules don't apply. CPU test suite is the right gate.

[shuheng-liu]

@claude fix per review.

[shuheng-liu]

We don't even want this. Remove it outright.

The old low_level_planner/ path is preserved as a thin re-export shim that aliases the new classes under their old names and emits a DeprecationWarning at package-import time.

@claude fix accordingly.

[claude]

[claude-fix] Done in f3684781e6c40b3c4b3502b4cabc1a64fec88e85.

Removed the low_level_planner/ shim outright per #250 (comment):

• Deleted src/opentau/policies/pi07/low_level_planner/ (the four shim files: __init__.py, configuration_pi07_low_level.py, modeling_pi07_low_level.py, video_encoder.py).
• Deleted tests/policies/test_pi07_low_level_shim.py (no shim → no shim test).

Verified no remaining low_level_planner / LowLevelPlanner references in src/opentau/policies/pi07/ or tests/ (the matches in pi07_paligemma/ are the separate retired package and out of scope per the PR description).

The PR description's "Backward compatibility (deprecation shim)" section is now stale — happy to update it in the same branch if you'd like, just say the word.

tests: passed — pytest -m "not gpu" -n auto tests/policies/test_pi07_attention_layout.py tests/policies/test_pi07_cpu.py tests/policies/test_pi07_video_encoder_cpu.py tests/policies/test_pi07_low_level.py tests/test_available.py → 57 passed in 99s.

[claude]

Re-review of 1ce5b87 post-shim-removal. No blocking issues — the PR is now a clean rename. Details in the [claude-review] summary comment.