Rmj" dZddlmZddlmZddlmZddlmZddlm Z ddl m Z ddl mZmZmZdd l mZdd l mZdd l mZdd l mZd,dZdddddddd-d Zdddd!d.d$Zddddd%d/d&Zedddddddd'd0d*Zgd+ZdS)1azScope 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_relay with nemo_relay.scope.scope("demo-agent", nemo_relay.ScopeType.Agent) as handle: nemo_relay.scope.event("checkpoint", handle=handle, data={"step": 1}) ) annotations)contextmanager)datetime)Iterator)Json)ensure_scope_stack)ScopeAttributes ScopeHandle ScopeType)event) get_handle) pop_scope) push_scopereturnr c:ttS)a$Return the current top-of-stack ``ScopeHandle``. Returns: ScopeHandle: The scope currently at the top of the active scope stack. Notes: If the current Python context does not yet have a scope stack, one is created automatically before the handle lookup. )_ensure_scope_stack_native_get_handleX/home/thesage/.hermes/hermes-agent/venv/lib/python3.11/site-packages/nemo_relay/scope.pyr r ,s   rNhandle attributesdatametadatainput timestampnamestr scope_typer rScopeHandle | NonerScopeAttributes | Noner Json | Nonerrrdatetime | Nonec Ltt||||||||S)aAPush a new child scope and return its handle. 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. When omitted, the current runtime time is used. Returns: ScopeHandle: Handle for the newly pushed scope. 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_relay with nemo_relay.scope.scope("parent", nemo_relay.ScopeType.Agent) as parent: handle = nemo_relay.scope.push( "worker", nemo_relay.ScopeType.Function, handle=parent, attributes=None, data={"step": 1}, metadata={"source": "scope.push"}, ) nemo_relay.scope.pop(handle) r)r_native_push_scope)rr rrrrrrs rpushr':s@f       routputrrr)NonecHtt||||dS)aAPop a scope previously returned by ``push()`` or ``scope()``. Args: handle: Scope handle to close. output: Optional JSON payload exported as the semantic scope output. metadata: Optional JSON metadata to append to the metadata set when the scope was created. timestamp: Optional timezone-aware ``datetime`` recorded on the scope end event. When omitted, the runtime default end timestamp is used. Returns: None: This function returns after the scope is closed successfully. 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. r(N)r_native_pop_scope)rr)rrs rpopr-zs-*fVh)TTTTTTrrrrrcJtt|||||dS)a<Emit a ``Mark`` event under the current or provided scope. Args: 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: None: This function returns after the event has been emitted. 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. r.N)r _native_event)rrrrrs rr r s/6$vD8yYYYYYYr)rrrrrr end_timestampr1Iterator[ScopeHandle]c #FKtd} d} d} t||||||||} | Vd} n$#t$r} d} t| } d} ~ wwxYw | d| i}| | |d<t | ||dSdS#| d| i}| | |d<t | ||wwxYw) aCreate 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}) NUNSETrOKERRORzotel.status_codezotel.status_description)rr)rr& Exceptionrr-) rr rrrrrrr1 pushed_handle status_codestatus_messagees rscoper<s)pMKNK*  !      Q    $*K8H)6D23  M J J J J J J % $= $*K8H)6D23  M J J J J J %s&6A> AAAA>>"B )r r r-r'r<)rr )rrr r rr!rr"rr#rr#rr#rr$rr ) rr r)r#rr#rr$rr*) rrrr!rr#rr#rr$rr*)rrr r rr!rr"rr#rr#rr#rr$r1r$rr2)__doc__ __future__r contextlibrrtypingr nemo_relayrnemo_relay._contextrrnemo_relay._nativer r r r r0r rrr,rr&r'r-r<__all__rrrrEs.  #"""""%%%%%%IIIIII      $"&)- !%======B37PTswUUUUUU8"& !% ZZZZZZ> "&)- !%%)QKQKQKQKQKQKh : 9 9r