nemoguardrails.actions.llm.utils | NVIDIA NeMo Guardrails Library Developer Guide

Colang-facing helpers for the LLM generation path.

Conversation-history rendering, event accessors, and the completion parsers that depend on Colang intent/action vocabulary, used by the Colang runtimes and by nemoguardrails.actions.llm.generation.

This module imports the Colang v2.x AST and runtime, so importing it pulls in the Colang runtime. Two groups of helpers were moved out for that reason, and are re-exported below so existing imports keep working:

model invocation -> :mod:nemoguardrails.llm.call
Colang-free completion text helpers -> :mod:nemoguardrails.llm.completion_parsing

Prefer importing those from their canonical modules; a rail action that imports them from here will drag the Colang runtime into its dependency graph.

Module Contents

Functions

Name	Description
`_extract_user_text_from_event`	Flatten a multimodal user-message payload into a string for colang history.
`_has_unclosed_quote`	Check if a string has an unclosed double quote (ignoring escaped quotes).
`escape_flow_name`	Escape invalid keywords in flow names.
`events_to_dialog_history`	Create the dialog history based on provided events.
`extract_bot_thinking_from_events`	-
`extract_tool_calls_from_events`	Extract tool_calls from runtime events.
`flow_to_colang`	Converts a flow to colang format.
`from_log_event_to_identifier`	convert log message to prompt interaction identifier.
`get_and_clear_reasoning_trace_contextvar`	Get the current reasoning trace and clear it from the context.
`get_and_clear_response_metadata_contextvar`	Get the current response metadata and clear it from the context.
`get_and_clear_tool_calls_contextvar`	Get the current tool calls and clear them from the context.
`get_colang_history`	Creates a history of user messages and bot responses in colang format.
`get_first_bot_action`	Returns first bot action.
`get_first_bot_intent`	Returns first bot intent.
`get_first_nonempty_line`	Helper that returns the first non-empty line from a string
`get_first_user_intent`	Returns first user intent.
`get_initial_actions`	Returns the first action before an empty line.
`get_last_bot_intent_event`	Returns the last user intent from the events.
`get_last_bot_utterance_event`	Returns the last bot utterance from the events.
`get_last_user_intent_event`	Returns the last user intent from the events.
`get_last_user_utterance`	Returns the last user utterance from the events.
`get_last_user_utterance_event`	Returns the last user utterance from the events.
`get_last_user_utterance_event_v2_x`	Returns the last user utterance from the events.
`get_retrieved_relevant_chunks`	Returns the retrieved chunks for current user utterance from the events.
`get_top_k_nonempty_lines`	Helper that returns a list with the top k non-empty lines from a string.
`remove_text_messages_from_history`	Helper that given a history in colang format, removes all texts.

Data

_MAX_QUOTE_CONTINUATION_LINES

API

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:

event_text

Union[str, List[Dict[str, Any]]]

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

nemoguardrails.actions.llm.utils._has_unclosed_quote(
    s: str
) -> bool

Check if a string has an unclosed double quote (ignoring escaped quotes).

nemoguardrails.actions.llm.utils.escape_flow_name(
    name: str
) -> str

Escape invalid keywords in flow names.

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.

nemoguardrails.actions.llm.utils.extract_bot_thinking_from_events(
    events: list
)

nemoguardrails.actions.llm.utils.extract_tool_calls_from_events(
    events: list
) -> typing.Optional[list]

Extract tool_calls from runtime events.

StartToolCallBotAction carries the tool calls that passed tool-output rails and should be returned to the caller. BotToolCalls is used as a fallback for paths that do not emit the post-rail action event.

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:

  - user: ask capabilities
  - bot: inform capabilities

to colang:

user ask capabilities
bot inform capabilities

nemoguardrails.actions.llm.utils.from_log_event_to_identifier(
    event_name: str
) -> str

convert log message to prompt interaction identifier.

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.

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.

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.

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 …”

nemoguardrails.actions.llm.utils.get_first_bot_action(
    strings: typing.List[str]
) -> typing.Optional[str]

Returns first bot action.

nemoguardrails.actions.llm.utils.get_first_bot_intent(
    strings: typing.List[str]
) -> typing.Optional[str]

Returns first bot intent.

nemoguardrails.actions.llm.utils.get_first_nonempty_line(
    s: str
) -> typing.Optional[str]

Helper that returns the first non-empty line from a string

nemoguardrails.actions.llm.utils.get_first_user_intent(
    strings: typing.List[str]
) -> typing.Optional[str]

Returns first user intent.

nemoguardrails.actions.llm.utils.get_initial_actions(
    strings: typing.List[str]
) -> typing.List[str]

Returns the first action before an empty line.

nemoguardrails.actions.llm.utils.get_last_bot_intent_event(
    events: typing.List[dict]
) -> typing.Optional[dict]

Returns the last user intent from the events.

nemoguardrails.actions.llm.utils.get_last_bot_utterance_event(
    events: typing.List[dict]
) -> typing.Optional[dict]

Returns the last bot utterance from the events.

nemoguardrails.actions.llm.utils.get_last_user_intent_event(
    events: typing.List[dict]
) -> typing.Optional[dict]

Returns the last user intent from the events.

nemoguardrails.actions.llm.utils.get_last_user_utterance(
    events: typing.List[dict]
) -> typing.Optional[str]

Returns the last user utterance from the events.

nemoguardrails.actions.llm.utils.get_last_user_utterance_event(
    events: typing.List[dict]
) -> typing.Optional[dict]

Returns the last user utterance from the events.

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.

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.

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.

nemoguardrails.actions.llm.utils.remove_text_messages_from_history(
    history: str
) -> str

Helper that given a history in colang format, removes all texts.

nemoguardrails.actions.llm.utils._MAX_QUOTE_CONTINUATION_LINES = 50