unienv_interface.remote¶
Lightweight RPC for UniEnv environments, worlds, nodes and data transformations.
Host objects with :class:RemoteServer and use them through
:class:RemoteClient proxies that implement the normal Env / World /
WorldNode / DataTransformation interfaces. Transports: TCP, Unix sockets, WebSocket (optional
websockets dependency) and in-memory. See docs/guides/remote-execution.md.
Modules:
| Name | Description |
|---|---|
client |
Connect to a :class: |
compression |
Opt-in lossy compression of server-to-client image arrays. |
errors |
Errors raised by the remote client. |
protocol |
Protocol constants shared by client and server. |
proxies |
Local |
server |
Host environments, worlds, nodes and data transformations for remote clients. |
transport |
Frame transports: TCP and Unix stream sockets, WebSocket, and in-memory pairs. |
wire |
Safe wire format: one JSON document plus raw binary attachments. No pickle. |
Classes:
| Name | Description |
|---|---|
RemoteClient |
A connection to a :class: |
Subscription |
Iterator over the latest results of a hosted env (latest wins, never queued). |
SubscriptionEvent |
The result of a |
RemoteError |
An exception raised by the hosted object (or the server) while handling a call. |
RemoteDataTransformation |
A |
RemoteEnv |
An |
RemoteWorld |
A |
RemoteWorldNode |
A |
RemoteServer |
Serve registered objects to :class: |
MemoryTransport |
In-process pair (tests); frames are copied, as on a real connection. |
StreamTransport |
Frames over a connected stream socket; each frame goes out in one |
Transport |
A reliable, ordered connection carrying whole frames. |
WebSocketTransport |
One frame per binary WebSocket message (requires |
WireError |
A frame is malformed or violates the wire format's limits. |
Attributes:
| Name | Type | Description |
|---|---|---|
PROTOCOL_VERSION |
int
|
|
RemoteClient
¶
RemoteClient(
transport: Transport,
*,
backend: ComputeBackend = NumpyComputeBackend,
device: Optional[Any] = None,
timeout: Optional[float] = None,
compress: Optional[Dict[str, str]] = None,
)
A connection to a :class:RemoteServer. Thread-safe: calls may be concurrent.
Results are converted to backend arrays on device. A remote exception
is re-raised as :class:RemoteError; a lost connection raises
ConnectionError, in which case a call that was in flight may or may not
have run on the server. timeout (seconds, None = wait forever) bounds
each call; a timed-out call keeps running on the server.
Methods:
| Name | Description |
|---|---|
connect |
Connect to |
call |
Call an allowed |
resource |
The proxy of hosted resource |
env |
Proxy of a hosted |
world |
Proxy of a hosted |
node |
Proxy of a hosted |
transformation |
Proxy of a hosted |
subscribe |
Follow the |
close |
Close the connection (hosted objects stay open on the server). |
Attributes:
| Name | Type | Description |
|---|---|---|
closed |
|
|
resources |
Dict[str, Dict[str, Any]]
|
Descriptor of every hosted resource, by name. |
resources
instance-attribute
¶
Descriptor of every hosted resource, by name.
connect
classmethod
¶
connect(
address: str,
*,
timeout: Optional[float] = None,
connect_timeout: float = 10.0,
backend: ComputeBackend = NumpyComputeBackend,
device: Optional[Any] = None,
compress: Optional[Dict[str, str]] = None,
max_frame_size: int = DEFAULT_MAX_FRAME_SIZE,
) -> RemoteClient
Connect to tcp://host:port, unix:///path or ws://host:port.
compress opts into lossy compression of server-to-client data, e.g.
{"image": "jpeg:90"} JPEG-encodes uint8 image leaves (spaces whose
metadata["kind"] == "image") at quality 90.
call
¶
Call an allowed method of the hosted resource name.
resource
¶
resource(
name: str,
) -> Union[RemoteEnv, RemoteWorld, RemoteWorldNode, RemoteDataTransformation]
The proxy of hosted resource name (one shared proxy per name).
world
¶
world(name: str) -> RemoteWorld
Proxy of a hosted World (e.g. "sim/world" for a WorldEnv registered recursively as "sim").
node
¶
node(name: str) -> RemoteWorldNode
Proxy of a hosted WorldNode (e.g. "sim/node", "sim/node/camera").
transformation
¶
transformation(name: str) -> RemoteDataTransformation
Proxy of a hosted DataTransformation.
subscribe
¶
subscribe(name: str) -> Subscription
Follow the reset / reload / step results of hosted env name.
Results of calls by any client are delivered, latest wins: a slow subscriber skips results rather than slowing the server down.
Subscription
¶
Subscription(client: RemoteClient, name: str)
SubscriptionEvent
¶
Bases: NamedTuple
The result of a reset / reload / step of a subscribed env.
Attributes:
| Name | Type | Description |
|---|---|---|
kind |
str
|
Name of the method that produced |
sequence |
int
|
Per-env call counter; gaps mean intermediate results were skipped. |
value |
Any
|
The method's return value, converted to the client's backend and device. |
RemoteError
¶
Bases: RuntimeError
An exception raised by the hosted object (or the server) while handling a call.
type is the remote exception's class name and remote_traceback its
formatted traceback; exception objects themselves never cross the wire.
RemoteDataTransformation
¶
RemoteDataTransformation(client: RemoteClient, name: str)
Bases: _Remote, DataTransformation
A DataTransformation hosted by a :class:RemoteServer.
transform and get_target_space_from_source run on the server: the
source space and the data are rebuilt there on the backend / device the
transformation was registered with, and the result comes back on the
client's. Use it to run a transformation whose dependencies live in another
environment (e.g. a grasp synthesizer pinned to an old CUDA toolchain).
The proxy has no inverse and cannot be serialized: it is bound to its connection (serialize the hosted transformation on the server instead).
Methods:
| Name | Description |
|---|---|
direction_inverse |
Return the inverse transformation when one exists. |
close |
No-op: the hosted object stays open (it is closed by its server). |
get_target_space_from_source |
|
transform |
|
serialize |
|
deserialize_from |
|
Attributes:
| Name | Type | Description |
|---|---|---|
client |
RemoteClient
|
|
remote_name |
str
|
|
has_inverse |
|
direction_inverse
¶
direction_inverse(
source_space: Optional[
Space[SourceDataT, SourceBDeviceT, SourceBDTypeT, SourceBDRNGT]
] = None,
) -> Optional[DataTransformation]
Return the inverse transformation when one exists.
deserialize_from
classmethod
¶
deserialize_from(
json_data: Dict[str, Any], source_space: Any = None
) -> RemoteDataTransformation
RemoteEnv
¶
RemoteEnv(client: RemoteClient, name: str)
Bases: _Remote, Env
An Env hosted by a :class:RemoteServer.
Methods:
| Name | Description |
|---|---|
close |
No-op: the hosted object stays open (it is closed by its server). |
sample_space |
Sample from |
sample_action |
Sample one action from |
sample_observation |
Sample one observation from |
sample_context |
Sample one context value if |
update_observation_post_reset |
Merge masked reset observations back into a full batched observation. |
update_context_post_reset |
Merge masked reset contexts back into a full batched context. |
has_wrapper_attr |
Checks if the attribute |
get_wrapper_attr |
Gets the attribute |
set_wrapper_attr |
Sets the attribute |
reset |
|
reload |
|
step |
|
render |
|
get_node |
Node proxy by key path, for envs built on a |
Attributes:
| Name | Type | Description |
|---|---|---|
metadata |
dict[str, Any]
|
|
render_mode |
Optional[str]
|
|
render_fps |
Optional[int]
|
|
backend |
ComputeBackend[BArrayType, BDeviceType, BDtypeType, BRNGType]
|
|
device |
Optional[BDeviceType]
|
|
batch_size |
Optional[int]
|
|
action_space |
Space[ActType, BDeviceType, BDtypeType, BRNGType]
|
|
observation_space |
Space[ObsType, BDeviceType, BDtypeType, BRNGType]
|
|
context_space |
Optional[Space[ContextType, BDeviceType, BDtypeType, BRNGType]]
|
|
unwrapped |
Env
|
|
prev_wrapper_layer |
Optional[Env]
|
|
client |
RemoteClient
|
|
remote_name |
str
|
|
rng |
|
observation_space
instance-attribute
¶
context_space
class-attribute
instance-attribute
¶
context_space: Optional[Space[ContextType, BDeviceType, BDtypeType, BRNGType]] = None
sample_context
¶
sample_context() -> Optional[ContextType]
Sample one context value if context_space is defined.
update_observation_post_reset
¶
update_observation_post_reset(
old_obs: ObsType, newobs_masked: ObsType, mask: BArrayType
) -> ObsType
Merge masked reset observations back into a full batched observation.
update_context_post_reset
¶
update_context_post_reset(
old_context: ContextType, new_context: ContextType, mask: BArrayType
) -> ContextType
Merge masked reset contexts back into a full batched context.
has_wrapper_attr
¶
Checks if the attribute name exists in the environment.
set_wrapper_attr
¶
Sets the attribute name on the environment with value.
get_node
¶
get_node(nested_keys: Union[str, Sequence[str]]) -> Optional[RemoteWorldNode]
Node proxy by key path, for envs built on a WorldEnv.
RemoteWorld
¶
RemoteWorld(client: RemoteClient, name: str)
Bases: _Remote, World
A World hosted by a :class:RemoteServer.
Methods:
| Name | Description |
|---|---|
close |
No-op: the hosted object stays open (it is closed by its server). |
is_control_timestep_compatible |
Check whether a node control period aligns with |
step |
|
reset |
|
reload |
|
after_reset |
|
after_reload |
|
Attributes:
| Name | Type | Description |
|---|---|---|
backend |
ComputeBackend[BArrayType, BDeviceType, BDtypeType, BRNGType]
|
|
device |
Optional[BDeviceType]
|
The world timestep in seconds, if None, the world is asynchronous (real-time) |
world_subtimestep |
Optional[float]
|
The number of parallel environments in this world |
batch_size |
Optional[int]
|
|
client |
RemoteClient
|
|
remote_name |
str
|
|
world_timestep |
Optional[float]
|
|
device
instance-attribute
¶
The world timestep in seconds, if None, the world is asynchronous (real-time)
world_subtimestep
class-attribute
instance-attribute
¶
The number of parallel environments in this world
is_control_timestep_compatible
¶
Check whether a node control period aligns with world_timestep.
RemoteWorldNode
¶
RemoteWorldNode(client: RemoteClient, name: str)
Bases: _Remote, WorldNode
A WorldNode hosted by a :class:RemoteServer.
Methods:
| Name | Description |
|---|---|
get_nodes_by_type |
Return nodes in this subtree that are instances of |
close |
No-op: the hosted object stays open (it is closed by its server). |
has_wrapper_attr |
Checks if the attribute |
get_wrapper_attr |
Gets the attribute |
set_wrapper_attr |
Sets the attribute |
reset |
|
reload |
|
after_reset |
|
after_reload |
|
pre_environment_step |
|
post_environment_step |
|
set_next_action |
|
get_context |
|
get_observation |
|
get_reward |
|
get_termination |
|
get_truncation |
|
get_info |
|
render |
|
get_node |
|
get_nodes_by_fn |
|
Attributes:
| Name | Type | Description |
|---|---|---|
name |
str
|
|
control_timestep |
Optional[float]
|
|
update_timestep |
Optional[float]
|
|
context_space |
Optional[Space[ContextType, BDeviceType, BDtypeType, BRNGType]]
|
|
observation_space |
Optional[Space[ObsType, BDeviceType, BDtypeType, BRNGType]]
|
|
action_space |
Optional[Space[ActType, BDeviceType, BDtypeType, BRNGType]]
|
|
has_reward |
bool
|
|
has_termination_signal |
bool
|
|
has_truncation_signal |
bool
|
|
supported_render_modes |
Sequence[str]
|
|
render_mode |
Optional[str]
|
|
reset_priorities |
Set[int]
|
|
reload_priorities |
Set[int]
|
|
after_reset_priorities |
Set[int]
|
|
after_reload_priorities |
Set[int]
|
|
pre_environment_step_priorities |
Set[int]
|
|
post_environment_step_priorities |
Set[int]
|
|
can_render |
bool
|
Whether the node currently exposes a render mode. |
effective_update_timestep |
Optional[float]
|
Resolved update period, defaulting to |
unwrapped |
WorldNode
|
|
prev_wrapper_layer |
Optional[WorldNode]
|
|
client |
RemoteClient
|
|
remote_name |
str
|
|
world |
|
|
backend |
ComputeBackend
|
|
device |
Any
|
|
nodes |
List[RemoteWorldNode]
|
Proxies of the child nodes (empty for a leaf node). |
context_space
class-attribute
instance-attribute
¶
context_space: Optional[Space[ContextType, BDeviceType, BDtypeType, BRNGType]] = None
observation_space
class-attribute
instance-attribute
¶
action_space
class-attribute
instance-attribute
¶
supported_render_modes
class-attribute
instance-attribute
¶
after_reset_priorities
class-attribute
instance-attribute
¶
after_reload_priorities
class-attribute
instance-attribute
¶
pre_environment_step_priorities
class-attribute
instance-attribute
¶
post_environment_step_priorities
class-attribute
instance-attribute
¶
effective_update_timestep
property
¶
Resolved update period, defaulting to control_timestep when unset.
get_nodes_by_type
¶
Return nodes in this subtree that are instances of node_type.
has_wrapper_attr
¶
Checks if the attribute name exists in the environment.
set_wrapper_attr
¶
Sets the attribute name on the environment with value.
reset
¶
reload
¶
RemoteServer
¶
RemoteServer(*, max_frame_size: int = DEFAULT_MAX_FRAME_SIZE)
Serve registered objects to :class:RemoteClient connections.
Example::
with RemoteServer() as server:
server.register("sim", env) # or register_recursive() to also host its world and nodes
server.serve("tcp://0.0.0.0:7000") # blocks; or listen() in the background
Each registered root runs on its own worker thread, shared by every hosted object
with the same world; calls on them are executed there one at a time, in arrival
order, whichever client sent them. Only the methods in protocol.METHODS can be
called.
Methods:
| Name | Description |
|---|---|
register |
Host |
register_recursive |
Like :meth: |
listen |
Accept connections on |
serve |
Listen on |
connect |
An in-process client over a :class: |
close |
Stop listening, drop every connection, close owned objects on their workers. |
Attributes:
| Name | Type | Description |
|---|---|---|
max_frame_size |
|
|
resources |
List[str]
|
Names of every hosted resource. |
register
¶
register(
name: str,
obj: Hosted,
*,
close: bool = True,
backend: Optional[ComputeBackend] = None,
device: Optional[Any] = None,
) -> str
Host obj (an Env, World, WorldNode or DataTransformation) under name.
Only obj itself is exposed; use :meth:register_recursive to also expose
the world and nodes it is built from. Objects sharing a world (e.g. an env and
its world registered separately) run on the same worker. Registering an object
that is already hosted returns its existing name. With close=True the server
closes obj (on its worker) when it shuts down.
A DataTransformation has no backend of its own: backend / device
(default: numpy, no device) are where the source spaces and data of its
calls are rebuilt on the server. Other objects use their own.
register_recursive
¶
register_recursive(name: str, obj: Hosted, *, close: bool = True) -> str
Like :meth:register, but also expose everything obj is built from.
An env built on a WorldEnv also exposes name/world and name/node
(the root node), and every node exposes its world (<node name>/world, unless
already hosted) and its children as <node name>/<child>, so clients can
compose them in components mode. Objects already hosted keep their first name.
listen
¶
Accept connections on address in the background; return the bound address.
address is tcp://host:port, unix:///path or ws://host:port
(the latter requires websockets, from the network extra).
serve
¶
Listen on address and block until :meth:close (or Ctrl-C).
connect
¶
connect(**client_options: Any) -> RemoteClient
An in-process client over a :class:MemoryTransport (mainly for tests).
close
¶
Stop listening, drop every connection, close owned objects on their workers.
MemoryTransport
¶
MemoryTransport(
incoming: _Queue, outgoing: _Queue, max_frame_size: int = DEFAULT_MAX_FRAME_SIZE
)
Bases: Transport
In-process pair (tests); frames are copied, as on a real connection.
Methods:
| Name | Description |
|---|---|
pair |
|
send |
|
recv |
|
close |
|
Attributes:
| Name | Type | Description |
|---|---|---|
max_frame_size |
int
|
|
pair
classmethod
¶
pair(
max_frame_size: int = DEFAULT_MAX_FRAME_SIZE,
) -> Tuple[MemoryTransport, MemoryTransport]
StreamTransport
¶
StreamTransport(sock: socket, max_frame_size: int = DEFAULT_MAX_FRAME_SIZE)
Bases: Transport
Frames over a connected stream socket; each frame goes out in one sendmsg.
Methods:
| Name | Description |
|---|---|
send |
|
recv |
|
close |
|
Attributes:
| Name | Type | Description |
|---|---|---|
max_frame_size |
int
|
|
Transport
¶
A reliable, ordered connection carrying whole frames.
Methods:
| Name | Description |
|---|---|
send |
Send the frame |
recv |
Block for the next frame; raise |
close |
Close the connection, unblocking |
Attributes:
| Name | Type | Description |
|---|---|---|
max_frame_size |
int
|
|
send
¶
Send the frame parts (size bytes in total). Thread-safe.
WebSocketTransport
¶
WebSocketTransport(connection: Any, max_frame_size: int = DEFAULT_MAX_FRAME_SIZE)
Bases: Transport
One frame per binary WebSocket message (requires websockets).
Methods:
| Name | Description |
|---|---|
send |
|
recv |
|
close |
|
Attributes:
| Name | Type | Description |
|---|---|---|
max_frame_size |
int
|
|
WireError
¶
Bases: ValueError
A frame is malformed or violates the wire format's limits.