session
=======

.. contents:: :local:

phoenix.launch_app
------------------
.. automethod:: session.session::launch_app

   **Usage**

      Launch Phoenix as a collector of LLM Traces generated by your LLM applications.
      By default the collector listens on port 6006::

         import phoenix as px

      Launch Phoenix with primary and reference inferences `prim_inf_` and `ref_inf_`,
      both instances of Inferences, with::

         session = px.launch_app(prim_inf_, ref_inf_)

      Alternatively, launch Phoenix with a single dataset inf, an instance of Inferences, with::

         session = px.launch_app(inf)

      Then session is an instance of Session that can be used to open the Phoenix UI in an inline
      frame within the notebook or in a separate browser tab or window.

phoenix.active_session
----------------------
.. automethod:: session.session::active_session

   **Usage**

      Suppose you previously ran::

         px.launch_app()

      without assigning the returned Session instance to a variable.
      If you later find that you need access to the running session object, run::

         session = px.active_session()

      Then session is an instance of Session that can be used to open the Phoenix UI
      in an inline frame within your notebook or in a separate browser tab or window.

phoenix.close_app
-----------------
.. automethod:: session.session::close_app

   .. warning::
      The Phoenix server will continue running in the background until it is explicitly closed, even if the Jupyter server and kernel are stopped.

phoenix.delete_all
------------------
.. automethod:: session.session::delete_all

phoenix.Session
---------------
   A session that maintains the state of the Phoenix app. Obtain the active session as follows::

      session = px.active_session()

.. warning::

   Phoenix users should not instantiate their own phoenix.Session instances.
   They interact with this API only when an instance of the class is returned by launch_app or active_session.

.. autoclass:: session.session::Session
   :members:
   :exclude-members: active, end, trace_dataset

**Usage**

   Launch Phoenix with primary and reference inferences prim_inf and ref_inf, both instances of phoenix.Dataset, with::

      session = px.launch_app(prim_inf, ref_inf)

   Alternatively, launch Phoenix with a single dataset ds, an instance of phoenix.Dataset, with::

      session = px.launch_app(inf)

   Open the Phoenix UI in an inline frame within your notebook with::

      session.view()

   You can adjust the height of the inline frame by passing the desired height (number of pixels) to the height parameter.
   For example, instead of the line above, run::

      session.view(height=1200)

   to open an inline frame of height 1200 pixels.

   As an alternative to an inline frame within your notebook, you can open the Phoenix UI in a new browser tab or window by running::

      session.url

   and copying and pasting the URL.

   Once a cluster or subset of your data is selected in the UI, it can be saved by clicking the "Export" button.
   You can then access your exported data in your notebook via the exports property on your session object, which returns a
   list of dataframes containing each export.

   ..code::

      session.exports

   Exported dataframes are listed in chronological order. To access your most recent export, run::

      session.exports[-1]

**Get LLM Spans As DataFrame**

   Get all available spans. See LLM Traces on how to trace your LLM applications.::

      session.get_spans_dataframe()

   Get spans associated with calls to LLMs.::

      session.get_spans_dataframe("span_kind == 'LLM'")

   Get spans associated with calls to retrievers in a Retrieval Augmented Generation use case.::

      session.get_spans_dataframe("span_kind == 'RETRIEVER'")