arize-phoenix 8.28.0__tar.gz → 8.29.0__tar.gz

{arize_phoenix-8.28.0 → arize_phoenix-8.29.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: arize-phoenix
-Version: 8.28.0
+Version: 8.29.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.28.0 → arize_phoenix-8.29.0}/src/phoenix/config.py

@@ -2,7 +2,7 @@ import logging
 import os
 import re
 import tempfile
-from dataclasses import dataclass
+from dataclasses import dataclass, field
 from datetime import timedelta
 from enum import Enum
 from importlib.metadata import version
@@ -240,6 +240,243 @@ ENV_PHOENIX_FASTAPI_MIDDLEWARE_PATHS = "PHOENIX_FASTAPI_MIDDLEWARE_PATHS"
 ENV_PHOENIX_GQL_EXTENSION_PATHS = "PHOENIX_GQL_EXTENSION_PATHS"
 ENV_PHOENIX_GRPC_INTERCEPTOR_PATHS = "PHOENIX_GRPC_INTERCEPTOR_PATHS"
 
+ENV_PHOENIX_TLS_ENABLED = "PHOENIX_TLS_ENABLED"
+"""
+Whether to enable TLS for Phoenix HTTP and gRPC servers.
+"""
+ENV_PHOENIX_TLS_CERT_FILE = "PHOENIX_TLS_CERT_FILE"
+"""
+Path to the TLS certificate file for HTTPS connections.
+When set, Phoenix will use HTTPS instead of HTTP for all connections.
+"""
+ENV_PHOENIX_TLS_KEY_FILE = "PHOENIX_TLS_KEY_FILE"
+"""
+Path to the TLS private key file for HTTPS connections.
+Required when PHOENIX_TLS_CERT_FILE is set.
+"""
+ENV_PHOENIX_TLS_KEY_FILE_PASSWORD = "PHOENIX_TLS_KEY_FILE_PASSWORD"
+"""
+Password for the TLS private key file if it's encrypted.
+Only needed if the private key file requires a password.
+"""
+ENV_PHOENIX_TLS_CA_FILE = "PHOENIX_TLS_CA_FILE"
+"""
+Path to the Certificate Authority (CA) file for client certificate verification.
+Used when PHOENIX_TLS_VERIFY_CLIENT is set to true.
+"""
+ENV_PHOENIX_TLS_VERIFY_CLIENT = "PHOENIX_TLS_VERIFY_CLIENT"
+"""
+Whether to verify client certificates for mutual TLS (mTLS) authentication.
+When set to true, clients must provide valid certificates signed by the CA specified in
+PHOENIX_TLS_CA_FILE.
+"""
+
+
+@dataclass(frozen=True)
+class TLSConfig:
+    """Configuration for TLS (Transport Layer Security) connections.
+
+    This class manages TLS certificates and private keys for secure connections.
+    It handles reading certificate and key files, and decrypting private keys
+    if they are password-protected.
+
+    Attributes:
+        cert_file: Path to the TLS certificate file
+        key_file: Path to the TLS private key file
+        key_file_password: Optional password for decrypting the private key
+        _cert_data: Cached certificate data (internal use)
+        _key_data: Cached decrypted key data (internal use)
+        _decrypted_key_data: Cached decrypted key data (internal use)
+    """
+
+    cert_file: Path
+    key_file: Path
+    key_file_password: Optional[str]
+    _cert_data: bytes = field(default=b"", init=False, repr=False)
+    _key_data: bytes = field(default=b"", init=False, repr=False)
+    _decrypted_key_data: Optional[bytes] = field(default=None, init=False, repr=False)
+
+    @property
+    def cert_data(self) -> bytes:
+        """Get the certificate data, reading from file if not cached.
+
+        Returns:
+            bytes: The certificate data in PEM format
+        """
+        if not self._cert_data:
+            with open(self.cert_file, "rb") as f:
+                object.__setattr__(self, "_cert_data", f.read())
+        return self._cert_data
+
+    @property
+    def key_data(self) -> bytes:
+        """Get the decrypted key data, reading from file if not cached.
+
+        This property reads the private key file and decrypts it if a password
+        is provided. The decrypted key is cached for subsequent accesses.
+
+        Returns:
+            bytes: The decrypted private key data in PEM format
+
+        Raises:
+            ValueError: If the cryptography library is not installed or if
+                decryption fails
+        """
+        if not self._key_data:
+            self._read_and_cache_key_data()
+        return self._key_data
+
+    def _read_and_cache_key_data(self) -> None:
+        """Read and decrypt the private key file, then cache the result.
+
+        This method reads the private key file, decrypts it if a password
+        is provided, and stores the decrypted key in the _key_data attribute.
+
+        Raises:
+            ValueError: If the cryptography library is not installed or if
+                decryption fails
+        """
+        try:
+            from cryptography.hazmat.backends import default_backend
+            from cryptography.hazmat.primitives.serialization import (
+                Encoding,
+                NoEncryption,
+                PrivateFormat,
+                load_pem_private_key,
+            )
+        except ImportError:
+            raise ValueError(
+                "The cryptography library is needed to read private keys for "
+                "TLS configuration. Please install it with: pip install cryptography"
+            )
+
+        # First read the key file
+        with open(self.key_file, "rb") as f:
+            key_data = f.read()
+
+        try:
+            # Convert password to bytes if it exists
+            password_bytes = self.key_file_password.encode() if self.key_file_password else None
+
+            # Load the key (decrypting if password is provided)
+            private_key = load_pem_private_key(
+                key_data,
+                password=password_bytes,
+                backend=default_backend(),
+            )
+
+            # Convert to PEM format without encryption
+            decrypted_pem = private_key.private_bytes(
+                encoding=Encoding.PEM,
+                format=PrivateFormat.PKCS8,
+                encryption_algorithm=NoEncryption(),
+            )
+        except Exception as e:
+            raise ValueError(f"Failed to decrypt private key: {e}")
+        object.__setattr__(self, "_key_data", decrypted_pem)
+
+
+@dataclass(frozen=True)
+class TLSConfigVerifyClient(TLSConfig):
+    """TLS configuration with client verification enabled."""
+
+    ca_file: Path
+    _ca_data: bytes = field(default=b"", init=False, repr=False)
+
+    @property
+    def ca_data(self) -> bytes:
+        """Get the CA certificate data, reading from file if not cached."""
+        if not self._ca_data:
+            with open(self.ca_file, "rb") as f:
+                object.__setattr__(self, "_ca_data", f.read())
+        return self._ca_data
+
+
+def get_env_tls_enabled() -> bool:
+    """
+    Gets the value of the PHOENIX_TLS_ENABLED environment variable.
+
+    Returns:
+        bool: True if TLS is enabled, False otherwise. Defaults to False if the environment
+        variable is not set.
+    """  # noqa: E501
+    return _bool_val(ENV_PHOENIX_TLS_ENABLED, False)
+
+
+def get_env_tls_verify_client() -> bool:
+    """
+    Gets the value of the PHOENIX_TLS_VERIFY_CLIENT environment variable.
+
+    Returns:
+        bool: True if client certificate verification is enabled, False otherwise. Defaults to False
+        if the environment variable is not set.
+    """  # noqa: E501
+    return _bool_val(ENV_PHOENIX_TLS_VERIFY_CLIENT, False)
+
+
+def get_env_tls_config() -> Optional[TLSConfig]:
+    """
+    Retrieves and validates TLS configuration from environment variables.
+
+    Returns:
+        Optional[TLSConfig]: A configuration object containing TLS settings, or None if TLS is disabled.
+        If client verification is enabled, returns TLSConfigVerifyClient instead.
+
+    The function reads the following environment variables:
+    - PHOENIX_TLS_ENABLED: Whether TLS is enabled (defaults to False)
+    - PHOENIX_TLS_CERT_FILE: Path to the TLS certificate file
+    - PHOENIX_TLS_KEY_FILE: Path to the TLS private key file
+    - PHOENIX_TLS_KEY_FILE_PASSWORD: Password for the TLS private key file
+    - PHOENIX_TLS_CA_FILE: Path to the Certificate Authority file (required for client verification)
+    - PHOENIX_TLS_VERIFY_CLIENT: Whether to verify client certificates
+
+    Raises:
+        ValueError: If required files are missing or don't exist when TLS is enabled
+    """  # noqa: E501
+    # Check if TLS is enabled
+    if not get_env_tls_enabled():
+        return None
+
+    # Get certificate file path if specified
+    if not (cert_file_str := getenv(ENV_PHOENIX_TLS_CERT_FILE)):
+        raise ValueError("PHOENIX_TLS_CERT_FILE must be set when PHOENIX_TLS_ENABLED is true")
+    cert_file = Path(cert_file_str)
+
+    # Get private key file path if specified
+    if not (key_file_str := getenv(ENV_PHOENIX_TLS_KEY_FILE)):
+        raise ValueError("PHOENIX_TLS_KEY_FILE must be set when PHOENIX_TLS_ENABLED is true")
+    key_file = Path(key_file_str)
+
+    # Get private key password if specified
+    key_file_password = getenv(ENV_PHOENIX_TLS_KEY_FILE_PASSWORD)
+
+    # Validate certificate and key files
+    _validate_file_exists_and_is_readable(cert_file, "certificate")
+    _validate_file_exists_and_is_readable(key_file, "key")
+
+    # If client verification is enabled, validate CA file and return TLSConfigVerifyClient
+    if get_env_tls_verify_client():
+        if not (ca_file_str := getenv(ENV_PHOENIX_TLS_CA_FILE)):
+            raise ValueError(
+                "PHOENIX_TLS_CA_FILE must be set when PHOENIX_TLS_VERIFY_CLIENT is true"
+            )
+
+        ca_file = Path(ca_file_str)
+        _validate_file_exists_and_is_readable(ca_file, "CA")
+
+        return TLSConfigVerifyClient(
+            cert_file=cert_file,
+            key_file=key_file,
+            key_file_password=key_file_password,
+            ca_file=ca_file,
+        )
+
+    return TLSConfig(
+        cert_file=cert_file,
+        key_file=key_file,
+        key_file_password=key_file_password,
+    )
+
 
 def server_instrumentation_is_enabled() -> bool:
     return bool(
@@ -956,7 +1193,8 @@ def get_env_root_url() -> URL:
     host = get_env_host()
     if host == "0.0.0.0":
         host = "127.0.0.1"
-    return URL(urljoin(f"http://{host}:{get_env_port()}", get_env_host_root_path()))
+    scheme = "https" if get_env_tls_enabled() else "http"
+    return URL(urljoin(f"{scheme}://{host}:{get_env_port()}", get_env_host_root_path()))
 
 
 def get_base_url() -> str:
@@ -964,7 +1202,8 @@ def get_base_url() -> str:
     host = get_env_host()
     if host == "0.0.0.0":
         host = "127.0.0.1"
-    base_url = get_env_collector_endpoint() or f"http://{host}:{get_env_port()}"
+    scheme = "https" if get_env_tls_enabled() else "http"
+    base_url = get_env_collector_endpoint() or f"{scheme}://{host}:{get_env_port()}"
     return base_url if base_url.endswith("/") else base_url + "/"
 
 
@@ -1159,3 +1398,30 @@ When the PHOENIX_ADMIN_SECRET is used as a bearer token in API requests, the
 request is authenticated as the system user with the user_id set to this
 SYSTEM_USER_ID value (only if this variable is not None).
 """
+
+
+def _validate_file_exists_and_is_readable(
+    file_path: Path,
+    description: str,
+    check_non_empty: bool = True,
+) -> None:
+    """
+    Validate that a file exists, is readable, and optionally has non-zero size.
+
+    Args:
+        file_path: Path to the file to validate
+        description: Description of the file for error messages (e.g., "certificate", "key", "CA")
+        check_non_empty: Whether to check if the file has non-zero size. Defaults to True.
+
+    Raises:
+        ValueError: If the path is not a file, isn't readable, or has zero size (if check_non_empty is True)
+    """  # noqa: E501
+    if not file_path.is_file():
+        raise ValueError(f"{description} path is not a file: {file_path}")
+    if check_non_empty and file_path.stat().st_size == 0:
+        raise ValueError(f"{description} file is empty: {file_path}")
+    try:
+        with open(file_path, "rb") as f:
+            f.read(1)  # Read just one byte to verify readability
+    except Exception as e:
+        raise ValueError(f"{description} file is not readable: {e}")

arize_phoenix-8.29.0/src/phoenix/db/README.md

@@ -0,0 +1,353 @@
+# Database
+
+This module is responsible for the database connection and the migrations.
+
+
+## Migrations
+
+All migrations are managed by Alembic. Migrations are applied to the database automatically when the application starts.
+
+
+### Manually Applying Migrations
+
+Sometimes, it's necessary to manually apply migrations, e.g., to recover from a failed migration. To manually apply migrations, you must first clone the Phoenix repository.
+
+```bash
+git clone https://github.com/Arize-ai/phoenix.git
+```
+
+Then navigate to the current directory.
+
+```bash
+cd phoenix/src/phoenix/db
+```
+
+If you are using a non-default SQL database URL (e.g., for running PostgreSQL), ensure your `PHOENIX_SQL_DATABASE_URL` is set. This is not needed if you are running Phoenix with the default SQLite URL.
+
+```bash
+export PHOENIX_SQL_DATABASE_URL=<sql-database-url>
+```
+
+
+To manually run up-migrations, run the following command:
+
+```bash
+alembic upgrade head
+```
+
+If the above command fails, it may be necessary to undo partially applied changes from a failed migration by first running down-migrations. This can be accomplished by identifying the ID of the migration revision you wish to return to. Revisions are defined [here](./migrations/versions/).
+
+⚠️ Running down-migrations can result in lost data. Only run down-migrations if you know what you are doing and consider backing up your database first. If you have any questions or doubts, contact the Phoenix team in the `#phoenix-support` channel of the [Arize AI Slack community](https://join.slack.com/t/arize-ai/shared_invite/zt-1px8dcmlf-fmThhDFD_V_48oU7ALan4Q) or via GitHub.
+
+```bash
+alembic downgrade <revision-id>
+```
+
+### Creating a Migration
+
+All migrations are stored in the `migrations` folder. To create a new migration, run the following command:
+
+```bash
+alembic revision -m "your_revision_name"
+```
+
+Then fill the migration file with the necessary changes.
+
+## Entity Relationship Diagram
+
+Below is a Mermaid diagram showing the current relationships between the main entities in the database:
+
+```mermaid
+erDiagram
+    Project ||--o{ Trace : has
+    Project {
+        int id PK
+        string name
+        string description
+        string gradient_start_color
+        string gradient_end_color
+        datetime created_at
+        datetime updated_at
+    }
+
+    ProjectSession ||--o{ Trace : has
+    ProjectSession {
+        int id PK
+        string session_id
+        int project_id FK
+        datetime start_time
+        datetime end_time
+    }
+
+    Trace ||--o{ Span : contains
+    Trace ||--o{ ExperimentRun : has
+    Trace ||--o{ TraceAnnotation : has
+    Trace ||--o{ ExperimentRunAnnotation : has
+    Trace {
+        int id PK
+        int project_rowid FK
+        string trace_id
+        int project_session_rowid FK
+        datetime start_time
+        datetime end_time
+    }
+
+    Span ||--o{ DocumentAnnotation : has
+    Span ||--o{ DatasetExample : has
+    Span ||--o{ SpanAnnotation : has
+    Span {
+        int id PK
+        int trace_rowid FK
+        string span_id
+        string parent_id
+        string name
+        string span_kind
+        datetime start_time
+        datetime end_time
+        json attributes
+        json events
+        string status_code
+        string status_message
+        int cumulative_error_count
+        int cumulative_llm_token_count_prompt
+        int cumulative_llm_token_count_completion
+        int llm_token_count_prompt
+        int llm_token_count_completion
+    }
+
+    DocumentAnnotation {
+        int id PK
+        int span_rowid FK
+        int document_position
+        string name
+        string label
+        float score
+        string explanation
+        json metadata
+        string annotator_kind
+        datetime created_at
+        datetime updated_at
+    }
+
+    SpanAnnotation {
+        int id PK
+        int span_rowid FK
+        string name
+        string label
+        float score
+        string explanation
+        json metadata
+        string annotator_kind
+        datetime created_at
+        datetime updated_at
+    }
+
+    TraceAnnotation {
+        int id PK
+        int trace_rowid FK
+        string name
+        string label
+        float score
+        string explanation
+        json metadata
+        string annotator_kind
+        datetime created_at
+        datetime updated_at
+    }
+
+    Dataset ||--o{ DatasetVersion : has
+    Dataset ||--o{ DatasetExample : contains
+    Dataset {
+        int id PK
+        string name
+        string description
+        json metadata
+        datetime created_at
+        datetime updated_at
+    }
+
+    DatasetVersion ||--o{ DatasetExampleRevision : has
+    DatasetVersion {
+        int id PK
+        int dataset_id FK
+        string description
+        json metadata
+        datetime created_at
+    }
+
+    DatasetExample ||--o{ DatasetExampleRevision : has
+    DatasetExample {
+        int id PK
+        int dataset_id FK
+        int span_rowid FK
+        datetime created_at
+    }
+
+    DatasetExampleRevision {
+        int id PK
+        int dataset_example_id FK
+        int dataset_version_id FK
+        json input
+        json output
+        json metadata
+        string revision_kind
+        datetime created_at
+    }
+
+    Experiment ||--o{ ExperimentRun : has
+    Experiment {
+        int id PK
+        int dataset_id FK
+        int dataset_version_id FK
+        string name
+        string description
+        int repetitions
+        json metadata
+        string project_name
+        datetime created_at
+        datetime updated_at
+    }
+
+    ExperimentRun ||--o{ ExperimentRunAnnotation : has
+    ExperimentRun {
+        int id PK
+        int experiment_id FK
+        int dataset_example_id FK
+        int repetition_number
+        string trace_id
+        json output
+        datetime start_time
+        datetime end_time
+        int prompt_token_count
+        int completion_token_count
+        string error
+    }
+
+    ExperimentRunAnnotation {
+        int id PK
+        int experiment_run_id FK
+        string name
+        string annotator_kind
+        string label
+        float score
+        string explanation
+        string trace_id
+        string error
+        json metadata
+        datetime start_time
+        datetime end_time
+    }
+
+    User ||--o{ ApiKey : has
+    User ||--o{ AccessToken : has
+    User ||--o{ RefreshToken : has
+    User ||--o{ PasswordResetToken : has
+    User ||--o{ PromptVersion : has
+    User ||--o{ PromptVersionTag : has
+    User {
+        int id PK
+        int user_role_id FK
+        string username
+        string email
+        string profile_picture_url
+        bytes password_hash
+        bytes password_salt
+        boolean reset_password
+        string oauth2_client_id
+        string oauth2_user_id
+        datetime created_at
+        datetime updated_at
+    }
+
+    UserRole ||--o{ User : has
+    UserRole {
+        int id PK
+        string name
+    }
+
+    ApiKey {
+        int id PK
+        int user_id FK
+        string name
+        string description
+        datetime created_at
+        datetime expires_at
+    }
+
+    AccessToken {
+        int id PK
+        int user_id FK
+        datetime created_at
+        datetime expires_at
+        int refresh_token_id FK
+    }
+
+    RefreshToken {
+        int id PK
+        int user_id FK
+        datetime created_at
+        datetime expires_at
+    }
+
+    PasswordResetToken {
+        int id PK
+        int user_id FK
+        datetime created_at
+        datetime expires_at
+    }
+
+    Prompt ||--o{ PromptVersion : has
+    Prompt ||--o{ PromptPromptLabel : has
+    Prompt ||--o{ PromptVersionTag : has
+    Prompt ||--o{ Prompt : has
+    Prompt {
+        int id PK
+        int source_prompt_id FK
+        string name
+        string description
+        json metadata
+        datetime created_at
+        datetime updated_at
+    }
+
+    PromptVersion ||--o{ PromptVersionTag : has
+    PromptVersion {
+        int id PK
+        int prompt_id FK
+        string description
+        int user_id FK
+        string template_type
+        string template_format
+        json template
+        json invocation_parameters
+        json tools
+        json response_format
+        string model_provider
+        string model_name
+        json metadata
+        datetime created_at
+    }
+
+    PromptLabel ||--o{ PromptPromptLabel : has
+    PromptLabel {
+        int id PK
+        string name
+        string description
+        string color
+    }
+
+    PromptPromptLabel {
+        int id PK
+        int prompt_label_id FK
+        int prompt_id FK
+    }
+
+    PromptVersionTag {
+        int id PK
+        string name
+        string description
+        int prompt_id FK
+        int prompt_version_id FK
+        int user_id FK
+    }
+```

{arize_phoenix-8.28.0 → arize_phoenix-8.29.0}/src/phoenix/server/api/queries.py

@@ -427,11 +427,8 @@ class Query:
     @strawberry.field
     async def functionality(self, info: Info[Context, None]) -> "Functionality":
         has_model_inferences = not info.context.model.is_empty
-        async with info.context.db() as session:
-            has_traces = (await session.scalar(select(models.Trace).limit(1))) is not None
         return Functionality(
             model_inferences=has_model_inferences,
-            tracing=has_traces,
         )
 
     @strawberry.field

{arize_phoenix-8.28.0 → arize_phoenix-8.29.0}/src/phoenix/server/api/types/Functionality.py

@@ -10,6 +10,3 @@ class Functionality:
     model_inferences: bool = strawberry.field(
         description="Model inferences are available for analysis"
     )
-    tracing: bool = strawberry.field(
-        description="Generative tracing records are available for analysis"
-    )