examples(teleop_session_manager): package under isaacteleop_examples

[jiwenc-nv]

Description

Part of #985. Stacked on #1034.

teleop_controls_simple_example.py imported its helper as a top-level module, which resolved only because the invoked script's own directory landed on sys.path. It broke under python -m, broke when copied into another project, and claimed the bare name teleop_controls_simple_helper. This moves the tree to the layout in examples/README.md.

uv pip install -e ./examples/teleop_session_manager
python -m isaacteleop_examples.teleop_session_manager.teleop_session_example

The four demos here are co-equal, so there is no __main__.py: each is its own submodule and the README lists them. Picking one as the default would have made it look privileged over the other three.

The README moves up beside the pyproject and now documents all four — it previously described only teleop_session_example, and its run instructions pointed into the install tree.

Type of change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Documentation update

Testing

x86_64 / Ubuntu, Python 3.12. Wheel ships isaacteleop_examples/teleop_session_manager/ with no namespace __init__.py. uv pip install -e ./examples/teleop_session_manager into a clean venv, then imported all four demo modules with the CWD outside the repo; import teleop_controls_simple_helper fails, so the flat name is gone rather than relocated. pre-commit clean on the changed files.

Not covered: a live run — that needs a headset.

Checklist

• I have read and understood the contribution guidelines
• I have run the linter and formatter with SKIP=check-copyright-year pre-commit run --all-files
• I have made corresponding changes to the documentation
• I have added tests that prove my fix/feature works (or explained why not)
• I have signed off all my commits (git commit -s) per the DCO

_{No tests: this is a move, and this example has no automated coverage. Verification is the wheel-layout and import checks above plus a human run.}

Summary by CodeRabbit

• New Features

  • Added standalone TeleopSession examples for message channels, control input, and observation pipelines.
  • Added installation and usage documentation covering the available teleoperation examples.
  • Added packaging support for installing the examples as a Python package.

• Bug Fixes

  • Updated example paths and imports to reflect the relocated package structure.
  • Improved plugin discovery across source and installed layouts.

• Documentation

  • Updated the teleoperation state-machine guide with the current example location.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 3c6de81d-51f4-489a-83df-683727cc9f46

📥 Commits

Reviewing files that changed from the base of the PR and between e3bf792 and 450d0c1.

📒 Files selected for processing (12)

• docs/source/getting_started/teleop_control_state_machine.rst
• examples/teleop_session_manager/CMakeLists.txt
• examples/teleop_session_manager/README.md
• examples/teleop_session_manager/pyproject.toml
• examples/teleop_session_manager/python/README.md
• examples/teleop_session_manager/python/isaacteleop_examples/teleop_session_manager/__init__.py
• examples/teleop_session_manager/python/isaacteleop_examples/teleop_session_manager/external_inputs_example.py
• examples/teleop_session_manager/python/isaacteleop_examples/teleop_session_manager/message_channel_example.py
• examples/teleop_session_manager/python/isaacteleop_examples/teleop_session_manager/teleop_controls_simple_example.py
• examples/teleop_session_manager/python/isaacteleop_examples/teleop_session_manager/teleop_controls_simple_helper.py
• examples/teleop_session_manager/python/isaacteleop_examples/teleop_session_manager/teleop_session_example.py
• examples/teleop_session_manager/python/pyproject.toml

💤 Files with no reviewable changes (2)

• examples/teleop_session_manager/python/README.md
• examples/teleop_session_manager/python/pyproject.toml

Included review availability: Your plan provides up to 12 included reviews per hour; 11 remain after this review.

---

📝 Walkthrough

Walkthrough

The teleoperation examples now use a package-based installation layout with Hatchling metadata and updated documentation links. The simple teleoperation helper provides state reporting, observation composition, and frame output. Runtime examples resolve plugin paths from repository or installation layouts. A new message-channel example manages a CloudXR-backed TeleopSession, decodes inbound messages, and sends periodic timestamped messages.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Merge Risk: ⚪ Minimal · up to 450d0

The examples are reorganized under the intended package layout and their documentation and import paths are updated; no actionable merge-blocking risk remains after normal checks and review.

Sequence Diagram(s)

sequenceDiagram
  participant message_channel_example.py
  participant TeleopSession
  participant CloudXR
  message_channel_example.py->>TeleopSession: configure message channel and retargeting nodes
  TeleopSession->>CloudXR: launch CloudXR-backed session
  CloudXR-->>TeleopSession: deliver inbound messages
  TeleopSession-->>message_channel_example.py: provide decoded messages
  message_channel_example.py->>TeleopSession: send timestamped messages while connected

Loading

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 36.36% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 11 functions across 6 files. (4 skipped: …	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly identifies the main change: packaging the teleop_session_manager examples under the isaacteleop_examples namespace.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

Full details: Docstring Coverage

Explanation

Docstring coverage is 36.36% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 11 functions across 6 files. (4 skipped: 4 unsupported.)

• Fix all pre-merge checks with AI

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch jiwenc-nv/examples-teleop-session-manager

---

_{Comment @coderabbitai help to get the list of available commands.}

[ivany-nv]

Read the diff line by line: pure move plus the teleop_controls_simple_helper relative-import fix, no logic change.

Verified the install tree lands correctly at the stack tip (pyproject.toml at the example root, no doubled python/python/, no isaacteleop_examples/__init__.py), and python -m isaacteleop_examples.teleop_session_manager.teleop_session_example --help runs from install/examples/teleop_session_manager/.