Torch

The Torch backend is experimental.

What This Backend Changes

rlmesh.torch keeps the same environment, model, and sandbox behavior as the shared RLMesh client APIs, but decodes tensor leaves to Torch tensors. Space wrappers returned from Torch clients also sample Torch-compatible values.

Install it with:

pip install "rlmesh[torch]"

Concrete API	Shared behavior	Backend-specific behavior
rlmesh.torch.RemoteEnv	Remote Environments single clients	Observations, actions, and render frames use tensors.
rlmesh.torch.RemoteVectorEnv	Remote Environments vector clients	Batched values use Torch-compatible containers.
rlmesh.torch.Model	Models	predict_fn receives Torch-decoded observations.
rlmesh.torch.SandboxEnv	Sandbox single sandbox sessions	Owned sandbox client is rlmesh.torch.RemoteEnv.
rlmesh.torch.SandboxVectorEnv	Sandbox vector sandbox sessions	Owned sandbox client is rlmesh.torch.RemoteVectorEnv.

Memory Sharing and Mutation

Decoded observations are owned, writable copies, so predict_fn can normalize in place (img.div_(255)) without corrupting the wire buffer. as_tensor(tensor) is the zero-copy opt-in: the Torch tensor shares memory with the RLMesh tensor over DLPack.

Warning

A zero-copy as_tensor(tensor) view shares memory. RLMesh flags the export read-only, but Torch, like most DLPack consumers, does not enforce that flag, so an in-place write corrupts the RLMesh tensor for every other view of the same data, including NumPy views in the same process. Treat a shared view as read-only, or pass copy=True.

Conversion details:

• Decode uses torch.utils.dlpack.from_dlpack; bool tensors fall back to a buffer copy on Torch older than 2.2 (no bool DLPack support there).

• uint16, uint32, and uint64 dtypes require Torch 2.3 or newer.

• Encode (from_tensor) detaches, moves to CPU, and exports over DLPack; NumPy is not required.

Value Helpers

rlmesh.torch.ensure_available()

Raise if Torch is not installed.

Return type:

None

rlmesh.torch.as_tensor(tensor, *, copy=False)

Return a Torch tensor view or copy of an RLMesh tensor.

Warning

Without copy=True the returned tensor shares memory with the RLMesh tensor, and Torch will let you write through it even though the export is flagged read-only (DLPack consumers may ignore that flag). Mutating the view corrupts the RLMesh tensor for every other view of the same data. Treat shared views as read-only, and pass copy=True for any tensor you intend to modify.

Parameters:

• tensor (Tensor | bool | int | float) – RLMesh tensor or scalar primitive to convert.

• copy (bool) – If True, copy tensor data before creating the Torch tensor.

Returns:

Torch tensor sharing the RLMesh tensor’s memory via DLPack, or an independent copy when copy=True.

Return type:

object

rlmesh.torch.from_tensor(tensor)

Encode a Torch tensor as an RLMesh value.

Parameters:

tensor (object) – Torch tensor to encode.

Returns:

Tensor for non-scalar tensors, or a primitive for scalar values.

Return type:

Tensor | bool | int | float

rlmesh.torch.space_from_spec(spec)

Create a Torch-adapted space wrapper for a native space spec.

Parameters:

spec (SpaceSpec)

Return type:

Space[None | bool | int | float | str | bytes | object | list[None | bool | int | float | str | bytes | object | list[TorchValue] | tuple[TorchValue, …] | dict[str, TorchValue]] | tuple[None | bool | int | float | str | bytes | object | list[TorchValue] | tuple[TorchValue, …] | dict[str, TorchValue], …] | dict[str, None | bool | int | float | str | bytes | object | list[TorchValue] | tuple[TorchValue, …] | dict[str, TorchValue]]]

RemoteEnv

final class rlmesh.torch.RemoteEnv

Bases: RemoteEnvBase[None | bool | int | float | str | bytes | object | list[TorchValue] | tuple[TorchValue, …] | dict[str, TorchValue], None | bool | int | float | str | bytes | object | list[TorchValue] | tuple[TorchValue, …] | dict[str, TorchValue]]

Experimental Torch-backed remote client for one environment.

Tensor leaves decode to Torch tensors while Python primitives and nested containers are preserved.

Parameters:

• address – Endpoint address such as "tcp://127.0.0.1:5555".

• host – TCP host helper used when address is omitted.

• port – TCP port helper used when address is omitted.

• path – Unix socket path helper used when address is omitted.

• transport – Explicit transport selector.

RemoteVectorEnv

final class rlmesh.torch.RemoteVectorEnv

Bases: RemoteVectorEnvBase[None | bool | int | float | str | bytes | object | list[TorchValue] | tuple[TorchValue, …] | dict[str, TorchValue], None | bool | int | float | str | bytes | object | list[TorchValue] | tuple[TorchValue, …] | dict[str, TorchValue]]

Experimental Torch-backed remote client for vectorized environments.

Parameters:

• address – Endpoint address such as "tcp://127.0.0.1:5555".

• host – TCP host helper used when address is omitted.

• port – TCP port helper used when address is omitted.

• path – Unix socket path helper used when address is omitted.

• transport – Explicit transport selector.

Model

final class rlmesh.torch.Model

Bases: ModelBase[None | bool | int | float | str | bytes | object | list[TorchValue] | tuple[TorchValue, …] | dict[str, TorchValue], None | bool | int | float | str | bytes | object | list[TorchValue] | tuple[TorchValue, …] | dict[str, TorchValue]]

Experimental Torch-backed model: predict works in Torch values.

The Torch-typed ModelBase; see it for the source/spec construction and run(env, seeds=[...]) -> RunResult eval.

Sandbox

final class rlmesh.torch.SandboxEnv

Bases: SandboxEnvBase[None | bool | int | float | str | bytes | object | list[TorchValue] | tuple[TorchValue, …] | dict[str, TorchValue], None | bool | int | float | str | bytes | object | list[TorchValue] | tuple[TorchValue, …] | dict[str, TorchValue]]

Experimental Torch-backed owned sandbox session for one environment.

Parameters:

• source – Gymnasium id, explicit gym:// source, or pinned environment source.

• base_image – Optional Docker base image override.

• rlmesh_package – Optional RLMesh package, wheel, or "local" installed in the sandbox.

• packages – Extra environment packages installed in the sandbox.

• imports – Import names checked during sandbox startup.

• trust_remote_code – Allow remote environment code to execute.

• allow_unpinned_hf – Allow Hugging Face sources without a pinned revision.

• **gym_make_kwargs – Keyword arguments forwarded to environment creation.

final class rlmesh.torch.SandboxVectorEnv

Bases: SandboxVectorEnvBase[None | bool | int | float | str | bytes | object | list[TorchValue] | tuple[TorchValue, …] | dict[str, TorchValue], None | bool | int | float | str | bytes | object | list[TorchValue] | tuple[TorchValue, …] | dict[str, TorchValue]]

Experimental Torch-backed owned sandbox session for vectorized environments.

Parameters:

• source – Gymnasium id, explicit gym:// source, or pinned environment source.

• num_envs – Number of environment instances to create.

• vectorization_mode – Vectorization mode requested inside the sandbox.

• base_image – Optional Docker base image override.

• rlmesh_package – Optional RLMesh package, wheel, or "local" installed in the sandbox.

• packages – Extra environment packages installed in the sandbox.

• imports – Import names checked during sandbox startup.

• trust_remote_code – Allow remote environment code to execute.

• allow_unpinned_hf – Allow Hugging Face sources without a pinned revision.

• **env_make_kwargs – Keyword arguments forwarded to environment creation.