Skip to navigation

nemoguardrails.server.hooks.checking

View as MarkdownOpen in Claude

The bridge to the engine: the check a hook’s tool call asks for, and the verdict the check’s result gives.

Module Contents

Classes

NameDescription
HookOutcomeA check’s verdict on a tool call, before it becomes the agent’s response.
ToolInvocationThe tool call a hook asks to check, whichever agent sent it; internal to the hooks server.

Functions

NameDescription
_blocked_outcomeA deny when any violation is a decision on the call, or an error when every violation is a check failure.
_check_failed_outcomeA rail_failed error when every failure is a rail’s, otherwise an error with no code naming the first other.
_deny_reasonThe first non-empty reason among the decided violations, then the result’s reason, then the rail that blocked.
_rail_failed_messageThe error message for a failed rail, naming the rail when the violation does.
check_messagesThe one assistant message carrying call, as check_async() takes it; with no id when the call has none.
check_toolsA compatibility declaration of the tool call names, as check_async() takes tools, for per-tool rails.
outcome_from_resultThe verdict a tool-call check’s result gives: allow, deny, or an error when no rail decided.

Data

_CHECK_FAILURES

_UNSPECIFIED_DENY_REASON

API

class nemoguardrails.server.hooks.HookOutcome(
kind: typing.Literal['allow', 'deny', 'error'],
reason: typing.Optional[str] = None,
message: typing.Optional[str] = None
)
Dataclass

A check’s verdict on a tool call, before it becomes the agent’s response.

code
Optional[HookErrorCode] = None
kind
Literal['allow', 'deny', 'error']
message
Optional[str] = None
reason
Optional[str] = None
nemoguardrails.server.hooks.HookOutcome.__post_init__() -> None

Refuse any field the outcome’s kind doesn’t have, so only a valid allow, deny or error exists.

nemoguardrails.server.hooks.HookOutcome._require_text(
name: str
) -> None

Raise unless the field name holds a non-empty string.

nemoguardrails.server.hooks.HookOutcome._require_unset(
names: str = ()
) -> None

Raise when any of the fields names is set, since this kind of outcome has none of them.

nemoguardrails.server.hooks.HookOutcome.allow() -> nemoguardrails.server.hooks.checking.HookOutcome
classmethod
nemoguardrails.server.hooks.HookOutcome.deny(
reason: str
classmethod
nemoguardrails.server.hooks.HookOutcome.error(
message: str,
classmethod
class nemoguardrails.server.hooks.checking.ToolInvocation(
name: str,
arguments: typing.Any,
call_id: typing.Optional[str] = None
)
Dataclass

The tool call a hook asks to check, whichever agent sent it; internal to the hooks server.

call_id
Optional[str] = None
name
str
nemoguardrails.server.hooks.checking._blocked_outcome(

A deny when any violation is a decision on the call, or an error when every violation is a check failure.

nemoguardrails.server.hooks.checking._check_failed_outcome(

A rail_failed error when every failure is a rail’s, otherwise an error with no code naming the first other.

nemoguardrails.server.hooks.checking._deny_reason(
) -> str

The first non-empty reason among the decided violations, then the result’s reason, then the rail that blocked.

nemoguardrails.server.hooks.checking._rail_failed_message(
) -> str

The error message for a failed rail, naming the rail when the violation does.

nemoguardrails.server.hooks.check_messages(
) -> list[dict]

The one assistant message carrying call, as check_async() takes it; with no id when the call has none.

nemoguardrails.server.hooks.check_tools(
) -> list[dict]

A compatibility declaration of the tool call names, as check_async() takes tools, for per-tool rails.

nemoguardrails.server.hooks.outcome_from_result(

The verdict a tool-call check’s result gives: allow, deny, or an error when no rail decided.

nemoguardrails.server.hooks.checking._CHECK_FAILURES = frozenset({ToolViolationType.RAIL_FAILED, ToolViolationType.EXTRACTION_FAILED, T...
nemoguardrails.server.hooks.checking._UNSPECIFIED_DENY_REASON = 'tool call blocked'