@arizeai/phoenix-client 7.5.0 → 7.7.0

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",
@@ -138,6 +145,13 @@ export const ADD_SESSION_NOTE_IDENTIFIER: ParameterRequirement = {
   minServerVersion: [15, 5, 0],
 };
 
+export const DELETE_PROMPT: RouteRequirement = {
+  kind: "route",
+  method: "DELETE",
+  path: "/v1/prompts/{prompt_identifier}",
+  minServerVersion: [13, 20, 0],
+};
+
 export const PATCH_PROMPT: RouteRequirement = {
   kind: "route",
   method: "PATCH",
@@ -220,10 +234,12 @@ 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,
   ADD_SESSION_NOTE_IDENTIFIER,
+  DELETE_PROMPT,
   PATCH_PROMPT,
   AGENT_SESSION_CREATE,
   AGENT_SESSION_LIST,

package/src/projects/index.ts

@@ -1 +1,2 @@
 export * from "./getProjects";
+export * from "./setProjectRetentionPolicy";

package/src/projects/setProjectRetentionPolicy.ts

@@ -0,0 +1,80 @@
+import invariant from "tiny-invariant";
+
+import type { components } from "../__generated__/api/v1";
+import { createClient } from "../client";
+import type { ClientFn } from "../types/core";
+import type { ProjectIdentifier } from "../types/projects";
+import { resolveProjectIdentifier } from "../types/projects";
+
+/**
+ * The retention-policy assignment returned for a project.
+ */
+export type ProjectRetentionPolicyAssignment =
+  components["schemas"]["ProjectRetentionPolicyData"];
+
+/**
+ * Parameters for assigning or resetting a project's retention policy.
+ */
+export type SetProjectRetentionPolicyParams = ClientFn &
+  ProjectIdentifier & {
+    /**
+     * The GlobalID of an existing trace retention policy, or `null` to reset
+     * the project to the default policy.
+     */
+    policyId: string | null;
+  };
+
+/**
+ * Assign an existing trace retention policy to a project, or reset the project
+ * to the default policy.
+ *
+ * This helper only changes the project's assignment. It does not create,
+ * retrieve, update, or delete retention policies.
+ *
+ * @param params - The project and policy assignment.
+ * @param params.project - A project name or GlobalID.
+ * @param params.projectId - A project GlobalID.
+ * @param params.projectName - A project name.
+ * @param params.policyId - An existing policy GlobalID, or `null` to reset.
+ * @param params.client - An optional Phoenix client instance.
+ * @returns The project's resulting retention-policy assignment.
+ *
+ * @example
+ * ```ts
+ * import { setProjectRetentionPolicy } from "@arizeai/phoenix-client/projects";
+ *
+ * await setProjectRetentionPolicy({
+ *   projectName: "support-bot",
+ *   policyId: "UHJvamVjdFRyYWNlUmV0ZW50aW9uUG9saWN5OjI=",
+ * });
+ *
+ * await setProjectRetentionPolicy({
+ *   projectId: "UHJvamVjdDox",
+ *   policyId: null,
+ * });
+ * ```
+ */
+export async function setProjectRetentionPolicy(
+  params: SetProjectRetentionPolicyParams
+): Promise<ProjectRetentionPolicyAssignment> {
+  const client = params.client ?? createClient();
+  const projectIdentifier = resolveProjectIdentifier(params);
+
+  const { data, error } = await client.PATCH(
+    "/v1/projects/{project_identifier}/retention",
+    {
+      params: {
+        path: {
+          project_identifier: projectIdentifier,
+        },
+      },
+      body: {
+        policy_id: params.policyId,
+      },
+    }
+  );
+
+  if (error) throw error;
+  invariant(data?.data, "Failed to set project retention policy");
+  return data.data;
+}

package/src/prompts/deletePrompt.ts

@@ -0,0 +1,70 @@
+import { createClient } from "../client";
+import { DELETE_PROMPT } from "../constants/serverRequirements";
+import { HttpError } from "../errors";
+import type { ClientFn } from "../types/core";
+import type { PromptIdentifier } from "../types/prompts";
+import { resolvePromptIdentifier } from "../utils/resolvePromptIdentifier";
+import { ensureServerCapability } from "../utils/serverVersionUtils";
+
+/**
+ * Parameters for deleting a prompt.
+ */
+export interface DeletePromptParams extends ClientFn {
+  /**
+   * The prompt to delete. Selected either by `name` or by `promptId` — the same
+   * selector style {@link getPrompt} takes, minus the version-level selectors,
+   * which do not identify a prompt.
+   */
+  prompt: PromptIdentifier;
+}
+
+/**
+ * Delete a prompt via `DELETE /v1/prompts/{prompt_identifier}`.
+ *
+ * Deletion cascades: every version of the prompt, along with its version tags
+ * and labels, is removed with it. This cannot be undone.
+ *
+ * @param params - The parameters to delete the prompt.
+ * @param params.prompt - The prompt to delete, selected by `name` or `promptId`.
+ * @returns A promise that resolves once the prompt is deleted.
+ * @throws An error if the prompt does not exist, or if the deletion fails.
+ *
+ * @requires Phoenix server >= 13.20.0
+ *
+ * @example
+ * ```ts
+ * import { deletePrompt } from "@arizeai/phoenix-client/prompts";
+ *
+ * // Delete by name
+ * await deletePrompt({ prompt: { name: "my-prompt" } });
+ *
+ * // Delete by prompt id
+ * await deletePrompt({ prompt: { promptId: "UHJvbXB0OjE=" } });
+ * ```
+ */
+export async function deletePrompt({
+  client: _client,
+  prompt,
+}: DeletePromptParams): Promise<void> {
+  const promptIdentifier = resolvePromptIdentifier(prompt);
+
+  const client = _client ?? createClient();
+  await ensureServerCapability({ client, requirement: DELETE_PROMPT });
+
+  try {
+    await client.DELETE("/v1/prompts/{prompt_identifier}", {
+      params: {
+        path: {
+          prompt_identifier: promptIdentifier,
+        },
+      },
+    });
+  } catch (error) {
+    if (error instanceof HttpError && error.status === 404) {
+      throw new Error(`Prompt not found: ${promptIdentifier}`, {
+        cause: error,
+      });
+    }
+    throw error;
+  }
+}

package/src/prompts/index.ts

@@ -1,5 +1,6 @@
 export * from "./getPrompt";
 export * from "./createPrompt";
+export * from "./deletePrompt";
 export * from "./listPrompts";
 export * from "./updatePrompt";
 export * from "./sdks";

package/src/testing/reporter-format.ts

@@ -322,7 +322,8 @@ interface AcceptanceBar {
  * reused as a per-run heuristic (the suite-level acceptance block still reports
  * the true aggregate verdict). `passRate` criteria decide passing with an
  * arbitrary `passFn` predicate — there is no static numeric bar to highlight
- * against — so their rows fall back to the default miss heuristic.
+ * against — so those annotations are ignored for per-run misses when any
+ * `average` bar exists.
  */
 function buildAcceptanceBars(suite: SuiteSummary): Map<string, AcceptanceBar> {
   const bars = new Map<string, AcceptanceBar>();
@@ -339,13 +340,22 @@ function buildAcceptanceBars(suite: SuiteSummary): Map<string, AcceptanceBar> {
 /**
  * Whether a passing test's evaluator scores fall short. When maximizing, a
  * boolean `false` or a numeric score below its bar is a miss; when minimizing,
- * a boolean `true` or a score above its bar is a miss. With no criterion for an
- * annotation, only a non-positive score counts (keeps zero-config suites quiet).
+ * a boolean `true` or a score above its bar is a miss.
+ *
+ * When the suite has `average` acceptance criteria, only those gated
+ * annotations decide per-run misses. That way a minimize metric whose desired
+ * value is 0 (e.g. `no_pii_detected`) is not listed as a miss on a correctly
+ * classified row. With no average criterion, a non-positive score still counts
+ * (keeps zero-config suites quiet).
  */
 function isMiss(result: TestResult, bars: Map<string, AcceptanceBar>): boolean {
+  const hasAverageBars = bars.size > 0;
   for (const ann of result.annotations) {
     if (ann.name === "pass") continue;
     const acceptanceBar = bars.get(ann.name);
+    if (hasAverageBars && acceptanceBar === undefined) {
+      continue;
+    }
     const minimizing = acceptanceBar?.direction === "minimize";
     if (typeof ann.score === "boolean") {
       if (minimizing ? ann.score : !ann.score) return true;

package/src/traces/getTraces.ts

@@ -22,7 +22,7 @@ export interface GetTracesParams extends ClientFn {
   order?: "asc" | "desc";
   /** Maximum number of traces to return */
   limit?: number;
-  /** Pagination cursor (Trace GlobalID) */
+  /** Pagination cursor */
   cursor?: string | null;
   /** If true, include full span details for each trace */
   includeSpans?: boolean;

package/src/traces/index.ts

@@ -2,4 +2,5 @@ export * from "./addTraceAnnotation";
 export * from "./addTraceNote";
 export * from "./getTraces";
 export * from "./logTraceAnnotations";
+export * from "./transferTraces";
 export type { TraceAnnotation } from "./types";

package/src/traces/transferTraces.ts

@@ -0,0 +1,89 @@
+import { createClient } from "../client";
+import { TRANSFER_TRACES } from "../constants/serverRequirements";
+import type { ClientFn } from "../types/core";
+import { ensureServerCapability } from "../utils/serverVersionUtils";
+
+/**
+ * Parameters for moving traces to another project.
+ */
+export interface TransferTracesParams extends ClientFn {
+  /**
+   * Trace GlobalIDs or OpenTelemetry trace IDs to move. All traces must
+   * currently belong to the same source project.
+   */
+  traceIdentifiers: string[];
+  /**
+   * The destination project name or GlobalID.
+   */
+  destinationProjectIdentifier: string;
+}
+
+/**
+ * The result of moving traces to another project.
+ */
+export interface TransferTracesResult {
+  /** The number of distinct traces moved. */
+  transferredTraceCount: number;
+  /** The destination project's GlobalID. */
+  destinationProjectId: string;
+}
+
+/**
+ * Move traces from one project to another.
+ *
+ * This operation re-parents the traces; it does not copy them. After the move,
+ * the traces no longer appear in their original project. Every trace must
+ * currently belong to the same source project.
+ *
+ * @param params - The parameters for moving traces.
+ * @param params.traceIdentifiers - Trace GlobalIDs or OpenTelemetry trace IDs to move.
+ * @param params.destinationProjectIdentifier - The destination project name or GlobalID.
+ * @returns The number of traces moved and the destination project's GlobalID.
+ * @throws {RangeError} If no trace identifiers are provided.
+ * @throws {HttpError} If a trace or destination project is missing, the traces
+ * belong to multiple source projects, or the transfer otherwise fails.
+ *
+ * @requires Phoenix server >= 20.4.0
+ *
+ * @example
+ * ```ts
+ * import { transferTraces } from "@arizeai/phoenix-client/traces";
+ *
+ * const result = await transferTraces({
+ *   traceIdentifiers: ["8f3a...", "VHJhY2U6Mg=="],
+ *   destinationProjectIdentifier: "production",
+ * });
+ *
+ * console.log(result.transferredTraceCount);
+ * console.log(result.destinationProjectId);
+ * ```
+ */
+export async function transferTraces({
+  client: _client,
+  traceIdentifiers,
+  destinationProjectIdentifier,
+}: TransferTracesParams): Promise<TransferTracesResult> {
+  if (traceIdentifiers.length === 0) {
+    throw new RangeError("At least one trace identifier is required");
+  }
+
+  const client = _client ?? createClient();
+  await ensureServerCapability({ client, requirement: TRANSFER_TRACES });
+
+  const { data, error } = await client.POST("/v1/traces/transfer", {
+    body: {
+      trace_identifiers: traceIdentifiers,
+      destination_project_identifier: destinationProjectIdentifier,
+    },
+  });
+
+  if (error) throw error;
+  if (!data?.data) {
+    throw new Error("Failed to transfer traces: no data returned");
+  }
+
+  return {
+    transferredTraceCount: data.data.transferred_trace_count,
+    destinationProjectId: data.data.destination_project_id,
+  };
+}

package/src/types/prompts.ts

@@ -75,6 +75,16 @@ export type PromptSelector =
   | GetPromptByVersionSelector
   | GetPromptByTagSelector;
 
+/**
+ * A selector for a prompt as a whole, rather than for one of its versions.
+ *
+ * Narrower than {@link PromptSelector}: a version id or a name + tag picks out a
+ * single version, which is not what operations on the prompt itself act on. Use
+ * this wherever the API needs the `{prompt_identifier}` path segment — the name
+ * and the prompt id are the two things the Phoenix REST API accepts there.
+ */
+export type PromptIdentifier = GetPromptByIdSelector | GetPromptByNameSelector;
+
 /**
  * The prompt data needed to create a prompt.
  */

package/src/users/getCurrentUser.ts

@@ -0,0 +1,39 @@
+import invariant from "tiny-invariant";
+
+import type { components } from "../__generated__/api/v1";
+import { createClient } from "../client";
+import type { ClientFn } from "../types/core";
+
+/** The user profile returned for the current Phoenix client credentials. */
+export type CurrentUser =
+  components["schemas"]["GetViewerResponseBody"]["data"];
+
+/**
+ * Get the currently authenticated user.
+ *
+ * When authentication is disabled, Phoenix returns an anonymous user with
+ * `auth_method: "ANONYMOUS"`.
+ *
+ * @param params - The parameters for fetching the current user.
+ * @param params.client - An optional Phoenix client instance.
+ * @returns The current user's generated API profile shape.
+ * @throws {HttpError} If the request is not authenticated or is forbidden.
+ *
+ * @example
+ * ```ts
+ * import { getCurrentUser } from "@arizeai/phoenix-client/users";
+ *
+ * const user = await getCurrentUser();
+ * console.log(user.auth_method);
+ * ```
+ */
+export async function getCurrentUser({
+  client: _client,
+}: ClientFn = {}): Promise<CurrentUser> {
+  const client = _client ?? createClient();
+  const { data, error } = await client.GET("/v1/user");
+
+  if (error) throw error;
+  invariant(data?.data, "Failed to get current user");
+  return data.data;
+}

package/src/users/index.ts

@@ -0,0 +1 @@
+export * from "./getCurrentUser";

package/src/utils/resolvePromptIdentifier.ts

@@ -0,0 +1,41 @@
+import type { PromptIdentifier } from "../types/prompts";
+
+/**
+ * Resolve a prompt-level selector to the `{prompt_identifier}` path segment the
+ * Phoenix REST API expects.
+ *
+ * Version-level selectors are rejected rather than silently widened: structural
+ * typing lets a `{ name, tag }` or `{ versionId }` value reach a
+ * {@link PromptIdentifier} parameter, and quietly dropping the version would
+ * point the caller at the whole prompt instead of the version they named.
+ *
+ * @param prompt - the prompt, selected by `name` or by `promptId`
+ * @returns The identifier to interpolate into the request path.
+ * @throws An error if the selector is empty, or selects a version rather than a
+ * prompt.
+ */
+export function resolvePromptIdentifier(prompt: PromptIdentifier): string {
+  if ("versionId" in prompt) {
+    throw new Error(
+      "A prompt version id selects a single version, not a prompt. Select the prompt by name or promptId."
+    );
+  }
+  if ("tag" in prompt) {
+    throw new Error(
+      "A tag selects a single version, not a prompt. Select the prompt by name or promptId."
+    );
+  }
+  if ("promptId" in prompt) {
+    if (!prompt.promptId) {
+      throw new Error("promptId must be a non-empty prompt id.");
+    }
+    return prompt.promptId;
+  }
+  if ("name" in prompt) {
+    if (!prompt.name) {
+      throw new Error("name must be a non-empty prompt name.");
+    }
+    return prompt.name;
+  }
+  throw new Error("A prompt must be selected by either name or promptId.");
+}