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

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

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`:

- `pyproject.toml`:
  - new `[isaac]` extra (lightweight Isaac-companion deps that ARE
    pip-installable: `usd-core>=24.5,<26.0`, `warp-lang>=1.13.0`).
    Comment explains that Isaac Sim itself is NOT installable from
    PyPI — must come via Omniverse Launcher / Isaac Lab / nvcr.io.
  - new `[all]` aggregate extra (currently delegates to `[isaac]`;
    will gain `[newton]` etc. as later backends land).
  - new `[project.entry-points."strands_robots.backends"]` declaring
    both `isaac` and `isaac_sim` aliases pointing at
    `strands_robots_sim.isaac.simulation:IsaacSimulation` (the class
    itself lands in PR-4 / `feat(isaac): IsaacSimulation backend`).
  - new `pytest>=7.0` in `dev` extras and `[tool.hatch.envs.default]`
    deps so future PRs in this split chain can run pytest under
    `hatch run test`.
  - new `[tool.pytest.ini_options]` with a `gpu` marker so PR-4's
    GPU-only integ tests can gate on `STRANDS_GPU_TEST=1`.

- `strands_robots_sim/isaac/__init__.py`:
  PEP 562 lazy stub — declares `__all__ = ["IsaacSimulation",
  "IsaacConfig"]` and routes attribute access through `__getattr__`
  to deferred imports of `.simulation` and `.config`. The bare
  `import strands_robots_sim.isaac` does NOT import any `omni`
  modules; that overhead only fires when a caller actually accesses
  `IsaacSimulation` or `IsaacConfig`.

- `strands_robots_sim/isaac/tests/__init__.py`: empty package marker
  so future test files in this directory are collectable. Test files
  themselves land in subsequent slices alongside the code they cover.

CI signal: lint clean (black / isort / flake8); the existing
`hatch run test` import-smoke passes (it doesn't touch `isaac`, so
no missing-submodule errors). Pytest doesn't run yet from `hatch
run test` — the test command stays as the import-smoke placeholder
in this slice and flips to `pytest strands_robots_sim/isaac/tests/`
in PR-3 once the first real test files land.

Why this lands first: PR-2 / PR-3 / PR-4 all import from
`strands_robots_sim.isaac`, so the package stub + extras + entry
points have to exist before any of those files can be code-reviewed
against current `main`.

Original work by @cagataycali in #31 (`413ff15..befb1e3`); this
slice cherry-picks just the foundation files. Review-thread anchors
on the original commits stay intact for whichever child PR consumes
the relevant code.

* review(isaac): port 10 entry-point + lazy-import tests from #43 (PR #44 R1)

Closes @cagataycali's R1 review on #44 -- the lazy-import contract
ships with concrete CI signal now, not just a manual probe in the PR
description.

Three coordinated changes per the review:

1. **Port `tests/test_entrypoint.py` (140 LOC, 10 tests)** from the
   closed orphan PR #43 (`feat/isaac-extras-and-lazy-import`). These
   tests verify *only* PR-1's surface and have **zero dependency on
   `simulation.py`** (which lands in PR-4 of the #31 split):

   - `TestEntryPointDeclaration` (6 tests):
     - `test_pyproject_exists`
     - `test_isaac_entry_point_declared_in_pyproject`
     - `test_isaac_sim_alias_entry_point_declared_in_pyproject`
     - `test_isaac_extra_declared_in_pyproject`
     - `test_isaac_extra_includes_pytest`
     - `test_entry_points_visible_via_importlib_metadata_when_installed`
       (skips with actionable hint when not pip-installed)

   - `TestLazyImportSurface` (4 tests):
     - `test_import_isaac_does_not_load_omni` -- pins the `omni`-not-
       loaded contract via `sys.modules` set diff before/after
       import.
     - `test_isaac_subpackage_exposes_lazy_attrs_in___all__`
     - `test_unknown_attr_raises_attributeerror` -- pins the PEP 562
       `__getattr__` raises `AttributeError` (not `ImportError`) on
       unknown attrs.
     - `test_dunder_getattr_is_present`

2. **Add `pytest>=7.0` to the `[isaac]` extra** in `pyproject.toml`.
   Means `pip install '.[isaac]'` covers the test deps without a
   separate dev extra on CI hosts. Also pinned by
   `test_isaac_extra_includes_pytest`.

3. **Flip `hatch run test`** from the import-smoke placeholder
   (`python -c "import strands_robots_sim; ..."`) to
   `pytest strands_robots_sim/isaac/tests/ -v`. The 10 tests collect
   and pass standalone; PR-4's simulation-module tests join the
   collection automatically when that PR rebases.

Verification:

- `pytest strands_robots_sim/isaac/tests/ -v` -> **10 passed in 0.14s**
- `black --check` / `isort --check-only` / `flake8` (max-line=120) on
  `strands_robots_sim/` + `examples/` -> clean
- AST parse on touched files -> ok
- The 10 tests have no import path through `simulation.py`; they
  validate only PR-1's actual surface (pyproject parsing, entry-
  point declaration, PEP 562 `__getattr__` contract).

The original `test_entrypoint.py` on `cagataycali/feat/isaac-sim`
imports from `strands_robots_sim.isaac.simulation`, which is why
PR-1 of the split couldn't ship that file unmodified. The version
ported here was rewritten on the #43 branch specifically for the
PR-1 surface; cleanly self-contained against this slice.

Author: yinsong1986

pyproject.toml

@@ -41,13 +41,32 @@ dev = [
     "black",
     "isort",
     "flake8",
+    "pytest>=7.0",
+]
+# Isaac Sim is NOT installable from PyPI -- it's an Omniverse Kit app.
+# The user must install it separately:
+#   - via NVIDIA Omniverse Launcher (Isaac Sim 2024.x), OR
+#   - via Isaac Lab: git clone IsaacLab && ./isaaclab.sh -i, OR
+#   - via Docker: nvcr.io/nvidia/isaac-sim:4.5.0
+# We declare lightweight deps that Isaac ships and that ARE pip-installable:
+isaac = [
+    "usd-core>=24.5,<26.0",
+    "warp-lang>=1.13.0",
+    "pytest>=7.0",
 ]
 # NOTE: the lightweight `sim` extra (libero / robosuite / mujoco / gymnasium)
 # was removed in 0.2.0 — that backend now lives in `strands-robots` and is
 # installed via `pip install 'strands-robots[sim-mujoco]'`. Heavy GPU-only
 # backends (Isaac Sim, Newton) will land here behind `[isaac]` / `[newton]`
 # extras in upcoming releases. See examples/MIGRATION.md and
 # https://github.com/strands-labs/robots-sim/issues/8.
+all = [
+    "strands-robots-sim[isaac]",
+]
+
+[project.entry-points."strands_robots.backends"]
+isaac = "strands_robots_sim.isaac.simulation:IsaacSimulation"
+isaac_sim = "strands_robots_sim.isaac.simulation:IsaacSimulation"
 
 [project.urls]
 Homepage = "https://github.com/strands-labs/robots-sim"
@@ -68,12 +87,16 @@ dependencies = [
     "black",
     "isort",
     "flake8",
+    "pytest>=7.0",
 ]
 
 [tool.hatch.envs.default.scripts]
-# No tests until backend code lands in R7 (Isaac) / R11 (Newton). For now
-# `hatch run test` is an import smoke that exercises the no-op stub.
-test = "python -c \"import strands_robots_sim; print('strands-robots-sim', strands_robots_sim.__version__, 'OK')\""
+# `hatch run test` runs the Isaac PR-1 entry-point + lazy-import test
+# slice (10 tests; pyproject parsing + importlib.metadata discovery +
+# PEP 562 lazy `__getattr__` contract). PR-4 of the #31 split adds the
+# simulation-module tests under the same directory; the glob picks
+# them up automatically.
+test = "pytest strands_robots_sim/isaac/tests/ -v"
 # Lint extends to `examples/` so the runnable example files (which copy-
 # paste into PR docstrings + the README matrix) catch the same drift the
 # package source does. Keeps each new R8/R12/R23 backend example honest.
@@ -96,3 +119,8 @@ include = '\.pyi?$'
 profile = "black"
 line_length = 120
 multi_line_output = 3
+
+[tool.pytest.ini_options]
+markers = [
+    "gpu: tests requiring NVIDIA GPU + Isaac Sim (gated on STRANDS_GPU_TEST=1)",
+]

strands_robots_sim/isaac/__init__.py

@@ -0,0 +1,43 @@
+"""strands_robots_sim.isaac -- GPU-native Isaac Sim simulation backend.
+
+This subpackage provides :class:`IsaacSimulation`, a ``SimEngine`` backend
+built on **NVIDIA Isaac Sim / Omniverse** for photorealistic rendering,
+synthetic data generation, and GPU-batched sensor simulation.
+
+Usage::
+
+    from strands_robots_sim.isaac import IsaacSimulation, IsaacConfig
+    config = IsaacConfig(num_envs=1, headless=True)
+    sim = IsaacSimulation(config)
+    ok, msg = IsaacSimulation.is_available()
+
+Requires NVIDIA Isaac Sim 2024.x+ (not pip-installable).
+Install via Omniverse Launcher or ``nvcr.io/nvidia/isaac-sim:4.5.0``.
+"""
+
+from __future__ import annotations
+
+__all__ = ["IsaacSimulation", "IsaacConfig"]
+
+
+def _lazy_isaac_simulation():
+    """Lazy import to avoid pulling omni/Isaac at module-import time."""
+    from strands_robots_sim.isaac.simulation import IsaacSimulation
+
+    return IsaacSimulation
+
+
+def _lazy_isaac_config():
+    """Lazy import to avoid pulling dataclass internals at import time."""
+    from strands_robots_sim.isaac.config import IsaacConfig
+
+    return IsaacConfig
+
+
+def __getattr__(name: str):
+    """PEP 562 lazy attribute access."""
+    if name == "IsaacSimulation":
+        return _lazy_isaac_simulation()
+    if name == "IsaacConfig":
+        return _lazy_isaac_config()
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

strands_robots_sim/isaac/tests/__init__.py

@@ -0,0 +1 @@
+"""strands_robots_sim.isaac.tests package."""

strands_robots_sim/isaac/tests/test_entrypoint.py

@@ -0,0 +1,140 @@
+"""Entry-point + lazy-import tests for the Isaac backend skeleton.
+
+This is the PR-1 slice of #31 (see issue #42): the `[isaac]` extra,
+the ``strands_robots.backends`` entry points, and the PEP 562 lazy
+``strands_robots_sim.isaac`` import surface.
+
+Class-level contracts that depend on
+``strands_robots_sim.isaac.simulation`` (``SimEngine`` subclassing,
+abstract-method completeness, ``is_available()`` return shape, no-GPU
+constructor) are covered in PR-4 once that module lands; importing
+``IsaacSimulation`` here would create a hard dependency on PR-4 that
+defeats the point of the split.
+
+Run with:: pytest strands_robots_sim/isaac/tests/test_entrypoint.py -v
+"""
+
+from __future__ import annotations
+
+import importlib.metadata
+import pathlib
+
+import pytest
+
+_PYPROJECT = pathlib.Path(__file__).resolve().parents[3] / "pyproject.toml"
+
+
+class TestEntryPointDeclaration:
+    """Validate that ``strands_robots.backends`` entry points are declared."""
+
+    def test_pyproject_exists(self):
+        assert _PYPROJECT.exists(), f"pyproject.toml not found at {_PYPROJECT}"
+
+    def test_isaac_entry_point_declared_in_pyproject(self):
+        """``isaac`` entry point points at the planned simulation module."""
+        content = _PYPROJECT.read_text()
+        assert 'isaac = "strands_robots_sim.isaac.simulation:IsaacSimulation"' in content, (
+            'Expected `isaac = "strands_robots_sim.isaac.simulation:IsaacSimulation"` '
+            'under [project.entry-points."strands_robots.backends"] in pyproject.toml. '
+            "PR-4 of the #31 split will land the simulation module the entry point resolves to."
+        )
+
+    def test_isaac_sim_alias_entry_point_declared_in_pyproject(self):
+        """``isaac_sim`` alias is declared alongside ``isaac``."""
+        content = _PYPROJECT.read_text()
+        assert 'isaac_sim = "strands_robots_sim.isaac.simulation:IsaacSimulation"' in content, (
+            "Expected `isaac_sim` alias entry point alongside `isaac` so users can write either "
+            '`create_simulation("isaac")` or `create_simulation("isaac_sim")`.'
+        )
+
+    def test_isaac_extra_declared_in_pyproject(self):
+        """``[project.optional-dependencies] isaac = [...]`` extra exists."""
+        content = _PYPROJECT.read_text()
+        assert "\nisaac = [" in content or "\nisaac=[" in content, (
+            "Expected `isaac = [...]` under [project.optional-dependencies] declaring "
+            "the pip-installable subset of Isaac Sim's runtime deps (usd-core, warp-lang, pytest)."
+        )
+
+    def test_isaac_extra_includes_pytest(self):
+        """``[isaac]`` ships pytest so ``pip install '.[isaac]'`` is enough to run the suite."""
+        content = _PYPROJECT.read_text()
+        # crude but durable: locate the [isaac] block and check its body
+        idx = content.find("\nisaac = [")
+        assert idx != -1, "[isaac] extras block not found"
+        block_end = content.find("]", idx)
+        block = content[idx:block_end]
+        assert "pytest" in block, (
+            "[isaac] extras must include pytest so `pip install '.[isaac]'` covers the test deps "
+            "without requiring a separate dev extra on CI hosts."
+        )
+
+    def test_entry_points_visible_via_importlib_metadata_when_installed(self):
+        """If the package is pip-installed in this env, entry points are discoverable."""
+        try:
+            eps = importlib.metadata.entry_points()
+            if hasattr(eps, "select"):
+                backend_eps = list(eps.select(group="strands_robots.backends"))
+            else:
+                backend_eps = eps.get("strands_robots.backends", [])
+        except Exception as exc:  # pragma: no cover - defensive
+            pytest.skip(f"importlib.metadata unavailable: {exc}")
+
+        if not backend_eps:
+            pytest.skip(
+                "Package not installed (no entry points discoverable). "
+                "Run `pip install -e .` to validate this assertion locally."
+            )
+
+        names = {ep.name for ep in backend_eps}
+        if "isaac" not in names and "isaac_sim" not in names:
+            pytest.skip(
+                "Package installed but entry-point cache is stale -- reinstall after "
+                "pyproject.toml change: `pip install -e . --force-reinstall --no-deps`."
+            )
+
+        for ep in backend_eps:
+            if ep.name in {"isaac", "isaac_sim"}:
+                assert ep.value == "strands_robots_sim.isaac.simulation:IsaacSimulation", (
+                    f"Entry point {ep.name!r} resolves to {ep.value!r}; expected "
+                    "'strands_robots_sim.isaac.simulation:IsaacSimulation'."
+                )
+
+
+class TestLazyImportSurface:
+    """Validate the PEP 562 lazy-import contract on the ``isaac`` subpackage."""
+
+    def test_import_isaac_does_not_load_omni(self):
+        """Importing ``strands_robots_sim.isaac`` adds zero ``omni.*`` modules."""
+        import sys
+
+        before = {k for k in sys.modules if k.startswith("omni")}
+        import strands_robots_sim.isaac  # noqa: F401
+
+        added = {k for k in sys.modules if k.startswith("omni")} - before
+        assert added == set(), (
+            f"Importing strands_robots_sim.isaac loaded omni modules: {sorted(added)}. "
+            "The PEP 562 lazy stub must defer `omni` resolution until an attribute is accessed."
+        )
+
+    def test_isaac_subpackage_exposes_lazy_attrs_in___all__(self):
+        """``__all__`` advertises the planned public surface."""
+        import strands_robots_sim.isaac as isaac_pkg
+
+        assert "IsaacSimulation" in isaac_pkg.__all__
+        assert "IsaacConfig" in isaac_pkg.__all__
+
+    def test_unknown_attr_raises_attributeerror(self):
+        """Unknown attribute access raises AttributeError, not ImportError."""
+        import strands_robots_sim.isaac as isaac_pkg
+
+        with pytest.raises(AttributeError, match="no attribute 'NotARealClass'"):
+            _ = isaac_pkg.NotARealClass
+
+    def test_dunder_getattr_is_present(self):
+        """The PEP 562 hook is defined at module level."""
+        import strands_robots_sim.isaac as isaac_pkg
+
+        assert hasattr(
+            isaac_pkg, "__getattr__"
+        ), "PEP 562 module-level __getattr__ must be defined for lazy import to work."
+        assert callable(isaac_pkg.__getattr__)