feat: simulation foundation — models, ABC, factory, model registry, assets

.gitignore

@@ -9,3 +9,4 @@ build
 dist
 .strands_robots
 .coverage
+.ideation/

AGENTS.md

@@ -84,3 +84,19 @@ hatch run format            # ruff check --fix, ruff format
 4. Open PR from your fork, address all review comments
 5. Track follow-up items as issues on the [project board](https://github.com/orgs/strands-labs/projects/2)
 6. Squash merge into `main`
+
+
+## Registry conventions (strands_robots/registry/robots.json)
+
+- **Flat asset paths** (e.g. `"model_xml": "scene.xml"`) are the common case.
+- **Nested asset paths** (e.g. `"model_xml": "xmls/asimov.xml"`) are allowed when
+  the upstream source repo uses a subdir layout. Example: `asimov_v0` maps to
+  `asimovinc/asimov-v0` which has `sim-model/xmls/asimov.xml` +
+  `sim-model/assets/`. The `_safe_join` helper in `strands_robots/utils.py`
+  guards against traversal (`..`).
+- **Auto-download strategy** — every robot with an `asset` block must declare
+  exactly one of:
+    1. `asset.robot_descriptions_module` (preferred)
+    2. `asset.source` with `type: "github"`
+    3. `asset.auto_download: false` (explicit opt-out)
+  Enforced by `tests/test_registry_integrity.py`.

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

@@ -48,9 +48,13 @@ groot-service = [
 lerobot = [
     "lerobot>=0.5.0,<0.6.0",
 ]
+sim = [
+    "robot_descriptions>=1.11.0,<2.0.0",
+]
 all = [
     "strands-robots[groot-service]",
     "strands-robots[lerobot]",
+    "strands-robots[sim]",
 ]
 dev = [
     "pytest>=6.0,<9.0.0",
@@ -124,7 +128,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.*"]
 ignore_missing_imports = true
 
 # @tool decorator injects runtime signatures mypy cannot check

strands_robots/assets/__init__.py

@@ -0,0 +1,41 @@
+"""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_robot_info,
+    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,
+)
+from strands_robots.utils import get_assets_dir, get_search_paths
+
+__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",
+]