Implementation:Explodinggradients Ragas Utils Module

Field	Value
source	Explodinggradients_Ragas (GitHub)
domains	Utilities, Framework
last_updated	2026-02-10 00:00 GMT

Overview

The utils module provides a broad collection of utility functions and helper classes used throughout Ragas, including safe numerical operations, deprecation handling, token counting, batching, unique ID generation, progress bar management, and async-to-sync conversion.

Description

Numerical utilities: safe_nanmean computes the mean of a list ignoring NaN values, returning NaN for empty or all-NaN arrays. check_if_sum_is_close verifies that values sum to a target within a specified number of decimal places using integer arithmetic.

Deprecation: The deprecated decorator marks functions with configurable version, removal schedule, and alternative suggestions. DeprecationHelper is a class-level wrapper that emits deprecation warnings when a deprecated class is instantiated or accessed.

Token counting: num_tokens_from_string counts tokens using either a provided BaseTokenizer instance or a tiktoken encoding name.

Batching and iteration: batched splits an iterable into tuples of size n (last batch may be shorter).

ID generation: create_nano_id generates short unique identifiers by converting UUID4 integers to base-62 strings. MemorableNames generates Docker-style memorable names by combining adjectives with computer scientist names.

Progress bars: ProgressBarManager manages tqdm progress bars for both single and nested (batched) execution patterns.

Async support: async_to_sync converts async functions to sync, handling both running and non-running event loop scenarios.

Usage

Import individual utilities as needed. These functions are used internally throughout Ragas and are also available for external use in custom metrics and evaluation pipelines.

Code Reference

Item	Detail
Source Location	src/ragas/utils.py L29-697
Key Functions	safe_nanmean, deprecated, num_tokens_from_string, batched, create_nano_id, async_to_sync, camel_to_snake
Key Classes	MemorableNames, ProgressBarManager, DeprecationHelper
Import	from ragas.utils import safe_nanmean, deprecated, create_nano_id

I/O Contract

Inputs

Function	Parameter	Type	Description
safe_nanmean	arr	List[float]	List of floats (may contain NaN)
num_tokens_from_string	string	str	Text to count tokens for
num_tokens_from_string	encoding_name	str	Tiktoken encoding (default "cl100k_base")
num_tokens_from_string	tokenizer	Optional[BaseTokenizer]	Optional tokenizer (overrides encoding_name)
batched	iterable	Iterable	Iterable to split into batches
batched	n	int	Batch size (must be >= 1)
create_nano_id	size	int	Length of the ID (default 12)

Outputs

Function	Return Type	Description
safe_nanmean	float	Mean value ignoring NaN, or NaN for empty/all-NaN input
num_tokens_from_string	int	Number of tokens in the string
batched	Iterator[Tuple]	Iterator yielding tuples of size n
create_nano_id	str	Short alphanumeric unique identifier
async_to_sync	Callable	Synchronous wrapper function

Usage Examples

from ragas.utils import safe_nanmean, deprecated, create_nano_id, batched, num_tokens_from_string

# Safe mean with NaN handling
print(safe_nanmean([1.0, float('nan'), 3.0]))  # 2.0
print(safe_nanmean([]))                          # nan

# Token counting
count = num_tokens_from_string("Hello, how are you?")
print(count)  # e.g., 6

# Batching
for batch in batched(range(10), 3):
    print(batch)  # (0,1,2), (3,4,5), (6,7,8), (9,)

# Unique IDs
print(create_nano_id())       # e.g., 'a3Bf9kLm2xYz'
print(create_nano_id(size=6)) # e.g., 'k9mX2p'

# Deprecation decorator
@deprecated("0.1", removal="0.2", alternative="new_function")
def old_function():
    return "result"

Related Pages

• Tokenizers_Module - Tokenizer classes used by num_tokens_from_string
• Validation_Module - Dataset validation utilities
• MetricResult_Class - Result class whose float values are used with safe_nanmean