> This page is for version v0.24.1.
> For other versions, use one of these documentation indexes:
> - Latest (default): https://docs.nvidia.com/nemo/guardrails/latest/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.
> 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

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`](#nemoguardrails-actions-llm-utils-_extract_user_text_from_event)                           | Flatten a multimodal user-message payload into a string for colang history. |
| [`_has_unclosed_quote`](#nemoguardrails-actions-llm-utils-_has_unclosed_quote)                                               | Check if a string has an unclosed double quote (ignoring escaped quotes).   |
| [`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 runtime 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_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.    |
| [`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.            |

### Data

[`_MAX_QUOTE_CONTINUATION_LINES`](#nemoguardrails-actions-llm-utils-_MAX_QUOTE_CONTINUATION_LINES)

### API

```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:**

**`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

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

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

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

```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_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.remove_text_messages_from_history(
    history: str
) -> str
```

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

```python
nemoguardrails.actions.llm.utils._MAX_QUOTE_CONTINUATION_LINES = 50
```