arize-phoenix 2.6.0__py3-none-any.whl → 2.8.0__py3-none-any.whl

phoenix/session/session.py

@@ -533,7 +533,8 @@ def _is_databricks() -> bool:
         import IPython  # type: ignore
     except ImportError:
         return False
-    shell = IPython.get_ipython()
+    if (shell := IPython.get_ipython()) is None:
+        return False
     try:
         dbutils = shell.user_ns["dbutils"]
     except KeyError:

phoenix/trace/exporter.py

@@ -5,6 +5,7 @@ from queue import SimpleQueue
 from threading import Thread
 from types import MethodType
 from typing import Any, Optional, Union
+from urllib.parse import urljoin
 
 import opentelemetry.proto.trace.v1.trace_pb2 as otlp
 import requests
@@ -42,22 +43,25 @@ class HttpExporter:
         Parameters
         ----------
         endpoint: Optional[str]
-            The endpoint of the Phoenix server (collector). This should be set if the Phoenix
-            server is running on a remote instance. It can also be set using environment
-            variable `PHOENIX_COLLECTOR_ENDPOINT`, otherwise it defaults to `http://127.0.0.1:6006`
-            Note, this parameter supersedes `host` and `port`.
+            The endpoint of the Phoenix server (collector). This should be set
+            if the Phoenix server is running on a remote instance. It can also
+            be set using environment variable `PHOENIX_COLLECTOR_ENDPOINT`,
+            otherwise it defaults to `http://<host>:<port>`. Note, this
+            parameter supersedes `host` and `port`.
         host: Optional[str]
             The host of the Phoenix server. It can also be set using environment
-            variable `PHOENIX_HOST`, otherwise it defaults to `127.0.0.1`.
+            variable `PHOENIX_HOST`, otherwise it defaults to `0.0.0.0`.
         port: Optional[int]
             The port of the Phoenix server. It can also be set using environment
             variable `PHOENIX_PORT`, otherwise it defaults to `6006`.
         """
         self._host = host or get_env_host()
         self._port = port or get_env_port()
-        endpoint = endpoint or get_env_collector_endpoint() or f"http://{self._host}:{self._port}"
-        # Make sure the url does not end with a slash
-        self._base_url = endpoint.rstrip("/")
+        self._base_url = (
+            endpoint
+            or get_env_collector_endpoint()
+            or f"http://{'127.0.0.1' if self._host == '0.0.0.0' else self._host}:{self._port}"
+        )
         self._warn_if_phoenix_is_not_running()
         self._session = Session()
         weakref.finalize(self, self._session.close)
@@ -104,15 +108,15 @@ class HttpExporter:
 
     def _url(self, message: Message) -> str:
         if isinstance(message, otlp.Span):
-            return f"{self._base_url}/v1/spans"
+            return urljoin(self._base_url, "v1/spans")
         if isinstance(message, pb.Evaluation):
-            return f"{self._base_url}/v1/evaluations"
+            return urljoin(self._base_url, "v1/evaluations")
         logger.exception(f"unrecognized message type: {type(message)}")
         assert_never(message)
 
     def _warn_if_phoenix_is_not_running(self) -> None:
         try:
-            requests.get(f"{self._base_url}/arize_phoenix_version").raise_for_status()
+            requests.get(urljoin(self._base_url, "arize_phoenix_version")).raise_for_status()
         except Exception:
             logger.warning(
                 f"Arize Phoenix is not running on {self._base_url}. Launch Phoenix "

phoenix/trace/fixtures.py

@@ -164,6 +164,11 @@ def _read_eval_fixture(eval_fixture: EvaluationFixture) -> Iterator[pb.Evaluatio
         )
         if isinstance(eval_fixture, DocumentEvaluationFixture):
             span_id, document_position = cast(Tuple[str, int], index)
+            # Legacy fixture files contain UUID strings for span_ids. The hyphens in these
+            # strings need to be removed because we are also removing the hyphens from the
+            # span_ids of their corresponding traces. In general, hyphen is not an allowed
+            # character in the string representation of span_ids.
+            span_id = span_id.replace("-", "")
             subject_id = pb.Evaluation.SubjectId(
                 document_retrieval_id=pb.Evaluation.SubjectId.DocumentRetrievalId(
                     document_position=document_position,
@@ -172,6 +177,11 @@ def _read_eval_fixture(eval_fixture: EvaluationFixture) -> Iterator[pb.Evaluatio
             )
         else:
             span_id = cast(str, index)
+            # Legacy fixture files contain UUID strings for span_ids. The hyphens in these
+            # strings need to be removed because we are also removing the hyphens from the
+            # span_ids of their corresponding traces. In general, hyphen is not an allowed
+            # character in the string representation of span_ids.
+            span_id = span_id.replace("-", "")
             subject_id = pb.Evaluation.SubjectId(span_id=span_id)
         yield pb.Evaluation(
             name=eval_fixture.evaluation_name,

phoenix/trace/llama_index/callback.py

@@ -7,7 +7,7 @@ It enables production LLMapp servers to seamlessly integrate with LLM
 observability solutions such as Arize and Phoenix.
 
 For more information on the specification, see
-https://github.com/Arize-ai/open-inference-spec
+https://github.com/Arize-ai/openinference
 """
 import json
 import logging
@@ -27,7 +27,7 @@ from typing import (
     Union,
     cast,
 )
-from uuid import UUID, uuid4
+from uuid import uuid4
 
 import llama_index
 from llama_index.callbacks.base_handler import BaseCallbackHandler
@@ -241,7 +241,7 @@ class OpenInferenceTraceCallbackHandler(BaseCallbackHandler):
     with LLM observability solutions such as Arize and Phoenix.
 
     For more information on the specification, see
-    https://github.com/Arize-ai/open-inference-spec
+    https://github.com/Arize-ai/openinference
     """
 
     def __init__(
@@ -291,7 +291,7 @@ class OpenInferenceTraceCallbackHandler(BaseCallbackHandler):
         if parent_data := self._event_id_to_event_data.get(parent_id):
             trace_id = parent_data.trace_id
         else:
-            trace_id = uuid4()
+            trace_id = TraceID(uuid4())
         event_data = self._event_id_to_event_data[event_id]
         event_data.name = event_type.value
         event_data.event_type = event_type
@@ -432,7 +432,7 @@ def _add_spans_to_tracer(
             attributes=attributes,
             events=sorted(span_exceptions, key=lambda event: event.timestamp) or None,
             conversation=None,
-            span_id=UUID(event_data.span_id),
+            span_id=SpanID(event_data.span_id),
         )
         new_parent_span_id = span.context.span_id
         for new_child_event_id in trace_map.get(event_id, []):

phoenix/trace/llama_index/streaming.py

@@ -1,11 +1,10 @@
 from datetime import datetime, timezone
 from typing import TYPE_CHECKING, Generator, List
-from uuid import UUID
 
 from llama_index.callbacks.schema import TIMESTAMP_FORMAT
 from llama_index.response.schema import StreamingResponse
 
-from phoenix.trace.schemas import SpanKind, SpanStatusCode
+from phoenix.trace.schemas import SpanID, SpanKind, SpanStatusCode
 from phoenix.trace.semantic_conventions import OUTPUT_VALUE
 from phoenix.trace.tracer import Tracer
 
@@ -60,11 +59,11 @@ class TokenGenInstrumentor:
             end_time=datetime.now(timezone.utc),
             status_code=SpanStatusCode.OK,
             status_message="",
-            parent_id=UUID(parent_id) if parent_id else None,
+            parent_id=SpanID(parent_id) if parent_id else None,
             attributes=self._event_data.attributes,
             events=[],
             conversation=None,
-            span_id=UUID(self._event_data.span_id),
+            span_id=SpanID(self._event_data.span_id),
         )
 
 

phoenix/trace/otel.py

@@ -1,3 +1,5 @@
+import json
+from binascii import hexlify, unhexlify
 from datetime import datetime, timezone
 from types import MappingProxyType
 from typing import (
@@ -16,7 +18,6 @@ from typing import (
     Union,
     cast,
 )
-from uuid import UUID
 
 import opentelemetry.proto.trace.v1.trace_pb2 as otlp
 from opentelemetry.proto.common.v1.common_pb2 import AnyValue, ArrayValue, KeyValue
@@ -36,13 +37,16 @@ from phoenix.trace.schemas import (
     TraceID,
 )
 from phoenix.trace.semantic_conventions import (
+    DOCUMENT_METADATA,
     EXCEPTION_ESCAPED,
     EXCEPTION_MESSAGE,
     EXCEPTION_STACKTRACE,
     EXCEPTION_TYPE,
     INPUT_MIME_TYPE,
+    LLM_PROMPT_TEMPLATE_VARIABLES,
     OPENINFERENCE_SPAN_KIND,
     OUTPUT_MIME_TYPE,
+    TOOL_PARAMETERS,
 )
 
 
@@ -56,7 +60,7 @@ def decode(otlp_span: otlp.Span) -> Span:
         _decode_unix_nano(otlp_span.end_time_unix_nano) if otlp_span.end_time_unix_nano else None
     )
 
-    attributes = dict(_unflatten(_decode_key_values(otlp_span.attributes)))
+    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):
@@ -84,18 +88,12 @@ def decode(otlp_span: otlp.Span) -> Span:
     )
 
 
-def _decode_identifier(identifier: bytes) -> Optional[UUID]:
-    # This is a stopgap solution until we move away from UUIDs.
-    # The goal is to convert bytes to UUID in a deterministic way.
+def _decode_identifier(identifier: bytes) -> Optional[str]:
     if not identifier:
         return None
-    try:
-        # OTEL trace_id is 16 bytes, so it matches UUID's length, but
-        # OTEL span_id is 8 bytes, so we double up by concatenating.
-        return UUID(bytes=identifier[:8] + identifier[-8:])
-    except ValueError:
-        # Fallback to a seeding a UUID from the bytes.
-        return UUID(int=int.from_bytes(identifier, byteorder="big"))
+    # Hex encoding is used for trace and span identifiers in OTLP.
+    # See e.g. https://github.com/open-telemetry/opentelemetry-go/blob/ce3faf1488b72921921f9589048835dddfe97f33/trace/trace.go#L33  # noqa: E501
+    return hexlify(identifier).decode()
 
 
 def _decode_event(otlp_event: otlp.Span.Event) -> SpanEvent:
@@ -149,6 +147,27 @@ def _decode_value(any_value: AnyValue) -> Any:
     assert_never(which)
 
 
+_JSON_STRING_ATTRIBUTES = (
+    DOCUMENT_METADATA,
+    LLM_PROMPT_TEMPLATE_VARIABLES,
+    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(
@@ -277,9 +296,9 @@ _BILLION = 1_000_000_000  # for converting seconds to nanoseconds
 
 
 def encode(span: Span) -> otlp.Span:
-    trace_id: bytes = span.context.trace_id.bytes
-    span_id: bytes = _span_id_to_bytes(span.context.span_id)
-    parent_span_id: bytes = _span_id_to_bytes(span.parent_id) if span.parent_id else bytes()
+    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)
 
     # floating point rounding error can cause the timestamp to be slightly different from expected
     start_time_unix_nano: int = int(span.start_time.timestamp() * _BILLION)
@@ -297,7 +316,10 @@ def encode(span: Span) -> otlp.Span:
             attributes.pop(key, None)
         elif isinstance(value, Mapping):
             attributes.pop(key, None)
-            attributes.update(_flatten_mapping(value, key))
+            if key.endswith(_JSON_STRING_ATTRIBUTES):
+                attributes[key] = json.dumps(value)
+            else:
+                attributes.update(_flatten_mapping(value, key))
         elif not isinstance(value, str) and isinstance(value, Sequence) and _has_mapping(value):
             attributes.pop(key, None)
             attributes.update(_flatten_sequence(value, key))
@@ -334,10 +356,13 @@ def _encode_status(span_status_code: SpanStatusCode, status_message: str) -> otl
     return otlp.Status(code=code, message=status_message)
 
 
-def _span_id_to_bytes(span_id: SpanID) -> bytes:
-    # Note that this is not compliant with the OTEL spec, which uses 8-byte span IDs.
-    # This is a stopgap solution for backward compatibility until we move away from UUIDs.
-    return span_id.bytes
+def _encode_identifier(identifier: Optional[str]) -> bytes:
+    if not identifier:
+        return bytes()
+    # For legacy JSONL files containing UUID strings we
+    # need to remove the hyphen.
+    identifier = identifier.replace("-", "")
+    return unhexlify(identifier)
 
 
 def _has_mapping(sequence: Sequence[Any]) -> bool:
@@ -354,7 +379,10 @@ def _flatten_mapping(
     for key, value in mapping.items():
         prefixed_key = f"{prefix}.{key}"
         if isinstance(value, Mapping):
-            yield from _flatten_mapping(value, prefixed_key)
+            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:

phoenix/trace/schemas.py

@@ -54,8 +54,8 @@ class SpanKind(Enum):
         return None if v else cls.UNKNOWN
 
 
-TraceID = UUID
-SpanID = UUID
+TraceID = str
+SpanID = str
 AttributePrimitiveValue = Union[str, bool, float, int]
 AttributeValue = Union[AttributePrimitiveValue, List[AttributePrimitiveValue]]
 SpanAttributes = Dict[str, AttributeValue]

phoenix/trace/span_json_decoder.py

@@ -1,7 +1,6 @@
 import json
 from datetime import datetime
 from typing import Any, Dict, Optional
-from uuid import UUID
 
 from phoenix.trace.schemas import (
     MimeType,
@@ -10,8 +9,10 @@ from phoenix.trace.schemas import (
     SpanConversationAttributes,
     SpanEvent,
     SpanException,
+    SpanID,
     SpanKind,
     SpanStatusCode,
+    TraceID,
 )
 from phoenix.trace.semantic_conventions import (
     EXCEPTION_MESSAGE,
@@ -54,11 +55,11 @@ def json_to_span(data: Dict[str, Any]) -> Any:
         if not isinstance(context, dict):
             raise ValueError(f"context should be dict, but context={context}")
         data["context"] = SpanContext(
-            trace_id=UUID(context["trace_id"]),
-            span_id=UUID(context["span_id"]),
+            trace_id=TraceID(context["trace_id"]),
+            span_id=SpanID(context["span_id"]),
         )
         parent_id = data.get("parent_id")
-        data["parent_id"] = UUID(parent_id) if parent_id else None
+        data["parent_id"] = parent_id
         attributes = data.get("attributes")
         data["attributes"] = json_to_attributes(attributes)
         data["start_time"] = datetime.fromisoformat(data["start_time"])

phoenix/trace/tracer.py

@@ -2,7 +2,7 @@ import logging
 from datetime import datetime
 from threading import RLock
 from typing import Any, Callable, Iterator, List, Optional, Protocol
-from uuid import UUID, uuid4
+from uuid import uuid4
 
 from .schemas import (
     Span,
@@ -13,6 +13,7 @@ from .schemas import (
     SpanID,
     SpanKind,
     SpanStatusCode,
+    TraceID,
 )
 
 logger = logging.getLogger(__name__)
@@ -68,18 +69,18 @@ class Tracer:
         status_code: SpanStatusCode = SpanStatusCode.UNSET,
         status_message: Optional[str] = "",
         parent_id: Optional[SpanID] = None,
-        trace_id: Optional[UUID] = None,
+        trace_id: Optional[TraceID] = None,
         attributes: Optional[SpanAttributes] = None,
         events: Optional[List[SpanEvent]] = None,
         conversation: Optional[SpanConversationAttributes] = None,
-        span_id: Optional[UUID] = None,
+        span_id: Optional[SpanID] = None,
     ) -> Span:
         """
         create_span creates a new span with the given name and options.
         """
         # If no trace_id is provided, generate a new one
         if trace_id is None:
-            trace_id = uuid4()
+            trace_id = TraceID(uuid4())
 
         # If no attributes are provided, create an empty dict
         if attributes is None:
@@ -91,7 +92,7 @@ class Tracer:
 
         span = Span(
             name=name,
-            context=SpanContext(trace_id=trace_id, span_id=span_id or uuid4()),
+            context=SpanContext(trace_id=trace_id, span_id=span_id or SpanID(uuid4())),
             span_kind=span_kind,
             parent_id=parent_id,
             start_time=start_time,

phoenix/version.py

@@ -1 +1 @@
-__version__ = "2.6.0"
+__version__ = "2.8.0"