@arizeai/phoenix-client 6.8.0 → 6.8.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arizeai/phoenix-client",
-  "version": "6.8.0",
+  "version": "6.8.1",
   "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-otel": "1.0.0",
-    "@arizeai/phoenix-config": "0.1.3"
+    "@arizeai/phoenix-config": "0.1.3",
+    "@arizeai/phoenix-otel": "1.0.0"
   },
   "devDependencies": {
     "@ai-sdk/openai": "^3.0.29",

package/src/__generated__/api/v1.ts

@@ -214,6 +214,23 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/v1/datasets/{id}/jsonl": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** Download dataset examples as JSONL file */
+        get: operations["getDatasetJSONL"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/v1/datasets/{id}/jsonl/openai_ft": {
         parameters: {
             query?: never;
@@ -914,6 +931,26 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/v1/session_notes": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        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.
+         */
+        post: operations["createSessionNote"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/v1/document_annotations": {
         parameters: {
             query?: never;
@@ -1285,6 +1322,14 @@ export interface components {
         CreatePromptResponseBody: {
             data: components["schemas"]["PromptVersion"];
         };
+        /** CreateSessionNoteRequestBody */
+        CreateSessionNoteRequestBody: {
+            data: components["schemas"]["SessionNoteData"];
+        };
+        /** CreateSessionNoteResponseBody */
+        CreateSessionNoteResponseBody: {
+            data: components["schemas"]["InsertedSessionAnnotation"];
+        };
         /** CreateSpanNoteRequestBody */
         CreateSpanNoteRequestBody: {
             data: components["schemas"]["SpanNoteData"];
@@ -1363,6 +1408,8 @@ export interface components {
         DatasetExample: {
             /** Id */
             id: string;
+            /** Node Id */
+            node_id: string;
             /** Input */
             input: {
                 [key: string]: unknown;
@@ -2215,8 +2262,34 @@ export interface components {
             top_p?: number;
             /** Stop Sequences */
             stop_sequences?: string[];
+            output_config?: components["schemas"]["PromptAnthropicOutputConfig"];
             /** Thinking */
-            thinking?: components["schemas"]["PromptAnthropicThinkingConfigDisabled"] | components["schemas"]["PromptAnthropicThinkingConfigEnabled"];
+            thinking?: components["schemas"]["PromptAnthropicThinkingConfigDisabled"] | components["schemas"]["PromptAnthropicThinkingConfigEnabled"] | components["schemas"]["PromptAnthropicThinkingConfigAdaptive"];
+            /** Extra Body */
+            extra_body?: {
+                [key: string]: unknown;
+            };
+        };
+        /** PromptAnthropicOutputConfig */
+        PromptAnthropicOutputConfig: {
+            /**
+             * Effort
+             * @enum {string}
+             */
+            effort?: "low" | "medium" | "high" | "xhigh" | "max";
+        };
+        /** PromptAnthropicThinkingConfigAdaptive */
+        PromptAnthropicThinkingConfigAdaptive: {
+            /**
+             * @description discriminator enum property added by openapi-typescript
+             * @enum {string}
+             */
+            type: "adaptive";
+            /**
+             * Display
+             * @enum {string}
+             */
+            display?: "summarized" | "omitted";
         };
         /** PromptAnthropicThinkingConfigDisabled */
         PromptAnthropicThinkingConfigDisabled: {
@@ -2235,6 +2308,11 @@ export interface components {
             type: "enabled";
             /** Budget Tokens */
             budget_tokens: number;
+            /**
+             * Display
+             * @enum {string}
+             */
+            display?: "summarized" | "omitted";
         };
         /** PromptAwsInvocationParameters */
         PromptAwsInvocationParameters: {
@@ -2253,6 +2331,8 @@ export interface components {
             temperature?: number;
             /** Top P */
             top_p?: number;
+            /** Stop Sequences */
+            stop_sequences?: string[];
         };
         /** PromptAzureOpenAIInvocationParameters */
         PromptAzureOpenAIInvocationParameters: {
@@ -2279,11 +2359,17 @@ export interface components {
             top_p?: number;
             /** Seed */
             seed?: number;
+            /** Stop */
+            stop?: string[];
             /**
              * Reasoning Effort
              * @enum {string}
              */
             reasoning_effort?: "none" | "minimal" | "low" | "medium" | "high" | "xhigh";
+            /** Extra Body */
+            extra_body?: {
+                [key: string]: unknown;
+            };
         };
         /** PromptCerebrasInvocationParameters */
         PromptCerebrasInvocationParameters: {
@@ -2310,11 +2396,17 @@ export interface components {
             top_p?: number;
             /** Seed */
             seed?: number;
+            /** Stop */
+            stop?: string[];
             /**
              * Reasoning Effort
              * @enum {string}
              */
             reasoning_effort?: "none" | "minimal" | "low" | "medium" | "high" | "xhigh";
+            /** Extra Body */
+            extra_body?: {
+                [key: string]: unknown;
+            };
         };
         /** PromptChatTemplate */
         PromptChatTemplate: {
@@ -2363,11 +2455,17 @@ export interface components {
             top_p?: number;
             /** Seed */
             seed?: number;
+            /** Stop */
+            stop?: string[];
             /**
              * Reasoning Effort
              * @enum {string}
              */
             reasoning_effort?: "none" | "minimal" | "low" | "medium" | "high" | "xhigh";
+            /** Extra Body */
+            extra_body?: {
+                [key: string]: unknown;
+            };
         };
         /** PromptFireworksInvocationParameters */
         PromptFireworksInvocationParameters: {
@@ -2394,11 +2492,17 @@ export interface components {
             top_p?: number;
             /** Seed */
             seed?: number;
+            /** Stop */
+            stop?: string[];
             /**
              * Reasoning Effort
              * @enum {string}
              */
             reasoning_effort?: "none" | "minimal" | "low" | "medium" | "high" | "xhigh";
+            /** Extra Body */
+            extra_body?: {
+                [key: string]: unknown;
+            };
         };
         /** PromptGoogleInvocationParameters */
         PromptGoogleInvocationParameters: {
@@ -2425,6 +2529,19 @@ export interface components {
             top_p?: number;
             /** Top K */
             top_k?: number;
+            thinking_config?: components["schemas"]["PromptGoogleThinkingConfig"];
+        };
+        /** PromptGoogleThinkingConfig */
+        PromptGoogleThinkingConfig: {
+            /** Thinking Budget */
+            thinking_budget?: number;
+            /**
+             * Thinking Level
+             * @enum {string}
+             */
+            thinking_level?: "minimal" | "low" | "medium" | "high";
+            /** Include Thoughts */
+            include_thoughts?: boolean;
         };
         /** PromptGroqInvocationParameters */
         PromptGroqInvocationParameters: {
@@ -2451,11 +2568,17 @@ export interface components {
             top_p?: number;
             /** Seed */
             seed?: number;
+            /** Stop */
+            stop?: string[];
             /**
              * Reasoning Effort
              * @enum {string}
              */
             reasoning_effort?: "none" | "minimal" | "low" | "medium" | "high" | "xhigh";
+            /** Extra Body */
+            extra_body?: {
+                [key: string]: unknown;
+            };
         };
         /** PromptMessage */
         PromptMessage: {
@@ -2492,11 +2615,17 @@ export interface components {
             top_p?: number;
             /** Seed */
             seed?: number;
+            /** Stop */
+            stop?: string[];
             /**
              * Reasoning Effort
              * @enum {string}
              */
             reasoning_effort?: "none" | "minimal" | "low" | "medium" | "high" | "xhigh";
+            /** Extra Body */
+            extra_body?: {
+                [key: string]: unknown;
+            };
         };
         /** PromptOllamaInvocationParameters */
         PromptOllamaInvocationParameters: {
@@ -2523,11 +2652,17 @@ export interface components {
             top_p?: number;
             /** Seed */
             seed?: number;
+            /** Stop */
+            stop?: string[];
             /**
              * Reasoning Effort
              * @enum {string}
              */
             reasoning_effort?: "none" | "minimal" | "low" | "medium" | "high" | "xhigh";
+            /** Extra Body */
+            extra_body?: {
+                [key: string]: unknown;
+            };
         };
         /** PromptOpenAIInvocationParameters */
         PromptOpenAIInvocationParameters: {
@@ -2554,11 +2689,17 @@ export interface components {
             top_p?: number;
             /** Seed */
             seed?: number;
+            /** Stop */
+            stop?: string[];
             /**
              * Reasoning Effort
              * @enum {string}
              */
             reasoning_effort?: "none" | "minimal" | "low" | "medium" | "high" | "xhigh";
+            /** Extra Body */
+            extra_body?: {
+                [key: string]: unknown;
+            };
         };
         /** PromptPerplexityInvocationParameters */
         PromptPerplexityInvocationParameters: {
@@ -2585,11 +2726,17 @@ export interface components {
             top_p?: number;
             /** Seed */
             seed?: number;
+            /** Stop */
+            stop?: string[];
             /**
              * Reasoning Effort
              * @enum {string}
              */
             reasoning_effort?: "none" | "minimal" | "low" | "medium" | "high" | "xhigh";
+            /** Extra Body */
+            extra_body?: {
+                [key: string]: unknown;
+            };
         };
         /** PromptResponseFormatJSONSchema */
         PromptResponseFormatJSONSchema: {
@@ -2658,11 +2805,17 @@ export interface components {
             top_p?: number;
             /** Seed */
             seed?: number;
+            /** Stop */
+            stop?: string[];
             /**
              * Reasoning Effort
              * @enum {string}
              */
             reasoning_effort?: "none" | "minimal" | "low" | "medium" | "high" | "xhigh";
+            /** Extra Body */
+            extra_body?: {
+                [key: string]: unknown;
+            };
         };
         /** PromptToolChoiceNone */
         PromptToolChoiceNone: {
@@ -2809,11 +2962,17 @@ export interface components {
             top_p?: number;
             /** Seed */
             seed?: number;
+            /** Stop */
+            stop?: string[];
             /**
              * Reasoning Effort
              * @enum {string}
              */
             reasoning_effort?: "none" | "minimal" | "low" | "medium" | "high" | "xhigh";
+            /** Extra Body */
+            extra_body?: {
+                [key: string]: unknown;
+            };
         };
         /** ResponseBody[UpsertOrDeleteSecretsResult] */
         ResponseBody_UpsertOrDeleteSecretsResult_: {
@@ -2947,6 +3106,19 @@ export interface components {
             /** Traces */
             traces: components["schemas"]["SessionTraceData"][];
         };
+        /** SessionNoteData */
+        SessionNoteData: {
+            /**
+             * Session Id
+             * @description Session ID
+             */
+            session_id: string;
+            /**
+             * Note
+             * @description The note text to add to the session
+             */
+            note: string;
+        };
         /** SessionTraceData */
         SessionTraceData: {
             /** Id */
@@ -3468,6 +3640,12 @@ export interface components {
             dataset_id: string;
             /** Version Id */
             version_id: string;
+            /** Num Created Examples */
+            num_created_examples: number;
+            /** Num Updated Examples */
+            num_updated_examples: number;
+            /** Num Deleted Examples */
+            num_deleted_examples: number;
         };
         /** UploadDatasetResponseBody */
         UploadDatasetResponseBody: {
@@ -4173,7 +4351,7 @@ export interface operations {
             content: {
                 "application/json": {
                     /** @enum {string} */
-                    action?: "create" | "append";
+                    action?: "create" | "append" | "update";
                     name: string;
                     description?: string;
                     inputs: Record<string, unknown>[];
@@ -4183,21 +4361,27 @@ export interface operations {
                     splits?: (string | string[] | null)[];
                     /** @description Span IDs to link examples back to spans */
                     span_ids?: (string | null)[];
+                    /** @description Optional example ID per example. If provided, it is used as the example's stable public ID. */
+                    example_ids?: (string | null)[];
                 };
                 "multipart/form-data": {
                     /** @enum {string} */
-                    action?: "create" | "append";
+                    action?: "create" | "append" | "update";
                     name: string;
                     description?: string;
                     "input_keys[]": string[];
                     "output_keys[]": string[];
                     "metadata_keys[]"?: string[];
-                    /** @description Column names for auto-assigning examples to splits */
+                    /** @description Deprecated: use split_key instead. Column names for auto-assigning examples to splits */
                     "split_keys[]"?: string[];
+                    /** @description Single column name containing split names (plain string or JSON list) per row */
+                    split_key?: string;
                     /** @description Column names whose object values should be flattened into their selected bucket */
                     "flatten_keys[]"?: string[];
                     /** @description Column name for span IDs to link examples back to spans */
                     span_id_key?: string;
+                    /** @description Column name containing stable IDs for examples. When provided, examples with matching IDs are updated in place when their content changes. */
+                    example_id_key?: string;
                     /** Format: binary */
                     file: string;
                 };
@@ -4222,7 +4406,7 @@ export interface operations {
                     "text/plain": string;
                 };
             };
-            /** @description Dataset of the same name already exists */
+            /** @description Dataset with the given name already exists (action=create). */
             409: {
                 headers: {
                     [name: string]: unknown;
@@ -4341,6 +4525,50 @@ export interface operations {
             };
         };
     };
+    getDatasetJSONL: {
+        parameters: {
+            query?: {
+                /** @description The ID of the dataset version (if omitted, returns data from the latest version) */
+                version_id?: string | null;
+            };
+            header?: never;
+            path: {
+                /** @description The ID of the dataset */
+                id: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Successful Response */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "text/plain": string;
+                };
+            };
+            /** @description Forbidden */
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "text/plain": string;
+                };
+            };
+            /** @description Invalid dataset or version ID */
+            422: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "text/plain": string;
+                };
+            };
+        };
+    };
     getDatasetJSONLOpenAIFineTuning: {
         parameters: {
             query?: {
@@ -6565,6 +6793,57 @@ export interface operations {
             };
         };
     };
+    createSessionNote: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["CreateSessionNoteRequestBody"];
+            };
+        };
+        responses: {
+            /** @description Session note created successfully */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["CreateSessionNoteResponseBody"];
+                };
+            };
+            /** @description Forbidden */
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "text/plain": string;
+                };
+            };
+            /** @description Session 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"];
+                };
+            };
+        };
+    };
     annotateSpanDocuments: {
         parameters: {
             query?: {

package/src/constants/serverRequirements.ts

@@ -91,6 +91,14 @@ export const GET_SPANS_BY_ATTRIBUTE: ParameterRequirement = {
   minServerVersion: [14, 9, 0],
 };
 
+export const DATASET_UPLOAD_EXAMPLE_IDS: ParameterRequirement = {
+  kind: "parameter",
+  parameterName: "example_ids",
+  parameterLocation: "body",
+  route: "POST /v1/datasets/upload",
+  minServerVersion: [15, 0, 0],
+};
+
 /**
  * Aggregate list of every known capability requirement.
  *
@@ -108,4 +116,5 @@ export const ALL_REQUIREMENTS: readonly CapabilityRequirement[] = [
   GET_SPANS_FILTERS,
   GET_SPANS_BY_ATTRIBUTE,
   LIST_PROJECT_TRACES,
+  DATASET_UPLOAD_EXAMPLE_IDS,
 ] as const;

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,
   };
 }