nemoguardrails.guardrails.tool_schema | NVIDIA NeMo Guardrails Library Developer Guide

Internal tool types for IORails tool-calling rails.

These engine-internal dataclasses are the normalized, provider-neutral shape the tool rails validate against. They are NOT part of the public API and NOT carried on GenerationOptions: the request surface stays the provider-native llm_params block, which ModelEngine parses into a Toolset (and incoming tool results into ToolResult objects) per inference call.

Tool is a declared tool definition (what the caller offers); ToolCall (in nemoguardrails.types) is an invocation the model emitted. Field names are provider-neutral so the per-provider adapters all produce the same shape: arguments_schema is OpenAI parameters / Anthropic input_schema / Gemini parameters; ToolResult.call_id is the OpenAI tool_call_id / Responses call_id / Anthropic tool_use_id / Gemini function-call id. OpenAI Chat Completions is the engine implemented today.

Module Contents

Classes

Name	Description
`Tool`	A declared tool definition the caller offered to the model.
`ToolExchange`	One assistant turn’s tool calls paired with the tool results that answer them.
`ToolResult`	A normalized tool result extracted from incoming messages by the engine.
`Toolset`	The set of tools declared on a request, indexed by tool key.

Functions

Name	Description
`_no_arguments_reason`	Block reason for a tool that accepts no arguments, or `None` when the call is allowed.
`_schema_accepts_no_arguments`	Whether an argument schema declares no way to supply arguments.
`validate_arguments`	Validate model-supplied tool-call arguments against the tool’s schema.

API

class nemoguardrails.guardrails.tool_schema.Tool(
    name: str | None = None,
    type: str = 'function',
    description: str | None = None,
    arguments_schema: dict | None = None,
    strict: bool | None = None
)

Dataclass

A declared tool definition the caller offered to the model.

name is set for function tools and None for hosted/server tools that are identified only by type (e.g. web_search). arguments_schema is the JSON Schema for the call arguments, or None when none is declared. A hosted tool with no schema is allowlist-only (the provider owns the call shape); a function tool that declares no parameters accepts no arguments, so a call that supplies any is rejected.

arguments_schema

dict | None = None

description

str | None = None

key

str

Allowlist / lookup identifier: the function name, else the type.

name

str | None = None

strict

bool | None = None

type

str = 'function'

class nemoguardrails.guardrails.tool_schema.ToolExchange()

Bases: NamedTuple

One assistant turn’s tool calls paired with the tool results that answer them.

calls

list[ToolCall]

results

list[ToolResult]

class nemoguardrails.guardrails.tool_schema.ToolResult(
    call_id: str | None = None,
    name: str | None = None,
    content: str | list[dict] | None = None,
    is_error: bool = False
)

Dataclass

A normalized tool result extracted from incoming messages by the engine.

The ToolResultRail consumes a list of these; the per-provider extraction (e.g. OpenAI role:"tool" messages) lives in the engine adapter, so the rail never sees provider wire shapes. content is a string or a list of content blocks (the latter covers multimodal results). is_error flags a failed result where the provider exposes one (e.g. Anthropic is_error / Bedrock status:"error").

call_id

str | None = None

content

str | list[dict] | None = None

is_error

bool = False

name

str | None = None

class nemoguardrails.guardrails.tool_schema.Toolset(
    tools: collections.abc.Iterable[nemoguardrails.guardrails.tool_schema.Tool] | None = None
)

The set of tools declared on a request, indexed by tool key.

Backed by a single key -> Tool mapping built at construction, so there is no separate list that can drift out of sync with the index. Look tools up with :meth:get (toolset.get(name)); iterate or count via the read-only :attr:tools.

__slots__

= ('_by_key',)

_by_key

dict[str, Tool] = {}

tools

tuple[Tool, ...]

The declared tools in declaration order (read-only view of the index).

nemoguardrails.guardrails.tool_schema.Toolset.get(
    key: str
) -> nemoguardrails.guardrails.tool_schema.Tool | None

Return the declared tool registered under key (function name or hosted-tool type), or None.

nemoguardrails.guardrails.tool_schema._no_arguments_reason(
    tool: nemoguardrails.guardrails.tool_schema.Tool,
    arguments: dict
) -> str | None

Block reason for a tool that accepts no arguments, or None when the call is allowed.

Hosted/server tools (no name) are allowlist-only — the provider owns the call shape — so arguments are accepted here. A function tool that declares no parameters must be called with no arguments, so any supplied argument is rejected.

nemoguardrails.guardrails.tool_schema._schema_accepts_no_arguments(
    schema: dict
) -> bool

Whether an argument schema declares no way to supply arguments.

True for an empty schema ({}) or an object schema that names no properties and opens no other input channel (additionalProperties, patternProperties, or a composition/reference keyword). Such a schema describes a tool that takes no arguments; jsonschema treats it as permissive, so callers enforce emptiness directly.

nemoguardrails.guardrails.tool_schema.validate_arguments(
    tool: nemoguardrails.guardrails.tool_schema.Tool,
    arguments: dict
) -> str | None

Validate model-supplied tool-call arguments against the tool’s schema.

Returns None when the arguments are valid. Returns a human-readable reason when the arguments violate the schema, when the declared schema itself is not valid JSON Schema (e.g. a non-JSON-Schema dialect reaching this validator before its engine adapter normalizes it), or when a function tool that declares no parameters is called with arguments.