feat: Improve client semantics (#7399)

* Update project_identifier semantics

* Improve joining ergonomics for annotations dataframe

* Ruff 🐶

* Optimize fetching project name

* Ignore some pyright errors w/ pandas

* Update type ignore

Author: anticorrelator

packages/phoenix-client/src/phoenix/client/resources/spans/__init__.py

@@ -1,3 +1,4 @@
+import base64
 import logging
 from datetime import datetime, timezone, tzinfo
 from io import StringIO
@@ -46,6 +47,7 @@ def get_spans_dataframe(
         end_time: Optional[datetime] = None,
         limit: int = 1000,
         root_spans_only: Optional[bool] = None,
+        project_identifier: Optional[str] = None,
         project_name: Optional[str] = None,
         timeout: Optional[int] = DEFAULT_TIMEOUT_IN_SECONDS,
     ) -> "pd.DataFrame":
@@ -58,7 +60,9 @@ def get_spans_dataframe(
             end_time: Optional end time for filtering.
             limit: Maximum number of spans to return.
             root_spans_only: Whether to return only root spans.
-            project_name: Optional project name to filter by.
+            project_name: Optional project name to filter by. Deprecated, use `project_identifier`
+                to also specify by the project id.
+            project_identifier: Optional project identifier (name or id) to filter by.
             timeout: Optional request timeout in seconds.
 
         Returns:
@@ -86,6 +90,21 @@ def get_spans_dataframe(
 
             _ = pd  # Prevent unused symbol error
 
+            if project_identifier and project_name:
+                raise ValueError("Provide only one of 'project_identifier' or 'project_name'.")
+            elif project_identifier and not project_name:
+                if _is_base64_project_identifier(project_identifier):
+                    project_response = self._client.get(
+                        url=f"v1/projects/{project_identifier}",
+                        headers={"accept": "application/json"},
+                        timeout=timeout,
+                    )
+                    project_response.raise_for_status()
+                    project = project_response.json()
+                    project_name = project["data"]["name"]
+                else:
+                    project_name = project_identifier
+
             response = self._client.post(
                 url="v1/spans",
                 headers={"accept": "application/json"},
@@ -120,7 +139,7 @@ def get_span_annotations_dataframe(
         *,
         spans_dataframe: Optional["pd.DataFrame"] = None,
         span_ids: Optional[Iterable[str]] = None,
-        project: str = "default",
+        project_identifier: str = "default",
         limit: int = 1000,
         timeout: Optional[int] = DEFAULT_TIMEOUT_IN_SECONDS,
     ) -> "pd.DataFrame":
@@ -133,7 +152,7 @@ def get_span_annotations_dataframe(
             spans_dataframe: A DataFrame (typically returned by `get_spans_dataframe`) with a
                 `context.span_id` or `span_id` column.
             span_ids: An iterable of span IDs.
-            project: The project identifier (name or ID) used in the API path.
+            project_identifier: The project identifier (name or ID) used in the API path.
             limit: Maximum number of annotations returned per request page.
             timeout: Optional request timeout in seconds.
 
@@ -173,7 +192,7 @@ def get_span_annotations_dataframe(
             return pd.DataFrame()
 
         annotations: list[v1.SpanAnnotation] = []
-        path = f"v1/projects/{project}/span_annotations"
+        path = f"v1/projects/{project_identifier}/span_annotations"
 
         for i in range(0, len(span_ids_list), _MAX_SPAN_IDS_PER_REQUEST):
             batch_ids = span_ids_list[i : i + _MAX_SPAN_IDS_PER_REQUEST]
@@ -202,14 +221,16 @@ def get_span_annotations_dataframe(
                     break  # finished paginating this batch
 
         df = pd.DataFrame(annotations)
-        df.set_index("span_id", inplace=True)
+        df = _flatten_nested_column(df, "result")
+        df.rename(columns={"name": "annotation_name"}, inplace=True)
+        df.set_index("span_id", inplace=True)  # type: ignore[unused-ignore]
         return df
 
     def get_span_annotations(
         self,
         *,
         span_ids: Iterable[str],
-        project: str,
+        project_identifier: str,
         limit: int = 1000,
         timeout: Optional[int] = DEFAULT_TIMEOUT_IN_SECONDS,
     ) -> list[v1.SpanAnnotation]:
@@ -218,7 +239,7 @@ def get_span_annotations(
 
         Args:
             span_ids: An iterable of span IDs.
-            project: The project identifier (name or ID) used in the API path.
+            project_identifier: The project identifier (name or ID) used in the API path.
             limit: Maximum number of annotations returned per request page.
             timeout: Optional request timeout in seconds.
 
@@ -234,7 +255,7 @@ def get_span_annotations(
             return []
 
         annotations: list[v1.SpanAnnotation] = []
-        path = f"v1/projects/{project}/span_annotations"
+        path = f"v1/projects/{project_identifier}/span_annotations"
 
         for i in range(0, len(span_ids_list), _MAX_SPAN_IDS_PER_REQUEST):
             batch_ids = span_ids_list[i : i + _MAX_SPAN_IDS_PER_REQUEST]
@@ -290,6 +311,7 @@ async def get_spans_dataframe(
         limit: int = 1000,
         root_spans_only: Optional[bool] = None,
         project_name: Optional[str] = None,
+        project_identifier: Optional[str] = None,
         timeout: Optional[int] = DEFAULT_TIMEOUT_IN_SECONDS,
     ) -> "pd.DataFrame":
         """
@@ -301,7 +323,9 @@ async def get_spans_dataframe(
             end_time: Optional end time for filtering.
             limit: Maximum number of spans to return.
             root_spans_only: Whether to return only root spans.
-            project_name: Optional project name to filter by.
+            project_name: Optional project name to filter by. Deprecated, use `project_identifier`
+                to also specify by the project id.
+            project_identifier: Optional project identifier (name or id) to filter by.
             timeout: Optional request timeout in seconds.
 
         Returns:
@@ -329,6 +353,21 @@ async def get_spans_dataframe(
 
             _ = pd  # Prevent unused symbol error
 
+            if project_identifier and project_name:
+                raise ValueError("Provide only one of 'project_identifier' or 'project_name'.")
+            elif project_identifier and not project_name:
+                if _is_base64_project_identifier(project_identifier):
+                    project_response = await self._client.get(
+                        url=f"v1/projects/{project_identifier}",
+                        headers={"accept": "application/json"},
+                        timeout=timeout,
+                    )
+                    project_response.raise_for_status()
+                    project = project_response.json()
+                    project_name = project["name"]
+                else:
+                    project_name = project_identifier
+
             response = await self._client.post(
                 url="v1/spans",
                 headers={"accept": "application/json"},
@@ -444,7 +483,9 @@ async def get_span_annotations_dataframe(
                     break
 
         df = pd.DataFrame(annotations)
-        df.set_index("span_id", inplace=True)
+        df = _flatten_nested_column(df, "result")
+        df.rename(columns={"name": "annotation_name"}, inplace=True)
+        df.set_index("span_id", inplace=True)  # type: ignore[unused-ignore]
         return df
 
     async def get_span_annotations(
@@ -565,4 +606,27 @@ def _process_span_dataframe(response: httpx.Response) -> "pd.DataFrame":
         return pd.DataFrame()
 
 
+def _is_base64_project_identifier(s: str) -> bool:
+    try:
+        decoded = base64.b64decode(s, validate=True)
+        if not decoded.startswith(b"Project:"):
+            return False
+        return True
+    except Exception:
+        return False
+
+
+def _flatten_nested_column(df: "pd.DataFrame", column_name: str) -> "pd.DataFrame":
+    import pandas as pd
+
+    if column_name in df.columns:
+        # Flatten the nested dictionary column and prefix each resulting column with
+        # the original column name (e.g., "result.label").
+        nested_df = pd.json_normalize(df[column_name]).rename(  # type: ignore[arg-type]
+            columns=lambda col: f"{column_name}.{col}"
+        )
+        df = pd.concat([df.drop(columns=[column_name]), nested_df], axis=1)
+    return df
+
+
 class TimeoutError(Exception): ...

tutorials/human_feedback/chatbot_with_human_feedback.ipynb

@@ -34,7 +34,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 1,
+   "execution_count": null,
    "metadata": {},
    "outputs": [],
    "source": [
@@ -89,7 +89,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 2,
+   "execution_count": null,
    "metadata": {},
    "outputs": [],
    "source": [
@@ -114,7 +114,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 4,
+   "execution_count": null,
    "metadata": {},
    "outputs": [],
    "source": [
@@ -236,13 +236,13 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 1,
+   "execution_count": null,
    "metadata": {},
    "outputs": [],
    "source": [
-    "spans_df = client.spans.get_spans_dataframe(project_name=\"default\")\n",
+    "spans_df = client.spans.get_spans_dataframe(project_identifier=\"default\")\n",
     "annotations_df = client.spans.get_span_annotations_dataframe(\n",
-    "    spans_dataframe=spans_df, project=\"default\"\n",
+    "    spans_dataframe=spans_df, project_identifier=\"default\"\n",
     ")"
    ]
   },
@@ -252,27 +252,22 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "annotations_df.join(spans_df, how=\"inner\", lsuffix=\"_annotation\", rsuffix=\"_span\")"
+    "annotations_df.join(spans_df, how=\"inner\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "client.spans.get_span_annotations(span_ids=spans_df.index, project_identifier=\"default\")"
    ]
   }
  ],
  "metadata": {
-  "kernelspec": {
-   "display_name": "dev",
-   "language": "python",
-   "name": "python3"
-  },
   "language_info": {
-   "codemirror_mode": {
-    "name": "ipython",
-    "version": 3
-   },
-   "file_extension": ".py",
-   "mimetype": "text/x-python",
-   "name": "python",
-   "nbconvert_exporter": "python",
-   "pygments_lexer": "ipython3",
-   "version": "3.11.9"
+   "name": "python"
   }
  },
  "nbformat": 4,