@arizeai/phoenix-client 6.8.1 → 6.9.0

package/README.md

@@ -368,6 +368,69 @@ do {
 
 > **Note:** Requires Phoenix server >= 13.15.0.
 
+### Trace Annotations
+
+Add structured feedback (label/score by name) to entire traces. Use `addTraceAnnotation` for one trace or `logTraceAnnotations` for batches.
+
+```ts
+import {
+  addTraceAnnotation,
+  logTraceAnnotations,
+} from "@arizeai/phoenix-client/traces";
+
+// Single annotation
+const result = await addTraceAnnotation({
+  traceAnnotation: {
+    traceId: "abc123",
+    name: "correctness",
+    label: "correct",
+    score: 1.0,
+    annotatorKind: "HUMAN",
+  },
+  sync: true, // returns { id: "..." } when sync, null when async
+});
+
+// Batch
+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,
+});
+```
+
+The reserved name `note` is rejected — use `addTraceNote` instead for free-form notes (see below).
+
+### Trace Notes
+
+Notes are a special type of annotation for free-form text — useful for open coding, where reviewers leave qualitative observations on a trace before any rubric exists. Multiple notes can coexist on the same trace.
+
+```ts
+import { addTraceNote } from "@arizeai/phoenix-client/traces";
+
+await addTraceNote({
+  traceNote: {
+    traceId: "abc123",
+    note: "Needs follow-up — unexpected tool call sequence",
+  },
+});
+```
+
+> **Note:** `addTraceNote` requires Phoenix server >= 14.13.0.
+
 ## Spans
 
 The `@arizeai/phoenix-client` package provides a `spans` export for querying spans with powerful filtering.
@@ -505,6 +568,7 @@ import {
   listSessions,
   getSession,
   addSessionAnnotation,
+  addSessionNote,
 } from "@arizeai/phoenix-client/sessions";
 
 // List all sessions for a project
@@ -537,6 +601,19 @@ await addSessionAnnotation({
 });
 ```
 
+### Adding Session Notes
+
+Session notes require Phoenix server `14.17.0` or newer.
+
+```ts
+await addSessionNote({
+  sessionNote: {
+    sessionId: "my-session-id",
+    note: "Needs review",
+  },
+});
+```
+
 ## Examples
 
 To run examples, install dependencies using `pnpm` and run:

package/dist/esm/__generated__/api/v1.d.ts

@@ -66,7 +66,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;
@@ -83,7 +86,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;
@@ -100,7 +106,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;
@@ -485,7 +494,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;
@@ -590,7 +599,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;
@@ -941,7 +950,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;
@@ -3966,9 +3975,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. */
@@ -4027,9 +4038,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. */
@@ -4088,9 +4101,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. */