@arizeai/phoenix-client 5.6.0 → 5.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arizeai/phoenix-client",
-  "version": "5.6.0",
+  "version": "5.7.0",
   "description": "A client for the Phoenix API",
   "main": "dist/src/index.js",
   "module": "dist/esm/index.js",
@@ -75,7 +75,7 @@
     "tsx": "^4.19.3",
     "typescript": "^5.8.2",
     "vitest": "^4.0.10",
-    "@arizeai/phoenix-evals": "0.6.5"
+    "@arizeai/phoenix-evals": "0.7.0"
   },
   "dependencies": {
     "@arizeai/openinference-semantic-conventions": "^1.1.0",

package/src/__generated__/api/v1.ts

@@ -172,7 +172,7 @@ export interface paths {
         };
         get?: never;
         put?: never;
-        /** Upload dataset from JSON, CSV, or PyArrow */
+        /** Upload dataset from JSON, JSONL, CSV, or PyArrow */
         post: operations["uploadDataset"];
         delete?: never;
         options?: never;
@@ -3616,6 +3616,8 @@ export interface operations {
                     metadata?: Record<string, unknown>[];
                     /** @description Split per example: string, string array, or null */
                     splits?: (string | string[] | null)[];
+                    /** @description Span IDs to link examples back to spans */
+                    span_ids?: (string | null)[];
                 };
                 "multipart/form-data": {
                     /** @enum {string} */
@@ -3627,6 +3629,8 @@ export interface operations {
                     "metadata_keys[]"?: string[];
                     /** @description Column names for auto-assigning examples to splits */
                     "split_keys[]"?: string[];
+                    /** @description Column name for span IDs to link examples back to spans */
+                    span_id_key?: string;
                     /** Format: binary */
                     file: string;
                 };

package/src/datasets/appendDatasetExamples.ts

@@ -24,8 +24,36 @@ export type AppendDatasetExamplesResponse = {
 };
 
 /**
- * Append examples to an existing dataset
+ * Append examples to an existing dataset.
+ *
  * @experimental this interface may change in the future
+ *
+ * @param params - The parameters for appending examples
+ * @param params.client - Optional Phoenix client instance
+ * @param params.dataset - The dataset to append examples to (by ID or name)
+ * @param params.examples - The examples to append. Each example can include:
+ *   - `input`: Required input data for the example
+ *   - `output`: Optional expected output data
+ *   - `metadata`: Optional metadata for the example
+ *   - `splits`: Optional split assignment (string, array of strings, or null)
+ *   - `spanId`: Optional OpenTelemetry span ID to link the example back to its source span
+ *
+ * @returns A promise that resolves to the dataset ID
+ *
+ * @example
+ * ```ts
+ * // Append examples with span links to an existing dataset
+ * const { datasetId } = await appendDatasetExamples({
+ *   dataset: { datasetName: "qa-dataset" },
+ *   examples: [
+ *     {
+ *       input: { question: "What is deep learning?" },
+ *       output: { answer: "Deep learning is..." },
+ *       spanId: "span123abc" // Links to the source span
+ *     }
+ *   ]
+ * });
+ * ```
  */
 export async function appendDatasetExamples({
   client: _client,
@@ -39,6 +67,13 @@ export async function appendDatasetExamples({
   const splits = examples.map((example) =>
     example.splits !== undefined ? example.splits : null
   );
+
+  // Extract span IDs from examples, preserving null/undefined as null
+  const spanIds = examples.map((example) => example?.spanId ?? null);
+
+  // Only include span_ids in the request if at least one example has a span ID
+  const hasSpanIds = spanIds.some((id) => id !== null);
+
   let datasetName: string;
   if ("datasetName" in dataset) {
     datasetName = dataset.datasetName;
@@ -62,6 +97,7 @@ export async function appendDatasetExamples({
       outputs,
       metadata,
       splits,
+      ...(hasSpanIds ? { span_ids: spanIds } : {}),
     },
   });
   invariant(appendResponse.data?.data, "Failed to append dataset examples");

package/src/datasets/createDataset.ts

@@ -24,8 +24,43 @@ export type CreateDatasetResponse = {
 };
 
 /**
- * Create a new dataset
+ * Create a new dataset with examples.
+ *
  * @experimental this interface may change in the future
+ *
+ * @param params - The parameters for creating the dataset
+ * @param params.client - Optional Phoenix client instance
+ * @param params.name - The name of the dataset
+ * @param params.description - The description of the dataset
+ * @param params.examples - The examples to create in the dataset. Each example can include:
+ *   - `input`: Required input data for the example
+ *   - `output`: Optional expected output data
+ *   - `metadata`: Optional metadata for the example
+ *   - `splits`: Optional split assignment (string, array of strings, or null)
+ *   - `spanId`: Optional OpenTelemetry span ID to link the example back to its source span
+ *
+ * @returns A promise that resolves to the created dataset ID
+ *
+ * @example
+ * ```ts
+ * // Create a dataset with span links
+ * const { datasetId } = await createDataset({
+ *   name: "qa-dataset",
+ *   description: "Q&A examples from traces",
+ *   examples: [
+ *     {
+ *       input: { question: "What is AI?" },
+ *       output: { answer: "Artificial Intelligence is..." },
+ *       spanId: "abc123def456" // Links to the source span
+ *     },
+ *     {
+ *       input: { question: "Explain ML" },
+ *       output: { answer: "Machine Learning is..." },
+ *       spanId: "789ghi012jkl"
+ *     }
+ *   ]
+ * });
+ * ```
  */
 export async function createDataset({
   client: _client,
@@ -40,6 +75,13 @@ export async function createDataset({
   const splits = examples.map((example) =>
     example?.splits !== undefined ? example.splits : null
   );
+
+  // Extract span IDs from examples, preserving null/undefined as null
+  const spanIds = examples.map((example) => example?.spanId ?? null);
+
+  // Only include span_ids in the request if at least one example has a span ID
+  const hasSpanIds = spanIds.some((id) => id !== null);
+
   const createDatasetResponse = await client.POST("/v1/datasets/upload", {
     params: {
       query: {
@@ -55,6 +97,7 @@ export async function createDataset({
       outputs,
       metadata,
       splits,
+      ...(hasSpanIds ? { span_ids: spanIds } : {}),
     },
   });
   invariant(createDatasetResponse.data?.data, "Failed to create dataset");

package/src/experiments/runExperiment.ts

@@ -48,7 +48,6 @@ import {
 import { getExperimentInfo } from "./getExperimentInfo";
 import { getExperimentEvaluators } from "./helpers";
 
-import assert from "assert";
 import { queue } from "async";
 import invariant from "tiny-invariant";
 
@@ -181,7 +180,7 @@ export async function runExperiment({
   diagLogLevel,
 }: RunExperimentParams): Promise<RanExperiment> {
   // Validation
-  assert(
+  invariant(
     isValidRepetitionParam(repetitions),
     "repetitions must be an integer greater than 0"
   );
@@ -416,7 +415,7 @@ function runTaskWithExamples({
   repetitions?: number;
 }): Promise<void> {
   // Validate the input
-  assert(
+  invariant(
     isValidRepetitionParam(repetitions),
     "repetitions must be an integer greater than 0"
   );

package/src/types/datasets.ts

@@ -52,6 +52,12 @@ export interface Example {
    * - null for no split assignment
    */
   splits?: string | string[] | null;
+  /**
+   * OpenTelemetry span ID to link this example back to its source span.
+   * When provided, the dataset example will be associated with the span
+   * in the Phoenix UI, enabling traceability from datasets back to traces.
+   */
+  spanId?: string | null;
 }
 
 /**