Prompt Version Tagging#

Prompt version tags are named, human-readable labels (e.g., production, staging, development) that can be assigned to specific prompt versions in Phoenix. They provide a lightweight aliasing system so callers can resolve a prompt by a stable tag name rather than a version ID.

Default Tags#

Three built-in tags are pre-seeded from DEFAULT_PROMPT_VERSION_TAGS in app/src/constants/promptConstants.ts:

These defaults are merged with any custom tags the user has created when rendering the tag selection popover 1.

Tag Name Constraints#

Tag names must satisfy the identifierPattern validator from app/src/utils/identifierUtils.ts: lowercase alphanumeric, allowing internal underscores and dashes, but starting and ending with alphanumeric characters (/^[a-z0-9]([_a-z0-9-]*[a-z0-9])?$/).

Key UI Components#

TagPromptVersionButton#

TagPromptVersionButton.tsx is the primary entry point for tagging a version. It renders a "Tag Version" button on the prompt version page (requires promptId and versionId from route params). Clicking it opens a Popover with a TagList sub-component showing all available tags as checkboxes — pre-checked if the tag is already applied to the current version 2.

• Tags already applied are shown as checked and disabled (no un-tagging via this UI; a tag can only be moved, not removed).
• The "New Tag" button inside the popover dismisses it and opens the NewPromptVersionDialog 3.

Data is loaded via a lazy Relay query TagPromptVersionButtonTagsQuery that fetches both all versionTags on the prompt and the tags already applied to the specific version.

NewPromptVersionTagDialog#

NewPromptVersionTagDialog.tsx is a modal form (react-hook-form + Relay mutation) for creating a new tag and immediately assigning it to the current prompt version. Fields:

• Tag Name — required, validated against identifierPattern 4
• Description — optional free text

On submit it fires the setPromptVersionTag GraphQL mutation 5 and re-fetches the PromptVersionTagsList_data fragment to refresh the version's tag list.

PromptVersionTagsConfigCard#

PromptVersionTagsConfigCard.tsx renders a compact sortable table of all tags defined on a prompt (not per-version). Columns: Name, Description, and a linked Version ID that navigates to /prompts/:promptId/versions/:versionId. Each row has an inline DeletePromptVersionTagButton 6 that fires the deletePromptVersionTag mutation.

Data comes from the PromptVersionTagsConfigCard_data Relay fragment on the Prompt type 7, querying versionTags { id, name, description, promptVersionId }.

GraphQL API Surface#

File Map#