> 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.llm.cache.utils

## Module Contents

### Classes

| Name                                                                 | Description |
| -------------------------------------------------------------------- | ----------- |
| [`CacheEntry`](#nemoguardrails-llm-cache-utils-CacheEntry)           | -           |
| [`LLMCacheData`](#nemoguardrails-llm-cache-utils-LLMCacheData)       | -           |
| [`LLMMetadataDict`](#nemoguardrails-llm-cache-utils-LLMMetadataDict) | -           |
| [`LLMStatsDict`](#nemoguardrails-llm-cache-utils-LLMStatsDict)       | -           |

### Functions

| Name                                                                                                   | Description                                          |
| ------------------------------------------------------------------------------------------------------ | ---------------------------------------------------- |
| [`create_normalized_cache_key`](#nemoguardrails-llm-cache-utils-create_normalized_cache_key)           | Create a normalized, hashed cache key from a prompt. |
| [`extract_llm_metadata_for_cache`](#nemoguardrails-llm-cache-utils-extract_llm_metadata_for_cache)     | -                                                    |
| [`extract_llm_stats_for_cache`](#nemoguardrails-llm-cache-utils-extract_llm_stats_for_cache)           | -                                                    |
| [`get_from_cache_and_restore_stats`](#nemoguardrails-llm-cache-utils-get_from_cache_and_restore_stats) | -                                                    |
| [`restore_llm_metadata_from_cache`](#nemoguardrails-llm-cache-utils-restore_llm_metadata_from_cache)   | -                                                    |
| [`restore_llm_stats_from_cache`](#nemoguardrails-llm-cache-utils-restore_llm_stats_from_cache)         | -                                                    |

### Data

[`PROMPT_PATTERN_WHITESPACES`](#nemoguardrails-llm-cache-utils-PROMPT_PATTERN_WHITESPACES)

### API

```python
class nemoguardrails.llm.cache.utils.CacheEntry
```

**Bases:** `typing.TypedDict`

```python
class nemoguardrails.llm.cache.utils.LLMCacheData
```

**Bases:** `typing.TypedDict`

```python
class nemoguardrails.llm.cache.utils.LLMMetadataDict
```

**Bases:** `typing.TypedDict`

```python
class nemoguardrails.llm.cache.utils.LLMStatsDict
```

**Bases:** `typing.TypedDict`

```python
nemoguardrails.llm.cache.utils.create_normalized_cache_key(
    prompt: typing.Union[str, typing.List[dict]],
    normalize_whitespace: bool = True
) -> str
```

Create a normalized, hashed cache key from a prompt.

This function generates a deterministic cache key by normalizing the prompt
and applying SHA-256 hashing. The normalization ensures that semantically
equivalent prompts produce the same cache key.

**Parameters:**

The prompt to be cached. Can be:

* str: A single prompt string (for completion models)
* List\[dict]: A list of message dictionaries for chat models
  (e.g., \[\{"type": "user", "content": "Hello"}])
  Note: render\_task\_prompt() returns Union\[str, List\[dict]]

Whether to normalize whitespace characters.
When True, collapses all whitespace sequences to single spaces and
strips leading/trailing whitespace. Default: True

**Returns:** `str`

A SHA-256 hex digest string (64 characters) suitable for use as a cache key

**Raises:**

* `TypeError`: If prompt is not a str or List\[dict]

**Examples:**

```python
>>> create_normalized_cache_key("Hello world")
'64ec88ca00b268e5ba1a35678a1b5316d212f4f366b2477232534a8aeca37f3c'
```

```python
>>> create_normalized_cache_key([{"type": "user", "content": "Hello"}])
'b2f5c9d8e3a1f7b6c4d2e5f8a9c1d3e5f7b9a2c4d6e8f1a3b5c7d9e2f4a6b8'
```

```python
nemoguardrails.llm.cache.utils.extract_llm_metadata_for_cache() -> typing.Optional[nemoguardrails.llm.cache.utils.LLMMetadataDict]
```

```python
nemoguardrails.llm.cache.utils.extract_llm_stats_for_cache() -> typing.Optional[nemoguardrails.llm.cache.utils.LLMStatsDict]
```

```python
nemoguardrails.llm.cache.utils.get_from_cache_and_restore_stats(
    cache: nemoguardrails.llm.cache.interface.CacheInterface,
    cache_key: str
) -> typing.Optional[dict]
```

```python
nemoguardrails.llm.cache.utils.restore_llm_metadata_from_cache(
    cached_metadata: nemoguardrails.llm.cache.utils.LLMMetadataDict
) -> None
```

```python
nemoguardrails.llm.cache.utils.restore_llm_stats_from_cache(
    cached_stats: nemoguardrails.llm.cache.utils.LLMStatsDict,
    cache_read_duration_s: float
) -> None
```

```python
nemoguardrails.llm.cache.utils.PROMPT_PATTERN_WHITESPACES = re.compile('\\s+')
```