Core Exports

Note

This is the autodoc API reference. For authoring guides see Environments and Models.

The top-level rlmesh package re-exports the common entry points: environment serving and clients, model running, sandboxing, and the spaces, types, and adapters subpackages.

The top-level client and model classes are dependency-free wrappers around RLMesh-native values. Reach for them when you want native values and no framework dependency; use a backend module (Framework Backends) when you want tensor leaves decoded to NumPy arrays or Torch tensors.

Import	Description
rlmesh.EnvServer	Serve a Gymnasium-compatible environment endpoint (scalar or vector).
rlmesh.RemoteEnv	Connect to one environment and preserve RLMesh-native values.
rlmesh.RemoteVectorEnv	Connect to a vector endpoint and preserve RLMesh-native values.
rlmesh.SandboxEnv	Build an env image and own the container behind a single client.
rlmesh.SandboxVectorEnv	Build an env image and own the container behind a vector client.
rlmesh.Model	Wrap a Python prediction function as a native-value model.
rlmesh.RemoteModel	Connect to an already-served model and drive it against an env.
rlmesh.SandboxModel	Run a model policy in its own container (experimental).
rlmesh.ServeOptions	Native serve lifecycle options.
rlmesh.Tensor	Native tensor value used by dependency-free clients.
rlmesh.adapters	Observation/action adapters and contract-based resolution.
rlmesh.spaces	Space wrappers and Gymnasium conversion helpers.
rlmesh.types	Structural protocols and value aliases.

The detailed pages below describe the shared behavior:

• Serving and Clients

• Models

• Contracts and Specs

Run and Evaluate

The eval surface binds a model to an environment. run() pumps whole episodes and returns a RunResult; session() returns a Session you drive by hand with reset / predict / step.

rlmesh.run(model, env, *, seeds=None, max_episodes=None, max_episode_steps=None, max_episode_seconds=None, hooks=None, instruction=None, close_env=False, trust_entrypoints=None, execution_horizon=1, view=None)

Drive model against env to completion and return a RunResult.

The auto-pump convenience over rlmesh.session(): it creates the session internally and closes it (honoring close_env) when the run ends – hold a rlmesh.session() yourself to reuse one binding across runs. Works for a local Model or a served RemoteModel / SandboxModel (a served model rejects instruction=; the env’s own instruction is used). max_episode_steps / max_episode_seconds cap each episode (hitting a cap marks it truncated), and hooks (rlmesh.RunHooks) observes the loop; all three pass through to Session.run.

Parameters:

• model (object)

• env (EnvTarget)

• seeds (Sequence[int] | None)

• max_episodes (int | None)

• max_episode_steps (int | None)

• max_episode_seconds (float | None)

• hooks (RunHooks | None)

• instruction (str | None)

• close_env (bool)

• trust_entrypoints (bool | None)

• execution_horizon (int)

• view (ViewArg)

Return type:

RunResult

rlmesh.session(model: ModelBase[ObsT, ActT], env: LocalEnvTarget, *, instruction: str | None = None, close_env: bool = False, trust_entrypoints: bool | None = None, execution_horizon: int = 1, view: ViewArg = None) → Session[ObsT, ActT]

rlmesh.session(model: type[Any], env: EnvTarget, *, instruction: str | None = None, close_env: bool = False, trust_entrypoints: bool | None = None, execution_horizon: int = 1, view: ViewArg = None) → Session[Any, Any]

rlmesh.session(model: Callable[[ObsT], ActT], env: LocalEnvTarget, *, instruction: str | None = None, close_env: bool = False, trust_entrypoints: bool | None = None, execution_horizon: int = 1, view: ViewArg = None) → Session[ObsT, ActT]

rlmesh.session(model: object, env: EnvTarget, *, instruction: str | None = None, close_env: bool = False, trust_entrypoints: bool | None = None, execution_horizon: int = 1, view: ViewArg = None) → Session[Any, Any]

Bind a model to an env and return a Session to drive by hand or via run().

model is a local Model (instance, subclass class, or a bare predict callable) or a served handle (RemoteModel / SandboxModel); env is a local env, an EnvFactory, a remote-env handle, or an address string. A spec’d model resolves its adapter from the env’s tags – a local env must carry them (via rlmesh.adapters.tag() or an EnvFactory). A served model rejects instruction= (the env’s own instruction is used).

The returned session is yours: Session.run() leaves it open, so drive it (or re-run it) as often as you like, then close it via close() or the with block.

Pass rlmesh.RANDOM_SAMPLE as model for a random baseline: each step samples the env’s action space, no spec or adapter involved.

Typing: a Model instance or an annotated predict callable flows its observation/action types onto the returned Session (predict/step are typed accordingly); a class source, duck-typed policy, or served handle yields Session[Any, Any].

Parameters:

• model (object)

• env (EnvTarget)

• instruction (str | None)

• close_env (bool)

• trust_entrypoints (bool | None)

• execution_horizon (int)

• view (ViewArg)

Return type:

Session[Any, Any]

class rlmesh.Session

Bases: Generic[ObsT, ActT]

A model bound to one env: drive it by hand, or pump whole episodes.

The neutral pair-driver returned by rlmesh.session(). reset / predict / step drive one step at a time – predict applies the model’s adapter (resolved from the env’s published contract) around the model’s own predict, replaying an action chunk one action per step when execution_horizon > 1 and the model defines predict_chunk. run pumps whole episodes and returns a typed RunResult.

The env connection is opened lazily on first reset (manual driving); run drives whole episodes through the same primitives and leaves the session open, so a caller-held session runs as often as you like. Close it yourself – close() or the with block; after that, any further use raises. (The one-shot rlmesh.run() / Model.run create their session internally and close it when the run ends.)

__init__()

Return type:

None

property done: bool

Whether the current episode has terminated or truncated.

reset(*, seed=None)

Begin a new episode: end the previous one, then reset the env and adapter.

Ending the previous episode fires the model’s on_episode_end (the local per-episode boundary), so a stateful model clears its state between episodes on the hand-driven path too, not only via run().

Parameters:

seed (int | None)

Return type:

tuple[ObsT, Mapping[str, Any]]

predict(observation)

Map one env observation to an env-ready action (the model’s adapter applied).

Parameters:

observation (ObsT)

Return type:

ActT

step(action)

Apply one action to the env; record reward and termination.

Parameters:

action (ActT)

Return type:

tuple[ObsT, float, bool, bool, Mapping[str, Any]]

reader(*items)

Build a read-only, role-addressed view over this env’s observations.

Each item is a role constant – kept in the env’s native encoding – or a model-input leaf declaring the encoding you want (Image(IMAGE_PRIMARY, layout="hwc"), State(EEF_POS)). The returned Reader maps a raw observation to {role: value} through the same adapter pipeline a model uses, so it is encoding-agnostic across envs and runs identically in the native core. Resolved once here, reused each step:

read = sess.reader(Image(IMAGE_PRIMARY, layout="hwc"), EEF_POS)
obs, _ = sess.reset()
while not sess.done:
    screen.show(read(obs)[IMAGE_PRIMARY])
    obs, *_ = sess.step(sess.predict(obs))

A bare role is desugared to the env-native leaf for that role (by the env’s own tag); pass an explicit leaf to override the encoding.

Parameters:

items (object)

Return type:

Reader

read(observation, item)

One-shot read of a single role from one observation.

The single-value convenience for reader() – item is a role constant or a model-input leaf. The reader is resolved once and cached per item, so calling this every step does not re-resolve:

ee = sess.read(obs, EEF_POS)
img = sess.read(obs, Image(IMAGE_PRIMARY, layout="hwc"))

The value is typed Any (like Reader’s): its concrete shape is the leaf’s declared encoding, which the caller owns.

Parameters:

• observation (object)

• item (object)

Return type:

Any

observation_roles()

The observation roles this session’s env declares, grouped by kind.

Connects if needed, reads the env contract’s published tags, and returns their observation_roles. An env that publishes no tags yields empty groups – “none declared” is an answer, not an error.

Return type:

ObservationRoles

run(*, seeds=None, max_episodes=None, max_episode_steps=None, max_episode_seconds=None, hooks=None)

Drive whole episodes to completion and return a typed RunResult.

The single drive loop: pumps this session’s own reset / predict / step primitives, so Model.run routes through here. seeds gives a per-episode seed and sets the episode count unless max_episodes is given. max_episode_steps / max_episode_seconds cap each episode – hitting a cap marks it truncated, exactly like the built-in step bound (the wall-clock cap is checked at the top of the step loop). hooks (RunHooks) observes the loop; hook exceptions propagate and abort the run, and RunHooks.on_run_end() always fires exactly once with the completed episodes, even on an error or interrupt.

Does not close the session: a caller-held session (from rlmesh.session() / Model.session()) stays connected – viewer and hooks included – so run can be called again or mixed with manual driving; close it via close() or the with block. (The one-shot rlmesh.run() / Model.run() own their internal session and close it for you.)

Parameters:

• seeds (Sequence[int] | None)

• max_episodes (int | None)

• max_episode_steps (int | None)

• max_episode_seconds (float | None)

• hooks (RunHooks | None)

Return type:

RunResult

close()

Close this session: model close hook, served route (and owned source), env.

For a served model, closes the model client and shuts down a managed source it started (e.g. a SandboxModel container). For the env, shuts it down only on the close_env opt-in and closes a connection this session dialed.

Idempotent: the first call tears everything down (firing a local model’s on_close exactly once, whether the session was pumped via run or driven by hand); later calls are no-ops, and any other use of a closed session raises RuntimeError.

Return type:

None

class rlmesh.RunResult

Bases: object

The result of a Model.run() eval.

property num_episodes: int

Number of episodes in this result.

property total_steps: int

Total env steps across all episodes.

property mean_reward: float

Mean total reward per episode (0.0 when empty).

property success_rate: float

Fraction of episodes that succeeded.

Prefers the env-reported task outcome (Gymnasium info["is_success"] / ["success"], captured per episode in EpisodeResult.success). For an env that emits no such signal, falls back to terminated for that episode – so a time-limit env whose success is the truncation cap should report success via info rather than rely on this.

__init__(episodes=())

Parameters:

episodes (tuple[EpisodeResult, ...])

Return type:

None

class rlmesh.EpisodeResult

Bases: object

The outcome of one evaluation episode.

index

0-based episode index within the run.

Type:

int

seed

The seed the episode was reset with, or None.

Type:

int | None

steps

Number of env steps taken.

Type:

int

reward

Total reward accumulated over the episode.

Type:

float

terminated

Whether the env reported a terminal state.

Type:

bool

truncated

Whether the episode was cut short (env truncation, a max_episode_steps / max_episode_seconds cap, or the built-in step bound).

Type:

bool

success

The env-reported task outcome from the final step’s info (Gymnasium’s is_success / success key), or None when the env emits no such signal. Distinct from terminated (which only says the episode reached a terminal state, not whether it succeeded).

Type:

bool | None

duration_s

Wall time from reset-return to episode end, in seconds.

Type:

float

predict_ms

Mean per-step wall time of predict, in milliseconds.

Type:

float

step_ms

Mean per-step wall time of the env step round trip, in milliseconds.

Type:

float

__init__(index, seed, steps, reward, terminated, truncated, success=None, duration_s=0.0, predict_ms=0.0, step_ms=0.0)

Parameters:

• index (int)

• seed (int | None)

• steps (int)

• reward (float)

• terminated (bool)

• truncated (bool)

• success (bool | None)

• duration_s (float)

• predict_ms (float)

• step_ms (float)

Return type:

None

class rlmesh.RunHooks

Bases: object

Observer callbacks for Session.run(); every default is a no-op.

Subclass and override any subset, then pass an instance as hooks= to rlmesh.run(), Model.run, or Session.run(). Hook exceptions propagate and abort the run; on_run_end() still fires exactly once with the completed episodes.

on_episode_start(*, episode, seed)

Called after each episode’s reset returns (no-op by default).

Parameters:

• episode (int) – 0-based episode index (equals EpisodeResult.index).

• seed (int | None) – The seed the episode was reset with, or None.

Return type:

None

on_step(event)

Called after each env step with its StepEvent (no-op by default).

Parameters:

event (StepEvent)

Return type:

None

on_episode_end(result)

Called with each completed episode’s EpisodeResult (no-op by default).

Parameters:

result (EpisodeResult)

Return type:

None

on_run_end(result)

Called exactly once when the run ends (no-op by default).

Fires even on an exception or interrupt, with the possibly-partial RunResult of the episodes that completed.

Parameters:

result (RunResult)

Return type:

None

class rlmesh.StepEvent

Bases: object

One env step of a Session.run() eval, passed to RunHooks.on_step().

episode

0-based episode index (equals EpisodeResult.index).

Type:

int

seed

The episode’s reset seed, or None.

Type:

int | None

step

0-based step index within the episode.

Type:

int

observation

The raw observation the action was predicted from (pre-step).

Type:

Any

action

The env-ready action applied to the env.

Type:

Any

reward

The step’s reward.

Type:

float

terminated

Whether the env reported a terminal state on this step.

Type:

bool

truncated

Whether this step truncated the episode.

Type:

bool

info

The step’s info mapping.

Type:

collections.abc.Mapping[str, Any]

predict_ms

Raw wall time of this step’s predict, in milliseconds; near zero on chunk-replay steps, where no model forward runs.

Type:

float

step_ms

Raw wall time of the env step round trip, in milliseconds.

Type:

float

read

Lazy role reader bound to observation – event.read(item) delegates to Session.read(), so resolution is cached per item and never triggered unless called.

Type:

collections.abc.Callable[[object], object]

__init__(episode, seed, step, observation, action, reward, terminated, truncated, info, predict_ms, step_ms, read)

Parameters:

• episode (int)

• seed (int | None)

• step (int)

• observation (Any)

• action (Any)

• reward (float)

• terminated (bool)

• truncated (bool)

• info (Mapping[str, Any])

• predict_ms (float)

• step_ms (float)

• read (Callable[[object], object])

Return type:

None

class rlmesh.View

Bases: object

How to show a live eval. Pass to run / session as view=.

The common cases are the string shorthands "terminal" / "http" / "http:9000" / "both"; construct a View directly only to tune.

backend

Where to draw – "terminal" (in-place half-blocks), "http" (a local web page), or "both".

Type:

str

port

HTTP port for the "http" / "both" backends.

Type:

int

fps

Target frame rate; frames produced faster are dropped.

Type:

int

source

Which source to show first by label (a render label or an image role); None shows the first available.

Type:

str | None

format

Encoding for HTTP frames, "jpeg" or "png".

Type:

str

quality

JPEG quality 1..100 (ignored for PNG).

Type:

int

__init__(backend='terminal', port=8008, fps=30, source=None, format='jpeg', quality=75)

Parameters:

• backend (str)

• port (int)

• fps (int)

• source (str | None)

• format (str)

• quality (int)

Return type:

None

rlmesh.sanitize_metadata(info)

Coerce an info/metadata mapping into what RLMesh metadata accepts.

Lossy by design: simulator handles and other rich objects (for example a sapien.Pose) become their str() form rather than failing the serve path. Accepted values pass through unchanged: None, bool, int, float, str, bytes, and nested mappings/lists/tuples of them (tuples become lists, as in the codec). NumPy scalars/arrays and namedtuples are unwrapped the way the codec does (_asdict / tolist / item), enums resolve to their value with a name fallback, and non-string keys are stringified.

Parameters:

info (Mapping[str, Any]) – The mapping to sanitize (e.g. a Gymnasium info dict).

Returns:

A plain dict the native metadata codec accepts verbatim.

Raises:

• TypeError – If info is not a mapping.

• ValueError – If info contains a reference cycle (the error names the key path).

Return type:

dict[str, Any]

Sentinels

Two module-level sentinels change what run and session do:

• rlmesh.NO_ADAPTER: pass as a model’s spec to explicitly skip adapter resolution; the model handles raw env observations and actions itself.

• rlmesh.RANDOM_SAMPLE: pass as the model to rlmesh.run / rlmesh.session to sample the env’s action space each step, a random baseline with no spec or adapter involved.

Environment Authoring

The authoring surface declares an environment before anything is built: a factory with its construction params, the catalog of named variants, and the describe envelope tooling. The guide is Environments.

class rlmesh.EnvFactory

Bases: ABC

Authoring base that builds environment(s): set tags and implement make.

Subclass per obs/action contract – the tags (a EnvTags) are that contract. make(**kwargs) is the factory and may return a single env or a vectorized batch; task selection and num_envs are its parameters, not separate subclasses. tags = None (the default) means a generic, un-adapted env.

Optionally set params to a ParamSpec declaring make’s construction parameters; a managed dashboard then presents/validates/sweeps them, and a bad binding is rejected before construction (see rlmesh.params). params = None (default) keeps today’s blind passthrough to make.

Optionally implement an enumerate_variants() classmethod that returns a list of Variant (or yield them lazily) – the finite, named catalog of concrete sub-environments this factory contains (e.g. one per benchmark task). Each variant binds only its identity-defining params; the remaining free dials stay in params (the ParamSpec is always the full validation surface – never describe the same dimension in both enumerate_variants and enumerate_params). Import heavy/optional deps lazily inside the method, as make does, so describe stays off-GPU. See rlmesh.describe().

params: ClassVar[ParamSpec | None] = None

Optional declared construction-parameter surface validated against make.

prepare()

Optional: one-time setup before make().

Return type:

None

classmethod describe()

Return this factory’s full metadata envelope (see rlmesh.describe()).

Return type:

dict[str, Any]

abstractmethod make(**kwargs)

Construct and return the environment.

Your override returns a plain env; the returned env is automatically stamped with this factory’s tags (in env.metadata), so the tag rides the environment – a spec’d model can resolve its adapter from the env alone, whether it is served or driven locally via rlmesh.session().

Parameters:

kwargs (Any)

Return type:

EnvLike[Any, Any]

close()

Optional: release resources.

Return type:

None

final serve(address, *, num_envs=1, vectorization_mode=None, framework=None, device=None, **make_kwargs)

Host this env on address (blocking): prepare() + make(**make_kwargs), publish tags.

The named keywords are serving options, forwarded to rlmesh.serve.serve_env() (num_envs > 1 fans make out into a vector env; framework/device type and place the served obs/action seam); every other keyword goes to make. Naming them here keeps a make kwarg from silently binding to a serving option – a make parameter that shares a serving option’s name cannot ride through serve.

Parameters:

• address (str)

• num_envs (int)

• vectorization_mode (str | None)

• framework (str | None)

• device (object | None)

• make_kwargs (Any)

Return type:

None

class rlmesh.Param

Bases: object

One declared construction parameter – validated, presentable, sweepable.

Declaring a Param is the act of marking a knob primary: it is presented as a first-class widget, validated (type/choices/required) before construction, and offered as a sweep axis. Undeclared keyword args of make/load are still presented and type-checked for free (the signature-derived tier); Param enriches one with domains, choices, grouping, and sweepability.

The default lives in the make/load signature, never here: a param with a signature default is optional, one without is required. A Param only enriches that knob (choices/grouping/description/sweepability); it does not restate the default.

Parameters:

• name – The keyword name, matching the make/load parameter.

• type – A Python type (int/float/str/bool) or its string name, "enum" (domain defined entirely by choices), or a Vector (a fixed-length float vector).

• choices – Allowed values – the enumeration/sweep axis; a supplied value outside them is rejected.

• description – Human-facing help text for the dashboard widget.

• group – Optional UI grouping label (advisory; the core never reads it).

__init__(name, type='str', choices=None, description='', group=None)

Parameters:

• name (str)

• type (type | str | Vector)

• choices (tuple[Any, ...] | None)

• description (str)

• group (str | None)

Return type:

None

class rlmesh.ParamSpec

Bases: object

A factory’s/model’s declared construction-parameter surface.

The validated ceiling over the free signature-derived floor. extra governs the single boundary door for undeclared keys:

• "forbid" (default): an undeclared key raises before construction, so a typo (robtos=) fails pre-GPU instead of vanishing.

• "passthrough": undeclared keys forward verbatim through the author’s own **kwargs into a third-party constructor (the escape hatch for a wrapper author). Bounded by that **kwargs – never by any downstream target – so it cannot collide with a body-computed argument.

Build the spec, rejecting a parameter declared more than once.

A duplicate Param name would silently last-win at resolve time, so the second declaration – always an authoring mistake – fails here.

__init__(*params, extra='forbid')

Build the spec, rejecting a parameter declared more than once.

A duplicate Param name would silently last-win at resolve time, so the second declaration – always an authoring mistake – fails here.

Parameters:

• params (Param)

• extra (Literal['forbid', 'passthrough'])

Return type:

None

class rlmesh.Vector

Bases: object

A fixed-length float-vector Param type, passed as Param(type=Vector(3)).

The value stays a plain tuple of dim finite floats; a JSON-bound list is canonicalized to a tuple. Vector is only a schema descriptor sitting in Param.type next to "float"/"enum" – it is not a container the runtime carries. unit requires unit L2 norm (the quaternion/direction case). Sweeps come from choices (a list of whole vectors): there is no continuous vector domain.

__init__(dim, unit=False)

Parameters:

• dim (int)

• unit (bool)

Return type:

None

class rlmesh.Variant

Bases: object

One concrete sub-environment in an EnvFactory’s catalog.

Return a list of these from an optional enumerate_variants() classmethod (or yield them lazily for a large catalog) to enumerate the finite, named environments a factory contains – e.g. one per benchmark task. Distinct from enumerate_params(), which declares independent sweep axes: a catalog is a flat list of named, already-bound sub-envs, the right shape when the dimensions are dependent (a task index whose range depends on the suite) and each entry has a human identity. python -m rlmesh._describe emits the catalog off-GPU for a managed dashboard / env hub to list and spawn.

Parameters:

• id – Author-explicit, non-empty, factory-unique handle (e.g. "libero_10/pick_up_the_black_bowl"). Prefer a stable upstream identity over a positional index – a positional id silently repoints if the upstream library reorders. A hub composes a global handle as (factory identity, id).

• params – make() kwargs binding ONLY the identity-defining params; the remaining free dials stay in the ParamSpec and are composed by the consumer (free dials = param_spec names minus these keys). Copied defensively, so reusing one dict across entries in a loop is safe.

• metadata – Open display bag (keyword-only). name is the one recognized key a dashboard renders as the title; every other key is domain metadata the framework passes through untouched (e.g. a robotics env’s instruction).

__init__(id, params, /, **metadata)

Parameters:

• id (str)

• params (Mapping[str, Any])

• metadata (Any)

Return type:

None

rlmesh.describe(obj, *, kind=None, generated_at=None)

Return an env/model’s full metadata envelope as a dict.

obj may be an EnvFactory/Model class or instance, a bare make/predict callable, or a "module:Class" entrypoint string. kind ("env"/"model") is auto-detected for a factory/model and required for a bare callable. generated_at is an optional RFC-3339 timestamp (the Rust layer validates it); omit it for a content-addressable artifact. The returned dict is parsed from the canonical string – use describe_json() when you need the exact bytes (e.g. an OCI label).

Parameters:

• obj (object)

• kind (str | None)

• generated_at (str | None)

Return type:

dict[str, Any]

rlmesh.describe_json(obj, *, kind=None, generated_at=None)

Like describe(), but return the canonical JSON string verbatim.

This is the byte-stable artifact (Rust-serialized); persist it as-is (no json.loads round-trip) when baking into OCI metadata.

Parameters:

• obj (object)

• kind (str | None)

• generated_at (str | None)

Return type:

str

Types

The rlmesh.types module defines the structural protocols that EnvServer accepts and the shared value aliases used by dependency-free clients. The protocols are structural, so any object with the right methods satisfies them; you do not subclass anything. Use them to type-annotate an environment or a value, or to check what EnvServer expects. For authoring an environment against these protocols see Environments.

Public structural protocols and shared value aliases.

class rlmesh.types.EnvLike

Bases: Protocol[EnvObsT, EnvActT]

Structural protocol for a single environment.

property observation_space: SpaceLike[EnvObsT]

Space describing reset and step observations.

property action_space: SpaceLike[EnvActT]

Space describing accepted actions.

__init__(*args, **kwargs)

reset(*, seed=None, options=None)

Reset the environment and return the initial observation.

Parameters:

• seed (int | None)

• options (dict[str, Any] | None)

Return type:

tuple[EnvObsT, dict[str, Any]]

step(action)

Apply one action and return the Gymnasium-style step tuple.

Parameters:

action (EnvActT)

Return type:

tuple[EnvObsT, SupportsFloat, bool, bool, dict[str, Any]]

close()

Release environment resources.

Return type:

None

rlmesh.types.EnvTarget

What a served-model session() (RemoteModel / SandboxModel) accepts as an env: everything in LocalEnvTarget, plus an env client exposing a published env_contract (the contract is sent to the served model at bind).

alias of LocalEnvTarget | HasEnvContract

class rlmesh.types.HasAddress

Bases: Protocol

Anything exposing a dialable endpoint address (e.g. a server handle).

property address: str

The dialable endpoint address.

__init__(*args, **kwargs)

class rlmesh.types.HasEnvContract

Bases: Protocol

An env client exposing a published env_contract (e.g. a served-env handle).

property env_contract: _EnvContract

The env’s published EnvContract.

__init__(*args, **kwargs)

rlmesh.types.InfoDict

User-owned diagnostic grab-bag returned by env reset/step (the gymnasium info norm).

Values are typed Any on purpose: the env author owns what goes in, the SDK never validates it, so strict-mode consumers can write info["success"] > 0.5 without a cast. Contrast Metadata, which the SDK validates and therefore types as object.

alias of dict[str, Any]

rlmesh.types.LocalEnvTarget

What the local drive paths (run()/session()/Model.run) accept as an env: a live env object, an EnvFactory, an object exposing an address, or an address string to dial. Matched structurally, exactly like the runtime’s own checks. A contract-only handle (env_contract without reset/step) cannot be stepped locally, so it is deliberately absent.

alias of SupportsResetStep | SupportsMake | HasAddress | str

rlmesh.types.Metadata

SDK-validated metadata mapping (e.g. adapter tags, describe envelopes).

Values are typed object on purpose: the SDK owns this surface and validates it, so consumers narrow explicitly instead of trusting an Any. Contrast InfoDict, the user-owned grab-bag.

alias of Mapping[str, object]

class rlmesh.types.SpaceLike

Bases: Protocol[SpaceT]

Structural protocol for RLMesh-compatible spaces.

sample()

Return one valid sample from the space.

Return type:

SpaceT

contains(value, /)

Return whether value belongs to the space.

Parameters:

value (Any)

Return type:

bool

seed(seed=None)

Seed the space sampler.

Parameters:

seed (int | None)

Return type:

int | list[int] | dict[str, int] | None

__init__(*args, **kwargs)

rlmesh.types.SpecArg

a ModelSpec, rlmesh.NO_ADAPTER to opt out on a tagged env, or None.

Type:

A model’s adapter spec argument

alias of _ModelSpec | _NoAdapter | None

class rlmesh.types.SupportsMake

Bases: Protocol

An env factory: anything with a make callable (e.g. EnvFactory).

property make: Callable[..., Any]

The factory’s make callable.

__init__(*args, **kwargs)

class rlmesh.types.SupportsResetStep

Bases: Protocol

A live env object: anything with reset and step callables.

property reset: Callable[..., Any]

The env’s reset callable.

property step: Callable[..., Any]

The env’s step callable.

__init__(*args, **kwargs)

class rlmesh.types.VectorEnvLike

Bases: Protocol[BatchActionT, VectorObsT, VectorActT]

Structural protocol for vectorized environments.

__init__(*args, **kwargs)

property num_envs: int

Number of environment instances in the vector.

property single_observation_space: SpaceLike[VectorObsT]

Observation space for one environment in the vector.

property single_action_space: SpaceLike[VectorActT]

Action space for one environment in the vector.

reset(*, seed=None, options=None)

Reset all environments and return batched observations.

Parameters:

• seed (int | None)

• options (dict[str, Any] | None)

Return type:

tuple[object, dict[str, Any]]

step(actions)

Apply a batch of actions and return batched step values.

Parameters:

actions (BatchActionT)

Return type:

tuple[object, object, object, object, dict[str, Any]]

close()

Release vector environment resources.

Return type:

None

rlmesh.types.ViewArg

a View, a shorthand string such as "terminal" or "http:9000", True for the default viewer, or None.

Type:

The view= argument

alias of _View | str | bool | None