arize-phoenix 10.0.4__py3-none-any.whl → 12.28.1__py3-none-any.whl

phoenix/settings.py

@@ -1,5 +1,6 @@
 import logging
 from dataclasses import dataclass, field
+from typing import Optional
 
 from phoenix.config import LoggingMode
 
@@ -18,6 +19,10 @@ class _Settings:
     db_logging_level: int = field(default=logging.WARNING)
     # By default, migrations are enabled
     disable_migrations: bool = field(default=False)
+    # FullStory organization ID for web analytics tracking
+    fullstory_org: Optional[str] = field(default=None)
+    # Scarf.sh pixel ID for open-source analytics and usage
+    scarf_sh_pixel_id: Optional[str] = field(default=None)
 
 
 # Singleton instance of the settings

phoenix/trace/attributes.py

@@ -1,18 +1,63 @@
 """
+OpenTelemetry Span Attribute Flattening/Unflattening for Phoenix
+
+This module handles the conversion between flattened dot-separated key-value pairs
+(as received from OpenTelemetry protobuf) and nested dictionary structures (as used
+internally by Phoenix).
+
+Basic Behavior
+--------------
 Span attribute keys have a special relationship with the `.` separator. When
 a span attribute is ingested from protobuf, it's in the form of a key value
-pair such as `("llm.token_count.completion", 123)`. What we need to do is to split
-the key by the `.` separator and turn it into part of a nested dictionary such
-as {"llm": {"token_count": {"completion": 123}}}. We also need to reverse this
-process, which is to flatten the nested dictionary into a list of key value
-pairs. This module provides functions to do both of these operations.
-
-Note that digit keys are treated as indices of a nested array. For example,
-the digits inside `("retrieval.documents.0.document.content", 'A')` and
-`("retrieval.documents.1.document.content": 'B')` turn the sub-keys following
-them into a nested list of dictionaries i.e.
-{`retrieval: {"documents": [{"document": {"content": "A"}}, {"document":
-{"content": "B"}}]}`.
+pair such as `("llm.token_count.completion", 123)`. We split the key by the `.`
+separator and turn it into a nested dictionary:
+    {"llm": {"token_count": {"completion": 123}}}
+
+Array Creation Rule
+-------------------
+Numeric keys are treated specially to support array-like structures in OpenTelemetry
+semantic conventions. A numeric key becomes an array index ONLY when:
+1. The numeric key has additional segments after it (e.g., "documents.0.content")
+2. Those segments lead to mappings (dictionaries), not scalar values
+
+Examples:
+    ("documents.0.content", "A"), ("documents.1.content", "B")
+    → {"documents": [{"content": "A"}, {"content": "B"}]}  # Array created
+
+    ("tags.0", "python"), ("tags.1", "ai")
+    → {"tags": {"0": "python", "1": "ai"}}  # Dict with string keys, NOT array
+
+Rationale: In OpenTelemetry semantic conventions, arrays typically contain structured
+objects (like documents or events), not primitive values. This rule ensures that only
+semantically meaningful arrays are created, avoiding ambiguity with numeric string keys.
+
+Terminal Value Node Behavior
+----------------------------
+When a path receives an explicit value (typically from pre-nested input), that node
+becomes "terminal" and cannot have children added via flattened keys. Instead,
+attempted extensions become separate dotted keys:
+
+    ("a", {"b": 1}), ("a.c", 2)
+    → {"a": {"b": 1}, "a.c": 2}  # "a.c" becomes dotted key, not nested
+
+This preserves all data during OpenTelemetry ingestion where:
+- Pre-nested values (dicts/arrays) come from the OTEL data model
+- Flattened keys come from custom instrumentation
+- Both must be preserved to avoid data loss
+
+Edge Cases
+----------
+- None values: Skipped entirely during processing
+- Leading zeros: Normalized ("00" → "0", treated as same key)
+- Negative numbers: Treated as string keys, not array indices
+- Empty key segments: Ignored ("a..b" → "a.b")
+- Alphanumeric keys: "0a", "1x" are string keys, not array indices
+- Whitespace: Stripped from key segments (" key " → "key")
+- Empty string key: Valid key, preserved as-is
+- Duplicate keys: Last write wins
+
+These edge cases are handled consistently to ensure reliable round-tripping
+between flattened and nested representations.
 """
 
 import inspect
@@ -107,6 +152,13 @@ def has_mapping(sequence: Iterable[Any]) -> bool:
     only contain primitive types, such as strings, integers, etc. Conversely,
     we'll only un-flatten digit sub-keys if it can be interpreted the index of
     an array of dictionaries.
+
+    This is the key function that implements the "arrays only for mappings" rule.
+    In OpenTelemetry semantic conventions, arrays typically contain structured
+    objects (e.g., retrieval.documents[0], llm.messages[1]) not primitive arrays
+    like ["tag1", "tag2"]. This check ensures semantic correctness during round-
+    trip conversions: primitive arrays stay as-is, only structured arrays are
+    flattened/unflattened with numeric indices.
     """
     for item in sequence:
         if isinstance(item, Mapping):
@@ -189,7 +241,9 @@ class _Trie(defaultdict[Union[str, int], "_Trie"]):
 
     def set_value(self, value: Any) -> None:
         self.value = value
-        # value and indices must not coexist
+        # value and indices must not coexist - convert indices to branches
+        # This handles the case where a numeric key ends a path (scalar value)
+        # vs. continues a path (array index). Example: "a.0" vs "a.0.b"
         self.branches.update(self.indices)
         self.indices.clear()
 
@@ -230,8 +284,14 @@ def _build_trie(
                 separator,
                 prefix_exclusions,
             )
+            # Strip whitespace from key segments for cleaner attribute keys
+            prefix = prefix.strip()
             if prefix.isdigit():
                 index = int(prefix)
+                # Key decision: numeric key with suffix → array index (add_index)
+                #               numeric key without suffix → dict key (add_branch)
+                # This ensures arrays only contain mappings, not scalar values,
+                # matching OpenTelemetry semantic conventions.
                 t = t.add_index(index) if suffix else t.add_branch(index)
             else:
                 t = t.add_branch(prefix)
@@ -253,8 +313,15 @@ def _walk(
     yield the prefix and the value. If the Trie node has indices, then yield the
     prefix and a list of dictionaries. If the Trie node has branches, then yield
     the prefix and a dictionary.
+
+    Conflict Resolution: When a node has both a value and child nodes, both are
+    yielded. The value is yielded with its current prefix, and children create
+    additional dotted keys. This preserves all data from mixed flattened/nested
+    input, avoiding data loss during OpenTelemetry span ingestion.
     """
     if trie.value is not None:
+        # Yield the value first - if there are also branches, those will become
+        # separate dotted keys (e.g., "a" and "a.b" coexist)
         yield prefix, trie.value
     elif prefix and trie.indices:
         yield (

phoenix/trace/dsl/helpers.py

@@ -1,6 +1,7 @@
+import json
 import warnings
 from datetime import datetime
-from typing import Optional, Protocol, Union, cast
+from typing import Any, Iterable, Mapping, Optional, Protocol, Union, cast
 
 import pandas as pd
 from openinference.semconv.trace import DocumentAttributes, SpanAttributes
@@ -13,11 +14,16 @@ DOCUMENT_SCORE = DocumentAttributes.DOCUMENT_SCORE
 INPUT_VALUE = SpanAttributes.INPUT_VALUE
 OUTPUT_VALUE = SpanAttributes.OUTPUT_VALUE
 RETRIEVAL_DOCUMENTS = SpanAttributes.RETRIEVAL_DOCUMENTS
+LLM_FUNCTION_CALL = SpanAttributes.LLM_FUNCTION_CALL
+LLM_INPUT_MESSAGES = SpanAttributes.LLM_INPUT_MESSAGES
+LLM_OUTPUT_MESSAGES = SpanAttributes.LLM_OUTPUT_MESSAGES
+
 
 INPUT = {"input": INPUT_VALUE}
 OUTPUT = {"output": OUTPUT_VALUE}
 IO = {**INPUT, **OUTPUT}
 
+
 IS_ROOT = "parent_id is None"
 IS_LLM = "span_kind == 'LLM'"
 IS_RETRIEVER = "span_kind == 'RETRIEVER'"
@@ -125,3 +131,86 @@ def get_qa_with_reference(
     df_ref = pd.DataFrame({"reference": ref})
     df_qa_ref = pd.concat([df_qa, df_ref], axis=1, join="inner").set_index("context.span_id")
     return df_qa_ref
+
+
+def get_called_tools(
+    obj: CanQuerySpans,
+    *,
+    start_time: Optional[datetime] = None,
+    end_time: Optional[datetime] = None,
+    project_name: Optional[str] = None,
+    timeout: Optional[int] = DEFAULT_TIMEOUT_IN_SECONDS,
+    function_name_only: bool = False,
+) -> Optional[pd.DataFrame]:
+    """Retrieve tool calls made by LLM spans within a specified time range.
+
+    This function queries LLM spans and extracts tool calls from their output messages.
+    It can return either just the function names or full function calls with arguments.
+
+    Args:
+        obj: An object that implements the CanQuerySpans protocol for querying spans.
+        start_time: Optional start time to filter spans. If None, no start time filter is applied.
+        end_time: Optional end time to filter spans. If None, no end time filter is applied.
+        project_name: Optional project name to filter spans. If None, uses the environment project name.
+        timeout: Optional timeout in seconds for the query. Defaults to DEFAULT_TIMEOUT_IN_SECONDS.
+        function_name_only: If True, returns only function names. If False, returns full function calls
+            with arguments. Defaults to False.
+
+    Returns:
+        A pandas DataFrame containing the tool calls, or None if no spans are found.
+        The DataFrame includes columns for input messages, output messages, and tool calls.
+    """  # noqa: E501
+    project_name = project_name or get_env_project_name()
+
+    def extract_tool_calls(outputs: list[dict[str, Any]]) -> Optional[list[str]]:
+        if not isinstance(outputs, list) or not outputs:
+            return None
+        ans = []
+        if isinstance(message := outputs[0].get("message"), Mapping) and isinstance(
+            tool_calls := message.get("tool_calls"), Iterable
+        ):
+            for tool_call in tool_calls:
+                if not isinstance(tool_call, Mapping):
+                    continue
+                if not isinstance(tc := tool_call.get("tool_call"), Mapping):
+                    continue
+                if not isinstance(function := tc.get("function"), Mapping):
+                    continue
+                if not isinstance(name := function.get("name"), str):
+                    continue
+                if function_name_only:
+                    ans.append(name)
+                    continue
+                kwargs = {}
+                if isinstance(arguments := function.get("arguments"), str):
+                    try:
+                        kwargs = json.loads(arguments)
+                    except Exception:
+                        pass
+                kwargs_str = "" if not kwargs else ", ".join(f"{k}={v}" for k, v in kwargs.items())
+                ans.append(f"{name}({kwargs_str})")
+        return ans or None
+
+    df_qa = cast(
+        pd.DataFrame,
+        obj.query_spans(
+            SpanQuery()
+            .where(IS_LLM)
+            .select(
+                input=LLM_INPUT_MESSAGES,
+                output=LLM_OUTPUT_MESSAGES,
+            ),
+            start_time=start_time,
+            end_time=end_time,
+            project_name=project_name,
+            timeout=timeout,
+        ),
+    )
+
+    if df_qa is None:
+        print("No spans found.")
+        return None
+
+    df_qa["tool_call"] = df_qa["output"].apply(extract_tool_calls)
+
+    return df_qa

phoenix/trace/dsl/query.py

@@ -456,16 +456,16 @@ class SpanQuery(_HasTmpSuffix):
         return replace(self, _filter=_filter)
 
     def explode(self, key: str, **kwargs: str) -> "SpanQuery":
-        assert (
-            isinstance(key, str) and key
-        ), "The field name for explosion must be a non-empty string."
+        assert isinstance(key, str) and key, (
+            "The field name for explosion must be a non-empty string."
+        )
         _explode = Explosion(key=key, kwargs=kwargs, primary_index_key=self._index.key)
         return replace(self, _explode=_explode)
 
     def concat(self, key: str, **kwargs: str) -> "SpanQuery":
-        assert (
-            isinstance(key, str) and key
-        ), "The field name for concatenation must be a non-empty string."
+        assert isinstance(key, str) and key, (
+            "The field name for concatenation must be a non-empty string."
+        )
         _concat = (
             Concatenation(key=key, kwargs=kwargs, separator=self._concat.separator)
             if self._concat
@@ -807,6 +807,8 @@ def _get_spans_dataframe(
         stmt = stmt.where(start_time <= models.Span.start_time)
     if end_time:
         stmt = stmt.where(models.Span.start_time < end_time)
+    # Default newest-first ordering by start_time, with id as a stable tiebreaker
+    stmt = stmt.order_by(models.Span.start_time.desc(), models.Span.id.desc())
     if root_spans_only:
         # A root span is either a span with no parent_id or an orphan span
         # (a span whose parent_id references a span that doesn't exist in the database)

phoenix/trace/projects.py

@@ -5,6 +5,7 @@ from typing import Any, Optional
 from openinference.semconv.resource import ResourceAttributes
 from opentelemetry.sdk import trace
 from opentelemetry.sdk.resources import Resource
+from typing_extensions import deprecated
 from wrapt import wrap_function_wrapper
 
 
@@ -27,6 +28,10 @@ def project_override_wrapper(project_name: str) -> Callable[..., None]:
     return wrapper
 
 
+@deprecated(
+    "This decorator has been moved to openinference-instrumentation via dangerously_using_project"
+    " in version 0.1.38 and will be removed in an upcoming major release"
+)
 class using_project:
     """
     A context manager that switches the project for all spans created within the context.

phoenix/utilities/template_formatters.py

@@ -85,7 +85,7 @@ class MustacheTemplateFormatter(TemplateFormatter):
         for variable_name in variable_names:
             template = re.sub(
                 pattern=rf"(?<!\\){{{{\s*{variable_name}\s*}}}}",
-                repl=variables[variable_name],
+                repl=str(variables[variable_name]),
                 string=template,
             )
         return template

phoenix/version.py

@@ -1 +1 @@
-__version__ = "10.0.4"
+__version__ = "12.28.1"