@arizeai/phoenix-client 7.13.0 → 7.14.0

package/docs/datasets.mdx

@@ -3,7 +3,7 @@ title: "Datasets"
 description: "Create and inspect datasets with @arizeai/phoenix-client"
 ---
 
-Datasets are the foundation for experiment runs. The dataset helpers cover creation (which upserts by name), record inspection, and example appends.
+Datasets are the foundation for experiment runs. The dataset helpers cover creation (which upserts by name), record inspection, example appends, and split management.
 
 <section className="hidden" data-agent-context="relevant-source-files" aria-label="Relevant source files">
   <h2>Relevant Source Files</h2>
@@ -25,14 +25,27 @@ const { datasetId } = await createDataset({
   description: "Support questions with expected answers",
   examples: [
     {
+      id: "order-tracking",
       input: { question: "Where is my order?" },
       output: { answer: "Use the tracking page in your account." },
       metadata: { channel: "chat" },
     },
+    {
+      id: "password-reset",
+      input: { question: "How do I reset my password?" },
+      output: { answer: "Use the forgot password flow." },
+      metadata: { channel: "chat" },
+    },
   ],
 });
 ```
 
+`id` is optional. When you do provide it, give every example its own value:
+example IDs are unique per dataset, so reusing one across examples in the same
+dataset is an error. A stable, unique `id` is what `createDataset()` matches on
+when it upserts, and what you can hand to the split helpers below instead of the
+server-generated `nodeId`. Omit `id` and the server generates one for you.
+
 ## 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.
@@ -48,6 +61,7 @@ const dataset = await createDataset({
   description: "Support questions with expected answers",
   examples: [
     {
+      id: "order-tracking",
       input: { question: "Where is my order?" },
       output: { answer: "Use the tracking page in your account." },
     },
@@ -58,6 +72,7 @@ await appendDatasetExamples({
   dataset,
   examples: [
     {
+      id: "password-reset",
       input: { question: "How do I reset my password?" },
       output: { answer: "Use the forgot password flow." },
     },
@@ -71,6 +86,61 @@ await appendDatasetExamples({
 
 Use `getDataset`, `getDatasetExamples`, and `getDatasetInfo` to inspect datasets after creation.
 
+## Manage Splits On An Existing Dataset
+
+Use `createDatasetSplit`, `updateDatasetSplit`, and `deleteDatasetSplit` to
+manage train, test, validation, or other named subsets after a dataset exists.
+Select the dataset by name or GlobalID. Example membership accepts either the
+user-provided `id` or Phoenix `nodeId` returned by `getDatasetExamples`.
+
+```ts
+import {
+  createDatasetSplit,
+  deleteDatasetSplit,
+  getDatasetExamples,
+  updateDatasetSplit,
+} from "@arizeai/phoenix-client/datasets";
+
+const datasetIdentifier = "support-eval";
+const dataset = { datasetName: datasetIdentifier };
+const { examples } = await getDatasetExamples({
+  dataset,
+});
+const [firstExample, secondExample] = examples;
+if (firstExample == null || secondExample == null) {
+  throw new Error("At least two examples are required to demonstrate split updates");
+}
+
+const testSplit = await createDatasetSplit({
+  dataset,
+  name: "test",
+  description: "Held-out evaluation examples",
+  exampleIds: [firstExample.id],
+});
+
+// Only provided fields change. Adding an existing member or removing a
+// non-member is an idempotent no-op.
+await updateDatasetSplit({
+  dataset,
+  splitId: testSplit.id,
+  description: "Reviewed held-out examples",
+  addExampleIds: [secondExample.id],
+  removeExampleIds: [firstExample.id],
+});
+
+// Deleting a split removes its memberships, not the underlying examples.
+await deleteDatasetSplit({
+  dataset,
+  splitId: testSplit.id,
+});
+```
+
+Split names are unique across the Phoenix instance. Creating or renaming a
+split to an existing name fails with HTTP 409. These helpers require Phoenix
+server 19.20.0 or newer. Servers on 19.20.0 through 20.15.0 resolve membership
+by `nodeId` only — user-provided `id` values are accepted from the release that
+follows 20.15.0, so pass `nodeId` when you target an older server.
+
 <section className="hidden" data-agent-context="source-map" aria-label="Source map">
   <h2>Source Map</h2>
   <ul>
@@ -79,5 +149,8 @@ Use `getDataset`, `getDatasetExamples`, and `getDatasetInfo` to inspect datasets
     <li><code>src/datasets/getDataset.ts</code></li>
     <li><code>src/datasets/getDatasetExamples.ts</code></li>
     <li><code>src/datasets/getDatasetInfo.ts</code></li>
+    <li><code>src/datasets/createDatasetSplit.ts</code></li>
+    <li><code>src/datasets/updateDatasetSplit.ts</code></li>
+    <li><code>src/datasets/deleteDatasetSplit.ts</code></li>
   </ul>
 </section>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arizeai/phoenix-client",
-  "version": "7.13.0",
+  "version": "7.14.0",
   "description": "A client for the Phoenix API",
   "keywords": [
     "arize",

package/src/__generated__/api/v1.ts

@@ -2679,7 +2679,7 @@ export interface components {
             };
             /**
              * Example Ids
-             * @description Optional dataset example IDs (GlobalIDs) to seed the split with. Each example must belong to this dataset. Omit to create an empty split.
+             * @description Optional dataset example identifiers (GlobalIDs or user-provided IDs) to seed the split with. Each example must belong to this dataset. Omit to create an empty split.
              */
             example_ids?: string[];
         };
@@ -6716,12 +6716,12 @@ export interface components {
             } | null;
             /**
              * Add Example Ids
-             * @description Dataset example IDs (GlobalIDs) to add to the split. Each example must belong to this dataset. Adding an example already in the split is a no-op.
+             * @description Dataset example identifiers (GlobalIDs or user-provided IDs) to add to the split. Each example must belong to this dataset. Adding an example already in the split is a no-op.
              */
             add_example_ids?: string[];
             /**
              * Remove Example Ids
-             * @description Dataset example IDs (GlobalIDs) to remove from the split.
+             * @description Dataset example identifiers (GlobalIDs or user-provided IDs) to remove from the split.
              */
             remove_example_ids?: string[];
         };

package/src/constants/serverRequirements.ts

@@ -147,6 +147,27 @@ export const DATASET_UPLOAD_EXAMPLE_IDS: ParameterRequirement = {
   minServerVersion: [15, 0, 0],
 };
 
+export const CREATE_DATASET_SPLIT: RouteRequirement = {
+  kind: "route",
+  method: "POST",
+  path: "/v1/datasets/{dataset_identifier}/splits",
+  minServerVersion: [19, 20, 0],
+};
+
+export const UPDATE_DATASET_SPLIT: RouteRequirement = {
+  kind: "route",
+  method: "PATCH",
+  path: "/v1/datasets/{dataset_identifier}/splits/{split_id}",
+  minServerVersion: [19, 20, 0],
+};
+
+export const DELETE_DATASET_SPLIT: RouteRequirement = {
+  kind: "route",
+  method: "DELETE",
+  path: "/v1/datasets/{dataset_identifier}/splits/{split_id}",
+  minServerVersion: [19, 20, 0],
+};
+
 export const ADD_TRACE_NOTE_IDENTIFIER: ParameterRequirement = {
   kind: "parameter",
   parameterName: "identifier",
@@ -265,6 +286,9 @@ export const ALL_REQUIREMENTS: readonly CapabilityRequirement[] = [
   LIST_SESSIONS_FILTER_EXPRESSION,
   TRANSFER_TRACES,
   DATASET_UPLOAD_EXAMPLE_IDS,
+  CREATE_DATASET_SPLIT,
+  UPDATE_DATASET_SPLIT,
+  DELETE_DATASET_SPLIT,
   ADD_TRACE_NOTE_IDENTIFIER,
   ADD_SPAN_NOTE_IDENTIFIER,
   ADD_SESSION_NOTE_IDENTIFIER,

package/src/datasets/createDatasetSplit.ts

@@ -0,0 +1,80 @@
+import invariant from "tiny-invariant";
+
+import type { components } from "../__generated__/api/v1";
+import { createClient } from "../client";
+import { CREATE_DATASET_SPLIT } from "../constants/serverRequirements";
+import type { ClientFn } from "../types/core";
+import type { DatasetIdentifier, DatasetSplit } from "../types/datasets";
+import { ensureServerCapability } from "../utils/serverVersionUtils";
+import { resolveDatasetIdentifier } from "./resolveDatasetIdentifier";
+
+type CreateDatasetSplitRequestBody =
+  components["schemas"]["CreateDatasetSplitRequestBody"];
+type CreateDatasetSplitResponseBody =
+  components["schemas"]["CreateDatasetSplitResponseBody"];
+
+/** Parameters for creating a dataset split. */
+export interface CreateDatasetSplitParams extends ClientFn {
+  /** The dataset, selected by name or GlobalID. */
+  dataset: DatasetIdentifier;
+  /** A unique name for the split. */
+  name: CreateDatasetSplitRequestBody["name"];
+  /** An optional description of the split. */
+  description?: CreateDatasetSplitRequestBody["description"];
+  /** An optional hex color for the split. */
+  color?: CreateDatasetSplitRequestBody["color"];
+  /** Arbitrary JSON metadata for the split. */
+  metadata?: CreateDatasetSplitRequestBody["metadata"];
+  /** Dataset example GlobalIDs or user-provided IDs with which to seed the split. */
+  exampleIds?: CreateDatasetSplitRequestBody["example_ids"];
+}
+
+/**
+ * Create a split on an existing dataset.
+ *
+ * @param params - The split to create.
+ * @param params.client - Optional Phoenix client instance.
+ * @param params.dataset - The dataset, selected by name or GlobalID.
+ * @param params.name - A unique name for the split.
+ * @param params.description - An optional description of the split.
+ * @param params.color - An optional hex color for the split.
+ * @param params.metadata - Arbitrary JSON metadata for the split.
+ * @param params.exampleIds - Dataset example GlobalIDs or user-provided IDs with which to seed the split.
+ * @returns The created dataset split.
+ * @throws {HttpError} If the dataset or an example does not exist, the name is
+ * already in use, or the request is invalid.
+ *
+ * @requires Phoenix server >= 19.20.0
+ */
+export async function createDatasetSplit({
+  client: _client,
+  dataset,
+  name,
+  description,
+  color,
+  metadata,
+  exampleIds,
+}: CreateDatasetSplitParams): Promise<DatasetSplit> {
+  const client = _client ?? createClient();
+  await ensureServerCapability({ client, requirement: CREATE_DATASET_SPLIT });
+  const datasetIdentifier = resolveDatasetIdentifier(dataset);
+
+  const body: CreateDatasetSplitRequestBody = {
+    name,
+    ...(description !== undefined ? { description } : {}),
+    ...(color !== undefined ? { color } : {}),
+    ...(metadata !== undefined ? { metadata } : {}),
+    ...(exampleIds !== undefined ? { example_ids: exampleIds } : {}),
+  };
+  const response = await client.POST(
+    "/v1/datasets/{dataset_identifier}/splits",
+    {
+      params: { path: { dataset_identifier: datasetIdentifier } },
+      body,
+    }
+  );
+  const responseBody: CreateDatasetSplitResponseBody | undefined =
+    response.data;
+  invariant(responseBody?.data, "Failed to create dataset split");
+  return responseBody.data;
+}

package/src/datasets/deleteDatasetSplit.ts

@@ -0,0 +1,46 @@
+import { createClient } from "../client";
+import { DELETE_DATASET_SPLIT } from "../constants/serverRequirements";
+import type { ClientFn } from "../types/core";
+import type { DatasetIdentifier } from "../types/datasets";
+import { ensureServerCapability } from "../utils/serverVersionUtils";
+import { resolveDatasetIdentifier } from "./resolveDatasetIdentifier";
+
+/** Parameters for deleting a dataset split. */
+export interface DeleteDatasetSplitParams extends ClientFn {
+  /** The dataset, selected by name or GlobalID. */
+  dataset: DatasetIdentifier;
+  /** The dataset split GlobalID. */
+  splitId: string;
+}
+
+/**
+ * Delete a dataset split and its memberships without deleting its examples.
+ *
+ * @param params - The split to delete.
+ * @param params.client - Optional Phoenix client instance.
+ * @param params.dataset - The dataset, selected by name or GlobalID.
+ * @param params.splitId - The dataset split GlobalID.
+ * @returns A promise that resolves once the split is deleted.
+ * @throws {HttpError} If the dataset or split does not exist, or the split ID
+ * is invalid.
+ *
+ * @requires Phoenix server >= 19.20.0
+ */
+export async function deleteDatasetSplit({
+  client: _client,
+  dataset,
+  splitId,
+}: DeleteDatasetSplitParams): Promise<void> {
+  const client = _client ?? createClient();
+  await ensureServerCapability({ client, requirement: DELETE_DATASET_SPLIT });
+  const datasetIdentifier = resolveDatasetIdentifier(dataset);
+
+  await client.DELETE("/v1/datasets/{dataset_identifier}/splits/{split_id}", {
+    params: {
+      path: {
+        dataset_identifier: datasetIdentifier,
+        split_id: splitId,
+      },
+    },
+  });
+}

package/src/datasets/index.ts

@@ -1,5 +1,9 @@
 export * from "./createDataset";
+export * from "./createDatasetSplit";
+export * from "./deleteDatasetSplit";
 export * from "./getDataset";
 export * from "./getDatasetExamples";
 export * from "./appendDatasetExamples";
 export * from "./getDatasetInfo";
+export * from "./updateDatasetSplit";
+export type { DatasetIdentifier, DatasetSplit } from "../types/datasets";

package/src/datasets/resolveDatasetIdentifier.ts

@@ -0,0 +1,6 @@
+import type { DatasetIdentifier } from "../types/datasets";
+
+/** Resolve a typed dataset selector to the REST path identifier. */
+export function resolveDatasetIdentifier(dataset: DatasetIdentifier): string {
+  return "datasetName" in dataset ? dataset.datasetName : dataset.datasetId;
+}

package/src/datasets/updateDatasetSplit.ts

@@ -0,0 +1,99 @@
+import invariant from "tiny-invariant";
+
+import type { components } from "../__generated__/api/v1";
+import { createClient } from "../client";
+import { UPDATE_DATASET_SPLIT } from "../constants/serverRequirements";
+import type { ClientFn } from "../types/core";
+import type { DatasetIdentifier, DatasetSplit } from "../types/datasets";
+import { ensureServerCapability } from "../utils/serverVersionUtils";
+import { resolveDatasetIdentifier } from "./resolveDatasetIdentifier";
+
+type UpdateDatasetSplitRequestBody =
+  components["schemas"]["UpdateDatasetSplitRequestBody"];
+type UpdateDatasetSplitResponseBody =
+  components["schemas"]["UpdateDatasetSplitResponseBody"];
+
+/** Parameters for partially updating a dataset split. */
+export interface UpdateDatasetSplitParams extends ClientFn {
+  /** The dataset, selected by name or GlobalID. */
+  dataset: DatasetIdentifier;
+  /** The dataset split GlobalID. */
+  splitId: string;
+  /** A new unique name for the split. */
+  name?: UpdateDatasetSplitRequestBody["name"];
+  /** A new description, or null to clear it. */
+  description?: UpdateDatasetSplitRequestBody["description"];
+  /** A new hex color for the split. */
+  color?: UpdateDatasetSplitRequestBody["color"];
+  /** JSON metadata that replaces the existing metadata. */
+  metadata?: UpdateDatasetSplitRequestBody["metadata"];
+  /** Dataset example GlobalIDs or user-provided IDs to add. Existing memberships are no-ops. */
+  addExampleIds?: UpdateDatasetSplitRequestBody["add_example_ids"];
+  /** Dataset example GlobalIDs or user-provided IDs to remove. Missing memberships are no-ops. */
+  removeExampleIds?: UpdateDatasetSplitRequestBody["remove_example_ids"];
+}
+
+/**
+ * Partially update a dataset split and/or its example membership.
+ *
+ * Only provided fields change. Membership additions and removals are
+ * idempotent; if an example appears in both arrays, removal wins.
+ *
+ * @param params - The split fields and memberships to update.
+ * @param params.client - Optional Phoenix client instance.
+ * @param params.dataset - The dataset, selected by name or GlobalID.
+ * @param params.splitId - The dataset split GlobalID.
+ * @param params.name - A new unique name for the split.
+ * @param params.description - A new description, or null to clear it.
+ * @param params.color - A new hex color for the split.
+ * @param params.metadata - JSON metadata that replaces the existing metadata.
+ * @param params.addExampleIds - Dataset example GlobalIDs or user-provided IDs to add.
+ * @param params.removeExampleIds - Dataset example GlobalIDs or user-provided IDs to remove.
+ * @returns The updated dataset split.
+ * @throws {HttpError} If the dataset, split, or an example does not exist, the
+ * name is already in use, or the request is invalid.
+ *
+ * @requires Phoenix server >= 19.20.0
+ */
+export async function updateDatasetSplit({
+  client: _client,
+  dataset,
+  splitId,
+  name,
+  description,
+  color,
+  metadata,
+  addExampleIds,
+  removeExampleIds,
+}: UpdateDatasetSplitParams): Promise<DatasetSplit> {
+  const client = _client ?? createClient();
+  await ensureServerCapability({ client, requirement: UPDATE_DATASET_SPLIT });
+  const datasetIdentifier = resolveDatasetIdentifier(dataset);
+
+  const body: UpdateDatasetSplitRequestBody = {
+    ...(name !== undefined ? { name } : {}),
+    ...(description !== undefined ? { description } : {}),
+    ...(color !== undefined ? { color } : {}),
+    ...(metadata !== undefined ? { metadata } : {}),
+    ...(addExampleIds !== undefined ? { add_example_ids: addExampleIds } : {}),
+    ...(removeExampleIds !== undefined
+      ? { remove_example_ids: removeExampleIds }
+      : {}),
+  };
+  const response = await client.PATCH(
+    "/v1/datasets/{dataset_identifier}/splits/{split_id}",
+    {
+      params: {
+        path: {
+          dataset_identifier: datasetIdentifier,
+          split_id: splitId,
+        },
+      },
+      body,
+    }
+  );
+  const responseBody: UpdateDatasetSplitResponseBody | undefined =
+    response.data;
+  invariant(responseBody?.data, "Failed to update dataset split");
+  return responseBody.data;
+}

package/src/types/datasets.ts

@@ -1,13 +1,18 @@
+import type { components } from "../__generated__/api/v1";
 import type { Node } from "./core";
 
+/** A named subset of examples in a dataset. */
+export type DatasetSplit = components["schemas"]["DatasetSplit"];
+
 type DatasetSelectorBase = { versionId?: string; splits?: string[] };
 
+/** A dataset identified by either its GlobalID or name. */
+export type DatasetIdentifier = { datasetId: string } | { datasetName: string };
+
 /**
  * A dataset can be identified by its datasetId, datasetName, or datasetVersionId
  */
-export type DatasetSelector =
-  | (DatasetSelectorBase & { datasetId: string })
-  | (DatasetSelectorBase & { datasetName: string });
+export type DatasetSelector = DatasetSelectorBase & DatasetIdentifier;
 
 /**
  * Overview information about a dataset