arize 8.0.0b1__py3-none-any.whl → 8.0.0b4__py3-none-any.whl

arize/spans/client.py

@@ -1,6 +1,5 @@
 """Client implementation for managing spans and traces in the Arize platform."""
 
-# type: ignore[pb2]
 from __future__ import annotations
 
 import json
@@ -21,12 +20,16 @@ from arize._flight.types import FlightRequestType
 from arize.constants.spans import DEFAULT_DATETIME_FMT
 from arize.exceptions.base import (
     INVALID_ARROW_CONVERSION_MSG,
+    ValidationError,
     ValidationFailure,
 )
 from arize.exceptions.models import MissingProjectNameError
 from arize.exceptions.spaces import MissingSpaceIDError
 from arize.logging import CtxAdapter
 from arize.ml.types import Environments
+from arize.spans.validation.metadata.value_validation import (
+    InvalidPatchDocumentFormat,
+)
 from arize.utils.arrow import post_arrow_table
 from arize.utils.dataframe import (
     remove_extraneous_columns,
@@ -78,10 +81,11 @@ class SpansClient:
         Args:
             space_id: The space ID where the project resides.
             project_name: A unique name to identify your project in the Arize platform.
-            dataframe: The dataframe containing the LLM traces.
-            evals_dataframe: A dataframe containing LLM evaluations data.
-                The evaluations are joined to their corresponding spans via a left outer join, i.e.,
-                using only `context.span_id` from the spans dataframe. Defaults to None.
+            dataframe (:class:`pandas.DataFrame`): The dataframe containing the LLM traces.
+            evals_dataframe (:class:`pandas.DataFrame` | :obj:`None`): A dataframe containing
+                LLM evaluations data. The evaluations are joined to their corresponding spans
+                via a left outer join, i.e., using only `context.span_id` from the spans
+                dataframe. Defaults to None.
             datetime_format: format for the timestamp captured in the LLM traces.
                 Defaults to "%Y-%m-%dT%H:%M:%S.%f+00:00".
             validate: When set to True, validation is run before sending data.
@@ -280,7 +284,7 @@ class SpansClient:
         Args:
             space_id: The space ID where the project resides.
             project_name: A unique name to identify your project in the Arize platform.
-            dataframe: A dataframe containing LLM evaluations data.
+            dataframe (:class:`pandas.DataFrame`): A dataframe containing LLM evaluations data.
             validate: When set to True, validation is run before sending data.
                 Defaults to True.
             force_http: Force the use of HTTP for data upload. Defaults to False.
@@ -453,7 +457,7 @@ class SpansClient:
         Args:
             space_id: The space ID where the project resides.
             project_name: A unique name to identify your project in the Arize platform.
-            dataframe: A dataframe containing LLM annotation data.
+            dataframe (:class:`pandas.DataFrame`): A dataframe containing LLM annotation data.
             validate: When set to True, validation is run before sending data.
                 Defaults to True.
         """
@@ -684,7 +688,8 @@ class SpansClient:
         Args:
             space_id: The space ID where the project resides.
             project_name: A unique name to identify your project in the Arize platform.
-            dataframe: DataFrame with span_ids and either patch documents or metadata field columns.
+            dataframe (:class:`pandas.DataFrame`): DataFrame with span_ids and either patch
+                documents or metadata field columns.
             patch_document_column_name: Name of the column containing JSON patch documents.
                 Defaults to "patch_document".
             validate: When set to True, validation is run before sending data.
@@ -848,7 +853,8 @@ class SpansClient:
                     )
                     for idx in range(len(metadata_df))
                 ]
-                metadata_df[final_patch_column] = merged_patches
+                # Type ignore: pandas DataFrame column assignment type is overly restrictive
+                metadata_df[final_patch_column] = merged_patches  # type: ignore[assignment]
             else:
                 # Just use the field patches directly
                 metadata_df[final_patch_column] = field_patches
@@ -885,7 +891,8 @@ class SpansClient:
                     log.error(e)
                 raise ValidationFailure(validation_errors)
 
-            metadata_df[final_patch_column] = processed_patches
+            # Type ignore: pandas DataFrame column assignment type is overly restrictive
+            metadata_df[final_patch_column] = processed_patches  # type: ignore[assignment]
 
         # Run validations on the processed dataframe
         if validate:
@@ -1004,14 +1011,14 @@ class SpansClient:
         columns: list | None = None,
         stream_chunk_size: int | None = None,
     ) -> pd.DataFrame:
-        """Export span data from Arize to a pandas DataFrame.
+        """Export span data from Arize to a :class:`pandas.DataFrame`.
 
         Retrieves trace/span data from the specified project within a time range
-        and returns it as a pandas DataFrame. Supports filtering with SQL-like
+        and returns it as a :class:`pandas.DataFrame`. Supports filtering with SQL-like
         WHERE clauses and similarity search for semantic retrieval.
 
         Returns:
-            DataFrame containing the requested span data with columns
+            :class:`pandas.DataFrame`: DataFrame containing the requested span data with columns
                 for span metadata, attributes, events, and any custom fields.
         """
         with ArizeFlightClient(
@@ -1052,8 +1059,26 @@ class SpansClient:
 
         Retrieves trace/span data from the specified project within a time range
         and writes it directly to a Parquet file at the specified path. Supports
-        filtering with SQL-like WHERE clauses and similarity search for semantic
-        retrieval. Efficient for large datasets and long-term storage.
+        filtering with SQL-like WHERE clauses for efficient querying. Ideal for
+        large datasets and long-term storage.
+
+        Args:
+            path: The file path where the Parquet file will be written.
+            space_id: The space ID where the project resides.
+            project_name: The name of the project to export span data from.
+            start_time: Start of the time range (inclusive) as a datetime object.
+            end_time: End of the time range (inclusive) as a datetime object.
+            where: Optional SQL-like WHERE clause to filter rows (e.g., "span.status_code = 'ERROR'").
+            columns: Optional list of column names to include. If None, all columns are returned.
+            stream_chunk_size: Optional chunk size for streaming large result sets.
+
+        Raises:
+            RuntimeError: If the Flight client request fails or returns no response.
+
+        Notes:
+            - Uses Apache Arrow Flight for efficient data transfer
+            - Data is written directly to the specified path as a Parquet file
+            - Large exports may benefit from specifying stream_chunk_size
         """
         with ArizeFlightClient(
             api_key=self._sdk_config.api_key,
@@ -1066,7 +1091,7 @@ class SpansClient:
             exporter = ArizeExportClient(
                 flight_client=flight_client,
             )
-            return exporter.export_to_parquet(
+            exporter.export_to_parquet(
                 path=path,
                 space_id=space_id,
                 model_id=project_name,
@@ -1080,6 +1105,15 @@ class SpansClient:
 
 
 def _build_patch_document(row: pd.Series) -> dict[str, object]:
+    """Build a patch document from a pandas Series row by extracting metadata fields.
+
+    Args:
+        row: A pandas Series representing a row of data with potential metadata columns.
+
+    Returns:
+        dict[str, object]: A dictionary mapping metadata field names (without the
+            'attributes.metadata.' prefix) to their values, preserving arrays and scalars.
+    """
     # Extract and preserve metadata values with proper types
     patch = {}
     for key in row.index:
@@ -1101,9 +1135,21 @@ def _build_patch_document(row: pd.Series) -> dict[str, object]:
 def _process_patch_document(
     metadata_df: pd.DataFrame,
     patch_document_column_name: str,
-    field_patches: pd.DataFrame,
+    field_patches: pd.Series[Any],
     row_idx: int,
 ) -> dict[str, object]:
+    """Process and merge patch documents from field patches and explicit patch column.
+
+    Args:
+        metadata_df: DataFrame containing the metadata with patch documents.
+        patch_document_column_name: Name of the column containing explicit patch documents.
+        field_patches: DataFrame containing patches derived from individual metadata fields.
+        row_idx: The row index to process.
+
+    Returns:
+        dict[str, object]: Merged patch document where explicit patches take precedence over
+            field patches. Returns empty dict if patch document is invalid or missing.
+    """
     # Get the field patch for this row
     field_patch = field_patches.iloc[row_idx]
 
@@ -1150,9 +1196,21 @@ def _ensure_dict_patch(
     metadata_df: pd.DataFrame,
     final_patch_column: str,
     row_idx: int,
-) -> tuple[dict[str, object], list[str]]:
+) -> tuple[dict[str, object], list[ValidationError]]:
+    """Ensure a patch value is a dictionary, converting from JSON string if needed.
+
+    Args:
+        metadata_df: DataFrame containing the patch data.
+        final_patch_column: Name of the column containing the final patch document.
+        row_idx: The row index to process.
+
+    Returns:
+        tuple[dict[str, object], list[ValidationError]]: A tuple containing:
+            - The patch as a dictionary (empty dict if invalid or missing)
+            - List of validation errors (empty if no errors)
+    """
     patch = metadata_df.loc[row_idx, final_patch_column]
-    validation_errors = []
+    validation_errors: list[ValidationError] = []
 
     # For None/null values, return an empty dict
     if patch is None:
@@ -1171,25 +1229,26 @@ def _ensure_dict_patch(
         try:
             parsed = json.loads(patch)
             if isinstance(parsed, dict):
-                return parsed
+                return parsed, validation_errors
         except json.JSONDecodeError as e:
-            error_msg = f"Row {row_idx}: Invalid JSON in patch document: {e}"
-            logger.warning(error_msg)
-            validation_errors.append(error_msg)
+            error_msg = f"Invalid JSON in patch document: {e}"
+            logger.warning(f"Row {row_idx}: {error_msg}")
+            validation_errors.append(
+                InvalidPatchDocumentFormat(row_idx, error_msg)
+            )
             return {}, validation_errors  # if not validate else None
         else:
-            error_msg = (
-                f"Row {row_idx}: JSON must be an object/dictionary, "
-                f"got {type(parsed).__name__}"
+            error_msg = f"JSON must be an object/dictionary, got {type(parsed).__name__}"
+            logger.warning(f"Row {row_idx}: {error_msg}")
+            validation_errors.append(
+                InvalidPatchDocumentFormat(row_idx, error_msg)
             )
-            logger.warning(error_msg)
-            validation_errors.append(error_msg)
             return {}, validation_errors  # if not validate else None
 
     # For other types, log warning
-    error_msg = f"Row {row_idx}: Unsupported patch type: {type(patch).__name__}"
-    logger.warning(error_msg)
-    validation_errors.append(error_msg)
+    error_msg = f"Unsupported patch type: {type(patch).__name__}"
+    logger.warning(f"Row {row_idx}: {error_msg}")
+    validation_errors.append(InvalidPatchDocumentFormat(row_idx, error_msg))
     return {}, validation_errors  # if not validate else None
 
 
@@ -1197,6 +1256,16 @@ def _format_note_for_storage(
     note_text: str,
     current_time_ms: int,
 ) -> list[str] | None:
+    """Format a note text into a JSON-serialized list for storage.
+
+    Args:
+        note_text: The note text content to format.
+        current_time_ms: The current timestamp in milliseconds.
+
+    Returns:
+        list[str] | None: A list containing a single JSON string with note metadata
+            (text, updated_by, updated_at), or None if note_text is NaN/missing.
+    """
     if pd.isna(note_text):
         return None
     note_obj = {
@@ -1213,6 +1282,19 @@ def _log_flight_update_summary(
     request_type: FlightRequestType,
     response: FlightPostArrowFileResponse,
 ) -> None:
+    """Log a structured summary of Flight update results including metrics and errors.
+
+    Args:
+        project_name: Name of the project being updated.
+        total_spans: Total number of spans in the update request.
+        request_type: The type of Flight request being performed.
+        response: The Flight response object containing update results and errors.
+
+    Notes:
+        Logs one summary line with aggregated metrics, plus individual error lines
+        for any failed span updates. Metrics include success rate, spans processed,
+        and failure counts.
+    """
     spans_updated = getattr(response, "spans_updated", None)
     if spans_updated is None:
         # Fallback for older response types
@@ -1276,6 +1358,18 @@ def _message_to_dict(
     preserve_names: bool = True,
     use_int_enums: bool = False,
 ) -> dict[str, object]:
+    """Convert a protobuf Message to a dictionary representation.
+
+    Args:
+        msg: The protobuf Message to convert.
+        preserve_names: If True, preserve original proto field names. If False, use
+            lowerCamelCase names. Defaults to True.
+        use_int_enums: If True, represent enum values as integers. If False, use
+            enum string names. Defaults to False.
+
+    Returns:
+        dict[str, object]: Dictionary representation of the protobuf message.
+    """
     return json_format.MessageToDict(
         msg,
         preserving_proto_field_name=preserve_names,

arize/spans/columns.py

@@ -39,8 +39,6 @@ class SpanColumn:
         self.data_type = data_type
 
 
-#
-#
 # Root level columns
 SPAN_TRACE_ID_COL = SpanColumn(
     name="context.trace_id",
@@ -96,18 +94,18 @@ SPAN_KIND_COL = SpanColumn(
     data_type=SpanColumnDataType.STRING,
 )
 # Attributes Exception columns
-# SPAN_ATTRIBUTES_EXCEPTION_TYPE_COL = SpanColumn(
-#     name=f"attributes.{otel.SpanAttributes.EXCEPTION_TYPE}",
-#     data_type=SpanColumnDataType.STRING,
-# )
+SPAN_ATTRIBUTES_EXCEPTION_TYPE_COL = SpanColumn(
+    name=f"attributes.{otel.SpanAttributes.EXCEPTION_TYPE}",
+    data_type=SpanColumnDataType.STRING,
+)
 SPAN_ATTRIBUTES_EXCEPTION_MESSAGE_COL = SpanColumn(
     name=f"attributes.{otel.SpanAttributes.EXCEPTION_MESSAGE}",
     data_type=SpanColumnDataType.STRING,
 )
-# SPAN_ATTRIBUTES_EXCEPTION_ESCAPED_COL = SpanColumn(
-#     name=f"attributes.{otel.SpanAttributes.EXCEPTION_ESCAPED}",
-#     data_type=SpanColumnDataType.BOOL,
-# )
+SPAN_ATTRIBUTES_EXCEPTION_ESCAPED_COL = SpanColumn(
+    name=f"attributes.{otel.SpanAttributes.EXCEPTION_ESCAPED}",
+    data_type=SpanColumnDataType.BOOL,
+)
 SPAN_ATTRIBUTES_EXCEPTION_STACKTRACE_COL = SpanColumn(
     name=f"attributes.{otel.SpanAttributes.EXCEPTION_STACKTRACE}",
     data_type=SpanColumnDataType.STRING,
@@ -176,20 +174,19 @@ SPAN_ATTRIBUTES_LLM_PROMPT_TEMPLATE_VERSION_COL = SpanColumn(
     name=f"attributes.{oinf.SpanAttributes.LLM_PROMPT_TEMPLATE_VERSION}",
     data_type=SpanColumnDataType.STRING,
 )
-# SPAN_ATTRIBUTES_LLM_PROMPT_TOKEN_COUNT_COL = SpanColumn(
-#     name=f"attributes.{oinf.SpanAttributes.LLM_TOKEN_COUNT_PROMPT}",
-#     data_type=SpanColumnDataType.NUMERIC,
-# )
-# SPAN_ATTRIBUTES_LLM_COMPLETION_TOKEN_COUNT_COL = SpanColumn(
-#     name=f"attributes.{oinf.SpanAttributes.LLM_TOKEN_COUNT_COMPLETION}",
-#     data_type=SpanColumnDataType.NUMERIC,
-# )
-# SPAN_ATTRIBUTES_LLM_TOTAL_TOKEN_COUNT_COL = SpanColumn(
-#     name=f"attributes.{oinf.SpanAttributes.LLM_TOKEN_COUNT_TOTAL}",
-#     data_type=SpanColumnDataType.NUMERIC,
-# )
+SPAN_ATTRIBUTES_LLM_PROMPT_TOKEN_COUNT_COL = SpanColumn(
+    name=f"attributes.{oinf.SpanAttributes.LLM_TOKEN_COUNT_PROMPT}",
+    data_type=SpanColumnDataType.NUMERIC,
+)
+SPAN_ATTRIBUTES_LLM_COMPLETION_TOKEN_COUNT_COL = SpanColumn(
+    name=f"attributes.{oinf.SpanAttributes.LLM_TOKEN_COUNT_COMPLETION}",
+    data_type=SpanColumnDataType.NUMERIC,
+)
+SPAN_ATTRIBUTES_LLM_TOTAL_TOKEN_COUNT_COL = SpanColumn(
+    name=f"attributes.{oinf.SpanAttributes.LLM_TOKEN_COUNT_TOTAL}",
+    data_type=SpanColumnDataType.NUMERIC,
+)
 # Attributes Message Keys
-# SPAN_ATTRIBUTES_MESSAGE_NAME_KEY = f"{oinf.MessageAttributes.MESSAGE_NAME}"
 SPAN_ATTRIBUTES_MESSAGE_ROLE_KEY = f"{oinf.MessageAttributes.MESSAGE_ROLE}"
 SPAN_ATTRIBUTES_MESSAGE_CONTENT_KEY = (
     f"{oinf.MessageAttributes.MESSAGE_CONTENT}"
@@ -223,7 +220,6 @@ SPAN_ATTRIBUTES_RETRIEVAL_DOCUMENTS_COL = SpanColumn(
 )
 # Document Object Keys
 SPAN_ATTRIBUTES_DOCUMENT_ID_KEY = f"{oinf.DocumentAttributes.DOCUMENT_ID}"
-# SPAN_ATTRIBUTES_DOCUMENT_SCORE_KEY = f"{oinf.DocumentAttributes.DOCUMENT_SCORE}"
 SPAN_ATTRIBUTES_DOCUMENT_CONTENT_KEY = (
     f"{oinf.DocumentAttributes.DOCUMENT_CONTENT}"
 )
@@ -247,10 +243,10 @@ SPAN_ATTRIBUTES_RERANKER_MODEL_NAME_COL = SpanColumn(
     name=f"attributes.{oinf.RerankerAttributes.RERANKER_MODEL_NAME}",
     data_type=SpanColumnDataType.STRING,
 )
-# SPAN_ATTRIBUTES_RERANKER_TOP_K_COL = SpanColumn(
-#     name=f"attributes.{oinf.RerankerAttributes.RERANKER_TOP_K}",
-#     data_type=SpanColumnDataType.NUMERIC,
-# )
+SPAN_ATTRIBUTES_RERANKER_TOP_K_COL = SpanColumn(
+    name=f"attributes.{oinf.RerankerAttributes.RERANKER_TOP_K}",
+    data_type=SpanColumnDataType.NUMERIC,
+)
 SPAN_ATTRIBUTES_SESSION_ID = SpanColumn(
     name=f"attributes.{oinf.SpanAttributes.SESSION_ID}",
     data_type=SpanColumnDataType.STRING,
@@ -281,9 +277,9 @@ SPAN_OPENINFERENCE_COLUMNS = [
     SPAN_STATUS_CODE_COL,
     SPAN_STATUS_MESSAGE_COL,
     SPAN_EVENTS_COL,
-    #     SPAN_ATTRIBUTES_EXCEPTION_TYPE_COL,
+    SPAN_ATTRIBUTES_EXCEPTION_TYPE_COL,
     SPAN_ATTRIBUTES_EXCEPTION_MESSAGE_COL,
-    #     SPAN_ATTRIBUTES_EXCEPTION_ESCAPED_COL,
+    SPAN_ATTRIBUTES_EXCEPTION_ESCAPED_COL,
     SPAN_ATTRIBUTES_EXCEPTION_STACKTRACE_COL,
     SPAN_ATTRIBUTES_INPUT_VALUE_COL,
     SPAN_ATTRIBUTES_INPUT_MIME_TYPE_COL,
@@ -297,9 +293,9 @@ SPAN_OPENINFERENCE_COLUMNS = [
     SPAN_ATTRIBUTES_LLM_PROMPT_TEMPLATE_TEMPLATE_COL,
     SPAN_ATTRIBUTES_LLM_PROMPT_TEMPLATE_VARIABLES_COL,
     SPAN_ATTRIBUTES_LLM_PROMPT_TEMPLATE_VERSION_COL,
-    #     SPAN_ATTRIBUTES_LLM_PROMPT_TOKEN_COUNT_COL,
-    #     SPAN_ATTRIBUTES_LLM_COMPLETION_TOKEN_COUNT_COL,
-    #     SPAN_ATTRIBUTES_LLM_TOTAL_TOKEN_COUNT_COL,
+    SPAN_ATTRIBUTES_LLM_PROMPT_TOKEN_COUNT_COL,
+    SPAN_ATTRIBUTES_LLM_COMPLETION_TOKEN_COUNT_COL,
+    SPAN_ATTRIBUTES_LLM_TOTAL_TOKEN_COUNT_COL,
     SPAN_ATTRIBUTES_TOOL_NAME_COL,
     SPAN_ATTRIBUTES_TOOL_DESCRIPTION_COL,
     SPAN_ATTRIBUTES_TOOL_PARAMETERS_COL,
@@ -308,18 +304,18 @@ SPAN_OPENINFERENCE_COLUMNS = [
     SPAN_ATTRIBUTES_RERANKER_OUTPUT_DOCUMENTS_COL,
     SPAN_ATTRIBUTES_RERANKER_QUERY_COL,
     SPAN_ATTRIBUTES_RERANKER_MODEL_NAME_COL,
-    #     SPAN_ATTRIBUTES_RERANKER_TOP_K_COL,
+    SPAN_ATTRIBUTES_RERANKER_TOP_K_COL,
     SPAN_ATTRIBUTES_SESSION_ID,
     SPAN_ATTRIBUTES_USER_ID,
     SPAN_ATTRIBUTES_METADATA,
     SPAN_ATTRIBUTES_LLM_TOOLS_COL,
 ]
-#
+
 # List of columns that must be present in the dataframe
 SPAN_OPENINFERENCE_REQUIRED_COLUMNS = [
     col for col in SPAN_OPENINFERENCE_COLUMNS if col.required
 ]
-#
+
 # Eval columns
 # EVAL_COLUMN_PREFIX = "eval."
 # SESSION_EVAL_COLUMN_PREFIX = "session_eval."

arize/spans/conversion.py

@@ -7,22 +7,21 @@ from datetime import datetime, timezone
 import numpy as np
 import pandas as pd
 
-# from arize.utils.logging import logger
 from arize.spans.columns import SPAN_OPENINFERENCE_COLUMNS, SpanColumnDataType
 
 
 def convert_timestamps(df: pd.DataFrame, fmt: str = "") -> pd.DataFrame:
-    """Convert timestamp columns in a DataFrame to nanoseconds.
+    """Convert timestamp columns in a :class:`pandas.DataFrame` to nanoseconds.
 
     Args:
-        df: The pandas DataFrame containing timestamp columns.
+        df: The :class:`pandas.DataFrame` containing timestamp columns.
         fmt: Optional datetime format string for parsing string timestamps. Defaults to "".
 
     Returns:
-        The DataFrame with timestamp columns converted to nanoseconds.
+        The :class:`pandas.DataFrame` with timestamp columns converted to nanoseconds.
 
     Raises:
-        KeyError: If required timestamp column is not found in DataFrame.
+        KeyError: If required timestamp column is not found in :class:`pandas.DataFrame`.
     """
     for col in SPAN_OPENINFERENCE_COLUMNS:
         if col.data_type != SpanColumnDataType.TIMESTAMP:
@@ -70,7 +69,7 @@ def jsonify_dictionaries(df: pd.DataFrame) -> pd.DataFrame:
     """Convert dictionary and list-of-dictionary columns to JSON strings.
 
     Args:
-        df: The pandas DataFrame containing dictionary columns.
+        df: The :class:`pandas.DataFrame` containing dictionary columns.
 
     Returns:
         The DataFrame with dictionary columns converted to JSON strings.
@@ -121,17 +120,19 @@ def is_missing_value(value: object) -> bool:
         np.inf,
         -np.inf,
     )
-    return value in assumed_missing_values or pd.isna(value)
+    return value in assumed_missing_values or pd.isna(value)  # type: ignore[call-overload]
 
 
 def _jsonify_list_of_dicts(
     list_of_dicts: Iterable[dict[str, object]] | None,
 ) -> list[str]:
-    if not isinstance(list_of_dicts, Iterable) and is_missing_value(
-        list_of_dicts
-    ):
+    if list_of_dicts is None or is_missing_value(list_of_dicts):
         return []
-    return [_jsonify_dict(d) for d in list_of_dicts]
+    return [
+        result
+        for d in list_of_dicts
+        if (result := _jsonify_dict(d)) is not None
+    ]
 
 
 def _jsonify_dict(d: dict[str, object] | None) -> str | None:

arize/spans/validation/annotations/dataframe_form_validation.py

@@ -65,7 +65,7 @@ def check_invalid_annotation_column_names(
     df: pd.DataFrame,
 ) -> list[ValidationError]:
     """Checks for columns that start with 'annotation.' but don't match the expected pattern."""
-    errors = []
+    errors: list[ValidationError] = []
 
     invalid_annotation_columns = [
         col

arize/spans/validation/annotations/value_validation.py

@@ -78,7 +78,7 @@ def check_annotation_updated_at_timestamp(
     df: pd.DataFrame,
     col_name: str,
     is_required: bool,
-) -> list[InvalidMissingValueInColumn | InvalidAnnotationTimestamp]:
+) -> list[ValidationError]:
     """Validates annotation timestamp values for validity and acceptable ranges.
 
     Checks that timestamp values are positive, not in the future, and satisfy
@@ -96,7 +96,7 @@ def check_annotation_updated_at_timestamp(
     if col_name not in df.columns:
         return []
 
-    errors = []
+    errors: list[ValidationError] = []
     if is_required and df[col_name].isnull().any():
         errors.append(
             InvalidMissingValueInColumn(
@@ -131,7 +131,7 @@ def check_annotation_cols(
     dataframe: pd.DataFrame,
 ) -> list[ValidationError]:
     """Checks value length and validity for columns matching annotation patterns."""
-    checks = []
+    checks: list[list[ValidationError]] = []
     for col in dataframe.columns:
         if col.endswith(ANNOTATION_LABEL_SUFFIX):
             checks.append(
@@ -140,7 +140,8 @@ def check_annotation_cols(
                     col_name=col,
                     min_len=ANNOTATION_LABEL_MIN_STR_LENGTH,
                     max_len=ANNOTATION_LABEL_MAX_STR_LENGTH,
-                    is_required=False,  # Individual columns are not required, null check handles completeness
+                    # Individual columns are not required
+                    is_required=False,
                 )
             )
         elif col.endswith(ANNOTATION_SCORE_SUFFIX):
@@ -231,15 +232,11 @@ def check_annotation_notes_column(
     col_name = ANNOTATION_NOTES_COLUMN_NAME
     if col_name in dataframe.columns:
         # Validate the length of the raw string
-        return list(
-            chain(
-                *common_value_validation.check_string_column_value_length(
-                    df=dataframe,
-                    col_name=col_name,
-                    min_len=0,  # Allow empty notes
-                    max_len=ANNOTATION_NOTES_MAX_STR_LENGTH,
-                    is_required=False,
-                )
-            )
+        return common_value_validation.check_string_column_value_length(
+            df=dataframe,
+            col_name=col_name,
+            min_len=0,  # Allow empty notes
+            max_len=ANNOTATION_NOTES_MAX_STR_LENGTH,
+            is_required=False,
         )
     return []

arize/spans/validation/common/argument_validation.py

@@ -39,13 +39,13 @@ def check_field_convertible_to_str(
 def check_dataframe_type(
     dataframe: object,
 ) -> list[InvalidTypeArgument]:
-    """Validates that the provided argument is a pandas DataFrame.
+    """Validates that the provided argument is a :class:`pandas.DataFrame`.
 
     Args:
-        dataframe: The object to validate as a pandas DataFrame.
+        dataframe: The object to validate as a :class:`pandas.DataFrame`.
 
     Returns:
-        List of validation errors if not a DataFrame (empty if valid).
+        List of validation errors if not a :class:`pandas.DataFrame` (empty if valid).
     """
     if not isinstance(dataframe, pd.DataFrame):
         return [

arize/spans/validation/common/dataframe_form_validation.py

@@ -17,10 +17,10 @@ if TYPE_CHECKING:
 def check_dataframe_index(
     dataframe: pd.DataFrame,
 ) -> list[InvalidDataFrameIndex]:
-    """Validates that the DataFrame has a default integer index.
+    """Validates that the :class:`pandas.DataFrame` has a default integer index.
 
     Args:
-        dataframe: The DataFrame to validate.
+        dataframe: The :class:`pandas.DataFrame` to validate.
 
     Returns:
         List of validation errors if index is not default (empty if valid).
@@ -34,10 +34,10 @@ def check_dataframe_required_column_set(
     df: pd.DataFrame,
     required_columns: list[str],
 ) -> list[InvalidDataFrameMissingColumns]:
-    """Validates that the DataFrame contains all required columns.
+    """Validates that the :class:`pandas.DataFrame` contains all required columns.
 
     Args:
-        df: The DataFrame to validate.
+        df: The :class:`pandas.DataFrame` to validate.
         required_columns: List of column names that must be present.
 
     Returns:
@@ -56,10 +56,10 @@ def check_dataframe_required_column_set(
 def check_dataframe_for_duplicate_columns(
     df: pd.DataFrame,
 ) -> list[InvalidDataFrameDuplicateColumns]:
-    """Validates that the DataFrame has no duplicate column names.
+    """Validates that the :class:`pandas.DataFrame` has no duplicate column names.
 
     Args:
-        df: The DataFrame to validate.
+        df: The :class:`pandas.DataFrame` to validate.
 
     Returns:
         List of validation errors if duplicate columns exist (empty if valid).
@@ -67,5 +67,5 @@ def check_dataframe_for_duplicate_columns(
     # Get the duplicated column names from the dataframe
     duplicate_columns = df.columns[df.columns.duplicated()]
     if not duplicate_columns.empty:
-        return [InvalidDataFrameDuplicateColumns(duplicate_columns)]
+        return [InvalidDataFrameDuplicateColumns(duplicate_columns.tolist())]
     return []