@arizeai/phoenix-client 7.13.0 → 7.15.0

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/types/datasets.ts

@@ -1,13 +1,18 @@
+import type { components } from "../__generated__/api/v1";
 import type { Node } from "./core";
 
+/** A named subset of examples in a dataset. */
+export type DatasetSplit = components["schemas"]["DatasetSplit"];
+
 type DatasetSelectorBase = { versionId?: string; splits?: string[] };
 
+/** A dataset identified by either its GlobalID or name. */
+export type DatasetIdentifier = { datasetId: string } | { datasetName: string };
+
 /**
  * A dataset can be identified by its datasetId, datasetName, or datasetVersionId
  */
-export type DatasetSelector =
-  | (DatasetSelectorBase & { datasetId: string })
-  | (DatasetSelectorBase & { datasetName: string });
+export type DatasetSelector = DatasetSelectorBase & DatasetIdentifier;
 
 /**
  * Overview information about a dataset

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;
+}