ReferencePython SDK ReferenceNemoguardrailsLlmCache

nemoguardrails.llm.cache.utils

View as Markdown

Module Contents

Classes

Functions

Data

PROMPT_PATTERN_WHITESPACES

API

class nemoguardrails.llm.cache.utils.CacheEntry

Bases: typing.TypedDict

llm_metadata
Optional[LLMMetadataDict]
llm_stats
Optional[LLMStatsDict]
result
dict
class nemoguardrails.llm.cache.utils.LLMCacheData

Bases: typing.TypedDict

metadata
Optional[LLMMetadataDict]
stats
Optional[LLMStatsDict]
class nemoguardrails.llm.cache.utils.LLMMetadataDict

Bases: typing.TypedDict

model_name
str
provider_name
str
class nemoguardrails.llm.cache.utils.LLMStatsDict

Bases: typing.TypedDict

completion_tokens
int
prompt_tokens
int
total_tokens
int
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:

prompt
Union[str, List[dict]]

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]]
normalize_whitespace
boolDefaults to True

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:

>>> create_normalized_cache_key("Hello world")
'64ec88ca00b268e5ba1a35678a1b5316d212f4f366b2477232534a8aeca37f3c'
>>> create_normalized_cache_key([{"type": "user", "content": "Hello"}])
'b2f5c9d8e3a1f7b6c4d2e5f8a9c1d3e5f7b9a2c4d6e8f1a3b5c7d9e2f4a6b8'
nemoguardrails.llm.cache.utils.extract_llm_metadata_for_cache() -> typing.Optional[nemoguardrails.llm.cache.utils.LLMMetadataDict]
 
nemoguardrails.llm.cache.utils.extract_llm_stats_for_cache() -> typing.Optional[nemoguardrails.llm.cache.utils.LLMStatsDict]
 
nemoguardrails.llm.cache.utils.get_from_cache_and_restore_stats(
    cache: nemoguardrails.llm.cache.interface.CacheInterface,
    cache_key: str
) -> typing.Optional[dict]
 
nemoguardrails.llm.cache.utils.restore_llm_metadata_from_cache(
    cached_metadata: nemoguardrails.llm.cache.utils.LLMMetadataDict
) -> None
 
nemoguardrails.llm.cache.utils.restore_llm_stats_from_cache(
    cached_stats: nemoguardrails.llm.cache.utils.LLMStatsDict,
    cache_read_duration_s: float
) -> None
 
nemoguardrails.llm.cache.utils.PROMPT_PATTERN_WHITESPACES = re.compile('\\s+')