arize-phoenix 10.0.4__py3-none-any.whl → 12.28.1__py3-none-any.whl

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

@@ -1,7 +1,10 @@
 from datetime import datetime
+from typing import Any
 
 from pydantic import BaseModel, ConfigDict
 
+from phoenix.db.types.db_models import UNDEFINED
+
 
 def datetime_encoder(dt: datetime) -> str:
     """
@@ -43,3 +46,7 @@ class V1RoutesBaseModel(BaseModel):
             []
         ),  # suppress warnings about protected namespaces starting with `model_` on pydantic 2.9
     )
+
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        kwargs = {k: v for k, v in kwargs.items() if v is not UNDEFINED}
+        super().__init__(*args, **kwargs)

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

@@ -1,20 +1,13 @@
 from typing import Optional
 
-from fastapi import APIRouter, HTTPException, Path, Query
+from fastapi import APIRouter, Depends, HTTPException, Path, Query
 from pydantic import Field
 from sqlalchemy import select
 from starlette.requests import Request
-from starlette.status import (
-    HTTP_204_NO_CONTENT,
-    HTTP_403_FORBIDDEN,
-    HTTP_404_NOT_FOUND,
-    HTTP_422_UNPROCESSABLE_ENTITY,
-)
 from strawberry.relay import GlobalID
 
 from phoenix.config import DEFAULT_PROJECT_NAME
 from phoenix.db import models
-from phoenix.db.enums import UserRole
 from phoenix.db.helpers import exclude_experiment_projects
 from phoenix.server.api.routers.v1.models import V1RoutesBaseModel
 from phoenix.server.api.routers.v1.utils import (
@@ -24,6 +17,7 @@ from phoenix.server.api.routers.v1.utils import (
     add_errors_to_responses,
 )
 from phoenix.server.api.types.Project import Project as ProjectNodeType
+from phoenix.server.authorization import is_not_locked, require_admin
 
 router = APIRouter(tags=["projects"])
 
@@ -69,7 +63,7 @@ class UpdateProjectResponseBody(ResponseBody[Project]):
     response_description="A list of projects with pagination information",  # noqa: E501
     responses=add_errors_to_responses(
         [
-            HTTP_422_UNPROCESSABLE_ENTITY,
+            422,
         ]
     ),
 )
@@ -114,7 +108,7 @@ async def get_projects(
             except ValueError:
                 raise HTTPException(
                     detail=f"Invalid cursor format: {cursor}",
-                    status_code=HTTP_422_UNPROCESSABLE_ENTITY,
+                    status_code=422,
                 )
 
         stmt = stmt.limit(limit + 1)
@@ -141,8 +135,8 @@ async def get_projects(
     response_description="The requested project",  # noqa: E501
     responses=add_errors_to_responses(
         [
-            HTTP_404_NOT_FOUND,
-            HTTP_422_UNPROCESSABLE_ENTITY,
+            404,
+            422,
         ]
     ),
 )
@@ -174,13 +168,14 @@ async def get_project(
 
 @router.post(
     "/projects",
+    dependencies=[Depends(is_not_locked)],
     operation_id="createProject",
     summary="Create a new project",  # noqa: E501
     description="Create a new project with the specified configuration.",  # noqa: E501
     response_description="The newly created project",  # noqa: E501
     responses=add_errors_to_responses(
         [
-            HTTP_422_UNPROCESSABLE_ENTITY,
+            422,
         ]
     ),
 )
@@ -214,15 +209,16 @@ async def create_project(
 
 @router.put(
     "/projects/{project_identifier}",
+    dependencies=[Depends(require_admin), Depends(is_not_locked)],
     operation_id="updateProject",
     summary="Update a project by ID or name",  # noqa: E501
     description="Update an existing project with new configuration. Project names cannot be changed. The project identifier is either project ID or project name. Note: When using a project name as the identifier, it cannot contain slash (/), question mark (?), or pound sign (#) characters.",  # noqa: E501
     response_description="The updated project",  # noqa: E501
     responses=add_errors_to_responses(
         [
-            HTTP_403_FORBIDDEN,
-            HTTP_404_NOT_FOUND,
-            HTTP_422_UNPROCESSABLE_ENTITY,
+            403,
+            404,
+            422,
         ]
     ),
 )
@@ -248,20 +244,6 @@ async def update_project(
     Raises:
         HTTPException: If the project identifier format is invalid or the project is not found.
     """  # noqa: E501
-    if request.app.state.authentication_enabled:
-        async with request.app.state.db() as session:
-            # Check if the user is an admin
-            stmt = (
-                select(models.UserRole.name)
-                .join(models.User)
-                .where(models.User.id == int(request.user.identity))
-            )
-            role_name = await session.scalar(stmt)
-        if role_name != UserRole.ADMIN.value:
-            raise HTTPException(
-                status_code=HTTP_403_FORBIDDEN,
-                detail="Only admins can update projects",
-            )
     async with request.app.state.db() as session:
         project = await _get_project_by_identifier(session, project_identifier)
 
@@ -275,16 +257,17 @@ async def update_project(
 
 @router.delete(
     "/projects/{project_identifier}",
+    dependencies=[Depends(require_admin)],
     operation_id="deleteProject",
     summary="Delete a project by ID or name",  # noqa: E501
     description="Delete an existing project and all its associated data. The project identifier is either project ID or project name. The default project cannot be deleted. Note: When using a project name as the identifier, it cannot contain slash (/), question mark (?), or pound sign (#) characters.",  # noqa: E501
     response_description="No content returned on successful deletion",  # noqa: E501
-    status_code=HTTP_204_NO_CONTENT,
+    status_code=204,
     responses=add_errors_to_responses(
         [
-            HTTP_403_FORBIDDEN,
-            HTTP_404_NOT_FOUND,
-            HTTP_422_UNPROCESSABLE_ENTITY,
+            403,
+            404,
+            422,
         ]
     ),
 )
@@ -308,27 +291,13 @@ async def delete_project(
     Raises:
         HTTPException: If the project identifier format is invalid, the project is not found, or it's the default project.
     """  # noqa: E501
-    if request.app.state.authentication_enabled:
-        async with request.app.state.db() as session:
-            # Check if the user is an admin
-            stmt = (
-                select(models.UserRole.name)
-                .join(models.User)
-                .where(models.User.id == int(request.user.identity))
-            )
-            role_name = await session.scalar(stmt)
-        if role_name != UserRole.ADMIN.value:
-            raise HTTPException(
-                status_code=HTTP_403_FORBIDDEN,
-                detail="Only admins can delete projects",
-            )
     async with request.app.state.db() as session:
         project = await _get_project_by_identifier(session, project_identifier)
 
         # The default project must not be deleted - it's forbidden
         if project.name == DEFAULT_PROJECT_NAME:
             raise HTTPException(
-                status_code=HTTP_403_FORBIDDEN,
+                status_code=403,
                 detail="The default project cannot be deleted",
             )
 

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

@@ -1,12 +1,12 @@
 import logging
 from typing import Any, Optional, Union
 
-from fastapi import APIRouter, HTTPException, Path, Query
+from fastapi import APIRouter, Depends, HTTPException, Path, Query
 from pydantic import ValidationError, model_validator
 from sqlalchemy import select
+from sqlalchemy.orm import joinedload
 from sqlalchemy.sql import Select
 from starlette.requests import Request
-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
 
@@ -33,6 +33,7 @@ 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.authorization import is_not_locked
 from phoenix.server.bearer_auth import PhoenixUser
 
 logger = logging.getLogger(__name__)
@@ -42,6 +43,7 @@ class PromptData(V1RoutesBaseModel):
     name: Identifier
     description: Optional[str] = None
     source_prompt_id: Optional[str] = None
+    metadata: Optional[dict[str, Any]] = None
 
 
 class Prompt(PromptData):
@@ -109,7 +111,7 @@ router = APIRouter(tags=["prompts"])
     response_description="A list of prompts with pagination information",
     responses=add_errors_to_responses(
         [
-            HTTP_422_UNPROCESSABLE_ENTITY,
+            422,
         ]
     ),
 )
@@ -153,7 +155,7 @@ async def get_prompts(
             except ValueError:
                 raise HTTPException(
                     detail=f"Invalid cursor format: {cursor}",
-                    status_code=HTTP_422_UNPROCESSABLE_ENTITY,
+                    status_code=422,
                 )
 
         query = query.limit(limit + 1)
@@ -180,7 +182,7 @@ async def get_prompts(
     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]),
+    responses=add_errors_to_responses([422, 404]),
     response_model_by_alias=True,
     response_model_exclude_defaults=True,
     response_model_exclude_unset=True,
@@ -213,7 +215,7 @@ async def list_prompt_versions(
         HTTPException: If the cursor format is invalid, the prompt identifier is invalid,
             or the prompt is not found.
     """
-    query = select(models.PromptVersion)
+    query = select(models.PromptVersion).options(joinedload(models.PromptVersion.prompt))
     query = _filter_by_prompt_identifier(query.join(models.Prompt), prompt_identifier)
     query = query.order_by(models.PromptVersion.id.desc())
 
@@ -225,7 +227,7 @@ async def list_prompt_versions(
             except ValueError:
                 raise HTTPException(
                     detail=f"Invalid cursor format: {cursor}",
-                    status_code=HTTP_422_UNPROCESSABLE_ENTITY,
+                    status_code=422,
                 )
 
         query = query.limit(limit + 1)
@@ -254,8 +256,8 @@ async def list_prompt_versions(
     response_description="The requested prompt version",
     responses=add_errors_to_responses(
         [
-            HTTP_404_NOT_FOUND,
-            HTTP_422_UNPROCESSABLE_ENTITY,
+            404,
+            422,
         ]
     ),
     response_model_by_alias=True,
@@ -285,11 +287,16 @@ async def get_prompt_version_by_prompt_version_id(
             PromptVersionNodeType.__name__,
         )
     except ValueError:
-        raise HTTPException(HTTP_422_UNPROCESSABLE_ENTITY, "Invalid prompt version ID")
+        raise HTTPException(422, "Invalid prompt version ID")
     async with request.app.state.db() as session:
-        prompt_version = await session.get(models.PromptVersion, id_)
+        stmt = (
+            select(models.PromptVersion)
+            .options(joinedload(models.PromptVersion.prompt))
+            .where(models.PromptVersion.id == id_)
+        )
+        prompt_version = await session.scalar(stmt)
         if prompt_version is None:
-            raise HTTPException(HTTP_404_NOT_FOUND)
+            raise HTTPException(404)
     data = _prompt_version_from_orm_version(prompt_version)
     return GetPromptResponseBody(data=data)
 
@@ -303,8 +310,8 @@ async def get_prompt_version_by_prompt_version_id(
     response_description="The prompt version with the specified tag",
     responses=add_errors_to_responses(
         [
-            HTTP_404_NOT_FOUND,
-            HTTP_422_UNPROCESSABLE_ENTITY,
+            404,
+            422,
         ]
     ),
     response_model_by_alias=True,
@@ -333,9 +340,10 @@ async def get_prompt_version_by_tag_name(
     try:
         name = Identifier.model_validate(tag_name)
     except ValidationError:
-        raise HTTPException(HTTP_422_UNPROCESSABLE_ENTITY, "Invalid tag name")
+        raise HTTPException(422, "Invalid tag name")
     stmt = (
         select(models.PromptVersion)
+        .options(joinedload(models.PromptVersion.prompt))
         .join_from(models.PromptVersion, models.PromptVersionTag)
         .where(models.PromptVersionTag.name == name)
     )
@@ -343,7 +351,7 @@ async def get_prompt_version_by_tag_name(
     async with request.app.state.db() as session:
         prompt_version: models.PromptVersion = await session.scalar(stmt)
         if prompt_version is None:
-            raise HTTPException(HTTP_404_NOT_FOUND)
+            raise HTTPException(404)
     data = _prompt_version_from_orm_version(prompt_version)
     return GetPromptResponseBody(data=data)
 
@@ -356,8 +364,8 @@ async def get_prompt_version_by_tag_name(
     response_description="The latest version of the specified prompt",
     responses=add_errors_to_responses(
         [
-            HTTP_404_NOT_FOUND,
-            HTTP_422_UNPROCESSABLE_ENTITY,
+            404,
+            422,
         ]
     ),
     response_model_by_alias=True,
@@ -381,25 +389,31 @@ async def get_prompt_version_by_latest(
     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 = (
+        select(models.PromptVersion)
+        .options(joinedload(models.PromptVersion.prompt))
+        .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:
         prompt_version: models.PromptVersion = await session.scalar(stmt)
         if prompt_version is None:
-            raise HTTPException(HTTP_404_NOT_FOUND)
+            raise HTTPException(404)
     data = _prompt_version_from_orm_version(prompt_version)
     return GetPromptResponseBody(data=data)
 
 
 @router.post(
     "/prompts",
+    dependencies=[Depends(is_not_locked)],
     operation_id="postPromptVersion",
     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,
+            422,
         ]
     ),
     response_model_by_alias=True,
@@ -429,7 +443,7 @@ async def create_prompt(
         or request_body.version.template_type != PromptTemplateType.CHAT
     ):
         raise HTTPException(
-            HTTP_422_UNPROCESSABLE_ENTITY,
+            422,
             "Only CHAT template type is supported for prompts",
         )
     prompt = request_body.prompt
@@ -437,7 +451,7 @@ async def create_prompt(
         name = Identifier.model_validate(prompt.name)
     except ValidationError as e:
         raise HTTPException(
-            HTTP_422_UNPROCESSABLE_ENTITY,
+            422,
             "Invalid name identifier for prompt: " + e.errors()[0]["msg"],
         )
     version = request_body.version
@@ -446,17 +460,15 @@ async def create_prompt(
         assert isinstance(user := request.user, PhoenixUser)
         user_id = int(user.identity)
     async with request.app.state.db() as session:
-        if not (prompt_id := await session.scalar(select(models.Prompt.id).filter_by(name=name))):
+        if not (prompt_orm := await session.scalar(select(models.Prompt).filter_by(name=name))):
             prompt_orm = models.Prompt(
                 name=name,
                 description=prompt.description,
+                metadata_=prompt.metadata or {},
             )
-            session.add(prompt_orm)
-            await session.flush()
-            prompt_id = prompt_orm.id
         version_orm = models.PromptVersion(
             user_id=user_id,
-            prompt_id=prompt_id,
+            prompt=prompt_orm,
             description=version.description,
             model_provider=version.model_provider,
             model_name=version.model_name,
@@ -494,8 +506,8 @@ class GetPromptVersionTagsResponseBody(PaginatedResponseBody[PromptVersionTag]):
     response_description="A list of tags associated with the prompt version",
     responses=add_errors_to_responses(
         [
-            HTTP_404_NOT_FOUND,
-            HTTP_422_UNPROCESSABLE_ENTITY,
+            404,
+            422,
         ]
     ),
     response_model_by_alias=True,
@@ -535,7 +547,7 @@ async def list_prompt_version_tags(
             PromptVersionNodeType.__name__,
         )
     except ValueError:
-        raise HTTPException(HTTP_422_UNPROCESSABLE_ENTITY, "Invalid prompt version ID")
+        raise HTTPException(422, "Invalid prompt version ID")
 
     # Build the query for tags
     stmt = (
@@ -558,7 +570,7 @@ async def list_prompt_version_tags(
         except ValueError:
             raise HTTPException(
                 detail=f"Invalid cursor format: {cursor}",
-                status_code=HTTP_422_UNPROCESSABLE_ENTITY,
+                status_code=422,
             )
 
     # Apply limit
@@ -569,7 +581,7 @@ async def list_prompt_version_tags(
 
     # Check if prompt version exists
     if not result:
-        raise HTTPException(HTTP_404_NOT_FOUND, "Prompt version not found")
+        raise HTTPException(404, "Prompt version not found")
 
     # Check if there are any tags
     has_tags = any(id_ is not None for _, id_, _, _ in result)
@@ -602,16 +614,17 @@ async def list_prompt_version_tags(
 
 @router.post(
     "/prompt_versions/{prompt_version_id}/tags",
+    dependencies=[Depends(is_not_locked)],
     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,
+    status_code=204,
     responses=add_errors_to_responses(
         [
-            HTTP_404_NOT_FOUND,
-            HTTP_422_UNPROCESSABLE_ENTITY,
+            404,
+            422,
         ]
     ),
     response_model_by_alias=True,
@@ -644,7 +657,7 @@ async def create_prompt_version_tag(
             PromptVersionNodeType.__name__,
         )
     except ValueError:
-        raise HTTPException(HTTP_422_UNPROCESSABLE_ENTITY, "Invalid prompt version ID")
+        raise HTTPException(422, "Invalid prompt version ID")
     user_id: Optional[int] = None
     if request.app.state.authentication_enabled:
         assert isinstance(user := request.user, PhoenixUser)
@@ -652,7 +665,7 @@ async def create_prompt_version_tag(
     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)
+            raise HTTPException(404)
         dialect = SupportedSQLDialect(session.bind.dialect.name)
         values = dict(
             name=request_body.name,
@@ -683,7 +696,7 @@ def _parse_prompt_identifier(
     prompt_identifier: str,
 ) -> _PromptIdentifier:
     if not prompt_identifier:
-        raise HTTPException(HTTP_422_UNPROCESSABLE_ENTITY, "Invalid prompt identifier")
+        raise HTTPException(422, "Invalid prompt identifier")
     try:
         prompt_id = from_global_id_with_expected_type(
             GlobalID.from_id(prompt_identifier),
@@ -693,7 +706,7 @@ def _parse_prompt_identifier(
         try:
             return Identifier.model_validate(prompt_identifier)
         except ValidationError:
-            raise HTTPException(HTTP_422_UNPROCESSABLE_ENTITY, "Invalid prompt name")
+            raise HTTPException(422, "Invalid prompt name")
     return _PromptId(prompt_id)
 
 
@@ -739,4 +752,5 @@ def _prompt_from_orm_prompt(orm_prompt: models.Prompt) -> Prompt:
         source_prompt_id=source_prompt_id,
         name=orm_prompt.name,
         description=orm_prompt.description,
+        metadata=orm_prompt.metadata_,
     )

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

@@ -0,0 +1,108 @@
+from __future__ import annotations
+
+import warnings
+from typing import Optional
+
+from fastapi import APIRouter, Depends, HTTPException, Query
+from pydantic import Field
+from sqlalchemy import select
+from starlette.requests import Request
+
+from phoenix.db import models
+from phoenix.db.helpers import SupportedSQLDialect
+from phoenix.db.insertion.helpers import as_kv, insert_on_conflict
+from phoenix.server.api.routers.v1.models import V1RoutesBaseModel
+from phoenix.server.authorization import is_not_locked
+from phoenix.server.bearer_auth import PhoenixUser
+
+from .annotations import SessionAnnotationData
+from .utils import RequestBody, ResponseBody, add_errors_to_responses
+
+router = APIRouter(tags=["sessions"])
+
+
+class InsertedSessionAnnotation(V1RoutesBaseModel):
+    id: str = Field(description="The ID of the inserted session annotation")
+
+
+class AnnotateSessionsRequestBody(RequestBody[list[SessionAnnotationData]]):
+    pass
+
+
+class AnnotateSessionsResponseBody(ResponseBody[list[InsertedSessionAnnotation]]):
+    pass
+
+
+@router.post(
+    "/session_annotations",
+    dependencies=[Depends(is_not_locked)],
+    operation_id="annotateSessions",
+    summary="Create session annotations",
+    responses=add_errors_to_responses([{"status_code": 404, "description": "Session not found"}]),
+    response_description="Session annotations inserted successfully",
+    include_in_schema=True,
+)
+async def annotate_sessions(
+    request: Request,
+    request_body: AnnotateSessionsRequestBody,
+    sync: bool = Query(default=False, description="If true, fulfill request synchronously."),
+) -> AnnotateSessionsResponseBody:
+    if not request_body.data:
+        return AnnotateSessionsResponseBody(data=[])
+
+    user_id: Optional[int] = None
+    if request.app.state.authentication_enabled and isinstance(request.user, PhoenixUser):
+        user_id = int(request.user.identity)
+
+    session_annotations = request_body.data
+    filtered_session_annotations = list(filter(lambda d: d.name != "note", session_annotations))
+    if len(filtered_session_annotations) != len(session_annotations):
+        warnings.warn(
+            (
+                "Session annotations with the name 'note' are not supported in this endpoint. "
+                "They will be ignored."
+            ),
+            UserWarning,
+        )
+    precursors = [d.as_precursor(user_id=user_id) for d in filtered_session_annotations]
+    if not sync:
+        await request.state.enqueue_annotations(*precursors)
+        return AnnotateSessionsResponseBody(data=[])
+
+    session_ids = {p.session_id for p in precursors}
+    async with request.app.state.db() as session:
+        existing_sessions = {
+            session_id: rowid
+            async for session_id, rowid in await session.stream(
+                select(models.ProjectSession.session_id, models.ProjectSession.id).filter(
+                    models.ProjectSession.session_id.in_(session_ids)
+                )
+            )
+        }
+
+    missing_session_ids = session_ids - set(existing_sessions.keys())
+    # We prefer to fail the entire operation if there are missing sessions in sync mode
+    if missing_session_ids:
+        raise HTTPException(
+            detail=f"Sessions with IDs {', '.join(missing_session_ids)} do not exist.",
+            status_code=404,
+        )
+
+    async with request.app.state.db() as session:
+        inserted_ids = []
+        dialect = SupportedSQLDialect(session.bind.dialect.name)
+        for p in precursors:
+            values = dict(as_kv(p.as_insertable(existing_sessions[p.session_id]).row))
+            session_annotation_id = await session.scalar(
+                insert_on_conflict(
+                    values,
+                    dialect=dialect,
+                    table=models.ProjectSessionAnnotation,
+                    unique_by=("name", "project_session_id", "identifier"),
+                ).returning(models.ProjectSessionAnnotation.id)
+            )
+            inserted_ids.append(session_annotation_id)
+
+    return AnnotateSessionsResponseBody(
+        data=[InsertedSessionAnnotation(id=str(inserted_id)) for inserted_id in inserted_ids]
+    )