Function scope

python/nemo_relay/scope.py:207–288

Create a scope for the duration of a ``with`` block. OTEL status codes will be automatically recorded in the scope's metadata. Args: name: Human-readable name for the new scope. scope_type: Semantic scope type, such as ``ScopeType.Agent`` or ``ScopeType.Function

(
    name: str,
    scope_type: ScopeType,
    *,
    handle: ScopeHandle | None = None,
    attributes: ScopeAttributes | None = None,
    data: Json | None = None,
    metadata: Json | None = None,
    input: Json | None = None,
    timestamp: datetime | None = None,
    end_timestamp: datetime | None = None,
)

@contextmanager
def scope(
    name: str,
    scope_type: ScopeType,
    *,
    handle: ScopeHandle | None = None,
    attributes: ScopeAttributes | None = None,
    data: Json | None = None,
    metadata: Json | None = None,
    input: Json | None = None,
    timestamp: datetime | None = None,
    end_timestamp: datetime | None = None,
) -> Iterator[ScopeHandle]:
    """Create a scope for the duration of a ``with`` block.

    OTEL status codes will be automatically recorded in the scope's metadata.

    Args:
        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_relay

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