@arizeai/phoenix-client 6.7.0 → 6.8.1

package/src/datasets/appendDatasetExamples.ts

@@ -1,8 +1,10 @@
 import invariant from "tiny-invariant";
 
 import { createClient } from "../client";
+import { DATASET_UPLOAD_EXAMPLE_IDS } from "../constants/serverRequirements";
 import type { ClientFn } from "../types/core";
 import type { DatasetSelector, Example } from "../types/datasets";
+import { ensureServerCapability } from "../utils/serverVersionUtils";
 import { getDatasetInfo } from "./getDatasetInfo";
 
 export type AppendDatasetExamplesParams = ClientFn & {
@@ -18,8 +20,7 @@ export type AppendDatasetExamplesParams = ClientFn & {
 
 export type AppendDatasetExamplesResponse = {
   datasetId: string;
-  // TODO: respond with the versionId
-  // versionId: string;
+  versionId: string;
 };
 
 /**
@@ -36,19 +37,24 @@ export type AppendDatasetExamplesResponse = {
  *   - `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
+ *   - `id`: Optional stable ID for the example, used to reference or update it later
  *
- * @returns A promise that resolves to the dataset ID
+ * @returns A promise that resolves to the dataset ID and version ID
  *
  * @example
  * ```ts
- * // Append examples with span links to an existing dataset
- * const { datasetId } = await appendDatasetExamples({
+ * const { datasetId, versionId } = 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
+ *     },
+ *     {
+ *       id: "my-stable-id", // Stable ID for referencing this example later
+ *       input: { question: "What is a transformer?" },
+ *       output: { answer: "A transformer is..." },
  *     }
  *   ]
  * });
@@ -73,6 +79,12 @@ export async function appendDatasetExamples({
   // Only include span_ids in the request if at least one example has a span ID
   const hasSpanIds = spanIds.some((id) => id !== null);
 
+  // Extract example IDs from examples, preserving null/undefined as null
+  const exampleIds = examples.map((example) => example?.id ?? null);
+
+  // Only include example_ids in the request if at least one example has an ID
+  const hasExampleIds = exampleIds.some((id) => id !== null);
+
   let datasetName: string;
   if ("datasetName" in dataset) {
     datasetName = dataset.datasetName;
@@ -83,6 +95,12 @@ export async function appendDatasetExamples({
     });
     datasetName = datasetInfo.name;
   }
+  if (hasExampleIds) {
+    await ensureServerCapability({
+      client,
+      requirement: DATASET_UPLOAD_EXAMPLE_IDS,
+    });
+  }
   const appendResponse = await client.POST("/v1/datasets/upload", {
     params: {
       query: {
@@ -97,11 +115,14 @@ export async function appendDatasetExamples({
       metadata,
       splits,
       ...(hasSpanIds ? { span_ids: spanIds } : {}),
+      ...(hasExampleIds ? { example_ids: exampleIds } : {}),
     },
   });
   invariant(appendResponse.data?.data, "Failed to append dataset examples");
   const datasetId = appendResponse.data.data.dataset_id;
+  const versionId = appendResponse.data.data.version_id;
   return {
     datasetId,
+    versionId,
   };
 }

package/src/datasets/createDataset.ts

@@ -1,8 +1,10 @@
 import invariant from "tiny-invariant";
 
 import { createClient } from "../client";
+import { DATASET_UPLOAD_EXAMPLE_IDS } from "../constants/serverRequirements";
 import type { ClientFn } from "../types/core";
 import type { Example } from "../types/datasets";
+import { ensureServerCapability } from "../utils/serverVersionUtils";
 
 export type CreateDatasetParams = ClientFn & {
   /**
@@ -24,7 +26,10 @@ export type CreateDatasetResponse = {
 };
 
 /**
- * Create a new dataset with examples.
+ * Create a dataset with the given examples.
+ *
+ * If a dataset with the same name already exists, it is updated to match the
+ * provided examples. Re-running with the same inputs is a no-op.
  *
  * @experimental this interface may change in the future
  *
@@ -82,27 +87,70 @@ export async function createDataset({
   // 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: {
-        // TODO: parameterize this
-        sync: true,
+  // Extract example IDs from examples, preserving null/undefined as null
+  const exampleIds = examples.map((example) => example?.id ?? null);
+
+  // Only include example_ids in the request if at least one example has an ID
+  const hasExampleIds = exampleIds.some((id) => id !== null);
+
+  const post = (action: "update" | "create") =>
+    client.POST("/v1/datasets/upload", {
+      params: {
+        query: {
+          // TODO: parameterize this
+          sync: true,
+        },
       },
-    },
-    body: {
-      name,
-      description,
-      action: "create",
-      inputs,
-      outputs,
-      metadata,
-      splits,
-      ...(hasSpanIds ? { span_ids: spanIds } : {}),
-    },
-  });
+      body: {
+        name,
+        description,
+        action,
+        inputs,
+        outputs,
+        metadata,
+        splits,
+        ...(hasSpanIds ? { span_ids: spanIds } : {}),
+        ...(hasExampleIds ? { example_ids: exampleIds } : {}),
+      },
+    });
+
+  if (hasExampleIds) {
+    await ensureServerCapability({
+      client,
+      requirement: DATASET_UPLOAD_EXAMPLE_IDS,
+    });
+  }
+  let createDatasetResponse = await post("update");
+  if (isUnsupportedUpdateActionResponse(createDatasetResponse)) {
+    warnUpdateFallback();
+    createDatasetResponse = await post("create");
+  }
   invariant(createDatasetResponse.data?.data, "Failed to create dataset");
   const datasetId = createDatasetResponse.data.data.dataset_id;
   return {
     datasetId,
   };
 }
+
+function isUnsupportedUpdateActionResponse(result: {
+  response?: Response;
+  error?: unknown;
+}): boolean {
+  if (result.response?.status !== 422) return false;
+  const body =
+    typeof result.error === "string"
+      ? result.error
+      : JSON.stringify(result.error ?? "");
+  return (
+    body.includes("Invalid dateset action") ||
+    body.includes("Invalid dataset action")
+  );
+}
+
+function warnUpdateFallback(): void {
+  // eslint-disable-next-line no-console
+  console.warn(
+    "Phoenix server does not support declarative update semantics. " +
+      "Upgrade to Phoenix v15 or later."
+  );
+}

package/src/datasets/getDatasetExamples.ts

@@ -51,9 +51,12 @@ export async function getDatasetExamples({
   const examplesData = response.data.data;
   return {
     versionId: examplesData.version_id,
-    examples: examplesData.examples.map((example) => ({
-      ...example,
-      updatedAt: new Date(example.updated_at),
-    })),
+    examples: examplesData.examples.map(
+      ({ node_id, updated_at, ...example }) => ({
+        ...example,
+        nodeId: node_id,
+        updatedAt: new Date(updated_at),
+      })
+    ),
   };
 }

package/src/datasets/index.ts

@@ -3,4 +3,3 @@ export * from "./getDataset";
 export * from "./getDatasetExamples";
 export * from "./appendDatasetExamples";
 export * from "./getDatasetInfo";
-export * from "./createOrGetDataset";

package/src/experiments/resumeEvaluation.ts

@@ -136,6 +136,7 @@ function buildIncompleteEvaluation(
     },
     datasetExample: {
       id: apiResponse.dataset_example.id,
+      nodeId: apiResponse.dataset_example.node_id,
       input: apiResponse.dataset_example.input,
       output: apiResponse.dataset_example.output ?? null,
       metadata: apiResponse.dataset_example.metadata || {},
@@ -728,7 +729,7 @@ async function runSingleEvaluation({
         ...objectAsAttributes({
           experiment_id: experimentId,
           experiment_run_id: experimentRun.id,
-          dataset_example_id: datasetExample.id,
+          dataset_example_id: datasetExample.nodeId,
         }),
       });
 

package/src/experiments/resumeExperiment.ts

@@ -132,6 +132,7 @@ function buildExampleFromApiResponse(
 ): ExampleWithId {
   return {
     id: apiExample.id,
+    nodeId: apiExample.node_id,
     input: apiExample.input,
     output: apiExample.output || null,
     metadata: apiExample.metadata || {},
@@ -618,7 +619,7 @@ async function recordTaskResult({
         },
       },
       body: {
-        dataset_example_id: example.id,
+        dataset_example_id: example.nodeId,
         repetition_number: repetitionNumber,
         output: output as Record<string, unknown>,
         start_time: startTime.toISOString(),
@@ -694,7 +695,7 @@ async function runSingleTask({
         [SemanticConventions.INPUT_MIME_TYPE]: MimeType.JSON,
         ...objectAsAttributes({
           experiment_id: experimentId,
-          dataset_example_id: example.id,
+          dataset_example_id: example.nodeId,
           repetition_number: repetitionNumber,
         }),
       });

package/src/experiments/runExperiment.ts

@@ -509,7 +509,7 @@ function runTaskWithExamples({
             },
           },
           body: {
-            dataset_example_id: example.id,
+            dataset_example_id: example.nodeId,
             output: thisRun.output,
             repetition_number: repetitionNumber,
             start_time: thisRun.startTime.toISOString(),

package/src/spans/addSpanNote.ts

@@ -27,7 +27,7 @@ export interface AddSpanNoteParams extends ClientFn {
  *
  * Notes are a special type of annotation that allow multiple entries per span
  * (unlike regular annotations which are unique by name and identifier).
- * Each note gets a unique timestamp-based identifier.
+ * Each note gets a unique UUIDv4 identifier.
  *
  * @param params - The parameters to add a span note
  * @returns The ID of the created note annotation

package/src/traces/addTraceNote.ts

@@ -0,0 +1,71 @@
+import { createClient } from "../client";
+import { ADD_TRACE_NOTE } from "../constants/serverRequirements";
+import type { ClientFn } from "../types/core";
+import { ensureServerCapability } from "../utils/serverVersionUtils";
+
+/**
+ * Parameters for a single trace note.
+ */
+export interface TraceNote {
+  /**
+   * The OpenTelemetry trace ID (hex format without 0x prefix).
+   */
+  traceId: string;
+  /**
+   * The note text to add to the trace.
+   */
+  note: string;
+}
+
+/**
+ * Parameters to add a trace note.
+ */
+export interface AddTraceNoteParams extends ClientFn {
+  traceNote: TraceNote;
+}
+
+/**
+ * Add a note to a trace.
+ *
+ * Notes are a special type of annotation that allow multiple entries per trace.
+ * Each note gets a unique timestamp-based identifier.
+ *
+ * @param params - The parameters to add a trace note.
+ * @returns The ID of the created note annotation.
+ *
+ * @example
+ * ```ts
+ * const result = await addTraceNote({
+ *   traceNote: {
+ *     traceId: "abc123",
+ *     note: "Needs review"
+ *   }
+ * });
+ * ```
+ */
+export async function addTraceNote({
+  client: _client,
+  traceNote,
+}: AddTraceNoteParams): Promise<{ id: string }> {
+  const client = _client ?? createClient();
+  await ensureServerCapability({ client, requirement: ADD_TRACE_NOTE });
+
+  const { data, error } = await client.POST("/v1/trace_notes", {
+    body: {
+      data: {
+        trace_id: traceNote.traceId.trim(),
+        note: traceNote.note,
+      },
+    },
+  });
+
+  if (error) {
+    throw new Error(`Failed to add trace note: ${error}`);
+  }
+
+  if (!data?.data) {
+    throw new Error("Failed to add trace note: no data returned");
+  }
+
+  return data.data;
+}

package/src/traces/index.ts

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

package/src/types/datasets.ts

@@ -58,12 +58,21 @@ export interface Example {
    * in the Phoenix UI, enabling traceability from datasets back to traces.
    */
   spanId?: string | null;
+  /**
+   * Optional user-provided ID for this example.
+   * If not provided, the server will generate an ID.
+   */
+  id?: string | null;
 }
 
 /**
  * An example that has been synced to the server
  */
-export interface ExampleWithId extends Example, Node {
+export interface ExampleWithId extends Example {
+  /** The user-provided or server-generated ID for this example. */
+  id: string;
+  /** Server-generated node ID for this example. */
+  nodeId: string;
   updatedAt: Date;
 }
 

package/dist/esm/datasets/createOrGetDataset.d.ts

@@ -1,18 +0,0 @@
-import type { CreateDatasetParams } from "./createDataset.js";
-export type CreateOrGetDatasetParams = CreateDatasetParams;
-export type CreateOrGetDatasetResponse = {
-    datasetId: string;
-};
-/**
- * Given the parameters to create a dataset, this function will either
- * retrieve an existing dataset by name or create a new one with the provided parameters.
- *
- * This is useful in cases where you would like to re-run a pipeline like:
- * - ensure dataset exists
- * - create a task
- * - run experiment
- * - evaluate experiment
- * without having to create a new dataset each time.
- */
-export declare function createOrGetDataset({ name, description, examples, client: _client, }: CreateOrGetDatasetParams): Promise<CreateOrGetDatasetResponse>;
-//# sourceMappingURL=createOrGetDataset.d.ts.map

package/dist/esm/datasets/createOrGetDataset.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"createOrGetDataset.d.ts","sourceRoot":"","sources":["../../../src/datasets/createOrGetDataset.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAI3D,MAAM,MAAM,wBAAwB,GAAG,mBAAmB,CAAC;AAE3D,MAAM,MAAM,0BAA0B,GAAG;IACvC,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF;;;;;;;;;;GAUG;AACH,wBAAsB,kBAAkB,CAAC,EACvC,IAAI,EACJ,WAAW,EACX,QAAQ,EACR,MAAM,EAAE,OAAO,GAChB,EAAE,wBAAwB,GAAG,OAAO,CAAC,0BAA0B,CAAC,CAYhE"}

package/dist/esm/datasets/createOrGetDataset.js

@@ -1,29 +0,0 @@
-import { createClient } from "../client.js";
-import { createDataset } from "./createDataset.js";
-import { getDatasetInfoByName } from "./getDatasetInfoByName.js";
-/**
- * Given the parameters to create a dataset, this function will either
- * retrieve an existing dataset by name or create a new one with the provided parameters.
- *
- * This is useful in cases where you would like to re-run a pipeline like:
- * - ensure dataset exists
- * - create a task
- * - run experiment
- * - evaluate experiment
- * without having to create a new dataset each time.
- */
-export async function createOrGetDataset({ name, description, examples, client: _client, }) {
-    const client = _client || createClient();
-    // start by fetching an existing dataset by name, catching any errors that occur
-    try {
-        const dataset = await getDatasetInfoByName({ datasetName: name, client });
-        return {
-            datasetId: dataset.id,
-        };
-    }
-    catch {
-        // If the dataset doesn't exist, create it, falling back to the error handling inside createDataset
-        return await createDataset({ name, description, examples, client });
-    }
-}
-//# sourceMappingURL=createOrGetDataset.js.map

package/dist/esm/datasets/createOrGetDataset.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"createOrGetDataset.js","sourceRoot":"","sources":["../../../src/datasets/createOrGetDataset.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAEzC,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,OAAO,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAQ9D;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CAAC,EACvC,IAAI,EACJ,WAAW,EACX,QAAQ,EACR,MAAM,EAAE,OAAO,GACU;IACzB,MAAM,MAAM,GAAG,OAAO,IAAI,YAAY,EAAE,CAAC;IACzC,gFAAgF;IAChF,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,MAAM,oBAAoB,CAAC,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;QAC1E,OAAO;YACL,SAAS,EAAE,OAAO,CAAC,EAAE;SACtB,CAAC;IACJ,CAAC;IAAC,MAAM,CAAC;QACP,mGAAmG;QACnG,OAAO,MAAM,aAAa,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC,CAAC;IACtE,CAAC;AACH,CAAC"}

package/dist/src/datasets/createOrGetDataset.d.ts

@@ -1,18 +0,0 @@
-import type { CreateDatasetParams } from "./createDataset";
-export type CreateOrGetDatasetParams = CreateDatasetParams;
-export type CreateOrGetDatasetResponse = {
-    datasetId: string;
-};
-/**
- * Given the parameters to create a dataset, this function will either
- * retrieve an existing dataset by name or create a new one with the provided parameters.
- *
- * This is useful in cases where you would like to re-run a pipeline like:
- * - ensure dataset exists
- * - create a task
- * - run experiment
- * - evaluate experiment
- * without having to create a new dataset each time.
- */
-export declare function createOrGetDataset({ name, description, examples, client: _client, }: CreateOrGetDatasetParams): Promise<CreateOrGetDatasetResponse>;
-//# sourceMappingURL=createOrGetDataset.d.ts.map

package/dist/src/datasets/createOrGetDataset.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"createOrGetDataset.d.ts","sourceRoot":"","sources":["../../../src/datasets/createOrGetDataset.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAI3D,MAAM,MAAM,wBAAwB,GAAG,mBAAmB,CAAC;AAE3D,MAAM,MAAM,0BAA0B,GAAG;IACvC,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF;;;;;;;;;;GAUG;AACH,wBAAsB,kBAAkB,CAAC,EACvC,IAAI,EACJ,WAAW,EACX,QAAQ,EACR,MAAM,EAAE,OAAO,GAChB,EAAE,wBAAwB,GAAG,OAAO,CAAC,0BAA0B,CAAC,CAYhE"}

package/dist/src/datasets/createOrGetDataset.js

@@ -1,32 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.createOrGetDataset = createOrGetDataset;
-const client_1 = require("../client");
-const createDataset_1 = require("./createDataset");
-const getDatasetInfoByName_1 = require("./getDatasetInfoByName");
-/**
- * Given the parameters to create a dataset, this function will either
- * retrieve an existing dataset by name or create a new one with the provided parameters.
- *
- * This is useful in cases where you would like to re-run a pipeline like:
- * - ensure dataset exists
- * - create a task
- * - run experiment
- * - evaluate experiment
- * without having to create a new dataset each time.
- */
-async function createOrGetDataset({ name, description, examples, client: _client, }) {
-    const client = _client || (0, client_1.createClient)();
-    // start by fetching an existing dataset by name, catching any errors that occur
-    try {
-        const dataset = await (0, getDatasetInfoByName_1.getDatasetInfoByName)({ datasetName: name, client });
-        return {
-            datasetId: dataset.id,
-        };
-    }
-    catch (_a) {
-        // If the dataset doesn't exist, create it, falling back to the error handling inside createDataset
-        return await (0, createDataset_1.createDataset)({ name, description, examples, client });
-    }
-}
-//# sourceMappingURL=createOrGetDataset.js.map

package/dist/src/datasets/createOrGetDataset.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"createOrGetDataset.js","sourceRoot":"","sources":["../../../src/datasets/createOrGetDataset.ts"],"names":[],"mappings":";;AAsBA,gDAiBC;AAvCD,sCAAyC;AAEzC,mDAAgD;AAChD,iEAA8D;AAQ9D;;;;;;;;;;GAUG;AACI,KAAK,UAAU,kBAAkB,CAAC,EACvC,IAAI,EACJ,WAAW,EACX,QAAQ,EACR,MAAM,EAAE,OAAO,GACU;IACzB,MAAM,MAAM,GAAG,OAAO,IAAI,IAAA,qBAAY,GAAE,CAAC;IACzC,gFAAgF;IAChF,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,MAAM,IAAA,2CAAoB,EAAC,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;QAC1E,OAAO;YACL,SAAS,EAAE,OAAO,CAAC,EAAE;SACtB,CAAC;IACJ,CAAC;IAAC,WAAM,CAAC;QACP,mGAAmG;QACnG,OAAO,MAAM,IAAA,6BAAa,EAAC,EAAE,IAAI,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC,CAAC;IACtE,CAAC;AACH,CAAC"}

package/src/datasets/createOrGetDataset.ts

@@ -1,40 +0,0 @@
-import { createClient } from "../client";
-import type { CreateDatasetParams } from "./createDataset";
-import { createDataset } from "./createDataset";
-import { getDatasetInfoByName } from "./getDatasetInfoByName";
-
-export type CreateOrGetDatasetParams = CreateDatasetParams;
-
-export type CreateOrGetDatasetResponse = {
-  datasetId: string;
-};
-
-/**
- * Given the parameters to create a dataset, this function will either
- * retrieve an existing dataset by name or create a new one with the provided parameters.
- *
- * This is useful in cases where you would like to re-run a pipeline like:
- * - ensure dataset exists
- * - create a task
- * - run experiment
- * - evaluate experiment
- * without having to create a new dataset each time.
- */
-export async function createOrGetDataset({
-  name,
-  description,
-  examples,
-  client: _client,
-}: CreateOrGetDatasetParams): Promise<CreateOrGetDatasetResponse> {
-  const client = _client || createClient();
-  // start by fetching an existing dataset by name, catching any errors that occur
-  try {
-    const dataset = await getDatasetInfoByName({ datasetName: name, client });
-    return {
-      datasetId: dataset.id,
-    };
-  } catch {
-    // If the dataset doesn't exist, create it, falling back to the error handling inside createDataset
-    return await createDataset({ name, description, examples, client });
-  }
-}