session package#

Submodules#

session.client module#

class session.client.Client(*, endpoint: str | None = None, warn_if_server_not_running: bool = True, headers: Mapping[str, str] | None = None, **kwargs: Any)#

Bases: TraceDataExtractor

append_to_dataset(*, dataset_name: str, dataframe: DataFrame | None = None, csv_file_path: str | Path | None = None, input_keys: Iterable[str] = (), output_keys: Iterable[str] = (), metadata_keys: Iterable[str] = (), inputs: Iterable[Mapping[str, Any]] = (), outputs: Iterable[Mapping[str, Any]] = (), metadata: Iterable[Mapping[str, Any]] = (), dataset_description: str | None = None) → Dataset#

Append examples to dataset on the Phoenix server. If dataframe or csv_file_path are provided, must also provide input_keys (and optionally with output_keys or metadata_keys or both), which is a list of strings denoting the column names in the dataframe or the csv file. On the other hand, a sequence of dictionaries can also be provided via inputs (and optionally with outputs or metadat or both), each item of which represents a separate example in the dataset.

Parameters:

dataset_name – (str): Name of the dataset.
dataframe (pd.DataFrame) – pandas DataFrame.
csv_file_path (str | Path) – Location of a CSV text file
input_keys (Iterable[str]) – List of column names used as input keys. input_keys, output_keys, metadata_keys must be disjoint, and must exist in CSV column headers.
output_keys (Iterable[str]) – List of column names used as output keys. input_keys, output_keys, metadata_keys must be disjoint, and must exist in CSV column headers.
metadata_keys (Iterable[str]) – List of column names used as metadata keys. input_keys, output_keys, metadata_keys must be disjoint, and must exist in CSV column headers.
inputs (Iterable[Mapping[str, Any]]) – List of dictionaries object each corresponding to an example in the dataset.
outputs (Iterable[Mapping[str, Any]]) – List of dictionaries object each corresponding to an example in the dataset.
metadata (Iterable[Mapping[str, Any]]) – List of dictionaries object each corresponding to an example in the dataset.
dataset_description – (Optional[str]): Description of the dataset.

Returns:

A Dataset object with its examples.

get_dataset(*, id: str | None = None, name: str | None = None, version_id: str | None = None) → Dataset#

Gets the dataset for a specific version, or gets the latest version of the dataset if no version is specified.

Parameters:

id (Optional[str]) – An ID for the dataset.
name (Optional[str]) – the name for the dataset. If provided, the ID
name. (is ignored and the dataset is retrieved by)
version_id (Optional[str]) – An ID for the version of the dataset, or
None.

Returns:

A dataset object.

get_dataset_versions(dataset_id: str, /, *, limit: int | None = 100) → DataFrame#

Get dataset versions as pandas DataFrame.

Parameters:

dataset_id (str) – dataset ID
limit (Optional[int]) – maximum number of versions to return, starting from the most recent version

Returns:

pandas DataFrame

get_evaluations(project_name: str | None = None) → List[Evaluations]#

Retrieves evaluations for a given project from the Phoenix server or active session.

Parameters:

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:

A list of Evaluations objects containing evaluation data. Returns an: empty list if no evaluations are found.

Return type:

List[Evaluations]

log_evaluations(*evals: Evaluations, **kwargs: Any) → None#

Logs evaluation data to the Phoenix server.

Parameters:

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

log_traces(trace_dataset: TraceDataset, project_name: str | None = None) → None#

Logs traces from a TraceDataset to the Phoenix server.

Parameters:

trace_dataset (TraceDataset) – A TraceDataset instance with the traces to log to the Phoenix server.
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

Queries spans from the Phoenix server or active session based on specified criteria.

Parameters:

queries (SpanQuery) – One or more SpanQuery objects defining the query criteria.
start_time (datetime, optional) – The start time for the query range. Default None.
end_time (datetime, optional) – The end 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:

A pandas DataFrame or a list of pandas: DataFrames containing the queried span data, or None if no spans are found.

Return type:

Union[pd.DataFrame, List[pd.DataFrame]]

upload_dataset(*, dataset_name: str, dataframe: DataFrame | None = None, csv_file_path: str | Path | None = None, input_keys: Iterable[str] = (), output_keys: Iterable[str] = (), metadata_keys: Iterable[str] = (), inputs: Iterable[Mapping[str, Any]] = (), outputs: Iterable[Mapping[str, Any]] = (), metadata: Iterable[Mapping[str, Any]] = (), dataset_description: str | None = None) → Dataset#

Upload examples as dataset to the Phoenix server. If dataframe or csv_file_path are provided, must also provide input_keys (and optionally with output_keys or metadata_keys or both), which is a list of strings denoting the column names in the dataframe or the csv file. On the other hand, a sequence of dictionaries can also be provided via inputs (and optionally with outputs or metadat or both), each item of which represents a separate example in the dataset.

Parameters:

dataset_name – (str): Name of the dataset.
dataframe (pd.DataFrame) – pandas DataFrame.
csv_file_path (str | Path) – Location of a CSV text file
input_keys (Iterable[str]) – List of column names used as input keys. input_keys, output_keys, metadata_keys must be disjoint, and must exist in CSV column headers.
output_keys (Iterable[str]) – List of column names used as output keys. input_keys, output_keys, metadata_keys must be disjoint, and must exist in CSV column headers.
metadata_keys (Iterable[str]) – List of column names used as metadata keys. input_keys, output_keys, metadata_keys must be disjoint, and must exist in CSV column headers.
inputs (Iterable[Mapping[str, Any]]) – List of dictionaries object each corresponding to an example in the dataset.
outputs (Iterable[Mapping[str, Any]]) – List of dictionaries object each corresponding to an example in the dataset.
metadata (Iterable[Mapping[str, Any]]) – List of dictionaries object each corresponding to an example in the dataset.
dataset_description – (Optional[str]): Description of the dataset.

Returns:

A Dataset object with the uploaded examples.

property web_url: str#

Return the web URL of the Phoenix UI. This is different from the base URL in the cases where there is a proxy like colab

Returns:: A fully qualified URL to the Phoenix UI.
Return type:: str

exception session.client.DatasetUploadError#: Bases: Exception

session.data_extractor module#

class session.data_extractor.TraceDataExtractor#

Bases: ABC

An abstract base class intended to constraint both Client and Session so that they both implement the same methods.

abstract get_evaluations(project_name: str | None = None) → List[Evaluations]#

get_spans_dataframe(filter_condition: str | None = None, *, start_time: datetime | None = None, end_time: datetime | None = None, limit: int | None = 1000, root_spans_only: bool | None = None, project_name: str | None = None) → DataFrame | None#

get_trace_dataset(project_name: str | None = None) → TraceDataset | None#

abstract query_spans(*queries: SpanQuery, start_time: datetime | None = None, end_time: datetime | None = None, limit: int | None = 1000, root_spans_only: bool | None = None, project_name: str | None = None) → DataFrame | List[DataFrame] | None#

session.evaluation module#

A set of helper functions to

extract spans from Phoenix for evaluation - explode retrieved documents from (horizontal) lists to a (vertical) series

indexed by context.span_id and document_position
ingest evaluation results into Phoenix via HttpExporter

session.evaluation.add_evaluations(exporter: HttpExporter, evaluations: Evaluations) → None#

session.evaluation.get_qa_with_reference(obj: CanQuerySpans, start_time: datetime | None = None, end_time: datetime | None = None, project_name: str | None = None, stop_time: datetime | None = None) → DataFrame | None#

session.evaluation.get_retrieved_documents(obj: CanQuerySpans, start_time: datetime | None = None, end_time: datetime | None = None, project_name: str | None = None, stop_time: datetime | None = None) → DataFrame#

session.session module#

class session.session.DatabricksContext(host, org_id, cluster_id)#

Bases: NamedTuple

cluster_id: str#: Alias for field number 2

host: str#: Alias for field number 0

org_id: str#: Alias for field number 1

class session.session.ExportedData#

Bases: UserList

add(paths: Iterable[Path]) → None#

class session.session.NotebookEnvironment(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)#

Bases: Enum

COLAB = 'colab'#

DATABRICKS = 'databricks'#

LOCAL = 'local'#

SAGEMAKER = 'sagemaker'#

class session.session.ProcessSession(database_url: str, primary_inferences: Inferences, reference_inferences: Inferences | None = None, corpus_inferences: Inferences | None = None, trace_dataset: TraceDataset | None = None, default_umap_parameters: Mapping[str, Any] | None = None, host: str | None = None, port: int | None = None, root_path: str | None = None, notebook_env: NotebookEnvironment | None = None)#

Bases: Session

property active: bool#: Whether session is active, i.e. whether server still serves

end() → None#: Ends the session and closes the app service

class session.session.Session(database_url: str, primary_inferences: Inferences, reference_inferences: Inferences | None = None, corpus_inferences: Inferences | None = None, trace_dataset: TraceDataset | None = None, default_umap_parameters: Mapping[str, Any] | None = None, host: str | None = None, port: int | None = None, notebook_env: NotebookEnvironment | None = None)#

Bases: TraceDataExtractor, ABC

Session that maintains a 1-1 shared state with the Phoenix App.

abstract property active: bool#: Whether session is active, i.e. whether server still serves

property database_url: str#

abstract end() → None#: Ends the session and closes the app service

property exports: ExportedData#

Exported data sorted in descending order by modification date.

Returns:: dataframes – List of dataframes
Return type:: list

get_evaluations(project_name: str | None = 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 – A list of evaluations for the specified project.
Return type:: List[Evaluations]

notebook_env: NotebookEnvironment#: The notebook environment that the session is running in.

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:

DataFrame: DataFrame or list of DataFrames containing the query results.

Return type:

results

trace_dataset: TraceDataset | None#

property url: str#: Returns the url for the phoenix app

view(height: int = 1000) → IFrame#

Returns an IFrame that can be displayed in a notebook to view the app.

Parameters:: height (int, optional) – The height of the IFrame in pixels. Defaults to 1000.

class session.session.ThreadSession(database_url: str, primary_inferences: Inferences, reference_inferences: Inferences | None = None, corpus_inferences: Inferences | None = None, trace_dataset: TraceDataset | None = None, default_umap_parameters: Mapping[str, Any] | None = None, host: str | None = None, port: int | None = None, root_path: str | None = None, notebook_env: NotebookEnvironment | None = None)#

Bases: Session

property active: bool#: Whether session is active, i.e. whether server still serves

end() → None#: Ends the session and closes the app service

session.session.active_session() → Session | None#: Returns the active session if one exists, otherwise returns None

session.session.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.

session.session.delete_all(prompt_before_delete: bool | None = True) → None#: Deletes the entire contents of the working directory. This will delete, traces, evaluations, and any other data stored in the working directory.

Launches the phoenix application and returns a session to interact with.

Parameters:

primary (Dataset, optional) – The primary dataset to analyze
reference (Dataset, optional) – The reference dataset to compare against. If not provided, drift analysis will not be available.
corpus (Dataset, optional) – The dataset containing corpus for LLM context retrieval.
trace (TraceDataset, optional) – The trace dataset containing the trace data.
host (str, optional) – The host on which the server runs. It can also be set using environment variable PHOENIX_HOST, otherwise it defaults to 127.0.0.1.
port (int, optional) – The port on which the server listens. When using traces this should not be used and should instead set the environment variable PHOENIX_PORT. Defaults to 6006.
run_in_thread (bool, optional, default=True) – Whether the server should run in a Thread or Process.
default_umap_parameters (Dict[str, Union[int, float]], optional, default=None) – User specified default UMAP parameters eg: {“n_neighbors”: 10, “n_samples”: 5, “min_dist”: 0.5}
notebook_environment (str, optional, default=None) – 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:

session – The session object that can be used to view the application

Return type:

Session

Examples

>>> import phoenix as px
>>> # construct an inference set to analyze
>>> inferences = px.Inferences(...)
>>> session = px.launch_app(inferences)

session package#

Submodules#

session.client module#

session.data_extractor module#

session.evaluation module#

session.session module#

Module contents#

This Page