@arizeai/phoenix-client 2.4.0 → 3.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arizeai/phoenix-client",
-  "version": "2.4.0",
+  "version": "3.1.0",
   "description": "A client for the Phoenix API",
   "main": "dist/src/index.js",
   "module": "dist/esm/index.js",
@@ -85,7 +85,7 @@
   "optionalDependencies": {
     "@anthropic-ai/sdk": "^0.35.0",
     "ai": "^4.1.47",
-    "openai": "^4.86.1"
+    "openai": "^5.12.1"
   },
   "scripts": {
     "clean": "rimraf dist",

package/src/__generated__/api/v1.ts

@@ -318,6 +318,30 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/v1/traces/{trace_identifier}": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        post?: never;
+        /**
+         * Delete a trace by identifier
+         * @description Delete an entire trace by its identifier. The identifier can be either:
+         *     1. A Relay node ID (base64-encoded)
+         *     2. An OpenTelemetry trace_id (hex string)
+         *
+         *     This will permanently remove all spans in the trace and their associated data.
+         */
+        delete: operations["deleteTrace"];
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/v1/projects/{project_identifier}/spans/otlpv1": {
         parameters: {
             query?: never;
@@ -379,6 +403,38 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/v1/spans/{span_identifier}": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        post?: never;
+        /**
+         * Delete a span by span_identifier
+         * @description Delete a single span by identifier.
+         *
+         *             **Important**: This operation deletes ONLY the specified span itself and does NOT
+         *             delete its descendants/children. All child spans will remain in the trace and
+         *             become orphaned (their parent_id will point to a non-existent span).
+         *
+         *             Behavior:
+         *             - Deletes only the target span (preserves all descendant spans)
+         *             - If this was the last span in the trace, the trace record is also deleted
+         *             - If the deleted span had a parent, its cumulative metrics (error count, token counts)
+         *               are subtracted from all ancestor spans in the chain
+         *
+         *             **Note**: This operation is irreversible and may create orphaned spans.
+         */
+        delete: operations["deleteSpan"];
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/v1/evaluations": {
         parameters: {
             query?: never;
@@ -882,6 +938,8 @@ export interface components {
              * Format: date-time
              */
             updated_at: string;
+            /** Example Count */
+            example_count: number;
         };
         /** DatasetExample */
         DatasetExample: {
@@ -1634,7 +1692,7 @@ export interface components {
              * Reasoning Effort
              * @enum {string}
              */
-            reasoning_effort?: "low" | "medium" | "high";
+            reasoning_effort?: "minimal" | "low" | "medium" | "high";
         };
         /** PromptChatTemplate */
         PromptChatTemplate: {
@@ -1683,7 +1741,7 @@ export interface components {
              * Reasoning Effort
              * @enum {string}
              */
-            reasoning_effort?: "low" | "medium" | "high";
+            reasoning_effort?: "minimal" | "low" | "medium" | "high";
         };
         /** PromptGoogleInvocationParameters */
         PromptGoogleInvocationParameters: {
@@ -1750,7 +1808,7 @@ export interface components {
              * Reasoning Effort
              * @enum {string}
              */
-            reasoning_effort?: "low" | "medium" | "high";
+            reasoning_effort?: "minimal" | "low" | "medium" | "high";
         };
         /** PromptOpenAIInvocationParameters */
         PromptOpenAIInvocationParameters: {
@@ -1781,7 +1839,7 @@ export interface components {
              * Reasoning Effort
              * @enum {string}
              */
-            reasoning_effort?: "low" | "medium" | "high";
+            reasoning_effort?: "minimal" | "low" | "medium" | "high";
         };
         /** PromptResponseFormatJSONSchema */
         PromptResponseFormatJSONSchema: {
@@ -1974,7 +2032,7 @@ export interface components {
              * Reasoning Effort
              * @enum {string}
              */
-            reasoning_effort?: "low" | "medium" | "high";
+            reasoning_effort?: "minimal" | "low" | "medium" | "high";
         };
         /** Span */
         Span: {
@@ -2293,11 +2351,11 @@ export interface components {
              * @description The end time of the evaluation in ISO format
              */
             end_time: string;
-            /** @description The result of the evaluation */
-            result: components["schemas"]["ExperimentEvaluationResult"];
+            /** @description The result of the evaluation. Either result or error must be provided. */
+            result?: components["schemas"]["ExperimentEvaluationResult"] | null;
             /**
              * Error
-             * @description Optional error message if the evaluation encountered an error
+             * @description Error message if the evaluation encountered an error. Either result or error must be provided.
              */
             error?: string | null;
             /**
@@ -3457,6 +3515,54 @@ export interface operations {
             };
         };
     };
+    deleteTrace: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                /** @description The trace identifier: either a relay GlobalID or OpenTelemetry trace_id */
+                trace_identifier: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Successful Response */
+            204: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description Forbidden */
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "text/plain": string;
+                };
+            };
+            /** @description Not Found */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "text/plain": string;
+                };
+            };
+            /** @description Validation Error */
+            422: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["HTTPValidationError"];
+                };
+            };
+        };
+    };
     spanSearch: {
         parameters: {
             query?: {
@@ -3692,6 +3798,54 @@ export interface operations {
             };
         };
     };
+    deleteSpan: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                /** @description The span identifier: either a relay GlobalID or OpenTelemetry span_id */
+                span_identifier: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Successful Response */
+            204: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description Forbidden */
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "text/plain": string;
+                };
+            };
+            /** @description Not Found */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "text/plain": string;
+                };
+            };
+            /** @description Validation Error */
+            422: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["HTTPValidationError"];
+                };
+            };
+        };
+    };
     getEvaluations: {
         parameters: {
             query?: {

package/src/experiments/instrumention.ts

@@ -1,10 +1,16 @@
 import { diag, DiagConsoleLogger, DiagLogLevel } from "@opentelemetry/api";
 import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-proto";
 import { resourceFromAttributes } from "@opentelemetry/resources";
-import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";
+import {
+  NodeTracerProvider,
+  SpanProcessor,
+} from "@opentelemetry/sdk-trace-node";
 import { SEMRESATTRS_PROJECT_NAME } from "@arizeai/openinference-semantic-conventions";
 import { HeadersOptions } from "openapi-fetch";
-import { OpenInferenceSimpleSpanProcessor } from "@arizeai/openinference-vercel";
+import {
+  OpenInferenceBatchSpanProcessor,
+  OpenInferenceSimpleSpanProcessor,
+} from "@arizeai/openinference-vercel";
 
 /**
  * Creates a provider that exports traces to Phoenix.
@@ -13,9 +19,15 @@ export function createProvider({
   projectName,
   baseUrl,
   headers,
+  useBatchSpanProcessor = true,
 }: {
   projectName: string;
   headers: HeadersOptions;
+  /**
+   * Whether to use batching for the span processor.
+   * @default true
+   */
+  useBatchSpanProcessor: boolean;
   /**
    * The base URL of the Phoenix. Doesn't include the /v1/traces path.
    */
@@ -23,22 +35,23 @@ export function createProvider({
 }) {
   diag.setLogger(new DiagConsoleLogger(), DiagLogLevel.ERROR);
 
+  const exporter = new OTLPTraceExporter({
+    url: `${baseUrl}/v1/traces`,
+    headers: Array.isArray(headers) ? Object.fromEntries(headers) : headers,
+  });
+
+  let spanProcessor: SpanProcessor;
+  if (useBatchSpanProcessor) {
+    spanProcessor = new OpenInferenceBatchSpanProcessor({ exporter });
+  } else {
+    spanProcessor = new OpenInferenceSimpleSpanProcessor({ exporter });
+  }
+
   const provider = new NodeTracerProvider({
     resource: resourceFromAttributes({
       [SEMRESATTRS_PROJECT_NAME]: projectName,
     }),
-    spanProcessors: [
-      // We opt to use the OpenInferenceSimpleSpanProcessor instead of the SimpleSpanProcessor
-      // Since so many AI applications use the AI SDK
-      new OpenInferenceSimpleSpanProcessor({
-        exporter: new OTLPTraceExporter({
-          url: `${baseUrl}/v1/traces`,
-          headers: Array.isArray(headers)
-            ? Object.fromEntries(headers)
-            : headers,
-        }),
-      }),
-    ],
+    spanProcessors: [spanProcessor],
   });
 
   return provider;

package/src/experiments/runExperiment.ts

@@ -94,6 +94,11 @@ export type RunExperimentParams = ClientFn & {
    * @default true
    */
   setGlobalTracerProvider?: boolean;
+  /**
+   * Whether to use batching for the span processor.
+   * @default true
+   */
+  useBatchSpanProcessor?: boolean;
 };
 
 /**
@@ -141,6 +146,7 @@ export async function runExperiment({
   concurrency = 5,
   dryRun = false,
   setGlobalTracerProvider = true,
+  useBatchSpanProcessor = true,
 }: RunExperimentParams): Promise<RanExperiment> {
   let provider: NodeTracerProvider | undefined;
   const isDryRun = typeof dryRun === "number" || dryRun === true;
@@ -201,6 +207,7 @@ export async function runExperiment({
       projectName,
       baseUrl,
       headers: client.config.headers ?? {},
+      useBatchSpanProcessor,
     });
     // Register the provider
     if (setGlobalTracerProvider) {
@@ -276,6 +283,7 @@ export async function runExperiment({
     concurrency,
     dryRun,
     setGlobalTracerProvider,
+    useBatchSpanProcessor,
   });
   ranExperiment.evaluationRuns = evaluationRuns;
 
@@ -421,6 +429,7 @@ export async function evaluateExperiment({
   concurrency = 5,
   dryRun = false,
   setGlobalTracerProvider = true,
+  useBatchSpanProcessor = true,
 }: {
   /**
    * The experiment to evaluate
@@ -445,6 +454,11 @@ export async function evaluateExperiment({
    * @default true
    */
   setGlobalTracerProvider?: boolean;
+  /**
+   * Whether to use batching for the span processor.
+   * @default true
+   */
+  useBatchSpanProcessor?: boolean;
 }): Promise<RanExperiment> {
   const isDryRun = typeof dryRun === "number" || dryRun === true;
   const client = _client ?? createClient();
@@ -459,6 +473,7 @@ export async function evaluateExperiment({
       projectName: "evaluators",
       baseUrl,
       headers: client.config.headers ?? {},
+      useBatchSpanProcessor,
     });
     if (setGlobalTracerProvider) {
       provider.register();

package/src/schemas/llm/converters.ts

@@ -38,7 +38,7 @@ export const safelyConvertMessageToProvider = <
     );
     // convert the OpenAI format to the target provider format
     return fromOpenAIMessage({ message: openAIMessage, targetProvider });
-  } catch (e) {
+  } catch {
     return null;
   }
 };
@@ -64,7 +64,7 @@ export const safelyConvertToolCallToProvider = <
       toolCall: openAIToolCall,
       targetProvider,
     });
-  } catch (e) {
+  } catch {
     return null;
   }
 };
@@ -90,7 +90,7 @@ export const safelyConvertToolDefinitionToProvider = <
       toolDefinition: openAIToolDefinition,
       targetProvider,
     });
-  } catch (e) {
+  } catch {
     return null;
   }
 };
@@ -116,7 +116,7 @@ export const safelyConvertToolChoiceToProvider = <
       toolChoice: openAIToolChoice,
       targetProvider,
     });
-  } catch (e) {
+  } catch {
     return null;
   }
 };

package/src/spans/deleteSpan.ts

@@ -0,0 +1,81 @@
+import { createClient } from "../client";
+import { ClientFn } from "../types/core";
+
+/**
+ * Parameters to delete a span
+ */
+export interface DeleteSpanParams extends ClientFn {
+  /**
+   * The span identifier. Can be either:
+   * - OpenTelemetry span_id (string)
+   * - Phoenix Global ID (string)
+   */
+  spanIdentifier: string;
+}
+
+/**
+ * Delete a single span by identifier.
+ *
+ * **Important**: This operation deletes ONLY the specified span itself and does NOT
+ * delete its descendants/children. All child spans will remain in the trace and
+ * become orphaned (their parent_id will point to a non-existent span).
+ *
+ * Behavior:
+ * - Deletes only the target span (preserves all descendant spans)
+ * - Child spans become orphaned but remain in the database
+ * - Returns successfully if span is found and deleted
+ * - Throws error if span is not found (404) or other errors occur
+ *
+ * @experimental this function is experimental and may change in the future
+ *
+ * @param params - The parameters to delete a span
+ * @returns Promise that resolves when the span is successfully deleted
+ * @throws Error if the span is not found or deletion fails
+ *
+ * @example
+ * ```ts
+ * // Delete by OpenTelemetry span_id
+ * await deleteSpan({
+ *   client,
+ *   spanIdentifier: "abc123def456"
+ * });
+ *
+ * // Delete by Phoenix Global ID
+ * await deleteSpan({
+ *   client,
+ *   spanIdentifier: "U3BhbjoyMzQ1Njc4OQ=="
+ * });
+ * ```
+ */
+export async function deleteSpan({
+  client: _client,
+  spanIdentifier,
+}: DeleteSpanParams): Promise<void> {
+  const client = _client ?? createClient();
+
+  const { error } = await client.DELETE("/v1/spans/{span_identifier}", {
+    params: {
+      path: {
+        span_identifier: spanIdentifier,
+      },
+    },
+  });
+
+  if (error) {
+    const isNotFound =
+      typeof error === "object" &&
+      error !== null &&
+      "status" in error &&
+      error.status === 404;
+    if (isNotFound) {
+      throw new Error(`Span not found: ${spanIdentifier}`);
+    }
+
+    // Extract meaningful error information
+    const errorMessage =
+      typeof error === "object" && error !== null
+        ? JSON.stringify(error, null, 2)
+        : String(error);
+    throw new Error(`Failed to delete span: ${errorMessage}`);
+  }
+}

package/src/spans/index.ts

@@ -2,3 +2,4 @@ export * from "./addSpanAnnotation";
 export * from "./logSpanAnnotations";
 export * from "./getSpans";
 export * from "./getSpanAnnotations";
+export * from "./deleteSpan";