@arizeai/phoenix-client 7.9.0 → 7.11.0

package/docs/traces.mdx

@@ -29,7 +29,7 @@ The traces module provides trace retrieval, project transfer, and trace-level an
 
 ## Retrieve Traces
 
-Use `getTraces` when you want trace-centric pagination by project, optional inline spans, or filtering by session.
+Use `getTraces` when you want trace-centric pagination by project, optional inline spans, or filtering by session, error status, or latency.
 
 ```ts
 import { getTraces } from "@arizeai/phoenix-client/traces";
@@ -60,6 +60,18 @@ console.log(result.nextCursor);
 - `cursor`
 - `includeSpans`
 - `sessionId`
+- `error`
+- `minLatencyMs`
+- `maxLatencyMs`
+
+```ts
+// Slow traces that contain at least one errored span
+const slowFailures = await getTraces({
+  project: { projectName: "support-bot" },
+  error: true,
+  minLatencyMs: 1000,
+});
+```
 
 ### Notes
 
@@ -67,6 +79,7 @@ console.log(result.nextCursor);
 - Use the returned `nextCursor` to continue pagination
 - Set `includeSpans` when you need a trace-centric fetch that also contains span details
 - `project` accepts `{ project }`, `{ projectId }`, or `{ projectName }`
+- `error`, `minLatencyMs`, and `maxLatencyMs` require Phoenix server >= 20.8.0; `error: false` selects traces with no errored spans
 
 ## Move Traces To Another Project
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arizeai/phoenix-client",
-  "version": "7.9.0",
+  "version": "7.11.0",
   "description": "A client for the Phoenix API",
   "keywords": [
     "arize",
@@ -103,30 +103,30 @@
     }
   },
   "dependencies": {
-    "@arizeai/openinference-semantic-conventions": "^2.7.0",
+    "@arizeai/openinference-semantic-conventions": "^2.9.0",
     "@arizeai/phoenix-config": "0.5.0",
     "@arizeai/phoenix-otel": "2.2.0",
     "async": "^3.2.6",
     "openapi-fetch": "^0.17.0",
     "tiny-invariant": "^1.3.3",
-    "zod": "^4.4.3"
+    "zod": "^4.5.4"
   },
   "devDependencies": {
-    "@ai-sdk/openai": "^4.0.46",
-    "@ai-sdk/otel": "^1.0.77",
+    "@ai-sdk/openai": "^4.0.60",
+    "@ai-sdk/otel": "^1.0.93",
     "@anthropic-ai/sdk": "^0.111.0",
-    "@arizeai/phoenix-evals": "2.4.0",
+    "@arizeai/phoenix-evals": "2.5.0",
     "@arizeai/phoenix-testing": "0.0.0",
     "@opentelemetry/api": "^1.9.1",
-    "@opentelemetry/sdk-trace-node": "^2.10.0",
+    "@opentelemetry/sdk-trace-node": "^2.11.0",
     "@types/async": "^3.2.25",
-    "@types/node": "^26.2.0",
-    "ai": "^7.0.77",
+    "@types/node": "^26.4.1",
+    "ai": "^7.0.93",
     "dotenv": "^17.4.2",
-    "jest": "^30.4.2",
+    "jest": "^30.5.1",
     "openai": "^6.49.0",
     "openapi-typescript": "^7.13.0",
-    "tsx": "^4.23.12",
+    "tsx": "^4.23.13",
     "vitest": "^5.0.0"
   },
   "peerDependencies": {

package/src/__generated__/api/v1.ts

@@ -5296,6 +5296,13 @@ export interface components {
         PromptVersion: {
             /** Description */
             description?: string | null;
+            /**
+             * Metadata
+             * @description Arbitrary JSON metadata for the prompt version.
+             */
+            metadata?: {
+                [key: string]: unknown;
+            };
             model_provider: components["schemas"]["ModelProvider"];
             /** Model Name */
             model_name: string;
@@ -5315,6 +5322,13 @@ export interface components {
         PromptVersionData: {
             /** Description */
             description?: string | null;
+            /**
+             * Metadata
+             * @description Arbitrary JSON metadata for the prompt version.
+             */
+            metadata?: {
+                [key: string]: unknown;
+            };
             model_provider: components["schemas"]["ModelProvider"];
             /** Model Name */
             model_name: string;

package/src/constants/serverRequirements.ts

@@ -98,6 +98,16 @@ export const LIST_PROJECT_TRACES: RouteRequirement = {
   minServerVersion: [13, 15, 0],
 };
 
+export const GET_TRACES_FILTERS: ParameterRequirement = {
+  kind: "parameter",
+  parameterName: "error",
+  parameterLocation: "query",
+  route: "GET /v1/projects/{id}/traces",
+  minServerVersion: [20, 8, 0],
+  description:
+    "The 'error', 'min_latency_ms', and 'max_latency_ms' query parameters on GET /v1/projects/{id}/traces",
+};
+
 export const TRANSFER_TRACES: RouteRequirement = {
   kind: "route",
   method: "POST",
@@ -234,6 +244,7 @@ export const ALL_REQUIREMENTS: readonly CapabilityRequirement[] = [
   GET_SPANS_FILTERS,
   GET_SPANS_BY_ATTRIBUTE,
   LIST_PROJECT_TRACES,
+  GET_TRACES_FILTERS,
   TRANSFER_TRACES,
   DATASET_UPLOAD_EXAMPLE_IDS,
   ADD_TRACE_NOTE_IDENTIFIER,

package/src/prompts/createPrompt.ts

@@ -84,6 +84,11 @@ interface PromptVersionInputBase {
    * The description of the prompt version.
    */
   description?: string;
+  /**
+   * Optional metadata for the prompt version as a JSON object.
+   * @example { "agent": "support", "dependencies": ["retriever"] }
+   */
+  metadata?: PromptVersionData["metadata"];
   /**
    * The name of the model to use for the prompt version.
    */
@@ -165,142 +170,51 @@ export type PromptVersionInput =
 export function promptVersion(params: PromptVersionInput): PromptVersionData {
   const {
     description = "",
+    metadata,
     modelProvider: model_provider,
     modelName: model_name,
     template: templateMessages,
     templateFormat: template_format = "MUSTACHE",
-    invocationParameters: invocation_parameters,
   } = params;
-  switch (model_provider) {
+  return {
+    description,
+    ...(metadata ? { metadata } : {}),
+    model_provider,
+    model_name,
+    template_type: "CHAT",
+    template_format,
+    template: {
+      type: "chat",
+      messages: templateMessages,
+    },
+    invocation_parameters: toInvocationParameters(params),
+  };
+}
+
+function toInvocationParameters(
+  params: PromptVersionInput
+): PromptVersionData["invocation_parameters"] {
+  switch (params.modelProvider) {
     case "OPENAI":
-      return {
-        description,
-        model_provider,
-        model_name,
-        template_type: "CHAT",
-        template_format,
-        template: {
-          type: "chat",
-          messages: templateMessages,
-        },
-        invocation_parameters: {
-          type: "openai",
-          openai: invocation_parameters ?? {},
-        },
-      };
+      return { type: "openai", openai: params.invocationParameters ?? {} };
     case "AZURE_OPENAI":
       return {
-        description,
-        model_provider,
-        model_name,
-        template_type: "CHAT",
-        template_format,
-        template: {
-          type: "chat",
-          messages: templateMessages,
-        },
-        invocation_parameters: {
-          type: "azure_openai",
-          azure_openai: invocation_parameters ?? {},
-        },
+        type: "azure_openai",
+        azure_openai: params.invocationParameters ?? {},
       };
     case "ANTHROPIC":
-      return {
-        description,
-        model_provider,
-        model_name,
-        template_type: "CHAT",
-        template_format,
-        template: {
-          type: "chat",
-          messages: templateMessages,
-        },
-        invocation_parameters: {
-          type: "anthropic",
-          anthropic: invocation_parameters,
-        },
-      };
+      return { type: "anthropic", anthropic: params.invocationParameters };
     case "GOOGLE":
-      return {
-        description,
-        model_provider,
-        model_name,
-        template_type: "CHAT",
-        template_format,
-        template: {
-          type: "chat",
-          messages: templateMessages,
-        },
-        invocation_parameters: {
-          type: "google",
-          google: invocation_parameters ?? {},
-        },
-      };
+      return { type: "google", google: params.invocationParameters ?? {} };
     case "DEEPSEEK":
-      return {
-        description,
-        model_provider,
-        model_name,
-        template_type: "CHAT",
-        template_format,
-        template: {
-          type: "chat",
-          messages: templateMessages,
-        },
-        invocation_parameters: {
-          type: "deepseek",
-          deepseek: invocation_parameters ?? {},
-        },
-      };
+      return { type: "deepseek", deepseek: params.invocationParameters ?? {} };
     case "XAI":
-      return {
-        description,
-        model_provider,
-        model_name,
-        template_type: "CHAT",
-        template_format,
-        template: {
-          type: "chat",
-          messages: templateMessages,
-        },
-        invocation_parameters: {
-          type: "xai",
-          xai: invocation_parameters ?? {},
-        },
-      };
+      return { type: "xai", xai: params.invocationParameters ?? {} };
     case "OLLAMA":
-      return {
-        description,
-        model_provider,
-        model_name,
-        template_type: "CHAT",
-        template_format,
-        template: {
-          type: "chat",
-          messages: templateMessages,
-        },
-        invocation_parameters: {
-          type: "ollama",
-          ollama: invocation_parameters ?? {},
-        },
-      };
+      return { type: "ollama", ollama: params.invocationParameters ?? {} };
     case "AWS":
-      return {
-        description,
-        model_provider,
-        model_name,
-        template_type: "CHAT",
-        template_format,
-        template: {
-          type: "chat",
-          messages: templateMessages,
-        },
-        invocation_parameters: {
-          type: "aws",
-          aws: invocation_parameters ?? {},
-        },
-      };
+      return { type: "aws", aws: params.invocationParameters ?? {} };
     default:
-      return assertUnreachable(model_provider);
+      return assertUnreachable(params);
   }
 }

package/src/traces/getTraces.ts

@@ -1,6 +1,9 @@
 import type { operations } from "../__generated__/api/v1";
 import { createClient } from "../client";
-import { LIST_PROJECT_TRACES } from "../constants/serverRequirements";
+import {
+  GET_TRACES_FILTERS,
+  LIST_PROJECT_TRACES,
+} from "../constants/serverRequirements";
 import type { ClientFn } from "../types/core";
 import type { ProjectIdentifier } from "../types/projects";
 import { resolveProjectIdentifier } from "../types/projects";
@@ -28,6 +31,112 @@ export interface GetTracesParams extends ClientFn {
   includeSpans?: boolean;
   /** Filter traces by session identifier(s) (session_id strings or GlobalIDs) */
   sessionId?: string | string[] | null;
+  /**
+   * Filter by trace error status. `true` returns only traces containing at
+   * least one errored span, `false` only traces with no errored spans.
+   * Omit to leave traces unfiltered by error status.
+   *
+   * @requires Phoenix server >= 20.8.0
+   */
+  error?: boolean | null;
+  /**
+   * Inclusive lower bound on trace latency in milliseconds.
+   *
+   * @requires Phoenix server >= 20.8.0
+   */
+  minLatencyMs?: number | null;
+  /**
+   * Inclusive upper bound on trace latency in milliseconds.
+   *
+   * @requires Phoenix server >= 20.8.0
+   */
+  maxLatencyMs?: number | null;
+}
+
+/**
+ * Reject latency bounds the server would reject (negatives) or that can never
+ * match a trace (an inverted range), so callers get a clear error instead of a
+ * 422 or a silently empty page.
+ */
+function validateLatencyBounds({
+  minLatencyMs,
+  maxLatencyMs,
+}: Pick<GetTracesParams, "minLatencyMs" | "maxLatencyMs">): void {
+  if (minLatencyMs != null && minLatencyMs < 0) {
+    throw new Error(`minLatencyMs must be non-negative, got ${minLatencyMs}`);
+  }
+  if (maxLatencyMs != null && maxLatencyMs < 0) {
+    throw new Error(`maxLatencyMs must be non-negative, got ${maxLatencyMs}`);
+  }
+  if (
+    minLatencyMs != null &&
+    maxLatencyMs != null &&
+    minLatencyMs > maxLatencyMs
+  ) {
+    throw new Error(
+      `minLatencyMs (${minLatencyMs}) must not exceed maxLatencyMs (${maxLatencyMs})`
+    );
+  }
+}
+
+type ListProjectTracesQuery = NonNullable<
+  operations["listProjectTraces"]["parameters"]["query"]
+>;
+
+/**
+ * Translate the camelCase parameters into the endpoint's snake_case query,
+ * omitting anything the caller left unset so the server applies its defaults.
+ */
+function buildQuery({
+  cursor,
+  limit = 100,
+  startTime,
+  endTime,
+  sort,
+  order,
+  includeSpans,
+  sessionId,
+  error,
+  minLatencyMs,
+  maxLatencyMs,
+}: Omit<GetTracesParams, "client" | "project">): ListProjectTracesQuery {
+  const query: ListProjectTracesQuery = { limit };
+  if (cursor) {
+    query.cursor = cursor;
+  }
+  if (startTime) {
+    query.start_time =
+      startTime instanceof Date ? startTime.toISOString() : startTime;
+  }
+  if (endTime) {
+    query.end_time = endTime instanceof Date ? endTime.toISOString() : endTime;
+  }
+  if (sort) {
+    query.sort = sort;
+  }
+  if (order) {
+    query.order = order;
+  }
+  if (includeSpans) {
+    query.include_spans = true;
+  }
+  if (sessionId) {
+    query.session_identifier = Array.isArray(sessionId)
+      ? sessionId
+      : [sessionId];
+  }
+  // `error: false` is a meaningful filter (traces with no errored spans), so
+  // send the parameter whenever it was set rather than only when truthy.
+  if (error != null) {
+    query.error = error;
+  }
+  if (minLatencyMs != null) {
+    query.min_latency_ms = minLatencyMs;
+  }
+  if (maxLatencyMs != null) {
+    query.max_latency_ms = maxLatencyMs;
+  }
+  return query;
 }
 
 export type GetTracesResponse =
@@ -81,60 +190,30 @@ export type GetTracesResult = {
  *   });
  *   cursor = result.nextCursor || undefined;
  * } while (cursor);
+ *
+ * // Only slow traces that errored
+ * const slowFailures = await getTraces({
+ *   client,
+ *   project: { projectName: "my-project" },
+ *   error: true,
+ *   minLatencyMs: 1000,
+ * });
  * ```
  */
 export async function getTraces({
   client: _client,
   project,
-  cursor,
-  limit = 100,
-  startTime,
-  endTime,
-  sort,
-  order,
-  includeSpans,
-  sessionId,
+  ...params
 }: GetTracesParams): Promise<GetTracesResult> {
+  const { error: errorFilter, minLatencyMs, maxLatencyMs } = params;
   const client = _client ?? createClient();
+  validateLatencyBounds({ minLatencyMs, maxLatencyMs });
   await ensureServerCapability({ client, requirement: LIST_PROJECT_TRACES });
-  const projectIdentifier = resolveProjectIdentifier(project);
-
-  const params: NonNullable<
-    operations["listProjectTraces"]["parameters"]["query"]
-  > = {
-    limit,
-  };
-
-  if (cursor) {
-    params.cursor = cursor;
-  }
-
-  if (startTime) {
-    params.start_time =
-      startTime instanceof Date ? startTime.toISOString() : startTime;
-  }
-
-  if (endTime) {
-    params.end_time = endTime instanceof Date ? endTime.toISOString() : endTime;
-  }
-
-  if (sort) {
-    params.sort = sort;
-  }
-
-  if (order) {
-    params.order = order;
-  }
-
-  if (includeSpans) {
-    params.include_spans = true;
-  }
-
-  if (sessionId) {
-    params.session_identifier = Array.isArray(sessionId)
-      ? sessionId
-      : [sessionId];
+  if (errorFilter != null || minLatencyMs != null || maxLatencyMs != null) {
+    await ensureServerCapability({ client, requirement: GET_TRACES_FILTERS });
   }
+  const projectIdentifier = resolveProjectIdentifier(project);
+  const query = buildQuery(params);
 
   const { data, error } = await client.GET(
     "/v1/projects/{project_identifier}/traces",
@@ -143,7 +222,7 @@ export async function getTraces({
         path: {
           project_identifier: projectIdentifier,
         },
-        query: params,
+        query,
       },
     }
   );