> 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. > For full documentation content, see https://docs.nvidia.com/nemo/guardrails/llms-full.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/nemo/guardrails/_mcp/server. # nemoguardrails.actions.llm.utils ## Module Contents ### Functions | Name | Description | | ---------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | | [`_ensure_chat_messages`](#nemoguardrails-actions-llm-utils-_ensure_chat_messages) | - | | [`_extract_and_remove_think_tags`](#nemoguardrails-actions-llm-utils-_extract_and_remove_think_tags) | Extract reasoning from \ tags and remove them from `response.content`. | | [`_extract_chunk_metadata`](#nemoguardrails-actions-llm-utils-_extract_chunk_metadata) | - | | [`_extract_content`](#nemoguardrails-actions-llm-utils-_extract_content) | Extract text content from response. | | [`_extract_user_text_from_event`](#nemoguardrails-actions-llm-utils-_extract_user_text_from_event) | Flatten a multimodal user-message payload into a string for colang history. | | [`_log_completion`](#nemoguardrails-actions-llm-utils-_log_completion) | - | | [`_log_prompt`](#nemoguardrails-actions-llm-utils-_log_prompt) | Log the prompt to LLM call info. | | [`_raise_llm_call_exception`](#nemoguardrails-actions-llm-utils-_raise_llm_call_exception) | - | | [`_setup_llm_call_info`](#nemoguardrails-actions-llm-utils-_setup_llm_call_info) | Initialize or update LLM call info in context. | | [`_store_reasoning_traces`](#nemoguardrails-actions-llm-utils-_store_reasoning_traces) | - | | [`_store_response_metadata`](#nemoguardrails-actions-llm-utils-_store_response_metadata) | - | | [`_store_tool_calls`](#nemoguardrails-actions-llm-utils-_store_tool_calls) | - | | [`_stream_llm_call`](#nemoguardrails-actions-llm-utils-_stream_llm_call) | - | | [`_update_token_stats`](#nemoguardrails-actions-llm-utils-_update_token_stats) | - | | [`_update_token_stats_from_chunk`](#nemoguardrails-actions-llm-utils-_update_token_stats_from_chunk) | - | | [`escape_flow_name`](#nemoguardrails-actions-llm-utils-escape_flow_name) | Escape invalid keywords in flow names. | | [`events_to_dialog_history`](#nemoguardrails-actions-llm-utils-events_to_dialog_history) | Create the dialog history based on provided events. | | [`extract_bot_thinking_from_events`](#nemoguardrails-actions-llm-utils-extract_bot_thinking_from_events) | - | | [`extract_tool_calls_from_events`](#nemoguardrails-actions-llm-utils-extract_tool_calls_from_events) | Extract tool\_calls from BotToolCalls events. | | [`flow_to_colang`](#nemoguardrails-actions-llm-utils-flow_to_colang) | Converts a flow to colang format. | | [`from_log_event_to_identifier`](#nemoguardrails-actions-llm-utils-from_log_event_to_identifier) | convert log message to prompt interaction identifier. | | [`get_and_clear_reasoning_trace_contextvar`](#nemoguardrails-actions-llm-utils-get_and_clear_reasoning_trace_contextvar) | Get the current reasoning trace and clear it from the context. | | [`get_and_clear_response_metadata_contextvar`](#nemoguardrails-actions-llm-utils-get_and_clear_response_metadata_contextvar) | Get the current response metadata and clear it from the context. | | [`get_and_clear_tool_calls_contextvar`](#nemoguardrails-actions-llm-utils-get_and_clear_tool_calls_contextvar) | Get the current tool calls and clear them from the context. | | [`get_colang_history`](#nemoguardrails-actions-llm-utils-get_colang_history) | Creates a history of user messages and bot responses in colang format. | | [`get_first_bot_action`](#nemoguardrails-actions-llm-utils-get_first_bot_action) | Returns first bot action. | | [`get_first_bot_intent`](#nemoguardrails-actions-llm-utils-get_first_bot_intent) | Returns first bot intent. | | [`get_first_nonempty_line`](#nemoguardrails-actions-llm-utils-get_first_nonempty_line) | Helper that returns the first non-empty line from a string | | [`get_first_user_intent`](#nemoguardrails-actions-llm-utils-get_first_user_intent) | Returns first user intent. | | [`get_initial_actions`](#nemoguardrails-actions-llm-utils-get_initial_actions) | Returns the first action before an empty line. | | [`get_last_bot_intent_event`](#nemoguardrails-actions-llm-utils-get_last_bot_intent_event) | Returns the last user intent from the events. | | [`get_last_bot_utterance_event`](#nemoguardrails-actions-llm-utils-get_last_bot_utterance_event) | Returns the last bot utterance from the events. | | [`get_last_user_intent_event`](#nemoguardrails-actions-llm-utils-get_last_user_intent_event) | Returns the last user intent from the events. | | [`get_last_user_utterance`](#nemoguardrails-actions-llm-utils-get_last_user_utterance) | Returns the last user utterance from the events. | | [`get_last_user_utterance_event`](#nemoguardrails-actions-llm-utils-get_last_user_utterance_event) | Returns the last user utterance from the events. | | [`get_last_user_utterance_event_v2_x`](#nemoguardrails-actions-llm-utils-get_last_user_utterance_event_v2_x) | Returns the last user utterance from the events. | | [`get_multiline_response`](#nemoguardrails-actions-llm-utils-get_multiline_response) | Helper that extracts multi-line responses from the LLM. | | [`get_retrieved_relevant_chunks`](#nemoguardrails-actions-llm-utils-get_retrieved_relevant_chunks) | Returns the retrieved chunks for current user utterance from the events. | | [`get_top_k_nonempty_lines`](#nemoguardrails-actions-llm-utils-get_top_k_nonempty_lines) | Helper that returns a list with the top k non-empty lines from a string. | | [`llm_call`](#nemoguardrails-actions-llm-utils-llm_call) | - | | [`remove_action_intent_identifiers`](#nemoguardrails-actions-llm-utils-remove_action_intent_identifiers) | Removes the action/intent identifiers. | | [`remove_text_messages_from_history`](#nemoguardrails-actions-llm-utils-remove_text_messages_from_history) | Helper that given a history in colang format, removes all texts. | | [`strip_quotes`](#nemoguardrails-actions-llm-utils-strip_quotes) | Helper that removes quotes from a string if the entire string is between quotes | | [`warn_if_truncated`](#nemoguardrails-actions-llm-utils-warn_if_truncated) | Return True and emit a warning if the LLM produced no visible content because it hit the max\_tokens budget. | ### Data [`logger`](#nemoguardrails-actions-llm-utils-logger) ### API ```python nemoguardrails.actions.llm.utils._ensure_chat_messages( prompt: typing.Union[str, list] ) -> typing.Union[str, typing.List[nemoguardrails.types.ChatMessage]] ``` ```python nemoguardrails.actions.llm.utils._extract_and_remove_think_tags( response: nemoguardrails.types.LLMResponse ) -> typing.Optional[str] ``` Extract reasoning from \ tags and remove them from `response.content`. This function looks for \...\ tags in the response content, and if found, extracts the reasoning content inside the tags. It has a side-effect: it removes the full reasoning trace and tags from response.content. **Parameters:** The LLM response object **Returns:** `Optional[str]` The extracted reasoning content, or None if no \ tags found ```python nemoguardrails.actions.llm.utils._extract_chunk_metadata( chunk: nemoguardrails.types.LLMResponseChunk ) -> typing.Optional[typing.Dict[str, typing.Any]] ``` ```python nemoguardrails.actions.llm.utils._extract_content( response: nemoguardrails.types.LLMResponse ) -> str ``` Extract text content from response. ```python nemoguardrails.actions.llm.utils._extract_user_text_from_event( event_text: typing.Union[str, typing.List[typing.Dict[str, typing.Any]]] ) -> str ``` Flatten a multimodal user-message payload into a string for colang history. Multimodal user events carry `event_text` as a list of OpenAI-style content parts (`[{"type": "text", "text": "..."}, {"type": "image_url", "image_url": {...}}, ...]`). Including the full list in the colang history bloats the context with raw base64 data; this helper extracts the visible text parts and appends a `[+ image]` marker when one or more image parts were present. Non-string text fields (`None` or other types) inside a content part are skipped so the `" ".join(...)` step cannot crash. If the message is image-only, the result is just `"[+ image]"` without a leading space. **Parameters:** Either a string (already flat) or a list of multimodal content parts. **Returns:** `str` The flattened text. A list input always produces a string; a string ```python nemoguardrails.actions.llm.utils._log_completion( response: nemoguardrails.types.LLMResponse ) -> None ``` ```python nemoguardrails.actions.llm.utils._log_prompt( prompt: typing.Union[str, typing.List[dict]] ) -> None ``` Log the prompt to LLM call info. ```python nemoguardrails.actions.llm.utils._raise_llm_call_exception( exception: Exception, model: nemoguardrails.types.LLMModel ) -> typing.NoReturn ``` ```python nemoguardrails.actions.llm.utils._setup_llm_call_info( model: nemoguardrails.types.LLMModel, model_name: typing.Optional[str], model_provider: typing.Optional[str] ) -> None ``` Initialize or update LLM call info in context. ```python nemoguardrails.actions.llm.utils._store_reasoning_traces( response: nemoguardrails.types.LLMResponse ) -> None ``` ```python nemoguardrails.actions.llm.utils._store_response_metadata( response: nemoguardrails.types.LLMResponse ) -> None ``` ```python nemoguardrails.actions.llm.utils._store_tool_calls( response: nemoguardrails.types.LLMResponse ) -> None ``` ```python nemoguardrails.actions.llm.utils._stream_llm_call( model: nemoguardrails.types.LLMModel, prompt: typing.Union[str, typing.List[nemoguardrails.types.ChatMessage]], handler: nemoguardrails.streaming.StreamingHandler, stop: typing.Optional[typing.List[str]], llm_params: typing.Optional[dict] = None ) -> nemoguardrails.types.LLMResponse ``` async ```python nemoguardrails.actions.llm.utils._update_token_stats( response: nemoguardrails.types.LLMResponse ) -> None ``` ```python nemoguardrails.actions.llm.utils._update_token_stats_from_chunk( chunk: nemoguardrails.types.LLMResponseChunk ) -> None ``` ```python nemoguardrails.actions.llm.utils.escape_flow_name( name: str ) -> str ``` Escape invalid keywords in flow names. ```python nemoguardrails.actions.llm.utils.events_to_dialog_history( events: typing.List[nemoguardrails.colang.v2_x.runtime.flows.InternalEvent] ) -> str ``` Create the dialog history based on provided events. ```python nemoguardrails.actions.llm.utils.extract_bot_thinking_from_events( events: list ) ``` ```python nemoguardrails.actions.llm.utils.extract_tool_calls_from_events( events: list ) -> typing.Optional[list] ``` Extract tool\_calls from BotToolCalls events. **Parameters:** List of events to search through **Returns:** `Optional[list]` tool\_calls if found in BotToolCalls event, None otherwise ```python nemoguardrails.actions.llm.utils.flow_to_colang( flow: typing.Union[dict, nemoguardrails.colang.v2_x.lang.colang_ast.Flow] ) -> str ``` Converts a flow to colang format. Example flow: ```python - user: ask capabilities - bot: inform capabilities ``` to colang: ```python user ask capabilities bot inform capabilities ``` ```python nemoguardrails.actions.llm.utils.from_log_event_to_identifier( event_name: str ) -> str ``` convert log message to prompt interaction identifier. ```python nemoguardrails.actions.llm.utils.get_and_clear_reasoning_trace_contextvar() -> typing.Optional[str] ``` Get the current reasoning trace and clear it from the context. **Returns:** `Optional[str]` Optional\[str]: The reasoning trace if one exists, None otherwise. ```python nemoguardrails.actions.llm.utils.get_and_clear_response_metadata_contextvar() -> typing.Optional[dict] ``` Get the current response metadata and clear it from the context. **Returns:** `Optional[dict]` Optional\[dict]: The response metadata if it exists, None otherwise. ```python nemoguardrails.actions.llm.utils.get_and_clear_tool_calls_contextvar() -> typing.Optional[list] ``` Get the current tool calls and clear them from the context. **Returns:** `Optional[list]` Optional\[list]: The tool calls if they exist, None otherwise. ```python nemoguardrails.actions.llm.utils.get_colang_history( events: typing.List[dict], include_texts: bool = True, remove_retrieval_events: bool = False ) -> str ``` Creates a history of user messages and bot responses in colang format. user "Hi, how are you today?" express greeting bot express greeting "Greetings! I am the official NVIDIA Benefits Ambassador AI bot and I'm here to assist you." user "What can you help me with?" ask capabilities bot inform capabilities "As an AI, I can provide you with a wide range of services, such as ..." ```python nemoguardrails.actions.llm.utils.get_first_bot_action( strings: typing.List[str] ) -> typing.Optional[str] ``` Returns first bot action. ```python nemoguardrails.actions.llm.utils.get_first_bot_intent( strings: typing.List[str] ) -> typing.Optional[str] ``` Returns first bot intent. ```python nemoguardrails.actions.llm.utils.get_first_nonempty_line( s: str ) -> typing.Optional[str] ``` Helper that returns the first non-empty line from a string ```python nemoguardrails.actions.llm.utils.get_first_user_intent( strings: typing.List[str] ) -> typing.Optional[str] ``` Returns first user intent. ```python nemoguardrails.actions.llm.utils.get_initial_actions( strings: typing.List[str] ) -> typing.List[str] ``` Returns the first action before an empty line. ```python nemoguardrails.actions.llm.utils.get_last_bot_intent_event( events: typing.List[dict] ) -> typing.Optional[dict] ``` Returns the last user intent from the events. ```python nemoguardrails.actions.llm.utils.get_last_bot_utterance_event( events: typing.List[dict] ) -> typing.Optional[dict] ``` Returns the last bot utterance from the events. ```python nemoguardrails.actions.llm.utils.get_last_user_intent_event( events: typing.List[dict] ) -> typing.Optional[dict] ``` Returns the last user intent from the events. ```python nemoguardrails.actions.llm.utils.get_last_user_utterance( events: typing.List[dict] ) -> typing.Optional[str] ``` Returns the last user utterance from the events. ```python nemoguardrails.actions.llm.utils.get_last_user_utterance_event( events: typing.List[dict] ) -> typing.Optional[dict] ``` Returns the last user utterance from the events. ```python nemoguardrails.actions.llm.utils.get_last_user_utterance_event_v2_x( events: typing.List[dict] ) -> typing.Optional[dict] ``` Returns the last user utterance from the events. ```python nemoguardrails.actions.llm.utils.get_multiline_response( s: str ) -> str ``` Helper that extracts multi-line responses from the LLM. Stopping conditions: when a non-empty line ends with a quote or when the token "user" appears after a newline. Empty lines at the begging of the string are skipped. ```python nemoguardrails.actions.llm.utils.get_retrieved_relevant_chunks( events: typing.List[dict], skip_user_message: typing.Optional[bool] = False ) -> typing.Optional[str] ``` Returns the retrieved chunks for current user utterance from the events. ```python nemoguardrails.actions.llm.utils.get_top_k_nonempty_lines( s: str, k: int = 1 ) -> typing.Optional[typing.List[str]] ``` Helper that returns a list with the top k non-empty lines from a string. If there are less than k non-empty lines, it returns a smaller number of lines. ```python nemoguardrails.actions.llm.utils.llm_call( llm: typing.Optional[typing.Any], prompt: typing.Union[str, typing.List[dict]], model_name: typing.Optional[str] = None, model_provider: typing.Optional[str] = None, stop: typing.Optional[typing.List[str]] = None, llm_params: typing.Optional[dict] = None, streaming_handler: typing.Optional[nemoguardrails.streaming.StreamingHandler] = None ) -> nemoguardrails.types.LLMResponse ``` async ```python nemoguardrails.actions.llm.utils.remove_action_intent_identifiers( lines: typing.List[str] ) -> typing.List[str] ``` Removes the action/intent identifiers. ```python nemoguardrails.actions.llm.utils.remove_text_messages_from_history( history: str ) -> str ``` Helper that given a history in colang format, removes all texts. ```python nemoguardrails.actions.llm.utils.strip_quotes( s: str ) -> str ``` Helper that removes quotes from a string if the entire string is between quotes ```python nemoguardrails.actions.llm.utils.warn_if_truncated( response: nemoguardrails.types.LLMResponse, task: str ) -> bool ``` Return True and emit a warning if the LLM produced no visible content because it hit the max\_tokens budget. Reasoning models (OpenAI o-series, gpt-5, DeepSeek-R1, Gemini 2.5, Qwen QwQ, etc.) spend output tokens on internal reasoning before emitting visible text. A small max\_tokens budget can be fully consumed by the reasoning phase, leaving empty content and finish\_reason="length". The call succeeds silently and callers that only inspect response.content see nothing. Callers whose downstream parser does not fail safely on empty input (e.g. self\_check\_facts, whose parser inverts the result) should use the return value to take an explicit fail-safe branch. ```python nemoguardrails.actions.llm.utils.logger = logging.getLogger(__name__) ```