reflex-sdk 0.3.0__tar.gz → 0.3.2__tar.gz

{reflex_sdk-0.3.0 → reflex_sdk-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: reflex-sdk
-Version: 0.3.0
+Version: 0.3.2
 Summary: Python SDK for Reflex hosted robot inference and training
 Author: Reflex
 Project-URL: Homepage, https://tryreflex.ai
@@ -15,8 +15,15 @@ Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Requires-Python: >=3.9
 Description-Content-Type: text/markdown
+Requires-Dist: PyYAML<7,>=6.0
 Requires-Dist: typer<0.24,>=0.23; python_version < "3.10"
 Requires-Dist: typer>=0.24.1; python_version >= "3.10"
+Provides-Extra: webrtc
+Requires-Dist: aiortc>=1.8; extra == "webrtc"
+Requires-Dist: av>=11; extra == "webrtc"
+Requires-Dist: msgpack>=1.0; extra == "webrtc"
+Requires-Dist: numpy>=1.24; extra == "webrtc"
+Requires-Dist: Pillow>=10; extra == "webrtc"
 
 # Reflex Python SDK
 

{reflex_sdk-0.3.0 → reflex_sdk-0.3.2}/pyproject.toml

@@ -1,10 +1,11 @@
 [project]
 name = "reflex-sdk"
-version = "0.3.0"
+version = "0.3.2"
 description = "Python SDK for Reflex hosted robot inference and training"
 readme = "README.md"
 requires-python = ">=3.9"
 dependencies = [
+    "PyYAML>=6.0,<7",
     "typer>=0.23,<0.24; python_version < '3.10'",
     "typer>=0.24.1; python_version >= '3.10'",
 ]
@@ -22,6 +23,19 @@ classifiers = [
     "Programming Language :: Python :: 3.12",
 ]
 
+[project.optional-dependencies]
+# Pulled in by `pip install reflex-sdk[webrtc]`. Required when using
+# `target.kind: webrtc` in a `reflex connect` config — the WebRTCTransport
+# imports numpy/Pillow at module top, and the vendored client uses aiortc
+# (peer connection + H.264 video tracks) and msgpack (DataChannel wire).
+webrtc = [
+    "aiortc>=1.8",
+    "av>=11",
+    "msgpack>=1.0",
+    "numpy>=1.24",
+    "Pillow>=10",
+]
+
 [project.urls]
 Homepage = "https://tryreflex.ai"
 Repository = "https://github.com/reflex-inc/reflex"
@@ -30,11 +44,11 @@ Repository = "https://github.com/reflex-inc/reflex"
 reflex = "reflex.cli:main_reflex"
 
 [tool.setuptools]
-packages = ["reflex"]
+packages = ["reflex", "reflex.cameras", "reflex.connectors", "reflex.transports"]
 
 [tool.ruff]
 line-length = 100
 
 [build-system]
 requires = ["setuptools>=68"]
-build-backend = "setuptools.build_meta"
+build-backend = "setuptools.build_meta"

{reflex_sdk-0.3.0 → reflex_sdk-0.3.2}/reflex/__init__.py

@@ -3,6 +3,7 @@
 from ._version import __version__
 from .actions import ActionStream, action, connect, infer_actions, observation
 from .client import Client
+# TODO PROD.2: re-add ConnectError/ConnectRunner/SessionGrant once auth wrapper is integrated
 from .datasets import (
     complete_dataset,
     create_dataset,
@@ -12,9 +13,26 @@ from .datasets import (
     upload_dataset,
     validate_dataset,
 )
+from .deployments import (
+    create_deployment,
+    create_deployment_from_spec,
+    get_deployment,
+    list_deployments,
+    run_deployment_doctor,
+)
 from .instances import instance_status, provision_instance, teardown_instance
-from .keys import bind_key_to_model
-from .models import delete_model, get_model, import_from_hf, list_models
+from .receipts import list_receipts
+from .robots import (
+    claim_pairing_token,
+    create_pairing_token,
+    heartbeat_robot,
+    list_robot_schemas,
+    list_robots,
+    register_robot,
+    register_robot_schema,
+)
+from .robot_runtime import RobotExecutionConfig, RobotExecutionResult, run_robot_execution_loop
+from .sessions import close_session, list_sessions, promote_session, start_session
 from .training import (
     AdamParams,
     AdapterHandle,
@@ -37,35 +55,53 @@ __all__ = [
     "AdamParams",
     "AdapterHandle",
     "Client",
+    "claim_pairing_token",
     "Datum",
     "ForwardBackwardResult",
     "LoraTrainingClient",
     "OptimStepResult",
+    "RobotExecutionConfig",
+    "RobotExecutionResult",
     "ServiceClient",
+    "SessionGrant",
     "__version__",
     "action",
     "bind_key_to_model",
     "cancel_training_job",
+    "close_session",
     "complete_dataset",
     "connect",
     "create_dataset",
+    "create_deployment",
+    "create_deployment_from_spec",
+    "create_pairing_token",
     "create_training_job",
     "delete_model",
     "full_finetune",
     "full_train",
     "get_dataset",
-    "get_model",
+    "get_deployment",
     "get_training_job",
-    "import_from_hf",
+    "heartbeat_robot",
     "infer_actions",
     "instance_status",
-    "list_models",
+    "list_sessions",
     "list_training_jobs",
     "list_datasets",
+    "list_deployments",
+    "list_receipts",
+    "list_robot_schemas",
+    "list_robots",
     "lora_finetune",
     "observation",
     "provision_instance",
+    "promote_session",
     "register_huggingface_dataset",
+    "register_robot",
+    "register_robot_schema",
+    "run_deployment_doctor",
+    "run_robot_execution_loop",
+    "start_session",
     "teardown_instance",
     "upload_dataset",
     "validate_dataset",

reflex_sdk-0.3.2/reflex/_region_probe.py

@@ -0,0 +1,210 @@
+"""Client-side nearest-region probe for the Reflex SDK CLI (CFG.1).
+
+When `REFLEX_INFERENCE_REGION_MAP=region=URL,region=URL,...` is set, the
+CLI hits each URL's `/health` at startup, picks the lowest-p50 region,
+and uses that URL for the inference stream instead of the one the
+platform returned. This buys ~20-60ms RTT on multi-region deploys
+without server-side changes (NetR.3a finding, re-nr7l).
+
+Single-entry maps skip the probe entirely (zero startup cost), so the
+default single-region behaviour is unchanged until a multi-region map
+is configured.
+
+Stdlib-only (urllib + statistics) so it runs in any environment the
+rest of the published `reflex` package runs in.
+"""
+
+from __future__ import annotations
+
+import os
+import time
+import urllib.error
+import urllib.request
+from dataclasses import dataclass
+from typing import Callable, Optional
+
+DEFAULT_REGION_ENV = "REFLEX_INFERENCE_REGION_MAP"
+DEFAULT_PROBE_ATTEMPTS = 5
+DEFAULT_PROBE_WARMUP = 1
+DEFAULT_PROBE_TIMEOUT_S = 5.0
+DEFAULT_PROBE_SETTLE_S = 0.05
+
+
+@dataclass(frozen=True)
+class RegionResult:
+    label: str
+    url: str
+    ok_count: int
+    attempts: int
+    p50_ms: Optional[float]
+    error_tail: Optional[str] = None
+
+
+def parse_region_map(spec: str) -> list[tuple[str, str]]:
+    """Parse `region1=url1,region2=url2[,...]` into `[(label, url), ...]`.
+
+    Empty input → []. Malformed entries raise `ValueError` so a typo in
+    the env var fails loudly instead of silently routing to the wrong
+    region.
+    """
+    if not spec or not spec.strip():
+        return []
+    items: list[tuple[str, str]] = []
+    for raw in spec.split(","):
+        raw = raw.strip()
+        if not raw:
+            continue
+        if "=" not in raw:
+            raise ValueError(f"region map entry missing '=': {raw!r}")
+        label, url = raw.split("=", 1)
+        label, url = label.strip(), url.strip()
+        if not label or not url:
+            raise ValueError(f"empty label or url in region map entry: {raw!r}")
+        items.append((label, url))
+    return items
+
+
+def _pct(samples: list[float], q: float) -> Optional[float]:
+    if not samples:
+        return None
+    s = sorted(samples)
+    idx = max(0, min(len(s) - 1, int(round(q * (len(s) - 1)))))
+    return round(s[idx], 2)
+
+
+def _probe_once(url: str, timeout_s: float) -> tuple[Optional[float], Optional[str]]:
+    started = time.perf_counter()
+    try:
+        req = urllib.request.Request(
+            url, headers={"User-Agent": "reflex-sdk-region-probe/1.0"}
+        )
+        with urllib.request.urlopen(req, timeout=timeout_s) as response:
+            response.read()  # drain so the conn closes cleanly
+            if not (200 <= response.status < 300):
+                return None, f"HTTP {response.status}"
+    except urllib.error.HTTPError as exc:
+        return None, f"HTTPError {exc.code}: {exc.reason}"
+    except Exception as exc:  # noqa: BLE001 — any failure → unviable target
+        return None, f"{type(exc).__name__}: {exc}"
+    return (time.perf_counter() - started) * 1000.0, None
+
+
+def probe_region(
+    label: str,
+    url: str,
+    *,
+    attempts: int = DEFAULT_PROBE_ATTEMPTS,
+    warmup: int = DEFAULT_PROBE_WARMUP,
+    timeout_s: float = DEFAULT_PROBE_TIMEOUT_S,
+    settle_s: float = DEFAULT_PROBE_SETTLE_S,
+) -> RegionResult:
+    """Hit `<url>/health` `warmup + attempts` times; return per-region stats.
+
+    Warmup probes amortise TCP/TLS handshake + Modal proxy cold-route so
+    the p50 reflects steady-state RTT.
+    """
+    health = url.rstrip("/") + "/health"
+    for _ in range(warmup):
+        _probe_once(health, timeout_s)
+        if settle_s > 0:
+            time.sleep(settle_s)
+    samples: list[float] = []
+    last_err: Optional[str] = None
+    for _ in range(attempts):
+        rtt, err = _probe_once(health, timeout_s)
+        if rtt is not None:
+            samples.append(rtt)
+        elif err is not None:
+            last_err = err
+        if settle_s > 0:
+            time.sleep(settle_s)
+    return RegionResult(
+        label=label,
+        url=url,
+        attempts=attempts,
+        ok_count=len(samples),
+        p50_ms=_pct(samples, 0.5),
+        error_tail=last_err if not samples else None,
+    )
+
+
+def pick_nearest(
+    region_map: list[tuple[str, str]],
+    *,
+    attempts: int = DEFAULT_PROBE_ATTEMPTS,
+    warmup: int = DEFAULT_PROBE_WARMUP,
+    timeout_s: float = DEFAULT_PROBE_TIMEOUT_S,
+    settle_s: float = DEFAULT_PROBE_SETTLE_S,
+    log: Optional[Callable[[RegionResult], None]] = None,
+) -> tuple[str, str, list[RegionResult]]:
+    """Return `(label, url, all_results)` for the lowest-p50 region.
+
+    Single-region maps skip the probe entirely. All-fail falls back to
+    the first entry so the caller always gets a usable URL — better to
+    attempt against a known-stale endpoint than refuse to start.
+    """
+    if not region_map:
+        raise ValueError("region_map is empty")
+    if len(region_map) == 1:
+        label, url = region_map[0]
+        result = RegionResult(
+            label=label, url=url, attempts=0, ok_count=0, p50_ms=None,
+        )
+        if log is not None:
+            log(result)
+        return label, url, [result]
+    results: list[RegionResult] = []
+    for label, url in region_map:
+        r = probe_region(
+            label, url,
+            attempts=attempts, warmup=warmup,
+            timeout_s=timeout_s, settle_s=settle_s,
+        )
+        if log is not None:
+            log(r)
+        results.append(r)
+    viable = [r for r in results if r.p50_ms is not None]
+    if not viable:
+        first = results[0]
+        return first.label, first.url, results
+    best = min(viable, key=lambda r: r.p50_ms)  # type: ignore[arg-type,return-value]
+    return best.label, best.url, results
+
+
+def resolve_url(
+    explicit_url: Optional[str],
+    *,
+    region_map: Optional[list[tuple[str, str]]] = None,
+    env_var: str = DEFAULT_REGION_ENV,
+    fallback_url: Optional[str] = None,
+    attempts: int = DEFAULT_PROBE_ATTEMPTS,
+    warmup: int = DEFAULT_PROBE_WARMUP,
+    timeout_s: float = DEFAULT_PROBE_TIMEOUT_S,
+    settle_s: float = DEFAULT_PROBE_SETTLE_S,
+    log: Optional[Callable[[RegionResult], None]] = None,
+) -> str:
+    """Resolve the URL to use, honouring explicit > region-map > fallback.
+
+    - `explicit_url` truthy → return as-is (server-returned URL wins
+      unless overridden by env).
+    - Else parse `region_map` (or `os.environ[env_var]` if not given).
+    - Empty map → return `fallback_url` (preserves current behaviour).
+    - Non-empty map → `pick_nearest` and return its URL.
+    """
+    if explicit_url:
+        return explicit_url
+    if region_map is None:
+        region_map = parse_region_map(os.environ.get(env_var, ""))
+    if not region_map:
+        if fallback_url is None:
+            raise RuntimeError(
+                f"resolve_url: env var {env_var} is empty and no fallback_url given"
+            )
+        return fallback_url
+    _, url, _ = pick_nearest(
+        region_map,
+        attempts=attempts, warmup=warmup,
+        timeout_s=timeout_s, settle_s=settle_s,
+        log=log,
+    )
+    return url

{reflex_sdk-0.3.0 → reflex_sdk-0.3.2}/reflex/actions.py

@@ -9,6 +9,7 @@ import os
 import socket
 import ssl
 import struct
+import time
 from types import TracebackType
 from typing import Any
 from urllib import parse
@@ -17,6 +18,16 @@ from ._version import user_agent as _user_agent
 from ._transport import api_key as _api_key
 from ._transport import base_url as _base_url
 
+RETRYABLE_HANDSHAKE_STATUS_CODES = {403, 404, 408, 425, 429, 500, 502, 503, 504}
+DEFAULT_CONNECT_RETRY_SECONDS = 90.0
+
+
+class WebSocketHandshakeError(RuntimeError):
+    def __init__(self, status_line: str) -> None:
+        super().__init__(f"WebSocket handshake failed: {status_line}")
+        self.status_line = status_line
+        self.status_code = _status_code(status_line)
+
 
 def _actions_ws_url(url: str | None) -> str:
     resolved = (url or os.environ.get("REFLEX_ACTIONS_URL", "")).strip()
@@ -25,6 +36,8 @@ def _actions_ws_url(url: str | None) -> str:
 
     parsed = parse.urlparse(resolved)
     if parsed.scheme in {"ws", "wss"}:
+        if parsed.query:
+            return resolved
         if parsed.path and parsed.path != "/":
             return resolved
         return f"{resolved.rstrip('/')}/v1/actions"
@@ -35,7 +48,42 @@ def _actions_ws_url(url: str | None) -> str:
     raise ValueError("Actions URL must start with http://, https://, ws://, or wss://.")
 
 
-def _connect_websocket(url: str, *, api_key: str, timeout: float) -> socket.socket:
+def _status_code(status_line: str) -> int | None:
+    pieces = status_line.split()
+    if len(pieces) < 2:
+        return None
+    try:
+        return int(pieces[1])
+    except ValueError:
+        return None
+
+
+def _connect_retry_seconds(timeout: float) -> float:
+    raw = os.environ.get("REFLEX_WS_CONNECT_RETRY_SECONDS", "").strip()
+    if raw:
+        try:
+            configured = float(raw)
+        except ValueError:
+            configured = DEFAULT_CONNECT_RETRY_SECONDS
+    else:
+        configured = DEFAULT_CONNECT_RETRY_SECONDS
+    return max(0.0, min(max(0.0, timeout), configured))
+
+
+def _retryable_connect_error(exc: BaseException) -> bool:
+    if isinstance(exc, WebSocketHandshakeError):
+        return exc.status_code in RETRYABLE_HANDSHAKE_STATUS_CODES
+    return isinstance(exc, (TimeoutError, socket.timeout, OSError))
+
+
+def _connect_websocket(
+    url: str,
+    *,
+    api_key: str,
+    timeout: float,
+    timing: dict[str, float] | None = None,
+) -> socket.socket:
+    connect_started = time.monotonic()
     parsed = parse.urlparse(url)
     if parsed.scheme not in {"ws", "wss"} or not parsed.hostname:
         raise ValueError("Actions URL must be a ws:// or wss:// URL.")
@@ -45,17 +93,27 @@ def _connect_websocket(url: str, *, api_key: str, timeout: float) -> socket.sock
     if parsed.query:
         path = f"{path}?{parsed.query}"
 
+    tcp_started = time.monotonic()
     raw_sock = socket.create_connection((parsed.hostname, port), timeout=timeout)
+    if timing is not None:
+        timing["tcp_ms"] = (time.monotonic() - tcp_started) * 1000.0
     sock: socket.socket
     if parsed.scheme == "wss":
+        tls_started = time.monotonic()
         context = ssl.create_default_context()
         sock = context.wrap_socket(raw_sock, server_hostname=parsed.hostname)
+        if timing is not None:
+            timing["tls_ms"] = (time.monotonic() - tls_started) * 1000.0
     else:
         sock = raw_sock
+        if timing is not None:
+            timing["tls_ms"] = 0.0
     sock.settimeout(timeout)
 
+    upgrade_started = time.monotonic()
     key = base64.b64encode(os.urandom(16)).decode("ascii")
     host = parsed.hostname if parsed.port is None else f"{parsed.hostname}:{port}"
+    auth_header = f"Authorization: Bearer {api_key}\r\n" if api_key else ""
     request_text = (
         f"GET {path} HTTP/1.1\r\n"
         f"Host: {host}\r\n"
@@ -63,7 +121,7 @@ def _connect_websocket(url: str, *, api_key: str, timeout: float) -> socket.sock
         "Connection: Upgrade\r\n"
         f"Sec-WebSocket-Key: {key}\r\n"
         "Sec-WebSocket-Version: 13\r\n"
-        f"Authorization: Bearer {api_key}\r\n"
+        f"{auth_header}"
         f"User-Agent: {_user_agent('reflex-actions-sdk')}\r\n"
         "\r\n"
     )
@@ -79,7 +137,7 @@ def _connect_websocket(url: str, *, api_key: str, timeout: float) -> socket.sock
     status_line = header_text.split("\r\n", 1)[0]
     if " 101 " not in status_line:
         sock.close()
-        raise RuntimeError(f"WebSocket handshake failed: {status_line}")
+        raise WebSocketHandshakeError(status_line)
 
     accept_source = (key + "258EAFA5-E914-47DA-95CA-C5AB0DC85B11").encode("ascii")
     expected_accept = base64.b64encode(hashlib.sha1(accept_source).digest()).decode("ascii")
@@ -91,6 +149,9 @@ def _connect_websocket(url: str, *, api_key: str, timeout: float) -> socket.sock
     if headers.get("sec-websocket-accept") != expected_accept:
         sock.close()
         raise RuntimeError("WebSocket handshake failed: invalid Sec-WebSocket-Accept header.")
+    if timing is not None:
+        timing["websocket_upgrade_ms"] = (time.monotonic() - upgrade_started) * 1000.0
+        timing["connect_ms"] = (time.monotonic() - connect_started) * 1000.0
     return sock
 
 
@@ -176,6 +237,11 @@ def _normalize_images(images: dict[str, Any] | None) -> dict[str, Any]:
     return normalized
 
 
+def _query_has_token(url: str) -> bool:
+    parsed = parse.urlparse(url)
+    return bool(parse.parse_qs(parsed.query).get("token"))
+
+
 class ActionStream:
     """Long-lived Reflex actions session.
 
@@ -193,25 +259,36 @@ class ActionStream:
         prompt: str,
         model: str | None = None,
         lora: str | None = None,
+        robot: str | None = None,
+        action_adapter: str | None = None,
         cameras: list[str] | None = None,
         hz: float | None = None,
         chunk_size: int | None = None,
         max_gpu_seconds: float | None = None,
         session_id: str = "",
         timeout: float = 30.0,
+        connect_retry_seconds: float | None = None,
     ) -> None:
         self.url = _actions_ws_url(url)
-        self.api_key = _api_key(api_key)
+        self.api_key = (
+            ""
+            if _query_has_token(self.url) and not (api_key or "").strip()
+            else _api_key(api_key)
+        )
         self.prompt = prompt
         self.model = model
         self.lora = lora
+        self.robot = robot
+        self.action_adapter = action_adapter
         self.cameras = cameras or []
         self.hz = hz
         self.chunk_size = chunk_size
         self.max_gpu_seconds = max_gpu_seconds
         self.session_id = session_id
         self.timeout = timeout
+        self.connect_retry_seconds = connect_retry_seconds
         self.ready: dict[str, Any] | None = None
+        self.open_timing: dict[str, float] = {}
         self._sock: socket.socket | None = None
         self._next_seq = 0
 
@@ -227,24 +304,61 @@ class ActionStream:
         self.close()
 
     def open(self) -> ActionStream:
-        self._sock = _connect_websocket(self.url, api_key=self.api_key, timeout=self.timeout)
-        self.send_raw({
-            "type": "session.open",
-            "session_id": self.session_id,
-            "prompt": self.prompt,
-            "model": self.model,
-            "lora": self.lora,
-            "cameras": self.cameras,
-            "hz": self.hz,
-            "chunk_size": self.chunk_size,
-            "max_gpu_seconds": self.max_gpu_seconds,
-        })
-        ready = self.receive()
-        if ready.get("type") != "session.ready":
-            raise RuntimeError(f"Expected session.ready, received {ready!r}")
-        self.ready = ready
-        self.session_id = str(ready.get("session_id") or self.session_id)
-        return self
+        retry_seconds = (
+            _connect_retry_seconds(self.timeout)
+            if self.connect_retry_seconds is None
+            else max(0.0, min(max(0.0, self.timeout), self.connect_retry_seconds))
+        )
+        deadline = time.monotonic() + retry_seconds
+        delay = 0.5
+        while True:
+            open_started = time.monotonic()
+            timing: dict[str, float] = {}
+            try:
+                self._sock = _connect_websocket(
+                    self.url,
+                    api_key=self.api_key,
+                    timeout=min(self.timeout, 15.0),
+                    timing=timing,
+                )
+                ready_started = time.monotonic()
+                self.send_raw({
+                    "type": "session.open",
+                    "session_id": self.session_id,
+                    "prompt": self.prompt,
+                    "model": self.model,
+                    "lora": self.lora,
+                    "robot": self.robot,
+                    "action_adapter": self.action_adapter,
+                    "cameras": self.cameras,
+                    "hz": self.hz,
+                    "chunk_size": self.chunk_size,
+                    "max_gpu_seconds": self.max_gpu_seconds,
+                })
+                ready = self.receive()
+                if ready.get("type") != "session.ready":
+                    raise RuntimeError(f"Expected session.ready, received {ready!r}")
+                timing["session_ready_ms"] = (time.monotonic() - ready_started) * 1000.0
+                timing["open_ms"] = (time.monotonic() - open_started) * 1000.0
+                self.open_timing = timing
+                self.ready = ready
+                self.session_id = str(ready.get("session_id") or self.session_id)
+                return self
+            except Exception as exc:
+                if self._sock is not None:
+                    try:
+                        _close_websocket(self._sock)
+                    except Exception:
+                        try:
+                            self._sock.close()
+                        except Exception:
+                            pass
+                    self._sock = None
+                now = time.monotonic()
+                if retry_seconds <= 0 or not _retryable_connect_error(exc) or now >= deadline:
+                    raise
+                time.sleep(min(delay, max(0.0, deadline - now)))
+                delay = min(delay * 1.6, 5.0)
 
     def send_raw(self, frame: dict[str, Any]) -> None:
         if self._sock is None:
@@ -428,4 +542,4 @@ def infer_actions(
     }
     with ActionStream(url=url, api_key=api_key, timeout=timeout, **session_fields) as stream:
         stream.send_observation_frame(observation)
-        return stream.recv_action()
+        return stream.recv_action()