> This page is for version Main (default).
> For other versions, use one of these documentation indexes:
> - Main (default): https://docs.nvidia.com/nemo/gym/main/llms.txt
> - 0.7.0: https://docs.nvidia.com/nemo/gym/v0.7.0/llms.txt
> - 0.6.0: https://docs.nvidia.com/nemo/gym/v0.6.0/llms.txt
> - 0.5.1: https://docs.nvidia.com/nemo/gym/v0.5.1/llms.txt
> - 0.5.0: https://docs.nvidia.com/nemo/gym/v0.5.0/llms.txt
> - 0.4.0: https://docs.nvidia.com/nemo/gym/v0.4.0/llms.txt
> - 0.3.0: https://docs.nvidia.com/nemo/gym/v0.3.0/llms.txt
> - 0.2.1: https://docs.nvidia.com/nemo/gym/v0.2.1/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nvidia.com/nemo/gym/llms.txt.

# nemo_gym.server_runtime.episode_tools

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

## Module Contents

### Classes

| Name                                                                              | Description                                                                                           |
| --------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| [`EpisodeToolset`](#nemo_gym-server_runtime-episode_tools-EpisodeToolset)         | The tools of one episode.                                                                             |
| [`ToolArgumentsError`](#nemo_gym-server_runtime-episode_tools-ToolArgumentsError) | The agent sent arguments that the tool does not accept. The message is shown to the agent.            |
| [`ToolCallRecord`](#nemo_gym-server_runtime-episode_tools-ToolCallRecord)         | One tool call of an episode, in the order the server ran it.                                          |
| [`ToolResult`](#nemo_gym-server_runtime-episode_tools-ToolResult)                 | What one tool call returns to the agent. `is_error` marks an error the agent should see and handle.   |
| [`ToolSpec`](#nemo_gym-server_runtime-episode_tools-ToolSpec)                     | One tool as the agent sees it.                                                                        |
| [`TypedToolset`](#nemo_gym-server_runtime-episode_tools-TypedToolset)             | An `EpisodeToolset` built from the `@episode_tool` methods of one object, such as an episode's state. |

### Functions

| Name                                                                  | Description                                                                                 |
| --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| [`_tool_table`](#nemo_gym-server_runtime-episode_tools-_tool_table)   | The arguments model and spec of each `@episode_tool` method of a class.                     |
| [`episode_tool`](#nemo_gym-server_runtime-episode_tools-episode_tool) | Mark an async method as a tool for `TypedToolset`. Its docstring is the tool's description. |

### Data

[`TOOL_NAME_PATTERN`](#nemo_gym-server_runtime-episode_tools-TOOL_NAME_PATTERN)

[`_EPISODE_TOOL_ATTRIBUTE`](#nemo_gym-server_runtime-episode_tools-_EPISODE_TOOL_ATTRIBUTE)

[`_POSITIONAL`](#nemo_gym-server_runtime-episode_tools-_POSITIONAL)

### API

```python
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.

```python
nemo_gym.server_runtime.episode_tools.EpisodeToolset.call(
    name: str,
    arguments: dict[str, typing.Any]
) -> nemo_gym.server_runtime.episode_tools.ToolResult
```

async

```python
nemo_gym.server_runtime.episode_tools.EpisodeToolset.specs() -> collections.abc.Sequence[nemo_gym.server_runtime.episode_tools.ToolSpec]
```

```python
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.

```python
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`

---

```python
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`

---

```python
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]`

---

```python
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.

```python
nemo_gym.server_runtime.episode_tools.ToolSpec.validate_object_schema(
    parameters: dict[str, pydantic.JsonValue]
) -> dict[str, pydantic.JsonValue]
```

classmethod

```python
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))`

---

```python
nemo_gym.server_runtime.episode_tools.TypedToolset.call(
    name: str,
    arguments: dict[str, typing.Any]
) -> nemo_gym.server_runtime.episode_tools.ToolResult
```

async

```python
nemo_gym.server_runtime.episode_tools.TypedToolset.specs() -> list[nemo_gym.server_runtime.episode_tools.ToolSpec]
```

```python
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.

```python
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.

```python
nemo_gym.server_runtime.episode_tools.TOOL_NAME_PATTERN = '^[A-Za-z0-9][A-Za-z0-9._-]*$'
```

```python
nemo_gym.server_runtime.episode_tools._EPISODE_TOOL_ATTRIBUTE = '__nemo_gym_episode_tool__'
```

```python
nemo_gym.server_runtime.episode_tools._POSITIONAL = (inspect.Parameter.POSITIONAL_ONLY, inspect.Parameter.POSITIONAL_OR_KEYWORD)
```