@arizeai/phoenix-client 6.7.0 → 6.8.0

package/docs/span-annotations.mdx

@@ -226,7 +226,7 @@ do {
 
 ## Span Notes
 
-`addSpanNote` attaches a free-text comment to a span. Unlike structured annotations (which are keyed by `name` + `identifier`), notes are append-only — each call creates a new note with a unique timestamp-based identifier, so multiple notes naturally accumulate on the same span.
+`addSpanNote` attaches a free-text comment to a span. Unlike structured annotations (which are keyed by `name` + `identifier`), notes are append-only — each call creates a new note with a unique UUIDv4 identifier, so multiple notes naturally accumulate on the same span.
 
 This makes notes a good mechanism for **open coding**: reviewers can leave qualitative observations on spans during exploratory analysis without needing to define annotation names or scoring rubrics up front. The accumulated notes can later inform what structured annotations to create.
 

package/docs/spans.mdx

@@ -32,6 +32,29 @@ for (const span of result.spans) {
 }
 ```
 
+### Filtering by Attributes
+
+Use the `attributes` parameter to filter spans by OpenInference attribute key-value pairs. Multiple entries are ANDed together. The JS type of the value determines how the stored attribute is matched: a `number` matches a stored integer or float, a `boolean` matches a stored boolean, and a `string` matches a stored string.
+
+```ts
+// Spans from a specific model
+const result = await getSpans({
+  project: { projectName: "support-bot" },
+  attributes: { "llm.model_name": "gpt-4o" },
+});
+
+// Spans for a session and a specific user (AND semantics)
+const result = await getSpans({
+  project: { projectName: "support-bot" },
+  attributes: {
+    "session.id": "sess-abc123",
+    "user.id": "user-42",
+  },
+});
+```
+
+Non-finite number values (`Infinity`, `NaN`) throw a `RangeError`. Requires Phoenix server ≥ 14.9.0.
+
 ## Root Span Queries
 
 Use `parentId: null` to limit results to root spans only.
@@ -45,8 +68,12 @@ const rootSpans = await getSpans({
 
 ## Span Maintenance
 
+### Adding Notes
+
+Use `addSpanNote` to attach a free-text note to a span. Multiple notes can be added to the same span — they are independent entries, each with its own timestamp.
+
 ```ts
-import { addSpanNote, deleteSpan } from "@arizeai/phoenix-client/spans";
+import { addSpanNote } from "@arizeai/phoenix-client/spans";
 
 await addSpanNote({
   spanNote: {
@@ -54,6 +81,12 @@ await addSpanNote({
     note: "Escalated due to failed retrieval",
   },
 });
+```
+
+### Deleting Spans
+
+```ts
+import { deleteSpan } from "@arizeai/phoenix-client/spans";
 
 await deleteSpan({
   spanIdentifier: "abc123def456",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arizeai/phoenix-client",
-  "version": "6.7.0",
+  "version": "6.8.0",
   "description": "A client for the Phoenix API",
   "keywords": [
     "arize",
@@ -79,8 +79,8 @@
     "openapi-fetch": "^0.12.5",
     "tiny-invariant": "^1.3.3",
     "zod": "^4.0.14",
-    "@arizeai/phoenix-config": "0.1.3",
-    "@arizeai/phoenix-otel": "1.0.0"
+    "@arizeai/phoenix-otel": "1.0.0",
+    "@arizeai/phoenix-config": "0.1.3"
   },
   "devDependencies": {
     "@ai-sdk/openai": "^3.0.29",

package/src/__generated__/api/v1.ts

@@ -458,6 +458,26 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/v1/trace_notes": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        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.
+         */
+        post: operations["createTraceNote"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/v1/traces/{trace_identifier}": {
         parameters: {
             query?: never;
@@ -554,7 +574,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 timestamp-based identifier.
+         * @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.
          */
         post: operations["createSpanNote"];
         delete?: never;
@@ -1291,6 +1311,14 @@ export interface components {
              */
             total_queued: number;
         };
+        /** CreateTraceNoteRequestBody */
+        CreateTraceNoteRequestBody: {
+            data: components["schemas"]["TraceNoteData"];
+        };
+        /** CreateTraceNoteResponseBody */
+        CreateTraceNoteResponseBody: {
+            data: components["schemas"]["InsertedTraceAnnotation"];
+        };
         /** CreateUserRequestBody */
         CreateUserRequestBody: {
             /** User */
@@ -3382,6 +3410,19 @@ export interface components {
             /** Spans */
             spans?: components["schemas"]["TraceSpanData"][] | null;
         };
+        /** TraceNoteData */
+        TraceNoteData: {
+            /**
+             * Trace Id
+             * @description OpenTelemetry Trace ID (hex format w/o 0x prefix)
+             */
+            trace_id: string;
+            /**
+             * Note
+             * @description The note text to add to the trace
+             */
+            note: string;
+        };
         /** TraceSpanData */
         TraceSpanData: {
             /** Id */
@@ -5082,6 +5123,57 @@ export interface operations {
             };
         };
     };
+    createTraceNote: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["CreateTraceNoteRequestBody"];
+            };
+        };
+        responses: {
+            /** @description Trace note created successfully */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["CreateTraceNoteResponseBody"];
+                };
+            };
+            /** @description Forbidden */
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "text/plain": string;
+                };
+            };
+            /** @description Trace not found */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "text/plain": string;
+                };
+            };
+            /** @description Validation Error */
+            422: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["HTTPValidationError"];
+                };
+            };
+        };
+    };
     deleteTrace: {
         parameters: {
             query?: never;

package/src/constants/serverRequirements.ts

@@ -53,6 +53,13 @@ export const ANNOTATE_SESSIONS: RouteRequirement = {
   minServerVersion: [12, 0, 0],
 };
 
+export const ADD_TRACE_NOTE: RouteRequirement = {
+  kind: "route",
+  method: "POST",
+  path: "/v1/trace_notes",
+  minServerVersion: [14, 13, 0],
+};
+
 export const GET_SPANS_TRACE_IDS: ParameterRequirement = {
   kind: "parameter",
   parameterName: "trace_id",
@@ -96,6 +103,7 @@ export const ALL_REQUIREMENTS: readonly CapabilityRequirement[] = [
   DELETE_SESSIONS,
   LIST_PROJECT_SESSIONS,
   ANNOTATE_SESSIONS,
+  ADD_TRACE_NOTE,
   GET_SPANS_TRACE_IDS,
   GET_SPANS_FILTERS,
   GET_SPANS_BY_ATTRIBUTE,

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";