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

Least Frequently Used (LFU) cache implementation.

## Module Contents

### Classes

| Name                                                                 | Description                                                   |
| -------------------------------------------------------------------- | ------------------------------------------------------------- |
| [`DoublyLinkedList`](#nemoguardrails-llm-cache-lfu-DoublyLinkedList) | Doubly linked list to maintain nodes with the same frequency. |
| [`LFUCache`](#nemoguardrails-llm-cache-lfu-LFUCache)                 | Least Frequently Used (LFU) Cache implementation.             |
| [`LFUNode`](#nemoguardrails-llm-cache-lfu-LFUNode)                   | Node for the LFU cache doubly linked list.                    |

### Data

[`log`](#nemoguardrails-llm-cache-lfu-log)

### API

```python
class nemoguardrails.llm.cache.lfu.DoublyLinkedList()
```

Doubly linked list to maintain nodes with the same frequency.

```python
nemoguardrails.llm.cache.lfu.DoublyLinkedList.append(
    node: nemoguardrails.llm.cache.lfu.LFUNode
) -> None
```

Add node to the end of the list (before tail).

```python
nemoguardrails.llm.cache.lfu.DoublyLinkedList.pop(
    node: typing.Optional[nemoguardrails.llm.cache.lfu.LFUNode] = None
) -> typing.Optional[nemoguardrails.llm.cache.lfu.LFUNode]
```

Remove and return a node. If no node specified, removes the first node.

```python
class nemoguardrails.llm.cache.lfu.LFUCache(
    maxsize: int,
    track_stats: bool = False,
    stats_logging_interval: typing.Optional[float] = None
)
```

**Bases:** [CacheInterface](/guardrails-python-sdk/nemoguardrails/llm/cache/interface#nemoguardrails-llm-cache-interface-CacheInterface)

Least Frequently Used (LFU) Cache implementation.

When the cache reaches maxsize, it evicts the least frequently used item.
If there are ties in frequency, it evicts the least recently used among them.

Get the maximum size of the cache.

```python
nemoguardrails.llm.cache.lfu.LFUCache._check_and_log_stats() -> None
```

Check if enough time has passed and log stats if needed.

```python
nemoguardrails.llm.cache.lfu.LFUCache._evict_lfu() -> None
```

Evict the least frequently used item from the cache.

```python
nemoguardrails.llm.cache.lfu.LFUCache._log_stats() -> None
```

Log current cache statistics.

```python
nemoguardrails.llm.cache.lfu.LFUCache._update_node_freq(
    node: nemoguardrails.llm.cache.lfu.LFUNode
) -> None
```

Update the frequency of a node and move it to the appropriate frequency list.

```python
nemoguardrails.llm.cache.lfu.LFUCache.clear() -> None
```

Clear all items from the cache.

```python
nemoguardrails.llm.cache.lfu.LFUCache.contains(
    key: typing.Any
) -> bool
```

Check if a key exists in the cache without updating its frequency.

This is more efficient than the default implementation which uses get()
and has the side effect of updating frequency counts.

**Parameters:**

The key to check

**Returns:** `bool`

True if the key exists in the cache, False otherwise

```python
nemoguardrails.llm.cache.lfu.LFUCache.get(
    key: typing.Any,
    default: typing.Any = None
) -> typing.Any
```

Get an item from the cache.

**Parameters:**

The key to look up

Value to return if key is not found

**Returns:** `Any`

The value associated with the key, or default if not found

```python
nemoguardrails.llm.cache.lfu.LFUCache.get_or_compute(
    key: typing.Any,
    compute_fn: typing.Callable[[], typing.Any],
    default: typing.Any = None
) -> typing.Any
```

async

Atomically get a value from the cache or compute it if not present.

This method ensures that the compute function is called at most once
even in the presence of concurrent requests for the same key.

**Parameters:**

The key to look up

Async function to compute the value if key is not found

Value to return if compute\_fn raises an exception

**Returns:** `Any`

The cached value or the computed value

```python
nemoguardrails.llm.cache.lfu.LFUCache.get_stats() -> dict
```

Get cache statistics.

**Returns:** `dict`

Dictionary with cache statistics (if tracking is enabled)

```python
nemoguardrails.llm.cache.lfu.LFUCache.is_empty() -> bool
```

Check if the cache is empty.

```python
nemoguardrails.llm.cache.lfu.LFUCache.log_stats_now() -> None
```

Force immediate logging of cache statistics.

```python
nemoguardrails.llm.cache.lfu.LFUCache.put(
    key: typing.Any,
    value: typing.Any
) -> None
```

Put an item into the cache.

**Parameters:**

The key to store

The value to associate with the key

```python
nemoguardrails.llm.cache.lfu.LFUCache.reset_stats() -> None
```

Reset cache statistics.

```python
nemoguardrails.llm.cache.lfu.LFUCache.size() -> int
```

Return the current size of the cache.

```python
nemoguardrails.llm.cache.lfu.LFUCache.supports_stats_logging() -> bool
```

Check if this cache instance supports stats logging.

```python
class nemoguardrails.llm.cache.lfu.LFUNode(
    key: typing.Any,
    value: typing.Any
)
```

Node for the LFU cache doubly linked list.

```python
nemoguardrails.llm.cache.lfu.log = logging.getLogger(__name__)
```