> This page is for version v0.25.0.
> For other versions, use one of these documentation indexes:
> - Latest (default): https://docs.nvidia.com/nemo/guardrails/latest/llms.txt
> - v0.25.0: https://docs.nvidia.com/nemo/guardrails/v0.25.0/llms.txt
> - v0.24.1: https://docs.nvidia.com/nemo/guardrails/v0.24.1/llms.txt
> - v0.24.0: https://docs.nvidia.com/nemo/guardrails/v0.24.0/llms.txt
> - v0.23.0: https://docs.nvidia.com/nemo/guardrails/v0.23.0/llms.txt
> - v0.22.0: https://docs.nvidia.com/nemo/guardrails/v0.22.0/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/guardrails/llms.txt.

# nemoguardrails.server.hooks.checking

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

| Name                                                                     | Description                                                                                |
| ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------ |
| [`HookOutcome`](#nemoguardrails-server-hooks-checking-HookOutcome)       | A check's verdict on a tool call, before it becomes the agent's response.                  |
| [`ToolInvocation`](#nemoguardrails-server-hooks-checking-ToolInvocation) | The tool call a hook asks to check, whichever agent sent it; internal to the hooks server. |

### Functions

| Name                                                                                   | Description                                                                                                    |
| -------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| [`_blocked_outcome`](#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.      |
| [`_check_failed_outcome`](#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.  |
| [`_deny_reason`](#nemoguardrails-server-hooks-checking-_deny_reason)                   | The first non-empty reason among the decided violations, then the result's reason, then the rail that blocked. |
| [`_rail_failed_message`](#nemoguardrails-server-hooks-checking-_rail_failed_message)   | The error message for a failed rail, naming the rail when the violation does.                                  |
| [`check_messages`](#nemoguardrails-server-hooks-checking-check_messages)               | The one assistant message carrying *call*, as `check_async()` takes it; with no id when the call has none.     |
| [`check_tools`](#nemoguardrails-server-hooks-checking-check_tools)                     | A compatibility declaration of the tool *call* names, as `check_async()` takes `tools`, for per-tool rails.    |
| [`outcome_from_result`](#nemoguardrails-server-hooks-checking-outcome_from_result)     | The verdict a tool-call check's result gives: allow, deny, or an error when no rail decided.                   |

### Data

[`_CHECK_FAILURES`](#nemoguardrails-server-hooks-checking-_CHECK_FAILURES)

[`_UNSPECIFIED_DENY_REASON`](#nemoguardrails-server-hooks-checking-_UNSPECIFIED_DENY_REASON)

### API

```python
class nemoguardrails.server.hooks.HookOutcome(
    kind: typing.Literal['allow', 'deny', 'error'],
    reason: typing.Optional[str] = None,
    code: typing.Optional[nemoguardrails.server.hooks.schemas.HookErrorCode] = 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`

---

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

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

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

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

```python
nemoguardrails.server.hooks.HookOutcome.allow() -> nemoguardrails.server.hooks.checking.HookOutcome
```

classmethod

```python
nemoguardrails.server.hooks.HookOutcome.deny(
    reason: str
) -> nemoguardrails.server.hooks.checking.HookOutcome
```

classmethod

```python
nemoguardrails.server.hooks.HookOutcome.error(
    message: str,
    code: typing.Optional[nemoguardrails.server.hooks.schemas.HookErrorCode] = None
) -> nemoguardrails.server.hooks.checking.HookOutcome
```

classmethod

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

---

```python
nemoguardrails.server.hooks.checking._blocked_outcome(
    result: nemoguardrails.rails.llm.options.RailsResult
) -> nemoguardrails.server.hooks.checking.HookOutcome
```

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

```python
nemoguardrails.server.hooks.checking._check_failed_outcome(
    violations: list[nemoguardrails.rails.llm.options.ToolViolation]
) -> nemoguardrails.server.hooks.checking.HookOutcome
```

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

```python
nemoguardrails.server.hooks.checking._deny_reason(
    result: nemoguardrails.rails.llm.options.RailsResult
) -> str
```

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

```python
nemoguardrails.server.hooks.checking._rail_failed_message(
    violation: nemoguardrails.rails.llm.options.ToolViolation
) -> str
```

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

```python
nemoguardrails.server.hooks.check_messages(
    call: nemoguardrails.server.hooks.checking.ToolInvocation
) -> list[dict]
```

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

```python
nemoguardrails.server.hooks.check_tools(
    call: nemoguardrails.server.hooks.checking.ToolInvocation,
    policy: nemoguardrails.server.hooks.tool_policy.ToolPolicy
) -> list[dict]
```

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

```python
nemoguardrails.server.hooks.outcome_from_result(
    result: nemoguardrails.rails.llm.options.RailsResult
) -> nemoguardrails.server.hooks.checking.HookOutcome
```

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

```python
nemoguardrails.server.hooks.checking._CHECK_FAILURES = frozenset({ToolViolationType.RAIL_FAILED, ToolViolationType.EXTRACTION_FAILED, T...
```

```python
nemoguardrails.server.hooks.checking._UNSPECIFIED_DENY_REASON = 'tool call blocked'
```