feat(isaac): [isaac] extras + entry-point + PEP 562 lazy import (1/5 of #31 split)

[yinsong1986]

Summary

PR-1 of 5 in the #31 split tracked by #42. Lands the dependency-free bottom of the 5-PR graph: the [isaac] optional-dependencies extra, the strands_robots.backends entry points (isaac + isaac_sim alias), and the PEP 562 lazy stub at strands_robots_sim/isaac/__init__.py.

This is the slice that demonstrates entry-point discovery without any simulation code. The lazy stub references strands_robots_sim.isaac.simulation:IsaacSimulation and strands_robots_sim.isaac.config:IsaacConfig, which land in PR-4 and PR-2 respectively. The entry points in pyproject.toml are intentionally "dangling" until PR-4 merges; PR-1's tests verify declaration (parsing pyproject.toml) and the lazy-import contract (import strands_robots_sim.isaac adds zero omni.* modules to sys.modules), not loadability of the resolved class.

Lands first in the dependency graph below; PR-2 + PR-3 unblock once this merges, then PR-4 needs both, and PR-5 is parallel-mergeable with PR-4.

PR-1 (this PR — entry-point + extras + lazy import)
  ├── PR-2 (config dataclass)
  └── PR-3 (procedural USD builders)
        └── PR-4 (IsaacSimulation backend)
              ├── PR-5 (docs, parallel)
              └── close #31

What changed

File	Change
pyproject.toml	+ [isaac] extras (usd-core>=24.5,<26.0, warp-lang>=1.13.0, pytest>=7.0); + [project.entry-points."strands_robots.backends"] for isaac and isaac_sim alias; + [tool.pytest.ini_options] markers (gpu marker reserved for PR-4's test_gpu_integ.py); + all extra rolling up [isaac]; hatch test script switched from import-smoke to pytest strands_robots_sim/isaac/tests/ -v.
strands_robots_sim/isaac/__init__.py	PEP 562 __getattr__ lazy resolution for IsaacSimulation + IsaacConfig. __all__ advertises the planned public surface.
strands_robots_sim/isaac/tests/__init__.py	Empty package marker.
strands_robots_sim/isaac/tests/test_entrypoint.py	10 tests scoped to what PR-1 actually delivers (see below).

Diff size: +233 / −7, 4 files. Within the issue's "~250 LOC" budget for PR-1.

Test surface (10 tests)

Two test classes, scoped to what PR-1 can prove standalone:

TestEntryPointDeclaration (6 tests)

• test_pyproject_exists — locate pyproject.toml
• test_isaac_entry_point_declared_in_pyproject — isaac = "strands_robots_sim.isaac.simulation:IsaacSimulation" present
• test_isaac_sim_alias_entry_point_declared_in_pyproject — isaac_sim alias present
• test_isaac_extra_declared_in_pyproject — [isaac] extras block exists
• test_isaac_extra_includes_pytest — [isaac] ships pytest so pip install '.[isaac]' covers test deps
• test_entry_points_visible_via_importlib_metadata_when_installed — runtime entry-point discovery (skips gracefully if package isn't pip-installed in the env)

TestLazyImportSurface (4 tests)

• test_import_isaac_does_not_load_omni — import strands_robots_sim.isaac adds zero omni.* modules to sys.modules
• test_isaac_subpackage_exposes_lazy_attrs_in___all__ — __all__ advertises both classes
• test_unknown_attr_raises_attributeerror — unknown attribute access raises AttributeError, not ImportError (PEP 562 hook hygiene)
• test_dunder_getattr_is_present — module-level __getattr__ exists and is callable

Tests covering SimEngine subclassing, abstract-method completeness, is_available() return shape, and no-GPU constructor instantiation are intentionally deferred to PR-4 because they require importing the simulation module that hasn't landed yet. Including them here would re-create the cross-PR dependency the split is trying to avoid.

Acceptance criteria from #42 (PR-1 row)

• pyproject.toml: [isaac] extras
• pyproject.toml: entry-points (isaac, isaac_sim alias)
• isaac/__init__.py: PEP 562 lazy stub
• isaac/tests/__init__.py
• isaac/tests/test_entrypoint.py
• Demonstrates entry-point discovery without any simulation code
• Lands first in dependency-graph order
• ~250 LOC (actual: 233)
• CI green standalone (parallel-mergeable group)

Local validation

$ hatch run lint
black --check strands_robots_sim examples         # clean
isort --check-only strands_robots_sim examples    # clean
flake8 strands_robots_sim examples                # clean

$ hatch run test
9 passed, 1 skipped in 0.04s
# (the skip is `test_entry_points_visible_via_importlib_metadata_when_installed`;
#  hatch's hash-locked virtualenv doesn't see the source-tree editable install,
#  so importlib.metadata returns no entry points there. The test surface is correct
#  -- skip vs pass is purely env-dependent.)

$ pip install -e . && python -m pytest strands_robots_sim/isaac/tests/ -v
10 passed in 0.14s
# (under editable install, the importlib.metadata skip becomes a pass --
#  both `isaac` and `isaac_sim` resolve to
#  `strands_robots_sim.isaac.simulation:IsaacSimulation`.)

$ python -c "import sys; import strands_robots_sim.isaac; print([m for m in sys.modules if m.startswith('omni')])"
[]
# zero `omni.*` modules loaded on import — PEP 562 contract holds.

Out-of-scope follow-ups (deferred to other PRs in the split)

• PR-2 — IsaacConfig dataclass + R1's "reject unknown kwargs" pin
• PR-3 — procedural USD builders (SO-100 / Panda / G1) + R2's G1-DOF=21 truth-source pin
• PR-4 — IsaacSimulation backend with R1's omni.isaac.kit-specific is_available() probe + dropped unsafe __del__ + narrow except clauses + R4's get_observation diagnostic logs
• PR-5 — docs/backends/isaac.md reference with R2's Phase-1-status disclosure banner

The 9 review threads on #31 stay open until the corresponding child PR closes them. R1/R2/R3/R4 commit chronicle on #31 remains the forensic source of truth; child PRs preserve those commits as cherry-picks where the review-thread anchors apply (mirrors strands-labs/robots#195 → #220-#228 / robots#219 precedent).

Project board

This PR's issue #42 is the umbrella tracker; please move to "In review" on the Strands Labs - Robots board.

Refs: #31, #42

[cagataycali]

Local review on Thor — duplicate of #44 but actually has the better artifact

Reviewed PR43 vs PR44 side-by-side. They have the same lazy __init__.py contract but differ on test surface and hatch script:

Aspect	PR43 (this)	PR44
Branch	feat/isaac-extras-and-lazy-import	pr1/isaac-foundation
Tests	10 tests in test_entrypoint.py, all pass	0 tests
Hatch test script	pytest strands_robots_sim/isaac/tests/ -v	placeholder import-smoke
pyproject [isaac] extra	includes pytest>=7.0	doesn't
Lazy contract verified	✅ (zero omni modules loaded)	✅
Stack lineage	orphan (PR45/46/47/48 don't branch from this)	parent of PR45/46/47/48

Verdict

PR43 is the better artifact, but PR44 is the structurally correct one because PR45-48 all branched from PR44's commit 3a0a854, not from PR43's e717e71.

Recommendation

1. Close this PR (#43) as superseded by #44.
2. Port the 10 tests + hatch test script + pytest>=7.0 extra from this PR into #44 as a new commit on pr1/isaac-foundation. The 10 tests are good (they already pass cleanly on Thor) and PR44's lack-of-tests is the main gap I'd block #44 on otherwise.
3. The 10 tests carved cleanly so they only verify what PR-1 actually delivers (entry-point declaration + lazy-import contract) — no cross-PR coupling. Safe to add.

If you'd rather close PR44 and keep this one, the cost is rebasing PR45/46/47/48 onto PR43's branch — also fine, just 4 rebases.

[yinsong1986]

Closing as duplicate of #44 — both cover the same "1/5 of #31 split" slice, but #44 is the canonical chain head (followed by #45 / #46 / #47 / #48 per #42).

Substantive shape difference:

	#43	#44
tests/test_entrypoint.py	included	deferred to #47 alongside simulation.py
pyproject.toml test command	flipped to pytest …	left as import-smoke placeholder
Standalone CI	red (3/4 entry-point tests need simulation.py)	green

The deferral of test_entrypoint.py to #47 keeps the foundation slice CI-green standalone — test_entrypoint.py imports from strands_robots_sim.isaac.simulation import IsaacSimulation, SimEngine at the top of every test, so it can't pass without PR-4 in place.

No work is lost: #44 keeps the same pyproject.toml extras + entry-points + pytest dep + gpu marker that #43 had; the test_entrypoint.py content lands in #47 where its imports are satisfied.