@arizeai/phoenix-client 6.4.0 → 6.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arizeai/phoenix-client",
-  "version": "6.4.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

@@ -86,6 +86,7 @@ export async function getSessionTurns({
 }: 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) {

package/src/sessions/listSessions.ts

@@ -2,10 +2,12 @@ import invariant from "tiny-invariant";
 
 import type { components } from "../__generated__/api/v1";
 import { createClient } from "../client";
+import { LIST_PROJECT_SESSIONS } from "../constants/serverRequirements";
 import type { ClientFn } from "../types/core";
 import type { ProjectIdentifier } from "../types/projects";
 import { resolveProjectIdentifier } from "../types/projects";
 import type { Session } from "../types/sessions";
+import { ensureServerCapability } from "../utils/serverVersionUtils";
 import { toSession } from "./sessionUtils";
 
 export type ListSessionsParams = ClientFn & ProjectIdentifier;
@@ -17,6 +19,8 @@ const DEFAULT_PAGE_SIZE = 100;
 /**
  * List all sessions for a project with automatic pagination handling.
  *
+ * @requires Phoenix server >= 13.5.0
+ *
  * @example
  * ```ts
  * import { listSessions } from "@arizeai/phoenix-client/sessions";
@@ -34,6 +38,7 @@ export async function listSessions(
   params: ListSessionsParams
 ): Promise<Session[]> {
   const client = params.client || createClient();
+  await ensureServerCapability({ client, requirement: LIST_PROJECT_SESSIONS });
   const projectIdentifier = resolveProjectIdentifier(params);
 
   const sessions: Session[] = [];

package/src/sessions/logSessionAnnotations.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";
 
@@ -28,6 +30,8 @@ export interface LogSessionAnnotationsParams extends ClientFn {
  * @param params - The parameters to log session annotations
  * @returns The IDs of the created or updated annotations
  *
+ * @requires Phoenix server >= 12.0.0
+ *
  * @example
  * ```ts
  * const results = await logSessionAnnotations({
@@ -60,6 +64,7 @@ export async function logSessionAnnotations({
   sync = false,
 }: LogSessionAnnotationsParams): Promise<{ id: string }[]> {
   const client = _client ?? createClient();
+  await ensureServerCapability({ client, requirement: ANNOTATE_SESSIONS });
 
   const { data, error } = await client.POST("/v1/session_annotations", {
     params: {

package/src/spans/getSpans.ts

@@ -1,8 +1,10 @@
 import type { operations } from "../__generated__/api/v1";
 import { createClient } from "../client";
+import { GET_SPANS_TRACE_IDS } from "../constants/serverRequirements";
 import type { ClientFn } from "../types/core";
 import type { ProjectIdentifier } from "../types/projects";
 import { resolveProjectIdentifier } from "../types/projects";
+import { ensureServerCapability } from "../utils/serverVersionUtils";
 
 /**
  * Parameters to get spans from a project using auto-generated types
@@ -44,6 +46,8 @@ export type GetSpansResult = {
  * @param params - The parameters to search for spans
  * @returns A paginated response containing spans and optional next cursor
  *
+ * @requires Phoenix server >= 13.9.0 when filtering by `traceIds`
+ *
  * @example
  * ```ts
  * // Get recent spans from a project
@@ -101,6 +105,9 @@ export async function getSpans({
   parentId,
 }: GetSpansParams): Promise<GetSpansResult> {
   const client = _client ?? createClient();
+  if (traceIds) {
+    await ensureServerCapability({ client, requirement: GET_SPANS_TRACE_IDS });
+  }
   const projectIdentifier = resolveProjectIdentifier(project);
 
   const params: NonNullable<operations["getSpans"]["parameters"]["query"]> = {

package/src/types/semver.ts

@@ -0,0 +1,2 @@
+/** A semantic version triple: [major, minor, patch]. */
+export type SemanticVersion = [number, number, number];

package/src/types/serverRequirements.ts

@@ -0,0 +1,42 @@
+/**
+ * Server capability requirements.
+ *
+ * A "capability" represents a specific server-side feature — such as an HTTP
+ * route or query parameter — that is gated behind a minimum Phoenix server
+ * version.  Each {@link CapabilityRequirement} declares *what* the capability
+ * is and *which* server version first introduced it.
+ *
+ * The client checks these requirements at call time via
+ * {@link ensureServerCapability} so that callers get a clear, actionable error
+ * instead of an opaque 404 or 400 from an older server.
+ */
+
+import type { SemanticVersion } from "./semver";
+
+export interface RouteRequirement {
+  kind: "route";
+  /** HTTP method (e.g. "GET", "POST", "DELETE"). */
+  method: string;
+  /** URL path template (e.g. "/v1/sessions/{session_id}"). */
+  path: string;
+  /** Minimum Phoenix server version as [major, minor, patch]. */
+  minServerVersion: SemanticVersion;
+  /** Optional human-readable description override. */
+  description?: string;
+}
+
+export interface ParameterRequirement {
+  kind: "parameter";
+  /** Name of the query/path/header parameter. */
+  parameterName: string;
+  /** Location of the parameter (e.g. "query", "path", "header"). */
+  parameterLocation: string;
+  /** The route this parameter belongs to (e.g. "GET /v1/projects/{id}/spans"). */
+  route: string;
+  /** Minimum Phoenix server version as [major, minor, patch]. */
+  minServerVersion: SemanticVersion;
+  /** Optional human-readable description override. */
+  description?: string;
+}
+
+export type CapabilityRequirement = RouteRequirement | ParameterRequirement;

package/src/utils/semverUtils.ts

@@ -0,0 +1,66 @@
+/**
+ * Lightweight semantic version utilities.
+ */
+
+import type { SemanticVersion } from "../types/semver";
+
+// ---------------------------------------------------------------------------
+// Parsing
+// ---------------------------------------------------------------------------
+
+/**
+ * Parse a semver-like version string (e.g. "13.14.0") into a triple.
+ * Returns `null` if the string is not a valid version.
+ */
+export function parseSemanticVersion(raw: string): SemanticVersion | null {
+  const parts = raw.trim().split(".");
+  if (parts.length < 3) return null;
+  const major = parseInt(parts[0]!, 10);
+  const minor = parseInt(parts[1]!, 10);
+  const patch = parseInt(parts[2]!, 10);
+  if (
+    Number.isNaN(major) ||
+    Number.isNaN(minor) ||
+    Number.isNaN(patch) ||
+    major < 0 ||
+    minor < 0 ||
+    patch < 0
+  ) {
+    return null;
+  }
+  return [major, minor, patch];
+}
+
+// ---------------------------------------------------------------------------
+// Formatting
+// ---------------------------------------------------------------------------
+
+/**
+ * Format a `SemanticVersion` as a `"major.minor.patch"` string.
+ */
+export function formatVersion(version: SemanticVersion): string {
+  return `${version[0]}.${version[1]}.${version[2]}`;
+}
+
+// ---------------------------------------------------------------------------
+// Comparison
+// ---------------------------------------------------------------------------
+
+/**
+ * Returns `true` if `version` is greater than or equal to `minVersion`.
+ */
+export function satisfiesMinVersion({
+  version,
+  minVersion,
+}: {
+  version: SemanticVersion;
+  minVersion: SemanticVersion;
+}): boolean {
+  const [serverVersionMajor, serverVersionMinor, serverVersionPatch] = version;
+  const [minVersionMajor, minVersionMinor, minVersionPatch] = minVersion;
+  if (serverVersionMajor !== minVersionMajor)
+    return serverVersionMajor > minVersionMajor;
+  if (serverVersionMinor !== minVersionMinor)
+    return serverVersionMinor > minVersionMinor;
+  return serverVersionPatch >= minVersionPatch;
+}