Crate rlmesh 

Rust SDK for RLMesh model-environment evaluation workflows.

RLMesh connects a model to an environment over gRPC. This crate is the Rust facade over the transport, wire, and runtime crates. Python users should start with the rlmesh Python package; use this crate when serving or driving environments and models from Rust.

The two roles

Most deployments have one environment server and one model worker.

• Serve an environment. Implement Env for one environment and host it with EnvServer. Implement VectorEnv and use VectorEnvServer only for an explicit local batching fast path.

• Drive or serve a model. Implement ModelHandler, then run it against a remote environment with ModelWorker::run_local or serve it as an endpoint with ModelWorker::serve.

Use RemoteEnv when you want to step an environment server directly.

Bind-first servers

EnvServer::bind and ModelWorker::bind_async reserve the socket before serving and return the resolved address, including OS-assigned port 0. This avoids bind-drop-rebind races and poll-connect loops. Use the one-shot serve/serve_async methods when you do not need that address first.

Errors

Fallible operations return Result (alias for Result<T, Error>). Error separates transport/server faults from two domain failures: Error::Environment (carrying an ErrorCode) and Error::Model (a failure your ModelHandler raised). Both carry an is_recoverable flag surfaced by Error::is_recoverable.

Implementing the traits

Env, VectorEnv, and ModelHandler are async-trait traits, so every impl carries #[rlmesh::async_trait]: this crate re-exports the macro as async_trait (also in the prelude), already at the version the traits were desugared with, so nothing beyond rlmesh needs to be in your Cargo.toml.

Example: serve an environment

use rlmesh::prelude::*;

struct MyEnv {
    observation_space: SpaceSpec,
    action_space: SpaceSpec,
    contract: EnvContract,
}

#[rlmesh::async_trait]
impl Env for MyEnv {
    fn observation_space(&self) -> &SpaceSpec { &self.observation_space }
    fn action_space(&self) -> &SpaceSpec { &self.action_space }
    fn env_contract(&self) -> &EnvContract { &self.contract }

    // Env methods use the two-arg std::result::Result form.
    async fn reset(&mut self, _req: ResetRequest)
        -> Result<ResetResult, EnvRuntimeError>
    {
        Ok(ResetResult::default())
    }
    async fn step(&mut self, _req: StepRequest)
        -> Result<StepResult, EnvRuntimeError>
    {
        Ok(StepResult::default())
    }
    async fn render(&mut self, _req: RenderRequest)
        -> Result<RenderResult, EnvRuntimeError>
    {
        Ok(RenderResult::default())
    }
    async fn close(&mut self, _req: CloseRequest)
        -> Result<CloseResult, EnvRuntimeError>
    {
        Ok(CloseResult::default())
    }
}

// Bind first when the caller needs the resolved address.
let bound = EnvServer::new(env).bind(BindAddress::parse("tcp://127.0.0.1:0")?).await?;
println!("listening on {}", bound.local_addr());
bound.serve().await

Example: drive a model against that environment

use rlmesh::prelude::*;

struct MyModel;

#[rlmesh::async_trait]
impl ModelHandler for MyModel {
    async fn predict(&mut self, _obs: ModelObservation)
        -> rlmesh::Result<Vec<SpaceValue>>
    {
        // Read `_obs.decoded_lanes()`, run your policy, return one action per lane.
        Ok(vec![SpaceValue::Discrete(0)])
    }
}

// Drive a running env server for 100 episodes.
let report = ModelWorker::new(MyModel)
    .run_local_async(RunLocalOptions::parse("tcp://127.0.0.1:50051")?.for_episodes(100))
    .await?;
println!("ran {} steps", report.total_steps);
Ok(())

Re-exports

pub use env::BoundEnvServer;

pub use env::Env;

pub use env::EnvServer;

pub use env::EpisodeMetadata;

pub use env::RemoteEnv;

pub use env::RemoteVectorEnv;

pub use env::VectorCloseResult;

pub use env::VectorEnv;

pub use env::VectorEnvServer;

pub use env::VectorResetRequest;

pub use env::VectorResetResult;

pub use env::VectorStepRequest;

pub use env::VectorStepResult;

pub use model::AdaptedModelHandler;

pub use model::BoundModelServer;

pub use model::EnvClientRuntimeEnv;

pub use model::EpisodeInfo;

pub use model::HeldState;

pub use model::HistoryFrame;

pub use model::HistoryNeeds;

pub use model::ModelHandler;

pub use model::ModelHandlerRuntimeModel;

pub use model::ModelObservation;

pub use model::ModelRouteContext;

pub use model::ModelRouteSetup;

pub use model::ModelWorker;

pub use model::PredictFn;

pub use model::PredictFrames;

pub use model::RemoteModel;

pub use model::ResolveOptions;

pub use model::RouteConfig;

pub use model::RouteNeeds;

pub use model::RouteResolver;

pub use model::RunLocalOptions;

pub use model::ServeModelOptions;

pub use model::predict_seed;

pub use rlmesh_runtime::telemetry;

pub use rlmesh_runtime::ActionReceivedEvent;

pub use rlmesh_runtime::EpisodeCompletedEvent;

pub use rlmesh_runtime::EpisodeStartedEvent;

pub use rlmesh_runtime::HookError;

pub use rlmesh_runtime::NoopRuntimeHooks;

pub use rlmesh_runtime::ObservationEmittedEvent;

pub use rlmesh_runtime::RuntimeHooks;

pub use rlmesh_runtime::StepCompletedEvent;

pub use rlmesh_runtime::ENV_RESET_OPTIONS_KEY;

pub use rlmesh_runtime::PeerCeiling;

pub use rlmesh_runtime::RuntimeReport;

pub use rlmesh_runtime::TRIAL_INDEX_OPTION;

pub use serve_options::ServeOptions;

Modules

env

Environment traits, requests, the EnvServer, and remote clients.

model

Model-side API: the ModelHandler trait, the ModelWorker that drives or serves it, and the observation/route/lifecycle types a handler receives.

prelude

Common imports for RLMesh users.

serve_options

Transport serve options shared by the env and model servers.

spaces

Curated re-exports of the rlmesh_spaces space-system types.

Structs

CancellationToken

A token which can be used to signal a cancellation request to one or more tasks.

CloseRequest

CloseResult

EndpointPhases

The endpoint-local split of JoinResponse.endpoint_total_ns (ns), plus the pre-handler wait and slot depth a pipelining model endpoint reports.

EnvContract

EnvironmentError

A failure reported by the environment when serving a request.

ModelError

A failure originating from a user-implemented model handler.

RenderFrame

RenderRequest

RenderResult

ResetRequest

ResetResult

SpaceSpec

StepRequest

StepResult

Enums

BindAddress

A server-side address to bind a listener to.

ConnectAddress

A client-side address for connecting to a running server.

EnvRuntimeError

Error

The error type for every fallible operation in this crate.

ErrorCode

Classifies an EnvironmentError reported by an environment.

SpaceValue

Runtime value carried by an RLMesh space.

Constants

CURRENT_WORKFLOW_EDITION

Current workflow semantics edition.

Functions

parse_declared_edition

Resolve a declared edition — a participant’s WANT — to the arm it names, or say why this build cannot declare it.

remove_stale_socket

Remove a leftover Unix-domain socket file before binding.

Type Aliases

Result

The result type used throughout this crate: Result<T, Error>.

Attribute Macros

async_trait