nemo_gym.base_resources_server

Module Contents

Classes

Name	Description
`BaseMultiRewardVerifyResponse`	Base verify response for environments with multiple reward objectives.
`BaseResourcesServer`	-
`BaseResourcesServerConfig`	-
`BaseRunRequest`	-
`BaseSeedSessionRequest`	-
`BaseSeedSessionResponse`	-
`BaseVerifyRequest`	-
`BaseVerifyResponse`	-
`MCPServerMetadata`	Metadata returned from /seed_session for per-rollout Gym MCP access.
`ResourcesCloseSessionRequest`	Close resources-server state.
`ResourcesCloseSessionResponse`	Confirm resources-server state was closed.
`ResourcesSeedSessionRequest`	Idempotently initialize resources state under a caller-assigned identifier.
`ResourcesSeedSessionResponse`	Confirm resources state and return optional agent access.
`ResourcesVerifyRequest`	Carry typed environment output to a resources server.
`ReverifyMode`	-
`SimpleResourcesServer`	-

Functions

Name	Description
`normalize_tool_name`	Map a trajectory tool-call name to the server’s bare tool name.

Data

NEMO_GYM_MCP_METADATA_KEY

NEMO_GYM_MCP_SESSION_TOKEN_HEADER

RESERVED_MCP_TOOL_NAMES

VerificationInputT

_MCP_TOKEN_SALT

API

class nemo_gym.base_resources_server.BaseMultiRewardVerifyResponse()

Bases: BaseVerifyResponse

Base verify response for environments with multiple reward objectives.

Subclass this response instead of declaring reward_components on an environment-specific BaseVerifyResponse subclass. The mapping is required, and its objective keys should remain consistent across every task in the environment.

Set the inherited reward to the scalar aggregate expected by single-reward consumers. To include individual objectives in aggregate metrics, also expose them as top-level numeric fields because metrics do not descend into this mapping. See resources_servers/example_tool_call_multireward for a complete example.

reward_components

dict[str, float]

class nemo_gym.base_resources_server.BaseResourcesServer()

Bases: BaseServer

config

BaseResourcesServerConfig

class nemo_gym.base_resources_server.BaseResourcesServerConfig()

Bases: BaseRunServerInstanceConfig

REVERIFY_MODE

ReverifyMode = ReverifyMode.UNKNOWN

expose_tools_over_mcp

bool = False

class nemo_gym.base_resources_server.BaseRunRequest()

Bases: BaseModel

capture_rollout_id

Optional[str]

model_config

= ConfigDict(populate_by_name=True)

responses_create_params

NeMoGymResponseCreateParamsNonStreaming

class nemo_gym.base_resources_server.BaseSeedSessionRequest()

Bases: BaseModel

class nemo_gym.base_resources_server.BaseSeedSessionResponse()

Bases: BaseModel

class nemo_gym.base_resources_server.BaseVerifyRequest()

Bases: BaseRunRequest

response

NeMoGymResponse

class nemo_gym.base_resources_server.BaseVerifyResponse()

Bases: BaseVerifyRequest

failure_kind

Optional[str]

failure_reason

Optional[str] = None

mask_sample

bool

reward

float

nemo_gym.base_resources_server.BaseVerifyResponse._warn_on_unregistered_failure_kind(
    value: typing.Optional[str]
) -> typing.Optional[str]

classmethod

Producers learn about a name outside the vocabulary without losing the failure.

Validation warns rather than rejects: an unregistered kind is a migration signal, and dropping the response over it would replace a visible wrong label with an invisible lost failure.

class nemo_gym.base_resources_server.MCPServerMetadata()

Bases: BaseModel

Metadata returned from /seed_session for per-rollout Gym MCP access.

headers

dict[str, str]

server_name

str

transport

str = 'http'

url_path

str = '/mcp'

class nemo_gym.base_resources_server.ResourcesCloseSessionRequest()

Bases: BaseModel

Close resources-server state.

episode_id

EpisodeId

model_config

= ConfigDict(extra='forbid')

resources_session_id

str

class nemo_gym.base_resources_server.ResourcesCloseSessionResponse()

Bases: BaseModel

Confirm resources-server state was closed.

model_config

= ConfigDict(extra='forbid')

resources_session_id

str

class nemo_gym.base_resources_server.ResourcesSeedSessionRequest()

Bases: BaseModel

Idempotently initialize resources state under a caller-assigned identifier.

Repeating the same identifier and episode must return the existing session. Closing an unknown identifier must prevent a racing seed from creating it later. External resources should use provider TTLs when available. Current process-local session records may remain until the server shuts down.

episode_id

EpisodeId

model_config

= ConfigDict(extra='forbid')

resources_session_id

str = Field(min_length=1)

task_data

dict[str, JsonValue]

task_id

TaskId

class nemo_gym.base_resources_server.ResourcesSeedSessionResponse()

Bases: BaseModel

Confirm resources state and return optional agent access.

model_config

= ConfigDict(extra='forbid')

resources_session_id

str

resources_tools

MCPServerMetadata | None = None

sandbox_access

SandboxAccess | None = None

class nemo_gym.base_resources_server.ResourcesVerifyRequest()

Bases: BaseModel, Generic[VerificationInputT]

Carry typed environment output to a resources server.

episode_id

EpisodeId

model_config

= ConfigDict(extra='forbid')

task_id

TaskId

verification_input

VerificationInputT

class nemo_gym.base_resources_server.ReverifyMode

Bases: enum.Enum

STATELESS

= 'stateless'

UNKNOWN

= 'unknown'

UNSUPPORTED

= 'unsupported'

class nemo_gym.base_resources_server.SimpleResourcesServer()

Bases: BaseResourcesServer, AggregateMetricsMixin, SimpleServer

config

BaseResourcesServerConfig

nemo_gym.base_resources_server.SimpleResourcesServer.aggregate_metrics(
    body: nemo_gym.config_types.AggregateMetricsRequest
) -> nemo_gym.config_types.AggregateMetrics

async

Compute aggregate metrics from verify responses.

RewardProfiler provides baseline stats. Override compute_metrics(), compute_repeat_metrics(), and/or get_key_metrics() for benchmark-specific customization.

nemo_gym.base_resources_server.SimpleResourcesServer.close_resources_session(
    body: nemo_gym.base_resources_server.ResourcesCloseSessionRequest
) -> nemo_gym.base_resources_server.ResourcesCloseSessionResponse

async

Close state an Environment Server seeded; the default keeps none.

Served at /close_session. Servers that keep per-rollout state override this method, and may accept other close bodies by overriding it with a different signature. The name differs from the close_session helpers some servers already define for their own state.

An override must:

succeed when the session is already closed or was never seeded;
keep a seed that arrives after the close from creating the session again;
raise when releasing fails rather than recording the session as closed, so the caller can retry.

The default seed does not tie the session cookie to resources_session_id. A server that keys state by the cookie’s SESSION_ID_KEY releases it by that key, from request.session, or sets request.session[SESSION_ID_KEY] = body.resources_session_id in its own seed.

nemo_gym.testing.session_conformance.check_resources_session_contract checks these rules from a server’s tests.

nemo_gym.base_resources_server.SimpleResourcesServer.get_reverify_mode() -> nemo_gym.base_resources_server.ReverifyMode

async

nemo_gym.base_resources_server.SimpleResourcesServer.mcp_allowed_tools_for_session(
    seed_body: dict[str, typing.Any]
) -> typing.Optional[list[str]]

Per-session tool restriction: return the tool names allowed for this rollout’s MCP token, or None (the default) for unrestricted. seed_body is the JSON body POSTed to /seed_session, or its task_data when an Environment Server seeds the session.

nemo_gym.base_resources_server.SimpleResourcesServer.mcp_tools(
    harvested: list[nemo_gym.mcp_auto_exposure.MCPTool],
    catchall: typing.Optional[typing.Any]
) -> typing.Optional[list[nemo_gym.mcp_auto_exposure.MCPTool]]

Return the MCP tools to expose (default: the auto-harvested typed POST routes).

Override to exclude (filter harvested), add catch-all-backed tools (harvested + [catchall.tool(…)]), or disable (return None). ‘catchall’ is None unless the server has one parameterized catch-all route.

nemo_gym.base_resources_server.SimpleResourcesServer.normalize_tool_name(
    name: str
) -> str

Strip this server’s MCP namespace from a trajectory tool-call name (see module function).

nemo_gym.base_resources_server.SimpleResourcesServer.seed_session(
    body: nemo_gym.base_resources_server.ResourcesSeedSessionRequest | nemo_gym.base_resources_server.BaseSeedSessionRequest
) -> nemo_gym.base_resources_server.ResourcesSeedSessionResponse | nemo_gym.base_resources_server.BaseSeedSessionResponse

async

Seed per-rollout state; the default keeps none.

An Environment Server seeds with a ResourcesSeedSessionRequest and gets its caller-assigned resources_session_id back. An Agent’s /run seeds with its legacy body and gets an empty response. Servers that keep per-rollout state override this method.

nemo_gym.base_resources_server.SimpleResourcesServer.setup_webserver() -> fastapi.FastAPI

nemo_gym.base_resources_server.SimpleResourcesServer.verify(
    body: nemo_gym.base_resources_server.BaseVerifyRequest
) -> nemo_gym.base_resources_server.BaseVerifyResponse

asyncabstract

nemo_gym.base_resources_server.normalize_tool_name(
    name: str,
    server_name: typing.Optional[str] = None
) -> str

Map a trajectory tool-call name to the server’s bare tool name.

HTTP-driven agents record bare tool names (“email_reply_email”); MCP-native agents (e.g. Claude Code) record them namespaced per server (“mcp__workplace_assistant__email_reply_email”). Verifiers compare trajectory names against dataset/ground-truth vocabulary, so names are normalized before verify sees them and rollouts score identically on both transports. Non-namespaced names pass through unchanged. When server_name is given, only that server’s prefix is stripped (robust to tool names that themselves contain double underscores). This runs only for servers exposed over MCP and mirrors how MCP clients namespace tool names, so a real tool that is itself named mcp__<server>__x being stripped is accepted.

nemo_gym.base_resources_server.NEMO_GYM_MCP_METADATA_KEY = 'mcp'

nemo_gym.base_resources_server.NEMO_GYM_MCP_SESSION_TOKEN_HEADER = 'X-NeMo-Gym-Session-Token'

nemo_gym.base_resources_server.RESERVED_MCP_TOOL_NAMES = frozenset({'verify', 'seed_session', 'close_session', 'aggregate_metrics', 'mcp'...

nemo_gym.base_resources_server.VerificationInputT = TypeVar('VerificationInputT')

nemo_gym.base_resources_server._MCP_TOKEN_SALT = 'nemo-gym-mcp-session-token'