@arizeai/phoenix-client 6.8.0 → 6.9.0

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/sessions/addSessionNote.ts

@@ -0,0 +1,74 @@
+import { createClient } from "../client";
+import { ADD_SESSION_NOTE } from "../constants/serverRequirements";
+import type { ClientFn } from "../types/core";
+import { formatApiError } from "../utils/apiErrorUtils";
+import { ensureServerCapability } from "../utils/serverVersionUtils";
+
+/**
+ * Parameters for a single session note.
+ */
+export interface SessionNote {
+  /**
+   * The session ID used to track a conversation, thread, or session.
+   */
+  sessionId: string;
+  /**
+   * The note text to add to the session.
+   */
+  note: string;
+}
+
+/**
+ * Parameters to add a session note.
+ */
+export interface AddSessionNoteParams extends ClientFn {
+  sessionNote: SessionNote;
+}
+
+/**
+ * Add a note to a session.
+ *
+ * Notes are a special type of annotation that allow multiple entries per session.
+ * Each note gets a unique UUIDv4 identifier.
+ *
+ * @param params - The parameters to add a session note.
+ * @returns The ID of the created note annotation.
+ *
+ * @requires Phoenix server >= 14.17.0
+ *
+ * @example
+ * ```ts
+ * const result = await addSessionNote({
+ *   sessionNote: {
+ *     sessionId: "my-session",
+ *     note: "Needs review"
+ *   }
+ * });
+ * ```
+ */
+export async function addSessionNote({
+  client: _client,
+  sessionNote,
+}: AddSessionNoteParams): Promise<{ id: string }> {
+  const client = _client ?? createClient();
+  await ensureServerCapability({ client, requirement: ADD_SESSION_NOTE });
+
+  const { data, error } = await client.POST("/v1/session_notes", {
+    body: {
+      data: {
+        session_id: sessionNote.sessionId.trim(),
+        note: sessionNote.note,
+      },
+    },
+  });
+
+  if (error) {
+    throw new Error(`Failed to add session note: ${formatApiError(error)}`);
+  }
+
+  if (!data?.data) {
+    throw new Error("Failed to add session note: no data returned");
+  }
+
+  return data.data;
+}

package/src/sessions/index.ts

@@ -1,4 +1,5 @@
 export * from "./addSessionAnnotation";
+export * from "./addSessionNote";
 export * from "./deleteSession";
 export * from "./deleteSessions";
 export * from "./getSession";

package/src/spans/addSpanNote.ts

@@ -1,5 +1,6 @@
 import { createClient } from "../client";
 import type { ClientFn } from "../types/core";
+import { formatApiError } from "../utils/apiErrorUtils";
 
 /**
  * Parameters for a single span note
@@ -25,9 +26,11 @@ export interface AddSpanNoteParams extends ClientFn {
 /**
  * Add a note to a span.
  *
- * 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 UUIDv4 identifier.
+ * Notes are append-only: each call creates a new note with an auto-generated
+ * UUIDv4 identifier, so multiple notes accumulate on the same span. Structured
+ * annotations, by contrast, are keyed by `(name, spanId, identifier)` — to keep
+ * multiple structured annotations with the same name on a span, supply distinct
+ * identifiers; otherwise re-writing the same name overwrites the existing one.
  *
  * @param params - The parameters to add a span note
  * @returns The ID of the created note annotation
@@ -58,7 +61,7 @@ export async function addSpanNote({
   });
 
   if (error) {
-    throw new Error(`Failed to add span note: ${error}`);
+    throw new Error(`Failed to add span note: ${formatApiError(error)}`);
   }
 
   if (!data?.data) {

package/src/traces/addTraceAnnotation.ts

@@ -0,0 +1,65 @@
+import { createClient } from "../client";
+import type { ClientFn } from "../types/core";
+import type { TraceAnnotation } from "./types";
+import { toTraceAnnotationData } from "./types";
+
+/**
+ * Parameters to add a trace annotation
+ */
+export interface AddTraceAnnotationParams extends ClientFn {
+  traceAnnotation: TraceAnnotation;
+  /**
+   * If true, the request will be fulfilled synchronously and return the annotation ID.
+   * If false, the request will be processed asynchronously and return null.
+   * @default false
+   */
+  sync?: boolean;
+}
+
+/**
+ * Add an annotation to a trace.
+ *
+ * The annotation can be of type "LLM", "CODE", or "HUMAN" and can include a label, score, and metadata.
+ * If an identifier is provided and an annotation with that identifier already exists, it will be updated.
+ *
+ * @param params - The parameters to add a trace annotation
+ * @returns The ID of the created or updated annotation
+ *
+ * @example
+ * ```ts
+ * const result = await addTraceAnnotation({
+ *   traceAnnotation: {
+ *     traceId: "abc123",
+ *     name: "correctness",
+ *     label: "correct",
+ *     score: 1.0,
+ *     annotatorKind: "HUMAN",
+ *     identifier: "custom_id_123",
+ *     metadata: { reviewer: "alice" }
+ *   },
+ *   sync: true,
+ * });
+ * ```
+ */
+export async function addTraceAnnotation({
+  client: _client,
+  traceAnnotation,
+  sync = false,
+}: AddTraceAnnotationParams): Promise<{ id: string } | null> {
+  const client = _client ?? createClient();
+
+  const { data, error } = await client.POST("/v1/trace_annotations", {
+    params: {
+      query: { sync },
+    },
+    body: {
+      data: [toTraceAnnotationData(traceAnnotation)],
+    },
+  });
+
+  if (error) {
+    throw new Error(`Failed to add trace annotation: ${error}`);
+  }
+
+  return data?.data?.[0] || null;
+}

package/src/traces/addTraceNote.ts

@@ -1,6 +1,7 @@
 import { createClient } from "../client";
 import { ADD_TRACE_NOTE } from "../constants/serverRequirements";
 import type { ClientFn } from "../types/core";
+import { formatApiError } from "../utils/apiErrorUtils";
 import { ensureServerCapability } from "../utils/serverVersionUtils";
 
 /**
@@ -27,8 +28,11 @@ export interface AddTraceNoteParams extends ClientFn {
 /**
  * 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.
+ * Notes are append-only: each call creates a new note with an auto-generated
+ * UUIDv4 identifier, so multiple notes accumulate on the same trace. Structured
+ * annotations, by contrast, are keyed by `(name, traceId, identifier)` — to keep
+ * multiple structured annotations with the same name on a trace, supply distinct
+ * identifiers; otherwise re-writing the same name overwrites the existing one.
  *
  * @param params - The parameters to add a trace note.
  * @returns The ID of the created note annotation.
@@ -60,7 +64,7 @@ export async function addTraceNote({
   });
 
   if (error) {
-    throw new Error(`Failed to add trace note: ${error}`);
+    throw new Error(`Failed to add trace note: ${formatApiError(error)}`);
   }
 
   if (!data?.data) {

package/src/traces/index.ts

@@ -1,2 +1,5 @@
+export * from "./addTraceAnnotation";
 export * from "./addTraceNote";
 export * from "./getTraces";
+export * from "./logTraceAnnotations";
+export type { TraceAnnotation } from "./types";

package/src/traces/logTraceAnnotations.ts

@@ -0,0 +1,75 @@
+import { createClient } from "../client";
+import type { ClientFn } from "../types/core";
+import type { TraceAnnotation } from "./types";
+import { toTraceAnnotationData } from "./types";
+
+/**
+ * Parameters to log multiple trace annotations
+ */
+export interface LogTraceAnnotationsParams extends ClientFn {
+  /**
+   * The trace annotations to log
+   */
+  traceAnnotations: TraceAnnotation[];
+  /**
+   * If true, the request will be fulfilled synchronously and return the annotation IDs.
+   * If false, the request will be processed asynchronously and return null.
+   * @default false
+   */
+  sync?: boolean;
+}
+
+/**
+ * Log multiple trace annotations in a single request.
+ *
+ * Each annotation can be of type "LLM", "CODE", or "HUMAN" and can include a label, score, and metadata.
+ * If an identifier is provided and an annotation with that identifier already exists, it will be updated.
+ *
+ * @param params - The parameters to log trace annotations
+ * @returns The IDs of the created or updated annotations
+ *
+ * @example
+ * ```ts
+ * const results = await logTraceAnnotations({
+ *   traceAnnotations: [
+ *     {
+ *       traceId: "abc123",
+ *       name: "correctness",
+ *       label: "correct",
+ *       score: 1.0,
+ *       annotatorKind: "HUMAN",
+ *     },
+ *     {
+ *       traceId: "def456",
+ *       name: "faithfulness",
+ *       label: "faithful",
+ *       score: 0.9,
+ *       annotatorKind: "LLM",
+ *     },
+ *   ],
+ *   sync: true,
+ * });
+ * ```
+ */
+export async function logTraceAnnotations({
+  client: _client,
+  traceAnnotations,
+  sync = false,
+}: LogTraceAnnotationsParams): Promise<{ id: string }[]> {
+  const client = _client ?? createClient();
+
+  const { data, error } = await client.POST("/v1/trace_annotations", {
+    params: {
+      query: { sync },
+    },
+    body: {
+      data: traceAnnotations.map(toTraceAnnotationData),
+    },
+  });
+
+  if (error) {
+    throw new Error(`Failed to log trace annotations: ${error}`);
+  }
+
+  return data?.data || [];
+}

package/src/traces/types.ts

@@ -0,0 +1,72 @@
+import type { paths } from "../__generated__/api/v1";
+import type { Annotation, AnnotationResult } from "../types/annotations";
+
+type TraceAnnotationData =
+  paths["/v1/trace_annotations"]["post"]["requestBody"]["content"]["application/json"]["data"][0];
+
+/**
+ * Parameters for a single trace annotation
+ */
+export interface TraceAnnotation extends Annotation {
+  /**
+   * The OpenTelemetry Trace ID (hex format without 0x prefix)
+   */
+  traceId: string;
+  /**
+   * The kind of annotator used for the annotation
+   * Can be "HUMAN", "LLM", or "CODE"
+   * @default "HUMAN"
+   */
+  annotatorKind?: TraceAnnotationData["annotator_kind"];
+}
+
+/**
+ * Build and validate annotation result fields
+ */
+function buildTraceAnnotationResult(
+  annotation: Pick<TraceAnnotation, "label" | "score" | "explanation">
+): AnnotationResult {
+  const result: AnnotationResult = {};
+
+  if (annotation.label !== undefined) {
+    result.label = annotation.label.trim() || null;
+  }
+  if (annotation.score !== undefined) {
+    result.score = annotation.score;
+  }
+  if (annotation.explanation !== undefined) {
+    result.explanation = annotation.explanation.trim() || null;
+  }
+
+  const hasValidResult =
+    result.label || result.score !== undefined || result.explanation;
+  if (!hasValidResult) {
+    throw new Error(
+      "At least one of label, score, or explanation must be provided for trace annotation"
+    );
+  }
+  return result;
+}
+
+/**
+ * Convert a TraceAnnotation to the API format
+ */
+export function toTraceAnnotationData(
+  annotation: TraceAnnotation
+): TraceAnnotationData {
+  if (annotation.name.trim() === "note") {
+    throw new Error(
+      'The name "note" is reserved for trace and span notes. Use addTraceNote instead.'
+    );
+  }
+  const result = buildTraceAnnotationResult(annotation);
+
+  return {
+    trace_id: annotation.traceId.trim(),
+    name: annotation.name.trim(),
+    annotator_kind: annotation.annotatorKind ?? "HUMAN",
+    result,
+    metadata: annotation.metadata ?? null,
+    identifier: annotation.identifier?.trim() ?? "",
+  };
+}

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/src/utils/apiErrorUtils.ts

@@ -0,0 +1,17 @@
+export function formatApiError(error: unknown): string {
+  if (typeof error === "string") {
+    return error;
+  }
+  if (error && typeof error === "object") {
+    const errorWithDetail = error as { detail?: unknown };
+    if (typeof errorWithDetail.detail === "string") {
+      return errorWithDetail.detail;
+    }
+    try {
+      return JSON.stringify(error);
+    } catch {
+      return String(error);
+    }
+  }
+  return String(error);
+}