@arizeai/phoenix-client 7.14.0 → 7.16.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/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;
+}

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