roboapi 0.4.2__py3-none-any.whl

roboapi/policy/__init__.py

@@ -0,0 +1,7 @@
+"""Session-based model API client and coordinated action chunks."""
+
+from ..errors import PolicyUnavailable
+from .client import OpenAIChatPolicyClient
+from .protocol import ActionChunk
+
+__all__ = ["ActionChunk", "OpenAIChatPolicyClient", "PolicyUnavailable"]

roboapi/policy/client.py

@@ -0,0 +1,277 @@
+"""One model session per run, with serialized turns and execution feedback."""
+
+from __future__ import annotations
+
+import json
+import logging
+import re
+import threading
+import time
+from contextlib import closing
+from dataclasses import replace
+from urllib.parse import urlsplit
+
+import httpx
+import numpy as np
+
+from ..errors import PolicyUnavailable
+from .protocol import ActionChunk, decode_completion, decode_session, encode_observation
+from .settings import read_token
+
+logger = logging.getLogger(__name__)
+
+
+def _request_id(response) -> str | None:
+    value = response.headers.get("X-Request-ID", "")
+    return value if re.fullmatch(r"[A-Za-z0-9_.-]{1,128}", value) else None
+
+
+class OpenAIChatPolicyClient:
+    """Own the HTTP connection and current session; history stays on the server."""
+
+    def __init__(self, url: str, token_file: str, model: str, *, image_height: int | None = 360,
+                 timeout_s: float = 30.0, use_env_proxy: bool = True) -> None:
+        self._url = url.rstrip("/")
+        self._token_file = token_file
+        self._model = model
+        self._image_height = image_height
+        self._timeout_s = float(timeout_s)
+        self._use_env_proxy = use_env_proxy
+        self._host = urlsplit(url).hostname or "unknown"
+        self._http = None
+        self._session_lock = threading.RLock()
+        self._session_id: str | None = None
+        self._next_turn = 1
+        # A failed turn can still close its session. Unknown create/close outcomes
+        # are terminal and cannot be retried without preparing a new run.
+        self._state = "closed"  # closed | starting | open | failed | closing | unknown
+        self._inflight = False
+        self._pending_messages: list[dict] = []
+        self._awaiting_execution: tuple[int, dict] | None = None
+
+    @property
+    def session_status(self) -> dict:
+        with self._session_lock:
+            return {"id": self._session_id, "next_turn": self._next_turn,
+                    "status": "unknown" if self._state == "failed" else self._state}
+
+    @property
+    def ready(self) -> bool:
+        return self._http is not None
+
+    def _new_http(self, timeout_s: float):
+        return httpx.Client(
+            base_url=self._url + "/",
+            headers={"Authorization": f"Bearer {read_token(self._token_file)}",
+                     "Content-Type": "application/json", "Accept": "application/json"},
+            timeout=timeout_s, trust_env=self._use_env_proxy,
+        )
+
+    def _diagnostic(self, phase: str, kind: str, started: float, response=None) -> PolicyUnavailable:
+        fields = [f"policy {phase} {kind}", f"host={self._host}",
+                  f"elapsed_ms={(time.perf_counter() - started) * 1e3:.1f}"]
+        if response is not None:
+            fields.append(f"http_status={response.status_code}")
+            if request_id := _request_id(response):
+                fields.append(f"request_id={request_id}")
+        return PolicyUnavailable("; ".join(fields))
+
+    def _request(self, phase: str, path: str, *, body=None, http=None, decode=None):
+        """Send once, decode once, and expose only redacted network diagnostics."""
+        http = self._http if http is None else http
+        started = time.perf_counter()
+        try:
+            response = http.get(path) if body is None else http.post(path, json=body)
+            request_ms = (time.perf_counter() - started) * 1e3
+            if response.status_code >= 400:
+                kind = {401: "authentication rejected", 403: "model not authorized"}.get(
+                    response.status_code, "HTTP error",
+                )
+                raise self._diagnostic(phase, kind, started, response)
+            payload = response.json()
+            if not isinstance(payload, dict):
+                raise ValueError("response must be an object")
+            request_id = _request_id(response)
+            result = decode(payload, request_id) if decode else payload
+            logger.info("policy %s succeeded; host=%s; elapsed_ms=%.1f; http_status=%d; request_id=%s",
+                        phase, self._host, (time.perf_counter() - started) * 1e3,
+                        response.status_code, request_id or "none")
+            return result, request_ms
+        except PolicyUnavailable:
+            raise
+        except httpx.TransportError as exc:
+            kind = ("connect timeout" if isinstance(exc, httpx.ConnectTimeout) else
+                    "read timeout" if isinstance(exc, httpx.ReadTimeout) else "transport error")
+            raise self._diagnostic(phase, kind, started) from None
+        except (ValueError, TypeError, KeyError, IndexError, AttributeError, RuntimeError):
+            raise self._diagnostic(phase, "invalid response", started) from None
+
+    def connect(self) -> None:
+        if self.ready:
+            return
+        http = self._new_http(self._timeout_s)
+        if self._url.startswith("http://"):
+            logger.warning("policy API key is being sent over plaintext HTTP to host=%s", self._host)
+        started = time.perf_counter()
+
+        def check_model(payload, _request_id):
+            models = {item["id"] for item in payload.get("data", [])
+                      if isinstance(item, dict) and isinstance(item.get("id"), str)}
+            if self._model not in models:
+                raise self._diagnostic("model discovery", "model unavailable", started)
+
+        try:
+            self._request("model discovery", "models", http=http, decode=check_model)
+        except Exception:
+            http.close()
+            raise
+        self._http = http
+
+    def close(self) -> None:
+        if self._http is not None:
+            try:
+                self._http.close()
+            finally:
+                self._http = None
+
+    def prepare_session(self) -> None:
+        """Prepare locally before the runtime starts its background thread."""
+        with self._session_lock:
+            if self._state in {"open", "failed", "closing"} or self._inflight:
+                raise PolicyUnavailable("policy session is already active")
+            self._session_id, self._next_turn = None, 1
+            self._pending_messages.clear()
+            self._awaiting_execution = None
+            self._state = "starting"
+
+    def begin_session(self) -> None:
+        with self._session_lock:
+            if self._state in {"open", "failed", "closing"} or self._inflight:
+                raise PolicyUnavailable("policy session is already active")
+            if self._state == "unknown":
+                raise PolicyUnavailable("policy session outcome is unknown; prepare a new run")
+            if self._state == "closed":
+                self.prepare_session()
+            self._inflight = True
+        try:
+            if not self.ready:
+                self.connect()
+            (session_id, next_turn), _ = self._request(
+                "session create", "sessions", body={"model": self._model},
+                decode=lambda payload, _: decode_session(payload),
+            )
+            with self._session_lock:
+                self._session_id, self._next_turn = session_id, next_turn
+                self._state = "open"
+        except PolicyUnavailable:
+            with self._session_lock:
+                self._state = "unknown"
+            raise
+        finally:
+            with self._session_lock:
+                self._inflight = False
+
+    def record_lifecycle(self, event: str) -> None:
+        if event not in {"pause", "resume"}:
+            raise ValueError("session event must be pause or resume")
+        with self._session_lock:
+            if self._state in {"starting", "open"}:
+                self._pending_messages.append({"role": "user", "content": json.dumps({"event": event})})
+
+    def record_execution(self, chunk: ActionChunk, executed_steps: int, *, completed: bool) -> None:
+        if chunk.session_id is None:
+            return
+        with self._session_lock:
+            pending = self._awaiting_execution
+            if chunk.session_id != self._session_id or pending is None or chunk.session_turn != pending[0]:
+                raise PolicyUnavailable("policy execution feedback does not match the active turn")
+            if type(executed_steps) is not int or not 0 <= executed_steps <= len(chunk):
+                raise ValueError("executed_steps exceeds the returned action chunk")
+            self._pending_messages.extend([
+                pending[1],
+                {"role": "tool", "tool_call_id": f"call_{chunk.request_id}", "content": json.dumps({
+                    "executed_steps": executed_steps,
+                    "status": "completed" if completed and executed_steps == len(chunk) else "interrupted",
+                })},
+            ])
+            self._awaiting_execution = None
+
+    def _check_turn_available(self) -> tuple[str, int]:
+        """Called under the session lock before encoding and before sending."""
+        if self._state != "open" or self._inflight:
+            raise PolicyUnavailable("policy session is unavailable; end this episode before starting another")
+        if self._awaiting_execution is not None:
+            raise PolicyUnavailable("policy previous turn has no execution feedback")
+        return self._session_id, self._next_turn
+
+    def infer(self, pose7: np.ndarray, gripper: float, image: np.ndarray, instruction: str) -> ActionChunk:
+        with self._session_lock:
+            session_id, turn = self._check_turn_available()
+        observation = encode_observation(pose7, gripper, image, instruction, self._image_height)
+        with self._session_lock:
+            if self._check_turn_available() != (session_id, turn):
+                raise PolicyUnavailable("policy session changed before the request was sent")
+            feedback = list(self._pending_messages)
+            if len(feedback) > 64:
+                raise PolicyUnavailable("policy session pending messages exceeds the protocol limit")
+            request = {"model": self._model, "messages": feedback + [observation],
+                       "metadata": {"session_id": session_id, "turn": str(turn)}}
+            self._inflight = True
+        accepted = False
+        try:
+            if not self.ready:
+                self.connect()
+            started = time.perf_counter()
+            (message, chunk), request_ms = self._request(
+                "inference", "chat/completions", body=request,
+                decode=lambda payload, request_id: decode_completion(
+                    payload, request_id, session_id=session_id, turn=turn, instruction=instruction,
+                ),
+            )
+            chunk = replace(chunk, infer_ms=(time.perf_counter() - started) * 1e3, request_ms=request_ms)
+            with self._session_lock:
+                # Events received during the POST belong to the next turn.
+                del self._pending_messages[:len(feedback)]
+                self._next_turn = turn + 1
+                self._awaiting_execution = (turn, message)
+            accepted = True
+            return chunk
+        except PolicyUnavailable:
+            self.close()
+            raise
+        finally:
+            with self._session_lock:
+                self._inflight = False
+                if not accepted:
+                    self._state = "failed"
+
+    def end_session(self, reason: str = "stopped") -> None:
+        """Best effort close after local hold, without discovery or retries."""
+        with self._session_lock:
+            if self._inflight:
+                raise PolicyUnavailable("policy session request is still in flight")
+            if self._state not in {"open", "failed"}:
+                if self._state == "starting":
+                    self._state = "closed"
+                self._pending_messages.clear()
+                self._awaiting_execution = None
+                return
+            session_id = self._session_id
+            body = {"reason": (reason.strip() or "stopped")[:80], "messages": list(self._pending_messages)}
+            self._state = "closing"
+        outcome = "closed"
+        try:
+            with closing(self._new_http(1.0)) as http:
+                self._request(
+                    "session close", f"sessions/{session_id}/close", body=body, http=http,
+                    decode=lambda payload, _: decode_session(payload, expected_id=session_id),
+                )
+        except (PolicyUnavailable, httpx.TransportError, ValueError, TypeError, AttributeError) as exc:
+            detail = str(exc) if isinstance(exc, PolicyUnavailable) else f"host={self._host}"
+            logger.warning("policy session close was not confirmed: %s", detail)
+            outcome = "unknown"
+        finally:
+            with self._session_lock:
+                self._state = outcome
+                self._pending_messages.clear()
+                self._awaiting_execution = None

roboapi/policy/protocol.py

@@ -0,0 +1,166 @@
+"""Observation encoding and strict action decoding for the model API contract."""
+
+from __future__ import annotations
+
+import base64
+import io
+import json
+import re
+from dataclasses import dataclass, replace
+
+import numpy as np
+
+from .. import geometry as geo
+from ..semantics import ACTION_DT
+
+
+def resize_to_height(image: np.ndarray, height: int) -> np.ndarray:
+    """Resize to an exact height while preserving aspect ratio; never crop or pad."""
+    from PIL import Image
+
+    if image.ndim != 3 or image.shape[2] != 3:
+        raise ValueError(f"expected HxWx3 RGB, got {image.shape}")
+    if height < 1:
+        raise ValueError(f"resize height must be >= 1, got {height}")
+    cur_h, cur_w = image.shape[0], image.shape[1]
+    width = max(1, round(cur_w * height / cur_h))
+    resized = Image.fromarray(image.astype(np.uint8)).resize((width, height), resample=Image.BILINEAR)
+    return np.asarray(resized, dtype=np.uint8)
+
+
+@dataclass(frozen=True)
+class ActionChunk:
+    """One inference result: T coordinated arm + gripper frames."""
+
+    arm: np.ndarray  # (T, 7) pose7d wxyz
+    gripper: np.ndarray  # (T,) normalized [0, 1]
+    infer_ms: float
+    instruction: str
+    request_id: str | None = None
+    # Time spent in the HTTP POST, excluding image encoding and response decoding.
+    request_ms: float | None = None
+    # Model actions belong to a session turn; locally planned motions do not.
+    session_id: str | None = None
+    session_turn: int | None = None
+
+    @property
+    def action_dt(self):
+        return ACTION_DT
+
+    def __post_init__(self) -> None:
+        if self.arm.ndim != 2 or self.arm.shape[1] != 7:
+            raise ValueError(f"chunk arm must be (T,7), got {self.arm.shape}")
+        if self.gripper.shape != (self.arm.shape[0],):
+            raise ValueError(f"chunk gripper must be (T,), got {self.gripper.shape}")
+
+    def __len__(self) -> int:
+        return int(self.arm.shape[0])
+
+    def summary(self, current_pose: np.ndarray, current_gripper: float) -> dict:
+        """Summarize endpoint displacement and gripper movement."""
+        last = self.arm[-1]
+        d_xyz = (last[0:3] - np.asarray(current_pose, dtype=np.float64)[0:3]).round(4).tolist()
+        _, d_rot = geo.pose_delta(current_pose, last)
+        g_end = float(self.gripper[-1])
+        if abs(g_end - current_gripper) < 0.05:
+            g_desc = f"{current_gripper:.2f} (holding)"
+        else:
+            g_desc = f"{current_gripper:.2f} -> {g_end:.2f} ({'opening' if g_end > current_gripper else 'closing'})"
+        return {
+            "n_steps": len(self),
+            "duration_s": round(len(self) * self.action_dt, 3),
+            "delta_xyz_m": d_xyz,
+            "delta_rot_rad": round(d_rot, 4),
+            "gripper": g_desc,
+            "infer_ms": round(self.infer_ms, 1),
+        }
+
+
+OPENAI_GRIPPER_TOLERANCE = 0.01
+
+
+def decode_actions(response: dict, infer_ms: float, instruction: str,
+                   request_id: str | None = None, request_ms: float | None = None) -> ActionChunk:
+    """Decode absolute ``[xyz, quat_xyzw, gripper]`` action rows from the OpenAI adapter."""
+    if not isinstance(response, dict) or "output" not in response:
+        raise RuntimeError("policy response needs an 'output' array")
+    try:
+        actions = np.asarray(response["output"], dtype=np.float64)
+    except (TypeError, ValueError) as exc:
+        raise RuntimeError("policy 'output' must be a rectangular numeric array") from exc
+    if actions.ndim != 2 or actions.shape[0] < 1 or actions.shape[1] != 8:
+        raise RuntimeError(f"policy 'output' must be (T,8), got {actions.shape}")
+    if not np.all(np.isfinite(actions)):
+        raise RuntimeError("policy 'output' contains non-finite values")
+    try:
+        quat_wxyz = geo.quat_xyzw_to_wxyz(geo.normalize_quat(actions[:, 3:7]))
+    except ValueError as exc:
+        raise RuntimeError("policy 'output' contains a zero-norm quaternion") from exc
+    gripper = actions[:, 7]
+    tol = OPENAI_GRIPPER_TOLERANCE
+    if np.any((gripper < -tol) | (gripper > 1.0 + tol)):
+        raise RuntimeError("policy 'output' gripper exceeds the [0,1] range by more than 0.01")
+    return ActionChunk(
+        arm=np.concatenate([actions[:, 0:3], quat_wxyz], axis=1),
+        gripper=np.clip(gripper, 0.0, 1.0),
+        infer_ms=infer_ms,
+        instruction=instruction,
+        request_id=request_id,
+        request_ms=request_ms,
+    )
+
+
+def encode_observation(pose7: np.ndarray, gripper: float, image: np.ndarray,
+                       instruction: str, image_height: int | None) -> dict:
+    from PIL import Image
+
+    if image_height is not None:
+        image = resize_to_height(image, image_height)
+    image = np.asarray(image, dtype=np.uint8)
+    if image.ndim != 3 or image.shape[2] != 3:
+        raise ValueError(f"expected HxWx3 RGB, got {image.shape}")
+    encoded = io.BytesIO()
+    Image.fromarray(image).save(encoded, format="PNG")
+    state = np.concatenate([geo.obs_pose(pose7), [float(gripper)]]).astype(np.float32)
+    return {
+        "role": "user",
+        "content": [
+            {"type": "text", "text": json.dumps({"instruction": instruction, "state": state.tolist()})},
+            {"type": "image_url", "image_url": {
+                "url": "data:image/png;base64," + base64.b64encode(encoded.getvalue()).decode("ascii")
+            }},
+        ],
+    }
+
+
+def decode_session(payload: dict, expected_id: str | None = None) -> tuple[str, int]:
+    """Validate lifecycle responses without retaining the server's history."""
+    session_id = payload.get("id")
+    next_turn = payload.get("next_turn", 1)
+    if (not isinstance(session_id, str) or not re.fullmatch(r"[A-Za-z0-9_-]{1,128}", session_id)
+            or (expected_id is not None and session_id != expected_id)
+            or type(next_turn) is not int or next_turn < 1
+            or not isinstance(payload.get("messages"), list)):
+        raise ValueError("invalid session response")
+    return session_id, next_turn
+
+
+def decode_completion(payload: dict, request_id: str | None, *, session_id: str,
+                      turn: int, instruction: str) -> tuple[dict, ActionChunk]:
+    choice = payload["choices"][0]
+    message = choice["message"]
+    calls = message["tool_calls"]
+    if (message.get("role") != "assistant" or message.get("content") is not None
+            or choice.get("finish_reason") != "tool_calls" or not isinstance(calls, list)
+            or len(calls) != 1 or calls[0].get("type") != "function"
+            or calls[0].get("id") != f"call_{request_id}"
+            or calls[0]["function"].get("name") != "execute_actions"):
+        raise ValueError("completion must contain one execute_actions tool call")
+    metadata = payload.get("metadata", {})
+    if (metadata.get("session_id") != session_id or metadata.get("turn") != str(turn)
+            or metadata.get("next_turn") != str(turn + 1)
+            or not request_id or not re.fullmatch(r"[a-f0-9]{32}", request_id)):
+        raise ValueError("completion does not match the requested turn")
+    actions = json.loads(calls[0]["function"]["arguments"])
+    chunk = decode_actions(actions, 0.0, instruction, request_id)
+    return message, replace(chunk, session_id=session_id, session_turn=turn)

roboapi/policy/settings.py

@@ -0,0 +1,79 @@
+"""Local model endpoint settings and credentials."""
+
+from __future__ import annotations
+
+import os
+import tempfile
+from pathlib import Path
+from urllib.parse import urlsplit
+
+from ..errors import PolicyUnavailable
+
+
+def validate_policy_endpoint(url: str, model: str) -> tuple[str, str]:
+    if not isinstance(url, str) or not url or url != url.strip():
+        raise ValueError("base URL is required")
+    try:
+        parsed = urlsplit(url)
+        valid_port = parsed.port is None or 1 <= parsed.port <= 65535
+    except ValueError:
+        raise ValueError("base URL is invalid") from None
+    if (parsed.scheme not in ("http", "https") or not parsed.hostname or
+            parsed.username is not None or parsed.password is not None or
+            parsed.query or parsed.fragment or
+            not valid_port or any(c.isspace() for c in url)):
+        raise ValueError("base URL must be an http(s) endpoint without credentials or query")
+    if (not isinstance(model, str) or not model or model != model.strip() or
+            len(model) > 128 or any(c.isspace() or not c.isprintable() for c in model)):
+        raise ValueError("model must be a nonempty ID of at most 128 characters")
+    return url.rstrip("/"), model
+
+
+def _write_private_file(path_text: str, content: str) -> Path:
+    path = Path(path_text).expanduser()
+    path.parent.mkdir(mode=0o700, parents=True, exist_ok=True)
+    fd, temporary = tempfile.mkstemp(prefix=f".{path.name}.", dir=path.parent)
+    try:
+        os.fchmod(fd, 0o600)
+        with os.fdopen(fd, "w", encoding="utf-8") as stream:
+            fd = -1
+            stream.write(content)
+            stream.flush()
+            os.fsync(stream.fileno())
+        os.replace(temporary, path)
+    except Exception:
+        if fd >= 0:
+            os.close(fd)
+        Path(temporary).unlink(missing_ok=True)
+        raise
+    return path
+
+
+def read_token(token_file: str) -> str:
+    path = Path(token_file).expanduser()
+    try:
+        token = path.read_text(encoding="utf-8").strip()
+    except (OSError, UnicodeError):
+        token = ""
+    if not token:
+        raise PolicyUnavailable(
+            f"policy API key is not configured at {path}; use robot_configure_policy()"
+        )
+    return token
+
+
+def policy_token_configured(token_file: str) -> bool:
+    try:
+        read_token(token_file)
+    except PolicyUnavailable:
+        return False
+    return True
+
+
+def write_policy_token(token_file: str, token: str) -> Path:
+    if "\n" in token or "\r" in token:
+        raise ValueError("policy API key must be a single line")
+    token = token.strip()
+    if not token:
+        raise ValueError("policy API key must not be empty")
+    return _write_private_file(token_file, token + "\n")

roboapi/product-names.json

@@ -0,0 +1,12 @@
+{
+  "brand": { "zh": "破壳机器人", "en": "PokeBot" },
+  "product": { "name": "RoboAPI", "namespace": "roboapi" },
+  "labels": {
+    "docs": { "zh": "{product} 文档", "en": "{product} Docs" },
+    "docsTitle": { "zh": "{product} 开发者文档", "en": "{product} Documentation" },
+    "console": { "zh": "{product} 控制台", "en": "{product} Console" },
+    "cloudApi": { "zh": "云端模型 API", "en": "Cloud Model API" },
+    "cloudConsole": { "zh": "云端控制台", "en": "Cloud Console" },
+    "assistant": { "zh": "文档助手", "en": "Docs Assistant" }
+  }
+}