
    CjA                       % S SK Jr  S SKrS SKrS SKrS SKrS SKJr  S SKJ	r	  S SK
JrJr  S SKJr  SSKJr  S	S
KJr  S	SKJr  S	SKJr   " S S\R,                  5      rSS jr\ " S S5      5       rSr\" 5       rS\S'   \R:                  " 5       rS S jrS!S jr  " S S\5      r!SS.S"S jjr" " S S\5      r#\#" 5       r$ " S S\5      r%g)#    )annotationsN)OrderedDict)Mapping)	dataclassfield)Any   )logger   )util)TracingProcessor)Scopec                     \ rS rSrSr\R                  SS j5       r\R                  S 5       r\R                  SSS jj5       r	\R                  SSS jj5       r
\\R                  SS j5       5       r\\R                  SS	 j5       5       r\R                  SS
 j5       r\\R                  SS j5       5       rSS.SS jjrSrg)Trace   a  A complete end-to-end workflow containing related spans and metadata.

A trace represents a logical workflow or operation (e.g., "Customer Service Query"
or "Code Generation") and contains all the spans (individual operations) that occur
during that workflow.

Example:
    ```python
    # Basic trace usage
    with trace("Order Processing") as t:
        validation_result = await Runner.run(validator, order_data)
        if validation_result.approved:
            await Runner.run(processor, order_data)

    # Trace with metadata and grouping
    with trace(
        "Customer Service",
        group_id="chat_123",
        metadata={"customer": "user_456"}
    ) as t:
        result = await Runner.run(support_agent, query)
    ```

Notes:
    - Use descriptive workflow names
    - Group related traces with consistent group_ids
    - Add relevant metadata for filtering/analysis
    - Use context managers for reliable cleanup
    - Consider privacy when adding trace data
c                    g N selfs    g/home/rurouni/.local/share/pipx/venvs/strix-agent/lib/python3.13/site-packages/agents/tracing/traces.py	__enter__Trace.__enter__2           c                    g r   r   r   exc_typeexc_valexc_tbs       r   __exit__Trace.__exit__6   r   r   Fc                    g)a@  Start the trace and optionally mark it as the current trace.

Args:
    mark_as_current: If true, marks this trace as the current trace
        in the execution context.

Notes:
    - Must be called before any spans can be added
    - Only one trace can be current at a time
    - Thread-safe when using mark_as_current
Nr   r   mark_as_currents     r   startTrace.start:        	r   c                    g)a*  Finish the trace and optionally reset the current trace.

Args:
    reset_current: If true, resets the current trace to the previous
        trace in the execution context.

Notes:
    - Must be called to complete the trace
    - Finalizes all open spans
    - Thread-safe when using reset_current
Nr   r   reset_currents     r   finishTrace.finishI   r(   r   c                    g)a  Get the unique identifier for this trace.

Returns:
    str: The trace's unique ID in the format 'trace_<32_alphanumeric>'

Notes:
    - IDs are globally unique
    - Used to link spans to their parent trace
    - Can be used to look up traces in the dashboard
Nr   r   s    r   trace_idTrace.trace_idX   r(   r   c                    g)a  Get the human-readable name of this workflow trace.

Returns:
    str: The workflow name (e.g., "Customer Service", "Data Processing")

Notes:
    - Should be descriptive and meaningful
    - Used for grouping and filtering in the dashboard
    - Helps identify the purpose of the trace
Nr   r   s    r   name
Trace.nameg   r(   r   c                    g)a  Export the trace data as a serializable dictionary.

Returns:
    dict | None: Dictionary containing trace data, or None if tracing is disabled.

Notes:
    - Includes all spans and their data
    - Used for sending traces to backends
    - May include metadata and group ID
Nr   r   s    r   exportTrace.exportv   s     	r   c                    g)z;The API key to use when exporting this trace and its spans.Nr   r   s    r   tracing_api_keyTrace.tracing_api_key   s     	r   include_tracing_api_keyc                   U R                  5       nUc  g[        U5      nU(       a   U R                  (       a  U R                  US'   U$ )zSerialize trace metadata for persistence or transport.

Args:
    include_tracing_api_key: When True, include the tracing API key. Defaults to False
        to avoid persisting secrets unintentionally.
Nr8   )r5   dictr8   )r   r;   exportedpayloads       r   to_jsonTrace.to_json   sB     ;;=x."t';';)-)=)=G%&r   r   Nreturnr   Fr%   boolr+   rF   rC   strrC   dict[str, Any] | NonerC   
str | Noner;   rF   rC   rK   )__name__
__module____qualname____firstlineno____doc__abcabstractmethodr   r!   r&   r,   propertyr/   r2   r5   r8   r@   __static_attributes__r   r   r   r   r      s    > 	  	  	  	        	     :?  r   r   c                p    U c  g [         R                  " U R                  S5      5      R                  5       $ )Nzutf-8)hashlibsha256encode	hexdigestr8   s    r   _hash_tracing_api_keyr^      s0     >>/009:DDFFr   c                      \ rS rSr% SrSrS\S'   SrS\S'   SrS\S'   Sr	S\S	'   Sr
S\S
'   SrS\S'   SrS\S'   \" \S9rS\S'   \SS j5       r\SS j5       rSS.SS jjrSrg)
TraceState   z6Serializable trace metadata for run state persistence.NrM   r/   workflow_namegroup_idrK   metadatar8   tracing_api_key_hashobject_type)default_factoryzdict[str, Any]extrac                J    Uc  g UR                  SS9nU R                  U5      $ )NTr:   )r@   	from_json)clstracer?   s      r   
from_traceTraceState.from_trace   s)    =---=}}W%%r   c                   U(       d  g [        U5      nUR                  SS 5      nUR                  SS 5      =(       d    UR                  SS 5      nUR                  SS 5      nUR                  SS 5      nUR                  SS 5      n[        U[         5      (       a  UOS nUR                  SS 5      n	UR                  SS 5      n
[        U	[        5      (       a  U	OS n[	        U5      nUc  [        U
[        5      (       a  U
nU " [        U[        5      (       a  UOS [        U[        5      (       a  UOS [        U[        5      (       a  UOS UUU[        U[        5      (       a  UUS	9$ S US	9$ )
Nobjectidr/   rb   rc   rd   r8   re   )r/   rb   rc   rd   r8   re   rf   rh   )r=   pop
isinstancerI   r^   )rk   r?   datarf   r/   rb   rc   metadata_valuerd   r8   re   resolved_tracing_api_keyresolved_tracing_api_key_hashs                r   rj   TraceState.from_json   sT   G}hhx.88D$'E488J+E$788J-*d3%/%E%E>4((#4d;#xx(>E6@RU6V6V?\` (=>V(W% )0Z@TVY5Z5Z,@)!+Hc!:!:X+5mS+I+I-t!+Hc!:!:X4!>'1+s'C'C	
 		
 JN	
 		
r   Fr:   c                  U R                   c`  U R                  cS  U R                  cF  U R                  c9  U R                  c,  U R
                  c  U R                  c  U R                  (       d  g 0 nU R                  (       a  U R                  US'   U R                   (       a  U R                   US'   U R                  b  U R                  US'   U R                  b  U R                  US'   U R                  b  [        U R                  5      US'   U(       a   U R                  (       a  U R                  US'   U R
                  (       a  U R
                  US'   U R                  R                  5        H  u  p4X2;  d  M  XBU'   M     U$ )Nrp   rq   rb   rc   rd   r8   re   )
r/   rb   rc   rd   r8   re   rf   rh   r=   items)r   r;   r?   keyvalues        r   r@   TraceState.to_json   sB   MM!""*%%$$,))1  (JJ"$ $ 0 0GH== MMGDM)'+'9'9GO$==$"&--GJ==$"&t}}"5GJ"t';';)-)=)=G%&$$ /3.G.GG*+****,JC!$ - r   r   )rl   Trace | NonerC   TraceState | None)r?   zMapping[str, Any] | NonerC   r   rN   )rO   rP   rQ   rR   rS   r/   __annotations__rb   rc   rd   r8   re   rf   r   r=   rh   classmethodrm   rj   r@   rW   r   r   r   r`   r`      s    @Hj $M:$Hj&*H#*"&OZ&'+*+"K"!$7E>7& & 
 
: :?    r   r`   i   zOrderedDict[str, None]_started_trace_idsc                8   U (       a  U S:X  a  g [            U [        ;   a  [        R                  U 5        O	S [        U '   [        [        5      [        :  a,  [        R                  SS9  [        [        5      [        :  a  M,  S S S 5        g ! , (       d  f       g = f)Nno-opF)last)_started_trace_ids_lockr   move_to_endlen_MAX_STARTED_TRACE_IDSpopitemr/   s    r   _mark_trace_id_startedr      sq    x7*	 ))**84+/x($%(>>&&E&2 $%(>> 
!	 	 s   A+B
Bc                r    U (       a  U S:X  a  g[            U [        ;   sS S S 5        $ ! , (       d  f       g = f)Nr   F)r   r   r   s    r   _trace_id_was_startedr   	  s'    x7*	 -- 
!	 	 s   	(
6c                      \ rS rSrSrSr            SS jr\SS j5       r\SS j5       r	\SS j5       r
SSS jjrSSS	 jjrSS
 jrS rSS jrSrg)ReattachedTracei  zTA trace context rebuilt from persisted state without re-emitting trace start events._name	_trace_id_tracing_api_keyrc   rd   _prev_context_token_startedc               \    Xl         X l        XPl        X0l        X@l        S U l        SU l        g NFr   )r   r2   r/   rc   rd   r8   s         r   __init__ReattachedTrace.__init__  s-     
! /  KO r   c                    U R                   $ r   r   r   s    r   r/   ReattachedTrace.trace_id.      ~~r   c                    U R                   $ r   r   r   s    r   r2   ReattachedTrace.name2      zzr   c                    U R                   $ r   r   r   s    r   r8   ReattachedTrace.tracing_api_key6      $$$r   c                    U R                   (       a  g SU l         [        U R                  5        U(       a  [        R                  " U 5      U l        g g NT)r   r   r/   r   set_current_tracer   r$   s     r   r&   ReattachedTrace.start:  s:    ==t}}-','>'>t'DD$ r   c                    U R                   (       d  g U(       a6  U R                  b(  [        R                  " U R                  5        S U l        g g g r   )r   r   r   reset_current_tracer*   s     r   r,   ReattachedTrace.finishD  s>    }}T55A%%d&>&>?'+D$ B=r   c                    U R                   (       a)  U R                  (       d  [        R                  " S5        U $ U R	                  SS9  U $ Nz.Trace already started but no context token setT)r%   r   r   r
   errorr&   r   s    r   r   ReattachedTrace.__enter__L  7    ==++MNK

4
(r   c                .    U R                  U[        LS9  g Nr+   r,   GeneratorExitr   s       r   r!   ReattachedTrace.__exit__U      (-"?@r   c                b    SU R                   U R                  U R                  U R                  S.$ Nrl   )rp   rq   rb   rc   rd   r/   r2   rc   rd   r   s    r   r5   ReattachedTrace.exportX  +    --!YY
 	
r   )r   r   r   r   r   rc   rd   N)r2   rI   r/   rI   rc   rM   rd   rK   r8   rM   rC   NonerH   rL   rD   rE   rG   rB   rJ   rO   rP   rQ   rR   rS   	__slots__r   rV   r/   r2   r8   r&   r,   r   r!   r5   rW   r   r   r   r   r     s    ^I  	
  ( $ 
"     % %E,A
r   r   r]   c                   U R                   c  g[        U R                  =(       d    SU R                   U R                  U R                  b  [        U R                  5      OSU R                  b  U R                  S9$ US9$ )zMBuild a live trace context from persisted state without notifying processors.NzAgent workflow)r2   r/   rc   rd   r8   )r/   r   rb   rc   rd   r=   r8   )trace_stater8   s     r   reattach_tracer   b  s    #&&:*:%%%%/:/C/C/Ok**+UY **6 ''
 
 !
 
r   c                      \ rS rSrSrS rSS jrS rSSS jjrSSS jjr	\
SS j5       r\
SS	 j5       rSS
 jr\
SS j5       rSrg)	NoOpTraceis  a  A no-op implementation of Trace that doesn't record any data.

Used when tracing is disabled but trace operations still need to work.
Maintains proper context management but doesn't store or export any data.

Example:
    ```python
    # When tracing is disabled, traces become NoOpTrace
    with trace("Disabled Workflow") as t:
        # Operations still work but nothing is recorded
        await Runner.run(agent, "query")
    ```
c                     SU l         S U l        g r   )r   r   r   s    r   r   NoOpTrace.__init__  s    KO r   c                    U R                   (       a)  U R                  (       d  [        R                  " S5        U $ SU l         U R	                  SS9  U $ r   r   r   s    r   r   NoOpTrace.__enter__  s>    ==++MNK

4
(r   c                "    U R                  SS9  g )NTr   )r,   r   s       r   r!   NoOpTrace.__exit__  s    $'r   c                J    U(       a  [         R                  " U 5      U l        g g r   )r   r   r   r$   s     r   r&   NoOpTrace.start  s    ','>'>t'DD$ r   c                ~    U(       a6  U R                   b(  [        R                  " U R                   5        S U l         g g g r   )r   r   r   r*   s     r   r,   NoOpTrace.finish  s4    T55A%%d&>&>?'+D$ B=r   c                    g)zNThe trace's unique identifier.

Returns:
    str: A unique ID for this trace.
r   r   r   s    r   r/   NoOpTrace.trace_id       r   c                    g)zcThe workflow name for this trace.

Returns:
    str: Human-readable name describing this workflow.
r   r   r   s    r   r2   NoOpTrace.name  r   r   c                    g)zwExport the trace data as a dictionary.

Returns:
    dict | None: Trace data in exportable format, or None if no data.
Nr   r   s    r   r5   NoOpTrace.export  s     r   c                    g r   r   r   s    r   r8   NoOpTrace.tracing_api_key  s    r   )r   r   NrB   rD   rE   rG   rH   rJ   rL   )rO   rP   rQ   rR   rS   r   r   r!   r&   r,   rV   r/   r2   r5   r8   rW   r   r   r   r   r   s  sc    P	(E,
      r   r   c                      \ rS rSrSrSr S           SS jjr\SS j5       r\SS j5       r	\SS j5       r
SSS	 jjrSSS
 jjrSS jrS rSS jrSrg)	TraceImpli  z7
A trace that will be recorded by the tracing library.
)r   r   r   rc   rd   r   
_processorr   Nc                    Xl         U=(       d    [        R                  " 5       U l        X`l        X0l        X@l        S U l        XPl        SU l	        g r   )
r   r   gen_trace_idr   r   rc   rd   r   r   r   )r   r2   r/   rc   rd   	processorr8   s          r   r   TraceImpl.__init__  sB     
!8T%6%6%8 /  KO #r   c                    U R                   $ r   r   r   s    r   r/   TraceImpl.trace_id  r   r   c                    U R                   $ r   r   r   s    r   r2   TraceImpl.name  r   r   c                    U R                   $ r   r   r   s    r   r8   TraceImpl.tracing_api_key  r   r   c                    U R                   (       a  g SU l         U R                  R                  U 5        [        U R                  5        U(       a  [
        R                  " U 5      U l        g g r   )r   r   on_trace_startr   r/   r   r   r   r$   s     r   r&   TraceImpl.start  sL    ==&&t,t}}-','>'>t'DD$ r   c                    U R                   (       d  g U R                  R                  U 5        U(       a6  U R                  b(  [        R
                  " U R                  5        S U l        g g g r   )r   r   on_trace_endr   r   r   r*   s     r   r,   TraceImpl.finish  sP    }}$$T*T55A%%d&>&>?'+D$ B=r   c                    U R                   (       a)  U R                  (       d  [        R                  " S5        U $ U R	                  SS9  U $ r   r   r   s    r   r   TraceImpl.__enter__  r   r   c                .    U R                  U[        LS9  g r   r   r   s       r   r!   TraceImpl.__exit__  r   r   c                b    SU R                   U R                  U R                  U R                  S.$ r   r   r   s    r   r5   TraceImpl.export  r   r   )r   r   r   r   r   r   rc   rd   r   )r2   rI   r/   rM   rc   rM   rd   rK   r   r   r8   rM   rH   rL   rD   rE   rG   rB   rJ   r   r   r   r   r   r     s    	I$ '+  	
 ( $ $$     % %	E,A
r   r   )r8   rM   rC   rM   )r/   rM   rC   r   )r/   rM   rC   rF   )r   r`   r8   rM   rC   r~   )&
__future__r   rT   contextvarsrY   	threadingcollectionsr   collections.abcr   dataclassesr   r   typingr   r
    r   processor_interfacer   scoper   ABCr   r^   r`   r   r   r   Lockr   r   r   r   r   r   NO_OP_TRACEr   r   r   r   <module>r     s    " 
    # # (    1 ECGG EPG Q Q Qh  -8] * :#..* 
3.O
e O
d NR "F FR kV
 V
r   