@arizeai/phoenix-client 7.14.0 → 7.15.0

package/docs/prompts.mdx

@@ -3,7 +3,7 @@ title: "Prompts"
 description: "Manage prompts with @arizeai/phoenix-client"
 ---
 
-The prompts module lets you create prompt versions in Phoenix, fetch them back by selector, list prompts, update a prompt's description and metadata, delete a prompt, and adapt prompt versions to supported provider SDKs.
+The prompts module lets you create prompt versions in Phoenix, fetch them back by selector, manage prompt version tags, list prompts, update a prompt's description and metadata, delete a prompt, and adapt prompt versions to supported provider SDKs.
 
 <section className="hidden" data-agent-context="relevant-source-files" aria-label="Relevant source files">
   <h2>Relevant Source Files</h2>
@@ -43,6 +43,32 @@ const prompt = await getPrompt({
 
 `prompt` can be selected by `{ name }`, `{ name, tag }`, or `{ versionId }`.
 
+## Manage Version Tags
+
+```ts
+import {
+  deletePromptVersionTag,
+  upsertPromptVersionTag,
+} from "@arizeai/phoenix-client/prompts";
+
+await upsertPromptVersionTag({
+  prompt: { versionId: "UHJvbXB0VmVyc2lvbjox" },
+  name: "production",
+  description: "Currently deployed version",
+});
+
+await deletePromptVersionTag({
+  prompt: { versionId: "UHJvbXB0VmVyc2lvbjox" },
+  name: "staging",
+});
+```
+
+Tag names are unique within a prompt, not within an individual version. Upserting a new name creates the tag on the target version. Upserting a name that already exists on another version of the same prompt moves that tag to the target version and updates its description. The same name can still be used independently by unrelated prompts.
+
+Deletion also resolves the name within the prompt identified by `prompt.versionId`; the tag can be attached to any version of that prompt.
+
+Tag upserts require Phoenix 8.22.0 or later. Tag deletion requires Phoenix 13.20.0 or later.
+
 ## Update Description And Metadata
 
 ```ts
@@ -99,9 +125,12 @@ Supported `sdk` targets:
   <ul>
     <li><code>src/prompts/createPrompt.ts</code></li>
     <li><code>src/prompts/deletePrompt.ts</code></li>
+    <li><code>src/prompts/deletePromptVersionTag.ts</code></li>
     <li><code>src/prompts/getPrompt.ts</code></li>
     <li><code>src/prompts/listPrompts.ts</code></li>
     <li><code>src/prompts/updatePrompt.ts</code></li>
+    <li><code>src/prompts/upsertPromptVersionTag.ts</code></li>
+    <li><code>src/utils/resolvePromptVersionId.ts</code></li>
     <li><code>src/prompts/sdks/toSDK.ts</code></li>
     <li><code>src/types/prompts.ts</code></li>
   </ul>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arizeai/phoenix-client",
-  "version": "7.14.0",
+  "version": "7.15.0",
   "description": "A client for the Phoenix API",
   "keywords": [
     "arize",
@@ -116,22 +116,22 @@
     "zod": "^4.6.5"
   },
   "devDependencies": {
-    "@ai-sdk/openai": "^4.0.71",
-    "@ai-sdk/otel": "^1.0.107",
+    "@ai-sdk/openai": "^4.0.78",
+    "@ai-sdk/otel": "^1.0.116",
     "@anthropic-ai/sdk": "^0.111.0",
     "@arizeai/phoenix-evals": "2.6.0",
     "@arizeai/phoenix-testing": "0.0.0",
     "@opentelemetry/api": "^1.9.1",
     "@opentelemetry/sdk-trace-node": "^2.11.0",
     "@types/async": "^3.2.26",
-    "@types/node": "^26.6.2",
-    "ai": "^7.0.107",
+    "@types/node": "^26.6.3",
+    "ai": "^7.0.116",
     "dotenv": "^17.4.2",
     "jest": "^30.5.2",
     "openai": "^6.49.0",
     "openapi-typescript": "^7.13.0",
-    "tsx": "^4.23.13",
-    "vitest": "^5.0.1"
+    "tsx": "^4.23.15",
+    "vitest": "^5.0.2"
   },
   "peerDependencies": {
     "@anthropic-ai/sdk": "^0.35.0",

package/src/__generated__/api/v1.ts

@@ -3334,6 +3334,11 @@ 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
@@ -9383,6 +9388,10 @@ 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: {
@@ -10580,10 +10589,14 @@ export interface operations {
     getSpans: {
         parameters: {
             query?: {
-                /** @description Pagination cursor (Span Global ID) */
+                /** @description Pagination cursor: the next_cursor of a previous response with the same sort */
                 cursor?: string | null;
                 /** @description Maximum number of spans to return */
                 limit?: number;
+                /** @description Sort field. 'id' orders by insertion; 'start_time' orders by when the span started, breaking ties by id. */
+                sort?: "id" | "start_time";
+                /** @description Sort direction */
+                order?: "asc" | "desc";
                 /** @description Inclusive lower bound time */
                 start_time?: string | null;
                 /** @description Exclusive upper bound time */

package/src/constants/serverRequirements.ts

@@ -199,6 +199,20 @@ export const DELETE_PROMPT: RouteRequirement = {
   minServerVersion: [13, 20, 0],
 };
 
+export const UPSERT_PROMPT_VERSION_TAG: RouteRequirement = {
+  kind: "route",
+  method: "POST",
+  path: "/v1/prompt_versions/{prompt_version_id}/tags",
+  minServerVersion: [8, 22, 0],
+};
+
+export const DELETE_PROMPT_VERSION_TAG: RouteRequirement = {
+  kind: "route",
+  method: "DELETE",
+  path: "/v1/prompt_versions/{prompt_version_id}/tags/{tag_name}",
+  minServerVersion: [13, 20, 0],
+};
+
 export const PATCH_PROMPT: RouteRequirement = {
   kind: "route",
   method: "PATCH",
@@ -293,6 +307,8 @@ export const ALL_REQUIREMENTS: readonly CapabilityRequirement[] = [
   ADD_SPAN_NOTE_IDENTIFIER,
   ADD_SESSION_NOTE_IDENTIFIER,
   DELETE_PROMPT,
+  UPSERT_PROMPT_VERSION_TAG,
+  DELETE_PROMPT_VERSION_TAG,
   PATCH_PROMPT,
   AGENT_SESSION_CREATE,
   AGENT_SESSION_LIST,

package/src/prompts/deletePromptVersionTag.ts

@@ -0,0 +1,64 @@
+import { createClient } from "../client";
+import { DELETE_PROMPT_VERSION_TAG } from "../constants/serverRequirements";
+import type { ClientFn } from "../types/core";
+import type { GetPromptByVersionSelector } from "../types/prompts";
+import { resolvePromptVersionId } from "../utils/resolvePromptVersionId";
+import { ensureServerCapability } from "../utils/serverVersionUtils";
+
+/**
+ * Parameters for deleting a prompt version tag.
+ */
+export interface DeletePromptVersionTagParams extends ClientFn {
+  /** A version belonging to the prompt that owns the tag. */
+  prompt: GetPromptByVersionSelector;
+  /** The prompt-scoped tag name to delete. */
+  name: string;
+}
+
+/**
+ * Delete a tag from the prompt that owns the given prompt version.
+ *
+ * Tag names are unique within a prompt, so `name` identifies the tag across
+ * all versions of that prompt. The tag does not need to be attached to the
+ * selected version.
+ *
+ * @param params - The prompt version tag to delete.
+ * @param params.prompt - A version selector used to identify the prompt.
+ * @param params.name - The prompt-scoped tag name to delete.
+ * @returns A promise that resolves once the tag has been deleted.
+ * @throws {@link HttpError} when Phoenix rejects the request.
+ *
+ * @example
+ * ```ts
+ * import { deletePromptVersionTag } from "@arizeai/phoenix-client/prompts";
+ *
+ * await deletePromptVersionTag({
+ *   prompt: { versionId: "UHJvbXB0VmVyc2lvbjox" },
+ *   name: "production",
+ * });
+ * ```
+ */
+export async function deletePromptVersionTag({
+  client: _client,
+  prompt,
+  name,
+}: DeletePromptVersionTagParams): Promise<void> {
+  const promptVersionId = resolvePromptVersionId(prompt);
+  const client = _client ?? createClient();
+  await ensureServerCapability({
+    client,
+    requirement: DELETE_PROMPT_VERSION_TAG,
+  });
+
+  await client.DELETE(
+    "/v1/prompt_versions/{prompt_version_id}/tags/{tag_name}",
+    {
+      params: {
+        path: {
+          prompt_version_id: promptVersionId,
+          tag_name: name,
+        },
+      },
+    }
+  );
+}

package/src/prompts/index.ts

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

package/src/prompts/upsertPromptVersionTag.ts

@@ -0,0 +1,69 @@
+import { createClient } from "../client";
+import { UPSERT_PROMPT_VERSION_TAG } from "../constants/serverRequirements";
+import type { ClientFn } from "../types/core";
+import type { GetPromptByVersionSelector } from "../types/prompts";
+import { resolvePromptVersionId } from "../utils/resolvePromptVersionId";
+import { ensureServerCapability } from "../utils/serverVersionUtils";
+
+/**
+ * Parameters for creating or moving a prompt version tag.
+ */
+export interface UpsertPromptVersionTagParams extends ClientFn {
+  /** The prompt version that should own the tag. */
+  prompt: GetPromptByVersionSelector;
+  /** The prompt-scoped tag name. */
+  name: string;
+  /** An optional description for the tag. */
+  description?: string | null;
+}
+
+/**
+ * Create a prompt version tag or move an existing tag to another version.
+ *
+ * Tag names are unique within a prompt. If another version of the same prompt
+ * already has `name`, the tag is moved to the selected version and its
+ * description is updated.
+ *
+ * @param params - The prompt version tag to create or move.
+ * @param params.prompt - The target prompt, selected by version ID.
+ * @param params.name - The prompt-scoped tag name.
+ * @param params.description - An optional description for the tag.
+ * @returns A promise that resolves once the tag has been created or moved.
+ * @throws {@link HttpError} when Phoenix rejects the request.
+ *
+ * @example
+ * ```ts
+ * import { upsertPromptVersionTag } from "@arizeai/phoenix-client/prompts";
+ *
+ * await upsertPromptVersionTag({
+ *   prompt: { versionId: "UHJvbXB0VmVyc2lvbjox" },
+ *   name: "production",
+ *   description: "Currently deployed version",
+ * });
+ * ```
+ */
+export async function upsertPromptVersionTag({
+  client: _client,
+  prompt,
+  name,
+  description,
+}: UpsertPromptVersionTagParams): Promise<void> {
+  const promptVersionId = resolvePromptVersionId(prompt);
+  const client = _client ?? createClient();
+  await ensureServerCapability({
+    client,
+    requirement: UPSERT_PROMPT_VERSION_TAG,
+  });
+
+  await client.POST("/v1/prompt_versions/{prompt_version_id}/tags", {
+    params: {
+      path: {
+        prompt_version_id: promptVersionId,
+      },
+    },
+    body: {
+      name,
+      description,
+    },
+  });
+}

package/src/utils/resolvePromptVersionId.ts

@@ -0,0 +1,18 @@
+import type { GetPromptByVersionSelector } from "../types/prompts";
+
+/**
+ * Resolve a version selector to the `{prompt_version_id}` path segment used by
+ * the Phoenix REST API.
+ *
+ * @param prompt - The prompt, selected by version ID.
+ * @returns The prompt version ID to interpolate into the request path.
+ * @throws An error if the selector does not contain a non-empty version ID.
+ */
+export function resolvePromptVersionId(
+  prompt: GetPromptByVersionSelector
+): string {
+  if (!prompt.versionId) {
+    throw new Error("versionId must be a non-empty prompt version id.");
+  }
+  return prompt.versionId;
+}