arize-phoenix 3.25.0__py3-none-any.whl → 4.0.1__py3-none-any.whl

phoenix/session/session.py

@@ -1,15 +1,16 @@
 import json
 import logging
 import os
+import shutil
 import warnings
 from abc import ABC, abstractmethod
 from collections import UserList
 from datetime import datetime
 from enum import Enum
 from importlib.util import find_spec
+from itertools import chain
 from pathlib import Path
 from tempfile import TemporaryDirectory
-from threading import Thread
 from typing import (
     TYPE_CHECKING,
     Any,
@@ -29,26 +30,25 @@ from phoenix.config import (
     ENV_PHOENIX_COLLECTOR_ENDPOINT,
     ENV_PHOENIX_HOST,
     ENV_PHOENIX_PORT,
+    ensure_working_dir,
+    get_env_database_connection_str,
     get_env_host,
     get_env_port,
-    get_env_project_name,
     get_exported_files,
+    get_working_dir,
 )
 from phoenix.core.model_schema_adapter import create_model_from_datasets
-from phoenix.core.traces import Traces
 from phoenix.inferences.inferences import EMPTY_INFERENCES, Inferences
 from phoenix.pointcloud.umap_parameters import get_umap_parameters
 from phoenix.server.app import create_app
 from phoenix.server.thread_server import ThreadServer
 from phoenix.services import AppService
 from phoenix.session.client import Client
-from phoenix.session.data_extractor import TraceDataExtractor
+from phoenix.session.data_extractor import DEFAULT_SPAN_LIMIT, TraceDataExtractor
 from phoenix.session.evaluation import encode_evaluations
 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
@@ -64,6 +64,10 @@ if TYPE_CHECKING:
 else:
     _BaseList = UserList
 
+# Temporary directory for the duration of the session
+global _session_working_dir
+_session_working_dir: Optional["TemporaryDirectory[str]"] = None
+
 
 class NotebookEnvironment(Enum):
     COLAB = "colab"
@@ -95,7 +99,6 @@ class Session(TraceDataExtractor, ABC):
     """Session that maintains a 1-1 shared state with the Phoenix App."""
 
     trace_dataset: Optional[TraceDataset]
-    traces: Optional[Traces]
     notebook_env: NotebookEnvironment
     """The notebook environment that the session is running in."""
 
@@ -104,6 +107,7 @@ class Session(TraceDataExtractor, ABC):
 
     def __init__(
         self,
+        database_url: str,
         primary_dataset: Inferences,
         reference_dataset: Optional[Inferences] = None,
         corpus_dataset: Optional[Inferences] = None,
@@ -113,32 +117,12 @@ class Session(TraceDataExtractor, ABC):
         port: Optional[int] = None,
         notebook_env: Optional[NotebookEnvironment] = None,
     ):
+        self._database_url = database_url
         self.primary_dataset = primary_dataset
         self.reference_dataset = reference_dataset
         self.corpus_dataset = corpus_dataset
         self.trace_dataset = trace_dataset
         self.umap_parameters = get_umap_parameters(default_umap_parameters)
-        self.model = create_model_from_datasets(
-            primary_dataset,
-            reference_dataset,
-        )
-
-        self.corpus = (
-            create_model_from_datasets(
-                corpus_dataset,
-            )
-            if corpus_dataset is not None
-            else None
-        )
-
-        self.traces = Traces()
-        if trace_dataset:
-            for span in trace_dataset.to_spans():
-                self.traces.put(span)
-            for evaluations in trace_dataset.evaluations:
-                for pb_evaluation in encode_evaluations(evaluations):
-                    self.traces.put(pb_evaluation)
-
         self.host = host or get_env_host()
         self.port = port or get_env_port()
         self.temp_dir = TemporaryDirectory()
@@ -147,6 +131,87 @@ class Session(TraceDataExtractor, ABC):
         self.exported_data = ExportedData()
         self.notebook_env = notebook_env or _get_notebook_environment()
         self.root_path = _get_root_path(self.notebook_env, self.port)
+        host = "127.0.0.1" if self.host == "0.0.0.0" else self.host
+        self._client = Client(
+            endpoint=f"http://{host}:{self.port}", warn_if_server_not_running=False
+        )
+
+    def query_spans(
+        self,
+        *queries: SpanQuery,
+        start_time: Optional[datetime] = None,
+        end_time: Optional[datetime] = None,
+        limit: Optional[int] = DEFAULT_SPAN_LIMIT,
+        root_spans_only: Optional[bool] = None,
+        project_name: Optional[str] = None,
+        # Deprecated fields
+        stop_time: Optional[datetime] = None,
+    ) -> Optional[Union[pd.DataFrame, List[pd.DataFrame]]]:
+        """
+        Queries the spans in the project based on the provided parameters.
+
+        Parameters
+        ----------
+            queries : *SpanQuery
+                Variable-length argument list of SpanQuery objects representing
+                the queries to be executed.
+
+            start_time : datetime, optional
+                 datetime representing the start time of the query.
+
+            end_time : datetime, optional
+                datetime representing the end time of the query.
+
+            root_spans_only : boolean, optional
+                whether to include only root spans in the results.
+
+            project_name : string, optional
+                name of the project to query. Defaults to the project name set
+                in the environment variable `PHOENIX_PROJECT_NAME` or 'default' if not set.
+
+        Returns:
+            results : DataFrame
+                DataFrame or list of DataFrames containing the query results.
+        """
+        if stop_time is not None:
+            warnings.warn(
+                "The `stop_time` parameter is deprecated and will be removed in a future release. "
+                "Please use `end_time` instead.",
+                DeprecationWarning,
+            )
+            end_time = stop_time
+        return self._client.query_spans(
+            *queries,
+            start_time=start_time,
+            end_time=end_time,
+            limit=limit,
+            root_spans_only=root_spans_only,
+            project_name=project_name,
+        )
+
+    def get_evaluations(
+        self,
+        project_name: Optional[str] = None,
+    ) -> List[Evaluations]:
+        """
+        Get the evaluations for a project.
+
+        Parameters
+        ----------
+            project_name :  str, optional
+                The name of the project. If not provided, the project name set
+                in the environment variable `PHOENIX_PROJECT_NAME` will be used.
+                Otherwise, 'default' will be used.
+
+        Returns
+        -------
+            evaluations : List[Evaluations]
+                A list of evaluations for the specified project.
+
+        """
+        return self._client.get_evaluations(
+            project_name=project_name,
+        )
 
     @abstractmethod
     def end(self) -> None:
@@ -187,6 +252,10 @@ class Session(TraceDataExtractor, ABC):
         """Returns the url for the phoenix app"""
         return _get_url(self.host, self.port, self.notebook_env)
 
+    @property
+    def database_url(self) -> str:
+        return self._database_url
+
 
 _session: Optional[Session] = None
 
@@ -194,6 +263,7 @@ _session: Optional[Session] = None
 class ProcessSession(Session):
     def __init__(
         self,
+        database_url: str,
         primary_dataset: Inferences,
         reference_dataset: Optional[Inferences] = None,
         corpus_dataset: Optional[Inferences] = None,
@@ -205,6 +275,7 @@ class ProcessSession(Session):
         notebook_env: Optional[NotebookEnvironment] = None,
     ) -> None:
         super().__init__(
+            database_url=database_url,
             primary_dataset=primary_dataset,
             reference_dataset=reference_dataset,
             corpus_dataset=corpus_dataset,
@@ -228,12 +299,13 @@ class ProcessSession(Session):
         )
         # Initialize an app service that keeps the server running
         self.app_service = AppService(
-            self.export_path,
-            self.host,
-            self.port,
-            self.root_path,
-            self.primary_dataset.name,
-            umap_params_str,
+            database_url=database_url,
+            export_path=self.export_path,
+            host=self.host,
+            port=self.port,
+            root_path=self.root_path,
+            primary_dataset_name=self.primary_dataset.name,
+            umap_params=umap_params_str,
             reference_dataset_name=(
                 self.reference_dataset.name if self.reference_dataset is not None else None
             ),
@@ -244,11 +316,6 @@ class ProcessSession(Session):
                 self.trace_dataset.name if self.trace_dataset is not None else None
             ),
         )
-        host = "127.0.0.1" if self.host == "0.0.0.0" else self.host
-        self._client = Client(
-            endpoint=f"http://{host}:{self.port}",
-            use_active_session_if_available=False,
-        )
 
     @property
     def active(self) -> bool:
@@ -258,32 +325,11 @@ class ProcessSession(Session):
         self.app_service.stop()
         self.temp_dir.cleanup()
 
-    def query_spans(
-        self,
-        *queries: SpanQuery,
-        start_time: Optional[datetime] = None,
-        stop_time: Optional[datetime] = None,
-        root_spans_only: Optional[bool] = None,
-        project_name: Optional[str] = None,
-    ) -> Optional[Union[pd.DataFrame, List[pd.DataFrame]]]:
-        return self._client.query_spans(
-            *queries,
-            start_time=start_time,
-            stop_time=stop_time,
-            root_spans_only=root_spans_only,
-            project_name=project_name,
-        )
-
-    def get_evaluations(
-        self,
-        project_name: Optional[str] = None,
-    ) -> List[Evaluations]:
-        return self._client.get_evaluations()
-
 
 class ThreadSession(Session):
     def __init__(
         self,
+        database_url: str,
         primary_dataset: Inferences,
         reference_dataset: Optional[Inferences] = None,
         corpus_dataset: Optional[Inferences] = None,
@@ -295,6 +341,7 @@ class ThreadSession(Session):
         notebook_env: Optional[NotebookEnvironment] = None,
     ):
         super().__init__(
+            database_url=database_url,
             primary_dataset=primary_dataset,
             reference_dataset=reference_dataset,
             corpus_dataset=corpus_dataset,
@@ -304,20 +351,30 @@ 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()
+        self.model = create_model_from_datasets(
+            primary_dataset,
+            reference_dataset,
+        )
+        self.corpus = (
+            create_model_from_datasets(
+                corpus_dataset,
+            )
+            if corpus_dataset is not None
+            else None
+        )
         # Initialize an app service that keeps the server running
         self.app = create_app(
+            database_url=database_url,
             export_path=self.export_path,
             model=self.model,
             corpus=self.corpus,
-            traces=self.traces,
             umap_params=self.umap_parameters,
-            span_store=span_store,
+            initial_spans=trace_dataset.to_spans() if trace_dataset else None,
+            initial_evaluations=(
+                chain.from_iterable(map(encode_evaluations, initial_evaluations))
+                if (trace_dataset and (initial_evaluations := trace_dataset.evaluations))
+                else None
+            ),
         )
         self.server = ThreadServer(
             app=self.app,
@@ -336,91 +393,29 @@ class ThreadSession(Session):
         self.server.close()
         self.temp_dir.cleanup()
 
-    def query_spans(
-        self,
-        *queries: SpanQuery,
-        start_time: Optional[datetime] = None,
-        stop_time: Optional[datetime] = None,
-        root_spans_only: Optional[bool] = None,
-        project_name: Optional[str] = None,
-    ) -> Optional[Union[pd.DataFrame, List[pd.DataFrame]]]:
-        """
-        Queries the spans in the project based on the provided parameters.
-
-        Parameters
-        ----------
-            queries : *SpanQuery
-                Variable-length argument list of SpanQuery objects representing
-                the queries to be executed.
-
-            start_time : datetime, optional
-                 datetime representing the start time of the query.
 
-            stop_time : datetime, optional
-                datetime representing the stop time of the query.
-
-            root_spans_only : boolean, optional
-                whether to include only root spans in the results.
-
-            project_name : string, optional
-                name of the project to query. Defaults to the project name set
-                in the environment variable `PHOENIX_PROJECT_NAME` or 'default' if not set.
-
-        Returns:
-            results : DataFrame
-                DataFrame or list of DataFrames containing the query results.
-        """
-        if not (traces := self.traces) or not (
-            project := traces.get_project(project_name or get_env_project_name())
-        ):
-            return None
-        if not queries:
-            queries = (SpanQuery(),)
-        valid_eval_names = project.get_span_evaluation_names() if project else ()
-        queries = tuple(
-            SpanQuery.from_dict(
-                query.to_dict(),
-                evals=project,
-                valid_eval_names=valid_eval_names,
+def delete_all(prompt_before_delete: Optional[bool] = True) -> None:
+    """
+    Deletes the entire contents of the working directory. This will delete, traces, evaluations,
+    and any other data stored in the working directory.
+    """
+    global _session_working_dir
+    working_dir = get_working_dir()
+    directories_to_delete = []
+    if working_dir.exists():
+        directories_to_delete.append(working_dir)
+    if _session_working_dir is not None:
+        directories_to_delete.append(Path(_session_working_dir.name))
+
+    # Loop through directories to delete
+    for directory in directories_to_delete:
+        if prompt_before_delete:
+            input(
+                f"You have data at {directory}. Are you sure you want to delete?"
+                + " This cannot be undone. Press Enter to delete, Escape to cancel."
             )
-            for query in queries
-        )
-        results = query_spans(
-            project,
-            *queries,
-            start_time=start_time,
-            stop_time=stop_time,
-            root_spans_only=root_spans_only,
-        )
-        if len(results) == 1:
-            df = results[0]
-            return None if df.shape == (0, 0) else df
-        return results
-
-    def get_evaluations(
-        self,
-        project_name: Optional[str] = None,
-    ) -> List[Evaluations]:
-        """
-        Get the evaluations for a project.
-
-        Parameters
-        ----------
-            project_name :  str, optional
-                The name of the project. If not provided, the project name set
-                in the environment variable `PHOENIX_PROJECT_NAME` will be used.
-                Otherwise, 'default' will be used.
-
-        Returns
-        -------
-            evaluations : List[Evaluations]
-                A list of evaluations for the specified project.
-
-        """
-        project_name = project_name or get_env_project_name()
-        if not (traces := self.traces) or not (project := traces.get_project(project_name)):
-            return []
-        return project.export_evaluations()
+        shutil.rmtree(directory)
+    _session_working_dir = None
 
 
 def launch_app(
@@ -433,6 +428,7 @@ def launch_app(
     port: Optional[int] = None,
     run_in_thread: bool = True,
     notebook_environment: Optional[Union[NotebookEnvironment, str]] = None,
+    use_temp_dir: bool = True,
 ) -> Optional[Session]:
     """
     Launches the phoenix application and returns a session to interact with.
@@ -464,6 +460,10 @@ def launch_app(
         The environment the notebook is running in. This is either 'local', 'colab', or 'sagemaker'.
         If not provided, phoenix will try to infer the environment. This is only needed if
         there is a failure to infer the environment.
+    use_temp_dir: bool, optional, default=True
+        Whether to use a temporary directory to store the data. If set to False, the data will be
+        stored in the directory specified by PHOENIX_WORKING_DIR environment variable via SQLite.
+
 
     Returns
     -------
@@ -479,7 +479,11 @@ def launch_app(
     """
     global _session
 
-    # Stopgap solution to allow the app to run without a primary inferences
+    # First we must ensure that the working directory is setup
+    # NB: this is because the working directory can be deleted by the user
+    ensure_working_dir()
+
+    # Stopgap solution to allow the app to run without a primary dataset
     if primary is None:
         # Dummy inferences
         # TODO: pass through the lack of a primary inferences to the app
@@ -533,9 +537,16 @@ def launch_app(
 
     host = host or get_env_host()
     port = port or get_env_port()
+    if use_temp_dir:
+        global _session_working_dir
+        _session_working_dir = _session_working_dir or TemporaryDirectory()
+        database_url = f"sqlite:///{_session_working_dir.name}/phoenix.db"
+    else:
+        database_url = get_env_database_connection_str()
 
     if run_in_thread:
         _session = ThreadSession(
+            database_url,
             primary,
             reference,
             corpus,
@@ -548,6 +559,7 @@ def launch_app(
         # TODO: catch exceptions from thread
     else:
         _session = ProcessSession(
+            database_url,
             primary,
             reference,
             corpus,
@@ -568,7 +580,8 @@ def launch_app(
         return None
 
     print(f"🌍 To view the Phoenix app in your browser, visit {_session.url}")
-    print("📺 To view the Phoenix app in a notebook, run `px.active_session().view()`")
+    if not use_temp_dir:
+        print(f"💽 Your data is being persisted to {database_url}")
     print("📖 For more information on how to use Phoenix, check out https://docs.arize.com/phoenix")
     return _session
 
@@ -582,10 +595,15 @@ def active_session() -> Optional[Session]:
     return None
 
 
-def close_app() -> None:
+def close_app(delete_data: bool = False) -> None:
     """
     Closes the phoenix application.
     The application server is shut down and will no longer be accessible.
+
+    Parameters
+    ----------
+    delete_data : bool, optional
+        If set to true, all stored phoenix data, including traces and evaluations. Default False.
     """
     global _session
     if _session is None:
@@ -594,6 +612,9 @@ def close_app() -> None:
     _session.end()
     _session = None
     logger.info("Session closed")
+    if delete_data:
+        logger.info("Deleting all data")
+        delete_all(prompt_before_delete=False)
 
 
 def _get_url(host: str, port: int, notebook_env: NotebookEnvironment) -> str:

phoenix/settings.py

@@ -0,0 +1,13 @@
+from dataclasses import dataclass, field
+
+
+@dataclass
+class _Settings:
+    """Settings for Phoenix, lazily initialized."""
+
+    # By default, don't log migrations
+    log_migrations: bool = field(default=False)
+
+
+# Singleton instance of the settings
+Settings = _Settings()