arize 8.0.0a22__py3-none-any.whl → 8.0.0a23__py3-none-any.whl

arize/spans/validation/evals/dataframe_form_validation.py

@@ -1,6 +1,7 @@
+"""DataFrame form validation for span evaluations."""
+
 import logging
 import re
-from typing import List
 
 import pandas as pd
 
@@ -12,7 +13,7 @@ from arize.spans.columns import (
     EVAL_SCORE_PATTERN,
     SPAN_SPAN_ID_COL,
 )
-from arize.spans.conversion import isMissingValue
+from arize.spans.conversion import is_missing_value
 from arize.spans.validation.common.errors import (
     InvalidDataFrameColumnContentTypes,
 )
@@ -23,8 +24,16 @@ logger = logging.getLogger(__name__)
 def log_info_dataframe_extra_column_names(
     df: pd.DataFrame | None,
 ) -> None:
+    """Logs informational message about columns that don't follow evaluation naming conventions.
+
+    Args:
+        df: DataFrame to check for extra column names, or None.
+
+    Returns:
+        None.
+    """
     if df is None:
-        return None
+        return
     irrelevant_columns = [
         col
         for col in df.columns
@@ -42,12 +51,23 @@ def log_info_dataframe_extra_column_names(
             "- eval.<your-eval-name>.score"
             "- eval.<your-eval-name>.explanation"
         )
-    return None
+    return
 
 
 def check_dataframe_column_content_type(
     df: pd.DataFrame,
-) -> List[InvalidDataFrameColumnContentTypes]:
+) -> list[InvalidDataFrameColumnContentTypes]:
+    """Validates that evaluation DataFrame columns contain expected data types.
+
+    Checks that label columns contain strings, score columns contain numbers,
+    and explanation columns contain strings.
+
+    Args:
+        df: The DataFrame to validate.
+
+    Returns:
+        List of validation errors for columns with incorrect types.
+    """
     wrong_labels_cols = []
     wrong_scores_cols = []
     wrong_explanations_cols = []
@@ -67,18 +87,18 @@ def check_dataframe_column_content_type(
             )
         if eval_label_re.match(column):
             if not all(
-                isinstance(value, str) or isMissingValue(value)
+                isinstance(value, str) or is_missing_value(value)
                 for value in df[column]
             ):
                 wrong_labels_cols.append(column)
         elif eval_score_re.match(column):
             if not all(
-                isinstance(value, (int, float)) or isMissingValue(value)
+                isinstance(value, (int, float)) or is_missing_value(value)
                 for value in df[column]
             ):
                 wrong_scores_cols.append(column)
         elif eval_explanation_re.match(column) and not all(
-            isinstance(value, str) or isMissingValue(value)
+            isinstance(value, str) or is_missing_value(value)
             for value in df[column]
         ):
             wrong_explanations_cols.append(column)

arize/spans/validation/evals/evals_validation.py

@@ -1,7 +1,9 @@
+"""Evaluation validation orchestration for spans."""
+
 from __future__ import annotations
 
 from itertools import chain
-from typing import TYPE_CHECKING, List
+from typing import TYPE_CHECKING
 
 from arize.spans.columns import SPAN_SPAN_ID_COL
 from arize.spans.validation.common import (
@@ -30,7 +32,17 @@ def validate_argument_types(
     evals_dataframe: pd.DataFrame,
     project_name: str,
     model_version: str | None = None,
-) -> List[ValidationError]:
+) -> list[ValidationError]:
+    """Validate argument types for evaluation data submission.
+
+    Args:
+        evals_dataframe: The DataFrame containing evaluation data.
+        project_name: The project name to validate.
+        model_version: Optional model version to validate. Defaults to None.
+
+    Returns:
+        List of validation errors found in argument types.
+    """
     checks = chain(
         common_arg_validation.check_field_convertible_to_str(
             project_name, model_version
@@ -42,7 +54,15 @@ def validate_argument_types(
 
 def validate_dataframe_form(
     evals_dataframe: pd.DataFrame,
-) -> List[ValidationError]:
+) -> list[ValidationError]:
+    """Validate the structure and form of an evaluations DataFrame.
+
+    Args:
+        evals_dataframe: The DataFrame containing evaluation data to validate.
+
+    Returns:
+        List of validation errors found in the DataFrame structure.
+    """
     df_validation.log_info_dataframe_extra_column_names(evals_dataframe)
     checks = chain(
         # Common
@@ -63,7 +83,17 @@ def validate_values(
     evals_dataframe: pd.DataFrame,
     project_name: str,
     model_version: str | None = None,
-) -> List[ValidationError]:
+) -> list[ValidationError]:
+    """Validate the values within an evaluations DataFrame.
+
+    Args:
+        evals_dataframe: The DataFrame containing evaluation data to validate.
+        project_name: The project name associated with the evaluations.
+        model_version: Optional model version. Defaults to None.
+
+    Returns:
+        List of validation errors found in DataFrame values.
+    """
     checks = chain(
         # Common
         common_value_validation.check_invalid_project_name(project_name),

arize/spans/validation/evals/value_validation.py

@@ -1,8 +1,10 @@
+"""Value validation logic for span evaluation data."""
+
 from __future__ import annotations
 
 import re
 from itertools import chain
-from typing import TYPE_CHECKING, List
+from typing import TYPE_CHECKING
 
 from arize.constants.spans import (
     EVAL_EXPLANATION_MAX_STR_LENGTH,
@@ -26,7 +28,18 @@ if TYPE_CHECKING:
 
 def check_eval_cols(
     dataframe: pd.DataFrame,
-) -> List[ValidationError]:
+) -> list[ValidationError]:
+    """Validates evaluation column values for proper length and format.
+
+    Checks label strings for length constraints, scores for valid numeric values,
+    and explanations for length constraints.
+
+    Args:
+        dataframe: The DataFrame containing evaluation columns.
+
+    Returns:
+        List of validation errors found in evaluation columns.
+    """
     checks = []
     for col in dataframe.columns:
         if col.endswith(EVAL_LABEL_SUFFIX):
@@ -64,7 +77,17 @@ def check_eval_cols(
 # is not null
 def check_eval_columns_null_values(
     dataframe: pd.DataFrame,
-) -> List[ValidationError]:
+) -> list[ValidationError]:
+    """Validates that evaluation columns don't have orphan explanations without labels or scores.
+
+    Ensures that if an explanation exists, at least one of label or score is non-null.
+
+    Args:
+        dataframe: The DataFrame containing evaluation columns.
+
+    Returns:
+        List of validation errors for evaluations with invalid null combinations.
+    """
     invalid_eval_names = []
     eval_prefix_and_name = set()
     for col in dataframe.columns:

arize/spans/validation/metadata/__init__.py

@@ -1 +1 @@
-
+"""Metadata validation for LLM tracing spans."""

arize/spans/validation/metadata/argument_validation.py

@@ -1,4 +1,4 @@
-from typing import List
+"""Argument validation for span metadata."""
 
 import pandas as pd
 
@@ -6,22 +6,31 @@ from arize.exceptions.base import ValidationError
 
 
 class MetadataArgumentError(ValidationError):
+    """Raised when metadata arguments are invalid or incorrectly specified."""
+
     def __init__(self, message: str, resolution: str) -> None:
+        """Initialize the exception with metadata argument error context.
+
+        Args:
+            message: Error message describing the invalid argument.
+            resolution: Guidance on how to resolve the error.
+        """
         self.message = message
         self.resolution = resolution
 
     def __repr__(self) -> str:
+        """Return a string representation for debugging and logging."""
         return "Metadata_Argument_Error"
 
     def error_message(self) -> str:
+        """Return the error message for this exception."""
         return f"{self.message} {self.resolution}"
 
 
 def validate_argument_types(
-    metadata_dataframe, project_name
-) -> List[ValidationError]:
-    """
-    Validates the types of arguments passed to update_spans_metadata.
+    metadata_dataframe: object, project_name: object
+) -> list[ValidationError]:
+    """Validates the types of arguments passed to update_spans_metadata.
 
     Args:
         metadata_dataframe: DataFrame with span IDs and patch documents

arize/spans/validation/metadata/dataframe_form_validation.py

@@ -1,26 +1,38 @@
-from typing import List
+"""DataFrame form validation for span metadata."""
+
+import pandas as pd
 
 from arize.exceptions.base import ValidationError
 from arize.spans.columns import SPAN_SPAN_ID_COL
 
 
 class MetadataFormError(ValidationError):
+    """Raised when metadata DataFrame structure or format is invalid."""
+
     def __init__(self, message: str, resolution: str) -> None:
+        """Initialize the exception with metadata form error context.
+
+        Args:
+            message: Error message describing the invalid DataFrame structure.
+            resolution: Guidance on how to resolve the error.
+        """
         self.message = message
         self.resolution = resolution
 
     def __repr__(self) -> str:
+        """Return a string representation for debugging and logging."""
         return "Metadata_Form_Error"
 
     def error_message(self) -> str:
+        """Return the error message for this exception."""
         return f"{self.message} {self.resolution}"
 
 
 def validate_dataframe_form(
-    metadata_dataframe, patch_document_column_name="patch_document"
-) -> List[ValidationError]:
-    """
-    Validates the structure of the metadata update dataframe.
+    metadata_dataframe: pd.DataFrame,
+    patch_document_column_name: str = "patch_document",
+) -> list[ValidationError]:
+    """Validates the structure of the metadata update dataframe.
 
     Args:
         metadata_dataframe: DataFrame with span IDs and patch documents or attributes.metadata.* columns
@@ -90,11 +102,15 @@ def validate_dataframe_form(
 
     # If using metadata fields, check each one
     if has_metadata_fields:
-        for col in metadata_columns:
-            if (
-                metadata_dataframe[col].isna().all()
-            ):  # All values in column are null
-                null_columns.append(col)
+        null_columns.extend(
+            [
+                col
+                for col in metadata_columns
+                if metadata_dataframe[col]
+                .isna()
+                .all()  # All values in column are null
+            ]
+        )
 
     if null_columns:
         errors.append(

arize/spans/validation/metadata/value_validation.py

@@ -1,5 +1,8 @@
+"""Value validation logic for span metadata."""
+
 import json
-from typing import List
+
+import pandas as pd
 
 from arize.constants.spans import (
     MAX_JSON_NESTING_DEPTH,
@@ -10,20 +13,32 @@ from arize.spans.columns import SPAN_SPAN_ID_COL
 
 
 class MetadataValueError(ValidationError):
+    """Raised when metadata values are invalid or violate constraints."""
+
     def __init__(self, message: str, resolution: str) -> None:
+        """Initialize the exception with metadata value error context.
+
+        Args:
+            message: Error message describing the invalid value.
+            resolution: Guidance on how to resolve the error.
+        """
         self.message = message
         self.resolution = resolution
 
     def __repr__(self) -> str:
+        """Return a string representation for debugging and logging."""
         return "Metadata_Value_Error"
 
     def error_message(self) -> str:
+        """Return the error message for this exception."""
         return f"{self.message} {self.resolution}"
 
 
-def calculate_json_depth(obj, current_depth=1):
+def calculate_json_depth(obj: object, current_depth: int = 1) -> int:
     """Calculate the maximum nesting depth of a JSON object.
-    Stops recursing once MAX_JSON_NESTING_DEPTH + 1 is reached for efficiency."""
+
+    Stops recursing once MAX_JSON_NESTING_DEPTH + 1 is reached for efficiency.
+    """
     # If we've already exceeded the max depth, return the current depth to avoid unnecessary recursion
     if current_depth > MAX_JSON_NESTING_DEPTH:
         return current_depth
@@ -32,19 +47,18 @@ def calculate_json_depth(obj, current_depth=1):
         return max(
             [calculate_json_depth(v, current_depth + 1) for v in obj.values()]
         )
-    elif isinstance(obj, list) and obj:
+    if isinstance(obj, list) and obj:
         return max(
             [calculate_json_depth(item, current_depth + 1) for item in obj]
         )
-    else:
-        return current_depth
+    return current_depth
 
 
 def validate_values(
-    metadata_dataframe, patch_document_column_name="patch_document"
-) -> List[ValidationError]:
-    """
-    Validates the values in the metadata update dataframe.
+    metadata_dataframe: pd.DataFrame,
+    patch_document_column_name: str = "patch_document",
+) -> list[ValidationError]:
+    """Validates the values in the metadata update dataframe.
 
     Args:
         metadata_dataframe: DataFrame with span IDs and patch documents or attributes.metadata.* columns

arize/spans/validation/spans/__init__.py

@@ -0,0 +1 @@
+"""Span data validation for LLM tracing."""

arize/spans/validation/spans/dataframe_form_validation.py

@@ -1,15 +1,14 @@
+"""DataFrame form validation for spans."""
+
 import logging
+from collections.abc import Iterable
 from datetime import datetime
-from typing import Iterable, List
 
 import pandas as pd
 from pandas.api.types import is_bool_dtype, is_numeric_dtype
 
-from arize.spans.columns import (
-    SPAN_OPENINFERENCE_COLUMNS,
-    SpanColumnDataType,
-)
-from arize.spans.conversion import isMissingValue
+from arize.spans.columns import SPAN_OPENINFERENCE_COLUMNS, SpanColumnDataType
+from arize.spans.conversion import is_missing_value
 from arize.spans.validation.common.errors import (
     InvalidDataFrameColumnContentTypes,
 )
@@ -21,6 +20,14 @@ logger = logging.getLogger(__name__)
 def log_info_dataframe_extra_column_names(
     df: pd.DataFrame,
 ) -> None:
+    """Logs informational message about columns not part of Open Inference Specification.
+
+    Args:
+        df: DataFrame to check for extra column names.
+
+    Returns:
+        None.
+    """
     min_col_set = [col.name for col in SPAN_OPENINFERENCE_COLUMNS]
     extra_col_names = [col for col in df.columns if col not in min_col_set]
     if extra_col_names:
@@ -31,7 +38,7 @@ def log_info_dataframe_extra_column_names(
                 "extra_columns": extra_col_names,
             },
         )
-    return None
+    return
 
 
 # TODO(Kiko): Performance improvements
@@ -42,7 +49,18 @@ def log_info_dataframe_extra_column_names(
 # https://github.com/pandas-dev/pandas/blob/f538741432edf55c6b9fb5d0d496d2dd1d7c2457/pandas/core/dtypes/common.py
 def check_dataframe_column_content_type(
     df: pd.DataFrame,
-) -> List[InvalidDataFrameColumnContentTypes]:
+) -> list[InvalidDataFrameColumnContentTypes]:
+    """Validates that span DataFrame columns contain data types matching Open Inference Specification.
+
+    Checks that columns have appropriate data types: lists of dicts, dicts, numeric,
+    boolean, timestamp, JSON strings, or plain strings based on column specifications.
+
+    Args:
+        df: The DataFrame to validate.
+
+    Returns:
+        List of validation errors for columns with incorrect types.
+    """
     # We let this values be in the dataframe and don't use them to verify type
     # They will be serialized by arrow and understood as missing values
     wrong_lists_of_dicts_cols = []
@@ -57,7 +75,7 @@ def check_dataframe_column_content_type(
             continue
         if col.data_type == SpanColumnDataType.LIST_DICT:
             for row in df[col.name]:
-                if not isinstance(row, Iterable) and isMissingValue(row):
+                if not isinstance(row, Iterable) and is_missing_value(row):
                     continue
                 if not (
                     is_list_of(row, dict) or is_array_of(row, dict)
@@ -68,7 +86,10 @@ def check_dataframe_column_content_type(
                     break
         elif col.data_type == SpanColumnDataType.DICT:
             if not all(
-                (isMissingValue(row) or is_dict_of(row, key_allowed_types=str))
+                (
+                    is_missing_value(row)
+                    or is_dict_of(row, key_allowed_types=str)
+                )
                 for row in df[col.name]
             ):
                 wrong_dicts_cols.append(col.name)
@@ -82,7 +103,7 @@ def check_dataframe_column_content_type(
             # Accept strings and datetime objects, and int64
             if not all(
                 (
-                    isMissingValue(row)
+                    is_missing_value(row)
                     or isinstance(row, (str, datetime, pd.Timestamp, int))
                 )
                 for row in df[col.name]
@@ -92,12 +113,12 @@ def check_dataframe_column_content_type(
             # We check the correctness of the JSON strings when we check the values
             # of the data in the dataframe
             if not all(
-                (isMissingValue(row) or isinstance(row, str))
+                (is_missing_value(row) or isinstance(row, str))
                 for row in df[col.name]
             ):
                 wrong_JSON_cols.append(col.name)
         elif col.data_type == SpanColumnDataType.STRING and not all(
-            (isMissingValue(row) or isinstance(row, str))
+            (is_missing_value(row) or isinstance(row, str))
             for row in df[col.name]
         ):
             wrong_string_cols.append(col.name)

arize/spans/validation/spans/spans_validation.py

@@ -1,7 +1,9 @@
+"""Span validation orchestration and coordination."""
+
 from __future__ import annotations
 
 from itertools import chain
-from typing import TYPE_CHECKING, List
+from typing import TYPE_CHECKING
 
 from arize.spans.columns import SPAN_OPENINFERENCE_REQUIRED_COLUMNS
 from arize.spans.validation.common import (
@@ -29,7 +31,18 @@ def validate_argument_types(
     project_name: str,
     dt_fmt: str,
     model_version: str | None = None,
-) -> List[ValidationError]:
+) -> list[ValidationError]:
+    """Validate argument types for spans data submission.
+
+    Args:
+        spans_dataframe: The DataFrame containing spans data.
+        project_name: The project name to validate.
+        dt_fmt: The datetime format string to validate.
+        model_version: Optional model version to validate. Defaults to None.
+
+    Returns:
+        List of validation errors found in argument types.
+    """
     checks = chain(
         common_arg_validation.check_field_convertible_to_str(
             project_name, model_version
@@ -42,7 +55,15 @@ def validate_argument_types(
 
 def validate_dataframe_form(
     spans_dataframe: pd.DataFrame,
-) -> List[ValidationError]:
+) -> list[ValidationError]:
+    """Validate the structure and form of a spans DataFrame.
+
+    Args:
+        spans_dataframe: The DataFrame containing spans data to validate.
+
+    Returns:
+        List of validation errors found in the DataFrame structure.
+    """
     df_validation.log_info_dataframe_extra_column_names(spans_dataframe)
     checks = chain(
         # Common
@@ -66,7 +87,17 @@ def validate_values(
     spans_dataframe: pd.DataFrame,
     project_name: str,
     model_version: str | None = None,
-) -> List[ValidationError]:
+) -> list[ValidationError]:
+    """Validate the values within a spans DataFrame.
+
+    Args:
+        spans_dataframe: The DataFrame containing spans data to validate.
+        project_name: The project name associated with the spans.
+        model_version: Optional model version. Defaults to None.
+
+    Returns:
+        List of validation errors found in DataFrame values.
+    """
     checks = chain(
         # Common
         common_value_validation.check_invalid_project_name(project_name),

arize/spans/validation/spans/value_validation.py

@@ -1,7 +1,9 @@
+"""Value validation logic for span data."""
+
 from __future__ import annotations
 
 from itertools import chain
-from typing import TYPE_CHECKING, List
+from typing import TYPE_CHECKING
 
 from arize.constants import spans as tracing_constants
 from arize.constants.ml import MAX_EMBEDDING_DIMENSIONALITY
@@ -23,7 +25,18 @@ if TYPE_CHECKING:
 
 def check_span_root_field_values(
     dataframe: pd.DataFrame,
-) -> List[ValidationError]:
+) -> list[ValidationError]:
+    """Validates root-level span field values for proper format and constraints.
+
+    Checks span ID, trace ID, parent span ID, name, status code, status message,
+    timestamps, and events for conformance to specification limits.
+
+    Args:
+        dataframe: The DataFrame containing span data.
+
+    Returns:
+        List of validation errors found in root span fields.
+    """
     return list(
         chain(
             value_validation.check_string_column_value_length(
@@ -77,7 +90,18 @@ def check_span_root_field_values(
 
 def check_span_attributes_values(
     dataframe: pd.DataFrame,
-) -> List[ValidationError]:
+) -> list[ValidationError]:
+    """Validates span attribute values for proper format and constraints.
+
+    Checks all span attributes including LLM parameters, embeddings, documents,
+    tools, and other metadata fields for conformance to specification limits.
+
+    Args:
+        dataframe: The DataFrame containing span data.
+
+    Returns:
+        List of validation errors found in span attributes.
+    """
     return list(
         chain(
             value_validation.check_string_column_value_length(
@@ -242,7 +266,17 @@ def check_span_attributes_values(
 
 def check_event_column_value(
     df: pd.DataFrame,
-) -> List[InvalidEventValueInColumn]:
+) -> list[InvalidEventValueInColumn]:
+    """Validates span event column values for proper format and length constraints.
+
+    Checks event names for length limits and attributes for proper dictionary structure.
+
+    Args:
+        df: The DataFrame containing span events.
+
+    Returns:
+        List of validation errors found in event column values.
+    """
     col_name = tracing_cols.SPAN_EVENTS_COL.name
     if col_name not in df.columns:
         return []
@@ -284,7 +318,18 @@ def check_event_column_value(
 
 def check_embeddings_column_value(
     df: pd.DataFrame,
-) -> List[InvalidEmbeddingValueInColumn]:
+) -> list[InvalidEmbeddingValueInColumn]:
+    """Validates embedding column values for proper vector dimensions and text length.
+
+    Checks that embedding vectors are within dimensionality limits and text
+    values don't exceed maximum length.
+
+    Args:
+        df: The DataFrame containing embedding data.
+
+    Returns:
+        List of validation errors found in embedding column values.
+    """
     col_name = tracing_cols.SPAN_ATTRIBUTES_EMBEDDING_EMBEDDINGS_COL.name
     if col_name not in df.columns:
         return []
@@ -332,7 +377,19 @@ def check_embeddings_column_value(
 def check_LLM_IO_messages_column_value(
     df: pd.DataFrame,
     col_name: str,
-) -> List[InvalidLLMMessageValueInColumn]:
+) -> list[InvalidLLMMessageValueInColumn]:
+    """Validates LLM input/output message column values for proper format and length.
+
+    Checks message role, content, and tool calls for conformance to length limits
+    and proper JSON formatting.
+
+    Args:
+        df: The DataFrame containing LLM messages.
+        col_name: Name of the message column to validate.
+
+    Returns:
+        List of validation errors found in message column values.
+    """
     if col_name not in df.columns:
         return []
 
@@ -407,7 +464,19 @@ def check_LLM_IO_messages_column_value(
 def check_documents_column_value(
     df: pd.DataFrame,
     col_name: str,
-) -> List[InvalidDocumentValueInColumn]:
+) -> list[InvalidDocumentValueInColumn]:
+    """Validates document column values for proper format and length constraints.
+
+    Checks document ID, content, and metadata for conformance to length limits
+    and proper data type requirements.
+
+    Args:
+        df: The DataFrame containing documents.
+        col_name: Name of the document column to validate.
+
+    Returns:
+        List of validation errors found in document column values.
+    """
     if col_name not in df.columns:
         return []