nat.utils.providers

Process-wide provider hooks for generated identifiers and timestamps.

The runtime stamps workflow runs, intermediate steps, spans, function invocations, and interaction prompts and responses with freshly generated UUIDs and wall-clock timestamps. By default these come from uuid.uuid4() and time.time(), which is correct for normal execution but makes two otherwise identical runs produce different identifiers and timings.

Integrations that need reproducible runs can install their own providers. Examples include record/replay style testing, golden-file trace comparison, and integrations with runtimes that re-execute workflow code and require identifiers to be stable across re-executions.

Both hooks are process-wide and opt-in. When no provider is installed, behavior is unchanged. The setters return the previously installed provider so callers can restore it.

The id provider must return strings in canonical UUID form. Integer identifiers, such as the OpenTelemetry-style 128-bit trace ids and 64-bit span ids, are derived from the id provider by parsing the returned string, so a value that is not a valid UUID string raises ValueError at generation time.

Attributes

IdProvider	Zero-argument callable returning a new identifier as a canonical UUID string.
TimeProvider	Zero-argument callable returning the current time in fractional seconds since the Unix epoch.
_state

Classes

_ProviderState

Mutable holder for the process-wide providers. Mutated only through the module-level setters.

Functions

default_id_provider(→ str)	Return a random UUID4 string. This is the default id provider.
default_time_provider(→ float)	Return the current wall-clock time in fractional seconds. This is the default time provider.
set_id_provider(→ IdProvider)	Install provider as the process-wide id provider.
get_id_provider(→ IdProvider)	Return the currently installed id provider.
set_time_provider(→ TimeProvider)	Install provider as the process-wide time provider.
get_time_provider(→ TimeProvider)	Return the currently installed time provider.
generate_id(→ str)	Return a new identifier string from the installed id provider.
generate_trace_id(→ int)	Return a new 128-bit integer id derived from the installed id provider.
generate_span_id(→ int)	Return a new 64-bit integer id derived from the installed id provider.
current_time(→ float)	Return the current time in fractional seconds from the installed time provider.
current_time_ns(→ int)	Return the current time in integer nanoseconds from the installed time provider.

Module Contents

IdProvider

Zero-argument callable returning a new identifier as a canonical UUID string.

TimeProvider

Zero-argument callable returning the current time in fractional seconds since the Unix epoch.

default_id_provider() → str

Return a random UUID4 string. This is the default id provider.

default_time_provider() → float

Return the current wall-clock time in fractional seconds. This is the default time provider.

class _ProviderState

Mutable holder for the process-wide providers. Mutated only through the module-level setters.

id_provider: IdProvider

time_provider: TimeProvider

_state

set_id_provider(provider: IdProvider) → IdProvider

Install provider as the process-wide id provider.

Args:

provider: Zero-argument callable returning a new identifier as a canonical UUID string.

Returns:

IdProvider: The previously installed id provider, so callers can restore it.

get_id_provider() → IdProvider

Return the currently installed id provider.

set_time_provider(provider: TimeProvider) → TimeProvider

Install provider as the process-wide time provider.

Args:

provider: Zero-argument callable returning the current time in fractional seconds since the Unix epoch.

Returns:

TimeProvider: The previously installed time provider, so callers can restore it.

get_time_provider() → TimeProvider

Return the currently installed time provider.

generate_id() → str

Return a new identifier string from the installed id provider.

generate_trace_id() → int

Return a new 128-bit integer id derived from the installed id provider.

With the default provider this is equivalent to uuid.uuid4().int.

Raises:

ValueError: If the installed id provider generated a UUID whose derived trace ID is zero.

generate_span_id() → int

Return a new 64-bit integer id derived from the installed id provider.

With the default provider this is equivalent to uuid.uuid4().int >> 64.

Raises:

ValueError: If the installed id provider generated a UUID whose derived span ID is zero.

current_time() → float

Return the current time in fractional seconds from the installed time provider.

current_time_ns() → int

Return the current time in integer nanoseconds from the installed time provider.