@arizeai/phoenix-client 6.4.0 → 6.5.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arizeai/phoenix-client",
-  "version": "6.4.0",
+  "version": "6.5.1",
   "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,86 @@
+/**
+ * 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],
+};
+
+export const GET_SPANS_FILTERS: ParameterRequirement = {
+  kind: "parameter",
+  parameterName: "span_kind",
+  parameterLocation: "query",
+  route: "GET /v1/projects/{id}/spans",
+  minServerVersion: [13, 15, 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,
+  GET_SPANS_FILTERS,
+] as const;

package/src/prompts/sdks/toAI.ts

@@ -1,7 +1,12 @@
 import type { ModelMessage, ToolChoice, ToolSet } from "ai";
 import invariant from "tiny-invariant";
 
-import { safelyConvertMessageToProvider } from "../../schemas/llm/converters";
+import {
+  safelyConvertMessageToProvider,
+  safelyConvertToolChoiceToProvider,
+  safelyConvertToolDefinitionToProvider,
+} from "../../schemas/llm/converters";
+import { findToolDefinitionName } from "../../schemas/llm/utils";
 import { formatPromptMessages } from "../../utils/formatPromptMessages";
 import type { Variables, toSDKParamsBase } from "./types";
 
@@ -62,19 +67,40 @@ export const toAI = <V extends Variables>({
       return vercelAIMessage;
     });
 
-    const tools = undefined;
-    if (prompt.tools?.tools && prompt.tools?.tools.length) {
-      // eslint-disable-next-line no-console
-      console.warn(
-        "Phoenix client does not automatically convert tools to AI SDK tools, please manually convert them."
-      );
+    let tools: ToolSet | undefined;
+    if (prompt.tools?.tools && prompt.tools.tools.length > 0) {
+      const toolsRecord: Record<string, unknown> = {};
+      for (const tool of prompt.tools.tools) {
+        const name = findToolDefinitionName(tool);
+        invariant(name, "Tool definition name is not valid");
+        const converted = safelyConvertToolDefinitionToProvider({
+          toolDefinition: tool,
+          targetProvider: "VERCEL_AI",
+        });
+        invariant(converted, "Tool definition is not valid");
+        toolsRecord[name] = converted;
+      }
+      tools =
+        Object.keys(toolsRecord).length > 0
+          ? (toolsRecord as ToolSet)
+          : undefined;
+    }
+
+    let toolChoice: PartialAIParams["toolChoice"];
+    if (tools && prompt.tools?.tool_choice) {
+      toolChoice =
+        safelyConvertToolChoiceToProvider({
+          toolChoice: prompt.tools.tool_choice,
+          targetProvider: "VERCEL_AI",
+        }) ?? undefined;
     }
 
     // combine base and computed params
     const completionParams: PartialAIParams = {
       ...baseCompletionParams,
       messages,
-      tools,
+      ...(tools !== undefined && { tools }),
+      ...(toolChoice !== undefined && { toolChoice }),
     };
 
     return completionParams;

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,14 @@
 import type { operations } from "../__generated__/api/v1";
 import { createClient } from "../client";
+import {
+  GET_SPANS_FILTERS,
+  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 type { SpanKindFilter, SpanStatusCode } from "../types/spans";
+import { ensureServerCapability } from "../utils/serverVersionUtils";
 
 /**
  * Parameters to get spans from a project using auto-generated types
@@ -22,6 +28,12 @@ export interface GetSpansParams extends ClientFn {
   traceIds?: string[] | null;
   /** Filter by parent span ID. Use `null` or the string `"null"` to get root spans only. */
   parentId?: string | null;
+  /** Filter by span name(s) */
+  name?: string | string[] | null;
+  /** Filter by span kind(s) (LLM, CHAIN, TOOL, RETRIEVER, etc.) */
+  spanKind?: SpanKindFilter | SpanKindFilter[] | null;
+  /** Filter by status code(s) (OK, ERROR, UNSET) */
+  statusCode?: SpanStatusCode | SpanStatusCode[] | null;
 }
 
 export type GetSpansResponse = operations["getSpans"]["responses"]["200"];
@@ -44,6 +56,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
@@ -99,8 +113,17 @@ export async function getSpans({
   endTime,
   traceIds,
   parentId,
+  name,
+  spanKind,
+  statusCode,
 }: GetSpansParams): Promise<GetSpansResult> {
   const client = _client ?? createClient();
+  if (traceIds) {
+    await ensureServerCapability({ client, requirement: GET_SPANS_TRACE_IDS });
+  }
+  if (name != null || spanKind != null || statusCode != null) {
+    await ensureServerCapability({ client, requirement: GET_SPANS_FILTERS });
+  }
   const projectIdentifier = resolveProjectIdentifier(project);
 
   const params: NonNullable<operations["getSpans"]["parameters"]["query"]> = {
@@ -128,6 +151,18 @@ export async function getSpans({
     params.parent_id = parentId === null ? "null" : parentId;
   }
 
+  if (name) {
+    params.name = Array.isArray(name) ? name : [name];
+  }
+
+  if (spanKind) {
+    params.span_kind = Array.isArray(spanKind) ? spanKind : [spanKind];
+  }
+
+  if (statusCode) {
+    params.status_code = Array.isArray(statusCode) ? statusCode : [statusCode];
+  }
+
   const { data, error } = await client.GET(
     "/v1/projects/{project_identifier}/spans",
     {

package/src/spans/index.ts

@@ -4,5 +4,6 @@ export * from "./logSpanAnnotations";
 export * from "./addDocumentAnnotation";
 export * from "./logDocumentAnnotations";
 export * from "./getSpans";
+export type { SpanKindFilter, SpanStatusCode } from "../types/spans";
 export * from "./getSpanAnnotations";
 export * from "./deleteSpan";

package/src/types/semver.ts

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