nemo_flow.scope#

Scope stack operations.

Scopes define the hierarchy that tool calls, LLM calls, and mark events attach to. They are the main way to model agents, tasks, and nested units of work.

Example:

import nemo_flow

with nemo_flow.scope.scope("demo-agent", nemo_flow.ScopeType.Agent) as handle:
    nemo_flow.scope.event("checkpoint", handle=handle, data={"step": 1})

Functions#

`get_handle`()	Return the current top-of-stack `ScopeHandle`.
`push`(name, scope_type, *[, handle, attributes, data, ...])	Push a new child scope and return its handle.
`pop`(handle, *[, output, timestamp])	Pop a scope previously returned by `push()` or `scope()`.
`event`(name, *[, handle, data, metadata, timestamp])	Emit a `Mark` event under the current or provided scope.
`scope`(name, scope_type, *[, handle, attributes, data, ...])	Create a scope for the duration of a `with` block.

Module Contents#

nemo_flow.scope.get_handle() → nemo_flow._native.ScopeHandle#

Return the current top-of-stack ScopeHandle.

Returns:: The scope currently at the top of the active scope stack.
Return type:: ScopeHandle

Notes

If the current Python context does not yet have a scope stack, one is created automatically before the handle lookup.

nemo_flow.scope.push( name: str, scope_type: nemo_flow._native.ScopeType, *, handle: nemo_flow._native.ScopeHandle | None = None, attributes: nemo_flow._native.ScopeAttributes | None = None, data: nemo_flow.Json | None = None, metadata: nemo_flow.Json | None = None, input: nemo_flow.Json | None = None, timestamp: datetime.datetime | None = None, ) → nemo_flow._native.ScopeHandle#

Push a new child scope and return its handle.

Parameters:

name – Human-readable name for the new scope.
scope_type – Semantic scope type, such as ScopeType.Agent or ScopeType.Function.
handle – Optional parent scope handle. When omitted, the current top-of-stack scope becomes the parent.
attributes – Optional native scope attributes attached to the emitted start event.
data – Optional JSON application payload stored on the scope handle.
metadata – Optional JSON metadata recorded on the scope start event.
input – Optional JSON payload exported as the semantic scope input.
timestamp – Optional timezone-aware datetime recorded as the handle start time and on the scope start event. When omitted, the current runtime time is used.

Returns:

Handle for the newly pushed scope.

Return type:

ScopeHandle

Notes

A scope stack is created automatically if the current context does not yet have one. timestamp must be a timezone-aware datetime; strings and naive datetimes are rejected.

Example:

import nemo_flow

with nemo_flow.scope.scope("parent", nemo_flow.ScopeType.Agent) as parent:
    handle = nemo_flow.scope.push(
        "worker",
        nemo_flow.ScopeType.Function,
        handle=parent,
        attributes=None,
        data={"step": 1},
        metadata={"source": "scope.push"},
    )
    nemo_flow.scope.pop(handle)

nemo_flow.scope.pop( handle: nemo_flow._native.ScopeHandle, *, output: nemo_flow.Json | None = None, timestamp: datetime.datetime | None = None, ) → None#

Pop a scope previously returned by push() or scope().

Parameters:

handle – Scope handle to close.
output – Optional JSON payload exported as the semantic scope output.
timestamp – Optional timezone-aware datetime recorded on the scope end event. When omitted, the runtime default end timestamp is used.

Returns:

This function returns after the scope is closed successfully.

Return type:

None

Notes

The handle must correspond to an active scope in the current scope stack. Popping a scope also removes any scope-local registrations owned by that scope. timestamp must be a timezone-aware datetime; strings and naive datetimes are rejected.

nemo_flow.scope.event( name: str, *, handle: nemo_flow._native.ScopeHandle | None = None, data: nemo_flow.Json | None = None, metadata: nemo_flow.Json | None = None, timestamp: datetime.datetime | None = None, ) → None#

Emit a Mark event under the current or provided scope.

Parameters:

name – Event name to emit.
handle – Optional scope handle that should own the event. When omitted, the current top-of-stack scope is used.
data – Optional JSON payload attached to the event.
metadata – Optional JSON metadata attached to the event.
timestamp – Optional timezone-aware datetime recorded on the mark event. When omitted, the current runtime time is used.

Returns:

This function returns after the event has been emitted.

Return type:

None

Notes

A scope stack is created automatically when needed before the event is emitted through the native runtime. timestamp must be a timezone-aware datetime; strings and naive datetimes are rejected.

nemo_flow.scope.scope( name: str, scope_type: nemo_flow._native.ScopeType, *, handle: nemo_flow._native.ScopeHandle | None = None, attributes: nemo_flow._native.ScopeAttributes | None = None, data: nemo_flow.Json | None = None, metadata: nemo_flow.Json | None = None, input: nemo_flow.Json | None = None, timestamp: datetime.datetime | None = None, end_timestamp: datetime.datetime | None = None, ) → Iterator[nemo_flow._native.ScopeHandle]#

Create a scope for the duration of a with block.

Parameters:

name – Human-readable name for the new scope.
scope_type – Semantic scope type, such as ScopeType.Agent or ScopeType.Function.
handle – Optional parent scope handle. When omitted, the current top-of-stack scope becomes the parent.
attributes – Optional native scope attributes attached to the emitted start event.
data – Optional JSON application payload stored on the scope handle.
metadata – Optional JSON metadata recorded on the scope start event.
input – Optional JSON payload exported as the semantic scope input.
timestamp – Optional timezone-aware datetime recorded as the handle start time and on the scope start event.
end_timestamp – Optional timezone-aware datetime recorded on the scope end event.

Yields:

ScopeHandle – Handle for the scope that remains active inside the with block.

Notes

The scope is always popped when the with block exits, even if the body raises an exception. Timestamp arguments must be timezone-aware datetime objects; strings and naive datetimes are rejected.

Example:

import nemo_flow

with nemo_flow.scope.scope(
    "demo",
    nemo_flow.ScopeType.Agent,
    handle=None,
    attributes=None,
    data={"stage": "start"},
    metadata={"owner": "docs"},
) as handle:
    nemo_flow.scope.event("inside", handle=handle, data={"ok": True}, metadata={"step": 1})