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

[yinsong1986]

Summary

Part 1 / 5 of the split of #31 — tracked by #42.

Adds the package skeleton for the Isaac Sim backend with zero omni overhead on import strands_robots_sim. Lands first; PR-2 (config) / PR-3 (procedural) / PR-4 (simulation) all import from strands_robots_sim.isaac, so this stub + extras + entry-points has to exist before they can be code-reviewed against current main.

What's in this slice

File	Status	Purpose
pyproject.toml	modified	[isaac] + [all] extras; strands_robots.backends entry-points; pytest>=7.0 in dev + hatch envs; gpu pytest marker
strands_robots_sim/isaac/__init__.py	new (43 LOC)	PEP 562 lazy stub — __getattr__ defers imports of .simulation and .config until first attribute access
strands_robots_sim/isaac/tests/__init__.py	new (1 LOC)	empty package marker for future test collection

Why each bit

[isaac] extra — declares the Isaac-companion deps that ARE pip-installable (usd-core>=24.5,<26.0, warp-lang>=1.13.0). Inline comment in pyproject.toml makes clear that Isaac Sim itself is not PyPI-installable; users install it via Omniverse Launcher, Isaac Lab, or nvcr.io/nvidia/isaac-sim:4.5.0.

Entry-points — both isaac and isaac_sim aliases pointing at strands_robots_sim.isaac.simulation:IsaacSimulation. The target class itself lands in PR-4; declaring it now means PR-4's test_entry_points_declared_in_pyproject (which reads pyproject.toml directly) can pass against either an installed package or the source tree.

Lazy __init__.py — import strands_robots_sim.isaac does NOT pull omni / Isaac Sim / usd-core. That overhead only fires when a caller actually accesses IsaacSimulation or IsaacConfig — preserving the "lightweight import" contract of the rest of the package.

pytest>=7.0 + markers config — added now so subsequent slices can run pytest under hatch run test without each PR having to re-add the dependency. The gpu marker pre-declares the gate that PR-4's test_gpu_integ.py will use (STRANDS_GPU_TEST=1).

CI signal

• hatch run test (the existing import-smoke python -c "import strands_robots_sim; print(...)") — passes; doesn't touch isaac, so no missing-submodule errors.
• hatch run lint (black --check / isort --check-only / flake8 over strands_robots_sim/ + examples/) — clean.
• python -c "import strands_robots_sim.isaac; print(strands_robots_sim.isaac.__all__)" → ['IsaacSimulation', 'IsaacConfig']. The lazy stub doesn't import any omni modules at this point.

The hatch test command stays as the import-smoke placeholder in this slice and will flip to pytest strands_robots_sim/isaac/tests/ in PR-3, when the first real test files land.

Dependency chain

PR-1 (this) → unblocks PR-2 / PR-3 / PR-4 / PR-5 (parallel-mergeable after this lands).

Diff: 3 files, +68 / -0 LOC.

Original authorship

Original work by @cagataycali in #31 (413ff15..befb1e3). This slice cherry-picks just the foundation files; the R1-R4 review-thread anchors on the original commits stay intact for whichever child PR consumes the relevant code (per #42's review-thread bookkeeping note).

[cagataycali]

Local review on Thor — lazy contract works, but ships zero tests

Verified locally:

• pip install -e . clean
• import strands_robots_sim.isaac adds zero omni.* modules to sys.modules ✅
• strands_robots_sim.isaac.__all__ == ['IsaacSimulation', 'IsaacConfig'] ✅
• pytest strands_robots_sim/isaac/tests/ → 0 tests collected ❌

Why this matters

This PR is the structural parent of PR45/46/47/48 — they all branched from this commit (3a0a854). So merging this lands the foundation. But it ships with zero test coverage; the lazy-import contract claim is verified only by manual probing, not by CI.

Meanwhile, the orphan PR43 (feat/isaac-extras-and-lazy-import) ships 10 cleanly-passing tests that verify exactly what PR-1 delivers:

• 6 tests in TestEntryPointDeclaration — pyproject parsing + importlib.metadata discovery
• 4 tests in TestLazyImportSurface — including the omni.*-not-loaded assertion that the PR description promises

Those tests don't depend on PR-2/3/4/5 — they only inspect the surface PR-1 actually creates. Safe to land here.

Recommendation

Before merging, port these from PR43:

1. strands_robots_sim/isaac/tests/test_entrypoint.py (140 LOC, 10 tests)
2. pytest>=7.0 in the [isaac] extra (currently in [default] env only)
3. Switch hatch test script from python -c "import strands_robots_sim; ..." to pytest strands_robots_sim/isaac/tests/ -v

Then close PR43.

What works ✅

• Lazy __init__.py (43 LOC) — clean PEP 562 stub
• pyproject.toml extras + entry-points — both isaac and isaac_sim aliases declared correctly
• Lazy contract holds at runtime
• Lint clean

Waiting on the test port before approving.

[yinsong1986]

Thanks for the review. R1 fix pushed as c7e2e5e. All three asks resolved:

#	Ask	Resolution
1	Port test_entrypoint.py from PR #43 (10 tests, no simulation.py dep)	Cherry-picked from the closed feat/isaac-extras-and-lazy-import branch. 6 TestEntryPointDeclaration tests + 4 TestLazyImportSurface tests; all 10 pass standalone (pytest strands_robots_sim/isaac/tests/ -v → 10 passed in 0.14s).
2	Add pytest>=7.0 to [isaac] extra	Added; pinned by TestEntryPointDeclaration::test_isaac_extra_includes_pytest.
3	Flip hatch run test from import-smoke to pytest …	Done; [tool.hatch.envs.default.scripts] test = "pytest strands_robots_sim/isaac/tests/ -v". PR-4's simulation-module tests join the collection automatically once that PR rebases.

The ported tests are designed for PR-1's surface specifically — they read pyproject.toml directly (not via metadata when not installed), feature-detect importlib.metadata discovery (skip with actionable hint when not pip-installed), and pin the PEP 562 __getattr__ contract (AttributeError not ImportError on unknown attrs, lazy access doesn't pull omni.* modules). Zero imports through strands_robots_sim.isaac.simulation.

Downstream impact on the rest of the chain

[Update 2026-05-26]: the rebase below was executed shortly after this comment was posted (per follow-up direction). The plan in this section is no longer pending — see the per-PR status comments on #45 / #46 / #47 / #48 for the actual SHA shifts and conflict-resolution details.

#47 specifically: the test_entrypoint.py conflict was resolved by keeping the new R1 surface-only version + migrating two unique-to-PR-4 tests (test_isaac_is_simengine_subclass, test_isaac_implements_all_abstract_methods) into test_unit.py::TestIsaacSimulationAvailability. The migrated test_isaac_implements_all_abstract_methods now loudly pins the pre-existing abstract-method gap on IsaacSimulation.robot_joint_names (24 failing tests) — flagged on #47 as a separate review concern, not introduced by the rebase.

pr1/isaac-foundation advanced from 3a0a854 → c7e2e5e. The downstream branches (pr2/isaac-config → pr5/isaac-docs) all branched off the old SHA. Once you approve and merge this, I'll:

1. Rebase feat(isaac): IsaacConfig dataclass with validation (2/5 of #31 split) #45 / feat(isaac): procedural USD builders (SO-100, Panda, G1) (3/5 of #31 split) #46 / feat(isaac): IsaacSimulation backend (lifecycle + observation + render) (4/5 of #31 split) #47 / docs(isaac): backend reference + Phase 1 status banner (5/5 of #31 split) #48 onto the new pr1 head (then onto main after feat(isaac): [isaac] extras + entry-point + PEP 562 lazy import (1/5 of #31 split) #44 lands).
2. feat(isaac): IsaacSimulation backend (lifecycle + observation + render) (4/5 of #31 split) #47 needs special care — it currently carries cagataycali's original test_entrypoint.py (which imports from strands_robots_sim.isaac.simulation import IsaacSimulation, SimEngine). Those simulation-dependent tests (test_isaac_is_simengine_subclass, test_isaac_has_is_available_classmethod, test_is_available_returns_false_without_gpu) overlap with feat(isaac): IsaacSimulation backend (lifecycle + observation + render) (4/5 of #31 split) #47's test_unit.py::TestIsaacSimulationAvailability and TestIsaacSimulationContract. On rebase I'll resolve the conflict by:
   • Keeping the new R1 test_entrypoint.py from this PR (PR-1's surface tests).
   • Migrating the simulation-dependent tests to feat(isaac): IsaacSimulation backend (lifecycle + observation + render) (4/5 of #31 split) #47's test_unit.py (where similar tests already live), or dropping the redundant ones if test_unit.py already covers them.
   • The migration is its own focused commit on feat(isaac): IsaacSimulation backend (lifecycle + observation + render) (4/5 of #31 split) #47.

Let me know if you'd prefer a different rebase strategy (e.g., merge commit on #45-#48 instead of rebase to preserve their commit SHAs for any inline-thread anchors).