`mod scope`#

module scope#

Scope stack lifecycle and mark-event entry points.

Functions

fn event(params: EmitMarkEventParams<'_>) -> Result<()>#

Emit a standalone mark event under the current or provided scope.

This creates a point-in-time lifecycle event without pushing or popping a new scope.

Parameters

name: Event name to emit.
parent: Optional explicit parent scope. When None, the current top of stack is used.
data: Optional JSON payload recorded on the emitted event.
metadata: Optional JSON metadata recorded on the emitted event.
timestamp: Optional timestamp recorded on the emitted mark event. When None, the current UTC time is used.

Returns

A Result that is Ok(()) after the event has been emitted.

Errors

Returns an error when the runtime owner check fails or when internal state cannot be read safely.

Notes

Scope-local subscribers attached to ancestor scopes observe the emitted mark event just like scope, tool, and LLM lifecycle events.

fn get_handle() -> Result<ScopeHandle>#: Return the current scope at the top of the active stack.

This reads the task-local or thread-local scope stack without mutating it and returns a clone of the current top-most ScopeHandle.

Returns

A Result containing the current ScopeHandle when the runtime owner check succeeds.

Errors

Returns an error when the current binding has not initialized the shared runtime ownership correctly.

fn pop_scope(params: PopScopeParams<'_>) -> Result<()>#

Pop the current scope from the active scope stack.

This emits a scope-end event for the target scope and removes any scope-local registrations owned by that scope.

Parameters

handle_uuid: UUID of the scope that should be popped.
output: Optional JSON payload exported as the semantic scope output.
timestamp: Optional timestamp recorded on the emitted end event. When None, the runtime uses the current UTC time, or one microsecond after the handle start time if the current time is not later.

Returns

A Result that is Ok(()) when the scope was popped successfully.

Errors

Returns FlowError::InvalidArgument when the target scope exists but is not the current top of stack, and FlowError::NotFound when the UUID is unknown to the active stack.

Notes

The implicit root scope cannot be removed.

fn push_scope(params: PushScopeParams<'_>) -> Result<ScopeHandle>#

Push a new scope onto the active scope stack.

This creates a new ScopeHandle, emits a scope-start event to global and scope-local subscribers, and makes the new scope the current top of stack.

Parameters

name: Human-readable scope name recorded on emitted lifecycle events.
scope_type: Semantic category for the new scope.
parent: Optional explicit parent scope. When None, the current top of stack is used as the parent.
attributes: Bitflags that modify scope behavior and observability.
data: Optional application payload stored on the returned handle.
metadata: Optional JSON metadata recorded on the emitted start event.
input: Optional JSON payload exported as the ATOF data payload.
timestamp: Optional timestamp recorded as the handle start time and on the emitted start event. When None, the current UTC time is used.

Returns

A Result containing the newly created ScopeHandle.

Errors

Returns an error when the runtime owner check fails or when internal state cannot be read safely.

Notes

Scope-local subscribers attached to ancestor scopes observe the emitted start event before the function returns.

Enums

enum HandleAttributes#

Attribute bitflags attached to a concrete handle kind.

Scope(ScopeAttributes)#: Scope-specific attributes.

Tool(ToolAttributes)#: Tool-specific attributes.

Llm(LlmAttributes)#: LLM-specific attributes.

enum ScopeType#

Semantic category attached to a scope lifecycle span.

Agent#: A top-level agent or workflow scope.

Function#: A generic function or application step.

Tool#: A tool lifecycle scope.

Llm#: An LLM lifecycle scope.

Retriever#: A retrieval step such as document search.

Embedder#: An embedding generation step.

Reranker#: A reranking step.

Guardrail#: A guardrail or validation step.

Evaluator#: An evaluation or scoring step.

Custom#: A caller-defined custom scope category.

Unknown#: A fallback for unknown or unsupported scope categories.

Implementations

impl ScopeType#

Functions

const fn as_str(self) -> &'static str#: Return the stable lowercase string form used for encoded scope types.

Traits implemented

impl From<&EventCategory> for ScopeType#

Structs and Unions

struct CreateScopeHandleParams<'a>#

Builder parameters for NemoFlowContextState::create_scope_handle.

name: &'a str#: Human-readable scope name.

parent_uuid: Option<Uuid>#: Optional parent scope UUID.

scope_type: ScopeType#: Semantic category of the scope.

attributes: ScopeAttributes#: Scope attribute bitflags.

data: Option<Json>#: Optional application payload stored on the handle.

metadata: Option<Json>#: Optional metadata stored on the handle.

timestamp: Option<DateTime<Utc>>#: Optional timestamp captured as the handle start time and reused by the emitted start event. When omitted, the current UTC time is used.

struct EmitMarkEventParams<'a>#

Builder parameters for event.

name: &'a str#: Event name to emit.

parent: Option<&'a ScopeHandle>#: Optional explicit parent scope.

data: Option<Json>#: Optional JSON payload recorded as the mark data.

metadata: Option<Json>#: Optional JSON metadata recorded on the emitted event.

timestamp: Option<DateTime<Utc>>#: Optional timestamp recorded on the emitted mark event. When omitted, the current UTC time is used.

struct EndScopeHandleParams<'a>#

Builder parameters for NemoFlowContextState::build_scope_end_event.

handle: &'a ScopeHandle#: Scope handle to serialize into the emitted end event.

data: Option<Json>#: Optional JSON payload exported as the semantic scope output.

timestamp: Option<DateTime<Utc>>#: Optional timestamp recorded on the emitted end event. When omitted, the runtime records the current UTC time, or one microsecond after the handle start time if the current time is not later.

struct PopScopeParams<'a>#

Builder parameters for pop_scope.

handle_uuid: &'a Uuid#: UUID of the scope that should be popped.

output: Option<Json>#: Optional JSON payload exported as the semantic scope output.

timestamp: Option<DateTime<Utc>>#: Optional timestamp recorded on the emitted end event. When omitted, the runtime records the current UTC time, or one microsecond after the handle start time if the current time is not later.

struct PushScopeParams<'a>#

Builder parameters for push_scope.

name: &'a str#: Human-readable scope name recorded on emitted lifecycle events.

scope_type: ScopeType#: Semantic category for the new scope.

parent: Option<&'a ScopeHandle>#: Optional explicit parent scope.

attributes: ScopeAttributes#: Scope attribute bitflags applied to the new scope.

data: Option<Json>#: Optional application payload stored on the scope handle.

metadata: Option<Json>#: Optional JSON metadata recorded on the emitted start event.

input: Option<Json>#: Optional JSON payload exported as the scope start event data.

timestamp: Option<DateTime<Utc>>#: Optional timestamp recorded on the emitted start event.

struct ScopeHandle#

Runtime-owned handle identifying an active or completed scope.

uuid: Uuid#: Unique scope identifier.

started_at: DateTime<Utc>#: Timestamp captured when the scope handle was created.

scope_type: ScopeType#: Semantic category of the scope.

name: String#: Human-readable scope name.

data: Option<Json>#: Optional application payload stored on the handle.

metadata: Option<Json>#: Optional metadata attached to the scope.

attributes: ScopeAttributes#: Scope behavior flags.

parent_uuid: Option<Uuid>#: UUID of the parent scope, if any.

mod scope#

`mod scope`#