nemo_gym.sandbox.attribution

Automatic job attribution (team / user / workload / run) for sandbox metadata.

Sandbox providers merge these keys into every sandbox’s metadata so cluster operators can attribute running sandboxes to the team, user, and workload that created them (on OpenSandbox, metadata becomes queryable Kubernetes labels on the sandbox). Each field resolves from explicit configuration first, then NEMO_GYM_* environment variables, then Slurm job environment variables, then (for user only) the OS login name and (for workload) the server instance’s config path. Fields that cannot be resolved are omitted rather than guessed.

run identifies one launch of the creating process so a run’s sandboxes can be listed or garbage-collected exactly, even when the same user runs the same workload twice. It resolves from explicit configuration, then NEMO_GYM_RUN_ID, then a per-process generated id.

Module Contents

Functions

Name	Description
`_detect_user`	-
`_first_env`	-
`log_attribution_once`	Log the resolved attribution metadata once per process.
`resolve_attribution`	Resolve `team` / `user` / `workload` attribution metadata.
`resolve_run_id`	Resolve the `run` attribution id: explicit value, then `NEMO_GYM_RUN_ID`,

Data

IGNORED_LOGIN_NAMES

_logged_attribution

_process_run_id

API

nemo_gym.sandbox.attribution._detect_user(
    environ: collections.abc.Mapping[str, str]
) -> str | None

nemo_gym.sandbox.attribution._first_env(
    environ: collections.abc.Mapping[str, str],
    names: tuple[str, ...]
) -> str | None

nemo_gym.sandbox.attribution.log_attribution_once(
    metadata: collections.abc.Mapping[str, str]
) -> None

Log the resolved attribution metadata once per process.

The generated run id only exists in this process, so surfacing it in the logs is what lets operators later filter or garbage-collect this run’s sandboxes.

nemo_gym.sandbox.attribution.resolve_attribution(
    team: str | None = None,
    user: str | None = None,
    workload: str | None = None,
    environ: collections.abc.Mapping[str, str] | None = None
) -> dict[str, str]

Resolve team / user / workload attribution metadata.

Parameters:

team

str | NoneDefaults to None

Explicit team; falls back to NEMO_GYM_TEAM, then SLURM_JOB_ACCOUNT.

user

str | NoneDefaults to None

Explicit user; falls back to NEMO_GYM_USER, then SLURM_JOB_USER, then the OS login name (root is ignored — containers run as root by default, so it attributes the image, not a person).

workload

str | NoneDefaults to None

Explicit workload; falls back to NEMO_GYM_WORKLOAD, then SLURM_JOB_NAME, then NEMO_GYM_CONFIG_PATH (the server instance name the gym CLI sets on every server process it spawns).

environ

Mapping[str, str] | NoneDefaults to None

Environment mapping override, for testing. Defaults to os.environ.

Returns: dict[str, str]

A dict with only the resolved keys among team, user, and workload.

nemo_gym.sandbox.attribution.resolve_run_id(
    run: str | None = None,
    environ: collections.abc.Mapping[str, str] | None = None
) -> str

Resolve the run attribution id: explicit value, then NEMO_GYM_RUN_ID, then an id generated once per process.

Unlike :func:resolve_attribution fields, run is always resolvable. It scopes sandboxes to one launch of the creating process, so an interrupted run’s sandboxes can be listed and cleaned up exactly (team / user / workload cannot distinguish two runs of the same workload by the same user).

nemo_gym.sandbox.attribution.IGNORED_LOGIN_NAMES = frozenset({'root'})

nemo_gym.sandbox.attribution.LOGGER = logging.getLogger(__name__)

nemo_gym.sandbox.attribution.RUN_ENV_VARS = ('NEMO_GYM_RUN_ID',)

nemo_gym.sandbox.attribution.RUN_KEY = 'run'

nemo_gym.sandbox.attribution.TEAM_ENV_VARS = ('NEMO_GYM_TEAM', 'SLURM_JOB_ACCOUNT')

nemo_gym.sandbox.attribution.TEAM_KEY = 'team'

nemo_gym.sandbox.attribution.USER_ENV_VARS = ('NEMO_GYM_USER', 'SLURM_JOB_USER')

nemo_gym.sandbox.attribution.USER_KEY = 'user'

nemo_gym.sandbox.attribution.WORKLOAD_ENV_VARS = ('NEMO_GYM_WORKLOAD', 'SLURM_JOB_NAME', 'NEMO_GYM_CONFIG_PATH')

nemo_gym.sandbox.attribution.WORKLOAD_KEY = 'workload'

nemo_gym.sandbox.attribution._logged_attribution = False

nemo_gym.sandbox.attribution._process_run_id: str | None = None