feat: MuJoCo simulation backend — AgentTool with 35 actions

.github/workflows/test-lint.yml

@@ -26,6 +26,11 @@ jobs:
           python-version: '3.12'
           cache: 'pip'
 
+      - name: Install system dependencies (OpenGL for MuJoCo)
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y libosmesa6-dev
+
       - name: Install dependencies
         run: |
           pip install --no-cache-dir hatch
@@ -35,4 +40,6 @@ jobs:
         run: hatch run lint
 
       - name: Run tests
+        env:
+          MUJOCO_GL: osmesa
         run: hatch run test -x --strict-markers

README.md

@@ -486,6 +486,31 @@ while True:
 agent.tool.gr00t_inference(action="stop", port=8000)
 ```
 
+## Configuration
+
+### Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `STRANDS_ASSETS_DIR` | Custom directory for robot model assets (MJCF, meshes) | `~/.strands_robots/assets/` |
+| `GROOT_API_TOKEN` | API token for GR00T inference service | — |
+
+### Cache Directory
+
+Robot model assets (MJCF XML files and meshes) are cached in:
+
+```
+~/.strands_robots/
+└── assets/           # Downloaded robot models (from robot_descriptions / MuJoCo Menagerie)
+    ├── trs_so_arm100/
+    ├── franka_emika_panda/
+    └── ...
+```
+
+To clear the cache: `rm -rf ~/.strands_robots/assets/`
+
+To change the cache location: `export STRANDS_ASSETS_DIR=/path/to/custom/dir`
+
 ## Contributing
 
 We welcome contributions! Please see:

pyproject.toml

@@ -50,9 +50,19 @@ groot-service = [
 lerobot = [
     "lerobot>=0.5.0,<0.6.0",
 ]
+sim = [
+    "robot_descriptions>=1.11.0,<2.0.0",
+]
+sim-mujoco = [
+    "mujoco>=3.0.0,<4.0.0",
+    "imageio>=2.28.0,<3.0.0",
+    "imageio-ffmpeg>=0.4.0,<1.0.0",
+]
 all = [
     "strands-robots[groot-service]",
     "strands-robots[lerobot]",
+    "strands-robots[sim]",
+    "strands-robots[sim-mujoco]",
 ]
 dev = [
     "pytest>=6.0,<9.0.0",
@@ -125,7 +135,7 @@ ignore_missing_imports = false
 
 # Third-party libs without type stubs
 [[tool.mypy.overrides]]
-module = ["lerobot.*", "gr00t.*", "draccus.*", "msgpack.*", "zmq.*", "huggingface_hub.*", "serial.*", "psutil.*", "torch.*", "torchvision.*", "transformers.*", "einops.*"]
+module = ["lerobot.*", "gr00t.*", "draccus.*", "msgpack.*", "zmq.*", "huggingface_hub.*", "serial.*", "psutil.*", "torch.*", "torchvision.*", "transformers.*", "einops.*", "robot_descriptions.*", "mujoco.*", "imageio.*"]
 ignore_missing_imports = true
 
 # @tool decorator injects runtime signatures mypy cannot check
@@ -158,6 +168,22 @@ module = ["strands_robots.registry.*"]
 warn_return_any = false
 disallow_untyped_defs = false
 
+# MuJoCo simulation — mixins use cooperative self._world patterns
+# attr-defined: Mixins access self._world/self._lock/etc. from Simulation (cooperative pattern)
+# assignment: PEP 484 implicit Optional (= None on typed params)
+# override: Subclass signatures extend base with extra params (orientation, mesh_path)
+# misc: Multiple inheritance method resolution conflicts between mixin + ABC
+[[tool.mypy.overrides]]
+module = ["strands_robots.simulation.mujoco.*"]
+disallow_untyped_defs = false
+warn_return_any = false
+
+# Async utils and dataset recorder — thin wrappers with dynamic types
+[[tool.mypy.overrides]]
+module = ["strands_robots._async_utils", "strands_robots.dataset_recorder"]
+disallow_untyped_defs = false
+warn_return_any = false
+
 # Test files — relaxed type checking for mocks, fixtures, and test utilities
 [[tool.mypy.overrides]]
 module = ["tests.*", "tests_integ.*"]

strands_robots/_async_utils.py

@@ -0,0 +1,31 @@
+"""Async-to-sync helper for resolving coroutines in sync contexts."""
+
+import asyncio
+import concurrent.futures
+
+# Module-level executor reused across calls to avoid creating threads at high frequency.
+# A single worker is sufficient — we only need to offload one asyncio.run() at a time.
+_EXECUTOR = concurrent.futures.ThreadPoolExecutor(max_workers=1, thread_name_prefix="strands_async")
+
+
+def _resolve_coroutine(coro_or_result):  # type: ignore[no-untyped-def]
+    """Safely resolve a potentially-async result to a sync value.
+
+    Handles three cases:
+        1. Already a plain value → return as-is
+        2. Coroutine, no running loop → asyncio.run()
+        3. Coroutine, inside running loop → offload to reused thread
+
+    Args:
+        coro_or_result: Either a coroutine or an already-resolved value.
+
+    Returns:
+        The resolved (sync) value.
+    """
+    if not asyncio.iscoroutine(coro_or_result):
+        return coro_or_result
+    try:
+        asyncio.get_running_loop()
+        return _EXECUTOR.submit(asyncio.run, coro_or_result).result()
+    except RuntimeError:
+        return asyncio.run(coro_or_result)

strands_robots/assets/__init__.py

@@ -0,0 +1,42 @@
+"""Robot Asset Manager for Strands Robots Simulation.
+
+Assets are resolved from ``robot_descriptions`` package or downloaded from
+MuJoCo Menagerie GitHub, cached in ``~/.strands_robots/assets/``.
+Override with ``STRANDS_ASSETS_DIR`` env var.
+
+Implementation lives in ``assets/manager.py`` — this file is thin exports only.
+"""
+
+from strands_robots.assets.manager import (
+    get_assets_dir,
+    get_robot_info,
+    get_search_paths,
+    list_available_robots,
+    resolve_model_dir,
+    resolve_model_path,
+)
+from strands_robots.registry import (
+    format_robot_table,
+    get_robot,
+    list_aliases,
+    list_robots,
+    list_robots_by_category,
+)
+from strands_robots.registry import (
+    resolve_name as resolve_robot_name,
+)
+
+__all__ = [
+    "resolve_model_path",
+    "resolve_model_dir",
+    "resolve_robot_name",
+    "get_robot_info",
+    "list_available_robots",
+    "list_robots_by_category",
+    "list_aliases",
+    "format_robot_table",
+    "get_assets_dir",
+    "get_search_paths",
+    "get_robot",
+    "list_robots",
+]

strands_robots/assets/download.py

@@ -0,0 +1,18 @@
+"""Download robot model assets — redirects to strands_robots.tools.download_assets.
+
+The download tool is strands_robots/tools/download_assets.py and downloads to
+~/.strands_robots/assets/ (user cache) instead of the bundled package dir.
+"""
+
+from strands_robots.tools.download_assets import (
+    _needs_download,  # noqa: F401
+    download_assets,
+    download_robots,
+    get_user_assets_dir,
+    main,
+)
+
+__all__ = ["download_assets", "download_robots", "get_user_assets_dir", "main"]
+
+if __name__ == "__main__":
+    main()