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

Cache interface for NeMo Guardrails caching system.

This module defines the abstract base class for cache implementations
that can be used interchangeably throughout the guardrails system.

## Module Contents

### Classes

| Name                                                                   | Description                                                           |
| ---------------------------------------------------------------------- | --------------------------------------------------------------------- |
| [`CacheInterface`](#nemoguardrails-llm-cache-interface-CacheInterface) | Abstract base class defining the interface for cache implementations. |

### API

```python
class nemoguardrails.llm.cache.interface.CacheInterface()
```

Abstract

Abstract base class defining the interface for cache implementations.

All cache implementations must inherit from this class and implement
the required methods to ensure compatibility with the caching system.

Get the maximum size of the cache.

```python
nemoguardrails.llm.cache.interface.CacheInterface.clear() -> None
```

abstract

Remove all items from the cache.

After calling this method, the cache should be empty.

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

Check if a key exists in the cache.

This is an optional method that can be overridden for efficiency.
The default implementation uses get() to check existence.

**Parameters:**

The key to check.

**Returns:** `bool`

True if the key exists in the cache, False otherwise.

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

abstract

Retrieve an item from the cache.

**Parameters:**

The key to look up in the cache.

Value to return if key is not found (default: None).

**Returns:** `Any`

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

```python
nemoguardrails.llm.cache.interface.CacheInterface.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.

This is an optional method with a default implementation. Cache
implementations should override this for better thread-safety guarantees.

**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.interface.CacheInterface.get_stats() -> dict
```

Get cache statistics.

The default implementation returns a message indicating that
statistics tracking is not supported.

**Returns:** `dict`

Dictionary with cache statistics. The format and contents

```python
nemoguardrails.llm.cache.interface.CacheInterface.is_empty() -> bool
```

abstract

Check if the cache is empty.

**Returns:** `bool`

True if the cache contains no items, False otherwise.

```python
nemoguardrails.llm.cache.interface.CacheInterface.log_stats_now() -> None
```

Force immediate logging of cache statistics.

This is an optional method that cache implementations can override
if they support statistics logging. The default implementation does nothing.

Implementations that support statistics logging should output the
current cache statistics to their configured logging backend.

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

abstract

Store an item in the cache.

If the cache is at maxsize, this method should evict an item
according to the cache's eviction policy (e.g., LFU, LRU, etc.).

**Parameters:**

The key to store.

The value to associate with the key.

```python
nemoguardrails.llm.cache.interface.CacheInterface.reset_stats() -> None
```

Reset cache statistics.

This is an optional method that cache implementations can override
if they support statistics tracking. The default implementation does nothing.

```python
nemoguardrails.llm.cache.interface.CacheInterface.size() -> int
```

abstract

Get the current number of items in the cache.

**Returns:** `int`

The number of items currently stored in the cache.

```python
nemoguardrails.llm.cache.interface.CacheInterface.supports_stats_logging() -> bool
```

Check if this cache implementation supports statistics logging.

The default implementation returns False. Cache implementations
that support statistics logging should override this to return True
when logging is enabled.

**Returns:** `bool`

True if the cache supports statistics logging, False otherwise.