Skip to navigation

nemo_gym.sandbox.config

View as MarkdownOpen in Claude

Resolve a sandbox provider reference into a provider config.

An agent selects a sandbox by name (sandbox_provider: sandbox). The named block lives in its own provider config file, so swapping providers is swapping a config_paths entry, not editing the agent config:

# nemo_gym/sandbox/providers/opensandbox/configs/opensandbox.yaml
sandbox:
opensandbox:
connection: { ... }
# agent config
sandbox_provider: sandbox

An inline single-key mapping ({provider_name: {...}}) is also accepted for keeping everything in one file.

A block may also carry a reserved default_metadata key. Its entries are merged into the sandbox’s SandboxSpec.metadata as defaults (the agent’s own sandbox_spec.metadata overrides them), so provider-identifying tags live with the provider rather than the agent config:

sandbox:
opensandbox: { connection: { ... } }
default_metadata: { sandbox-api: opensandbox-sdk }

A block may also carry a reserved volume_sources key: a mapping from a Compose volume name (an external: true volume) or a bind-mount host path to the path, under the provider’s shared storage root, that stands in for it when a Compose group starts:

sandbox:
opensandbox: { shared_storage: { host_path: /mnt/shared } }
volume_sources: { pgdata: datasets/pgdata, /var/lib/models: models }

Module Contents

Classes

NameDescription
SandboxConfigThe sandbox_config settings a server applies to every sandbox it starts.

Functions

NameDescription
_candidate_sandbox_namesList top-level config keys that look like named sandbox provider blocks.
_provider_keysReturn the provider keys in a block (everything but reserved keys).
_resolve_blockResolve a sandbox_provider reference or inline mapping to a plain block.
_to_plain_dictReturn a plain dict for mappings, including OmegaConf DictConfig.
resolve_provider_configResolve a sandbox_provider field into a single-key provider config dict.
resolve_provider_metadataReturn a sandbox block’s default_metadata.
resolve_provider_volume_sourcesReturn a sandbox block’s volume_sources: Compose volume names and bind-mount host paths mapped
validate_volume_sourcesvolume_sources as a plain dict of non-empty strings; None is empty. source names the config

Data

SANDBOX_BLOCK_DEFAULT_METADATA_KEY

SANDBOX_BLOCK_RESERVED_KEYS

SANDBOX_BLOCK_VOLUME_SOURCES_KEY

API

class nemo_gym.sandbox.config.SandboxConfig()

Bases: BaseModel

The sandbox_config settings a server applies to every sandbox it starts.

Servers that need more, such as a fixed image, subclass it with their own fields.

env
dict[str, str] = Field(default_factory=dict)
metadata
dict[str, str] = Field(default_factory=dict)
model_config
= ConfigDict(extra='forbid')
provider_options
dict[str, Any] = Field(default_factory=dict)
ready_timeout_s
int | float | None = None
resources
dict[str, Any] = Field(default_factory=dict)
ttl_s
int | float | None = None
nemo_gym.sandbox.config.SandboxConfig._known_resources(
resources: dict[str, typing.Any]
) -> dict[str, typing.Any]
classmethod
nemo_gym.sandbox.config.SandboxConfig.spec(
sandbox_provider: str | collections.abc.Mapping[str, typing.Any],
image: str | None,
workdir: str | None,
metadata: collections.abc.Mapping[str, str] | None = None,
files: collections.abc.Mapping[str, str | bytes] | None = None,
named_configs: collections.abc.Mapping[str, typing.Any] | None = None

Build the spec of one sandbox; metadata adds to the provider’s and the config’s metadata.

nemo_gym.sandbox.config._candidate_sandbox_names(
named_configs: collections.abc.Mapping[str, typing.Any] | None
) -> list[str]

List top-level config keys that look like named sandbox provider blocks.

nemo_gym.sandbox.config._provider_keys(
block: collections.abc.Mapping[str, typing.Any]
) -> list[str]

Return the provider keys in a block (everything but reserved keys).

nemo_gym.sandbox.config._resolve_block(
sandbox_provider: str | collections.abc.Mapping[str, typing.Any],
named_configs: collections.abc.Mapping[str, typing.Any] | None
) -> tuple[dict[str, typing.Any], str]

Resolve a sandbox_provider reference or inline mapping to a plain block.

nemo_gym.sandbox.config._to_plain_dict(
value: typing.Any
) -> typing.Any

Return a plain dict for mappings, including OmegaConf DictConfig.

nemo_gym.sandbox.config.resolve_provider_config(
sandbox_provider: str | collections.abc.Mapping[str, typing.Any],
named_configs: collections.abc.Mapping[str, typing.Any] | None = None
) -> dict[str, typing.Any]

Resolve a sandbox_provider field into a single-key provider config dict.

Parameters:

sandbox_provider
str | Mapping[str, Any]

Either the name of a top-level sandbox config block (resolved from named_configs) or an inline single-key provider mapping of the form {provider_name: {...}}.

named_configs
Mapping[str, Any] | NoneDefaults to None

Mapping of top-level config name to config block, typically the merged global config dict. Required when sandbox_provider is a name reference.

Returns: dict[str, Any]

A plain {provider_name: provider_kwargs} dict suitable for

Raises:

  • TypeError: If sandbox_provider is neither a string nor a mapping.
  • ValueError: If a named reference cannot be found, or if the block does not hold exactly one provider key.
nemo_gym.sandbox.config.resolve_provider_metadata(
sandbox_provider: str | collections.abc.Mapping[str, typing.Any],
named_configs: collections.abc.Mapping[str, typing.Any] | None = None
) -> dict[str, typing.Any]

Return a sandbox block’s default_metadata.

These are provider-contributed defaults to merge into SandboxSpec.metadata. Returns an empty dict when the block has no default_metadata key. See resolve_provider_config for argument semantics.

nemo_gym.sandbox.config.resolve_provider_volume_sources(
sandbox_provider: str | collections.abc.Mapping[str, typing.Any],
named_configs: collections.abc.Mapping[str, typing.Any] | None = None
) -> dict[str, str]

Return a sandbox block’s volume_sources: Compose volume names and bind-mount host paths mapped to paths under the provider’s shared storage root.

Returns an empty dict when the block has no volume_sources key. Keys and values must be non-empty strings. See resolve_provider_config for argument semantics.

nemo_gym.sandbox.config.validate_volume_sources(
sources: typing.Any,
source: str = 'the sandbox block'
) -> dict[str, str]

volume_sources as a plain dict of non-empty strings; None is empty. source names the config in error messages.

nemo_gym.sandbox.config.SANDBOX_BLOCK_DEFAULT_METADATA_KEY = 'default_metadata'
nemo_gym.sandbox.config.SANDBOX_BLOCK_RESERVED_KEYS = frozenset({SANDBOX_BLOCK_DEFAULT_METADATA_KEY, SANDBOX_BLOCK_VOLUME_SOURCES_KEY}...
nemo_gym.sandbox.config.SANDBOX_BLOCK_VOLUME_SOURCES_KEY = 'volume_sources'