@arizeai/phoenix-client 7.0.0 → 7.1.0

package/docs/datasets.mdx

@@ -3,14 +3,14 @@ title: "Datasets"
 description: "Create and inspect datasets with @arizeai/phoenix-client"
 ---
 
-Datasets are the foundation for experiment runs. The dataset helpers cover creation, idempotent creation, record inspection, and example appends.
+Datasets are the foundation for experiment runs. The dataset helpers cover creation (which upserts by name), record inspection, and example appends.
 
 <section className="hidden" data-agent-context="relevant-source-files" aria-label="Relevant source files">
   <h2>Relevant Source Files</h2>
   <ul>
     <li>
-      <code>src/datasets/createOrGetDataset.ts</code> for the exact return
-      shape of the idempotent helper
+      <code>src/datasets/createDataset.ts</code> for the exact return shape and
+      upsert-by-name behavior
     </li>
   </ul>
 </section>
@@ -33,18 +33,25 @@ const { datasetId } = await createDataset({
 });
 ```
 
-## Reuse Or Append
+## Upsert Or Append
+
+`createDataset()` upserts by name: re-running it with the same name updates the existing dataset to match the examples you pass, and an unchanged upload is a no-op. To keep existing examples and add more, use `appendDatasetExamples()` instead of re-running `createDataset()` with the extra examples.
 
 ```ts
 import {
   appendDatasetExamples,
-  createOrGetDataset,
+  createDataset,
 } from "@arizeai/phoenix-client/datasets";
 
-const dataset = await createOrGetDataset({
+const dataset = await createDataset({
   name: "support-eval",
   description: "Support questions with expected answers",
-  examples: [],
+  examples: [
+    {
+      input: { question: "Where is my order?" },
+      output: { answer: "Use the tracking page in your account." },
+    },
+  ],
 });
 
 await appendDatasetExamples({
@@ -58,7 +65,7 @@ await appendDatasetExamples({
 });
 ```
 
-`createOrGetDataset()` returns `{ datasetId }`, so you can pass that object directly as the dataset selector for append or experiment calls.
+`createDataset()` returns `{ datasetId }`, so you can pass that object directly as the dataset selector for append or experiment calls.
 
 ## Read Back Dataset State
 
@@ -68,7 +75,6 @@ Use `getDataset`, `getDatasetExamples`, and `getDatasetInfo` to inspect datasets
   <h2>Source Map</h2>
   <ul>
     <li><code>src/datasets/createDataset.ts</code></li>
-    <li><code>src/datasets/createOrGetDataset.ts</code></li>
     <li><code>src/datasets/appendDatasetExamples.ts</code></li>
     <li><code>src/datasets/getDataset.ts</code></li>
     <li><code>src/datasets/getDatasetExamples.ts</code></li>

package/docs/overview.mdx

@@ -61,7 +61,7 @@ export PHOENIX_HOST=http://localhost:6006
 export PHOENIX_API_KEY=<your-api-key>
 ```
 
-If you're using Phoenix Cloud, `PHOENIX_HOST` may look like `https://app.phoenix.arize.com/s/my-space`.
+For a remote deployment, `PHOENIX_HOST` is that instance's base URL, e.g. `https://your-phoenix.example.com`.
 
 ```ts
 import { createClient } from "@arizeai/phoenix-client";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arizeai/phoenix-client",
-  "version": "7.0.0",
+  "version": "7.1.0",
   "description": "A client for the Phoenix API",
   "keywords": [
     "arize",
@@ -118,8 +118,8 @@
     "openapi-typescript": "^7.13.0",
     "tsx": "^4.23.1",
     "vitest": "^4.1.10",
-    "@arizeai/phoenix-evals": "2.0.0",
-    "@arizeai/phoenix-testing": "0.0.0"
+    "@arizeai/phoenix-testing": "0.0.0",
+    "@arizeai/phoenix-evals": "2.1.0"
   },
   "peerDependencies": {
     "@anthropic-ai/sdk": "^0.35.0",

package/src/__generated__/api/v1.ts

@@ -2417,6 +2417,14 @@ export interface components {
              * Format: date-time
              */
             updated_at: string;
+            source?: components["schemas"]["DatasetExampleSource"] | null;
+        };
+        /** DatasetExampleSource */
+        DatasetExampleSource: {
+            /** Span Id */
+            span_id: string;
+            /** Span Node Id */
+            span_node_id: string;
         };
         /** DatasetLabel */
         DatasetLabel: {
@@ -8628,6 +8636,8 @@ export interface operations {
                 end_time?: string | null;
                 /** @description Filter by one or more trace IDs */
                 trace_id?: string[] | null;
+                /** @description Filter by one or more span IDs */
+                span_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) */
@@ -8697,6 +8707,8 @@ export interface operations {
                 end_time?: string | null;
                 /** @description Filter by one or more trace IDs */
                 trace_id?: string[] | null;
+                /** @description Filter by one or more span IDs */
+                span_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) */

package/src/constants/serverRequirements.ts

@@ -75,6 +75,14 @@ export const GET_SPANS_TRACE_IDS: ParameterRequirement = {
   minServerVersion: [13, 9, 0],
 };
 
+export const GET_SPANS_SPAN_IDS: ParameterRequirement = {
+  kind: "parameter",
+  parameterName: "span_id",
+  parameterLocation: "query",
+  route: "GET /v1/projects/{id}/spans",
+  minServerVersion: [19, 6, 0],
+};
+
 export const GET_SPANS_FILTERS: ParameterRequirement = {
   kind: "parameter",
   parameterName: "span_kind",
@@ -145,6 +153,7 @@ export const ALL_REQUIREMENTS: readonly CapabilityRequirement[] = [
   ADD_TRACE_NOTE,
   ADD_SESSION_NOTE,
   GET_SPANS_TRACE_IDS,
+  GET_SPANS_SPAN_IDS,
   GET_SPANS_FILTERS,
   GET_SPANS_BY_ATTRIBUTE,
   LIST_PROJECT_TRACES,

package/src/experiments/resumeEvaluation.ts

@@ -522,7 +522,7 @@ export async function resumeEvaluation({
     }
 
     // Start concurrent execution
-    // Wrap in try-finally to ensure channel is always closed, even if Promise.all throws
+    // Wrap in try-finally to ensure channel is always closed, even if a task throws
     let executionError: Error | null = null;
     try {
       const producerTask = fetchIncompleteEvaluations();
@@ -530,31 +530,61 @@ export async function resumeEvaluation({
         processEvaluationsFromChannel()
       );
 
-      // Wait for producer and all workers to finish
-      await Promise.all([producerTask, ...workerTasks]);
-    } catch (error) {
-      // Classify and handle errors based on their nature
-      const err = error instanceof Error ? error : new Error(String(error));
-
-      // Always surface producer/infrastructure errors
-      if (error instanceof EvaluationFetchError) {
-        // Producer failed - this is ALWAYS critical regardless of stopOnFirstError
-        logger.error(`Critical: Failed to fetch evaluations from server`);
-        executionError = err;
-      } else if (error instanceof ChannelError && signal.aborted) {
-        // Channel closed due to intentional abort - wrap in semantic error
-        executionError = new EvaluationAbortedError(
-          "Evaluation stopped due to error in concurrent evaluator",
-          err
+      // Wait for the producer AND every worker to settle before continuing.
+      // Using allSettled (rather than Promise.all) is important: on the first
+      // worker error, Promise.all rejects immediately while the remaining
+      // workers keep running detached, logging and hitting the API after this
+      // function has already returned/thrown. Draining all tasks guarantees no
+      // background work outlives the call (and avoids teardown races in tests
+      // where late console output is flushed after the test completes).
+      const settled = await Promise.allSettled([producerTask, ...workerTasks]);
+      const rejections = settled
+        .filter(
+          (result): result is PromiseRejectedResult =>
+            result.status === "rejected"
+        )
+        .map((result) => result.reason);
+
+      if (rejections.length > 0) {
+        // Classify and handle errors based on their nature. When multiple tasks
+        // reject, prefer the most meaningful error over incidental fallout
+        // (e.g. a ChannelError raised in a blocked worker when the channel
+        // closes on abort).
+        const fetchError = rejections.find(
+          (reason) => reason instanceof EvaluationFetchError
         );
-      } else if (stopOnFirstError) {
-        // Worker error in stopOnFirstError mode - already logged by worker
-        executionError = err;
-      } else {
-        // Unexpected error (not from worker, not from producer fetch)
-        // This could be a bug in our code or infrastructure failure
-        logger.error(`Unexpected error during evaluation: ${err.message}`);
-        executionError = err;
+        const workerError = rejections.find(
+          (reason) =>
+            reason instanceof Error &&
+            !(reason instanceof EvaluationFetchError) &&
+            !(reason instanceof ChannelError)
+        );
+        const channelError = rejections.find(
+          (reason) => reason instanceof ChannelError
+        );
+
+        if (fetchError) {
+          // Producer failed - this is ALWAYS critical regardless of stopOnFirstError
+          logger.error(`Critical: Failed to fetch evaluations from server`);
+          executionError = fetchError;
+        } else if (workerError) {
+          // Worker error in stopOnFirstError mode - already logged by worker
+          executionError = workerError;
+        } else if (channelError && signal.aborted) {
+          // Channel closed due to intentional abort - wrap in semantic error
+          executionError = new EvaluationAbortedError(
+            "Evaluation stopped due to error in concurrent evaluator",
+            channelError
+          );
+        } else {
+          // Unexpected error (not from worker, not from producer fetch)
+          // This could be a bug in our code or infrastructure failure
+          const reason = rejections[0];
+          const err =
+            reason instanceof Error ? reason : new Error(String(reason));
+          logger.error(`Unexpected error during evaluation: ${err.message}`);
+          executionError = err;
+        }
       }
     } finally {
       // Ensure channel is closed even if there are unexpected errors

package/src/experiments/resumeExperiment.ts

@@ -489,7 +489,7 @@ export async function resumeExperiment({
     }
 
     // Start concurrent execution
-    // Wrap in try-finally to ensure channel is always closed, even if Promise.all throws
+    // Wrap in try-finally to ensure channel is always closed, even if a task throws
     let executionError: Error | null = null;
     try {
       const producerTask = fetchIncompleteRuns();
@@ -497,31 +497,63 @@ export async function resumeExperiment({
         processTasksFromChannel()
       );
 
-      // Wait for producer and all workers to finish
-      await Promise.all([producerTask, ...workerTasks]);
-    } catch (error) {
-      // Classify and handle errors based on their nature
-      const err = error instanceof Error ? error : new Error(String(error));
-
-      // Always surface producer/infrastructure errors
-      if (error instanceof TaskFetchError) {
-        // Producer failed - this is ALWAYS critical regardless of stopOnFirstError
-        logger.error(`Critical: Failed to fetch incomplete runs from server`);
-        executionError = err;
-      } else if (error instanceof ChannelError && signal.aborted) {
-        // Channel closed due to intentional abort - wrap in semantic error
-        executionError = new TaskAbortedError(
-          "Task execution stopped due to error in concurrent worker",
-          err
+      // Wait for the producer AND every worker to settle before continuing.
+      // Using allSettled (rather than Promise.all) is important: on the first
+      // worker error, Promise.all rejects immediately while the remaining
+      // workers keep running detached, logging and hitting the API after this
+      // function has already returned/thrown. Draining all tasks guarantees no
+      // background work outlives the call (and avoids teardown races in tests
+      // where late console output is flushed after the test completes).
+      const settled = await Promise.allSettled([producerTask, ...workerTasks]);
+      const rejections = settled
+        .filter(
+          (result): result is PromiseRejectedResult =>
+            result.status === "rejected"
+        )
+        .map((result) => result.reason);
+
+      if (rejections.length > 0) {
+        // Classify and handle errors based on their nature. When multiple tasks
+        // reject, prefer the most meaningful error over incidental fallout
+        // (e.g. a ChannelError raised in a blocked worker when the channel
+        // closes on abort).
+        const fetchError = rejections.find(
+          (reason) => reason instanceof TaskFetchError
         );
-      } else if (stopOnFirstError) {
-        // Worker error in stopOnFirstError mode - already logged by worker
-        executionError = err;
-      } else {
-        // Unexpected error (not from worker, not from producer fetch)
-        // This could be a bug in our code or infrastructure failure
-        logger.error(`Unexpected error during task execution: ${err.message}`);
-        executionError = err;
+        const taskError = rejections.find(
+          (reason) =>
+            reason instanceof Error &&
+            !(reason instanceof TaskFetchError) &&
+            !(reason instanceof ChannelError)
+        );
+        const channelError = rejections.find(
+          (reason) => reason instanceof ChannelError
+        );
+
+        if (fetchError) {
+          // Producer failed - this is ALWAYS critical regardless of stopOnFirstError
+          logger.error(`Critical: Failed to fetch incomplete runs from server`);
+          executionError = fetchError;
+        } else if (taskError) {
+          // Worker error in stopOnFirstError mode - already logged by worker
+          executionError = taskError;
+        } else if (channelError && signal.aborted) {
+          // Channel closed due to intentional abort - wrap in semantic error
+          executionError = new TaskAbortedError(
+            "Task execution stopped due to error in concurrent worker",
+            channelError
+          );
+        } else {
+          // Unexpected error (not from worker, not from producer fetch)
+          // This could be a bug in our code or infrastructure failure
+          const reason = rejections[0];
+          const err =
+            reason instanceof Error ? reason : new Error(String(reason));
+          logger.error(
+            `Unexpected error during task execution: ${err.message}`
+          );
+          executionError = err;
+        }
       }
     } finally {
       // Ensure channel is closed even if there are unexpected errors

package/src/spans/getSpans.ts

@@ -3,6 +3,7 @@ import { createClient } from "../client";
 import {
   GET_SPANS_BY_ATTRIBUTE,
   GET_SPANS_FILTERS,
+  GET_SPANS_SPAN_IDS,
   GET_SPANS_TRACE_IDS,
 } from "../constants/serverRequirements";
 import type { ClientFn } from "../types/core";
@@ -59,6 +60,8 @@ export interface GetSpansParams extends ClientFn {
   limit?: number;
   /** Filter spans by one or more trace IDs */
   traceIds?: string[] | null;
+  /** Filter spans by one or more span IDs */
+  spanIds?: 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) */
@@ -96,6 +99,7 @@ export type GetSpansResult = {
  * @returns A paginated response containing spans and optional next cursor
  *
  * @requires Phoenix server >= 13.9.0 when filtering by `traceIds`
+ * @requires Phoenix server >= 19.6.0 when filtering by `spanIds`
  * @requires Phoenix server >= 14.9.0 when filtering by `attributes`
  *
  * @example
@@ -125,6 +129,13 @@ export type GetSpansResult = {
  *   traceIds: ["trace-abc-123", "trace-def-456"],
  * });
  *
+ * // Get specific spans by span ID (requires Phoenix server >= 19.6.0)
+ * const result = await getSpans({
+ *   client,
+ *   project: { projectName: "my-project" },
+ *   spanIds: ["span-abc-123", "span-def-456"],
+ * });
+ *
  * // Paginate through results
  * let cursor: string | undefined;
  * do {
@@ -152,6 +163,7 @@ export async function getSpans({
   startTime,
   endTime,
   traceIds,
+  spanIds,
   parentId,
   name,
   spanKind,
@@ -168,6 +180,9 @@ export async function getSpans({
   if (traceIds) {
     await ensureServerCapability({ client, requirement: GET_SPANS_TRACE_IDS });
   }
+  if (spanIds) {
+    await ensureServerCapability({ client, requirement: GET_SPANS_SPAN_IDS });
+  }
   if (name != null || spanKind != null || statusCode != null) {
     await ensureServerCapability({ client, requirement: GET_SPANS_FILTERS });
   }
@@ -200,6 +215,10 @@ export async function getSpans({
     params.trace_id = traceIds;
   }
 
+  if (spanIds) {
+    params.span_id = spanIds;
+  }
+
   if (parentId !== undefined) {
     params.parent_id = parentId === null ? "null" : parentId;
   }