@arizeai/phoenix-client 7.15.0 → 7.16.0

package/docs/projects.mdx

@@ -1,16 +1,21 @@
 ---
 title: "Projects"
-description: "List projects and manage project retention-policy assignments"
+description: "List projects and manage project retention-policy and annotation-config assignments"
 ---
 
-The projects module lists Phoenix projects and assigns existing trace retention policies to them.
+The projects module lists Phoenix projects, assigns existing trace retention policies to them, and manages which annotation configs they use.
 
 <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/projects/listProjectAnnotationConfigs.ts</code></li>
+    <li><code>src/projects/assignProjectAnnotationConfig.ts</code></li>
+    <li><code>src/projects/unassignProjectAnnotationConfig.ts</code></li>
+    <li><code>src/projects/setProjectAnnotationConfigs.ts</code></li>
     <li><code>src/types/projects.ts</code></li>
+    <li><code>src/types/annotationConfigs.ts</code></li>
   </ul>
 </section>
 
@@ -60,12 +65,60 @@ await setProjectRetentionPolicy({
 
 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.
 
+## Assign Annotation Configs
+
+Annotation configs define the annotations that can be recorded on a project's traces, spans, and sessions. These helpers change which existing configs a project uses. They don't create, update, or delete the configs themselves. All four require Phoenix server 17.16.0 or later.
+
+```ts
+import {
+  assignProjectAnnotationConfig,
+  listProjectAnnotationConfigs,
+  setProjectAnnotationConfigs,
+  unassignProjectAnnotationConfig,
+} from "@arizeai/phoenix-client/projects";
+
+// Assign a config by name or GlobalID. Assigning an already-assigned config is a no-op.
+const correctness = await assignProjectAnnotationConfig({
+  projectName: "support-bot",
+  configName: "correctness",
+});
+
+// Unassign a config. Unassigning a config that isn't assigned is a no-op.
+await unassignProjectAnnotationConfig({
+  projectName: "support-bot",
+  configId: correctness.id,
+});
+
+// List every assigned config (pagination is handled automatically)
+const configs = await listProjectAnnotationConfigs({ projectName: "support-bot" });
+
+// Replace the whole set, keeping only categorical configs; configs not listed are unassigned
+await setProjectAnnotationConfigs({
+  projectName: "support-bot",
+  configIds: configs
+    .filter((config) => config.type === "CATEGORICAL")
+    .map((config) => config.id),
+});
+
+// Clear every assignment
+await setProjectAnnotationConfigs({ projectName: "support-bot", configIds: [] });
+```
+
+Select the config with exactly one of `configName`, `configId`, or the shorthand `config`, which accepts either. Use `configId` if a config name contains `/`, because the server can't route it in the URL path.
+
+`setProjectAnnotationConfigs` takes config GlobalIDs only, because the server doesn't accept names for this operation. Unknown or invalid config IDs produce a `422` response, and a missing project produces a `404`. The single-config helpers return a `404` when the project or the config is missing. The client surfaces all of these as `HttpError` instances.
+
 <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/listProjectAnnotationConfigs.ts</code></li>
+    <li><code>src/projects/assignProjectAnnotationConfig.ts</code></li>
+    <li><code>src/projects/unassignProjectAnnotationConfig.ts</code></li>
+    <li><code>src/projects/setProjectAnnotationConfigs.ts</code></li>
     <li><code>src/projects/index.ts</code></li>
     <li><code>src/types/projects.ts</code></li>
+    <li><code>src/types/annotationConfigs.ts</code></li>
   </ul>
 </section>

package/package.json

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

package/src/__generated__/api/v1.ts

@@ -3334,11 +3334,6 @@ export interface components {
              * @description The description of the experiment
              */
             description: string | null;
-            /**
-             * Sequence Number
-             * @description The 1-based sequence number of the experiment within its dataset, in creation order.
-             */
-            sequence_number: number;
             /**
              * Repetitions
              * @description Number of times the experiment is repeated
@@ -9388,10 +9383,6 @@ export interface operations {
                 cursor?: string | null;
                 /** @description The max number of experiments to return at a time. */
                 limit?: number;
-                /** @description Order by creation: 'desc' (default) returns newest experiments first, 'asc' returns oldest first so the lowest sequence numbers are on the first page. */
-                sort_dir?: "asc" | "desc";
-                /** @description When provided, return only the experiments with these 1-based per-dataset sequence numbers. */
-                sequence_numbers?: number[] | null;
             };
             header?: never;
             path: {

package/src/constants/serverRequirements.ts

@@ -220,6 +220,34 @@ export const PATCH_PROMPT: RouteRequirement = {
   minServerVersion: [19, 18, 0],
 };
 
+export const LIST_PROJECT_ANNOTATION_CONFIGS: RouteRequirement = {
+  kind: "route",
+  method: "GET",
+  path: "/v1/projects/{project_identifier}/annotation_configs",
+  minServerVersion: [17, 16, 0],
+};
+
+export const SET_PROJECT_ANNOTATION_CONFIGS: RouteRequirement = {
+  kind: "route",
+  method: "PUT",
+  path: "/v1/projects/{project_identifier}/annotation_configs",
+  minServerVersion: [17, 16, 0],
+};
+
+export const ASSIGN_PROJECT_ANNOTATION_CONFIG: RouteRequirement = {
+  kind: "route",
+  method: "PUT",
+  path: "/v1/projects/{project_identifier}/annotation_configs/{config_identifier}",
+  minServerVersion: [17, 16, 0],
+};
+
+export const UNASSIGN_PROJECT_ANNOTATION_CONFIG: RouteRequirement = {
+  kind: "route",
+  method: "DELETE",
+  path: "/v1/projects/{project_identifier}/annotation_configs/{config_identifier}",
+  minServerVersion: [17, 16, 0],
+};
+
 export const AGENT_SESSION_CREATE: RouteRequirement = {
   kind: "route",
   method: "POST",
@@ -310,6 +338,10 @@ export const ALL_REQUIREMENTS: readonly CapabilityRequirement[] = [
   UPSERT_PROMPT_VERSION_TAG,
   DELETE_PROMPT_VERSION_TAG,
   PATCH_PROMPT,
+  LIST_PROJECT_ANNOTATION_CONFIGS,
+  SET_PROJECT_ANNOTATION_CONFIGS,
+  ASSIGN_PROJECT_ANNOTATION_CONFIG,
+  UNASSIGN_PROJECT_ANNOTATION_CONFIG,
   AGENT_SESSION_CREATE,
   AGENT_SESSION_LIST,
   AGENT_SESSION_GET,

package/src/projects/assignProjectAnnotationConfig.ts

@@ -0,0 +1,78 @@
+import invariant from "tiny-invariant";
+
+import { createClient } from "../client";
+import { ASSIGN_PROJECT_ANNOTATION_CONFIG } from "../constants/serverRequirements";
+import type {
+  AnnotationConfig,
+  AnnotationConfigIdentifier,
+} from "../types/annotationConfigs";
+import { resolveAnnotationConfigIdentifier } from "../types/annotationConfigs";
+import type { ClientFn } from "../types/core";
+import type { ProjectIdentifier } from "../types/projects";
+import { resolveProjectIdentifier } from "../types/projects";
+import { ensureServerCapability } from "../utils/serverVersionUtils";
+
+/**
+ * Parameters for assigning an annotation config to a project.
+ */
+export type AssignProjectAnnotationConfigParams = ClientFn &
+  ProjectIdentifier &
+  AnnotationConfigIdentifier;
+
+/**
+ * Assign an existing annotation config to a project.
+ *
+ * Assignment is idempotent: assigning a config that is already assigned to
+ * the project succeeds and returns the config.
+ *
+ * @param params - The project and annotation config to assign.
+ * @param params.project - A project name or GlobalID.
+ * @param params.projectId - A project GlobalID.
+ * @param params.projectName - A project name.
+ * @param params.config - An annotation config name or GlobalID.
+ * @param params.configId - An annotation config GlobalID.
+ * @param params.configName - An annotation config name.
+ * Use `configId` instead if the name may contain `/`, which the server
+ * cannot route.
+ * @param params.client - An optional Phoenix client instance.
+ * @returns The assigned annotation config.
+ * @throws {@link HttpError} when Phoenix rejects the request, e.g. with a 404
+ * if the project or annotation config does not exist.
+ *
+ * @requires Phoenix server >= 17.16.0
+ *
+ * @example
+ * ```ts
+ * import { assignProjectAnnotationConfig } from "@arizeai/phoenix-client/projects";
+ *
+ * const config = await assignProjectAnnotationConfig({
+ *   projectName: "support-bot",
+ *   configName: "correctness",
+ * });
+ * ```
+ */
+export async function assignProjectAnnotationConfig(
+  params: AssignProjectAnnotationConfigParams
+): Promise<AnnotationConfig> {
+  const client = params.client ?? createClient();
+  await ensureServerCapability({
+    client,
+    requirement: ASSIGN_PROJECT_ANNOTATION_CONFIG,
+  });
+
+  const { data, error } = await client.PUT(
+    "/v1/projects/{project_identifier}/annotation_configs/{config_identifier}",
+    {
+      params: {
+        path: {
+          project_identifier: resolveProjectIdentifier(params),
+          config_identifier: resolveAnnotationConfigIdentifier(params),
+        },
+      },
+    }
+  );
+
+  if (error) throw error;
+  invariant(data?.data, "Failed to assign annotation config to project");
+  return data.data;
+}

package/src/projects/index.ts

@@ -1,2 +1,10 @@
+export * from "./assignProjectAnnotationConfig";
 export * from "./getProjects";
+export * from "./listProjectAnnotationConfigs";
+export * from "./setProjectAnnotationConfigs";
 export * from "./setProjectRetentionPolicy";
+export * from "./unassignProjectAnnotationConfig";
+export type {
+  AnnotationConfig,
+  AnnotationConfigIdentifier,
+} from "../types/annotationConfigs";

package/src/projects/listProjectAnnotationConfigs.ts

@@ -0,0 +1,85 @@
+import invariant from "tiny-invariant";
+
+import type { components } from "../__generated__/api/v1";
+import { createClient } from "../client";
+import { LIST_PROJECT_ANNOTATION_CONFIGS } from "../constants/serverRequirements";
+import type { AnnotationConfig } from "../types/annotationConfigs";
+import type { ClientFn } from "../types/core";
+import type { ProjectIdentifier } from "../types/projects";
+import { resolveProjectIdentifier } from "../types/projects";
+import { ensureServerCapability } from "../utils/serverVersionUtils";
+
+/**
+ * Parameters for listing the annotation configs assigned to a project.
+ */
+export type ListProjectAnnotationConfigsParams = ClientFn & ProjectIdentifier;
+
+type ProjectAnnotationConfigsResponse =
+  components["schemas"]["GetProjectAnnotationConfigsResponseBody"];
+
+const DEFAULT_PAGE_SIZE = 100;
+
+/**
+ * List every annotation config assigned to a project, with automatic
+ * pagination handling.
+ *
+ * @param params - The project whose assigned configs should be listed.
+ * @param params.project - A project name or GlobalID.
+ * @param params.projectId - A project GlobalID.
+ * @param params.projectName - A project name.
+ * @param params.client - An optional Phoenix client instance.
+ * @returns The annotation configs assigned to the project.
+ * @throws {@link HttpError} when Phoenix rejects the request, e.g. with a 404
+ * if the project does not exist.
+ *
+ * @requires Phoenix server >= 17.16.0
+ *
+ * @example
+ * ```ts
+ * import { listProjectAnnotationConfigs } from "@arizeai/phoenix-client/projects";
+ *
+ * const configs = await listProjectAnnotationConfigs({
+ *   projectName: "support-bot",
+ * });
+ *
+ * for (const config of configs) {
+ *   console.log(`${config.name} (${config.type})`);
+ * }
+ * ```
+ */
+export async function listProjectAnnotationConfigs(
+  params: ListProjectAnnotationConfigsParams
+): Promise<AnnotationConfig[]> {
+  const client = params.client ?? createClient();
+  await ensureServerCapability({
+    client,
+    requirement: LIST_PROJECT_ANNOTATION_CONFIGS,
+  });
+  const projectIdentifier = resolveProjectIdentifier(params);
+
+  const configs: AnnotationConfig[] = [];
+  let cursor: string | null = null;
+
+  do {
+    const response: {
+      data?: ProjectAnnotationConfigsResponse;
+      error?: unknown;
+    } = await client.GET(
+      "/v1/projects/{project_identifier}/annotation_configs",
+      {
+        params: {
+          path: { project_identifier: projectIdentifier },
+          query: { cursor, limit: DEFAULT_PAGE_SIZE },
+        },
+      }
+    );
+
+    if (response.error) throw response.error;
+    invariant(response.data?.data, "Failed to list project annotation configs");
+
+    cursor = response.data.next_cursor ?? null;
+    configs.push(...response.data.data);
+  } while (cursor != null);
+
+  return configs;
+}

package/src/projects/setProjectAnnotationConfigs.ts

@@ -0,0 +1,86 @@
+import invariant from "tiny-invariant";
+
+import { createClient } from "../client";
+import { SET_PROJECT_ANNOTATION_CONFIGS } from "../constants/serverRequirements";
+import type { AnnotationConfig } from "../types/annotationConfigs";
+import type { ClientFn } from "../types/core";
+import type { ProjectIdentifier } from "../types/projects";
+import { resolveProjectIdentifier } from "../types/projects";
+import { ensureServerCapability } from "../utils/serverVersionUtils";
+
+/**
+ * Parameters for replacing the annotation configs assigned to a project.
+ */
+export type SetProjectAnnotationConfigsParams = ClientFn &
+  ProjectIdentifier & {
+    /**
+     * The GlobalIDs of every annotation config that should be assigned to the
+     * project. Configs not in this list are unassigned; an empty list clears
+     * all assignments.
+     */
+    configIds: string[];
+  };
+
+/**
+ * Replace the full set of annotation configs assigned to a project.
+ *
+ * Configs in `configIds` that are not yet assigned are added, and assigned
+ * configs missing from `configIds` are removed. The annotation configs
+ * themselves are never deleted.
+ *
+ * @param params - The project and its desired annotation configs.
+ * @param params.project - A project name or GlobalID.
+ * @param params.projectId - A project GlobalID.
+ * @param params.projectName - A project name.
+ * @param params.configIds - The annotation config GlobalIDs to assign.
+ * @param params.client - An optional Phoenix client instance.
+ * @returns The annotation configs assigned to the project after the update.
+ * @throws {@link HttpError} when Phoenix rejects the request, e.g. with a 404
+ * if the project does not exist or a 422 if any config ID is invalid or
+ * missing.
+ *
+ * @requires Phoenix server >= 17.16.0
+ *
+ * @example
+ * ```ts
+ * import { setProjectAnnotationConfigs } from "@arizeai/phoenix-client/projects";
+ *
+ * await setProjectAnnotationConfigs({
+ *   projectName: "support-bot",
+ *   configIds: ["Q2F0ZWdvcmljYWxBbm5vdGF0aW9uQ29uZmlnOjE="],
+ * });
+ *
+ * // Clear every assignment
+ * await setProjectAnnotationConfigs({
+ *   projectName: "support-bot",
+ *   configIds: [],
+ * });
+ * ```
+ */
+export async function setProjectAnnotationConfigs(
+  params: SetProjectAnnotationConfigsParams
+): Promise<AnnotationConfig[]> {
+  const client = params.client ?? createClient();
+  await ensureServerCapability({
+    client,
+    requirement: SET_PROJECT_ANNOTATION_CONFIGS,
+  });
+
+  const { data, error } = await client.PUT(
+    "/v1/projects/{project_identifier}/annotation_configs",
+    {
+      params: {
+        path: {
+          project_identifier: resolveProjectIdentifier(params),
+        },
+      },
+      body: {
+        annotation_config_ids: params.configIds,
+      },
+    }
+  );
+
+  if (error) throw error;
+  invariant(data?.data, "Failed to set project annotation configs");
+  return data.data;
+}

package/src/projects/unassignProjectAnnotationConfig.ts

@@ -0,0 +1,71 @@
+import { createClient } from "../client";
+import { UNASSIGN_PROJECT_ANNOTATION_CONFIG } from "../constants/serverRequirements";
+import type { AnnotationConfigIdentifier } from "../types/annotationConfigs";
+import { resolveAnnotationConfigIdentifier } from "../types/annotationConfigs";
+import type { ClientFn } from "../types/core";
+import type { ProjectIdentifier } from "../types/projects";
+import { resolveProjectIdentifier } from "../types/projects";
+import { ensureServerCapability } from "../utils/serverVersionUtils";
+
+/**
+ * Parameters for unassigning an annotation config from a project.
+ */
+export type UnassignProjectAnnotationConfigParams = ClientFn &
+  ProjectIdentifier &
+  AnnotationConfigIdentifier;
+
+/**
+ * Unassign an annotation config from a project.
+ *
+ * Unassignment is idempotent: unassigning a config that is not assigned to
+ * the project succeeds. The annotation config itself is not deleted.
+ *
+ * @param params - The project and annotation config to unassign.
+ * @param params.project - A project name or GlobalID.
+ * @param params.projectId - A project GlobalID.
+ * @param params.projectName - A project name.
+ * @param params.config - An annotation config name or GlobalID.
+ * @param params.configId - An annotation config GlobalID.
+ * @param params.configName - An annotation config name.
+ * Use `configId` instead if the name may contain `/`, which the server
+ * cannot route.
+ * @param params.client - An optional Phoenix client instance.
+ * @returns A promise that resolves once the config is unassigned.
+ * @throws {@link HttpError} when Phoenix rejects the request, e.g. with a 404
+ * if the project or annotation config does not exist.
+ *
+ * @requires Phoenix server >= 17.16.0
+ *
+ * @example
+ * ```ts
+ * import { unassignProjectAnnotationConfig } from "@arizeai/phoenix-client/projects";
+ *
+ * await unassignProjectAnnotationConfig({
+ *   projectName: "support-bot",
+ *   configName: "correctness",
+ * });
+ * ```
+ */
+export async function unassignProjectAnnotationConfig(
+  params: UnassignProjectAnnotationConfigParams
+): Promise<void> {
+  const client = params.client ?? createClient();
+  await ensureServerCapability({
+    client,
+    requirement: UNASSIGN_PROJECT_ANNOTATION_CONFIG,
+  });
+
+  const { error } = await client.DELETE(
+    "/v1/projects/{project_identifier}/annotation_configs/{config_identifier}",
+    {
+      params: {
+        path: {
+          project_identifier: resolveProjectIdentifier(params),
+          config_identifier: resolveAnnotationConfigIdentifier(params),
+        },
+      },
+    }
+  );
+
+  if (error) throw error;
+}

package/src/types/annotationConfigs.ts

@@ -0,0 +1,37 @@
+import type { components } from "../__generated__/api/v1";
+
+/**
+ * An annotation configuration as returned by the Phoenix REST API.
+ */
+export type AnnotationConfig =
+  | components["schemas"]["CategoricalAnnotationConfig"]
+  | components["schemas"]["ContinuousAnnotationConfig"]
+  | components["schemas"]["FreeformAnnotationConfig"];
+
+/**
+ * Identifies an annotation configuration. Accepts any of:
+ * - `config` — an annotation config ID or name (the server accepts either)
+ * - `configId` — an explicit annotation config ID
+ * - `configName` — an explicit annotation config name
+ *
+ * Exactly one of these may be given. All three are sent to the server as the
+ * same `config_identifier`, which is tried as a GlobalID before a name. Prefer
+ * `configId` when a name may contain `/`, which the server cannot route in a
+ * path parameter.
+ */
+export type AnnotationConfigIdentifier =
+  | { config: string; configId?: never; configName?: never }
+  | { configId: string; config?: never; configName?: never }
+  | { configName: string; config?: never; configId?: never };
+
+/**
+ * Resolves an {@link AnnotationConfigIdentifier} union to a plain string
+ * suitable for the REST `config_identifier` path parameter.
+ */
+export function resolveAnnotationConfigIdentifier(
+  identifier: AnnotationConfigIdentifier
+): string {
+  if (identifier.config !== undefined) return identifier.config;
+  if (identifier.configId !== undefined) return identifier.configId;
+  return identifier.configName;
+}