roborouter 0.0.1__tar.gz

roborouter-0.0.1/.gitignore

@@ -0,0 +1,2 @@
+dist/
+.venv/

roborouter-0.0.1/PKG-INFO

@@ -0,0 +1,46 @@
+Metadata-Version: 2.5
+Name: roborouter
+Version: 0.0.1
+Summary: Run a robot on any model with a key and one call.
+Author: Momentum
+License: Apache-2.0
+Keywords: models,momentum,robotics
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.28
+Requires-Dist: msgpack>=1.0
+Provides-Extra: dev
+Requires-Dist: pytest>=9.1; extra == 'dev'
+Requires-Dist: ruff>=0.16; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# RoboRouter
+
+Run a robot, in a simulator or the real world, on any model with a key and one call.
+
+**Not ready for use yet.** The service isn't open to new users, and the only model so far is a test script.
+
+```bash
+pip install roborouter
+export MOMENTUM_API_KEY=fw_cli_...   # Settings, Workspace API keys
+```
+
+```python
+import roborouter
+
+config = {"model": "momentum/scripted"}
+
+while True:
+    state = {"joints": read_my_joints(), "images": {"top": read_my_camera_jpeg()}}
+    reply = roborouter.control_robot(config, state, "pick up the fork")
+    if reply.finished:
+        break
+    move_my_robot(reply.joints)
+```
+
+`joints` is a map of your joint names to their positions, for any number of arms. `images` is optional, and each frame is JPEG bytes. `momentum/scripted` nudges every joint a little for a few moves and then finishes, so you can check the loop with no model provider involved.
+
+**With no details from you, nothing checks the targets.** A bad reply moves the arm as far as your robot's own limits allow. `control_robot` raises `RoboRouterError` when it can't get an answer, so hold your robot on an exception.
+
+`control_robot` drives one robot per process. For several robots, give each its own `roborouter.Router()` and call `router.control_robot(...)`.
+
+`reply.usage` has tokens and cost. `reply.timings` has the time each stage took, in milliseconds.

roborouter-0.0.1/README.md

@@ -0,0 +1,31 @@
+# RoboRouter
+
+Run a robot, in a simulator or the real world, on any model with a key and one call.
+
+**Not ready for use yet.** The service isn't open to new users, and the only model so far is a test script.
+
+```bash
+pip install roborouter
+export MOMENTUM_API_KEY=fw_cli_...   # Settings, Workspace API keys
+```
+
+```python
+import roborouter
+
+config = {"model": "momentum/scripted"}
+
+while True:
+    state = {"joints": read_my_joints(), "images": {"top": read_my_camera_jpeg()}}
+    reply = roborouter.control_robot(config, state, "pick up the fork")
+    if reply.finished:
+        break
+    move_my_robot(reply.joints)
+```
+
+`joints` is a map of your joint names to their positions, for any number of arms. `images` is optional, and each frame is JPEG bytes. `momentum/scripted` nudges every joint a little for a few moves and then finishes, so you can check the loop with no model provider involved.
+
+**With no details from you, nothing checks the targets.** A bad reply moves the arm as far as your robot's own limits allow. `control_robot` raises `RoboRouterError` when it can't get an answer, so hold your robot on an exception.
+
+`control_robot` drives one robot per process. For several robots, give each its own `roborouter.Router()` and call `router.control_robot(...)`.
+
+`reply.usage` has tokens and cost. `reply.timings` has the time each stage took, in milliseconds.

roborouter-0.0.1/pyproject.toml

@@ -0,0 +1,31 @@
+[project]
+name = "roborouter"
+version = "0.0.1"
+description = "Run a robot on any model with a key and one call."
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "Apache-2.0" }
+authors = [{ name = "Momentum" }]
+keywords = ["momentum", "robotics", "models"]
+# The install stays small: no torch, numpy or robot libraries.
+dependencies = [
+    "httpx>=0.28",
+    "msgpack>=1.0",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=9.1", "ruff>=0.16"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/roborouter"]
+
+# Only the package itself goes public; tests, examples and benchmarks stay in this repo.
+[tool.hatch.build.targets.sdist]
+include = ["src/roborouter"]
+
+[tool.ruff.lint]
+select = ["E4", "E7", "E9", "F"]

roborouter-0.0.1/src/roborouter/__init__.py

@@ -0,0 +1,4 @@
+"""RoboRouter: run a robot on any model with a key and one call."""
+from roborouter.client import Reply, RoboRouterError, Router, control_robot
+
+__all__ = ["Reply", "RoboRouterError", "Router", "control_robot"]

roborouter-0.0.1/src/roborouter/client.py

@@ -0,0 +1,206 @@
+"""``control_robot``: send one move to a model and get the next joint targets back.
+
+This makes a run ID the first time an instruction is sent, then passes it with a step number on every
+call, and the server looks up the rest. A call only carries this move's state, as msgpack with camera
+frames as raw bytes, because encoding what comes off the robot is one of the biggest latency costs we
+control. One kept-alive connection serves every call, so a call doesn't pay for a new TLS handshake.
+"""
+from __future__ import annotations
+
+import math
+import os
+import threading
+import time
+import uuid
+from dataclasses import dataclass
+
+import httpx
+import msgpack
+
+DEFAULT_API_URL = "https://api-aws.momentumbots.io/api"
+TURNS_PATH = "/v1/router/turns"
+MEDIA_TYPE = "application/msgpack"
+# How long a model may take to answer. Assumed for now; real models may need it changed.
+CALL_TIMEOUT_SECONDS = 120
+RETRY_DELAYS_SECONDS = (0.5, 1.0, 2.0)
+_RETRY_STATUSES = {502, 503, 504}
+# The server won't take another step on these runs, so the next call starts a new one.
+_REFUSED_RUN_CODES = {"out_of_order", "run_finished", "run_mismatch"}
+
+
+class RoboRouterError(Exception):
+    """No answer for this move. Hold the robot."""
+
+    def __init__(self, code: str, message: str, param: str | None = None) -> None:
+        super().__init__(f"{code}: {message}")
+        self.code, self.message, self.param = code, message, param
+
+
+@dataclass(frozen=True)
+class Reply:
+    joints: dict[str, float] | None
+    finished: bool
+    reason: str | None
+    message: str | None
+    answered_by: str
+    usage: dict
+    timings: dict
+    run_id: str
+
+
+@dataclass
+class _Run:
+    id: str
+    step: int = 0
+    in_flight: bool = False
+
+
+def _model_of(config: object) -> str:
+    model = config.get("model") if isinstance(config, dict) else None
+    if not isinstance(model, str) or not model:
+        raise RoboRouterError("invalid_config", 'config needs a model, as {"model": "momentum/scripted"}.', "model")
+    return model
+
+
+def _joints_of(state: object) -> dict[str, float]:
+    joints = state.get("joints") if isinstance(state, dict) else None
+    if not isinstance(joints, dict) or not joints:
+        raise RoboRouterError("invalid_state", "state needs joints, a map of joint names to positions.", "joints")
+    positions = {}
+    for name, value in joints.items():
+        try:
+            position = float(value)
+        except (TypeError, ValueError):
+            raise RoboRouterError("invalid_state", f"Joint {name} is not a number: {value!r}.", f"joints.{name}")
+        if not math.isfinite(position):
+            raise RoboRouterError("invalid_state", f"Joint {name} is {position}.", f"joints.{name}")
+        positions[name] = position
+    return positions
+
+
+def _images_of(state: dict) -> dict | None:
+    images = state.get("images")
+    if images is None:
+        return None
+    if not isinstance(images, dict):
+        raise RoboRouterError("invalid_state", "images must be a map of camera names to JPEG bytes.", "images")
+    for name, frame in images.items():
+        if not isinstance(frame, (bytes, bytearray, memoryview)):
+            raise RoboRouterError("invalid_state", f"Camera {name} needs JPEG bytes, not {type(frame).__name__}.",
+                                  f"images.{name}")
+    return images
+
+
+def _api_error(response: httpx.Response) -> RoboRouterError:
+    try:
+        error = response.json()["error"]
+        return RoboRouterError(error["code"], error["message"], error.get("param"))
+    except (ValueError, KeyError, TypeError):
+        return RoboRouterError("http_error", f"The API answered with HTTP {response.status_code}.")
+
+
+def _reply_of(response: httpx.Response, run_id: str, extra_timings: dict) -> Reply:
+    try:
+        answer = msgpack.unpackb(response.content, raw=False)
+        return Reply(joints=answer["joints"], finished=answer["finished"], reason=answer["reason"],
+                     message=answer["message"], answered_by=answer["answered_by"], usage=answer["usage"],
+                     timings={**answer["timings"], **extra_timings}, run_id=run_id)
+    except (ValueError, TypeError, KeyError, msgpack.UnpackException):
+        raise RoboRouterError("bad_reply", "The API's reply couldn't be read. Hold the robot.")
+
+
+class Router:
+    """Holds the connection and the runs in progress. ``control_robot`` at module level uses a shared
+    one, which drives one robot. A process driving several robots gives each its own Router."""
+
+    def __init__(self, api_key: str | None = None, base_url: str | None = None,
+                 http: httpx.Client | None = None, sleep=time.sleep) -> None:
+        self._api_key, self._base_url, self._http, self._sleep = api_key, base_url, http, sleep
+        self._runs: dict[tuple[str, str], _Run] = {}
+        self._lock = threading.Lock()
+
+    def control_robot(self, config: dict, state: dict, instructions: str) -> Reply:
+        api_key = self._api_key or os.environ.get("MOMENTUM_API_KEY")
+        if not api_key:
+            raise RoboRouterError("no_api_key", "Set MOMENTUM_API_KEY to a workspace API key (fw_cli_…).")
+        started = time.perf_counter()
+        model = _model_of(config)
+        joints = _joints_of(state)
+        images = _images_of(state)
+        if not isinstance(instructions, str) or not instructions:
+            raise RoboRouterError("invalid_instructions", "instructions must be a non-empty string.", "instructions")
+
+        run_key = (model, instructions)
+        with self._lock:
+            run = self._runs.setdefault(run_key, _Run(id=uuid.uuid4().hex))
+            if run.in_flight:
+                raise RoboRouterError("run_busy", "Another call is already moving this run. To drive two robots "
+                                                  "in one process, give each its own roborouter.Router().")
+            run.in_flight = True
+        try:
+            reply = self._move(run, model, joints, images, instructions, api_key, started)
+        except RoboRouterError as error:
+            if error.code in _REFUSED_RUN_CODES:
+                with self._lock:
+                    self._runs.pop(run_key, None)
+            raise
+        else:
+            with self._lock:
+                if reply.finished:
+                    self._runs.pop(run_key, None)
+                else:
+                    run.step += 1
+            return reply
+        finally:
+            run.in_flight = False
+
+    def _move(self, run: _Run, model: str, joints: dict, images: dict | None, instructions: str, api_key: str,
+              started: float) -> Reply:
+        body = {"run_id": run.id, "step": run.step, "model": model, "joints": joints}
+        if images:
+            body["images"] = images
+        if run.step == 0:
+            body["instructions"] = instructions
+        payload = msgpack.packb(body, use_bin_type=True)
+        encode_ms = (time.perf_counter() - started) * 1000
+
+        sent = time.perf_counter()
+        response = self._post(payload, api_key)
+        round_trip_ms = (time.perf_counter() - sent) * 1000
+        if response.status_code != 200:
+            raise _api_error(response)
+        return _reply_of(response, run.id, {"encode_ms": encode_ms, "round_trip_ms": round_trip_ms})
+
+    def _post(self, payload: bytes, api_key: str) -> httpx.Response:
+        """Post, retrying the same step when the API can't be reached. The server returns its stored
+        reply for a step it already answered, so a retry never asks the model twice."""
+        base_url = self._base_url or os.environ.get("MOMENTUM_API_URL") or DEFAULT_API_URL
+        url = base_url.rstrip("/") + TURNS_PATH
+        headers = {"Authorization": f"Bearer {api_key}", "Content-Type": MEDIA_TYPE}
+        if self._http is None:
+            self._http = httpx.Client(timeout=CALL_TIMEOUT_SECONDS)
+        problem = "no answer"
+        for delay in (*RETRY_DELAYS_SECONDS, None):
+            try:
+                response = self._http.post(url, content=payload, headers=headers)
+                if response.status_code not in _RETRY_STATUSES:
+                    return response
+                problem = f"HTTP {response.status_code}"
+            except httpx.TransportError as exc:
+                problem = type(exc).__name__
+            if delay is not None:
+                self._sleep(delay)
+        raise RoboRouterError("unreachable", f"Could not reach {base_url}: {problem}. Hold the robot.")
+
+
+_default_router = Router()
+
+
+def control_robot(config: dict, state: dict, instructions: str) -> Reply:
+    """Send this move to the model in ``config`` and get the robot's next joint targets.
+
+    ``config`` needs ``{"model": ...}``. ``state`` needs ``{"joints": {name: position}}`` and may have
+    ``{"images": {camera: jpeg_bytes}}``. Raises :class:`RoboRouterError` when there's no answer, so
+    hold the robot on an exception.
+    """
+    return _default_router.control_robot(config, state, instructions)