> 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.app

The hooks server: checks the tool call in each agent hook with one config's tool-call rails, on IORails.

## Module Contents

### Classes

| Name                                                                    | Description                                                                 |
| ----------------------------------------------------------------------- | --------------------------------------------------------------------------- |
| [`HooksConfigError`](#nemoguardrails-server-hooks-app-HooksConfigError) | A config the hooks server can't serve, found before it answers any request. |

### Functions

| Name                                                                                                                          | Description                                                                                                   |
| ----------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| [`_answer_hook`](#nemoguardrails-server-hooks-app-_answer_hook)                                                               | Check the tool call the hook carries, and answer with the agent's allow or deny, or an error status.          |
| [`_build_engine`](#nemoguardrails-server-hooks-app-_build_engine)                                                             | The server's IORails engine for *config*, never LLMRails, which can't run tool checks.                        |
| [`_check_allowlist_sets_unlisted_tools_choice`](#nemoguardrails-server-hooks-app-_check_allowlist_sets_unlisted_tools_choice) | Raise when hooks_server.allowed_tools lists tools but leaves allow_unlisted_tools to its default.             |
| [`_check_main_model`](#nemoguardrails-server-hooks-app-_check_main_model)                                                     | Raise unless a tool-call rail uses any `main` model, and tool lists replace the tools it declares.            |
| [`_check_no_global_tool_call_rails`](#nemoguardrails-server-hooks-app-_check_no_global_tool_call_rails)                       | Raise when rails.tool_call.flows lists a rail, which can't deny a call the tool policy allows.                |
| [`_check_per_tool_rails_can_run`](#nemoguardrails-server-hooks-app-_check_per_tool_rails_can_run)                             | Raise when the tool policy denies every call to a tool that per-tool rails are configured for.                |
| [`_check_something_can_deny`](#nemoguardrails-server-hooks-app-_check_something_can_deny)                                     | Raise unless the tool policy or a per-tool rail can deny a call, since otherwise every call is allowed.       |
| [`_check_tool_call`](#nemoguardrails-server-hooks-app-_check_tool_call)                                                       | Decide the hook's call with the tool policy, then run its tool's per-tool rails on it, and log the verdict.   |
| [`_has_per_tool_rails`](#nemoguardrails-server-hooks-app-_has_per_tool_rails)                                                 | Whether *config* lists a per-tool rail for any tool's calls.                                                  |
| [`_lifespan`](#nemoguardrails-server-hooks-app-_lifespan)                                                                     | Start the metrics exporter and the engine before the server accepts requests, and stop them on shutdown.      |
| [`_log_check`](#nemoguardrails-server-hooks-app-_log_check)                                                                   | Log one line for a check, without the tool's input; an error, which no rail decided, as a warning.            |
| [`_main_model`](#nemoguardrails-server-hooks-app-_main_model)                                                                 | *config*'s `main` model, or None without one.                                                                 |
| [`_parse_hook`](#nemoguardrails-server-hooks-app-_parse_hook)                                                                 | The tool call *body* asks to check on *adapter*'s path, raising a failure for the shared `422` handler.       |
| [`_read_json`](#nemoguardrails-server-hooks-app-_read_json)                                                                   | The request body as JSON, whatever its `Content-Type` says.                                                   |
| [`_tool_call_rails_use_model`](#nemoguardrails-server-hooks-app-_tool_call_rails_use_model)                                   | Whether a global or per-tool tool-call rail names *model_type* with `$model=`.                                |
| [`_unsupported_hook_event_handler`](#nemoguardrails-server-hooks-app-_unsupported_hook_event_handler)                         | Answer a `hook_event_name` the path doesn't handle with `422 unsupported_hook_event`.                         |
| [`_warn_about_ignored_main_model_tools`](#nemoguardrails-server-hooks-app-_warn_about_ignored_main_model_tools)               | Warn that the hooks server ignores the tools a `main` model declares, since the tool policy replaces them.    |
| [`_warn_if_the_config_records_no_metrics`](#nemoguardrails-server-hooks-app-_warn_if_the_config_records_no_metrics)           | Warn that the scrape endpoint will show no guardrails metrics, when the config doesn't turn them on.          |
| [`check_hooks_config`](#nemoguardrails-server-hooks-app-check_hooks_config)                                                   | Raise `HooksConfigError` unless IORails can serve *config*, it can deny a call, its rails and `main` run, and |
| [`create_hooks_app`](#nemoguardrails-server-hooks-app-create_hooks_app)                                                       | Build the hooks server for *config*, with its own engine; raises `HooksConfigError` if it can't serve hooks.  |
| [`handle_claude_code_hook`](#nemoguardrails-server-hooks-app-handle_claude_code_hook)                                         | Answer a Claude Code hook in Claude Code's hook output format.                                                |
| [`handle_codex_hook`](#nemoguardrails-server-hooks-app-handle_codex_hook)                                                     | Answer a Codex hook in Codex's hook output format.                                                            |
| [`handle_nemo_relay_hook`](#nemoguardrails-server-hooks-app-handle_nemo_relay_hook)                                           | Answer a NeMo Relay tool conditional-execution guardrail with its decision.                                   |
| [`health`](#nemoguardrails-server-hooks-app-health)                                                                           | Return HTTP 200 while the server process is running and able to serve requests.                               |
| [`metrics_exporter_settings`](#nemoguardrails-server-hooks-app-metrics_exporter_settings)                                     | The `NEMO_GUARDRAILS_SERVER_METRICS_*` exporter settings, with the hooks server's defaults for those unset.   |

### Data

[`_EXCEPTION_HANDLERS`](#nemoguardrails-server-hooks-app-_EXCEPTION_HANDLERS)

[`_METRICS_DEFAULTS`](#nemoguardrails-server-hooks-app-_METRICS_DEFAULTS)

[`_MODEL_CALL_ERRORS`](#nemoguardrails-server-hooks-app-_MODEL_CALL_ERRORS)

[`_TOOL_POLICY`](#nemoguardrails-server-hooks-app-_TOOL_POLICY)

[`_router`](#nemoguardrails-server-hooks-app-_router)

[`log`](#nemoguardrails-server-hooks-app-log)

### API

```python
class nemoguardrails.server.hooks.app.HooksConfigError()
```

**Bases:** [ConfigurationError](/nemo/guardrails/v0.25.0/guardrails-python-sdk/nemoguardrails/exceptions#nemoguardrails-exceptions-ConfigurationError)

A config the hooks server can't serve, found before it answers any request.

```python
nemoguardrails.server.hooks.app._answer_hook(
    agent: nemoguardrails.server.hooks.adapters.HookAgent,
    request: fastapi.Request
) -> starlette.responses.Response
```

async

Check the tool call the hook carries, and answer with the agent's allow or deny, or an error status.

```python
nemoguardrails.server.hooks.app._build_engine(
    config: nemoguardrails.rails.llm.config.RailsConfig
) -> nemoguardrails.guardrails.guardrails.Guardrails
```

The server's IORails engine for *config*, never LLMRails, which can't run tool checks.

```python
nemoguardrails.server.hooks.app._check_allowlist_sets_unlisted_tools_choice(
    config: nemoguardrails.rails.llm.config.RailsConfig
) -> None
```

Raise when hooks_server.allowed_tools lists tools but leaves allow_unlisted_tools to its default.

```python
nemoguardrails.server.hooks.app._check_main_model(
    config: nemoguardrails.rails.llm.config.RailsConfig
) -> None
```

Raise unless a tool-call rail uses any `main` model, and tool lists replace the tools it declares.

```python
nemoguardrails.server.hooks.app._check_no_global_tool_call_rails(
    config: nemoguardrails.rails.llm.config.RailsConfig
) -> None
```

Raise when rails.tool_call.flows lists a rail, which can't deny a call the tool policy allows.

```python
nemoguardrails.server.hooks.app._check_per_tool_rails_can_run(
    config: nemoguardrails.rails.llm.config.RailsConfig,
    policy: nemoguardrails.server.hooks.tool_policy.ToolPolicy
) -> None
```

Raise when the tool policy denies every call to a tool that per-tool rails are configured for.

```python
nemoguardrails.server.hooks.app._check_something_can_deny(
    config: nemoguardrails.rails.llm.config.RailsConfig
) -> None
```

Raise unless the tool policy or a per-tool rail can deny a call, since otherwise every call is allowed.

```python
nemoguardrails.server.hooks.app._check_tool_call(
    engine: nemoguardrails.guardrails.guardrails.Guardrails,
    policy: nemoguardrails.server.hooks.tool_policy.ToolPolicy,
    adapter: nemoguardrails.server.hooks.adapters.HookAdapter,
    call: nemoguardrails.server.hooks.checking.ToolInvocation
) -> nemoguardrails.server.hooks.checking.HookOutcome
```

async

Decide the hook's call with the tool policy, then run its tool's per-tool rails on it, and log the verdict.

```python
nemoguardrails.server.hooks.app._has_per_tool_rails(
    config: nemoguardrails.rails.llm.config.RailsConfig
) -> bool
```

Whether *config* lists a per-tool rail for any tool's calls.

```python
nemoguardrails.server.hooks.app._lifespan(
    app: fastapi.FastAPI
) -> typing.AsyncIterator[None]
```

async

Start the metrics exporter and the engine before the server accepts requests, and stop them on shutdown.

```python
nemoguardrails.server.hooks.app._log_check(
    adapter: nemoguardrails.server.hooks.adapters.HookAdapter,
    call: nemoguardrails.server.hooks.checking.ToolInvocation,
    outcome: nemoguardrails.server.hooks.checking.HookOutcome,
    rail: typing.Optional[str]
) -> None
```

Log one line for a check, without the tool's input; an error, which no rail decided, as a warning.

```python
nemoguardrails.server.hooks.app._main_model(
    config: nemoguardrails.rails.llm.config.RailsConfig
) -> typing.Optional[nemoguardrails.rails.llm.config.Model]
```

*config*'s `main` model, or None without one.

```python
nemoguardrails.server.hooks.app._parse_hook(
    adapter: nemoguardrails.server.hooks.adapters.HookAdapter,
    body: object
) -> nemoguardrails.server.hooks.checking.ToolInvocation
```

The tool call *body* asks to check on *adapter*'s path, raising a failure for the shared `422` handler.

```python
nemoguardrails.server.hooks.app._read_json(
    request: fastapi.Request
) -> object
```

async

The request body as JSON, whatever its `Content-Type` says.

```python
nemoguardrails.server.hooks.app._tool_call_rails_use_model(
    config: nemoguardrails.rails.llm.config.RailsConfig,
    model_type: str
) -> bool
```

Whether a global or per-tool tool-call rail names *model_type* with `$model=`.

```python
nemoguardrails.server.hooks.app._unsupported_hook_event_handler(
    request: fastapi.Request,
    exc: nemoguardrails.server.hooks.adapters.UnsupportedHookEventError
) -> starlette.responses.Response
```

async

Answer a `hook_event_name` the path doesn't handle with `422 unsupported_hook_event`.

```python
nemoguardrails.server.hooks.app._warn_about_ignored_main_model_tools(
    config: nemoguardrails.rails.llm.config.RailsConfig
) -> None
```

Warn that the hooks server ignores the tools a `main` model declares, since the tool policy replaces them.

```python
nemoguardrails.server.hooks.app._warn_if_the_config_records_no_metrics(
    config: nemoguardrails.rails.llm.config.RailsConfig
) -> None
```

Warn that the scrape endpoint will show no guardrails metrics, when the config doesn't turn them on.

```python
nemoguardrails.server.hooks.app.check_hooks_config(
    config: nemoguardrails.rails.llm.config.RailsConfig
) -> None
```

Raise `HooksConfigError` unless IORails can serve *config*, it can deny a call, its rails and `main` run, and
an allowlist says whether unlisted tools are allowed.

```python
nemoguardrails.server.hooks.app.create_hooks_app(
    config: nemoguardrails.rails.llm.config.RailsConfig
) -> fastapi.FastAPI
```

Build the hooks server for *config*, with its own engine; raises `HooksConfigError` if it can't serve hooks.

```python
nemoguardrails.server.hooks.app.handle_claude_code_hook(
    request: fastapi.Request
) -> starlette.responses.Response
```

async

Answer a Claude Code hook in Claude Code's hook output format.

```python
nemoguardrails.server.hooks.app.handle_codex_hook(
    request: fastapi.Request
) -> starlette.responses.Response
```

async

Answer a Codex hook in Codex's hook output format.

```python
nemoguardrails.server.hooks.app.handle_nemo_relay_hook(
    request: fastapi.Request
) -> starlette.responses.Response
```

async

Answer a NeMo Relay tool conditional-execution guardrail with its decision.

```python
nemoguardrails.server.hooks.app.health() -> starlette.responses.Response
```

async

Return HTTP 200 while the server process is running and able to serve requests.

```python
nemoguardrails.server.hooks.app.metrics_exporter_settings(
    environ: typing.Optional[typing.Mapping[str, str]] = None
) -> nemoguardrails.server.metrics.MetricsExporterSettings
```

The `NEMO_GUARDRAILS_SERVER_METRICS_*` exporter settings, with the hooks server's defaults for those unset.

```python
nemoguardrails.server.hooks.app._EXCEPTION_HANDLERS = ((UnsupportedHookEventError, _unsupported_hook_event_handler), (NonStreamingWork...
```

```python
nemoguardrails.server.hooks.app._METRICS_DEFAULTS = MetricsExporterSettings(host='127.0.0.1', port=9465, service_name='nemoguardrail...
```

```python
nemoguardrails.server.hooks.app._MODEL_CALL_ERRORS = (LLMCallException, ModelEngineError, HTTPClientError)
```

```python
nemoguardrails.server.hooks.app._TOOL_POLICY = 'tool policy'
```

```python
nemoguardrails.server.hooks.app._router = APIRouter()
```

```python
nemoguardrails.server.hooks.app.log = logging.getLogger(__name__)
```