> This page is for version Latest (default).
> 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

Agent hook requests and responses for `nemoguardrails hooks-server`.

## Submodules

* **[`nemoguardrails.server.hooks.adapters`](/nemo/guardrails/guardrails-python-sdk/nemoguardrails/server/hooks/adapters)**
* **[`nemoguardrails.server.hooks.app`](/nemo/guardrails/guardrails-python-sdk/nemoguardrails/server/hooks/app)**
* **[`nemoguardrails.server.hooks.checking`](/nemo/guardrails/guardrails-python-sdk/nemoguardrails/server/hooks/checking)**
* **[`nemoguardrails.server.hooks.schemas`](/nemo/guardrails/guardrails-python-sdk/nemoguardrails/server/hooks/schemas)**
* **[`nemoguardrails.server.hooks.tool_policy`](/nemo/guardrails/guardrails-python-sdk/nemoguardrails/server/hooks/tool_policy)**

## Package Contents

### Classes

| Name                                                                                           | Description                                                                                                   |
| ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| [`HookAdapter`](#nemoguardrails-server-hooks-adapters-HookAdapter)                             | One agent's path: the event it handles, the tool call that event's body carries, and each outcome's response. |
| [`HookErrorCode`](#nemoguardrails-server-hooks-schemas-HookErrorCode)                          | The `error.code` of a hooks request that ends in an error rather than an allow or a deny.                     |
| [`HookOutcome`](#nemoguardrails-server-hooks-checking-HookOutcome)                             | A check's verdict on a tool call, before it becomes the agent's response.                                     |
| [`UnsupportedHookEventError`](#nemoguardrails-server-hooks-adapters-UnsupportedHookEventError) | A `hook_event_name` that the agent's path doesn't handle.                                                     |

### Functions

| Name                                                                               | Description                                                                                                 |
| ---------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| [`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

[`ADAPTERS`](#nemoguardrails-server-hooks-adapters-ADAPTERS)

[`HookAgent`](#nemoguardrails-server-hooks-adapters-HookAgent)

### API

```python
class nemoguardrails.server.hooks.HookAdapter(
    agent: nemoguardrails.server.hooks.adapters.HookAgent,
    event: str,
    request_model: type[pydantic.BaseModel],
    invocation: typing.Callable[[Any], nemoguardrails.server.hooks.checking.ToolInvocation],
    response_body: typing.Callable[[HookOutcome], dict]
)
```

Dataclass

One agent's path: the event it handles, the tool call that event's body carries, and each outcome's response.

**`agent`** `HookAgent`

---

**`event`** `str`

---

**`invocation`** `Callable[[Any], ToolInvocation]`

---

**`request_model`** `type[BaseModel]`

---

**`response_body`** `Callable[[HookOutcome], dict]`

---

```python
nemoguardrails.server.hooks.HookAdapter.parse(
    body: object
) -> nemoguardrails.server.hooks.checking.ToolInvocation
```

The tool call *body* asks to check, as this path's event; error locations are relative to the body.

```python
class nemoguardrails.server.hooks.HookErrorCode
```

**Bases:** `enum.Enum`

The `error.code` of a hooks request that ends in an error rather than an allow or a deny.

**`QUEUE_FULL`** `= 'queue_full'`

---

**`RAIL_FAILED`** `= 'rail_failed'`

---

**`UNSUPPORTED_HOOK_EVENT`** `= 'unsupported_hook_event'`

---

```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.UnsupportedHookEventError(
    agent: nemoguardrails.server.hooks.adapters.HookAgent,
    event: str,
    handled_event: str
)
```

Exception

**Bases:** `Exception`

A `hook_event_name` that the agent's path doesn't handle.

```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.adapters.ADAPTERS: dict[HookAgent, HookAdapter] = {(adapter.agent): adapter for adapter in (HookAdapter(agent='claude-code', event...
```

```python
nemoguardrails.server.hooks.adapters.HookAgent = Literal['claude-code', 'codex', 'nemo-relay']
```