@arizeai/phoenix-client 6.5.0 → 6.5.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arizeai/phoenix-client",
-  "version": "6.5.0",
+  "version": "6.5.2",
   "description": "A client for the Phoenix API",
   "keywords": [
     "arize",
@@ -47,6 +47,10 @@
       "import": "./dist/esm/sessions/index.js",
       "require": "./dist/src/sessions/index.js"
     },
+    "./traces": {
+      "import": "./dist/esm/traces/index.js",
+      "require": "./dist/src/traces/index.js"
+    },
     "./experiments": {
       "import": "./dist/esm/experiments/index.js",
       "require": "./dist/src/experiments/index.js"

package/src/constants/serverRequirements.ts

@@ -61,6 +61,21 @@ export const GET_SPANS_TRACE_IDS: ParameterRequirement = {
   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],
+};
+
+export const LIST_PROJECT_TRACES: RouteRequirement = {
+  kind: "route",
+  method: "GET",
+  path: "/v1/projects/{project_identifier}/traces",
+  minServerVersion: [13, 15, 0],
+};
+
 /**
  * Aggregate list of every known capability requirement.
  *
@@ -74,4 +89,6 @@ export const ALL_REQUIREMENTS: readonly CapabilityRequirement[] = [
   LIST_PROJECT_SESSIONS,
   ANNOTATE_SESSIONS,
   GET_SPANS_TRACE_IDS,
+  GET_SPANS_FILTERS,
+  LIST_PROJECT_TRACES,
 ] 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/spans/getSpans.ts

@@ -1,9 +1,13 @@
 import type { operations } from "../__generated__/api/v1";
 import { createClient } from "../client";
-import { GET_SPANS_TRACE_IDS } from "../constants/serverRequirements";
+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";
 
 /**
@@ -24,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"];
@@ -103,11 +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"]> = {
@@ -135,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/traces/getTraces.ts

@@ -0,0 +1,156 @@
+import type { operations } from "../__generated__/api/v1";
+import { createClient } from "../client";
+import { LIST_PROJECT_TRACES } 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 for getting traces from a project.
+ */
+export interface GetTracesParams extends ClientFn {
+  /** The project to get traces from */
+  project: ProjectIdentifier;
+  /** Inclusive lower bound time. Must be a valid ISO 8601 string or Date object. */
+  startTime?: Date | string | null;
+  /** Exclusive upper bound time. Must be a valid ISO 8601 string or Date object. */
+  endTime?: Date | string | null;
+  /** Sort field */
+  sort?: "start_time" | "latency_ms";
+  /** Sort direction */
+  order?: "asc" | "desc";
+  /** Maximum number of traces to return */
+  limit?: number;
+  /** Pagination cursor (Trace GlobalID) */
+  cursor?: string | null;
+  /** If true, include full span details for each trace */
+  includeSpans?: boolean;
+  /** Filter traces by session identifier(s) (session_id strings or GlobalIDs) */
+  sessionId?: string | string[] | null;
+}
+
+export type GetTracesResponse =
+  operations["listProjectTraces"]["responses"]["200"];
+
+export type GetTracesResult = {
+  traces: GetTracesResponse["content"]["application/json"]["data"];
+  nextCursor: GetTracesResponse["content"]["application/json"]["next_cursor"];
+};
+
+/**
+ * Get traces from a project with filtering and sorting options.
+ *
+ * This method fetches traces from a project with support for time range filtering,
+ * sorting, session filtering, and cursor-based pagination.
+ *
+ * @requires Phoenix server >= 13.15.0
+ *
+ * @param params - The parameters to get traces
+ * @returns A paginated response containing traces and optional next cursor
+ *
+ * @example
+ * ```ts
+ * // Get recent traces from a project
+ * const result = await getTraces({
+ *   client,
+ *   project: { projectName: "my-project" },
+ *   limit: 50,
+ * });
+ *
+ * // Get traces in a time range with spans included
+ * const result = await getTraces({
+ *   client,
+ *   project: { projectName: "my-project" },
+ *   startTime: new Date("2024-01-01"),
+ *   endTime: new Date("2024-01-02"),
+ *   includeSpans: true,
+ * });
+ *
+ * // Paginate through results
+ * let cursor: string | undefined;
+ * do {
+ *   const result = await getTraces({
+ *     client,
+ *     project: { projectName: "my-project" },
+ *     cursor,
+ *     limit: 100,
+ *   });
+ *   result.traces.forEach(trace => {
+ *     console.log(`Trace: ${trace.trace_id}`);
+ *   });
+ *   cursor = result.nextCursor || undefined;
+ * } while (cursor);
+ * ```
+ */
+export async function getTraces({
+  client: _client,
+  project,
+  cursor,
+  limit = 100,
+  startTime,
+  endTime,
+  sort,
+  order,
+  includeSpans,
+  sessionId,
+}: GetTracesParams): Promise<GetTracesResult> {
+  const client = _client ?? createClient();
+  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];
+  }
+
+  const { data, error } = await client.GET(
+    "/v1/projects/{project_identifier}/traces",
+    {
+      params: {
+        path: {
+          project_identifier: projectIdentifier,
+        },
+        query: params,
+      },
+    }
+  );
+
+  if (error) throw error;
+  return {
+    traces: data?.data ?? [],
+    nextCursor: data?.next_cursor ?? null,
+  };
+}

package/src/traces/index.ts

@@ -0,0 +1 @@
+export * from "./getTraces";

package/src/types/spans.ts

@@ -0,0 +1,12 @@
+import type { OpenInferenceSpanKind } from "@arizeai/openinference-semantic-conventions";
+
+/**
+ * Status codes for spans.
+ */
+export type SpanStatusCode = "OK" | "ERROR" | "UNSET";
+
+/**
+ * Span kind filter value. Accepts well-known OpenInference span kinds
+ * as well as arbitrary strings for forward-compatibility.
+ */
+export type SpanKindFilter = OpenInferenceSpanKind | (string & {});