
    Cj*                       S SK Jr  S SKrS SKrS SKJr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KJr  \" S\S9rSr " S S\	5      r " S S\R,                  \\   5      r " S S\\   5      r " S S\\   5      rg)    )annotationsN)AnyGenericTypeVar)	TypedDict   )logger   )util)TracingProcessor)Scope)SpanData	TSpanData)bound)agent_harness_idc                  .    \ rS rSr% SrS\S'   S\S'   Srg)		SpanError   zRepresents an error that occurred during span execution.

Attributes:
    message: A human-readable error description
    data: Optional dictionary containing additional error context
strmessagedict[str, Any] | Nonedata N)__name__
__module____qualname____firstlineno____doc____annotations____static_attributes__r       f/home/rurouni/.local/share/pipx/venvs/strix-agent/lib/python3.13/site-packages/agents/tracing/spans.pyr   r      s     L
r!   r   c                     \ rS rSrSr\\R                  SS j5       5       r\\R                  SS j5       5       r	\\R                  SS j5       5       r
\R                  SSS jj5       r\R                  SSS jj5       r\R                  SS j5       r\R                  S	 5       r\\R                  SS
 j5       5       r\R                  SS j5       r\\R                  SS j5       5       r\R                  SS j5       r\\R                  SS j5       5       r\\R                  SS j5       5       r\\R                  SS j5       5       r\SS j5       rSrg)Span   a  Base class for representing traceable operations with timing and context.

A span represents a single operation within a trace (e.g., an LLM call, tool execution,
or agent run). Spans track timing, relationships between operations, and operation-specific
data.

Type Args:
    TSpanData: The type of span-specific data this span contains.

Example:
    ```python
    # Creating a custom span
    with custom_span("database_query", {
        "operation": "SELECT",
        "table": "users"
    }) as span:
        results = await db.query("SELECT * FROM users")
        span.set_output({"count": len(results)})

    # Handling errors in spans
    with custom_span("risky_operation") as span:
        try:
            result = perform_risky_operation()
        except Exception as e:
            span.set_error({
                "message": str(e),
                "data": {"operation": "risky_operation"}
            })
            raise
    ```

    Notes:
    - Spans automatically nest under the current trace
    - Use context managers for reliable start/finish
    - Include relevant data but avoid sensitive information
    - Handle errors properly using set_error()
c                    g)zdThe ID of the trace this span belongs to.

Returns:
    str: Unique identifier of the parent trace.
Nr   selfs    r"   trace_idSpan.trace_idF        	r!   c                    g)z[Unique identifier for this span.

Returns:
    str: The span's unique ID within its trace.
Nr   r'   s    r"   span_idSpan.span_idP   r+   r!   c                    g)zOperation-specific data for this span.

Returns:
    TSpanData: Data specific to this type of span (e.g., LLM generation data).
Nr   r'   s    r"   	span_dataSpan.span_dataZ   r+   r!   c                    g)zc
Start the span.

Args:
    mark_as_current: If true, the span will be marked as the current span.
Nr   r(   mark_as_currents     r"   start
Span.startd   r+   r!   c                    g)za
Finish the span.

Args:
    reset_current: If true, the span will be reset as the current span.
Nr   r(   reset_currents     r"   finishSpan.finishn   r+   r!   c                    g Nr   r'   s    r"   	__enter__Span.__enter__x       r!   c                    g r=   r   )r(   exc_typeexc_valexc_tbs       r"   __exit__Span.__exit__|   r@   r!   c                    g)zoID of the parent span, if any.

Returns:
    str | None: The parent span's ID, or None if this is a root span.
Nr   r'   s    r"   	parent_idSpan.parent_id   r+   r!   c                    g r=   r   r(   errors     r"   	set_errorSpan.set_error   r@   r!   c                    g)zAny error that occurred during span execution.

Returns:
    SpanError | None: Error details if an error occurred, None otherwise.
Nr   r'   s    r"   rL   
Span.error   r+   r!   c                    g r=   r   r'   s    r"   exportSpan.export   r@   r!   c                    g)ztWhen the span started execution.

Returns:
    str | None: ISO format timestamp of span start, None if not started.
Nr   r'   s    r"   
started_atSpan.started_at   r+   r!   c                    g)ztWhen the span finished execution.

Returns:
    str | None: ISO format timestamp of span end, None if not finished.
Nr   r'   s    r"   ended_atSpan.ended_at   r+   r!   c                    g)z,The API key to use when exporting this span.Nr   r'   s    r"   tracing_api_keySpan.tracing_api_key   s     	r!   c                    g)z:Trace-level metadata inherited by this span, if available.Nr   r'   s    r"   trace_metadataSpan.trace_metadata   s     r!   r   Nreturnr   ra   r   Fr4   boolr9   re   ra   Nonera   zSpan[TSpanData]ra   
str | NonerL   r   ra   rg   ra   zSpanError | Nonera   r   )r   r   r   r   r   propertyabcabstractmethodr)   r-   r0   r5   r:   r>   rE   rH   rM   rL   rR   rU   rX   r[   r^   r    r   r!   r"   r$   r$      s   $L          	  	  	  	     	     	            r!   r$   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 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S j5       rSS jr\SS j5       r\SS j5       r\SS j5       rSrg) NoOpSpan   zA no-op implementation of Span that doesn't record any data.

Used when tracing is disabled but span operations still need to work.

Args:
    span_data: The operation-specific data for this span.

_span_data_prev_span_tokenc                    Xl         S U l        g r=   rt   )r(   r0   s     r"   __init__NoOpSpan.__init__   s    #RVr!   c                    gNzno-opr   r'   s    r"   r)   NoOpSpan.trace_id       r!   c                    gr{   r   r'   s    r"   r-   NoOpSpan.span_id   r}   r!   c                    U R                   $ r=   ru   r'   s    r"   r0   NoOpSpan.span_data       r!   c                    g r=   r   r'   s    r"   rH   NoOpSpan.parent_id       r!   c                J    U(       a  [         R                  " U 5      U l        g g r=   )r   set_current_spanrv   r3   s     r"   r5   NoOpSpan.start   s    $)$:$:4$@D! r!   c                ~    U(       a6  U R                   b(  [        R                  " U R                   5        S U l         g g g r=   )rv   r   reset_current_spanr8   s     r"   r:   NoOpSpan.finish   s3    T22>$$T%:%:;$(D! ?=r!   c                $    U R                  SS9  U $ NT)r4   r5   r'   s    r"   r>   NoOpSpan.__enter__       

4
(r!   c                h    SnU[         L a  [        R                  " S5        SnU R                  US9  g NTz"GeneratorExit, skipping span resetF)r9   GeneratorExitr	   debugr:   r(   rB   rC   rD   r9   s        r"   rE   NoOpSpan.__exit__   /    }$LL=>!M-0r!   c                    g r=   r   rK   s     r"   rM   NoOpSpan.set_error   s    r!   c                    g r=   r   r'   s    r"   rL   NoOpSpan.error   r   r!   c                    g r=   r   r'   s    r"   rR   NoOpSpan.export   s    r!   c                    g r=   r   r'   s    r"   rU   NoOpSpan.started_at   r   r!   c                    g r=   r   r'   s    r"   rX   NoOpSpan.ended_at   r   r!   c                    g r=   r   r'   s    r"   r[   NoOpSpan.tracing_api_key  r   r!   )rv   ru   N)r0   r   r`   rb   ri   rc   rd   rf   rh   rk   rl   rm   )r   r   r   r   r   	__slots__rx   rn   r)   r-   r0   rH   r5   r:   r>   rE   rM   rL   rR   rU   rX   r[   r    r   r!   r"   rr   rr      s     3IW        A)
1        r!   rr   c                  6   \ 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 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S j5       r\SS j5       r\SS j5       r\SS j5       r\S S j5       rS S jrSrg)!SpanImpli  )	_trace_id_span_id
_parent_id_started_at	_ended_at_errorrv   
_processorru   _tracing_api_key_trace_metadataNc                    Xl         U=(       d    [        R                  " 5       U l        X0l        S U l        S U l        X@l        S U l        S U l	        XPl
        X`l        Xpl        g r=   )r   r   gen_span_idr   r   r   r   r   r   rv   ru   r   r   )r(   r)   r-   rH   	processorr0   r[   r^   s           r"   rx   SpanImpl.__init__  sW     "54#3#3#5#'+%)#(,RV# /-r!   c                    U R                   $ r=   )r   r'   s    r"   r)   SpanImpl.trace_id,      ~~r!   c                    U R                   $ r=   )r   r'   s    r"   r-   SpanImpl.span_id0  s    }}r!   c                    U R                   $ r=   r   r'   s    r"   r0   SpanImpl.span_data4  r   r!   c                    U R                   $ r=   )r   r'   s    r"   rH   SpanImpl.parent_id8  r   r!   c                    U R                   b  [        R                  " S5        g [        R                  " 5       U l        U R                  R                  U 5        U(       a  [        R                  " U 5      U l
        g g )NzSpan already started)rU   r	   warningr   time_isor   r   on_span_startr   r   rv   r3   s     r"   r5   SpanImpl.start<  sW    ??&NN12==?%%d+$)$:$:4$@D! r!   c                0   U R                   b  [        R                  " S5        g [        R                  " 5       U l        U R                  R                  U 5        U(       a6  U R                  b(  [        R                  " U R                  5        S U l        g g g )NzSpan already finished)rX   r	   r   r   r   r   r   on_span_endrv   r   r   r8   s     r"   r:   SpanImpl.finishF  sl    ==$NN23##D)T22>$$T%:%:;$(D! ?=r!   c                $    U R                  SS9  U $ r   r   r'   s    r"   r>   SpanImpl.__enter__Q  r   r!   c                h    SnU[         L a  [        R                  " S5        SnU R                  US9  g r   r   r   s        r"   rE   SpanImpl.__exit__U  r   r!   c                    Xl         g r=   r   rK   s     r"   rM   SpanImpl.set_error]  s    r!   c                    U R                   $ r=   r   r'   s    r"   rL   SpanImpl.error`  s    {{r!   c                    U R                   $ r=   )r   r'   s    r"   rU   SpanImpl.started_atd  s    r!   c                    U R                   $ r=   )r   r'   s    r"   rX   SpanImpl.ended_ath  r   r!   c                    U R                   $ r=   )r   r'   s    r"   r[   SpanImpl.tracing_api_keyl  s    $$$r!   c                    U R                   $ r=   )r   r'   s    r"   r^   SpanImpl.trace_metadatap  s    ###r!   c           	     d   SU R                   U R                  U R                  U R                  U R                  U R
                  R                  5       U R                  S.n0 nU R                  bD  UR                  [         Vs0 s H#  nX0R                  ;   d  M  X0R                  U   _M%     sn5        [        U R
                  SS 5      n[        U[        5      (       a;  UR                  UR                  5        VVs0 s H  u  p5X2;  d  M  X5_M     snn5        U(       a  X!S'   U$ s  snf s  snnf )Nz
trace.span)objectidr)   rH   rU   rX   r0   rL   metadata)r-   r)   r   r   r   r0   rR   r   r   update_SPAN_METADATA_ROUTING_KEYSgetattr
isinstancedictitems)r(   payloadr   keyspan_data_metadatavalues         r"   rR   SpanImpl.exportt  s   ",,**..0[[	
 $&+OO  ;:222 3C--c22: %T^^ZF($//OO.@.F.F.H`.H
CL_.H` "*J as   D'D'=D,
D,
)r   r   r   rv   r   ru   r   r   r   r   r   r=   )r)   r   r-   rj   rH   rj   r   r   r0   r   r[   rj   r^   r   r`   rb   ri   rc   rd   rf   rh   rk   rl   rm   )r   r   r   r   r   rx   rn   r)   r-   r0   rH   r5   r:   r>   rE   rM   rL   rU   rX   r[   r^   rR   r    r   r!   r"   r   r     s*   I, 15.. . 	.
 $. . $. ..,        A	)1         % % $ $r!   r   )
__future__r   ro   contextvarstypingr   r   r   typing_extensionsr   r	    r   processor_interfacer   scoper   r0   r   r   r   r   ABCr$   rr   r   r   r!   r"   <module>r      s    " 
  ( ( '   1  Kx0	3 	 	 	 Z377GI& ZzHtI HVHtI Hr!   