@arizeai/phoenix-client 7.7.0 → 7.8.0

package/docs/sessions.mdx

@@ -29,10 +29,19 @@ const sessions = await listSessions({
 });
 
 for (const session of sessions) {
-  console.log(session.sessionId);
+  console.log({
+    sessionId: session.sessionId,
+    promptTokens: session.tokenCountPrompt,
+    completionTokens: session.tokenCountCompletion,
+    totalTokens: session.tokenCountTotal,
+  });
 }
 ```
 
+Each session includes cumulative prompt, completion, and total token counts across
+all of its spans. The fields may be `undefined` when using a Phoenix server that
+does not return session token usage.
+
 ## Retrieve A Session And Its Turns
 
 ```ts

package/package.json

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

package/src/__generated__/api/v1.ts

@@ -761,7 +761,11 @@ export interface paths {
         get: operations["listProjectTraces"];
         put?: never;
         post?: never;
-        delete?: never;
+        /**
+         * Delete traces from a project
+         * @description Delete traces from a project without deleting the project or its configuration. Only traces whose start time is within the required `[start_time, end_time)` interval are deleted. Associated spans are cascade deleted, and project sessions left with no remaining traces are also deleted. Naive datetimes are interpreted as UTC.
+         */
+        delete: operations["deleteProjectTraces"];
         options?: never;
         head?: never;
         patch?: never;
@@ -1568,7 +1572,7 @@ export interface paths {
         put?: never;
         /**
          * OpenAI-compatible chat completions
-         * @description Creates a chat completion using the OpenAI wire format, proxying to the selected provider with credentials resolved on the server (secret store first, environment second) — callers never handle provider API keys. Model must be '{provider}:{model_name}' for a built-in provider (one of anthropic, aws, azure_openai, cerebras, deepseek, fireworks, google, groq, moonshot, ollama, openai, perplexity, together, xai) or 'custom:{provider_id}:{model_name}' for a stored custom provider, e.g. 'openai:gpt-4o' or 'anthropic:claude-sonnet-4-5'. Set `stream: true` for server-sent events of `chat.completion.chunk` payloads terminated by `data: [DONE]`. Tool calling is not supported.
+         * @description Creates a chat completion using the OpenAI wire format, proxying to the selected provider with credentials resolved on the server (secret store first, environment second) — callers never handle provider API keys. Model must be '{provider}:{model_name}' for a built-in provider (one of anthropic, aws, azure_openai, cerebras, deepseek, fireworks, google, groq, moonshot, ollama, openai, perplexity, together, xai, zai) or 'custom:{provider_id}:{model_name}' for a stored custom provider, e.g. 'openai:gpt-4o' or 'anthropic:claude-sonnet-4-5'. Set `stream: true` for server-sent events of `chat.completion.chunk` payloads terminated by `data: [DONE]`. Tool calling is not supported.
          *
          *     **Phoenix is not an AI gateway.** The same server also takes on trace ingestion traffic, so routing production LLM calls through it competes with ingestion. Use this endpoint only to quickly try out different models in non-production environments.
          */
@@ -2424,6 +2428,11 @@ export interface components {
              * @description The id of the last transcript message the client has rendered, used for optimistic concurrency. Omit when the session has no messages; required (and validated against the persisted transcript) once it does. On mismatch the server rejects the send with HTTP 409 and code ``agent_session_messages_stale`` — the client should refetch the session before retrying.
              */
             lastMessageId?: string | null;
+            /**
+             * Credentials
+             * @description Client-held credentials for optional integrations (e.g. the user's own GitHub personal access token under the key ``GITHUB_PERSONAL_ACCESS_TOKEN``), used only for the duration of the turn and never persisted. Unknown keys are rejected.
+             */
+            credentials?: components["schemas"]["ChatRequestCredential"][];
             /**
              * Recordlocaltraces
              * @default false
@@ -2441,6 +2450,28 @@ export interface components {
              */
             instrumentUserId?: boolean;
         };
+        /**
+         * ChatRequestCredential
+         * @description One client-held credential riding the request for the duration of a turn.
+         *
+         *     The value is ephemeral: it is injected server-side as transport auth for
+         *     the matching integration and is never persisted, traced, or echoed. It is
+         *     top-level on the request body — never part of the message — so it cannot
+         *     reach the session transcript.
+         */
+        ChatRequestCredential: {
+            /**
+             * Key
+             * @description The credential's secret-key name.
+             * @constant
+             */
+            key: "GITHUB_PERSONAL_ACCESS_TOKEN";
+            /**
+             * Value
+             * Format: password
+             */
+            value: string;
+        };
         /** CodeEvaluatorUIContext */
         CodeEvaluatorUIContext: {
             /**
@@ -2561,7 +2592,7 @@ export interface components {
         CreateChatCompletionRequestBody: {
             /**
              * Model
-             * @description Model must be '{provider}:{model_name}' for a built-in provider (one of anthropic, aws, azure_openai, cerebras, deepseek, fireworks, google, groq, moonshot, ollama, openai, perplexity, together, xai) or 'custom:{provider_id}:{model_name}' for a stored custom provider, e.g. 'openai:gpt-4o' or 'anthropic:claude-sonnet-4-5'.
+             * @description Model must be '{provider}:{model_name}' for a built-in provider (one of anthropic, aws, azure_openai, cerebras, deepseek, fireworks, google, groq, moonshot, ollama, openai, perplexity, together, xai, zai) or 'custom:{provider_id}:{model_name}' for a stored custom provider, e.g. 'openai:gpt-4o' or 'anthropic:claude-sonnet-4-5'.
              */
             model: string;
             /** Messages */
@@ -4057,7 +4088,7 @@ export interface components {
          * ModelProvider
          * @enum {string}
          */
-        ModelProvider: "OPENAI" | "AZURE_OPENAI" | "ANTHROPIC" | "GOOGLE" | "DEEPSEEK" | "XAI" | "OLLAMA" | "AWS" | "CEREBRAS" | "FIREWORKS" | "GROQ" | "MOONSHOT" | "PERPLEXITY" | "TOGETHER";
+        ModelProvider: "OPENAI" | "AZURE_OPENAI" | "ANTHROPIC" | "GOOGLE" | "DEEPSEEK" | "XAI" | "OLLAMA" | "AWS" | "CEREBRAS" | "FIREWORKS" | "GROQ" | "MOONSHOT" | "PERPLEXITY" | "TOGETHER" | "ZAI";
         /** OAuth2User */
         OAuth2User: {
             /** Id */
@@ -5236,7 +5267,7 @@ export interface components {
             template_type: components["schemas"]["PromptTemplateType"];
             template_format: components["schemas"]["PromptTemplateFormat"];
             /** Invocation Parameters */
-            invocation_parameters: components["schemas"]["PromptOpenAIInvocationParameters"] | components["schemas"]["PromptAzureOpenAIInvocationParameters"] | components["schemas"]["PromptAnthropicInvocationParameters"] | components["schemas"]["PromptGoogleInvocationParameters"] | components["schemas"]["PromptDeepSeekInvocationParameters"] | components["schemas"]["PromptXAIInvocationParameters"] | components["schemas"]["PromptOllamaInvocationParameters"] | components["schemas"]["PromptAwsInvocationParameters"] | components["schemas"]["PromptCerebrasInvocationParameters"] | components["schemas"]["PromptFireworksInvocationParameters"] | components["schemas"]["PromptGroqInvocationParameters"] | components["schemas"]["PromptMoonshotInvocationParameters"] | components["schemas"]["PromptPerplexityInvocationParameters"] | components["schemas"]["PromptTogetherInvocationParameters"];
+            invocation_parameters: components["schemas"]["PromptOpenAIInvocationParameters"] | components["schemas"]["PromptAzureOpenAIInvocationParameters"] | components["schemas"]["PromptAnthropicInvocationParameters"] | components["schemas"]["PromptGoogleInvocationParameters"] | components["schemas"]["PromptDeepSeekInvocationParameters"] | components["schemas"]["PromptXAIInvocationParameters"] | components["schemas"]["PromptOllamaInvocationParameters"] | components["schemas"]["PromptAwsInvocationParameters"] | components["schemas"]["PromptCerebrasInvocationParameters"] | components["schemas"]["PromptFireworksInvocationParameters"] | components["schemas"]["PromptGroqInvocationParameters"] | components["schemas"]["PromptMoonshotInvocationParameters"] | components["schemas"]["PromptPerplexityInvocationParameters"] | components["schemas"]["PromptTogetherInvocationParameters"] | components["schemas"]["PromptZAIInvocationParameters"];
             tools?: components["schemas"]["PromptTools"] | null;
             /** Response Format */
             response_format?: components["schemas"]["PromptResponseFormatJSONSchema"] | null;
@@ -5255,7 +5286,7 @@ export interface components {
             template_type: components["schemas"]["PromptTemplateType"];
             template_format: components["schemas"]["PromptTemplateFormat"];
             /** Invocation Parameters */
-            invocation_parameters: components["schemas"]["PromptOpenAIInvocationParameters"] | components["schemas"]["PromptAzureOpenAIInvocationParameters"] | components["schemas"]["PromptAnthropicInvocationParameters"] | components["schemas"]["PromptGoogleInvocationParameters"] | components["schemas"]["PromptDeepSeekInvocationParameters"] | components["schemas"]["PromptXAIInvocationParameters"] | components["schemas"]["PromptOllamaInvocationParameters"] | components["schemas"]["PromptAwsInvocationParameters"] | components["schemas"]["PromptCerebrasInvocationParameters"] | components["schemas"]["PromptFireworksInvocationParameters"] | components["schemas"]["PromptGroqInvocationParameters"] | components["schemas"]["PromptMoonshotInvocationParameters"] | components["schemas"]["PromptPerplexityInvocationParameters"] | components["schemas"]["PromptTogetherInvocationParameters"];
+            invocation_parameters: components["schemas"]["PromptOpenAIInvocationParameters"] | components["schemas"]["PromptAzureOpenAIInvocationParameters"] | components["schemas"]["PromptAnthropicInvocationParameters"] | components["schemas"]["PromptGoogleInvocationParameters"] | components["schemas"]["PromptDeepSeekInvocationParameters"] | components["schemas"]["PromptXAIInvocationParameters"] | components["schemas"]["PromptOllamaInvocationParameters"] | components["schemas"]["PromptAwsInvocationParameters"] | components["schemas"]["PromptCerebrasInvocationParameters"] | components["schemas"]["PromptFireworksInvocationParameters"] | components["schemas"]["PromptGroqInvocationParameters"] | components["schemas"]["PromptMoonshotInvocationParameters"] | components["schemas"]["PromptPerplexityInvocationParameters"] | components["schemas"]["PromptTogetherInvocationParameters"] | components["schemas"]["PromptZAIInvocationParameters"];
             tools?: components["schemas"]["PromptTools"] | null;
             /** Response Format */
             response_format?: components["schemas"]["PromptResponseFormatJSONSchema"] | null;
@@ -5323,6 +5354,43 @@ export interface components {
                 [key: string]: unknown;
             };
         };
+        /** PromptZAIInvocationParameters */
+        PromptZAIInvocationParameters: {
+            /**
+             * @description discriminator enum property added by openapi-typescript
+             * @enum {string}
+             */
+            type: "zai";
+            zai: components["schemas"]["PromptZAIInvocationParametersContent"];
+        };
+        /** PromptZAIInvocationParametersContent */
+        PromptZAIInvocationParametersContent: {
+            /** Temperature */
+            temperature?: number;
+            /** Max Tokens */
+            max_tokens?: number;
+            /** Max Completion Tokens */
+            max_completion_tokens?: number;
+            /** Frequency Penalty */
+            frequency_penalty?: number;
+            /** Presence Penalty */
+            presence_penalty?: number;
+            /** Top P */
+            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;
+            };
+        };
         /**
          * PydanticAIMessageMetadata
          * @description Local pin of pydantic-ai's message-level ``pydantic_ai`` metadata
@@ -10041,6 +10109,59 @@ export interface operations {
             };
         };
     };
+    deleteProjectTraces: {
+        parameters: {
+            query: {
+                /** @description Required inclusive lower bound on trace start time (ISO 8601). */
+                start_time: string;
+                /** @description Required exclusive upper bound on trace start time (ISO 8601). */
+                end_time: string;
+            };
+            header?: never;
+            path: {
+                /** @description The project identifier: either project ID or project name. */
+                project_identifier: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description No content returned after the matching traces are deleted */
+            204: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description Forbidden */
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "text/plain": string;
+                };
+            };
+            /** @description Not Found */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "text/plain": string;
+                };
+            };
+            /** @description Unprocessable Entity */
+            422: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "text/plain": string;
+                };
+            };
+        };
+    };
     annotateTraces: {
         parameters: {
             query?: {

package/src/experiments/resumeEvaluation.ts

@@ -301,6 +301,71 @@ function setupEvaluationTracer({
  * });
  * ```
  */
+function isEmptyEvaluationBatch({
+  batchLength,
+  totalProcessed,
+  logger,
+}: {
+  batchLength: number;
+  totalProcessed: number;
+  logger: Logger;
+}): boolean {
+  if (batchLength > 0) return false;
+  if (totalProcessed === 0) {
+    logger.info(`${PROGRESS_PREFIX.completed}No incomplete evaluations found.`);
+  }
+  return true;
+}
+
+function shouldContinueEvaluationFetch({
+  cursor,
+  signal,
+}: {
+  cursor: string | null;
+  signal: AbortSignal;
+}): boolean {
+  return cursor !== null && !signal.aborted;
+}
+
+function getEvaluationExecutionError({
+  rejections,
+  isAborted,
+  logger,
+}: {
+  rejections: unknown[];
+  isAborted: boolean;
+  logger: Logger;
+}): Error | null {
+  if (rejections.length === 0) return null;
+  const fetchError = rejections.find(
+    (reason) => reason instanceof EvaluationFetchError
+  );
+  if (fetchError instanceof Error) {
+    logger.error(`Critical: Failed to fetch evaluations from server`);
+    return fetchError;
+  }
+  const workerError = rejections.find(
+    (reason) =>
+      reason instanceof Error &&
+      !(reason instanceof EvaluationFetchError) &&
+      !(reason instanceof ChannelError)
+  );
+  if (workerError instanceof Error) return workerError;
+  const channelError = rejections.find(
+    (reason) => reason instanceof ChannelError
+  );
+  if (channelError instanceof Error && isAborted) {
+    return new EvaluationAbortedError(
+      "Evaluation stopped due to error in concurrent evaluator",
+      channelError
+    );
+  }
+  const reason = rejections[0];
+  const error = reason instanceof Error ? reason : new Error(String(reason));
+  logger.error(`Unexpected error during evaluation: ${error.message}`);
+  return error;
+}
+
 export async function resumeEvaluation({
   client: _client,
   experimentId,
@@ -425,12 +490,13 @@ export async function resumeEvaluation({
           const batchIncomplete = res.data?.data;
           invariant(batchIncomplete, "Failed to fetch incomplete evaluations");
 
-          if (batchIncomplete.length === 0) {
-            if (totalProcessed === 0) {
-              logger.info(
-                `${PROGRESS_PREFIX.completed}No incomplete evaluations found.`
-              );
-            }
+          if (
+            isEmptyEvaluationBatch({
+              batchLength: batchIncomplete.length,
+              totalProcessed,
+              logger,
+            })
+          ) {
             break;
           }
 
@@ -468,7 +534,7 @@ export async function resumeEvaluation({
           logger.debug(
             `${PROGRESS_PREFIX.progress}Fetched batch of ${batchCount} evaluation tasks.`
           );
-        } while (cursor !== null && !signal.aborted);
+        } while (shouldContinueEvaluationFetch({ cursor, signal }));
       } catch (error) {
         // Re-throw with context preservation
         if (error instanceof EvaluationFetchError) {
@@ -547,47 +613,11 @@ export async function resumeEvaluation({
         )
         .map((result) => result.reason);
 
-      if (rejections.length > 0) {
-        // Classify and handle errors based on their nature. When multiple tasks
-        // reject, prefer the most meaningful error over incidental fallout
-        // (e.g. a ChannelError raised in a blocked worker when the channel
-        // closes on abort).
-        const fetchError = rejections.find(
-          (reason) => reason instanceof EvaluationFetchError
-        );
-        const workerError = rejections.find(
-          (reason) =>
-            reason instanceof Error &&
-            !(reason instanceof EvaluationFetchError) &&
-            !(reason instanceof ChannelError)
-        );
-        const channelError = rejections.find(
-          (reason) => reason instanceof ChannelError
-        );
-
-        if (fetchError) {
-          // Producer failed - this is ALWAYS critical regardless of stopOnFirstError
-          logger.error(`Critical: Failed to fetch evaluations from server`);
-          executionError = fetchError;
-        } else if (workerError) {
-          // Worker error in stopOnFirstError mode - already logged by worker
-          executionError = workerError;
-        } else if (channelError && signal.aborted) {
-          // Channel closed due to intentional abort - wrap in semantic error
-          executionError = new EvaluationAbortedError(
-            "Evaluation stopped due to error in concurrent evaluator",
-            channelError
-          );
-        } else {
-          // Unexpected error (not from worker, not from producer fetch)
-          // This could be a bug in our code or infrastructure failure
-          const reason = rejections[0];
-          const err =
-            reason instanceof Error ? reason : new Error(String(reason));
-          logger.error(`Unexpected error during evaluation: ${err.message}`);
-          executionError = err;
-        }
-      }
+      executionError = getEvaluationExecutionError({
+        rejections,
+        isAborted: signal.aborted,
+        logger,
+      });
     } finally {
       // Ensure channel is closed even if there are unexpected errors
       // This is a safety net in case producer's finally block didn't execute

package/src/experiments/resumeExperiment.ts

@@ -276,6 +276,67 @@ function setupTracer({
  * });
  * ```
  */
+function getResumeEvaluators({
+  evaluators,
+  executionError,
+}: {
+  evaluators: readonly ExperimentEvaluatorLike[] | undefined;
+  executionError: Error | null;
+}): readonly ExperimentEvaluatorLike[] | null {
+  return evaluators && evaluators.length > 0 && !executionError
+    ? evaluators
+    : null;
+}
+
+function shouldWarnAboutFailedRuns({
+  totalFailed,
+  executionError,
+}: {
+  totalFailed: number;
+  executionError: Error | null;
+}): boolean {
+  return totalFailed > 0 && !executionError;
+}
+
+function getTaskExecutionError({
+  rejections,
+  isAborted,
+  logger,
+}: {
+  rejections: unknown[];
+  isAborted: boolean;
+  logger: Logger;
+}): Error | null {
+  if (rejections.length === 0) return null;
+  const fetchError = rejections.find(
+    (reason) => reason instanceof TaskFetchError
+  );
+  if (fetchError instanceof Error) {
+    logger.error(`Critical: Failed to fetch incomplete runs from server`);
+    return fetchError;
+  }
+  const taskError = rejections.find(
+    (reason) =>
+      reason instanceof Error &&
+      !(reason instanceof TaskFetchError) &&
+      !(reason instanceof ChannelError)
+  );
+  if (taskError instanceof Error) return taskError;
+  const channelError = rejections.find(
+    (reason) => reason instanceof ChannelError
+  );
+  if (channelError instanceof Error && isAborted) {
+    return new TaskAbortedError(
+      "Task execution stopped due to error in concurrent worker",
+      channelError
+    );
+  }
+  const reason = rejections[0];
+  const error = reason instanceof Error ? reason : new Error(String(reason));
+  logger.error(`Unexpected error during task execution: ${error.message}`);
+  return error;
+}
+
 export async function resumeExperiment({
   client: _client,
   experimentId,
@@ -514,49 +575,11 @@ export async function resumeExperiment({
         )
         .map((result) => result.reason);
 
-      if (rejections.length > 0) {
-        // Classify and handle errors based on their nature. When multiple tasks
-        // reject, prefer the most meaningful error over incidental fallout
-        // (e.g. a ChannelError raised in a blocked worker when the channel
-        // closes on abort).
-        const fetchError = rejections.find(
-          (reason) => reason instanceof TaskFetchError
-        );
-        const taskError = rejections.find(
-          (reason) =>
-            reason instanceof Error &&
-            !(reason instanceof TaskFetchError) &&
-            !(reason instanceof ChannelError)
-        );
-        const channelError = rejections.find(
-          (reason) => reason instanceof ChannelError
-        );
-
-        if (fetchError) {
-          // Producer failed - this is ALWAYS critical regardless of stopOnFirstError
-          logger.error(`Critical: Failed to fetch incomplete runs from server`);
-          executionError = fetchError;
-        } else if (taskError) {
-          // Worker error in stopOnFirstError mode - already logged by worker
-          executionError = taskError;
-        } else if (channelError && signal.aborted) {
-          // Channel closed due to intentional abort - wrap in semantic error
-          executionError = new TaskAbortedError(
-            "Task execution stopped due to error in concurrent worker",
-            channelError
-          );
-        } else {
-          // Unexpected error (not from worker, not from producer fetch)
-          // This could be a bug in our code or infrastructure failure
-          const reason = rejections[0];
-          const err =
-            reason instanceof Error ? reason : new Error(String(reason));
-          logger.error(
-            `Unexpected error during task execution: ${err.message}`
-          );
-          executionError = err;
-        }
-      }
+      executionError = getTaskExecutionError({
+        rejections,
+        isAborted: signal.aborted,
+        logger,
+      });
     } finally {
       // Ensure channel is closed even if there are unexpected errors
       // This is a safety net in case producer's finally block didn't execute
@@ -570,11 +593,15 @@ export async function resumeExperiment({
       logger.info(`${PROGRESS_PREFIX.completed}Task runs completed.`);
     }
 
-    if (totalFailed > 0 && !executionError) {
+    if (shouldWarnAboutFailedRuns({ totalFailed, executionError })) {
       logger.warn(`${totalFailed} out of ${totalProcessed} runs failed.`);
     }
 
-    if (evaluators && evaluators.length > 0 && !executionError) {
+    const resumeEvaluators = getResumeEvaluators({
+      evaluators,
+      executionError,
+    });
+    if (resumeEvaluators) {
       await cleanupOwnedTracerProvider({
         provider,
         globalRegistration,
@@ -585,7 +612,7 @@ export async function resumeExperiment({
       logger.info(`${PROGRESS_PREFIX.start}Running evaluators.`);
       await resumeEvaluation({
         experimentId,
-        evaluators: [...evaluators],
+        evaluators: [...resumeEvaluators],
         client,
         logger,
         concurrency,