arize-phoenix 8.23.0__py3-none-any.whl → 8.24.0__py3-none-any.whl

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

@@ -1,7 +1,9 @@
 from typing import Optional
 
 from fastapi import APIRouter, HTTPException, Path, Query
+from pydantic import Field
 from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
 from starlette.requests import Request
 from starlette.status import (
     HTTP_204_NO_CONTENT,
@@ -14,6 +16,7 @@ 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 (
     PaginatedResponseBody,
@@ -27,7 +30,7 @@ router = APIRouter(tags=["projects"])
 
 
 class ProjectData(V1RoutesBaseModel):
-    name: str
+    name: str = Field(..., min_length=1)
     description: Optional[str] = None
 
 
@@ -43,8 +46,8 @@ class GetProjectResponseBody(ResponseBody[Project]):
     pass
 
 
-class CreateProjectRequestBody(V1RoutesBaseModel):
-    project: ProjectData
+class CreateProjectRequestBody(ProjectData):
+    pass
 
 
 class CreateProjectResponseBody(ResponseBody[Project]):
@@ -52,7 +55,7 @@ class CreateProjectResponseBody(ResponseBody[Project]):
 
 
 class UpdateProjectRequestBody(V1RoutesBaseModel):
-    project: ProjectData
+    description: Optional[str] = None
 
 
 class UpdateProjectResponseBody(ResponseBody[Project]):
@@ -75,19 +78,25 @@ async def get_projects(
     request: Request,
     cursor: Optional[str] = Query(
         default=None,
-        description="Cursor for pagination (base64-encoded project ID)",
+        description="Cursor for pagination (project ID)",
     ),
     limit: int = Query(
         default=100, description="The max number of projects to return at a time.", gt=0
     ),
+    include_experiment_projects: bool = Query(
+        default=False,
+        description="Include experiment projects in the response. Experiment projects are created from running experiments.",  # noqa: E501
+    ),
 ) -> GetProjectsResponseBody:
     """
     Retrieve a paginated list of all projects in the system.
 
     Args:
         request (Request): The FastAPI request object.
-        cursor (Optional[str]): Pagination cursor (base64-encoded project ID).
+        cursor (Optional[str]): Pagination cursor (project ID).
         limit (int): Maximum number of projects to return per request.
+        include_experiment_projects (bool): Flag to include experiment projects in the response.
+            Experiment projects are created from running experiments.
 
     Returns:
         GetProjectsResponseBody: Response containing a list of projects and pagination information.
@@ -95,9 +104,10 @@ async def get_projects(
     Raises:
         HTTPException: If the cursor format is invalid.
     """  # noqa: E501
+    stmt = select(models.Project).order_by(models.Project.id.desc())
+    if not include_experiment_projects:
+        stmt = exclude_experiment_projects(stmt)
     async with request.app.state.db() as session:
-        stmt = select(models.Project).order_by(models.Project.id.desc())
-
         if cursor:
             try:
                 cursor_id = GlobalID.from_id(cursor).node_id
@@ -109,27 +119,26 @@ async def get_projects(
                 )
 
         stmt = stmt.limit(limit + 1)
-        result = await session.execute(stmt)
-        orm_projects = result.scalars().all()
+        projects = (await session.scalars(stmt)).all()
 
-        if not orm_projects:
+        if not projects:
             return GetProjectsResponseBody(next_cursor=None, data=[])
 
         next_cursor = None
-        if len(orm_projects) == limit + 1:
-            last_project = orm_projects[-1]
+        if len(projects) == limit + 1:
+            last_project = projects[-1]
             next_cursor = str(GlobalID(ProjectNodeType.__name__, str(last_project.id)))
-            orm_projects = orm_projects[:-1]
+            projects = projects[:-1]
 
-        projects = [_project_from_orm_project(orm_project) for orm_project in orm_projects]
-    return GetProjectsResponseBody(next_cursor=next_cursor, data=projects)
+        project_responses = [_to_project_response(project) for project in projects]
+    return GetProjectsResponseBody(next_cursor=next_cursor, data=project_responses)
 
 
 @router.get(
-    "/projects/{project_id}",
+    "/projects/{project_identifier}",
     operation_id="getProject",
-    summary="Get project by ID",  # noqa: E501
-    description="Retrieve a specific project using its unique identifier.",  # noqa: E501
+    summary="Get project by ID or name",  # noqa: E501
+    description="Retrieve a specific project using its unique identifier: 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 requested project",  # noqa: E501
     responses=add_errors_to_responses(
         [
@@ -140,41 +149,27 @@ async def get_projects(
 )
 async def get_project(
     request: Request,
-    project_id: str = Path(description="The ID of the project."),
+    project_identifier: str = Path(
+        description="The project identifier: either project ID or project name. If using a project name, it cannot contain slash (/), question mark (?), or pound sign (#) characters.",  # noqa: E501
+    ),
 ) -> GetProjectResponseBody:
     """
-    Retrieve a specific project by its ID.
+    Retrieve a specific project by its ID or name.
 
     Args:
         request (Request): The FastAPI request object.
-        project_id (str): The ID of the project to retrieve.
+        project_identifier (str): The project identifier: either project ID or project name.
+            If using a project name, it cannot contain slash (/), question mark (?), or pound sign (#) characters.
 
     Returns:
         GetProjectResponseBody: Response containing the requested project.
 
     Raises:
-        HTTPException: If the project ID is invalid or the project is not found.
+        HTTPException: If the project identifier format is invalid or the project is not found.
     """  # noqa: E501
     async with request.app.state.db() as session:
-        try:
-            id_ = from_global_id_with_expected_type(
-                GlobalID.from_id(project_id),
-                ProjectNodeType.__name__,
-            )
-            project = await session.get(models.Project, id_)
-        except ValueError:
-            raise HTTPException(
-                status_code=HTTP_422_UNPROCESSABLE_ENTITY,
-                detail=f"Invalid project ID format: {project_id}",
-            )
-
-        if project is None:
-            raise HTTPException(
-                status_code=HTTP_404_NOT_FOUND,
-                detail=f"Project with ID {project_id} not found",
-            )
-
-    data = _project_from_orm_project(project)
+        project = await _get_project_by_identifier(session, project_identifier)
+    data = _to_project_response(project)
     return GetProjectResponseBody(data=data)
 
 
@@ -207,23 +202,22 @@ async def create_project(
     Raises:
         HTTPException: If any validation error occurs.
     """
-    project = request_body.project
     async with request.app.state.db() as session:
-        project_orm = models.Project(
-            name=project.name,
-            description=project.description,
+        project = models.Project(
+            name=request_body.name,
+            description=request_body.description,
         )
-        session.add(project_orm)
+        session.add(project)
         await session.flush()
-    data = _project_from_orm_project(project_orm)
+    data = _to_project_response(project)
     return CreateProjectResponseBody(data=data)
 
 
 @router.put(
-    "/projects/{project_id}",
+    "/projects/{project_identifier}",
     operation_id="updateProject",
-    summary="Update a project",  # noqa: E501
-    description="Update an existing project with new configuration. Project names cannot be changed.",  # noqa: E501
+    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(
         [
@@ -236,21 +230,24 @@ async def create_project(
 async def update_project(
     request: Request,
     request_body: UpdateProjectRequestBody,
-    project_id: str = Path(description="The ID of the project to update."),
+    project_identifier: str = Path(
+        description="The project identifier: either project ID or project name. If using a project name, it cannot contain slash (/), question mark (?), or pound sign (#) characters.",  # noqa: E501
+    ),
 ) -> UpdateProjectResponseBody:
     """
     Update an existing project.
 
     Args:
         request (Request): The FastAPI request object.
-        request_body (UpdateProjectRequestBody): The request body containing updated project data.
-        project_id (str): The ID of the project to update.
+        request_body (UpdateProjectRequestBody): The request body containing the new description.
+        project_identifier (str): The project identifier: either project ID or project name.
+            If using a project name, it cannot contain slash (/), question mark (?), or pound sign (#) characters.
 
     Returns:
         UpdateProjectResponseBody: Response containing the updated project.
 
     Raises:
-        HTTPException: If the project ID is invalid, the project is not found, or the name is changed.
+        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:
@@ -267,43 +264,21 @@ async def update_project(
                 detail="Only admins can update projects",
             )
     async with request.app.state.db() as session:
-        try:
-            id_ = from_global_id_with_expected_type(
-                GlobalID.from_id(project_id),
-                ProjectNodeType.__name__,
-            )
-            project_orm = await session.get(models.Project, id_)
-        except ValueError:
-            raise HTTPException(
-                status_code=HTTP_422_UNPROCESSABLE_ENTITY,
-                detail=f"Invalid project ID format: {project_id}",
-            )
-
-        if project_orm is None:
-            raise HTTPException(
-                status_code=HTTP_404_NOT_FOUND,
-                detail=f"Project with ID {project_id} not found",
-            )
-
-        # Prevent changing the project name
-        if project_orm.name != request_body.project.name:
-            raise HTTPException(
-                status_code=HTTP_422_UNPROCESSABLE_ENTITY,
-                detail="Project names cannot be changed",
-            )
+        project = await _get_project_by_identifier(session, project_identifier)
 
-        # Only update the description
-        project_orm.description = request_body.project.description
+        # Update the description if provided
+        if request_body.description is not None:
+            project.description = request_body.description
 
-    data = _project_from_orm_project(project_orm)
+    data = _to_project_response(project)
     return UpdateProjectResponseBody(data=data)
 
 
 @router.delete(
-    "/projects/{project_id}",
+    "/projects/{project_identifier}",
     operation_id="deleteProject",
-    summary="Delete a project",  # noqa: E501
-    description="Delete an existing project and all its associated data.",  # noqa: E501
+    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,
     responses=add_errors_to_responses(
@@ -316,20 +291,23 @@ async def update_project(
 )
 async def delete_project(
     request: Request,
-    project_id: str = Path(description="The ID of the project to delete."),
+    project_identifier: str = Path(
+        description="The project identifier: either project ID or project name. If using a project name, it cannot contain slash (/), question mark (?), or pound sign (#) characters.",  # noqa: E501
+    ),
 ) -> None:
     """
     Delete an existing project.
 
     Args:
         request (Request): The FastAPI request object.
-        project_id (str): The ID of the project to delete.
+        project_identifier (str): The project identifier: either project ID or project name.
+            If using a project name, it cannot contain slash (/), question mark (?), or pound sign (#) characters.
 
     Returns:
         None: Returns a 204 No Content response on success.
 
     Raises:
-        HTTPException: If the project ID is invalid, the project is not found, or it's the default project.
+        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:
@@ -346,23 +324,7 @@ async def delete_project(
                 detail="Only admins can delete projects",
             )
     async with request.app.state.db() as session:
-        try:
-            id_ = from_global_id_with_expected_type(
-                GlobalID.from_id(project_id),
-                ProjectNodeType.__name__,
-            )
-            project = await session.get(models.Project, id_)
-        except ValueError:
-            raise HTTPException(
-                status_code=HTTP_422_UNPROCESSABLE_ENTITY,
-                detail=f"Invalid project ID format: {project_id}",
-            )
-
-        if project is None:
-            raise HTTPException(
-                status_code=HTTP_404_NOT_FOUND,
-                detail=f"Project with ID {project_id} not found",
-            )
+        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:
@@ -375,9 +337,57 @@ async def delete_project(
     return None
 
 
-def _project_from_orm_project(orm_project: models.Project) -> Project:
+def _to_project_response(project: models.Project) -> Project:
     return Project(
-        id=str(GlobalID(ProjectNodeType.__name__, str(orm_project.id))),
-        name=orm_project.name,
-        description=orm_project.description,
+        id=str(GlobalID(ProjectNodeType.__name__, str(project.id))),
+        name=project.name,
+        description=project.description,
     )
+
+
+async def _get_project_by_identifier(
+    session: AsyncSession,
+    project_identifier: str,
+) -> models.Project:
+    """
+    Get a project by its ID or name.
+
+    Args:
+        session: The database session.
+        project_identifier: The project ID or name.
+
+    Returns:
+        The project object.
+
+    Raises:
+        HTTPException: If the identifier format is invalid or the project is not found.
+    """
+    # Try to parse as a GlobalID first
+    try:
+        id_ = from_global_id_with_expected_type(
+            GlobalID.from_id(project_identifier),
+            ProjectNodeType.__name__,
+        )
+    except Exception:
+        try:
+            name = project_identifier
+        except HTTPException:
+            raise HTTPException(
+                status_code=HTTP_422_UNPROCESSABLE_ENTITY,
+                detail=f"Invalid project identifier format: {project_identifier}",
+            )
+        stmt = select(models.Project).filter_by(name=name)
+        project = await session.scalar(stmt)
+        if project is None:
+            raise HTTPException(
+                status_code=HTTP_404_NOT_FOUND,
+                detail=f"Project with name {name} not found",
+            )
+    else:
+        project = await session.get(models.Project, id_)
+        if project is None:
+            raise HTTPException(
+                status_code=HTTP_404_NOT_FOUND,
+                detail=f"Project with ID {project_identifier} not found",
+            )
+    return project

phoenix/server/api/subscriptions.py

@@ -23,6 +23,7 @@ from strawberry.relay.types import GlobalID
 from strawberry.types import Info
 from typing_extensions import TypeAlias, assert_never
 
+from phoenix.config import PLAYGROUND_PROJECT_NAME
 from phoenix.datetime_utils import local_now, normalize_datetime
 from phoenix.db import models
 from phoenix.server.api.auth import IsLocked, IsNotReadOnly
@@ -84,7 +85,6 @@ ChatCompletionResult: TypeAlias = tuple[
     DatasetExampleID, Optional[models.Span], models.ExperimentRun
 ]
 ChatStream: TypeAlias = AsyncGenerator[ChatCompletionSubscriptionPayload, None]
-PLAYGROUND_PROJECT_NAME = "playground"
 
 
 @strawberry.type

phoenix/server/app.py

@@ -60,6 +60,7 @@ from phoenix.config import (
     get_env_host,
     get_env_port,
     server_instrumentation_is_enabled,
+    verify_server_environment_variables,
 )
 from phoenix.core.model_schema import Model
 from phoenix.db import models
@@ -551,6 +552,7 @@ def create_graphql_router(
     read_only: bool = False,
     secret: Optional[str] = None,
     token_store: Optional[TokenStore] = None,
+    email_sender: Optional[EmailSender] = None,
 ) -> GraphQLRouter[Context, None]:
     """Creates the GraphQL router.
 
@@ -566,6 +568,8 @@ def create_graphql_router(
         cache_for_dataloaders (Optional[CacheForDataLoaders], optional): GraphQL data loaders.
         read_only (bool, optional): Marks the app as read-only. Defaults to False.
         secret (Optional[str], optional): The application secret for auth. Defaults to None.
+        token_store (Optional[TokenStore], optional): The token store for auth. Defaults to None.
+        email_sender (Optional[EmailSender], optional): The email sender. Defaults to None.
 
     Returns:
         GraphQLRouter: The router mounted at /graphql
@@ -654,6 +658,7 @@ def create_graphql_router(
             auth_enabled=authentication_enabled,
             secret=secret,
             token_store=token_store,
+            email_sender=email_sender,
         )
 
     return GraphQLRouter(
@@ -768,6 +773,7 @@ def create_app(
     bulk_inserter_factory: Optional[Callable[..., BulkInserter]] = None,
     allowed_origins: Optional[list[str]] = None,
 ) -> FastAPI:
+    verify_server_environment_variables()
     if model.embedding_dimensions:
         try:
             import fast_hdbscan  # noqa: F401
@@ -870,6 +876,7 @@ def create_app(
         read_only=read_only,
         secret=secret,
         token_store=token_store,
+        email_sender=email_sender,
     )
     if enable_prometheus:
         from phoenix.server.prometheus import PrometheusMiddleware

phoenix/server/email/sender.py

@@ -1,14 +1,19 @@
-import asyncio
 import smtplib
 import ssl
 from email.message import EmailMessage
 from pathlib import Path
 from typing import Literal
 
+from anyio import to_thread
 from jinja2 import Environment, FileSystemLoader, select_autoescape
+from typing_extensions import TypeAlias
+
+from phoenix.config import get_env_root_url
 
 EMAIL_TEMPLATE_FOLDER = Path(__file__).parent / "templates"
 
+ConnectionMethod: TypeAlias = Literal["STARTTLS", "SSL", "PLAIN"]
+
 
 class SimpleEmailSender:
     def __init__(
@@ -18,7 +23,7 @@ class SimpleEmailSender:
         username: str,
         password: str,
         sender_email: str,
-        connection_method: Literal["STARTTLS", "SSL", "PLAIN"] = "STARTTLS",
+        connection_method: ConnectionMethod = "STARTTLS",
         validate_certs: bool = True,
     ) -> None:
         self.smtp_server = smtp_server
@@ -26,7 +31,7 @@ class SimpleEmailSender:
         self.username = username
         self.password = password
         self.sender_email = sender_email
-        self.connection_method = connection_method.upper()
+        self.connection_method: ConnectionMethod = connection_method
         self.validate_certs = validate_certs
 
         self.env = Environment(
@@ -34,6 +39,28 @@ class SimpleEmailSender:
             autoescape=select_autoescape(["html", "xml"]),
         )
 
+    async def send_welcome_email(
+        self,
+        email: str,
+        name: str,
+    ) -> None:
+        subject = "[Phoenix] Welcome to Arize Phoenix"
+        template_name = "welcome.html"
+
+        template = self.env.get_template(template_name)
+        html_content = template.render(
+            name=name,
+            welcome_url=str(get_env_root_url()),
+        )
+
+        msg = EmailMessage()
+        msg["Subject"] = subject
+        msg["From"] = self.sender_email
+        msg["To"] = email
+        msg.set_content(html_content, subtype="html")
+
+        await to_thread.run_sync(self._send_email, msg)
+
     async def send_password_reset_email(
         self,
         email: str,
@@ -51,47 +78,47 @@ class SimpleEmailSender:
         msg["To"] = email
         msg.set_content(html_content, subtype="html")
 
-        def send_email() -> None:
-            context: ssl.SSLContext
-            if self.validate_certs:
-                context = ssl.create_default_context()
-            else:
-                context = ssl._create_unverified_context()
-
-            methods_to_try = [self.connection_method]
-            # add secure method fallbacks
-            if self.connection_method != "PLAIN":
-                if self.connection_method != "STARTTLS":
-                    methods_to_try.append("STARTTLS")
-                elif self.connection_method != "SSL":
-                    methods_to_try.append("SSL")
-
-            for method in methods_to_try:
-                try:
-                    if method == "STARTTLS":
-                        server = smtplib.SMTP(self.smtp_server, self.smtp_port)
-                        server.ehlo()
-                        server.starttls(context=context)
-                        server.ehlo()
-                    elif method == "SSL":
-                        server = smtplib.SMTP_SSL(self.smtp_server, self.smtp_port, context=context)
-                        server.ehlo()
-                    elif method == "PLAIN":
-                        server = smtplib.SMTP(self.smtp_server, self.smtp_port)
-                        server.ehlo()
-                    else:
-                        continue  # Unsupported method
-
-                    if self.username and self.password:
-                        server.login(self.username, self.password)
-
-                    server.send_message(msg)
-                    server.quit()
-                    break  # Success
-                except Exception as e:
-                    print(f"Failed to send email using {method}: {e}")
-                    continue
-            else:
-                raise Exception("All connection methods failed")
-
-        await asyncio.to_thread(send_email)
+        await to_thread.run_sync(self._send_email, msg)
+
+    def _send_email(self, msg: EmailMessage) -> None:
+        context: ssl.SSLContext
+        if self.validate_certs:
+            context = ssl.create_default_context()
+        else:
+            context = ssl._create_unverified_context()
+
+        methods_to_try: list[ConnectionMethod] = [self.connection_method]
+        # add secure method fallbacks
+        if self.connection_method != "PLAIN":
+            if self.connection_method != "STARTTLS":
+                methods_to_try.append("STARTTLS")
+            if self.connection_method != "SSL":
+                methods_to_try.append("SSL")
+
+        for method in methods_to_try:
+            try:
+                if method == "STARTTLS":
+                    server = smtplib.SMTP(self.smtp_server, self.smtp_port)
+                    server.ehlo()
+                    server.starttls(context=context)
+                    server.ehlo()
+                elif method == "SSL":
+                    server = smtplib.SMTP_SSL(self.smtp_server, self.smtp_port, context=context)
+                    server.ehlo()
+                elif method == "PLAIN":
+                    server = smtplib.SMTP(self.smtp_server, self.smtp_port)
+                    server.ehlo()
+                else:
+                    continue  # Unsupported method
+
+                if self.username and self.password:
+                    server.login(self.username, self.password)
+
+                server.send_message(msg)
+                server.quit()
+                break  # Success
+            except Exception as e:
+                print(f"Failed to send email using {method}: {e}")
+                continue
+        else:
+            raise Exception("All connection methods failed")

phoenix/server/email/templates/welcome.html

@@ -0,0 +1,12 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <meta charset="UTF-8" />
+    <title>Welcome to Arize Phoenix</title>
+  </head>
+  <body>
+    <h1>Welcome to Arize Phoenix!</h1>
+    <p>Hi {{ name }}, please click the link below to get started:</p>
+    <a href="{{ welcome_url }}">Get Started</a>
+  </body>
+</html>

phoenix/server/email/types.py

@@ -3,9 +3,24 @@ from __future__ import annotations
 from typing import Protocol
 
 
-class EmailSender(Protocol):
+class WelcomeEmailSender(Protocol):
+    async def send_welcome_email(
+        self,
+        email: str,
+        name: str,
+    ) -> None: ...
+
+
+class PasswordResetEmailSender(Protocol):
     async def send_password_reset_email(
         self,
         email: str,
         reset_url: str,
     ) -> None: ...
+
+
+class EmailSender(
+    WelcomeEmailSender,
+    PasswordResetEmailSender,
+    Protocol,
+): ...