@arizeai/phoenix-client 7.6.0 → 7.7.1

package/docs/overview.mdx

@@ -3,7 +3,7 @@ title: "Overview"
 description: "Typed TypeScript client for Phoenix platform APIs"
 ---
 
-`@arizeai/phoenix-client` is the typed TypeScript client for Phoenix platform APIs. It ships a small root REST client plus focused module entrypoints for prompts, datasets, experiments, spans, sessions, traces, and CI-friendly dataset-backed eval tests.
+`@arizeai/phoenix-client` is the typed TypeScript client for Phoenix platform APIs. It ships a small root REST client plus focused module entrypoints for projects, prompts, datasets, experiments, spans, sessions, traces, users, and CI-friendly dataset-backed eval tests.
 
 ## Install
 
@@ -37,12 +37,14 @@ That gives the agent version-matched docs plus the exact implementation and gene
 | Import | Purpose |
 |--------|---------|
 | `@arizeai/phoenix-client` | `createClient`, generated OpenAPI types, config helpers |
+| `@arizeai/phoenix-client/projects` | Project listing and retention-policy assignment |
 | `@arizeai/phoenix-client/prompts` | Prompt CRUD plus `toSDK` conversion |
 | `@arizeai/phoenix-client/datasets` | Dataset creation and retrieval |
 | `@arizeai/phoenix-client/experiments` | Experiment execution and lifecycle |
 | `@arizeai/phoenix-client/spans` | Span search, notes, and span/document annotations |
 | `@arizeai/phoenix-client/sessions` | Session listing, retrieval, and session annotations |
-| `@arizeai/phoenix-client/traces` | Project trace retrieval and trace annotations |
+| `@arizeai/phoenix-client/traces` | Project trace retrieval, transfers, and trace annotations |
+| `@arizeai/phoenix-client/users` | Current authenticated user retrieval |
 | `@arizeai/phoenix-client/vitest` | Vitest entrypoint for dataset-backed eval tests |
 | `@arizeai/phoenix-client/vitest/reporter` | Vitest reporter for Phoenix eval summaries |
 | `@arizeai/phoenix-client/jest` | Jest entrypoint for dataset-backed eval tests |
@@ -158,10 +160,10 @@ Prefer this layer when:
 
 ## Where To Start
 
-- [Prompts](./prompts), [Datasets](./datasets), [Experiments](./experiments) — higher-level workflows
+- [Projects](./projects), [Prompts](./prompts), [Datasets](./datasets), [Experiments](./experiments) — higher-level workflows
 - [Annotations](./annotations) — annotation concepts, then [Span](./span-annotations), [Document](./document-annotations), and [Session](./session-annotations) annotations for detailed usage
 - [CI Eval Tests](./ci-evals) — Vitest/Jest eval suites backed by Phoenix datasets and experiments
-- [Spans](./spans), [Sessions](./sessions), [Traces](./traces) — retrieval and maintenance
+- [Spans](./spans), [Sessions](./sessions), [Traces](./traces), [Users](./users) — retrieval and maintenance
 
 <section className="hidden" data-agent-context="source-map" aria-label="Source map">
   <h2>Source Map</h2>
@@ -171,12 +173,14 @@ Prefer this layer when:
     <li><code>src/config.ts</code></li>
     <li><code>src/__generated__/api/v1.ts</code></li>
     <li><code>src/types/core.ts</code></li>
+    <li><code>src/projects/</code></li>
     <li><code>src/prompts/</code></li>
     <li><code>src/datasets/</code></li>
     <li><code>src/experiments/</code></li>
     <li><code>src/spans/</code></li>
     <li><code>src/sessions/</code></li>
     <li><code>src/traces/</code></li>
+    <li><code>src/users/</code></li>
     <li><code>src/vitest/</code></li>
     <li><code>src/jest/</code></li>
     <li><code>src/testing/</code></li>

package/docs/projects.mdx

@@ -0,0 +1,71 @@
+---
+title: "Projects"
+description: "List projects and manage project retention-policy assignments"
+---
+
+The projects module lists Phoenix projects and assigns existing trace retention policies to them.
+
+<section className="hidden" data-agent-context="relevant-source-files" aria-label="Relevant source files">
+  <h2>Relevant Source Files</h2>
+  <ul>
+    <li><code>src/projects/getProjects.ts</code></li>
+    <li><code>src/projects/setProjectRetentionPolicy.ts</code></li>
+    <li><code>src/types/projects.ts</code></li>
+  </ul>
+</section>
+
+## List Projects
+
+`getProjects` handles cursor pagination automatically. Use `nameContains` for a case-insensitive, server-side substring filter.
+
+```ts
+import { getProjects } from "@arizeai/phoenix-client/projects";
+
+const projects = await getProjects({ nameContains: "support" });
+
+for (const project of projects) {
+  console.log(`${project.name} (${project.id})`);
+}
+```
+
+## Assign A Retention Policy
+
+`setProjectRetentionPolicy` accepts a project name or project GlobalID and the GlobalID of an existing trace retention policy.
+
+```ts
+import { setProjectRetentionPolicy } from "@arizeai/phoenix-client/projects";
+
+const assignment = await setProjectRetentionPolicy({
+  projectName: "support-bot",
+  policyId: "UHJvamVjdFRyYWNlUmV0ZW50aW9uUG9saWN5OjI=",
+});
+
+console.log(assignment.project_id, assignment.policy_id);
+```
+
+You can select the project with `projectName`, `projectId`, or the shorthand `project`. `projectId` must be the project's GlobalID.
+
+This helper only changes which existing retention policy the project uses. It does not create, read, update, or delete retention policies; policy CRUD is outside the TypeScript client's projects helper.
+
+## Reset To The Default Policy
+
+Pass `null` as `policyId` to remove the explicit assignment and return the project to Phoenix's default retention policy.
+
+```ts
+await setProjectRetentionPolicy({
+  projectId: "UHJvamVjdDox",
+  policyId: null,
+});
+```
+
+Assigning or resetting a retention policy requires an admin when authentication is enabled. Invalid policy GlobalIDs produce a `422` response, while callers without permission receive `403`; both are surfaced as `HttpError` instances by the client.
+
+<section className="hidden" data-agent-context="source-map" aria-label="Source map">
+  <h2>Source Map</h2>
+  <ul>
+    <li><code>src/projects/getProjects.ts</code></li>
+    <li><code>src/projects/setProjectRetentionPolicy.ts</code></li>
+    <li><code>src/projects/index.ts</code></li>
+    <li><code>src/types/projects.ts</code></li>
+  </ul>
+</section>

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/docs/traces.mdx

@@ -1,9 +1,9 @@
 ---
 title: "Traces"
-description: "Retrieve traces and annotate them with @arizeai/phoenix-client"
+description: "Retrieve, move, and annotate traces with @arizeai/phoenix-client"
 ---
 
-The traces module provides trace retrieval and trace-level annotation functions.
+The traces module provides trace retrieval, project transfer, and trace-level annotation functions.
 
 <section className="hidden" data-agent-context="relevant-source-files" aria-label="Relevant source files">
   <h2>Relevant Source Files</h2>
@@ -18,6 +18,9 @@ The traces module provides trace retrieval and trace-level annotation functions.
     <li>
       <code>src/traces/logTraceAnnotations.ts</code> for batched annotation writes
     </li>
+    <li>
+      <code>src/traces/transferTraces.ts</code> for moving traces between projects
+    </li>
     <li>
       <code>src/traces/types.ts</code> for the <code>TraceAnnotation</code> type
     </li>
@@ -65,6 +68,28 @@ console.log(result.nextCursor);
 - Set `includeSpans` when you need a trace-centric fetch that also contains span details
 - `project` accepts `{ project }`, `{ projectId }`, or `{ projectName }`
 
+## Move Traces To Another Project
+
+Use `transferTraces` to move one or more traces from their current project to a destination project. This operation **moves rather than copies** the traces: after a successful transfer, they no longer appear in the source project.
+
+All traces in one call must currently belong to the same source project. Each trace identifier can be either an OpenTelemetry trace ID or a Phoenix trace GlobalID, and the destination can be either a project name or project GlobalID.
+
+```ts
+import { transferTraces } from "@arizeai/phoenix-client/traces";
+
+const result = await transferTraces({
+  traceIdentifiers: ["8f3a...", "VHJhY2U6Mg=="],
+  destinationProjectIdentifier: "production",
+});
+
+console.log(`Moved ${result.transferredTraceCount} traces`);
+console.log(`Destination project: ${result.destinationProjectId}`);
+```
+
+The result contains the number of distinct traces moved and the resolved GlobalID of the destination project. Phoenix rejects an empty list, trace or project identifiers that do not resolve, and requests that combine traces from multiple source projects.
+
+`transferTraces` requires Phoenix server 20.4.0 or newer.
+
 ## Annotate a Single Trace
 
 Use `addTraceAnnotation` to attach a label, score, or explanation to one trace. If you supply an `identifier`, Phoenix upserts the annotation when an annotation with that identifier already exists.
@@ -128,6 +153,7 @@ for (const r of results) {
     <li><code>src/traces/getTraces.ts</code></li>
     <li><code>src/traces/addTraceAnnotation.ts</code></li>
     <li><code>src/traces/logTraceAnnotations.ts</code></li>
+    <li><code>src/traces/transferTraces.ts</code></li>
     <li><code>src/traces/types.ts</code></li>
     <li><code>src/types/projects.ts</code></li>
   </ul>

package/docs/users.mdx

@@ -0,0 +1,44 @@
+---
+title: "Users"
+description: "Get the current Phoenix user with @arizeai/phoenix-client"
+---
+
+The users module identifies the user associated with the client's current credentials.
+
+## Get The Current User
+
+```ts
+import { getCurrentUser } from "@arizeai/phoenix-client/users";
+
+const user = await getCurrentUser();
+
+if (user.auth_method === "ANONYMOUS") {
+  console.log("Authentication is disabled");
+} else {
+  console.log(`${user.username} has the ${user.role} role`);
+}
+```
+
+`getCurrentUser()` returns the generated Phoenix API user union. Authenticated deployments return a local, OAuth 2, or LDAP user profile. When authentication is disabled, it returns `{ auth_method: "ANONYMOUS" }`. Invalid credentials reject with an `HttpError` whose `status` is `401`; other authorization failures retain their HTTP status as well.
+
+Pass a client explicitly when you need custom configuration:
+
+```ts
+import { createClient } from "@arizeai/phoenix-client";
+import { getCurrentUser } from "@arizeai/phoenix-client/users";
+
+const client = createClient({
+  options: { baseUrl: "https://phoenix.example.com" },
+});
+
+const user = await getCurrentUser({ client });
+```
+
+<section className="hidden" data-agent-context="source-map" aria-label="Source map">
+  <h2>Source Map</h2>
+  <ul>
+    <li><code>src/users/getCurrentUser.ts</code></li>
+    <li><code>src/users/index.ts</code></li>
+    <li><code>src/__generated__/api/v1.ts</code></li>
+  </ul>
+</section>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arizeai/phoenix-client",
-  "version": "7.6.0",
+  "version": "7.7.1",
   "description": "A client for the Phoenix API",
   "keywords": [
     "arize",
@@ -57,6 +57,10 @@
       "import": "./dist/esm/projects/index.js",
       "require": "./dist/src/projects/index.js"
     },
+    "./users": {
+      "import": "./dist/esm/users/index.js",
+      "require": "./dist/src/users/index.js"
+    },
     "./traces": {
       "import": "./dist/esm/traces/index.js",
       "require": "./dist/src/traces/index.js"
@@ -129,7 +133,7 @@
     "@anthropic-ai/sdk": "^0.35.0",
     "ai": "^7.0.0",
     "jest": ">=27",
-    "openai": "^6.10.0",
+    "openai": "^6.10.0 || ^7.0.0",
     "vitest": ">=1"
   },
   "peerDependenciesMeta": {

package/src/__generated__/api/v1.ts

@@ -9987,7 +9987,7 @@ export interface operations {
                 order?: "asc" | "desc";
                 /** @description Maximum number of traces to return */
                 limit?: number;
-                /** @description Pagination cursor (Trace GlobalID) */
+                /** @description Pagination cursor returned by a previous request */
                 cursor?: string | null;
                 /** @description If true, include full span details for each trace. This significantly increases response size and query latency, especially with large page sizes. Prefer fetching spans lazily for individual traces when possible. */
                 include_spans?: boolean;

package/src/constants/serverRequirements.ts

@@ -98,6 +98,13 @@ export const LIST_PROJECT_TRACES: RouteRequirement = {
   minServerVersion: [13, 15, 0],
 };
 
+export const TRANSFER_TRACES: RouteRequirement = {
+  kind: "route",
+  method: "POST",
+  path: "/v1/traces/transfer",
+  minServerVersion: [20, 4, 0],
+};
+
 export const GET_SPANS_BY_ATTRIBUTE: ParameterRequirement = {
   kind: "parameter",
   parameterName: "attribute",
@@ -227,6 +234,7 @@ export const ALL_REQUIREMENTS: readonly CapabilityRequirement[] = [
   GET_SPANS_FILTERS,
   GET_SPANS_BY_ATTRIBUTE,
   LIST_PROJECT_TRACES,
+  TRANSFER_TRACES,
   DATASET_UPLOAD_EXAMPLE_IDS,
   ADD_TRACE_NOTE_IDENTIFIER,
   ADD_SPAN_NOTE_IDENTIFIER,

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,