arize-phoenix 3.16.1__py3-none-any.whl → 7.7.0__py3-none-any.whl

phoenix/trace/otel.py

@@ -1,39 +1,34 @@
-import inspect
 import json
 from binascii import hexlify, unhexlify
+from collections.abc import Iterable, Iterator, Mapping, Sequence
 from datetime import datetime, timezone
 from types import MappingProxyType
-from typing import (
-    Any,
-    DefaultDict,
-    Dict,
-    Iterable,
-    Iterator,
-    List,
-    Mapping,
-    Optional,
-    Sequence,
-    Set,
-    SupportsFloat,
-    Tuple,
-    Union,
-    cast,
-)
+from typing import Any, Optional, SupportsFloat, cast
 
 import numpy as np
 import opentelemetry.proto.trace.v1.trace_pb2 as otlp
-from openinference.semconv import trace
-from openinference.semconv.trace import DocumentAttributes, SpanAttributes
+from openinference.semconv.trace import (
+    DocumentAttributes,
+    OpenInferenceMimeTypeValues,
+    SpanAttributes,
+)
 from opentelemetry.proto.common.v1.common_pb2 import AnyValue, ArrayValue, KeyValue
 from opentelemetry.util.types import Attributes, AttributeValue
 from typing_extensions import TypeAlias, assert_never
 
+from phoenix.trace.attributes import (
+    JSON_STRING_ATTRIBUTES,
+    flatten,
+    get_attribute_value,
+    has_mapping,
+    load_json_strings,
+    unflatten,
+)
 from phoenix.trace.schemas import (
     EXCEPTION_ESCAPED,
     EXCEPTION_MESSAGE,
     EXCEPTION_STACKTRACE,
     EXCEPTION_TYPE,
-    MimeType,
     Span,
     SpanContext,
     SpanEvent,
@@ -43,6 +38,7 @@ from phoenix.trace.schemas import (
     SpanStatusCode,
     TraceID,
 )
+from phoenix.utilities.json import jsonify
 
 DOCUMENT_METADATA = DocumentAttributes.DOCUMENT_METADATA
 INPUT_MIME_TYPE = SpanAttributes.INPUT_MIME_TYPE
@@ -53,28 +49,45 @@ OUTPUT_MIME_TYPE = SpanAttributes.OUTPUT_MIME_TYPE
 OUTPUT_VALUE = SpanAttributes.OUTPUT_VALUE
 TOOL_PARAMETERS = SpanAttributes.TOOL_PARAMETERS
 LLM_PROMPT_TEMPLATE_VARIABLES = SpanAttributes.LLM_PROMPT_TEMPLATE_VARIABLES
+LLM_TOKEN_COUNT_PROMPT = SpanAttributes.LLM_TOKEN_COUNT_PROMPT
+LLM_TOKEN_COUNT_COMPLETION = SpanAttributes.LLM_TOKEN_COUNT_COMPLETION
+LLM_TOKEN_COUNT_TOTAL = SpanAttributes.LLM_TOKEN_COUNT_TOTAL
 
 
-def decode(otlp_span: otlp.Span) -> Span:
+def coerce_otlp_span_attributes(
+    decoded_attributes: Iterable[tuple[str, Any]],
+) -> Iterator[tuple[str, Any]]:
+    for key, value in decoded_attributes:
+        if key in (LLM_TOKEN_COUNT_PROMPT, LLM_TOKEN_COUNT_COMPLETION, LLM_TOKEN_COUNT_TOTAL):
+            try:
+                value = int(value)
+            except BaseException:
+                pass
+        yield key, value
+
+
+def decode_otlp_span(otlp_span: otlp.Span) -> Span:
     trace_id = cast(TraceID, _decode_identifier(otlp_span.trace_id))
     span_id = cast(SpanID, _decode_identifier(otlp_span.span_id))
     parent_id = _decode_identifier(otlp_span.parent_span_id)
 
     start_time = _decode_unix_nano(otlp_span.start_time_unix_nano)
-    end_time = (
-        _decode_unix_nano(otlp_span.end_time_unix_nano) if otlp_span.end_time_unix_nano else None
-    )
+    end_time = _decode_unix_nano(otlp_span.end_time_unix_nano)
 
-    attributes = dict(_unflatten(_load_json_strings(_decode_key_values(otlp_span.attributes))))
-    span_kind = SpanKind(attributes.pop(OPENINFERENCE_SPAN_KIND, None))
-
-    for mime_type in (INPUT_MIME_TYPE, OUTPUT_MIME_TYPE):
-        if mime_type in attributes:
-            attributes[mime_type] = MimeType(attributes[mime_type])
+    attributes = unflatten(
+        load_json_strings(coerce_otlp_span_attributes(_decode_key_values(otlp_span.attributes)))
+    )
+    span_kind = SpanKind(get_attribute_value(attributes, OPENINFERENCE_SPAN_KIND))
 
     status_code, status_message = _decode_status(otlp_span.status)
     events = [_decode_event(event) for event in otlp_span.events]
 
+    if (input_value := get_attribute_value(attributes, INPUT_VALUE)) and not isinstance(
+        input_value, str
+    ):
+        attributes["input"]["value"] = json.dumps(input_value)
+        attributes["input"]["mime_type"] = OpenInferenceMimeTypeValues.JSON.value
+
     return Span(
         name=otlp_span.name,
         context=SpanContext(
@@ -127,7 +140,7 @@ def _decode_unix_nano(time_unix_nano: int) -> datetime:
 
 def _decode_key_values(
     key_values: Iterable[KeyValue],
-) -> Iterator[Tuple[str, Any]]:
+) -> Iterator[tuple[str, Any]]:
     return ((kv.key, _decode_value(kv.value)) for kv in key_values)
 
 
@@ -152,28 +165,6 @@ def _decode_value(any_value: AnyValue) -> Any:
     assert_never(which)
 
 
-_JSON_STRING_ATTRIBUTES = (
-    DOCUMENT_METADATA,
-    LLM_PROMPT_TEMPLATE_VARIABLES,
-    METADATA,
-    TOOL_PARAMETERS,
-)
-
-
-def _load_json_strings(key_values: Iterable[Tuple[str, Any]]) -> Iterator[Tuple[str, Any]]:
-    for key, value in key_values:
-        if key.endswith(_JSON_STRING_ATTRIBUTES):
-            try:
-                dict_value = json.loads(value)
-            except Exception:
-                yield key, value
-            else:
-                if dict_value:
-                    yield key, dict_value
-        else:
-            yield key, value
-
-
 StatusMessage: TypeAlias = str
 
 _STATUS_DECODING = MappingProxyType(
@@ -185,129 +176,15 @@ _STATUS_DECODING = MappingProxyType(
 )
 
 
-def _decode_status(otlp_status: otlp.Status) -> Tuple[SpanStatusCode, StatusMessage]:
+def _decode_status(otlp_status: otlp.Status) -> tuple[SpanStatusCode, StatusMessage]:
     status_code = _STATUS_DECODING.get(otlp_status.code, SpanStatusCode.UNSET)
     return status_code, otlp_status.message
 
 
-_SEMANTIC_CONVENTIONS: List[str] = sorted(
-    (
-        getattr(klass, attr)
-        for name in dir(trace)
-        if name.endswith("Attributes") and inspect.isclass(klass := getattr(trace, name))
-        for attr in dir(klass)
-        if attr.isupper()
-    ),
-    reverse=True,
-)  # sorted so the longer strings go first
-
-
-def _semantic_convention_prefix_partition(key: str, separator: str = ".") -> Tuple[str, str, str]:
-    """Return the longest prefix of `key` that is a semantic convention, and the remaining suffix
-    separated by `.`. For example, if `key` is "retrieval.documents.2.document.score", return
-    ("retrieval.documents", ".", "2.document.score"). The return signature is based on Python's
-    `.partition` method for strings.
-    """
-    for prefix in _SEMANTIC_CONVENTIONS:
-        if key == prefix:
-            return key, "", ""
-        if key.startswith(prefix) and key[len(prefix) :].startswith(separator):
-            return prefix, separator, key[len(prefix) + len(separator) :]
-    return "", "", ""
-
-
-class _Trie(DefaultDict[Union[str, int], "_Trie"]):
-    """Prefix Tree with special handling for indices (i.e. all-digit keys)."""
-
-    def __init__(self) -> None:
-        super().__init__(_Trie)
-        self.value: Any = None
-        self.indices: Set[int] = set()
-        self.branches: Set[Union[str, int]] = set()
-
-    def set_value(self, value: Any) -> None:
-        self.value = value
-        # value and indices must not coexist
-        self.branches.update(self.indices)
-        self.indices.clear()
-
-    def add_index(self, index: int) -> "_Trie":
-        if self.value is not None:
-            self.branches.add(index)
-        elif index not in self.branches:
-            self.indices.add(index)
-        return self[index]
-
-    def add_branch(self, branch: Union[str, int]) -> "_Trie":
-        if branch in self.indices:
-            self.indices.discard(cast(int, branch))
-        self.branches.add(branch)
-        return self[branch]
-
-
-# FIXME: Ideally we should not need something so complicated as a Trie, but it's useful here
-# for backward compatibility reasons regarding some deeply nested objects such as TOOL_PARAMETERS.
-# In the future, we should `json_dumps` them and not let things get too deeply nested.
-def _build_trie(
-    key_value_pairs: Iterable[Tuple[str, Any]],
-    separator: str = ".",
-) -> _Trie:
-    """Build a Trie (a.k.a. prefix tree) from `key_value_pairs`, by partitioning the keys by
-    separator. Each partition is a branch in the Trie. Special handling is done for partitions
-    that are all digits, e.g. "0", "12", etc., which are converted to integers and collected
-    as indices.
-    """
-    trie = _Trie()
-    for key, value in key_value_pairs:
-        if value is None:
-            continue
-        t = trie
-        while True:
-            prefix, _, suffix = _semantic_convention_prefix_partition(key, separator)
-            if prefix:
-                t = t.add_branch(prefix)
-            else:
-                prefix, _, suffix = key.partition(separator)
-                if prefix.isdigit():
-                    index = int(prefix)
-                    t = t.add_index(index) if suffix else t.add_branch(index)
-                else:
-                    t = t.add_branch(prefix)
-            if not suffix:
-                break
-            key = suffix
-        t.set_value(value)
-    return trie
-
-
-def _walk(trie: _Trie, prefix: str = "") -> Iterator[Tuple[str, Any]]:
-    if trie.value is not None:
-        yield prefix, trie.value
-    elif prefix and trie.indices:
-        yield prefix, [dict(_walk(trie[index])) for index in sorted(trie.indices)]
-    elif trie.indices:
-        for index in trie.indices:
-            yield from _walk(trie[index], prefix=f"{index}")
-    elif prefix:
-        yield prefix, dict(_walk(trie))
-        return
-    for branch in trie.branches:
-        new_prefix = f"{prefix}.{branch}" if prefix else f"{branch}"
-        yield from _walk(trie[branch], new_prefix)
-
-
-def _unflatten(
-    key_value_pairs: Iterable[Tuple[str, Any]],
-    separator: str = ".",
-) -> Iterator[Tuple[str, Any]]:
-    trie = _build_trie(key_value_pairs, separator)
-    yield from _walk(trie)
-
-
 _BILLION = 1_000_000_000  # for converting seconds to nanoseconds
 
 
-def encode(span: Span) -> otlp.Span:
+def encode_span_to_otlp(span: Span) -> otlp.Span:
     trace_id: bytes = _encode_identifier(span.context.trace_id)
     span_id: bytes = _encode_identifier(span.context.span_id)
     parent_span_id: bytes = _encode_identifier(span.parent_id)
@@ -316,11 +193,7 @@ def encode(span: Span) -> otlp.Span:
     start_time_unix_nano: int = int(span.start_time.timestamp() * _BILLION)
     end_time_unix_nano: int = int(span.end_time.timestamp() * _BILLION) if span.end_time else 0
 
-    attributes: Dict[str, Any] = span.attributes.copy()
-
-    for mime_type in (INPUT_MIME_TYPE, OUTPUT_MIME_TYPE):
-        if mime_type in attributes:
-            attributes[mime_type] = attributes[mime_type].value
+    attributes: dict[str, Any] = dict(span.attributes)
 
     for key, value in span.attributes.items():
         if value is None:
@@ -328,19 +201,34 @@ def encode(span: Span) -> otlp.Span:
             attributes.pop(key, None)
         elif isinstance(value, Mapping):
             attributes.pop(key, None)
-            if key.endswith(_JSON_STRING_ATTRIBUTES):
-                attributes[key] = json.dumps(value)
+            if key.endswith(JSON_STRING_ATTRIBUTES):
+                attributes[key] = json.dumps(jsonify(value))
             else:
-                attributes.update(_flatten_mapping(value, key))
+                attributes.update(
+                    flatten(
+                        value,
+                        prefix=key,
+                        recurse_on_sequence=True,
+                        json_string_attributes=JSON_STRING_ATTRIBUTES,
+                    )
+                )
         elif (
             not isinstance(value, str)
             and (isinstance(value, Sequence) or isinstance(value, np.ndarray))
-            and _has_mapping(value)
+            and has_mapping(value)
         ):
             attributes.pop(key, None)
-            attributes.update(_flatten_sequence(value, key))
-
-    attributes[OPENINFERENCE_SPAN_KIND] = span.span_kind.value
+            attributes.update(
+                flatten(
+                    value,
+                    prefix=key,
+                    recurse_on_sequence=True,
+                    json_string_attributes=JSON_STRING_ATTRIBUTES,
+                )
+            )
+
+    if OPENINFERENCE_SPAN_KIND not in attributes:
+        attributes[OPENINFERENCE_SPAN_KIND] = span.span_kind.value
 
     status = _encode_status(span.status_code, span.status_message)
     events = map(_encode_event, span.events)
@@ -381,42 +269,6 @@ def _encode_identifier(identifier: Optional[str]) -> bytes:
     return unhexlify(identifier)
 
 
-def _has_mapping(sequence: Sequence[Any]) -> bool:
-    for item in sequence:
-        if isinstance(item, Mapping):
-            return True
-    return False
-
-
-def _flatten_mapping(
-    mapping: Mapping[str, Any],
-    prefix: str,
-) -> Iterator[Tuple[str, Any]]:
-    for key, value in mapping.items():
-        prefixed_key = f"{prefix}.{key}"
-        if isinstance(value, Mapping):
-            if key.endswith(_JSON_STRING_ATTRIBUTES):
-                yield prefixed_key, json.dumps(value)
-            else:
-                yield from _flatten_mapping(value, prefixed_key)
-        elif isinstance(value, Sequence):
-            yield from _flatten_sequence(value, prefixed_key)
-        elif value is not None:
-            yield prefixed_key, value
-
-
-def _flatten_sequence(
-    sequence: Sequence[Any],
-    prefix: str,
-) -> Iterator[Tuple[str, Any]]:
-    if isinstance(sequence, str) or not _has_mapping(sequence):
-        yield prefix, sequence
-    for idx, obj in enumerate(sequence):
-        if not isinstance(obj, Mapping):
-            continue
-        yield from _flatten_mapping(obj, f"{prefix}.{idx}")
-
-
 def _encode_event(event: SpanEvent) -> otlp.Span.Event:
     return otlp.Span.Event(
         name=event.name,
@@ -451,6 +303,6 @@ def _encode_value(value: AttributeValue) -> AnyValue:
 
 
 __all__ = [
-    "encode",
-    "decode",
+    "encode_span_to_otlp",
+    "decode_otlp_span",
 ]

phoenix/trace/projects.py

@@ -1,5 +1,6 @@
 import types
-from typing import Any, Callable, Optional, Type
+from collections.abc import Callable
+from typing import Any, Optional
 
 from openinference.semconv.resource import ResourceAttributes
 from opentelemetry.sdk import trace
@@ -58,7 +59,7 @@ class using_project:
 
     def __exit__(
         self,
-        exc_type: Optional[Type[BaseException]],
+        exc_type: Optional[type[BaseException]],
         exc_value: Optional[BaseException],
         traceback: Optional[types.TracebackType],
     ) -> None:

phoenix/trace/schemas.py

@@ -1,7 +1,7 @@
 from dataclasses import dataclass
 from datetime import datetime
 from enum import Enum
-from typing import Any, Dict, List, Optional, Union
+from typing import Any, Mapping, NamedTuple, Optional
 from uuid import UUID
 
 EXCEPTION_TYPE = "exception.type"
@@ -29,8 +29,6 @@ class SpanKind(Enum):
     """
     SpanKind is loosely inspired by OpenTelemetry's SpanKind
     It captures the type of work that a Span encapsulates.
-
-    NB: this is actively under construction
     """
 
     TOOL = "TOOL"
@@ -40,6 +38,8 @@ class SpanKind(Enum):
     EMBEDDING = "EMBEDDING"
     AGENT = "AGENT"
     RERANKER = "RERANKER"
+    EVALUATOR = "EVALUATOR"
+    GUARDRAIL = "GUARDRAIL"
     UNKNOWN = "UNKNOWN"
 
     def __str__(self) -> str:
@@ -47,16 +47,14 @@ class SpanKind(Enum):
 
     @classmethod
     def _missing_(cls, v: Any) -> Optional["SpanKind"]:
-        if v and isinstance(v, str) and not v.isupper():
+        if v and isinstance(v, str) and v.isascii() and not v.isupper():
             return cls(v.upper())
-        return None if v else cls.UNKNOWN
+        return cls.UNKNOWN
 
 
 TraceID = str
 SpanID = str
-AttributePrimitiveValue = Union[str, bool, float, int]
-AttributeValue = Union[AttributePrimitiveValue, List[AttributePrimitiveValue]]
-SpanAttributes = Dict[str, AttributeValue]
+SpanAttributes = Mapping[str, Any]
 
 
 @dataclass(frozen=True)
@@ -73,7 +71,7 @@ class SpanConversationAttributes:
 
 
 @dataclass(frozen=True)
-class SpanEvent(Dict[str, Any]):
+class SpanEvent:
     """
     A Span Event can be thought of as a structured log message (or annotation)
     on a Span, typically used to denote a meaningful, singular point in time
@@ -142,7 +140,7 @@ class Span:
     "If the parent_id is None, this is the root span"
     parent_id: Optional[SpanID]
     start_time: datetime
-    end_time: Optional[datetime]
+    end_time: datetime
     status_code: SpanStatusCode
     status_message: str
     """
@@ -171,7 +169,7 @@ class Span:
     OpenTelemetry Inspiration:
     https://opentelemetry.io/docs/concepts/signals/traces/#span-events
     """
-    events: List[SpanEvent]
+    events: list[SpanEvent]
 
     """
     An extension of the OpenTelemetry Span interface to include the
@@ -189,6 +187,22 @@ class MimeType(Enum):
         return None if v else cls.TEXT
 
 
+@dataclass(frozen=True)
+class SpanIOValue:
+    value: str
+    mime_type: MimeType = MimeType.TEXT
+
+
+@dataclass(frozen=True)
+class TokenUsage:
+    prompt: int = 0
+    completion: int = 0
+
+    def __post_init__(self) -> None:
+        assert self.prompt >= 0, "prompt must be non-negative"
+        assert self.completion >= 0, "completion must be non-negative"
+
+
 ATTRIBUTE_PREFIX = "attributes."
 CONTEXT_PREFIX = "context."
 COMPUTED_PREFIX = "__computed__."
@@ -202,3 +216,11 @@ class ComputedAttributes(Enum):
     CUMULATIVE_LLM_TOKEN_COUNT_COMPLETION = "cumulative_token_count.completion"
     ERROR_COUNT = "error_count"
     CUMULATIVE_ERROR_COUNT = "cumulative_error_count"
+
+
+class ComputedValues(NamedTuple):
+    latency_ms: float
+    cumulative_error_count: int
+    cumulative_llm_token_count_prompt: int
+    cumulative_llm_token_count_completion: int
+    cumulative_llm_token_count_total: int

phoenix/trace/span_evaluations.py

@@ -1,17 +1,19 @@
 import json
 from abc import ABC
+from collections.abc import Callable, Mapping, Sequence
 from dataclasses import dataclass, field
 from itertools import product
 from pathlib import Path
 from types import MappingProxyType
-from typing import Any, Callable, List, Mapping, Optional, Sequence, Set, Tuple, Type, Union
+from typing import Any, Optional, Union
 from uuid import UUID, uuid4
 
 import pandas as pd
 from pandas.api.types import is_integer_dtype, is_numeric_dtype, is_string_dtype
 from pyarrow import RecordBatchStreamReader, Schema, Table, parquet
 
-from phoenix.config import TRACE_DATASET_DIR
+from phoenix.config import TRACE_DATASETS_DIR
+from phoenix.exceptions import PhoenixEvaluationNameIsMissing
 from phoenix.trace.errors import InvalidParquetMetadataError
 
 EVAL_NAME_COLUMN_PREFIX = "eval."
@@ -19,11 +21,11 @@ EVAL_PARQUET_FILE_NAME = "evaluations-{id}.parquet"
 
 
 class NeedsNamedIndex(ABC):
-    index_names: Mapping[Tuple[str, ...], Callable[[Any], bool]]
-    all_valid_index_name_sorted_combos: Set[Tuple[str, ...]]
+    index_names: Mapping[tuple[str, ...], Callable[[Any], bool]]
+    all_valid_index_name_sorted_combos: set[tuple[str, ...]]
 
     @classmethod
-    def preferred_names(cls) -> List[str]:
+    def preferred_names(cls) -> list[str]:
         return [choices[0] for choices in cls.index_names.keys()]
 
     @classmethod
@@ -42,7 +44,7 @@ class NeedsNamedIndex(ABC):
         )
 
     @classmethod
-    def find_valid_index_names(cls, dtypes: "pd.Series[Any]") -> Optional[List[str]]:
+    def find_valid_index_names(cls, dtypes: "pd.Series[Any]") -> Optional[list[str]]:
         valid_names = []
         for names, check_type in cls.index_names.items():
             for name in names:
@@ -64,14 +66,15 @@ class NeedsResultColumns(ABC):
     )
 
     @classmethod
-    def is_valid_result_columns(cls, dtypes: "pd.Series[Any]") -> bool:
+    def is_valid_result_columns(cls, df: pd.DataFrame) -> bool:
+        dtypes = df.dtypes
         names = cls.result_column_names.keys()
         intersection = dtypes.index.intersection(names)  # type: ignore
         if not len(intersection):
             return False
         for name in intersection:
             check_type = cls.result_column_names[name]
-            if not check_type(dtypes[name]):
+            if not check_type(dtypes[name]) and not df.loc[:, name].isna().all():
                 return False
         return True
 
@@ -91,7 +94,7 @@ class Evaluations(NeedsNamedIndex, NeedsResultColumns, ABC):
             f"dataframe=<rows: {len(self.dataframe)!r}>)"
         )
 
-    def __dir__(self) -> List[str]:
+    def __dir__(self) -> list[str]:
         return ["get_dataframe"]
 
     def get_dataframe(self, prefix_columns_with_name: bool = True) -> pd.DataFrame:
@@ -136,7 +139,7 @@ class Evaluations(NeedsNamedIndex, NeedsResultColumns, ABC):
             )
 
         # Validate that the dataframe contains result columns of appropriate types.
-        if not self.is_valid_result_columns(dataframe.dtypes):
+        if not self.is_valid_result_columns(dataframe):
             raise ValueError(
                 f"The dataframe must contain one of these columns with appropriate "
                 f"value types: {self.result_column_names.keys()} "
@@ -152,7 +155,7 @@ class Evaluations(NeedsNamedIndex, NeedsResultColumns, ABC):
 
     def __init_subclass__(
         cls,
-        index_names: Mapping[Tuple[str, ...], Callable[[Any], bool]],
+        index_names: Mapping[tuple[str, ...], Callable[[Any], bool]],
         **kwargs: Any,
     ) -> None:
         super().__init_subclass__(**kwargs)
@@ -200,7 +203,7 @@ class Evaluations(NeedsNamedIndex, NeedsResultColumns, ABC):
             UUID: The ID of the evaluations, which can be used as a key to load
             the evaluations from disk using `load`.
         """
-        directory = Path(directory) if directory else TRACE_DATASET_DIR
+        directory = Path(directory) if directory else TRACE_DATASETS_DIR
         path = directory / EVAL_PARQUET_FILE_NAME.format(id=self.id)
         table = self.to_pyarrow_table()
         parquet.write_table(table, path)
@@ -228,7 +231,7 @@ class Evaluations(NeedsNamedIndex, NeedsResultColumns, ABC):
         """
         if not isinstance(id, UUID):
             id = UUID(id)
-        path = Path(directory or TRACE_DATASET_DIR) / EVAL_PARQUET_FILE_NAME.format(id=id)
+        path = Path(directory or TRACE_DATASETS_DIR) / EVAL_PARQUET_FILE_NAME.format(id=id)
         schema = parquet.read_schema(path)
         eval_id, eval_name, evaluations_cls = _parse_schema_metadata(schema)
         if id != eval_id:
@@ -326,7 +329,7 @@ class TraceEvaluations(
 ): ...
 
 
-def _parse_schema_metadata(schema: Schema) -> Tuple[UUID, str, Type[Evaluations]]:
+def _parse_schema_metadata(schema: Schema) -> tuple[UUID, str, type[Evaluations]]:
     """
     Validates and parses the pyarrow schema metadata.
     """
@@ -335,8 +338,10 @@ def _parse_schema_metadata(schema: Schema) -> Tuple[UUID, str, Type[Evaluations]
         arize_metadata = json.loads(metadata[b"arize"])
         eval_classes = {subclass.__name__: subclass for subclass in Evaluations.__subclasses__()}
         eval_id = UUID(arize_metadata["eval_id"])
-        if not isinstance((eval_name := arize_metadata["eval_name"]), str):
-            raise ValueError('Arize metadata must contain a string value for key "eval_name"')
+        if not isinstance((eval_name := arize_metadata["eval_name"]), str) or not eval_name.strip():
+            raise PhoenixEvaluationNameIsMissing(
+                'Arize metadata must contain a non-empty string value for key "eval_name"'
+            )
         evaluations_cls = eval_classes[arize_metadata["eval_type"]]
         return eval_id, eval_name, evaluations_cls
     except Exception as err:

phoenix/trace/span_json_decoder.py

@@ -1,6 +1,6 @@
 import json
 from datetime import datetime
-from typing import Any, Dict, Optional
+from typing import Any, Optional
 
 from openinference.semconv.trace import SpanAttributes
 
@@ -22,7 +22,7 @@ INPUT_MIME_TYPE = SpanAttributes.INPUT_MIME_TYPE
 OUTPUT_MIME_TYPE = SpanAttributes.OUTPUT_MIME_TYPE
 
 
-def json_to_attributes(obj: Optional[Dict[str, Any]]) -> Dict[str, Any]:
+def json_to_attributes(obj: Optional[dict[str, Any]]) -> dict[str, Any]:
     if obj is None:
         return {}
     if not isinstance(obj, dict):
@@ -34,7 +34,7 @@ def json_to_attributes(obj: Optional[Dict[str, Any]]) -> Dict[str, Any]:
     return obj
 
 
-def json_to_span(data: Dict[str, Any]) -> Any:
+def json_to_span(data: dict[str, Any]) -> Any:
     """
     A hook for json.loads to convert a dict to a Span object.
     """
@@ -80,7 +80,9 @@ def json_to_span(data: Dict[str, Any]) -> Any:
                 attributes=event.get("attributes") or {},
                 timestamp=datetime.fromisoformat(event["timestamp"]),
             )
-            for event in data["events"]
+            for event in (
+                json.loads(data["events"]) if isinstance(data["events"], str) else data["events"]
+            )
         ]
         data["conversation"] = (
             SpanConversationAttributes(**data["conversation"])