Skip to navigation

nemo_gym.server_runtime.episode_tools

View as MarkdownOpen in Claude

Tools that an Environment Server serves to the agent for one episode.

Module Contents

Classes

NameDescription
EpisodeToolsetThe tools of one episode.
ToolArgumentsErrorThe agent sent arguments that the tool does not accept. The message is shown to the agent.
ToolCallRecordOne tool call of an episode, in the order the server ran it.
ToolResultWhat one tool call returns to the agent. is_error marks an error the agent should see and handle.
ToolSpecOne tool as the agent sees it.
TypedToolsetAn EpisodeToolset built from the @episode_tool methods of one object, such as an episode’s state.

Functions

NameDescription
_tool_tableThe arguments model and spec of each @episode_tool method of a class.
episode_toolMark an async method as a tool for TypedToolset. Its docstring is the tool’s description.

Data

TOOL_NAME_PATTERN

_EPISODE_TOOL_ATTRIBUTE

_POSITIONAL

API

class nemo_gym.server_runtime.episode_tools.EpisodeToolset()
Protocol

The tools of one episode.

specs is fixed for the episode. call runs one tool by name; the server checks the name against specs first. It raises ToolArgumentsError for arguments the tool does not accept.

nemo_gym.server_runtime.episode_tools.EpisodeToolset.call(
name: str,
arguments: dict[str, typing.Any]
async
nemo_gym.server_runtime.episode_tools.EpisodeToolset.specs() -> collections.abc.Sequence[nemo_gym.server_runtime.episode_tools.ToolSpec]
class nemo_gym.server_runtime.episode_tools.ToolArgumentsError()

Bases: ValueError

The agent sent arguments that the tool does not accept. The message is shown to the agent.

class nemo_gym.server_runtime.episode_tools.ToolCallRecord()

Bases: BaseModel

One tool call of an episode, in the order the server ran it.

arguments
JsonValue
call_id
str | None = None
duration_seconds
float
is_error
bool
model_config
= ConfigDict(extra='forbid')
name
str
output
JsonValue
class nemo_gym.server_runtime.episode_tools.ToolResult()

Bases: BaseModel

What one tool call returns to the agent. is_error marks an error the agent should see and handle.

is_error
bool = False
model_config
= ConfigDict(extra='forbid')
output
JsonValue
class nemo_gym.server_runtime.episode_tools.ToolSpec()

Bases: BaseModel

One tool as the agent sees it.

description
str = Field(min_length=1)
model_config
= ConfigDict(extra='forbid')
name
str = Field(pattern=TOOL_NAME_PATTERN)
parameters
dict[str, JsonValue]
nemo_gym.server_runtime.episode_tools.ToolSpec.function_tool() -> openai.types.responses.FunctionToolParam

Declare this tool to the model, for an agent that calls it over direct HTTP.

The parameters are the full schema, with its $defs. The declaration is not strict, because a strict schema must make every property required.

nemo_gym.server_runtime.episode_tools.ToolSpec.validate_object_schema(
parameters: dict[str, pydantic.JsonValue]
) -> dict[str, pydantic.JsonValue]
classmethod
class nemo_gym.server_runtime.episode_tools.TypedToolset(
owner: object
)

An EpisodeToolset built from the @episode_tool methods of one object, such as an episode’s state.

Each method takes one Pydantic model of arguments and returns a ToolResult, a Pydantic model or a JSON value. The tool’s name is the method’s name, and its parameters are the model’s JSON schema.

_tools
= _tool_table(type(owner))
nemo_gym.server_runtime.episode_tools.TypedToolset.call(
name: str,
arguments: dict[str, typing.Any]
async
nemo_gym.server_runtime.episode_tools.TypedToolset.specs() -> list[nemo_gym.server_runtime.episode_tools.ToolSpec]
nemo_gym.server_runtime.episode_tools._tool_table(
owner_type: type
) -> dict[str, tuple[type[pydantic.BaseModel], nemo_gym.server_runtime.episode_tools.ToolSpec]]

The arguments model and spec of each @episode_tool method of a class.

They depend only on the class, so each class builds them once, not once for each episode.

nemo_gym.server_runtime.episode_tools.episode_tool(
method: collections.abc.Callable[[Any, Any], collections.abc.Awaitable[typing.Any]]
) -> collections.abc.Callable[[Any, Any], collections.abc.Awaitable[typing.Any]]

Mark an async method as a tool for TypedToolset. Its docstring is the tool’s description.

nemo_gym.server_runtime.episode_tools.TOOL_NAME_PATTERN = '^[A-Za-z0-9][A-Za-z0-9._-]*$'
nemo_gym.server_runtime.episode_tools._EPISODE_TOOL_ATTRIBUTE = '__nemo_gym_episode_tool__'
nemo_gym.server_runtime.episode_tools._POSITIONAL = (inspect.Parameter.POSITIONAL_ONLY, inspect.Parameter.POSITIONAL_OR_KEYWORD)