@arizeai/phoenix-client 6.8.1 → 6.9.0

package/package.json

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

package/src/__generated__/api/v1.ts

@@ -67,7 +67,10 @@ export interface paths {
             path?: never;
             cookie?: never;
         };
-        /** Get span annotations for a list of span_ids. */
+        /**
+         * Get span annotations filtered by span_ids and/or identifier.
+         * @description Return span annotations for a project, filtered by `span_ids`, `identifier`, or both. At least one of `span_ids` or `identifier` must be supplied. When both are supplied, results are the AND-intersection of the two filters.
+         */
         get: operations["listSpanAnnotationsBySpanIds"];
         put?: never;
         post?: never;
@@ -84,7 +87,10 @@ export interface paths {
             path?: never;
             cookie?: never;
         };
-        /** Get trace annotations for a list of trace_ids. */
+        /**
+         * Get trace annotations filtered by trace_ids and/or identifier.
+         * @description Return trace annotations for a project, filtered by `trace_ids`, `identifier`, or both. At least one of `trace_ids` or `identifier` must be supplied. When both are supplied, results are the AND-intersection of the two filters.
+         */
         get: operations["listTraceAnnotationsByTraceIds"];
         put?: never;
         post?: never;
@@ -101,7 +107,10 @@ export interface paths {
             path?: never;
             cookie?: never;
         };
-        /** Get session annotations for a list of session_ids. */
+        /**
+         * Get session annotations filtered by session_ids and/or identifier.
+         * @description Return session annotations for a project, filtered by `session_ids`, `identifier`, or both. At least one of `session_ids` or `identifier` must be supplied. When both are supplied, results are the AND-intersection of the two filters.
+         */
         get: operations["listSessionAnnotationsBySessionIds"];
         put?: never;
         post?: never;
@@ -486,7 +495,7 @@ export interface paths {
         put?: never;
         /**
          * Create a trace note
-         * @description Add a note annotation to a trace. Notes are special annotations that allow multiple entries per trace (unlike regular annotations which are unique by name and identifier). Each note gets a unique UUIDv4 identifier.
+         * @description Add a note annotation to a trace. Each call appends 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, trace_id, identifier) — re-writing the same key overwrites the existing annotation, so to keep multiple structured annotations with the same name on a trace you must supply distinct identifiers.
          */
         post: operations["createTraceNote"];
         delete?: never;
@@ -591,7 +600,7 @@ export interface paths {
         put?: never;
         /**
          * Create a span note
-         * @description Add a note annotation to a span. Notes are special annotations that allow multiple entries per span (unlike regular annotations which are unique by name and identifier). Each note gets a unique UUIDv4 identifier.
+         * @description Add a note annotation to a span. Each call appends 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, span_id, identifier) — re-writing the same key overwrites the existing annotation, so to keep multiple structured annotations with the same name on a span you must supply distinct identifiers.
          */
         post: operations["createSpanNote"];
         delete?: never;
@@ -942,7 +951,7 @@ export interface paths {
         put?: never;
         /**
          * Create a session note
-         * @description Add a note annotation to a session. Notes are special annotations that allow multiple entries per session (unlike regular annotations which are unique by name and identifier). Each note gets a unique UUIDv4 identifier.
+         * @description Add a note annotation to a session. Each call appends a new note with an auto-generated UUIDv4 identifier, so multiple notes accumulate on the same session. Structured annotations, by contrast, are keyed by (name, session_id, identifier) — re-writing the same key overwrites the existing annotation, so to keep multiple structured annotations with the same name on a session you must supply distinct identifiers.
          */
         post: operations["createSessionNote"];
         delete?: never;
@@ -3967,9 +3976,11 @@ export interface operations {
     };
     listSpanAnnotationsBySpanIds: {
         parameters: {
-            query: {
-                /** @description One or more span id to fetch annotations for */
-                span_ids: string[];
+            query?: {
+                /** @description Optional list of span ids to fetch annotations for. If omitted, `identifier` must be supplied. */
+                span_ids?: string[] | null;
+                /** @description Optional list of annotation identifiers to filter by. Each value must be non-empty. If omitted, `span_ids` must be supplied. When combined with `span_ids`, results are the AND-intersection of both filters. */
+                identifier?: string[] | null;
                 /** @description Optional list of annotation names to include. If provided, only annotations with these names will be returned. 'note' annotations are excluded by default unless explicitly included in this list. */
                 include_annotation_names?: string[] | null;
                 /** @description Optional list of annotation names to exclude from results. */
@@ -4028,9 +4039,11 @@ export interface operations {
     };
     listTraceAnnotationsByTraceIds: {
         parameters: {
-            query: {
-                /** @description One or more trace id to fetch annotations for */
-                trace_ids: string[];
+            query?: {
+                /** @description Optional list of trace ids to fetch annotations for. If omitted, `identifier` must be supplied. */
+                trace_ids?: string[] | null;
+                /** @description Optional list of annotation identifiers to filter by. Each value must be non-empty. If omitted, `trace_ids` must be supplied. When combined with `trace_ids`, results are the AND-intersection of both filters. */
+                identifier?: string[] | null;
                 /** @description Optional list of annotation names to include. If provided, only annotations with these names will be returned. 'note' annotations are excluded by default unless explicitly included in this list. */
                 include_annotation_names?: string[] | null;
                 /** @description Optional list of annotation names to exclude from results. */
@@ -4089,9 +4102,11 @@ export interface operations {
     };
     listSessionAnnotationsBySessionIds: {
         parameters: {
-            query: {
-                /** @description One or more session id to fetch annotations for */
-                session_ids: string[];
+            query?: {
+                /** @description Optional list of session ids to fetch annotations for. If omitted, `identifier` must be supplied. */
+                session_ids?: string[] | null;
+                /** @description Optional list of annotation identifiers to filter by. Each value must be non-empty. If omitted, `session_ids` must be supplied. When combined with `session_ids`, results are the AND-intersection of both filters. */
+                identifier?: string[] | null;
                 /** @description Optional list of annotation names to include. If provided, only annotations with these names will be returned. 'note' annotations are excluded by default unless explicitly included in this list. */
                 include_annotation_names?: string[] | null;
                 /** @description Optional list of annotation names to exclude from results. */

package/src/constants/serverRequirements.ts

@@ -60,6 +60,13 @@ export const ADD_TRACE_NOTE: RouteRequirement = {
   minServerVersion: [14, 13, 0],
 };
 
+export const ADD_SESSION_NOTE: RouteRequirement = {
+  kind: "route",
+  method: "POST",
+  path: "/v1/session_notes",
+  minServerVersion: [14, 17, 0],
+};
+
 export const GET_SPANS_TRACE_IDS: ParameterRequirement = {
   kind: "parameter",
   parameterName: "trace_id",
@@ -112,6 +119,7 @@ export const ALL_REQUIREMENTS: readonly CapabilityRequirement[] = [
   LIST_PROJECT_SESSIONS,
   ANNOTATE_SESSIONS,
   ADD_TRACE_NOTE,
+  ADD_SESSION_NOTE,
   GET_SPANS_TRACE_IDS,
   GET_SPANS_FILTERS,
   GET_SPANS_BY_ATTRIBUTE,

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/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);
+}