Navigation

These docs describe unreleased changes on main. See the latest release.

rlmesh

RLMesh Python SDK.

import rlmesh

The top-level package holds the entry points: serve an environment, connect to one, run a model against it, and record what happened. The classes here keep RLMesh-native values; the value backends re-export the same names with NumPy, Torch, or JAX decoding.

Serve and connect

EnvServer owns one environment and exposes it as an endpoint. Pass a vectorized env (one with num_envs and single_observation_space) and it serves a vector endpoint; otherwise a single one. It inspects the env once and caches the EnvContract that every client receives in the handshake.

import rlmesh

server = rlmesh.EnvServer(env, "127.0.0.1:5555")
print(server.env_contract.observation_space.kind)
server.serve()

A client needs only the address: RemoteEnv for single endpoints, RemoteVectorEnv for vector ones. Both expose reset, step, render, and close, and build observation_space / action_space from the contract, so the client never needs a local copy of the env. render() returns None when the env produces no frame.

When RLMesh serves an env through its bootstrap entrypoint (inside a sandbox container, for example), the bind address comes from the environment:

Variable Meaning
RLMESH_ADDRESS Full bind address (host:port, port, tcp://host:port, unix:///...). Wins when set.
RLMESH_PORT Port-only fallback on 0.0.0.0, used when RLMESH_ADDRESS is unset (default 50051).

Constructing EnvServer yourself ignores both; pass the address explicitly. The transport is plaintext gRPC and unauthenticated unless a bearer token is configured, so bind 0.0.0.0 only on a trusted network (exposure and authentication).

Models

Model wraps a prediction function, or you subclass it and implement load() plus one of the four predict corners (predict, predict_chunk, predict_batch, predict_chunk_batch); the runtime derives the rest. A model does not have to live in your process: RemoteModel dials a policy that is already served, and SandboxModel runs a prebuilt image:// tag in its own container. The Models guide and Model Reference cover the corner contract.

Run and evaluate

run() binds a model to an env and pumps whole episodes, returning a RunResult. session() hands back a Session you drive by hand with reset / predict / step.

env = rlmesh.RemoteEnv("127.0.0.1:5555")
result = rlmesh.run(model, env, seeds=range(10))
print(result.episodes[0].reward)

Two sentinels change what they do. NO_ADAPTER as a model’s spec skips adapter resolution, so the model handles raw env values itself. RANDOM_SAMPLE as the model samples the action space each step: a random baseline with no spec involved.

Recorder accumulates one or more runs and exports a portable rlmesh.result.v1 bundle.

Sandboxes

SandboxEnv and SandboxVectorEnv build or pull an env image, start the container, connect a client to it, and stop the container on close. Reach for them when an env needs its own dependencies and process. SandboxBuild groups the build settings for a gym:// or hf:// source; SandboxRuntime groups the docker run flags. See Sandboxed Environments.

Error handling

RLMeshException is the base of the RLMesh-specific exception families and subclasses RuntimeError. It covers the RLMesh-specific protocol, environment, and model families; transport and argument errors use Python built-ins outside that hierarchy. EnvironmentException is raised when an endpoint fails a reset, step, or render; a recoverable fault raises RecoverableEnvironmentException. ModelException reports model failures. Both families carry code and is_recoverable; ProtocolException covers protocol and handshake violations. Transport faults, timeouts, and bad arguments raise the standard ConnectionError, TimeoutError, and ValueError. Troubleshooting maps each failure to its cause.

Classes

Functions

Exceptions

Submodules

Constants