lang2sim 2.0.0__py3-none-any.whl

lang2sim/perturbation/routers/world.py

@@ -0,0 +1,110 @@
+"""FastAPI router for dynamic simulation stress mutations (/v1/world).
+
+Mounted inside the simulation container (Control API server, :9090)
+or accessible via ControlClient on host.
+"""
+
+from __future__ import annotations
+
+from typing import Any, List, Optional
+from fastapi import APIRouter, FastAPI, HTTPException
+from pydantic import BaseModel, Field
+
+from lang2sim.perturbation._compat import Pose2D
+from lang2sim.perturbation.gazebo_bridge import GazeboBridge, get_bridge
+
+router = APIRouter(prefix="/world", tags=["world_mutation"])
+
+
+class SpawnRequest(BaseModel):
+    model_name: str = Field("wooden_crate", description="Asset type to spawn")
+    x: float = Field(2.0, description="X coordinate in meters")
+    y: float = Field(0.0, description="Y coordinate in meters")
+    z: float = Field(0.5, description="Z coordinate in meters")
+    yaw: float = Field(0.0, description="Heading rotation in radians")
+    linear_velocity: Optional[List[float]] = Field(None, description="Initial [vx, vy, vz]")
+    angular_velocity: Optional[List[float]] = Field(None, description="Initial [wx, wy, wz]")
+    entity_name: Optional[str] = Field(None, description="Optional custom entity name")
+
+
+class LightRequest(BaseModel):
+    diffuse: float = Field(0.5, ge=0.0, le=1.0, description="Sun diffuse reflectance")
+    specular: float = Field(0.1, ge=0.0, le=1.0, description="Sun specular reflectance")
+    intensity: Optional[float] = Field(None, ge=0.0, le=1.0, description="Overall luminance multiplier")
+    light_name: str = Field("sun", description="Target light entity")
+
+
+class ResetRequest(BaseModel):
+    mode: str = Field("world", description="Reset scope ('world' or 'robot')")
+
+
+class ChassisPerturbationRequest(BaseModel):
+    force_x: float = Field(10.0, description="X impulse force / velocity bias")
+    force_y: float = Field(0.0, description="Y impulse force / velocity bias")
+    force_z: float = Field(0.0, description="Z angular impulse / yaw velocity bias")
+    duration_s: float = Field(0.2, ge=0.01, le=5.0, description="Impulse duration in seconds")
+    robot_model: str = Field("turtlebot3_waffle", description="Target robot model name")
+
+
+@router.post("/spawn")
+async def spawn_entity(req: SpawnRequest) -> dict[str, Any]:
+    bridge: GazeboBridge = get_bridge()
+    res = await bridge.spawn_entity(
+        req.model_name,
+        Pose2D(x=req.x, y=req.y, yaw=req.yaw),
+    )
+    if not res.ok:
+        raise HTTPException(status_code=500, detail=res.to_dict())
+    return res.to_dict()
+
+
+@router.post("/light")
+async def set_light(req: LightRequest) -> dict[str, Any]:
+    bridge: GazeboBridge = get_bridge()
+    lum = req.intensity if req.intensity is not None else req.diffuse
+    res = await bridge.set_light(lum)
+    if not res.ok:
+        raise HTTPException(status_code=500, detail=res.to_dict())
+    return res.to_dict()
+
+
+@router.post("/reset")
+async def reset_world(req: Optional[ResetRequest] = None) -> dict[str, Any]:
+    bridge: GazeboBridge = get_bridge()
+    mode = req.mode if req and req.mode else "world"
+    res = await bridge.reset(mode)
+    if not res.ok:
+        raise HTTPException(status_code=500, detail=res.to_dict())
+    return res.to_dict()
+
+
+@router.post("/chassis")
+async def apply_chassis(req: ChassisPerturbationRequest) -> dict[str, Any]:
+    bridge: GazeboBridge = get_bridge()
+    res = await bridge.apply_perturbation(
+        Pose2D(x=req.force_x, y=req.force_y, yaw=req.force_z),
+        duration_s=req.duration_s,
+    )
+    if not res.ok:
+        raise HTTPException(status_code=500, detail=res.to_dict())
+    return res.to_dict()
+
+
+@router.get("/health")
+def world_health() -> dict[str, Any]:
+    bridge: GazeboBridge = get_bridge()
+    h = bridge.health()
+    h["ok"] = h.get("status") in ("ready", "healthy", "ok")
+    return h
+
+
+@router.get("/entities")
+def list_entities() -> dict[str, Any]:
+    bridge: GazeboBridge = get_bridge()
+    entities = bridge.list_spawned_entities()
+    return {"backend": type(bridge).__name__, "count": len(entities), "entities": entities}
+
+
+def mount_world_router(app: FastAPI, prefix: str = "/v1") -> None:
+    """Convenience helper to mount the world router into any FastAPI app."""
+    app.include_router(router, prefix=prefix)

lang2sim/perturbation/sdf_snippets.py

@@ -0,0 +1,112 @@
+"""Fallback inline SDF definitions for dynamic obstacle models.
+
+Used when pre-compiled models are not found on the local filesystem or Fuel catalog.
+Provides physics collision geometries, inertial tensors, and basic PBR/diffuse visuals.
+"""
+
+from __future__ import annotations
+
+_WOODEN_CRATE_SDF = """<?xml version="1.0" ?>
+<sdf version="1.6">
+  <model name="{name}">
+    <static>false</static>
+    <link name="link">
+      <inertial>
+        <mass>10.0</mass>
+        <inertia>
+          <ixx>0.6</ixx><ixy>0</ixy><ixz>0</ixz>
+          <iyy>0.6</iyy><iyz>0</iyz><izz>0.6</izz>
+        </inertia>
+      </inertial>
+      <collision name="collision">
+        <geometry>
+          <box><size>0.6 0.6 0.6</size></box>
+        </geometry>
+      </collision>
+      <visual name="visual">
+        <geometry>
+          <box><size>0.6 0.6 0.6</size></box>
+        </geometry>
+        <material>
+          <ambient>0.6 0.4 0.2 1</ambient>
+          <diffuse>0.6 0.4 0.2 1</diffuse>
+        </material>
+      </visual>
+    </link>
+  </model>
+</sdf>
+"""
+
+_BARREL_SDF = """<?xml version="1.0" ?>
+<sdf version="1.6">
+  <model name="{name}">
+    <static>false</static>
+    <link name="link">
+      <inertial>
+        <mass>15.0</mass>
+        <inertia>
+          <ixx>1.2</ixx><ixy>0</ixy><ixz>0</ixz>
+          <iyy>1.2</iyy><iyz>0</iyz><izz>0.675</izz>
+        </inertia>
+      </inertial>
+      <collision name="collision">
+        <geometry>
+          <cylinder><radius>0.3</radius><length>0.9</length></cylinder>
+        </geometry>
+      </collision>
+      <visual name="visual">
+        <geometry>
+          <cylinder><radius>0.3</radius><length>0.9</length></cylinder>
+        </geometry>
+        <material>
+          <ambient>0.2 0.3 0.6 1</ambient>
+          <diffuse>0.2 0.3 0.6 1</diffuse>
+        </material>
+      </visual>
+    </link>
+  </model>
+</sdf>
+"""
+
+_CARGO_BOX_SDF = """<?xml version="1.0" ?>
+<sdf version="1.6">
+  <model name="{name}">
+    <static>false</static>
+    <link name="link">
+      <inertial>
+        <mass>20.0</mass>
+        <inertia>
+          <ixx>1.2</ixx><ixy>0</ixy><ixz>0</ixz>
+          <iyy>2.2</iyy><iyz>0</iyz><izz>2.2</izz>
+        </inertia>
+      </inertial>
+      <collision name="collision">
+        <geometry>
+          <box><size>1.0 0.6 0.6</size></box>
+        </geometry>
+      </collision>
+      <visual name="visual">
+        <geometry>
+          <box><size>1.0 0.6 0.6</size></box>
+        </geometry>
+        <material>
+          <ambient>0.5 0.5 0.5 1</ambient>
+          <diffuse>0.7 0.7 0.2 1</diffuse>
+        </material>
+      </visual>
+    </link>
+  </model>
+</sdf>
+"""
+
+MODELS = {
+    "wooden_crate": _WOODEN_CRATE_SDF,
+    "barrel": _BARREL_SDF,
+    "cargo_box": _CARGO_BOX_SDF,
+}
+
+
+def get_inline_sdf(model_name: str, entity_name: str) -> str:
+    """Return inline SDF string for known models, formatted with entity name."""
+    template = MODELS.get(model_name, _WOODEN_CRATE_SDF)
+    return template.format(name=entity_name).strip()

lang2sim/runtime/__init__.py

@@ -0,0 +1,7 @@
+"""Part 3: container runtime, display/GPU selection, control API, Nav2 launch.
+
+Host side:      platform, hardware_probe, display, docker_runner, doctor, control_api.client
+Container side: control_api.server (FastAPI on :9090, needs the `sim` extra)
+
+Keep this module import-light: the TUI imports it on startup.
+"""

lang2sim/runtime/control_api/__init__.py

@@ -0,0 +1,7 @@
+"""Control API: FastAPI server inside the sim container, async client on the host.
+
+Versioned under /v1. Import `client` on the host; `server` needs fastapi/uvicorn
+(present in the sim image, or `pip install -e .[sim]`).
+"""
+
+API_PREFIX = "/v1"

lang2sim/runtime/control_api/client.py

@@ -0,0 +1,187 @@
+"""
+Async control API client. Runs on the HOST (TUI / agent tools / doctor).
+File: lang2sim/runtime/control_api/client.py
+
+    async with ControlClient() as api:
+        await api.wait_until_ready(timeout=60)
+        await api.sim_start(SimStartRequest(...))
+        print(await api.sim_status())
+
+Uses httpx; pass `transport=httpx.ASGITransport(app)` in tests to talk to the
+server in-process.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import importlib
+import time
+from typing import Any, AsyncIterator, Dict, List, Optional, Sequence
+
+import httpx
+
+from lang2sim.core.models import (
+    NavGoalRequest,
+    NavInitialPoseRequest,
+    NavStatus,
+    NavWaypointsRequest,
+    Pose2D,
+    SimStartRequest,
+    SimStatus,
+    SimStatusResponse,
+    SimStopRequest,
+)
+from lang2sim.runtime.control_api import API_PREFIX
+
+# NB: `from lang2sim.core import config` yields the Config *instance* (core/__init__
+# re-exports it under the module's name), so load the module explicitly.
+cfg = importlib.import_module("lang2sim.core.config")
+
+
+class ControlAPIError(RuntimeError):
+    def __init__(self, message: str, status_code: Optional[int] = None):
+        super().__init__(message)
+        self.status_code = status_code
+
+
+class ControlAPIUnavailable(ControlAPIError):
+    """Container not up / API not listening yet."""
+
+
+def default_base_url() -> str:
+    return f"http://127.0.0.1:{cfg.DEFAULT_CONTROL_PORT}"
+
+
+class ControlClient:
+    def __init__(self, base_url: Optional[str] = None, timeout: float = 10.0,
+                 transport: Optional[httpx.AsyncBaseTransport] = None):
+        self.base_url = (base_url or default_base_url()).rstrip("/")
+        self._http = httpx.AsyncClient(base_url=self.base_url + API_PREFIX,
+                                       timeout=timeout, transport=transport)
+
+    async def __aenter__(self) -> "ControlClient":
+        return self
+
+    async def __aexit__(self, *exc: Any) -> None:
+        await self.aclose()
+
+    async def aclose(self) -> None:
+        await self._http.aclose()
+
+    async def _request(self, method: str, path: str, **kw: Any) -> Any:
+        try:
+            r = await self._http.request(method, path, **kw)
+        except (httpx.ConnectError, httpx.ReadError, httpx.RemoteProtocolError,
+                httpx.ConnectTimeout) as e:
+            raise ControlAPIUnavailable(f"control API not reachable at {self.base_url}: {e}") from e
+        if r.status_code >= 400:
+            try:
+                detail = r.json().get("detail", r.text)
+            except ValueError:
+                detail = r.text
+            raise ControlAPIError(f"{method} {path} -> {r.status_code}: {detail}", r.status_code)
+        return r.json()
+
+    # --- endpoints -------------------------------------------------------
+    async def health(self) -> Dict[str, Any]:
+        return await self._request("GET", "/health")
+
+    async def info(self) -> Dict[str, Any]:
+        return await self._request("GET", "/info")
+
+    async def sim_status(self) -> SimStatusResponse:
+        return SimStatusResponse.model_validate(await self._request("GET", "/sim/status"))
+
+    async def sim_start(self, req: SimStartRequest) -> SimStatusResponse:
+        data = await self._request("POST", "/sim/start", json=req.model_dump(mode="json"))
+        return SimStatusResponse.model_validate(data)
+
+    async def sim_stop(self, force: bool = False) -> SimStatusResponse:
+        data = await self._request("POST", "/sim/stop",
+                                   json=SimStopRequest(force=force).model_dump(mode="json"))
+        return SimStatusResponse.model_validate(data)
+
+    async def sim_logs(self, tail: int = 200) -> List[str]:
+        return (await self._request("GET", "/sim/logs", params={"tail": tail}))["lines"]
+
+    # --- Part 4 world mutation endpoints ---------------------------------
+    async def world_spawn(self, req: Dict[str, Any]) -> Dict[str, Any]:
+        return await self._request("POST", "/world/spawn", json=req)
+
+    async def world_light(self, req: Dict[str, Any]) -> Dict[str, Any]:
+        return await self._request("POST", "/world/light", json=req)
+
+    async def world_reset(self, req: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+        return await self._request("POST", "/world/reset", json=req or {})
+
+    async def world_chassis(self, req: Dict[str, Any]) -> Dict[str, Any]:
+        return await self._request("POST", "/world/chassis", json=req)
+
+    async def world_health(self) -> Dict[str, Any]:
+        return await self._request("GET", "/world/health")
+
+    async def world_entities(self) -> Dict[str, Any]:
+        return await self._request("GET", "/world/entities")
+
+    # --- navigation and telemetry -----------------------------------------------
+    async def nav_initial_pose(self, pose: Pose2D) -> NavStatus:
+        data = await self._request("POST", "/nav/initial_pose",
+                                   json=NavInitialPoseRequest(pose=pose).model_dump(mode="json"))
+        return NavStatus.model_validate(data)
+
+    async def nav_goal(self, goal: Pose2D, timeout_seconds: float = 120.0) -> NavStatus:
+        body = NavGoalRequest(goal_pose=goal, timeout_seconds=timeout_seconds).model_dump(mode="json")
+        return NavStatus.model_validate(await self._request("POST", "/nav/goal", json=body))
+
+    async def nav_waypoints(self, waypoints: Sequence[Pose2D], timeout_seconds: float = 180.0) -> NavStatus:
+        body = NavWaypointsRequest(waypoints=list(waypoints), timeout_seconds=timeout_seconds).model_dump(mode="json")
+        return NavStatus.model_validate(await self._request("POST", "/nav/waypoints", json=body))
+
+    async def nav_cancel(self) -> NavStatus:
+        return NavStatus.model_validate(await self._request("POST", "/nav/cancel"))
+
+    async def nav_status(self) -> NavStatus:
+        return NavStatus.model_validate(await self._request("GET", "/nav/status"))
+
+    async def telemetry(self) -> SimStatus:
+        return SimStatus.model_validate(await self._request("GET", "/telemetry"))
+
+    async def nav_feedback(self, hz: float = 5.0) -> AsyncIterator[Dict[str, Any]]:
+        """Stream {"nav": NavStatus, "telemetry": SimStatus, "sim": {...}} dicts from WS /v1/nav/feedback.
+
+            async for msg in api.nav_feedback():
+                print(msg["nav"]["distance_remaining"])
+        """
+        import json
+
+        import websockets
+
+        url = self.base_url.replace("http", "ws", 1) + API_PREFIX + f"/nav/feedback?hz={hz}"
+        try:
+            async with websockets.connect(url) as ws:
+                async for raw in ws:
+                    yield json.loads(raw)
+        except OSError as e:
+            raise ControlAPIUnavailable(f"feedback stream not reachable at {url}: {e}") from e
+
+    async def wait_nav_done(self, poll_s: float = 1.0, timeout: float = 1800.0) -> NavStatus:
+        """Poll /nav/status until the current task is no longer active."""
+        deadline = time.monotonic() + timeout
+        while True:
+            st = await self.nav_status()
+            if not st.is_active or time.monotonic() > deadline:
+                return st
+            await asyncio.sleep(poll_s)
+
+    # --- helpers ---------------------------------------------------------
+    async def wait_until_ready(self, timeout: float = 60.0, interval: float = 0.5) -> Dict[str, Any]:
+        """Poll /health until it answers (container boot + uvicorn start)."""
+        deadline = time.monotonic() + timeout
+        last: Optional[Exception] = None
+        while time.monotonic() < deadline:
+            try:
+                return await self.health()
+            except ControlAPIUnavailable as e:
+                last = e
+                await asyncio.sleep(interval)
+        raise ControlAPIUnavailable(f"control API not ready after {timeout:.0f}s ({last})")