> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.nvidia.com/nemo/guardrails/latest/guardrails-python-sdk/nemoguardrails/server/hooks/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'] ``` ## Docs - [nemoguardrails.server.hooks.adapters](https://docs.nvidia.com/nemo/guardrails/latest/guardrails-python-sdk/nemoguardrails/server/hooks/adapters.md) - [nemoguardrails.server.hooks.app](https://docs.nvidia.com/nemo/guardrails/latest/guardrails-python-sdk/nemoguardrails/server/hooks/app.md) - [nemoguardrails.server.hooks.checking](https://docs.nvidia.com/nemo/guardrails/latest/guardrails-python-sdk/nemoguardrails/server/hooks/checking.md) - [nemoguardrails.server.hooks.schemas](https://docs.nvidia.com/nemo/guardrails/latest/guardrails-python-sdk/nemoguardrails/server/hooks/schemas.md) - [nemoguardrails.server.hooks.tool_policy](https://docs.nvidia.com/nemo/guardrails/latest/guardrails-python-sdk/nemoguardrails/server/hooks/tool_policy.md)