API ReferenceFull Library ReferenceNemo GymNemo GymSandboxProviders

nemo_gym.sandbox.providers.base

View as Markdown

Provider-facing sandbox protocol.

Module Contents

Classes

NameDescription
SandboxCreateErrorRaised when a provider cannot create a sandbox.
SandboxCreateVerificationErrorRaised when a newly-created sandbox fails provider readiness checks.
SandboxExecResultProvider-neutral process execution result.
SandboxHandleProvider-neutral handle to a created sandbox.
SandboxProviderRuntime/infra provider contract used by the public sandbox API.
SandboxResourcesProvider-neutral resource request.
SandboxSpecSandbox creation request.
SandboxStatusProvider-neutral sandbox lifecycle status.

Data

ExecResult

API

class nemo_gym.sandbox.providers.base.SandboxCreateError()

Bases: RuntimeError

Raised when a provider cannot create a sandbox.

class nemo_gym.sandbox.providers.base.SandboxCreateVerificationError()

Bases: SandboxCreateError

Raised when a newly-created sandbox fails provider readiness checks.

class nemo_gym.sandbox.providers.base.SandboxExecResult(
    stdout: str | None,
    stderr: str | None,
    return_code: int,
    error_type: str | None = None
)
Dataclass

Provider-neutral process execution result.

return_code is the process exit code when the sandbox actually ran the command. Providers may use a non-process sentinel with error_type set when the sandbox runtime reports an execution failure without a process exit code.

error_type
str | None = None
return_code
int
stderr
str | None
stdout
str | None
class nemo_gym.sandbox.providers.base.SandboxHandle(
    sandbox_id: str,
    provider_name: str,
    raw: typing.Any
)
Dataclass

Provider-neutral handle to a created sandbox.

raw is provider-owned opaque state. Public code should pass it back to the provider through this handle rather than inspecting or mutating it directly.

provider_name
str
sandbox_id
str
class nemo_gym.sandbox.providers.base.SandboxProvider()
Protocol

Runtime/infra provider contract used by the public sandbox API.

name
str
nemo_gym.sandbox.providers.base.SandboxProvider.aclose() -> None
async

Close provider-scoped resources such as SDK clients.

nemo_gym.sandbox.providers.base.SandboxProvider.close(
    handle: nemo_gym.sandbox.providers.base.SandboxHandle
) -> None
async

End the sandbox lifecycle and close provider resources for it.

nemo_gym.sandbox.providers.base.SandboxProvider.create(
    spec: nemo_gym.sandbox.providers.base.SandboxSpec
) -> nemo_gym.sandbox.providers.base.SandboxHandle
async

Create a ready sandbox and return a provider-neutral handle.

Providers must return only after the sandbox is healthy enough to run commands and transfer files. If the sandbox cannot become ready before the configured timeout, providers should raise SandboxCreateError or a provider-specific subclass.

nemo_gym.sandbox.providers.base.SandboxProvider.download_file(
    handle: nemo_gym.sandbox.providers.base.SandboxHandle,
    source_path: str,
    target_path: pathlib.Path
) -> None
async

Download one sandbox file to the local filesystem.

nemo_gym.sandbox.providers.base.SandboxProvider.exec(
    handle: nemo_gym.sandbox.providers.base.SandboxHandle,
    command: str,
    cwd: str | None = None,
    env: dict[str, str] | None = None,
    timeout_s: int | float | None = None,
    user: str | int | None = None
) -> nemo_gym.sandbox.providers.base.SandboxExecResult
async

Run a command inside a sandbox.

nemo_gym.sandbox.providers.base.SandboxProvider.status(
    handle: nemo_gym.sandbox.providers.base.SandboxHandle
) -> nemo_gym.sandbox.providers.base.SandboxStatus
async

Return the current sandbox lifecycle status.

nemo_gym.sandbox.providers.base.SandboxProvider.upload_file(
    handle: nemo_gym.sandbox.providers.base.SandboxHandle,
    source_path: pathlib.Path,
    target_path: str
) -> None
async

Upload one local file into a sandbox.

class nemo_gym.sandbox.providers.base.SandboxResources(
    cpu: float | None = None,
    memory_mib: int | None = None,
    disk_gib: int | None = None,
    gpu: int | None = None,
    gpu_type: str | None = None
)
Dataclass

Provider-neutral resource request.

cpu
float | None = None
disk_gib
int | None = None
gpu
int | None = None
gpu_type
str | None = None
memory_mib
int | None = None
nemo_gym.sandbox.providers.base.SandboxResources.from_mapping(
    resources: collections.abc.Mapping[str, typing.Any] | None
) -> nemo_gym.sandbox.providers.base.SandboxResources
classmethod
class nemo_gym.sandbox.providers.base.SandboxSpec(
    image: str | None = None,
    ttl_s: int | float | None = None,
    ready_timeout_s: int | float | None = None,
    workdir: str | None = None,
    env: dict[str, str] = dict(),
    files: dict[str, str] = dict(),
    metadata: dict[str, str] = dict(),
    resources: nemo_gym.sandbox.providers.base.SandboxResources | collections.abc.Mapping[str, typing.Any] = SandboxResources(),
    entrypoint: list[str] | None = None,
    provider_options: dict[str, typing.Any] = dict()
)
Dataclass

Sandbox creation request.

entrypoint
list[str] | None = None
env
dict[str, str] = field(default_factory=dict)
files
dict[str, str] = field(default_factory=dict)
image
str | None = None
metadata
dict[str, str] = field(default_factory=dict)
provider_options
dict[str, Any] = field(default_factory=dict)
ready_timeout_s
int | float | None = None
resources
SandboxResources | Mapping[str, Any] = field(default_factory=SandboxResources)
ttl_s
int | float | None = None
workdir
str | None = None
nemo_gym.sandbox.providers.base.SandboxSpec.__post_init__() -> None
class nemo_gym.sandbox.providers.base.SandboxStatus

Bases: enum.Enum

Provider-neutral sandbox lifecycle status.

ERROR
= 'error'
RUNNING
= 'running'
STARTING
= 'starting'
STOPPED
= 'stopped'
UNKNOWN
= 'unknown'
nemo_gym.sandbox.providers.base.ExecResult = SandboxExecResult