@arizeai/phoenix-client 6.9.3 → 6.10.0

package/package.json

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

package/src/__generated__/api/v1.ts

@@ -573,7 +573,7 @@ export interface paths {
         put?: never;
         /**
          * Create a trace note
-         * @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.
+         * @description Add a note annotation to a trace. By default each call appends a new note with an auto-generated UUIDv4 identifier, so multiple notes accumulate on the same trace. Callers may supply a non-empty `identifier` to upsert on (trace_id, name='note', identifier) — repeated calls with the same identifier overwrite the existing note, matching the semantics of structured annotations.
          */
         post: operations["createTraceNote"];
         delete?: never;
@@ -678,7 +678,7 @@ export interface paths {
         put?: never;
         /**
          * Create a span note
-         * @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.
+         * @description Add a note annotation to a span. By default each call appends a new note with an auto-generated UUIDv4 identifier, so multiple notes accumulate on the same span. Callers may supply a non-empty `identifier` to upsert on (span_id, name='note', identifier) — repeated calls with the same identifier overwrite the existing note, matching the semantics of structured annotations.
          */
         post: operations["createSpanNote"];
         delete?: never;
@@ -1029,7 +1029,7 @@ export interface paths {
         put?: never;
         /**
          * Create a session note
-         * @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.
+         * @description Add a note annotation to a session. By default each call appends a new note with an auto-generated UUIDv4 identifier, so multiple notes accumulate on the same session. Callers may supply a non-empty `identifier` to upsert on (session_id, name='note', identifier) — repeated calls with the same identifier overwrite the existing note, matching the semantics of structured annotations.
          */
         post: operations["createSessionNote"];
         delete?: never;
@@ -1558,6 +1558,31 @@ export interface components {
             /** Parts */
             parts: (components["schemas"]["TextUIPart"] | components["schemas"]["ReasoningUIPart"] | components["schemas"]["ToolInputStreamingPart"] | components["schemas"]["ToolInputAvailablePart"] | components["schemas"]["ToolOutputAvailablePart"] | components["schemas"]["ToolOutputErrorPart"] | components["schemas"]["ToolApprovalRequestedPart"] | components["schemas"]["ToolApprovalRespondedPart"] | components["schemas"]["ToolOutputDeniedPart"] | components["schemas"]["DynamicToolInputStreamingPart"] | components["schemas"]["DynamicToolInputAvailablePart"] | components["schemas"]["DynamicToolOutputAvailablePart"] | components["schemas"]["DynamicToolOutputErrorPart"] | components["schemas"]["DynamicToolApprovalRequestedPart"] | components["schemas"]["DynamicToolApprovalRespondedPart"] | components["schemas"]["DynamicToolOutputDeniedPart"] | components["schemas"]["SourceUrlUIPart"] | components["schemas"]["SourceDocumentUIPart"] | components["schemas"]["FileUIPart"] | components["schemas"]["DataUIPart"] | components["schemas"]["StepStartUIPart"])[];
         };
+        /**
+         * BuiltInProviderModelSelection
+         * @description Chat against a Phoenix built-in provider.
+         *
+         *     Credentials and connection details (base URL, Azure endpoint, AWS
+         *     region) are resolved from the secret store first and the process
+         *     environment second. ``openai_api_type`` is honoured by the OpenAI and
+         *     Azure OpenAI branches; other providers ignore it.
+         */
+        BuiltInProviderModelSelection: {
+            /**
+             * @description discriminator enum property added by openapi-typescript
+             * @enum {string}
+             */
+            providerType: "builtin";
+            provider: components["schemas"]["ModelProvider"];
+            /** Modelname */
+            modelName: string;
+            /**
+             * Openaiapitype
+             * @default responses
+             * @enum {string}
+             */
+            openaiApiType?: "chat_completions" | "responses";
+        };
         /** CategoricalAnnotationConfig */
         CategoricalAnnotationConfig: {
             /** Name */
@@ -1635,6 +1660,8 @@ export interface components {
             /** Contexts */
             contexts?: components["schemas"]["ChatContext"][];
             capabilities?: components["schemas"]["AgentCapabilities"];
+            /** Model */
+            model: components["schemas"]["CustomProviderModelSelection"] | components["schemas"]["BuiltInProviderModelSelection"];
         } & {
             [key: string]: unknown;
         };
@@ -1670,6 +1697,8 @@ export interface components {
             /** Contexts */
             contexts?: components["schemas"]["ChatContext"][];
             capabilities?: components["schemas"]["AgentCapabilities"];
+            /** Model */
+            model: components["schemas"]["CustomProviderModelSelection"] | components["schemas"]["BuiltInProviderModelSelection"];
         } & {
             [key: string]: unknown;
         };
@@ -1888,6 +1917,21 @@ export interface components {
             /** Data */
             data: components["schemas"]["LocalUser"] | components["schemas"]["OAuth2User"] | components["schemas"]["LDAPUser"];
         };
+        /**
+         * CustomProviderModelSelection
+         * @description Chat against a stored custom provider record.
+         */
+        CustomProviderModelSelection: {
+            /**
+             * @description discriminator enum property added by openapi-typescript
+             * @enum {string}
+             */
+            providerType: "custom";
+            /** Providerid */
+            providerId: string;
+            /** Modelname */
+            modelName: string;
+        };
         /**
          * DataUIPart
          * @description Data part with dynamic type based on data name.
@@ -3984,6 +4028,12 @@ export interface components {
              * @description The note text to add to the session
              */
             note: string;
+            /**
+             * Identifier
+             * @description Optional caller-supplied identifier. When non-empty, the note is upserted on (session_id, name='note', identifier) — repeated calls with the same identifier overwrite the existing note. When omitted or empty, the server stamps a unique 'px-session-note:<uuid>' identifier so each call appends a new note.
+             * @default
+             */
+            identifier?: string;
         };
         /** SessionTraceData */
         SessionTraceData: {
@@ -4327,6 +4377,12 @@ export interface components {
              * @description The note text to add to the span
              */
             note: string;
+            /**
+             * Identifier
+             * @description Optional caller-supplied identifier. When non-empty, the note is upserted on (span_id, name='note', identifier) — repeated calls with the same identifier overwrite the existing note. When omitted or empty, the server stamps a unique 'px-span-note:<uuid>' identifier so each call appends a new note.
+             * @default
+             */
+            identifier?: string;
         };
         /** SpansResponseBody */
         SpansResponseBody: {
@@ -4798,6 +4854,12 @@ export interface components {
              * @description The note text to add to the trace
              */
             note: string;
+            /**
+             * Identifier
+             * @description Optional caller-supplied identifier. When non-empty, the note is upserted on (trace_id, name='note', identifier) — repeated calls with the same identifier overwrite the existing note. When omitted or empty, the server stamps a unique 'px-trace-note:<uuid>' identifier so each call appends a new note.
+             * @default
+             */
+            identifier?: string;
         };
         /** TraceSpanData */
         TraceSpanData: {
@@ -4985,6 +5047,8 @@ export interface components {
             exportRemoteTraces?: boolean;
             /** Messages */
             messages: components["schemas"]["UIMessage"][];
+            /** Model */
+            model: components["schemas"]["CustomProviderModelSelection"] | components["schemas"]["BuiltInProviderModelSelection"];
         };
         /** _SummarizeResponse */
         _SummarizeResponse: {
@@ -5219,7 +5283,7 @@ export interface operations {
                 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. */
+                /** @description Optional list of annotation names to include. If provided, only annotations with these names will be returned (allowlist). When omitted, the response includes every matching row regardless of name (no annotation names are excluded by default). */
                 include_annotation_names?: string[] | null;
                 /** @description Optional list of annotation names to exclude from results. */
                 exclude_annotation_names?: string[] | null;
@@ -5343,7 +5407,7 @@ export interface operations {
                 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. */
+                /** @description Optional list of annotation names to include. If provided, only annotations with these names will be returned (allowlist). When omitted, the response includes every matching row regardless of name (no annotation names are excluded by default). */
                 include_annotation_names?: string[] | null;
                 /** @description Optional list of annotation names to exclude from results. */
                 exclude_annotation_names?: string[] | null;
@@ -5467,7 +5531,7 @@ export interface operations {
                 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. */
+                /** @description Optional list of annotation names to include. If provided, only annotations with these names will be returned (allowlist). When omitted, the response includes every matching row regardless of name (no annotation names are excluded by default). */
                 include_annotation_names?: string[] | null;
                 /** @description Optional list of annotation names to exclude from results. */
                 exclude_annotation_names?: string[] | null;
@@ -8802,13 +8866,7 @@ export interface operations {
     };
     chat_agents__agent_id__sessions__session_id__chat_post: {
         parameters: {
-            query: {
-                provider_type: "custom" | "builtin";
-                model_name: string;
-                provider_id?: string | null;
-                provider?: components["schemas"]["ModelProvider"] | null;
-                openai_api_type?: "chat_completions" | "responses";
-            };
+            query?: never;
             header?: never;
             path: {
                 agent_id: string;
@@ -8844,13 +8902,7 @@ export interface operations {
     };
     summarize_endpoint_agents__agent_id__sessions__session_id__summary_post: {
         parameters: {
-            query: {
-                provider_type: "custom" | "builtin";
-                model_name: string;
-                provider_id?: string | null;
-                provider?: components["schemas"]["ModelProvider"] | null;
-                openai_api_type?: "chat_completions" | "responses";
-            };
+            query?: never;
             header?: never;
             path: {
                 agent_id: string;

package/src/constants/serverRequirements.ts

@@ -106,6 +106,30 @@ export const DATASET_UPLOAD_EXAMPLE_IDS: ParameterRequirement = {
   minServerVersion: [15, 0, 0],
 };
 
+export const ADD_TRACE_NOTE_IDENTIFIER: ParameterRequirement = {
+  kind: "parameter",
+  parameterName: "identifier",
+  parameterLocation: "body",
+  route: "POST /v1/trace_notes",
+  minServerVersion: [15, 5, 0],
+};
+
+export const ADD_SPAN_NOTE_IDENTIFIER: ParameterRequirement = {
+  kind: "parameter",
+  parameterName: "identifier",
+  parameterLocation: "body",
+  route: "POST /v1/span_notes",
+  minServerVersion: [15, 5, 0],
+};
+
+export const ADD_SESSION_NOTE_IDENTIFIER: ParameterRequirement = {
+  kind: "parameter",
+  parameterName: "identifier",
+  parameterLocation: "body",
+  route: "POST /v1/session_notes",
+  minServerVersion: [15, 5, 0],
+};
+
 /**
  * Aggregate list of every known capability requirement.
  *
@@ -125,4 +149,7 @@ export const ALL_REQUIREMENTS: readonly CapabilityRequirement[] = [
   GET_SPANS_BY_ATTRIBUTE,
   LIST_PROJECT_TRACES,
   DATASET_UPLOAD_EXAMPLE_IDS,
+  ADD_TRACE_NOTE_IDENTIFIER,
+  ADD_SPAN_NOTE_IDENTIFIER,
+  ADD_SESSION_NOTE_IDENTIFIER,
 ] as const;

package/src/sessions/addSessionNote.ts

@@ -1,5 +1,8 @@
 import { createClient } from "../client";
-import { ADD_SESSION_NOTE } from "../constants/serverRequirements";
+import {
+  ADD_SESSION_NOTE,
+  ADD_SESSION_NOTE_IDENTIFIER,
+} from "../constants/serverRequirements";
 import type { ClientFn } from "../types/core";
 import { formatApiError } from "../utils/apiErrorUtils";
 import { ensureServerCapability } from "../utils/serverVersionUtils";
@@ -16,6 +19,13 @@ export interface SessionNote {
    * The note text to add to the session.
    */
   note: string;
+  /**
+   * Optional caller-supplied identifier. When non-empty, the note is upserted
+   * on `(sessionId, name='note', identifier)` — repeated calls with the same
+   * identifier overwrite the existing note. When omitted, the server stamps a
+   * unique `px-session-note:<uuid>` identifier so each call appends a new note.
+   */
+  identifier?: string;
 }
 
 /**
@@ -28,8 +38,10 @@ export interface AddSessionNoteParams extends ClientFn {
 /**
  * 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.
+ * When `sessionNote.identifier` is omitted, each call appends a new note with
+ * an auto-generated identifier. When `identifier` is non-empty, repeated calls
+ * with the same `(sessionId, name='note', identifier)` overwrite the existing
+ * note.
  *
  * @param params - The parameters to add a session note.
  * @returns The ID of the created note annotation.
@@ -52,12 +64,19 @@ export async function addSessionNote({
 }: AddSessionNoteParams): Promise<{ id: string }> {
   const client = _client ?? createClient();
   await ensureServerCapability({ client, requirement: ADD_SESSION_NOTE });
+  if (sessionNote.identifier) {
+    await ensureServerCapability({
+      client,
+      requirement: ADD_SESSION_NOTE_IDENTIFIER,
+    });
+  }
 
   const { data, error } = await client.POST("/v1/session_notes", {
     body: {
       data: {
         session_id: sessionNote.sessionId.trim(),
         note: sessionNote.note,
+        identifier: sessionNote.identifier,
       },
     },
   });

package/src/spans/addSpanNote.ts

@@ -1,6 +1,8 @@
 import { createClient } from "../client";
+import { ADD_SPAN_NOTE_IDENTIFIER } from "../constants/serverRequirements";
 import type { ClientFn } from "../types/core";
 import { formatApiError } from "../utils/apiErrorUtils";
+import { ensureServerCapability } from "../utils/serverVersionUtils";
 
 /**
  * Parameters for a single span note
@@ -14,6 +16,13 @@ export interface SpanNote {
    * The note text to add to the span
    */
   note: string;
+  /**
+   * Optional caller-supplied identifier. When non-empty, the note is upserted
+   * on `(spanId, name='note', identifier)` — repeated calls with the same
+   * identifier overwrite the existing note. When omitted, the server stamps a
+   * unique `px-span-note:<uuid>` identifier so each call appends a new note.
+   */
+  identifier?: string;
 }
 
 /**
@@ -26,11 +35,10 @@ export interface AddSpanNoteParams extends ClientFn {
 /**
  * Add a note to a span.
  *
- * 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.
+ * When `spanNote.identifier` is omitted, each call appends a new note with an
+ * auto-generated identifier. When `identifier` is non-empty, repeated calls
+ * with the same `(spanId, name='note', identifier)` overwrite the existing
+ * note.
  *
  * @param params - The parameters to add a span note
  * @returns The ID of the created note annotation
@@ -50,12 +58,19 @@ export async function addSpanNote({
   spanNote,
 }: AddSpanNoteParams): Promise<{ id: string }> {
   const client = _client ?? createClient();
+  if (spanNote.identifier) {
+    await ensureServerCapability({
+      client,
+      requirement: ADD_SPAN_NOTE_IDENTIFIER,
+    });
+  }
 
   const { data, error } = await client.POST("/v1/span_notes", {
     body: {
       data: {
         span_id: spanNote.spanId.trim(),
         note: spanNote.note,
+        identifier: spanNote.identifier,
       },
     },
   });

package/src/spans/getSpanAnnotations.ts

@@ -12,7 +12,7 @@ export interface GetSpanAnnotationsParams extends ClientFn {
   project: ProjectIdentifier;
   /** One or more span IDs to fetch annotations for */
   spanIds: string[];
-  /** 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. */
+  /** Optional list of annotation names to include. If provided, only annotations with these names will be returned (allowlist). When omitted, the response includes every matching row regardless of name (no annotation names are excluded by default). */
   includeAnnotationNames?: string[];
   /** Optional list of annotation names to exclude from results. */
   excludeAnnotationNames?: string[];

package/src/traces/addTraceNote.ts

@@ -1,5 +1,8 @@
 import { createClient } from "../client";
-import { ADD_TRACE_NOTE } from "../constants/serverRequirements";
+import {
+  ADD_TRACE_NOTE,
+  ADD_TRACE_NOTE_IDENTIFIER,
+} from "../constants/serverRequirements";
 import type { ClientFn } from "../types/core";
 import { formatApiError } from "../utils/apiErrorUtils";
 import { ensureServerCapability } from "../utils/serverVersionUtils";
@@ -16,6 +19,13 @@ export interface TraceNote {
    * The note text to add to the trace.
    */
   note: string;
+  /**
+   * Optional caller-supplied identifier. When non-empty, the note is upserted
+   * on `(traceId, name='note', identifier)` — repeated calls with the same
+   * identifier overwrite the existing note. When omitted, the server stamps a
+   * unique `px-trace-note:<uuid>` identifier so each call appends a new note.
+   */
+  identifier?: string;
 }
 
 /**
@@ -28,11 +38,10 @@ export interface AddTraceNoteParams extends ClientFn {
 /**
  * Add a note to a trace.
  *
- * 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.
+ * When `traceNote.identifier` is omitted, each call appends a new note with an
+ * auto-generated identifier. When `identifier` is non-empty, repeated calls
+ * with the same `(traceId, name='note', identifier)` overwrite the existing
+ * note.
  *
  * @param params - The parameters to add a trace note.
  * @returns The ID of the created note annotation.
@@ -53,12 +62,19 @@ export async function addTraceNote({
 }: AddTraceNoteParams): Promise<{ id: string }> {
   const client = _client ?? createClient();
   await ensureServerCapability({ client, requirement: ADD_TRACE_NOTE });
+  if (traceNote.identifier) {
+    await ensureServerCapability({
+      client,
+      requirement: ADD_TRACE_NOTE_IDENTIFIER,
+    });
+  }
 
   const { data, error } = await client.POST("/v1/trace_notes", {
     body: {
       data: {
         trace_id: traceNote.traceId.trim(),
         note: traceNote.note,
+        identifier: traceNote.identifier,
       },
     },
   });