
    /Ui$                       d dl mZ d dlZd dlZd dlmZmZmZ d dlm	Z	 ddl
m
Z
 ddlmZ dd	lmZ dd
lmZ ddlmZ  ede      Z G d de	      Z G d dej*                  ee         Z G d dee         Z G d dee         Zy)    )annotationsN)AnyGenericTypeVar)	TypedDict   )logger   )util)TracingProcessor)Scope)SpanData	TSpanData)boundc                  &    e Zd ZU dZded<   ded<   y)	SpanErrorzRepresents 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dataN)__name__
__module____qualname____doc____annotations__     p/home/jay/workspace/tools/ai-image-gen/jaaz-app/server/venv/lib/python3.12/site-packages/agents/tracing/spans.pyr   r      s     L
r   r   c                  F   e Zd ZdZeej                  dd              Zeej                  dd              Zeej                  dd              Z	ej                  ddd       Z
ej                  ddd       Zej                  dd       Zej                  d        Zeej                  dd	              Zej                  dd
       Zeej                  dd              Zej                  dd       Zeej                  dd              Zeej                  dd              Zy)Spana  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                     y)z|The ID of the trace this span belongs to.

        Returns:
            str: Unique identifier of the parent trace.
        Nr   selfs    r   trace_idzSpan.trace_idE        	r   c                     y)zsUnique identifier for this span.

        Returns:
            str: The span's unique ID within its trace.
        Nr   r"   s    r   span_idzSpan.span_idO   r%   r   c                     y)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_datazSpan.span_dataY   r%   r   c                     y)z
        Start the span.

        Args:
            mark_as_current: If true, the span will be marked as the current span.
        Nr   r#   mark_as_currents     r   startz
Span.startc   r%   r   c                     y)z
        Finish the span.

        Args:
            reset_current: If true, the span will be reset as the current span.
        Nr   r#   reset_currents     r   finishzSpan.finishm   r%   r   c                     y Nr   r"   s    r   	__enter__zSpan.__enter__w       r   c                     y r3   r   )r#   exc_typeexc_valexc_tbs       r   __exit__zSpan.__exit__{   r5   r   c                     y)zID 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_idzSpan.parent_id   r%   r   c                     y r3   r   r#   errors     r   	set_errorzSpan.set_error   r5   r   c                     y)zAny error that occurred during span execution.

        Returns:
            SpanError | None: Error details if an error occurred, None otherwise.
        Nr   r"   s    r   r?   z
Span.error   r%   r   c                     y r3   r   r"   s    r   exportzSpan.export   r5   r   c                     y)zWhen the span started execution.

        Returns:
            str | None: ISO format timestamp of span start, None if not started.
        Nr   r"   s    r   
started_atzSpan.started_at   r%   r   c                     y)zWhen the span finished execution.

        Returns:
            str | None: ISO format timestamp of span end, None if not finished.
        Nr   r"   s    r   ended_atzSpan.ended_at   r%   r   Nreturnr   rI   r   Fr,   boolr0   rM   rI   NonerI   zSpan[TSpanData]rI   
str | Noner?   r   rI   rO   rI   zSpanError | NonerI   r   )r   r   r   r   propertyabcabstractmethodr$   r'   r)   r-   r1   r4   r:   r<   r@   r?   rC   rE   rG   r   r   r   r    r       s   $L          	  	  	  	     	     	       r   r    c                      e Zd ZdZdZddZedd       Zedd       Zedd       Z	edd       Z
dddZddd	Zdd
Zd ZddZedd       ZddZedd       Zedd       Zy)NoOpSpanzA 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                     || _         d | _        y r3   r[   )r#   r)   s     r   __init__zNoOpSpan.__init__   s    #RVr   c                     yNzno-opr   r"   s    r   r$   zNoOpSpan.trace_id       r   c                     yra   r   r"   s    r   r'   zNoOpSpan.span_id   rb   r   c                    | j                   S r3   r\   r"   s    r   r)   zNoOpSpan.span_data       r   c                     y r3   r   r"   s    r   r<   zNoOpSpan.parent_id       r   c                >    |rt        j                  |       | _        y y r3   )r   set_current_spanr]   r+   s     r   r-   zNoOpSpan.start   s    $)$:$:4$@D! r   c                p    |r4| j                   't        j                  | j                          d | _         y y y r3   )r]   r   reset_current_spanr/   s     r   r1   zNoOpSpan.finish   s3    T22>$$T%:%:;$(D! ?=r   c                *    | j                  d       | S NT)r,   r-   r"   s    r   r4   zNoOpSpan.__enter__       

4
(r   c                j    d}|t         u rt        j                  d       d}| j                  |       y NTz"GeneratorExit, skipping span resetF)r0   GeneratorExitr	   debugr1   r#   r7   r8   r9   r0   s        r   r:   zNoOpSpan.__exit__   /    }$LL=>!M-0r   c                     y r3   r   r>   s     r   r@   zNoOpSpan.set_error   s    r   c                     y r3   r   r"   s    r   r?   zNoOpSpan.error   rh   r   c                     y r3   r   r"   s    r   rC   zNoOpSpan.export   s    r   c                     y r3   r   r"   s    r   rE   zNoOpSpan.started_at   rh   r   c                     y r3   r   r"   s    r   rG   zNoOpSpan.ended_at   rh   r   N)r)   r   rH   rJ   rQ   rK   rL   rN   rP   rS   rT   rU   )r   r   r   r   	__slots__r_   rV   r$   r'   r)   r<   r-   r1   r4   r:   r@   r?   rC   rE   rG   r   r   r   rZ   rZ      s     3IW        A)
1      r   rZ   c                      e Zd ZdZ	 	 	 	 	 	 	 	 	 	 ddZedd       Zedd       Zedd       Zedd       Z	dddZ
dddZdd	Zd
 ZddZedd       Zedd       Zedd       ZddZy)SpanImpl)		_trace_id_span_id
_parent_id_started_at	_ended_at_errorr]   
_processorr\   c                    || _         |xs t        j                         | _        || _        d | _        d | _        || _        d | _        d | _	        || _
        y r3   )r   r   gen_span_idr   r   r   r   r   r   r]   r\   )r#   r$   r'   r<   	processorr)   s         r   r_   zSpanImpl.__init__  sS     "54#3#3#5#'+%)#(,RV#r   c                    | j                   S r3   )r   r"   s    r   r$   zSpanImpl.trace_id      ~~r   c                    | j                   S r3   )r   r"   s    r   r'   zSpanImpl.span_id  s    }}r   c                    | j                   S r3   re   r"   s    r   r)   zSpanImpl.span_data  rf   r   c                    | j                   S r3   )r   r"   s    r   r<   zSpanImpl.parent_id"  rf   r   c                    | j                   t        j                  d       y t        j                         | _        | j                  j                  |        |rt        j                  |       | _
        y y )NzSpan already started)rE   r	   warningr   time_isor   r   on_span_startr   rj   r]   r+   s     r   r-   zSpanImpl.start&  sW    ??&NN12==?%%d+$)$:$:4$@D! r   c                   | j                   t        j                  d       y t        j                         | _        | j                  j                  |        |r4| j                  't        j                  | j                         d | _        y y y )NzSpan already finished)rG   r	   r   r   r   r   r   on_span_endr]   r   rl   r/   s     r   r1   zSpanImpl.finish0  sl    ==$NN23##D)T22>$$T%:%:;$(D! ?=r   c                *    | j                  d       | S rn   ro   r"   s    r   r4   zSpanImpl.__enter__;  rp   r   c                j    d}|t         u rt        j                  d       d}| j                  |       y rr   rs   rv   s        r   r:   zSpanImpl.__exit__?  rw   r   c                    || _         y r3   r   r>   s     r   r@   zSpanImpl.set_errorG  s	    r   c                    | j                   S r3   r   r"   s    r   r?   zSpanImpl.errorJ  s    {{r   c                    | j                   S r3   )r   r"   s    r   rE   zSpanImpl.started_atN  s    r   c                    | j                   S r3   )r   r"   s    r   rG   zSpanImpl.ended_atR  r   r   c           	         d| j                   | j                  | j                  | j                  | j                  | j
                  j                         | j                  dS )Nz
trace.span)objectidr$   r<   rE   rG   r)   r?   )r'   r$   r   r   r   r)   rC   r   r"   s    r   rC   zSpanImpl.exportV  sK    ",,**..0[[	
 		
r   N)
r$   r   r'   rR   r<   rR   r   r   r)   r   rH   rJ   rQ   rK   rL   rN   rP   rS   rT   rU   )r   r   r   r}   r_   rV   r$   r'   r)   r<   r-   r1   r4   r:   r@   r?   rE   rG   rC   r   r   r   r   r      s    
I$$ $ 	$
 $$ $$        A	)1        

r   r   )
__future__r   rW   contextvarstypingr   r   r   typing_extensionsr   r	    r   processor_interfacer   scoper   r)   r   r   r   ABCr    rZ   r   r   r   r   <module>r      s}    " 
  ( ( '   1  Kx0		 	 	 O377GI& OdDtI DNi
tI i
r   