chore: import upstream snapshot with attribution

apps/opik-documentation/python-sdk-docs/source/message_processing_emulation/TraceModel.rst

@@ -0,0 +1,254 @@
+TraceModel
+==========
+
+.. currentmodule:: opik.message_processing.emulation.models
+
+.. autoclass:: TraceModel
+    :special-members: __init__
+
+Description
+-----------
+
+The ``TraceModel`` class represents a trace model that encapsulates data about a trace, its related metadata, and associated spans. It is used for tracking and analyzing data during execution or processing tasks.
+
+This class provides a structure to represent trace information, including the start and end times, associated project details, input/output data, feedback scores, error information, and thread association. It is designed to handle optional fields for flexible use across various scenarios.
+
+A trace represents the complete execution path of a request or operation, containing one or more spans that represent individual steps or components within that execution.
+
+Attributes
+----------
+
+Required Attributes
+~~~~~~~~~~~~~~~~~~~
+
+.. attribute:: id
+   :type: str
+   :noindex:
+
+   Unique identifier for the trace.
+
+.. attribute:: start_time
+   :type: datetime.datetime
+   :noindex:
+
+   Timestamp representing the start of the trace.
+
+.. attribute:: name
+   :type: Optional[str]
+   :noindex:
+
+   Optional name for the trace, which can provide a descriptive label for the operation being traced.
+
+.. attribute:: project_name
+   :type: str
+   :noindex:
+
+   Name of the project associated with the trace.
+
+Optional Attributes
+~~~~~~~~~~~~~~~~~~~
+
+.. attribute:: input
+   :type: Optional[Dict[str, Any]]
+   :noindex:
+   :value: None
+
+   Optional dictionary containing the input data associated with the trace. This represents the initial parameters or data that started the trace.
+
+.. attribute:: output
+   :type: Optional[Dict[str, Any]]
+   :noindex:
+   :value: None
+
+   Optional dictionary containing the output data generated by the trace. This represents the final results or return values.
+
+.. attribute:: tags
+   :type: Optional[List[str]]
+   :noindex:
+   :value: None
+
+   Optional list of tags associated with the trace for classification or filtering purposes.
+
+.. attribute:: metadata
+   :type: Optional[Dict[str, Any]]
+   :noindex:
+   :value: None
+
+   Optional metadata providing additional information about the trace.
+
+.. attribute:: end_time
+   :type: Optional[datetime.datetime]
+   :noindex:
+   :value: None
+
+   Timestamp representing the end of the trace. When set, this marks when the operation completed.
+
+.. attribute:: error_info
+   :type: Optional[ErrorInfoDict]
+   :noindex:
+   :value: None
+
+   Optional dictionary containing information about errors encountered during the trace.
+
+.. attribute:: thread_id
+   :type: Optional[str]
+   :noindex:
+   :value: None
+
+   Optional identifier of the thread associated with the trace. Useful for concurrent operations.
+
+.. attribute:: last_updated_at
+   :type: Optional[datetime.datetime]
+   :noindex:
+   :value: None
+
+   Timestamp for when the trace was last updated.
+
+Collection Attributes
+~~~~~~~~~~~~~~~~~~~~~
+
+.. attribute:: spans
+   :type: List[SpanModel]
+   :noindex:
+
+   List of spans associated with the trace, representing individual processing parts or segments within the trace. Each span represents a specific operation or step in the overall execution.
+
+.. attribute:: feedback_scores
+   :type: List[FeedbackScoreModel]
+   :noindex:
+
+   List of feedback scores associated with the trace. These are used for overall trace evaluation and quality assessment.
+
+Examples
+--------
+
+Creating a basic trace:
+
+.. code-block:: python
+
+    import datetime
+    from opik.message_processing.emulation.models import TraceModel
+
+    # Create a simple trace
+    trace = TraceModel(
+        id="trace_123",
+        start_time=datetime.datetime.now(),
+        name="user_query_processing",
+        project_name="my_project",
+        input={"user_query": "What is machine learning?"},
+        output={"response": "Machine learning is a subset of AI..."}
+    )
+
+Creating a trace with spans:
+
+.. code-block:: python
+
+    from opik.message_processing.emulation.models import SpanModel
+
+    # Create a trace with associated spans
+    trace = TraceModel(
+        id="trace_456",
+        start_time=datetime.datetime.now(),
+        name="complex_operation",
+        project_name="ai_project"
+    )
+
+    # Add spans to represent different steps
+    preprocessing_span = SpanModel(
+        id="span_1",
+        start_time=datetime.datetime.now(),
+        name="data_preprocessing"
+    )
+
+    llm_span = SpanModel(
+        id="span_2",
+        start_time=datetime.datetime.now(),
+        name="llm_call",
+        type="llm"
+    )
+
+    trace.spans.extend([preprocessing_span, llm_span])
+
+Adding feedback scores to a trace:
+
+.. code-block:: python
+
+    from opik.message_processing.emulation.models import FeedbackScoreModel
+
+    # Add overall evaluation scores to the trace
+    overall_quality = FeedbackScoreModel(
+        id="score_123",
+        name="overall_quality",
+        value=0.88,
+        reason="Good response quality with minor improvements needed"
+    )
+
+    trace.feedback_scores.append(overall_quality)
+
+Working with trace hierarchies:
+
+.. code-block:: python
+
+    # Access nested spans within a trace
+    for span in trace.spans:
+        print(f"Span: {span.name}")
+
+        # Each span can have nested spans too
+        for nested_span in span.spans:
+            print(f"  Nested: {nested_span.name}")
+
+Usage in Evaluation Context
+---------------------------
+
+``TraceModel`` objects are commonly used in evaluation scenarios where you need to analyze the complete execution:
+
+.. code-block:: python
+
+    # Example of accessing trace data in evaluation
+    def analyze_trace(trace: TraceModel):
+        # Analyze overall trace performance
+        duration = trace.end_time - trace.start_time if trace.end_time else None
+
+        # Count different types of spans
+        llm_spans = [s for s in trace.spans if s.type == "llm"]
+
+        # Analyze input/output
+        input_complexity = len(str(trace.input)) if trace.input else 0
+        output_quality = evaluate_output_quality(trace.output)
+
+        return {
+            "duration": duration,
+            "llm_calls": len(llm_spans),
+            "complexity": input_complexity,
+            "quality": output_quality
+        }
+
+Common Use Cases
+----------------
+
+``TraceModel`` is commonly used for:
+
+- **Request Tracking**: Tracking complete user requests from start to finish
+- **Performance Analysis**: Analyzing the performance of complex operations
+- **Evaluation**: Providing complete context for evaluation metrics
+- **Debugging**: Understanding the full execution path and identifying issues
+- **Cost Tracking**: Aggregating costs across all spans in a trace
+- **A/B Testing**: Comparing different execution paths and their outcomes
+
+Relationship with Spans
+-----------------------
+
+A trace acts as a container for spans, creating a hierarchical structure:
+
+- **Trace**: The top-level container representing the complete operation
+- **Spans**: Individual steps or operations within the trace
+- **Nested Spans**: Spans can contain other spans, creating a tree structure
+
+This hierarchy allows for detailed tracking of complex operations while maintaining the overall context.
+
+See Also
+--------
+
+- :class:`SpanModel` - Individual operations within a trace
+- :class:`FeedbackScoreModel` - For attaching evaluation scores to traces
+- :doc:`../evaluation/evaluate` - For information about evaluating traces with custom metrics