.. attribute:: id
   :type: str
   :noindex:

   Unique identifier for the span.

.. attribute:: start_time
   :type: datetime.datetime
   :noindex:

   Start time of the span, marking when the operation began.

Optional Attributes

.. attribute:: spans
   :type: List[SpanModel]
   :noindex:

   List of nested spans related to this span. This creates a hierarchical structure where spans can contain child spans.

.. attribute:: feedback_scores
   :type: List[FeedbackScoreModel]
   :noindex:

   List of feedback scores associated with the span. These scores are used for evaluation and quality assessment.

Examples
--------

Creating a basic span:

.. code-block:: python

    import datetime
    from opik.message_processing.emulation.models import SpanModel

    # Create a simple span
    span = SpanModel(
        id="span_123",
        start_time=datetime.datetime.now(),
        name="llm_call",
        type="llm",
        input={"prompt": "What is the capital of France?"},
        output={"response": "Paris is the capital of France."},
        model="gpt-4",
        provider="openai"
    )

Creating a span with nested spans:

.. code-block:: python

    # Create a parent span with child spans
    parent_span = SpanModel(
        id="parent_123",
        start_time=datetime.datetime.now(),
        name="complex_operation"
    )

    child_span = SpanModel(
        id="child_456",
        start_time=datetime.datetime.now(),
        name="preprocessing_step"
    )

    parent_span.spans.append(child_span)

Adding feedback scores to a span:

.. code-block:: python

    from opik.message_processing.emulation.models import FeedbackScoreModel

    # Add evaluation scores to the span
    quality_score = FeedbackScoreModel(
        id="score_789",
        name="response_quality",
        value=0.92,
        reason="High quality response with accurate information"
    )

    span.feedback_scores.append(quality_score)

Usage in Task Span Evaluation
-----------------------------

``SpanModel`` objects are particularly important in task span evaluation, where custom metrics can analyze the span data:

.. code-block:: python

    from opik.evaluation.metrics import BaseMetric, score_result

    class CustomSpanMetric(BaseMetric):
        def score(self, task_span: SpanModel) -> score_result.ScoreResult:
            # Access span properties for evaluation
            input_data = task_span.input
            output_data = task_span.output

            # Perform custom evaluation logic
            score_value = self.evaluate_span_quality(input_data, output_data)

            return score_result.ScoreResult(
                value=score_value,
                name=self.name,
                reason=f"Evaluated span '{task_span.name}'"
            )

Common Use Cases
----------------

``SpanModel`` is commonly used for:

- **Function Tracking**: Recording individual function or method calls
- **LLM Operations**: Tracking language model API calls with usage and cost information
- **Pipeline Steps**: Representing steps in data processing pipelines
- **Evaluation**: Providing detailed execution data for custom evaluation metrics
- **Debugging**: Analyzing the structure and performance of complex operations

See Also
--------

- :class:`TraceModel` - The parent container that holds spans
- :class:`FeedbackScoreModel` - For attaching evaluation scores to spans
- :doc:`../evaluation/evaluate` - For information about evaluating spans with custom metrics