@arizeai/phoenix-client 7.3.1 → 7.4.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, and adapt prompt versions to supported provider SDKs.
+The prompts module lets you create prompt versions in Phoenix, fetch them back by selector, list prompts, update a prompt's description and metadata, 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,22 @@ const prompt = await getPrompt({
 
 `prompt` can be selected by `{ name }`, `{ name, tag }`, or `{ versionId }`.
 
+## Update Description And Metadata
+
+```ts
+import { updatePrompt } from "@arizeai/phoenix-client/prompts";
+
+await updatePrompt({
+  promptIdentifier: "support-response",
+  description: "Customer support reply prompt",
+  metadata: { team: "ml", env: "production" },
+});
+```
+
+`promptIdentifier` is a prompt name or ID. Omit a field to leave it unchanged, and pass `description: null` to clear it. `metadata` replaces the existing metadata object as a whole rather than merging into it.
+
+Requires a Phoenix server on 19.18.0 or later.
+
 ## Convert To Another SDK
 
 ```ts
@@ -67,6 +83,7 @@ Supported `sdk` targets:
     <li><code>src/prompts/createPrompt.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/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.3.1",
+  "version": "7.4.0",
   "description": "A client for the Phoenix API",
   "keywords": [
     "arize",

package/src/constants/serverRequirements.ts

@@ -138,6 +138,13 @@ export const ADD_SESSION_NOTE_IDENTIFIER: ParameterRequirement = {
   minServerVersion: [15, 5, 0],
 };
 
+export const PATCH_PROMPT: RouteRequirement = {
+  kind: "route",
+  method: "PATCH",
+  path: "/v1/prompts/{prompt_identifier}",
+  minServerVersion: [19, 18, 0],
+};
+
 /**
  * Aggregate list of every known capability requirement.
  *
@@ -161,4 +168,5 @@ export const ALL_REQUIREMENTS: readonly CapabilityRequirement[] = [
   ADD_TRACE_NOTE_IDENTIFIER,
   ADD_SPAN_NOTE_IDENTIFIER,
   ADD_SESSION_NOTE_IDENTIFIER,
+  PATCH_PROMPT,
 ] as const;

package/src/prompts/index.ts

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

package/src/prompts/updatePrompt.ts

@@ -0,0 +1,95 @@
+import invariant from "tiny-invariant";
+
+import { createClient } from "../client";
+import { PATCH_PROMPT } from "../constants/serverRequirements";
+import { HttpError } from "../errors";
+import type { ClientFn } from "../types/core";
+import type { Prompt } from "../types/prompts";
+import { ensureServerCapability } from "../utils/serverVersionUtils";
+
+/**
+ * Parameters for updating a prompt's description and/or metadata.
+ *
+ * Omit a field to leave it unchanged. Pass `description: null` to clear the
+ * description. `metadata` replaces the existing metadata object as a whole.
+ */
+export interface UpdatePromptParams extends ClientFn {
+  /**
+   * The prompt name or ID.
+   */
+  promptIdentifier: string;
+  /**
+   * New description for the prompt. Pass `null` to clear it. Omit to leave
+   * unchanged.
+   */
+  description?: string | null;
+  /**
+   * New metadata object for the prompt (full replace). Omit to leave unchanged.
+   */
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * Update a prompt's description and/or metadata via
+ * `PATCH /v1/prompts/{prompt_identifier}`.
+ *
+ * @param params - The parameters to update the prompt.
+ * @returns The updated prompt.
+ *
+ * @requires Phoenix server >= 19.18.0
+ *
+ * @example
+ * ```ts
+ * import { updatePrompt } from "@arizeai/phoenix-client/prompts";
+ *
+ * const prompt = await updatePrompt({
+ *   promptIdentifier: "my-prompt",
+ *   description: "Production classifier",
+ *   metadata: { team: "ml", env: "prod" },
+ * });
+ *
+ * // Clear the description only
+ * await updatePrompt({
+ *   promptIdentifier: "my-prompt",
+ *   description: null,
+ * });
+ * ```
+ */
+export async function updatePrompt({
+  client: _client,
+  promptIdentifier,
+  description,
+  metadata,
+}: UpdatePromptParams): Promise<Prompt> {
+  if (description === undefined && metadata === undefined) {
+    throw new Error(
+      "At least one of description or metadata must be provided."
+    );
+  }
+
+  const client = _client ?? createClient();
+  await ensureServerCapability({ client, requirement: PATCH_PROMPT });
+
+  try {
+    const response = await client.PATCH("/v1/prompts/{prompt_identifier}", {
+      params: {
+        path: {
+          prompt_identifier: promptIdentifier,
+        },
+      },
+      body: {
+        ...(description !== undefined ? { description } : {}),
+        ...(metadata !== undefined ? { metadata } : {}),
+      },
+    });
+    invariant(response.data?.data, "Failed to update prompt");
+    return response.data.data;
+  } catch (error) {
+    if (error instanceof HttpError && error.status === 404) {
+      throw new Error(`Prompt not found: ${promptIdentifier}`, {
+        cause: error,
+      });
+    }
+    throw error;
+  }
+}