arize-phoenix 3.14.2__py3-none-any.whl → 3.15.1__py3-none-any.whl

phoenix/session/client.py

@@ -34,15 +34,13 @@ class Client(TraceDataExtractor):
         """
         Client for connecting to a Phoenix server.
 
-        Parameters
-        ----------
-        endpoint : str, optional
-            Phoenix server endpoint, e.g. http://localhost:6006. If not provided, the
-            endpoint will be inferred from the environment variables.
-        use_active_session_if_available : bool, optional
-            If px.active_session() is available in the same runtime, e.g. the same Jupyter
-            notebook, delegate the request to the active session instead of making HTTP
-            requests. This argument is set to False if endpoint is provided explicitly.
+        Args:
+            endpoint (str, optional): Phoenix server endpoint, e.g. http://localhost:6006. If not
+                provided, the endpoint will be inferred from the environment variables.
+            use_active_session_if_available (bool, optional): If px.active_session() is available
+                in the same runtime, e.g. the same Jupyter notebook, delegate the request to the
+                active session instead of making HTTP requests. This argument is set to False if
+                endpoint is provided explicitly.
         """
         self._use_active_session_if_available = use_active_session_if_available and not endpoint
         host = get_env_host()
@@ -64,6 +62,21 @@ class Client(TraceDataExtractor):
         root_spans_only: Optional[bool] = None,
         project_name: Optional[str] = None,
     ) -> Optional[Union[pd.DataFrame, List[pd.DataFrame]]]:
+        """
+        Queries spans from the Phoenix server or active session based on specified criteria.
+
+        Args:
+            queries (SpanQuery): One or more SpanQuery objects defining the query criteria.
+            start_time (datetime, optional): The start time for the query range. Default None.
+            stop_time (datetime, optional): The stop time for the query range. Default None.
+            root_spans_only (bool, optional): If True, only root spans are returned. Default None.
+            project_name (str, optional): The project name to query spans for. This can be set
+                using environment variables. If not provided, falls back to the default project.
+
+        Returns:
+            Union[pd.DataFrame, List[pd.DataFrame]]: A pandas DataFrame or a list of pandas
+                DataFrames containing the queried span data, or None if no spans are found.
+        """
         project_name = project_name or get_env_project_name()
         if not queries:
             queries = (SpanQuery(),)
@@ -108,6 +121,18 @@ class Client(TraceDataExtractor):
         self,
         project_name: Optional[str] = None,
     ) -> List[Evaluations]:
+        """
+        Retrieves evaluations for a given project from the Phoenix server or active session.
+
+        Args:
+            project_name (str, optional): The name of the project to retrieve evaluations for.
+                This can be set using environment variables. If not provided, falls back to the
+                default project.
+
+        Returns:
+            List[Evaluations]: A list of Evaluations objects containing evaluation data. Returns an
+                empty list if no evaluations are found.
+        """
         project_name = project_name or get_env_project_name()
         if self._use_active_session_if_available and (session := px.active_session()):
             return session.get_evaluations(project_name=project_name)
@@ -140,16 +165,32 @@ class Client(TraceDataExtractor):
                 f"with `import phoenix as px; px.launch_app()`"
             )
 
-    def log_evaluations(self, *evals: Evaluations) -> None:
+    def log_evaluations(self, *evals: Evaluations, project_name: Optional[str] = None) -> None:
+        """
+        Logs evaluation data to the Phoenix server.
+
+        Args:
+            evals (Evaluations): One or more Evaluations objects containing the data to log.
+            project_name (str, optional): The project name under which to log the evaluations.
+                This can be set using environment variables. If not provided, falls back to the
+                default project.
+
+        Returns:
+            None
+        """
+        project_name = project_name or get_env_project_name()
         for evaluation in evals:
             table = evaluation.to_pyarrow_table()
             sink = pa.BufferOutputStream()
+            headers = {"content-type": "application/x-pandas-arrow"}
+            if project_name:
+                headers["project-name"] = project_name
             with pa.ipc.new_stream(sink, table.schema) as writer:
                 writer.write_table(table)
             self._session.post(
                 urljoin(self._base_url, "/v1/evaluations"),
                 data=cast(bytes, sink.getvalue().to_pybytes()),
-                headers={"content-type": "application/x-pandas-arrow"},
+                headers=headers,
             ).raise_for_status()
 
 

phoenix/session/session.py

@@ -9,6 +9,7 @@ from enum import Enum
 from importlib.util import find_spec
 from pathlib import Path
 from tempfile import TemporaryDirectory
+from threading import Thread
 from typing import (
     TYPE_CHECKING,
     Any,
@@ -47,6 +48,7 @@ from phoenix.trace import Evaluations
 from phoenix.trace.dsl.query import SpanQuery
 from phoenix.trace.trace_dataset import TraceDataset
 from phoenix.utilities import query_spans
+from phoenix.utilities.span_store import get_span_store, load_traces_data_from_store
 
 try:
     from IPython.display import IFrame  # type: ignore
@@ -302,6 +304,12 @@ class ThreadSession(Session):
             port=port,
             notebook_env=notebook_env,
         )
+        if span_store := get_span_store():
+            Thread(
+                target=load_traces_data_from_store,
+                args=(self.traces, span_store),
+                daemon=True,
+            ).start()
         # Initialize an app service that keeps the server running
         self.app = create_app(
             export_path=self.export_path,
@@ -309,6 +317,7 @@ class ThreadSession(Session):
             corpus=self.corpus,
             traces=self.traces,
             umap_params=self.umap_parameters,
+            span_store=span_store,
         )
         self.server = ThreadServer(
             app=self.app,

phoenix/storage/span_store/__init__.py

@@ -0,0 +1,23 @@
+from pathlib import Path
+from typing import Callable, Iterator, Mapping, Protocol
+
+from opentelemetry.proto.trace.v1.trace_pb2 import TracesData
+
+from phoenix.config import SpanStorageType
+from phoenix.storage.span_store.text_file import TextFileSpanStoreImpl
+
+
+class SpanStore(Protocol):
+    def save(self, req: TracesData) -> None: ...
+
+    def load(self) -> Iterator[TracesData]: ...
+
+
+SPAN_STORE_FACTORIES: Mapping[SpanStorageType, Callable[[Path], SpanStore]] = {
+    SpanStorageType.TEXT_FILES: TextFileSpanStoreImpl,
+}
+
+__all__ = (
+    "SpanStore",
+    "SPAN_STORE_FACTORIES",
+)

phoenix/trace/__init__.py

@@ -17,7 +17,14 @@ __all__ = [
 
 @contextlib.contextmanager
 def suppress_tracing() -> Iterator[None]:
-    """Context manager to pause OpenTelemetry instrumentation."""
+    """
+    Context manager to pause OpenTelemetry instrumentation.
+
+    Examples:
+        with suppress_tracing():
+            # No tracing will occur within this block
+            ...
+    """
     try:
         from opentelemetry.context import _SUPPRESS_INSTRUMENTATION_KEY, attach, detach, set_value
     except ImportError:

phoenix/trace/dsl/helpers.py

@@ -3,6 +3,7 @@ from typing import List, Optional, Protocol, Union, cast
 import pandas as pd
 from openinference.semconv.trace import DocumentAttributes, SpanAttributes
 
+from phoenix.config import get_env_project_name
 from phoenix.trace.dsl import SpanQuery
 
 DOCUMENT_CONTENT = DocumentAttributes.DOCUMENT_CONTENT
@@ -21,12 +22,14 @@ IS_RETRIEVER = "span_kind == 'RETRIEVER'"
 
 
 class CanQuerySpans(Protocol):
+    # Implemented by phoenix.session.client.Client
     def query_spans(
-        self, *query: SpanQuery
+        self, *query: SpanQuery, project_name: Optional[str] = None
     ) -> Optional[Union[pd.DataFrame, List[pd.DataFrame]]]: ...
 
 
-def get_retrieved_documents(obj: CanQuerySpans) -> pd.DataFrame:
+def get_retrieved_documents(obj: CanQuerySpans, project_name: Optional[str] = None) -> pd.DataFrame:
+    project_name = project_name or get_env_project_name()
     return cast(
         pd.DataFrame,
         obj.query_spans(
@@ -37,12 +40,14 @@ def get_retrieved_documents(obj: CanQuerySpans) -> pd.DataFrame:
                 RETRIEVAL_DOCUMENTS,
                 reference=DOCUMENT_CONTENT,
                 document_score=DOCUMENT_SCORE,
-            )
+            ),
+            project_name=project_name,
         ),
     )
 
 
-def get_qa_with_reference(obj: CanQuerySpans) -> pd.DataFrame:
+def get_qa_with_reference(obj: CanQuerySpans, project_name: Optional[str] = None) -> pd.DataFrame:
+    project_name = project_name or get_env_project_name()
     return pd.concat(
         cast(
             List[pd.DataFrame],
@@ -55,6 +60,7 @@ def get_qa_with_reference(obj: CanQuerySpans) -> pd.DataFrame:
                     RETRIEVAL_DOCUMENTS,
                     reference=DOCUMENT_CONTENT,
                 ),
+                project_name=project_name,
             ),
         ),
         axis=1,

phoenix/trace/projects.py

@@ -30,9 +30,19 @@ class using_project:
     """
     A context manager that switches the project for all spans created within the context.
 
-    This is useful for managing projects in notebook environments, however this should not be used
-    in production environments or complicated OpenTelemetry setups, as dynamically modifying the
-    span resource can lead to unexpected behavior.
+    This is intended for use in notebook environments where it's useful to be able to change the
+    project associated with spans on the fly.
+
+    Note: This should not be used in production environments or complex OpenTelemetry setups.
+    As dynamically modifying span resources in this way can lead to unexpected behavior.
+
+    Args:
+        project_name (str): The project name to associate with spans created within the context.
+
+    Examples:
+        with using_project('my_project'):
+            # Spans created here will be associated with 'my_project'
+            ...
     """
 
     def __init__(self, project_name: str) -> None:

phoenix/utilities/project.py

@@ -3,7 +3,7 @@ from typing import Iterable
 from openinference.semconv.resource import ResourceAttributes
 from opentelemetry.proto.common.v1.common_pb2 import KeyValue
 
-DEFAULT_PROJECT_NAME = "default"
+from phoenix.config import DEFAULT_PROJECT_NAME
 
 
 def get_project_name(attributes: Iterable[KeyValue]) -> str:

phoenix/utilities/span_store.py

@@ -0,0 +1,23 @@
+from typing import Optional
+
+from phoenix.config import get_env_span_storage_type, get_storage_dir
+from phoenix.core.traces import Traces
+from phoenix.storage.span_store import SPAN_STORE_FACTORIES, SpanStore
+from phoenix.trace.otel import decode
+from phoenix.utilities.project import get_project_name
+
+
+def get_span_store() -> Optional[SpanStore]:
+    if span_store_type := get_env_span_storage_type():
+        span_store_factory = SPAN_STORE_FACTORIES[span_store_type]
+        return span_store_factory(get_storage_dir())
+    return None
+
+
+def load_traces_data_from_store(traces: Traces, span_store: SpanStore) -> None:
+    for traces_data in span_store.load():
+        for resource_spans in traces_data.resource_spans:
+            project_name = get_project_name(resource_spans.resource.attributes)
+            for scope_span in resource_spans.scope_spans:
+                for span in scope_span.spans:
+                    traces.put(decode(span), project_name=project_name)

phoenix/version.py

@@ -1 +1 @@
-__version__ = "3.14.2"
+__version__ = "3.15.1"

phoenix/storage/spanstore/__init__.py

@@ -1,9 +0,0 @@
-from typing import Iterator, Protocol
-
-from opentelemetry.proto.trace.v1.trace_pb2 import TracesData
-
-
-class SpanStore(Protocol):
-    def save(self, req: TracesData) -> None: ...
-
-    def load(self) -> Iterator[TracesData]: ...