arize-phoenix 8.21.0__py3-none-any.whl → 8.22.0__py3-none-any.whl

{arize_phoenix-8.21.0.dist-info → arize_phoenix-8.22.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: arize-phoenix
-Version: 8.21.0
+Version: 8.22.0
 Summary: AI Observability and Evaluation
 Project-URL: Documentation, https://docs.arize.com/phoenix/
 Project-URL: Issues, https://github.com/Arize-ai/phoenix/issues

{arize_phoenix-8.21.0.dist-info → arize_phoenix-8.22.0.dist-info}/RECORD

@@ -6,7 +6,7 @@ phoenix/exceptions.py,sha256=n2L2KKuecrdflB9MsCdAYCiSEvGJptIsfRkXMoJle7A,169
 phoenix/py.typed,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
 phoenix/services.py,sha256=kpW1WL0kiB8XJsO6XycvZVJ-lBkNoenhQ7atCvBoSe8,5365
 phoenix/settings.py,sha256=x87BX7hWGQQZbrW_vrYqFR_izCGfO9gFc--JXUG4Tdk,754
-phoenix/version.py,sha256=IcFew5OfUbzsX2QRcX00Ngf0cInzeuF_IhyKYRXmTmI,23
+phoenix/version.py,sha256=87-3KQINFNZAUcsrNLppOae3DX76fIASs9wL99nLugI,23
 phoenix/core/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 phoenix/core/embedding_dimension.py,sha256=zKGbcvwOXgLf-yrJBpQyKtd-LEOPRKHnUToyAU8Owis,87
 phoenix/core/model.py,sha256=qBFraOtmwCCnWJltKNP18DDG0mULXigytlFsa6YOz6k,4837
@@ -27,7 +27,7 @@ phoenix/db/insertion/constants.py,sha256=8wifm7X-1XvroZ__R2Gc96NsgLhTDn0zXl4lehl
 phoenix/db/insertion/dataset.py,sha256=I9OC1ouVx7m6BH_c8hvcxW1dWGRAtpvXee29yBTuFkg,7136
 phoenix/db/insertion/document_annotation.py,sha256=vnszF9L0qHjUY-eWgBVRG5OTpz-ECs1BoCfy66ynzjo,5997
 phoenix/db/insertion/evaluation.py,sha256=SoI85N3MYUSeNgjKa5WzFw14OfNjNTjExv-2m3sxaR8,6371
-phoenix/db/insertion/helpers.py,sha256=-DyRcxzJnjSJFhscPoqiNiQn8fBvGqI8IcNJEu-79Vw,3455
+phoenix/db/insertion/helpers.py,sha256=PlYtLI6SfmQwoLZ8UYrkAffygjMwiuZz1FPs6g7Vchs,3437
 phoenix/db/insertion/span.py,sha256=02hpGo5ZY6N-n6Z-far-AC_yVAloXpJyt-CIHOeor0k,8126
 phoenix/db/insertion/span_annotation.py,sha256=EtzcjS8GR2rDM_cxIQloGc2SZqfdrACyAPwvyFBa2Ac,5273
 phoenix/db/insertion/trace_annotation.py,sha256=6yzWuU0Fh-mC-rJJ96rH0IYTJg1EQFnj-GZhUwolUKI,5338
@@ -44,7 +44,7 @@ phoenix/db/migrations/versions/bc8fea3c2bc8_add_prompt_tables.py,sha256=rq-bwg0g
 phoenix/db/migrations/versions/cd164e83824f_users_and_tokens.py,sha256=fkpmh5PgMZJiZpvLbZIaqlI2cucVpVbbNYpQ-Tznil8,5180
 phoenix/db/migrations/versions/cf03bd6bae1d_init.py,sha256=ZNQzTUyb3p9Bkq7rjd5MRxGQV8W08zpY8E3GlzSJ2cM,8630
 phoenix/db/types/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-phoenix/db/types/identifier.py,sha256=TSm3o4CDnd7vNyQj3c8CKtrx04ZNaDFDbYLFHTi0_7I,181
+phoenix/db/types/identifier.py,sha256=Opr3_1di6e5ncrBDn30WfBSr-jN_VGBnkkA4BMuSoyc,244
 phoenix/db/types/model_provider.py,sha256=96UMeqiy5X9PmYMOWA6dZAmI_BSV3yVxt9HEVYGe5Ns,157
 phoenix/experiments/__init__.py,sha256=6JGwgUd7xCbGpuHqYZlsmErmYvVgv7N_j43bn3dUqsk,123
 phoenix/experiments/functions.py,sha256=QOwYNMO1qxG2bah4ZjJKMk7agFkZRWGvwyazLcwRCys,32573
@@ -99,7 +99,7 @@ phoenix/server/api/auth.py,sha256=nywpmfMI1trZTbZRD3oBj4kFjzg_vnxDljcM431T1eY,12
 phoenix/server/api/context.py,sha256=OopBkMnY48TzulTtfuay3MXmhbFIWPtPoAsbhCW-Pl0,6459
 phoenix/server/api/exceptions.py,sha256=TA0JuY2YRnj35qGuMSQ8d0ToHum9gWm9W--3fSKHrX0,1171
 phoenix/server/api/interceptor.py,sha256=ykDnoC_apUd-llVli3m1CW18kNSIgjz2qZ6m5JmPDu8,1294
-phoenix/server/api/queries.py,sha256=e_zt4VKQj3dnLIrVEFbxIOhFo8bup_vVN9xAqVW009w,35726
+phoenix/server/api/queries.py,sha256=Xd1K-6bu_DuUxczyXzf0M6EiRL7Ahnx47QVqPmo2-58,36167
 phoenix/server/api/schema.py,sha256=fcs36xQwFF_Qe41_5cWR8wYpDvOrnbcyTeo5WNMbDsA,1702
 phoenix/server/api/subscriptions.py,sha256=DSIgQF6lQqkbc7D0AaI5R4g3hIHbU04H5Y2UIpwmpy0,22989
 phoenix/server/api/utils.py,sha256=quCBRcusc6PUq9tJq7M8PgwFZp7nXgVAxtbw8feribY,833
@@ -217,7 +217,7 @@ phoenix/server/api/routers/v1/experiment_evaluations.py,sha256=vx4CKlE84sAL1vtPi
 phoenix/server/api/routers/v1/experiment_runs.py,sha256=bInuasRv7ogiYf8fq-LwpJ5tptmMQsBNDlJAqwdymko,6378
 phoenix/server/api/routers/v1/experiments.py,sha256=V9_sxqLTE1MKGFu9H3FEdGKr70lYMbGZx813MGaavfQ,20430
 phoenix/server/api/routers/v1/models.py,sha256=r0nM2kFJ3mxDqgc5vFr1cjNuyOPs3RIKE_DS2VMdF48,1749
-phoenix/server/api/routers/v1/prompts.py,sha256=ytK8HnOZNxUMDtC7XAFxzaTSM9DMMua13vWsqqd4PAw,14986
+phoenix/server/api/routers/v1/prompts.py,sha256=aBOUBwLDzZDIzJQkxJcR8ZKnakNJOLMwzsLKINSs1mA,26545
 phoenix/server/api/routers/v1/spans.py,sha256=uoU_bwIgz86fuvPjP5sX8goDyuCcnsTig-x3f17p60U,9625
 phoenix/server/api/routers/v1/traces.py,sha256=hSv35QIB4mwFgp53rOpz3zWIiSwbZzQnjafD790QuJU,7908
 phoenix/server/api/routers/v1/utils.py,sha256=SoRl0Dc8By15ZckhNcXg2QRrqYjMvgTjVcqrZ6MwVmo,3065
@@ -273,7 +273,7 @@ phoenix/server/api/types/Prompt.py,sha256=ccP4eq1e38xbF0afclGWLOuDpBVpNbJ3AOSRCl
 phoenix/server/api/types/PromptLabel.py,sha256=g3IDSPYRZwb0qpMAk93R6J96jgYULUYGOciTnpeh3sI,1321
 phoenix/server/api/types/PromptResponse.py,sha256=Q8HKtpp8GpUOcxPCzZpkkokidDd6u0aZOv_SuPZZd5Q,630
 phoenix/server/api/types/PromptVersion.py,sha256=hLPwOwj1h0gH4fqpLS-xwcC2TQYLCmvaCiEkyXvTS1g,5494
-phoenix/server/api/types/PromptVersionTag.py,sha256=K2pbK-pIjzCTfwcwPpyk91m52XMhMlH0dLcPnaxyb4M,836
+phoenix/server/api/types/PromptVersionTag.py,sha256=dSumwkBv2P-yDLxE0tnu8O87M2ZcuhLrmnBb4CkuyC4,1389
 phoenix/server/api/types/PromptVersionTemplate.py,sha256=jlHJS079OhI8IHZoWQn0aIz5JnHOuYc8iD8UkytyzEQ,4627
 phoenix/server/api/types/ResponseFormat.py,sha256=ymBsPWGViiaEo4vyw50ht1K6BveKcOZ2YNce50PAoew,182
 phoenix/server/api/types/Retrieval.py,sha256=OhMK2ncjoyp5h1yjKhjlKpoTbQrMHuxmgSFw-AO1rWw,285
@@ -364,9 +364,9 @@ phoenix/utilities/project.py,sha256=auVpARXkDb-JgeX5f2aStyFIkeKvGwN9l7qrFeJMVxI,
 phoenix/utilities/re.py,sha256=6YyUWIkv0zc2SigsxfOWIHzdpjKA_TZo2iqKq7zJKvw,2081
 phoenix/utilities/span_store.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 phoenix/utilities/template_formatters.py,sha256=gh9PJD6WEGw7TEYXfSst1UR4pWWwmjxMLrDVQ_CkpkQ,2779
-arize_phoenix-8.21.0.dist-info/METADATA,sha256=0DkKUK_8BHpdYpiMIfmCLhA8bRmpQeHmmh0PgqoMmUU,21378
-arize_phoenix-8.21.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-arize_phoenix-8.21.0.dist-info/entry_points.txt,sha256=Pgpn8Upxx9P8z8joPXZWl2LlnAlGc3gcQoVchb06X1Q,94
-arize_phoenix-8.21.0.dist-info/licenses/IP_NOTICE,sha256=JBqyyCYYxGDfzQ0TtsQgjts41IJoa-hiwDrBjCb9gHM,469
-arize_phoenix-8.21.0.dist-info/licenses/LICENSE,sha256=HFkW9REuMOkvKRACuwLPT0hRydHb3zNg-fdFt94td18,3794
-arize_phoenix-8.21.0.dist-info/RECORD,,
+arize_phoenix-8.22.0.dist-info/METADATA,sha256=ahp8w8u1QgKzZCz7LglKC0DXLYJS-yZjFH7igLe2yO0,21378
+arize_phoenix-8.22.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+arize_phoenix-8.22.0.dist-info/entry_points.txt,sha256=Pgpn8Upxx9P8z8joPXZWl2LlnAlGc3gcQoVchb06X1Q,94
+arize_phoenix-8.22.0.dist-info/licenses/IP_NOTICE,sha256=JBqyyCYYxGDfzQ0TtsQgjts41IJoa-hiwDrBjCb9gHM,469
+arize_phoenix-8.22.0.dist-info/licenses/LICENSE,sha256=HFkW9REuMOkvKRACuwLPT0hRydHb3zNg-fdFt94td18,3794
+arize_phoenix-8.22.0.dist-info/RECORD,,

phoenix/db/insertion/helpers.py

@@ -78,7 +78,7 @@ def _clean(
     kv: Iterable[tuple[str, KeyedColumnElement[Any]]],
 ) -> Iterator[tuple[str, KeyedColumnElement[Any]]]:
     for k, v in kv:
-        if v.primary_key or v.foreign_keys or k == "created_at":
+        if v.primary_key or k == "created_at":
             continue
         if k == "metadata_":
             yield "metadata", v

phoenix/db/types/identifier.py

@@ -5,3 +5,6 @@ from pydantic import Field, RootModel
 
 class Identifier(RootModel[str]):
     root: Annotated[str, Field(pattern=r"^[a-z0-9]([_a-z0-9-]*[a-z0-9])?$")]
+
+    def __hash__(self) -> int:
+        return hash(self.root)

phoenix/server/api/queries.py

@@ -69,6 +69,7 @@ from phoenix.server.api.types.ProjectSession import ProjectSession, to_gql_proje
 from phoenix.server.api.types.Prompt import Prompt, to_gql_prompt_from_orm
 from phoenix.server.api.types.PromptLabel import PromptLabel, to_gql_prompt_label
 from phoenix.server.api.types.PromptVersion import PromptVersion, to_gql_prompt_version
+from phoenix.server.api.types.PromptVersionTag import PromptVersionTag, to_gql_prompt_version_tag
 from phoenix.server.api.types.SortDir import SortDir
 from phoenix.server.api.types.Span import Span
 from phoenix.server.api.types.SystemApiKey import SystemApiKey
@@ -596,6 +597,11 @@ class Query:
                 ):
                     raise NotFound(f"Unknown prompt label: {id}")
             return to_gql_prompt_label(prompt_label)
+        elif type_name == PromptVersionTag.__name__:
+            async with info.context.db() as session:
+                if not (prompt_version_tag := await session.get(models.PromptVersionTag, node_id)):
+                    raise NotFound(f"Unknown prompt version tag: {id}")
+            return to_gql_prompt_version_tag(prompt_version_tag)
         raise NotFound(f"Unknown node type: {type_name}")
 
     @strawberry.field

phoenix/server/api/routers/v1/prompts.py

@@ -6,11 +6,13 @@ from pydantic import ValidationError, model_validator
 from sqlalchemy import select
 from sqlalchemy.sql import Select
 from starlette.requests import Request
-from starlette.status import HTTP_404_NOT_FOUND, HTTP_422_UNPROCESSABLE_ENTITY
+from starlette.status import HTTP_204_NO_CONTENT, HTTP_404_NOT_FOUND, HTTP_422_UNPROCESSABLE_ENTITY
 from strawberry.relay import GlobalID
 from typing_extensions import Self, TypeAlias, assert_never
 
 from phoenix.db import models
+from phoenix.db.helpers import SupportedSQLDialect
+from phoenix.db.insertion.helpers import OnConflict, insert_on_conflict
 from phoenix.db.types.identifier import Identifier
 from phoenix.db.types.model_provider import ModelProvider
 from phoenix.server.api.helpers.prompts.models import (
@@ -22,10 +24,15 @@ from phoenix.server.api.helpers.prompts.models import (
     PromptTools,
 )
 from phoenix.server.api.routers.v1.models import V1RoutesBaseModel
-from phoenix.server.api.routers.v1.utils import ResponseBody, add_errors_to_responses
+from phoenix.server.api.routers.v1.utils import (
+    PaginatedResponseBody,
+    ResponseBody,
+    add_errors_to_responses,
+)
 from phoenix.server.api.types.node import from_global_id_with_expected_type
 from phoenix.server.api.types.Prompt import Prompt as PromptNodeType
 from phoenix.server.api.types.PromptVersion import PromptVersion as PromptVersionNodeType
+from phoenix.server.api.types.PromptVersionTag import PromptVersionTag as PromptVersionTagNodeType
 from phoenix.server.bearer_auth import PhoenixUser
 
 logger = logging.getLogger(__name__)
@@ -73,11 +80,11 @@ class GetPromptResponseBody(ResponseBody[PromptVersion]):
     pass
 
 
-class GetPromptsResponseBody(ResponseBody[list[Prompt]]):
+class GetPromptsResponseBody(PaginatedResponseBody[Prompt]):
     pass
 
 
-class GetPromptVersionsResponseBody(ResponseBody[list[PromptVersion]]):
+class GetPromptVersionsResponseBody(PaginatedResponseBody[PromptVersion]):
     pass
 
 
@@ -96,7 +103,10 @@ router = APIRouter(tags=["prompts"])
 @router.get(
     "/prompts",
     operation_id="getPrompts",
-    summary="Get all prompts",
+    summary="List all prompts",
+    description="Retrieve a paginated list of all prompts in the system. A prompt can have "
+    "multiple versions.",
+    response_description="A list of prompts with pagination information",
     responses=add_errors_to_responses(
         [
             HTTP_422_UNPROCESSABLE_ENTITY,
@@ -113,7 +123,27 @@ async def get_prompts(
         default=100, description="The max number of prompts to return at a time.", gt=0
     ),
 ) -> GetPromptsResponseBody:
+    """
+    Retrieve a paginated list of all prompts in the system.
+
+    Args:
+        request (Request): The FastAPI request object.
+        cursor (Optional[str]): Pagination cursor (base64-encoded prompt ID).
+        limit (int): Maximum number of prompts to return per request.
+
+    Returns:
+        GetPromptsResponseBody: Response containing a list of prompts and pagination information.
+
+    Raises:
+        HTTPException: If the cursor format is invalid.
+    """
     async with request.app.state.db() as session:
+        # First check if any prompts exist
+        if not cursor:
+            prompt_exists = await session.scalar(select(models.Prompt.id).limit(1))
+            if not prompt_exists:
+                return GetPromptsResponseBody(next_cursor=None, data=[])
+
         query = select(models.Prompt).order_by(models.Prompt.id.desc())
 
         if cursor:
@@ -146,8 +176,11 @@ async def get_prompts(
 @router.get(
     "/prompts/{prompt_identifier}/versions",
     operation_id="listPromptVersions",
-    summary="List all prompt versions for a given prompt",
-    responses=add_errors_to_responses([HTTP_422_UNPROCESSABLE_ENTITY]),
+    summary="List prompt versions",
+    description="Retrieve all versions of a specific prompt with pagination support. Each prompt "
+    "can have multiple versions with different configurations.",
+    response_description="A list of prompt versions with pagination information",
+    responses=add_errors_to_responses([HTTP_422_UNPROCESSABLE_ENTITY, HTTP_404_NOT_FOUND]),
     response_model_by_alias=True,
     response_model_exclude_defaults=True,
     response_model_exclude_unset=True,
@@ -163,6 +196,23 @@ async def list_prompt_versions(
         default=100, description="The max number of prompt versions to return at a time.", gt=0
     ),
 ) -> GetPromptVersionsResponseBody:
+    """
+    List all versions of a specific prompt with pagination support.
+
+    Args:
+        request (Request): The FastAPI request object.
+        prompt_identifier (str): The identifier of the prompt (name or ID).
+        cursor (Optional[str]): Pagination cursor (base64-encoded promptVersion ID).
+        limit (int): Maximum number of prompt versions to return per request.
+
+    Returns:
+        GetPromptVersionsResponseBody: Response containing a list of prompt versions and pagination
+            information.
+
+    Raises:
+        HTTPException: If the cursor format is invalid, the prompt identifier is invalid,
+            or the prompt is not found.
+    """
     query = select(models.PromptVersion)
     query = _filter_by_prompt_identifier(query.join(models.Prompt), prompt_identifier)
     query = query.order_by(models.PromptVersion.id.desc())
@@ -198,7 +248,10 @@ async def list_prompt_versions(
 @router.get(
     "/prompt_versions/{prompt_version_id}",
     operation_id="getPromptVersionByPromptVersionId",
-    summary="Get prompt by prompt version ID",
+    summary="Get prompt version by ID",
+    description="Retrieve a specific prompt version using its unique identifier. A prompt version "
+    "contains the actual template and configuration.",
+    response_description="The requested prompt version",
     responses=add_errors_to_responses(
         [
             HTTP_404_NOT_FOUND,
@@ -213,6 +266,19 @@ async def get_prompt_version_by_prompt_version_id(
     request: Request,
     prompt_version_id: str = Path(description="The ID of the prompt version."),
 ) -> GetPromptResponseBody:
+    """
+    Retrieve a specific prompt version by its ID.
+
+    Args:
+        request (Request): The FastAPI request object.
+        prompt_version_id (str): The ID of the prompt version to retrieve.
+
+    Returns:
+        GetPromptResponseBody: Response containing the requested prompt version.
+
+    Raises:
+        HTTPException: If the prompt version ID is invalid or the prompt version is not found.
+    """
     try:
         id_ = from_global_id_with_expected_type(
             GlobalID.from_id(prompt_version_id),
@@ -231,7 +297,10 @@ async def get_prompt_version_by_prompt_version_id(
 @router.get(
     "/prompts/{prompt_identifier}/tags/{tag_name}",
     operation_id="getPromptVersionByTagName",
-    summary="Get prompt by tag name",
+    summary="Get prompt version by tag",
+    description="Retrieve a specific prompt version using its tag name. Tags are used to identify "
+    "specific versions of a prompt.",
+    response_description="The prompt version with the specified tag",
     responses=add_errors_to_responses(
         [
             HTTP_404_NOT_FOUND,
@@ -247,6 +316,20 @@ async def get_prompt_version_by_tag_name(
     prompt_identifier: str = Path(description="The identifier of the prompt, i.e. name or ID."),
     tag_name: str = Path(description="The tag of the prompt version"),
 ) -> GetPromptResponseBody:
+    """
+    Retrieve a specific prompt version by its tag name.
+
+    Args:
+        request (Request): The FastAPI request object.
+        prompt_identifier (str): The identifier of the prompt (name or ID).
+        tag_name (str): The tag name associated with the prompt version.
+
+    Returns:
+        GetPromptResponseBody: Response containing the prompt version with the specified tag.
+
+    Raises:
+        HTTPException: If the tag name is invalid or the prompt version is not found.
+    """
     try:
         name = Identifier.model_validate(tag_name)
     except ValidationError:
@@ -268,7 +351,9 @@ async def get_prompt_version_by_tag_name(
 @router.get(
     "/prompts/{prompt_identifier}/latest",
     operation_id="getPromptVersionLatest",
-    summary="Get the latest prompt version",
+    summary="Get latest prompt version",
+    description="Retrieve the most recent version of a specific prompt.",
+    response_description="The latest version of the specified prompt",
     responses=add_errors_to_responses(
         [
             HTTP_404_NOT_FOUND,
@@ -283,6 +368,19 @@ async def get_prompt_version_by_latest(
     request: Request,
     prompt_identifier: str = Path(description="The identifier of the prompt, i.e. name or ID."),
 ) -> GetPromptResponseBody:
+    """
+    Retrieve the latest version of a specific prompt.
+
+    Args:
+        request (Request): The FastAPI request object.
+        prompt_identifier (str): The identifier of the prompt (name or ID).
+
+    Returns:
+        GetPromptResponseBody: Response containing the latest prompt version.
+
+    Raises:
+        HTTPException: If the prompt identifier is invalid or no prompt version is found.
+    """
     stmt = select(models.PromptVersion).order_by(models.PromptVersion.id.desc()).limit(1)
     stmt = _filter_by_prompt_identifier(stmt.join(models.Prompt), prompt_identifier)
     async with request.app.state.db() as session:
@@ -296,7 +394,9 @@ async def get_prompt_version_by_latest(
 @router.post(
     "/prompts",
     operation_id="postPromptVersion",
-    summary="Create a prompt version",
+    summary="Create a new prompt",
+    description="Create a new prompt and its initial version. A prompt can have multiple versions.",
+    response_description="The newly created prompt version",
     responses=add_errors_to_responses(
         [
             HTTP_422_UNPROCESSABLE_ENTITY,
@@ -310,6 +410,20 @@ async def create_prompt(
     request: Request,
     request_body: CreatePromptRequestBody,
 ) -> CreatePromptResponseBody:
+    """
+    Create a new prompt and its initial version.
+
+    Args:
+        request (Request): The FastAPI request object.
+        request_body (CreatePromptRequestBody): The request body containing prompt and version data.
+
+    Returns:
+        CreatePromptResponseBody: Response containing the created prompt version.
+
+    Raises:
+        HTTPException: If the template type is not supported, the name identifier is invalid,
+                      or any other validation error occurs.
+    """
     if (
         request_body.version.template.type.lower() != "chat"
         or request_body.version.template_type != PromptTemplateType.CHAT
@@ -358,6 +472,207 @@ async def create_prompt(
     return CreatePromptResponseBody(data=data)
 
 
+class PromptVersionTagData(V1RoutesBaseModel):
+    name: Identifier
+    description: Optional[str] = None
+
+
+class PromptVersionTag(PromptVersionTagData):
+    id: str
+
+
+class GetPromptVersionTagsResponseBody(PaginatedResponseBody[PromptVersionTag]):
+    pass
+
+
+@router.get(
+    "/prompt_versions/{prompt_version_id}/tags",
+    operation_id="getPromptVersionTags",
+    summary="List prompt version tags",
+    description="Retrieve all tags associated with a specific prompt version. Tags are used to "
+    "identify and categorize different versions of a prompt.",
+    response_description="A list of tags associated with the prompt version",
+    responses=add_errors_to_responses(
+        [
+            HTTP_404_NOT_FOUND,
+            HTTP_422_UNPROCESSABLE_ENTITY,
+        ]
+    ),
+    response_model_by_alias=True,
+    response_model_exclude_defaults=True,
+    response_model_exclude_unset=True,
+)
+async def list_prompt_version_tags(
+    request: Request,
+    prompt_version_id: str = Path(description="The ID of the prompt version."),
+    cursor: Optional[str] = Query(
+        default=None,
+        description="Cursor for pagination (base64-encoded promptVersionTag ID)",
+    ),
+    limit: int = Query(
+        default=100, description="The max number of tags to return at a time.", gt=0
+    ),
+) -> GetPromptVersionTagsResponseBody:
+    """
+    Get tags for a specific prompt version.
+
+    Args:
+        request (Request): The request object.
+        prompt_version_id (str): The ID of the prompt version.
+        cursor (Optional[str]): Pagination cursor (base64-encoded promptVersionTag ID).
+        limit (int): Maximum number of tags to return per request.
+
+    Returns:
+        GetPromptVersionTagsResponseBody: The response body containing the tags.
+
+    Raises:
+        HTTPException: If the prompt version ID is invalid, the prompt version is not found,
+            or the cursor format is invalid.
+    """
+    try:
+        id_ = from_global_id_with_expected_type(
+            GlobalID.from_id(prompt_version_id),
+            PromptVersionNodeType.__name__,
+        )
+    except ValueError:
+        raise HTTPException(HTTP_422_UNPROCESSABLE_ENTITY, "Invalid prompt version ID")
+
+    # Build the query for tags
+    stmt = (
+        select(
+            models.PromptVersion.id,
+            models.PromptVersionTag.id,
+            models.PromptVersionTag.name,
+            models.PromptVersionTag.description,
+        )
+        .outerjoin_from(models.PromptVersion, models.PromptVersionTag)
+        .where(models.PromptVersion.id == id_)
+        .order_by(models.PromptVersionTag.id.desc())
+    )
+
+    # Apply cursor-based pagination
+    if cursor:
+        try:
+            cursor_id = GlobalID.from_id(cursor).node_id
+            stmt = stmt.filter(models.PromptVersionTag.id <= int(cursor_id))
+        except ValueError:
+            raise HTTPException(
+                detail=f"Invalid cursor format: {cursor}",
+                status_code=HTTP_422_UNPROCESSABLE_ENTITY,
+            )
+
+    # Apply limit
+    stmt = stmt.limit(limit + 1)
+
+    async with request.app.state.db() as session:
+        result = (await session.execute(stmt)).all()
+
+    # Check if prompt version exists
+    if not result:
+        raise HTTPException(HTTP_404_NOT_FOUND, "Prompt version not found")
+
+    # Check if there are any tags
+    has_tags = any(id_ is not None for _, id_, _, _ in result)
+    if not has_tags:
+        return GetPromptVersionTagsResponseBody(next_cursor=None, data=[])
+
+    # Check if there are more results
+    next_cursor = None
+    if len(result) == limit + 1:
+        # Remove the extra item used for pagination
+        result = result[:-1]
+        # Get the ID of the last item for the next cursor
+        last_tag_id = result[-1][1]  # The second element is the tag ID
+        if last_tag_id is not None:
+            next_cursor = str(GlobalID(PromptVersionTagNodeType.__name__, str(last_tag_id)))
+
+    # Convert to response format
+    data = [
+        PromptVersionTag(
+            id=str(GlobalID(PromptVersionTagNodeType.__name__, str(id_))),
+            name=name,
+            description=description,
+        )
+        for _, id_, name, description in result
+        if id_ is not None
+    ]
+
+    return GetPromptVersionTagsResponseBody(next_cursor=next_cursor, data=data)
+
+
+@router.post(
+    "/prompt_versions/{prompt_version_id}/tags",
+    operation_id="createPromptVersionTag",
+    summary="Add tag to prompt version",
+    description="Add a new tag to a specific prompt version. Tags help identify and categorize "
+    "different versions of a prompt.",
+    response_description="No content returned on successful tag creation",
+    status_code=HTTP_204_NO_CONTENT,
+    responses=add_errors_to_responses(
+        [
+            HTTP_404_NOT_FOUND,
+            HTTP_422_UNPROCESSABLE_ENTITY,
+        ]
+    ),
+    response_model_by_alias=True,
+    response_model_exclude_defaults=True,
+    response_model_exclude_unset=True,
+)
+async def create_prompt_version_tag(
+    request: Request,
+    request_body: PromptVersionTagData,
+    prompt_version_id: str = Path(description="The ID of the prompt version."),
+) -> None:
+    """
+    Add a tag to a specific prompt version.
+
+    Args:
+        request (Request): The FastAPI request object.
+        request_body (PromptVersionTagData): The tag data to be added.
+        prompt_version_id (str): The ID of the prompt version to tag.
+
+    Returns:
+        None: Returns a 204 No Content response on success.
+
+    Raises:
+        HTTPException: If the prompt version ID is invalid, the prompt version is not found,
+            or any other validation error occurs.
+    """
+    try:
+        id_ = from_global_id_with_expected_type(
+            GlobalID.from_id(prompt_version_id),
+            PromptVersionNodeType.__name__,
+        )
+    except ValueError:
+        raise HTTPException(HTTP_422_UNPROCESSABLE_ENTITY, "Invalid prompt version ID")
+    user_id: Optional[int] = None
+    if request.app.state.authentication_enabled:
+        assert isinstance(user := request.user, PhoenixUser)
+        user_id = int(user.identity)
+    async with request.app.state.db() as session:
+        prompt_id = await session.scalar(select(models.PromptVersion.prompt_id).filter_by(id=id_))
+        if prompt_id is None:
+            raise HTTPException(HTTP_404_NOT_FOUND)
+        dialect = SupportedSQLDialect(session.bind.dialect.name)
+        values = dict(
+            name=request_body.name,
+            description=request_body.description,
+            prompt_id=prompt_id,
+            prompt_version_id=id_,
+            user_id=user_id,
+        )
+        await session.execute(
+            insert_on_conflict(
+                values,
+                dialect=dialect,
+                table=models.PromptVersionTag,
+                unique_by=("name", "prompt_id"),
+                on_conflict=OnConflict.DO_UPDATE,
+            )
+        )
+    return None
+
+
 class _PromptId(int): ...
 
 

phoenix/server/api/types/PromptVersionTag.py

@@ -1,19 +1,31 @@
 from typing import Optional
 
 import strawberry
+from strawberry import Info
 from strawberry.relay import GlobalID, Node, NodeID
 
 from phoenix.db import models
+from phoenix.server.api.context import Context
 from phoenix.server.api.types.Identifier import Identifier
+from phoenix.server.api.types.User import User, to_gql_user
 
 
 @strawberry.type
 class PromptVersionTag(Node):
     id_attr: NodeID[int]
+    user_id: strawberry.Private[Optional[int]]
     prompt_version_id: GlobalID
     name: Identifier
     description: Optional[str] = None
 
+    @strawberry.field
+    async def user(self, info: Info[Context, None]) -> Optional[User]:
+        if self.user_id is None:
+            return None
+        async with info.context.db() as session:
+            user = await session.get(models.User, self.user_id)
+        return to_gql_user(user) if user is not None else None
+
 
 def to_gql_prompt_version_tag(prompt_version_tag: models.PromptVersionTag) -> PromptVersionTag:
     from phoenix.server.api.types.PromptVersion import PromptVersion
@@ -24,4 +36,5 @@ def to_gql_prompt_version_tag(prompt_version_tag: models.PromptVersionTag) -> Pr
         prompt_version_id=version_gid,
         name=Identifier(prompt_version_tag.name.root),
         description=prompt_version_tag.description,
+        user_id=prompt_version_tag.user_id,
     )

phoenix/version.py

@@ -1 +1 @@
-__version__ = "8.21.0"
+__version__ = "8.22.0"