@arizeai/phoenix-client 6.3.0 → 6.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arizeai/phoenix-client",
-  "version": "6.3.0",
+  "version": "6.5.0",
   "description": "A client for the Phoenix API",
   "keywords": [
     "arize",

package/src/__generated__/api/v1.ts

@@ -424,6 +424,23 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/v1/projects/{project_identifier}/traces": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** List traces for a project */
+        get: operations["listProjectTraces"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/v1/trace_annotations": {
         parameters: {
             query?: never;
@@ -1562,6 +1579,13 @@ export interface components {
             /** Next Cursor */
             next_cursor: string | null;
         };
+        /** GetTracesResponseBody */
+        GetTracesResponseBody: {
+            /** Data */
+            data: components["schemas"]["TraceData"][];
+            /** Next Cursor */
+            next_cursor: string | null;
+        };
         /** GetUsersResponseBody */
         GetUsersResponseBody: {
             /** Data */
@@ -3210,6 +3234,52 @@ export interface components {
             /** Next Cursor */
             next_cursor: string | null;
         };
+        /** TraceData */
+        TraceData: {
+            /** Id */
+            id: string;
+            /** Trace Id */
+            trace_id: string;
+            /** Project Id */
+            project_id: string;
+            /**
+             * Start Time
+             * Format: date-time
+             */
+            start_time: string;
+            /**
+             * End Time
+             * Format: date-time
+             */
+            end_time: string;
+            /** Spans */
+            spans?: components["schemas"]["TraceSpanData"][] | null;
+        };
+        /** TraceSpanData */
+        TraceSpanData: {
+            /** Id */
+            id: string;
+            /** Span Id */
+            span_id: string;
+            /** Parent Id */
+            parent_id: string | null;
+            /** Name */
+            name: string;
+            /** Span Kind */
+            span_kind: string;
+            /** Status Code */
+            status_code: string;
+            /**
+             * Start Time
+             * Format: date-time
+             */
+            start_time: string;
+            /**
+             * End Time
+             * Format: date-time
+             */
+            end_time: string;
+        };
         /** UpdateAnnotationConfigResponseBody */
         UpdateAnnotationConfigResponseBody: {
             /** Data */
@@ -3938,6 +4008,8 @@ export interface operations {
                     "metadata_keys[]"?: string[];
                     /** @description Column names for auto-assigning examples to splits */
                     "split_keys[]"?: string[];
+                    /** @description Column names whose object values should be flattened into their selected bucket */
+                    "flatten_keys[]"?: string[];
                     /** @description Column name for span IDs to link examples back to spans */
                     span_id_key?: string;
                     /** Format: binary */
@@ -4744,6 +4816,73 @@ export interface operations {
             };
         };
     };
+    listProjectTraces: {
+        parameters: {
+            query?: {
+                /** @description Inclusive lower bound on trace start time (ISO 8601) */
+                start_time?: string | null;
+                /** @description Exclusive upper bound on trace start time (ISO 8601) */
+                end_time?: string | null;
+                /** @description Sort field */
+                sort?: "start_time" | "latency_ms";
+                /** @description Sort direction */
+                order?: "asc" | "desc";
+                /** @description Maximum number of traces to return */
+                limit?: number;
+                /** @description Pagination cursor (Trace GlobalID) */
+                cursor?: string | null;
+                /** @description If true, include full span details for each trace. This significantly increases response size and query latency, especially with large page sizes. Prefer fetching spans lazily for individual traces when possible. */
+                include_spans?: boolean;
+                /** @description List of session identifiers to filter traces by. Each value can be either a session_id string or a session GlobalID. Only traces belonging to the specified sessions will be returned. */
+                session_identifier?: string[] | null;
+            };
+            header?: never;
+            path: {
+                /** @description The project identifier: either project ID or project name. */
+                project_identifier: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Successful Response */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["GetTracesResponseBody"];
+                };
+            };
+            /** @description Forbidden */
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "text/plain": string;
+                };
+            };
+            /** @description Not Found */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "text/plain": string;
+                };
+            };
+            /** @description Unprocessable Entity */
+            422: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "text/plain": string;
+                };
+            };
+        };
+    };
     annotateTraces: {
         parameters: {
             query?: {
@@ -4861,6 +5000,10 @@ export interface operations {
                 trace_id?: string[] | null;
                 /** @description Filter by parent span ID. Use "null" to get root spans only. */
                 parent_id?: string | null;
+                /** @description Filter by span name(s) */
+                name?: string[] | null;
+                /** @description Filter by status code(s). Values: OK, ERROR, UNSET */
+                status_code?: string[] | null;
             };
             header?: never;
             path: {
@@ -4924,6 +5067,12 @@ export interface operations {
                 trace_id?: string[] | null;
                 /** @description Filter by parent span ID. Use "null" to get root spans only. */
                 parent_id?: string | null;
+                /** @description Filter by span name(s) */
+                name?: string[] | null;
+                /** @description Filter by span kind(s). Values: LLM, CHAIN, TOOL, RETRIEVER, EMBEDDING, AGENT, RERANKER, GUARDRAIL, EVALUATOR, UNKNOWN */
+                span_kind?: string[] | null;
+                /** @description Filter by status code(s). Values: OK, ERROR, UNSET */
+                status_code?: string[] | null;
             };
             header?: never;
             path: {

package/src/client.ts

@@ -12,6 +12,13 @@ import {
   defaultGetEnvironmentOptions,
   makeDefaultClientOptions,
 } from "./config";
+import type { SemanticVersion } from "./types/semver";
+import { parseSemanticVersion } from "./utils/semverUtils";
+
+/**
+ * The HTTP response header that carries the Phoenix server version string.
+ */
+export const PHOENIX_SERVER_VERSION_HEADER = "x-phoenix-server-version";
 
 export type pathsV1 = oapiPathsV1;
 export type componentsV1 = oapiComponentsV1;
@@ -98,10 +105,64 @@ export const createClient = (
 ) => {
   const mergedOptions = getMergedOptions(config);
   const openApiClient = createOpenApiClient<pathsV1>(mergedOptions);
+
+  // Lazily populated by versionMiddleware from the x-phoenix-server-version
+  // response header on the first successful API call. Read via getServerVersion().
+  let serverVersion: SemanticVersion | null | undefined;
+
+  const versionMiddleware: Middleware = {
+    onResponse({ response }) {
+      if (serverVersion === undefined) {
+        const header = response.headers.get(PHOENIX_SERVER_VERSION_HEADER);
+        if (header) {
+          serverVersion = parseSemanticVersion(header);
+        }
+      }
+    },
+  };
+
+  openApiClient.use(versionMiddleware);
   openApiClient.use(middleware);
+
   return {
     ...openApiClient,
     config: mergedOptions,
+    /**
+     * Get the Phoenix server version, returning a cached value if available.
+     *
+     * The version is first populated from the `x-phoenix-server-version`
+     * response header on any API call. If no version has been seen yet,
+     * this method fetches `GET /arize_phoenix_version` to populate the cache.
+     *
+     * @throws {Error} If the server version cannot be determined (e.g. the
+     * server is unreachable or returned an unparseable version string).
+     */
+    getServerVersion: async (): Promise<SemanticVersion> => {
+      if (serverVersion != null) return serverVersion;
+      try {
+        const baseUrl = mergedOptions.baseUrl ?? "";
+        const headers = mergedOptions.headers
+          ? { ...(mergedOptions.headers as Record<string, string>) }
+          : {};
+        const resp = await fetch(`${baseUrl}/arize_phoenix_version`, {
+          headers,
+        });
+        if (resp.ok) {
+          const text = await resp.text();
+          const parsed = parseSemanticVersion(text);
+          if (parsed) {
+            serverVersion = parsed;
+            return serverVersion;
+          }
+        }
+      } catch {
+        // fall through to throw below
+      }
+      throw new Error(
+        "Phoenix server version could not be determined. " +
+          "Please ensure you are connecting to a supported Phoenix server."
+      );
+    },
   };
 };
 

package/src/constants/serverRequirements.ts

@@ -0,0 +1,77 @@
+/**
+ * Known server capability requirements.
+ *
+ * Each constant below describes a single Phoenix server capability — an HTTP
+ * route or query parameter — together with the minimum server version that
+ * supports it.  These constants are passed to
+ * {@link ensureServerCapability} at call time to produce a clear error when
+ * the connected server is too old.
+ *
+ * When a new version-gated capability is added to the Phoenix REST API, add a
+ * corresponding requirement constant here and reference it from the client
+ * function that uses it.
+ */
+
+import type {
+  CapabilityRequirement,
+  ParameterRequirement,
+  RouteRequirement,
+} from "../types/serverRequirements";
+
+export const GET_SESSION: RouteRequirement = {
+  kind: "route",
+  method: "GET",
+  path: "/v1/sessions/{session_id}",
+  minServerVersion: [13, 5, 0],
+};
+
+export const DELETE_SESSION: RouteRequirement = {
+  kind: "route",
+  method: "DELETE",
+  path: "/v1/sessions/{session_id}",
+  minServerVersion: [13, 13, 0],
+};
+
+export const DELETE_SESSIONS: RouteRequirement = {
+  kind: "route",
+  method: "POST",
+  path: "/v1/sessions/delete",
+  minServerVersion: [13, 13, 0],
+};
+
+export const LIST_PROJECT_SESSIONS: RouteRequirement = {
+  kind: "route",
+  method: "GET",
+  path: "/v1/projects/{project_id}/sessions",
+  minServerVersion: [13, 5, 0],
+};
+
+export const ANNOTATE_SESSIONS: RouteRequirement = {
+  kind: "route",
+  method: "POST",
+  path: "/v1/session_annotations",
+  minServerVersion: [12, 0, 0],
+};
+
+export const GET_SPANS_TRACE_IDS: ParameterRequirement = {
+  kind: "parameter",
+  parameterName: "trace_id",
+  parameterLocation: "query",
+  route: "GET /v1/projects/{id}/spans",
+  minServerVersion: [13, 9, 0],
+};
+
+/**
+ * Aggregate list of every known capability requirement.
+ *
+ * Useful for manifest scanning or startup diagnostics — iterate over this
+ * array to check which capabilities the connected server supports.
+ */
+export const ALL_REQUIREMENTS: readonly CapabilityRequirement[] = [
+  GET_SESSION,
+  DELETE_SESSION,
+  DELETE_SESSIONS,
+  LIST_PROJECT_SESSIONS,
+  ANNOTATE_SESSIONS,
+  GET_SPANS_TRACE_IDS,
+] as const;

package/src/sessions/addSessionAnnotation.ts

@@ -1,5 +1,7 @@
 import { createClient } from "../client";
+import { ANNOTATE_SESSIONS } from "../constants/serverRequirements";
 import type { ClientFn } from "../types/core";
+import { ensureServerCapability } from "../utils/serverVersionUtils";
 import type { SessionAnnotation } from "./types";
 import { toSessionAnnotationData } from "./types";
 
@@ -25,6 +27,8 @@ export interface AddSessionAnnotationParams extends ClientFn {
  * @param params - The parameters to add a span annotation
  * @returns The ID of the created or updated annotation
  *
+ * @requires Phoenix server >= 12.0.0
+ *
  * @example
  * ```ts
  * const result = await addSessionAnnotation({
@@ -48,6 +52,7 @@ export async function addSessionAnnotation({
   sync = false,
 }: AddSessionAnnotationParams): Promise<{ id: string } | null> {
   const client = _client ?? createClient();
+  await ensureServerCapability({ client, requirement: ANNOTATE_SESSIONS });
 
   const { data, error } = await client.POST("/v1/session_annotations", {
     params: {

package/src/sessions/deleteSession.ts

@@ -1,5 +1,7 @@
 import { createClient } from "../client";
+import { DELETE_SESSION } from "../constants/serverRequirements";
 import type { ClientFn } from "../types/core";
+import { ensureServerCapability } from "../utils/serverVersionUtils";
 
 /**
  * Parameters to delete a session
@@ -25,6 +27,8 @@ export interface DeleteSessionParams extends ClientFn {
  * @returns Promise that resolves when the session is successfully deleted
  * @throws Error if the session is not found or deletion fails
  *
+ * @requires Phoenix server >= 13.13.0
+ *
  * @example
  * ```ts
  * // Delete by user-provided session ID
@@ -45,6 +49,7 @@ export async function deleteSession({
   sessionId,
 }: DeleteSessionParams): Promise<void> {
   const client = _client ?? createClient();
+  await ensureServerCapability({ client, requirement: DELETE_SESSION });
 
   const { error } = await client.DELETE("/v1/sessions/{session_identifier}", {
     params: {

package/src/sessions/deleteSessions.ts

@@ -1,5 +1,7 @@
 import { createClient } from "../client";
+import { DELETE_SESSIONS } from "../constants/serverRequirements";
 import type { ClientFn } from "../types/core";
+import { ensureServerCapability } from "../utils/serverVersionUtils";
 
 /**
  * Parameters to bulk delete sessions
@@ -28,6 +30,8 @@ export interface DeleteSessionsParams extends ClientFn {
  * @returns Promise that resolves when the sessions are successfully deleted
  * @throws Error if identifiers are mixed types or deletion fails
  *
+ * @requires Phoenix server >= 13.13.0
+ *
  * @example
  * ```ts
  * // Delete by user-provided session IDs
@@ -48,6 +52,7 @@ export async function deleteSessions({
   sessionIds,
 }: DeleteSessionsParams): Promise<void> {
   const client = _client ?? createClient();
+  await ensureServerCapability({ client, requirement: DELETE_SESSIONS });
 
   const { error } = await client.POST("/v1/sessions/delete", {
     body: {

package/src/sessions/getSession.ts

@@ -1,8 +1,10 @@
 import invariant from "tiny-invariant";
 
 import { createClient } from "../client";
+import { GET_SESSION } from "../constants/serverRequirements";
 import type { ClientFn } from "../types/core";
 import type { Session } from "../types/sessions";
+import { ensureServerCapability } from "../utils/serverVersionUtils";
 import { toSession } from "./sessionUtils";
 
 export type GetSessionParams = ClientFn & {
@@ -15,6 +17,8 @@ export type GetSessionParams = ClientFn & {
 /**
  * Fetch a single session by its GlobalID or user-provided session_id string.
  *
+ * @requires Phoenix server >= 13.5.0
+ *
  * @example
  * ```ts
  * import { getSession } from "@arizeai/phoenix-client/sessions";
@@ -28,6 +32,7 @@ export async function getSession({
   sessionId,
 }: GetSessionParams): Promise<Session> {
   const client = _client || createClient();
+  await ensureServerCapability({ client, requirement: GET_SESSION });
   const { data, error } = await client.GET(
     "/v1/sessions/{session_identifier}",
     {

package/src/sessions/getSessionTurns.ts

@@ -0,0 +1,220 @@
+import { SemanticConventions } from "@arizeai/openinference-semantic-conventions";
+
+import type { components } from "../__generated__/api/v1";
+import { createClient } from "../client";
+import { getSpans } from "../spans/getSpans";
+import type { ClientFn } from "../types/core";
+import type { Session, SessionTrace } from "../types/sessions";
+import { getSession } from "./getSession";
+
+type Span = components["schemas"]["Span"];
+
+const MAX_TRACE_IDS_PER_BATCH = 50;
+
+/**
+ * Input or output extracted from a root span's attributes.
+ *
+ * @experimental this interface is experimental and may change in the future
+ */
+export interface SessionTurnIO {
+  /** The string value of the input or output */
+  value: string;
+  /** Optional MIME type (e.g. "text/plain", "application/json") */
+  mimeType?: string;
+}
+
+/**
+ * A single turn in a session, representing one trace's root span input/output.
+ *
+ * **Note:** A "turn" is derived from a trace's root span. For input/output to appear,
+ * the root span must have `input.value` and `output.value` attributes set
+ * (per OpenInference semantic conventions). This typically requires instrumentation
+ * that records these attributes on the top-level span.
+ *
+ * @experimental this interface is experimental and may change in the future
+ */
+export interface SessionTurn {
+  /** The trace ID for this turn */
+  traceId: string;
+  /** ISO 8601 timestamp of when the trace started */
+  startTime: string;
+  /** ISO 8601 timestamp of when the trace ended */
+  endTime: string;
+  /** Input extracted from the root span's attributes */
+  input?: SessionTurnIO;
+  /** Output extracted from the root span's attributes */
+  output?: SessionTurnIO;
+  /** The full root span, if found */
+  rootSpan?: Span;
+}
+
+/**
+ * @experimental this interface is experimental and may change in the future
+ */
+export interface GetSessionTurnsParams extends ClientFn {
+  /** The session identifier: either a GlobalID or user-provided session_id string. */
+  sessionId: string;
+}
+
+/**
+ * Get the turns (root span I/O) for a session.
+ *
+ * Returns input/output extracted from root spans for each trace, along with
+ * the full root span. Turns are ordered by trace start_time.
+ *
+ * **Note:** A "turn" is derived from a trace's root span. For input/output to appear,
+ * the root span must have `input.value` and `output.value` attributes set
+ * (per OpenInference semantic conventions). This typically requires instrumentation
+ * that records these attributes on the top-level span.
+ *
+ * @experimental this function is experimental and may change in the future
+ *
+ * @example
+ * ```ts
+ * import { getSessionTurns } from "@arizeai/phoenix-client/sessions";
+ *
+ * const turns = await getSessionTurns({ sessionId: "my-session" });
+ * for (const turn of turns) {
+ *   console.log(`[${turn.startTime}] Input: ${turn.input?.value}`);
+ *   console.log(`[${turn.startTime}] Output: ${turn.output?.value}`);
+ * }
+ * ```
+ */
+export async function getSessionTurns({
+  client: _client,
+  sessionId,
+}: GetSessionTurnsParams): Promise<SessionTurn[]> {
+  const client = _client ?? createClient();
+
+  // getSession already calls ensureSessionsApi internally
+  const session: Session = await getSession({ client, sessionId });
+  const traces = session.traces;
+  if (traces.length === 0) {
+    return [];
+  }
+
+  const projectId = session.projectId;
+  const traceInfo = new Map<string, SessionTrace>(
+    traces.map((t) => [t.traceId, t])
+  );
+  const allTraceIds = [...traceInfo.keys()];
+
+  // Fetch root spans in batches
+  const rootSpansByTrace = new Map<string, Span>();
+  for (let i = 0; i < allTraceIds.length; i += MAX_TRACE_IDS_PER_BATCH) {
+    const traceIdBatch = allTraceIds.slice(i, i + MAX_TRACE_IDS_PER_BATCH);
+    const spans = await getAllRootSpansForBatch({
+      client,
+      projectId,
+      traceIdBatch,
+    });
+    for (const span of spans) {
+      const traceId = span.context.trace_id;
+      if (!rootSpansByTrace.has(traceId)) {
+        rootSpansByTrace.set(traceId, span);
+      }
+    }
+  }
+
+  return buildSessionTurns({ allTraceIds, traceInfo, rootSpansByTrace });
+}
+
+/**
+ * Fetch all root spans for a batch of trace IDs, handling pagination.
+ */
+async function getAllRootSpansForBatch({
+  client,
+  projectId,
+  traceIdBatch,
+}: {
+  client: ReturnType<typeof createClient>;
+  projectId: string;
+  traceIdBatch: string[];
+}): Promise<Span[]> {
+  const allSpans: Span[] = [];
+  let cursor: string | null = null;
+
+  do {
+    const result = await getSpans({
+      client,
+      project: { projectId },
+      traceIds: traceIdBatch,
+      parentId: null,
+      limit: traceIdBatch.length,
+      ...(cursor ? { cursor } : {}),
+    });
+    allSpans.push(...result.spans);
+    cursor = result.nextCursor;
+  } while (cursor != null);
+
+  return allSpans;
+}
+
+/**
+ * Extract a SessionTurnIO from span attributes for a given prefix.
+ */
+function extractIO({
+  attrs,
+  valueKey,
+  mimeTypeKey,
+}: {
+  attrs: Record<string, unknown>;
+  valueKey: string;
+  mimeTypeKey: string;
+}): SessionTurnIO | undefined {
+  const value = attrs[valueKey];
+  if (value == null) return undefined;
+  const io: SessionTurnIO = { value: String(value) };
+  const mimeType = attrs[mimeTypeKey];
+  if (mimeType != null) {
+    io.mimeType = String(mimeType);
+  }
+  return io;
+}
+
+/**
+ * Build session turns from trace info and root spans, ordered by start_time.
+ */
+function buildSessionTurns({
+  allTraceIds,
+  traceInfo,
+  rootSpansByTrace,
+}: {
+  allTraceIds: string[];
+  traceInfo: Map<string, SessionTrace>;
+  rootSpansByTrace: Map<string, Span>;
+}): SessionTurn[] {
+  const turns: SessionTurn[] = [];
+
+  for (const traceId of allTraceIds) {
+    const info = traceInfo.get(traceId);
+    if (!info) continue;
+
+    const turn: SessionTurn = {
+      traceId,
+      startTime: info.startTime,
+      endTime: info.endTime,
+    };
+
+    const rootSpan = rootSpansByTrace.get(traceId);
+    if (rootSpan) {
+      turn.rootSpan = rootSpan;
+      const attrs = rootSpan.attributes ?? {};
+      turn.input = extractIO({
+        attrs,
+        valueKey: SemanticConventions.INPUT_VALUE,
+        mimeTypeKey: SemanticConventions.INPUT_MIME_TYPE,
+      });
+      turn.output = extractIO({
+        attrs,
+        valueKey: SemanticConventions.OUTPUT_VALUE,
+        mimeTypeKey: SemanticConventions.OUTPUT_MIME_TYPE,
+      });
+    }
+
+    turns.push(turn);
+  }
+
+  turns.sort((a, b) => a.startTime.localeCompare(b.startTime));
+  return turns;
+}

package/src/sessions/index.ts

@@ -2,5 +2,6 @@ export * from "./addSessionAnnotation";
 export * from "./deleteSession";
 export * from "./deleteSessions";
 export * from "./getSession";
+export * from "./getSessionTurns";
 export * from "./listSessions";
 export * from "./logSessionAnnotations";