pointblank 0.13.3__py3-none-any.whl → 0.14.0__py3-none-any.whl

pointblank/validate.py

@@ -6,11 +6,14 @@ import copy
 import datetime
 import inspect
 import json
+import pickle
 import re
 import tempfile
 import threading
 from dataclasses import dataclass
+from enum import Enum
 from importlib.metadata import version
+from pathlib import Path
 from typing import TYPE_CHECKING, Any, Callable, Literal
 from zipfile import ZipFile
 
@@ -31,6 +34,7 @@ from pointblank._constants import (
     CROSS_MARK_SPAN,
     IBIS_BACKENDS,
     LOG_LEVELS_MAP,
+    MODEL_PROVIDERS,
     REPORTING_LANGUAGES,
     ROW_BASED_VALIDATION_TYPES,
     RTL_LANGUAGES,
@@ -74,6 +78,7 @@ from pointblank._utils import (
     _check_any_df_lib,
     _check_invalid_fields,
     _column_test_prep,
+    _copy_dataframe,
     _count_null_values_in_column,
     _count_true_values_in_column,
     _derive_bounds,
@@ -113,6 +118,8 @@ if TYPE_CHECKING:
 __all__ = [
     "Validate",
     "load_dataset",
+    "read_file",
+    "write_file",
     "config",
     "connect_to_table",
     "preview",
@@ -579,6 +586,759 @@ def load_dataset(
     return dataset
 
 
+def read_file(filepath: str | Path) -> Validate:
+    """
+    Read a Validate object from disk that was previously saved with `write_file()`.
+
+    This function loads a validation object that was previously serialized to disk using the
+    `write_file()` function. The validation object will be restored with all its validation results,
+    metadata, and optionally the source data (if it was saved with `keep_tbl=True`).
+
+    :::{.callout-warning}
+    The `read_file()` function is currently experimental. Please report any issues you encounter in
+    the [Pointblank issue tracker](https://github.com/posit-dev/pointblank/issues).
+    :::
+
+    Parameters
+    ----------
+    filepath
+        The path to the saved validation file. Can be a string or Path object.
+
+    Returns
+    -------
+    Validate
+        The restored validation object with all its original state, validation results, and
+        metadata.
+
+    Examples
+    --------
+    Load a validation object that was previously saved:
+
+    ```python
+    import pointblank as pb
+
+    # Load a validation object from disk
+    validation = pb.read_file("my_validation.pkl")
+
+    # View the validation results
+    validation
+    ```
+
+    You can also load using just the filename (without extension):
+
+    ```python
+    # This will automatically look for "my_validation.pkl"
+    validation = pb.read_file("my_validation")
+    ```
+
+    The loaded validation object retains all its functionality:
+
+    ```python
+    # Get validation summary
+    summary = validation.get_json_report()
+
+    # Get sundered data (if original table was saved)
+    if validation.data is not None:
+        failing_rows = validation.get_sundered_data(type="fail")
+    ```
+
+    See Also
+    --------
+    Use the [`write_file()`](`pointblank.Validate.write_file`) method to save a validation object
+    to disk for later retrieval with this function.
+    """
+    # Handle file path and extension
+    file_path = Path(filepath)
+    if not file_path.suffix:
+        file_path = file_path.with_suffix(".pkl")
+
+    # Check if file exists
+    if not file_path.exists():
+        raise FileNotFoundError(f"Validation file not found: {file_path}")
+
+    # Load and deserialize the validation object
+    try:
+        with open(file_path, "rb") as f:
+            loaded_data = pickle.load(f)
+
+        # Expect validation package format with function sources
+        if not isinstance(loaded_data, dict) or "validation" not in loaded_data:
+            raise RuntimeError(f"Invalid validation file format: {file_path}")
+
+        validation = loaded_data["validation"]
+        function_sources = loaded_data["function_sources"]
+
+        # Restore functions from source code
+        if function_sources:  # pragma: no cover
+            restored_functions = {}  # pragma: no cover
+            for func_name, source_code in function_sources.items():  # pragma: no cover
+                try:  # pragma: no cover
+                    # Create a namespace with common imports that functions might need
+                    execution_namespace = {}  # pragma: no cover
+
+                    # Add common imports to the execution namespace
+                    try:  # pragma: no cover
+                        import polars as pl  # pragma: no cover
+
+                        execution_namespace["pl"] = pl  # pragma: no cover
+
+                    except ImportError:  # pragma: no cover
+                        pass  # pragma: no cover
+
+                    try:  # pragma: no cover
+                        import pandas as pd  # pragma: no cover
+
+                        execution_namespace["pd"] = pd  # pragma: no cover
+
+                    except ImportError:  # pragma: no cover
+                        pass  # pragma: no cover
+
+                    try:  # pragma: no cover
+                        import narwhals as nw  # pragma: no cover
+
+                        execution_namespace["nw"] = nw  # pragma: no cover
+
+                    except ImportError:  # pragma: no cover
+                        pass  # pragma: no cover
+
+                    # Execute the function source code with the enhanced namespace
+                    exec(source_code, execution_namespace, execution_namespace)  # pragma: no cover
+
+                    # The function should now be in the execution namespace
+                    if func_name in execution_namespace:  # pragma: no cover
+                        restored_functions[func_name] = execution_namespace[
+                            func_name
+                        ]  # pragma: no cover
+                    else:  # pragma: no cover
+                        print(
+                            f"Warning: Function '{func_name}' not found after executing source code"
+                        )
+
+                except Exception as e:  # pragma: no cover
+                    print(f"Warning: Could not restore function '{func_name}': {e}")
+
+            # Restore functions to validation steps
+            for validation_info in validation.validation_info:  # pragma: no cover
+                if (  # pragma: no cover
+                    hasattr(validation_info, "_pb_function_name")
+                    and validation_info._pb_function_name in restored_functions
+                ):
+                    func_name = validation_info._pb_function_name  # pragma: no cover
+                    validation_info.pre = restored_functions[func_name]  # pragma: no cover
+                    # Clean up the temporary attribute
+                    delattr(validation_info, "_pb_function_name")  # pragma: no cover
+
+        # Verify that we loaded a Validate object
+        if not isinstance(validation, Validate):  # pragma: no cover
+            raise RuntimeError(f"File does not contain a valid Validate object: {file_path}")
+
+        return validation
+
+    except Exception as e:
+        raise RuntimeError(f"Failed to read validation object from {file_path}: {e}")
+
+
+def _check_for_unpicklable_objects(validation: Validate) -> tuple[dict[str, str], list[int]]:
+    """
+    Check for functions and capture source code for preservation across sessions.
+
+    This function examines all preprocessing functions and attempts to capture their source code for
+    later restoration. Lambda functions are rejected. Functions that might be picklable in the
+    current session but fail across sessions (e.g., interactively defined functions) have their
+    source preserved.
+
+    Returns
+    -------
+    tuple[dict[str, str], list[int]]
+        A tuple containing:
+        - A dictionary mapping function names to their source code
+        - A list of step indices that have unpicklable lambda functions (which should cause errors)
+    """
+    import inspect
+    import pickle
+
+    unpicklable_lambda_steps = []
+    function_sources = {}
+
+    for i, validation_info in enumerate(validation.validation_info):
+        if hasattr(validation_info, "pre") and validation_info.pre is not None:
+            func = validation_info.pre
+            func_name = getattr(func, "__name__", "<unknown>")
+
+            # Always reject lambda functions
+            if func_name == "<lambda>":
+                unpicklable_lambda_steps.append((i, validation_info))
+                continue
+
+            # For all non-lambda functions, try to capture source code
+            # This helps with functions that might be picklable now but fail across sessions
+            source_code = None
+
+            try:
+                # Try to get the source code
+                source_code = inspect.getsource(func)
+
+                # Test if the function can be pickled and loaded in a clean environment
+                # by checking if it's defined in a "real" module vs interactively
+                func_module = getattr(func, "__module__", None)
+
+                if func_module == "__main__" or not func_module:
+                    # Functions defined in __main__ or without a module are risky
+                    # These might pickle now but fail when loaded elsewhere
+                    function_sources[func_name] = source_code  # pragma: no cover
+                    validation_info._pb_function_name = func_name  # pragma: no cover
+
+            except (OSError, TypeError):  # pragma: no cover
+                # If we can't get source, check if it's at least picklable
+                try:  # pragma: no cover
+                    pickle.dumps(func, protocol=pickle.HIGHEST_PROTOCOL)  # pragma: no cover
+                    # It's picklable but no source: this might cause issues across sessions
+                    print(  # pragma: no cover
+                        f"Warning: Function '{func_name}' is picklable but source code could not be captured. "
+                        f"It may not be available when loading in a different session."
+                    )
+                except (pickle.PicklingError, AttributeError, TypeError):  # pragma: no cover
+                    # Not picklable and no source: treat as problematic
+                    print(  # pragma: no cover
+                        f"Warning: Function '{func_name}' is not picklable and source could not be captured. "
+                        f"It will not be available after saving/loading."
+                    )
+                    unpicklable_lambda_steps.append((i, validation_info))  # pragma: no cover
+
+    # Only raise error for lambda functions now
+    if unpicklable_lambda_steps:
+        step_descriptions = []
+        for i, step in unpicklable_lambda_steps:
+            desc = f"Step {i + 1}"
+            if hasattr(step, "assertion_type"):
+                desc += f" ({step.assertion_type})"
+            if hasattr(step, "column") and step.column:
+                desc += f" on column '{step.column}'"
+            step_descriptions.append(desc)
+
+        raise ValueError(
+            f"Cannot serialize validation object: found {len(unpicklable_lambda_steps)} validation step(s) "
+            f"with unpicklable preprocessing functions (likely lambda functions defined in interactive "
+            f"environments):\n\n"
+            + "\n".join(f"  - {desc}" for desc in step_descriptions)
+            + "\n\nTo resolve this, define your preprocessing functions at the module level:\n\n"
+            "  # Instead of:\n"
+            "  .col_vals_gt(columns='a', value=10, pre=lambda df: df.with_columns(...))\n\n"
+            "  # Use:\n"
+            "  def preprocess_data(df):\n"
+            "      return df.with_columns(...)\n\n"
+            "  .col_vals_gt(columns='a', value=10, pre=preprocess_data)\n\n"
+            "Module-level functions can be pickled and will preserve the complete validation logic."
+        )
+
+    return function_sources, []
+
+
+def _provide_serialization_guidance(validation: Validate) -> None:
+    """
+    Provide helpful guidance to users about creating serializable validations.
+
+    This function analyzes the validation object and provides tailored advice
+    about preprocessing functions, best practices, and potential issues.
+    """
+    import pickle
+
+    # Find all preprocessing functions in the validation
+    preprocessing_functions = []
+
+    for i, validation_info in enumerate(validation.validation_info):
+        if hasattr(validation_info, "pre") and validation_info.pre is not None:
+            preprocessing_functions.append((i, validation_info))
+
+    if not preprocessing_functions:  # pragma: no cover
+        # No preprocessing functions: validation should serialize cleanly
+        print("  Serialization Analysis:")  # pragma: no cover
+        print("   ✓ No preprocessing functions detected")  # pragma: no cover
+        print(
+            "   ✓ This validation should serialize and load reliably across sessions"
+        )  # pragma: no cover
+        return  # pragma: no cover
+
+    print("  Serialization Analysis:")  # pragma: no cover
+    print(  # pragma: no cover
+        f"   Found {len(preprocessing_functions)} validation step(s) with preprocessing functions"
+    )
+
+    # Analyze each function
+    functions_analysis = {  # pragma: no cover
+        "module_functions": [],
+        "interactive_functions": [],
+        "lambda_functions": [],
+        "unpicklable_functions": [],
+    }
+
+    for i, validation_info in preprocessing_functions:  # pragma: no cover
+        func = validation_info.pre  # pragma: no cover
+        func_name = getattr(func, "__name__", "<unknown>")  # pragma: no cover
+        func_module = getattr(func, "__module__", "<unknown>")  # pragma: no cover
+
+        # Categorize the function
+        if func_name == "<lambda>":  # pragma: no cover
+            functions_analysis["lambda_functions"].append(
+                (i, func_name, func_module)
+            )  # pragma: no cover
+        else:  # pragma: no cover
+            # Test if it can be pickled
+            try:  # pragma: no cover
+                pickle.dumps(func, protocol=pickle.HIGHEST_PROTOCOL)  # pragma: no cover
+                can_pickle = True  # pragma: no cover
+            except (pickle.PicklingError, AttributeError, TypeError):  # pragma: no cover
+                can_pickle = False  # pragma: no cover
+                functions_analysis["unpicklable_functions"].append(
+                    (i, func_name, func_module)
+                )  # pragma: no cover
+                continue  # pragma: no cover
+
+            # Check if it's likely to work across sessions
+            if (
+                func_module == "__main__" or not func_module or func_module == "<unknown>"
+            ):  # pragma: no cover
+                # Function defined interactively - risky for cross-session use
+                functions_analysis["interactive_functions"].append(
+                    (i, func_name, func_module)
+                )  # pragma: no cover
+            else:  # pragma: no cover
+                # Function from a proper module - should work reliably
+                functions_analysis["module_functions"].append(
+                    (i, func_name, func_module)
+                )  # pragma: no cover
+
+    # Provide specific guidance based on analysis
+    if functions_analysis["module_functions"]:  # pragma: no cover
+        print("   ✓ Module-level functions detected:")
+        for i, func_name, func_module in functions_analysis["module_functions"]:
+            print(f"     • Step {i + 1}: {func_name} (from {func_module})")
+        print("     These should work reliably across sessions")
+
+    if functions_analysis["interactive_functions"]:  # pragma: no cover
+        print("      Interactive functions detected:")
+        for i, func_name, func_module in functions_analysis["interactive_functions"]:
+            print(f"     • Step {i + 1}: {func_name} (defined in {func_module})")
+        print("     These may not load properly in different sessions")
+        print()
+        print("     Recommendation: Move these functions to a separate .py module:")
+        print("      1. Create a file like 'preprocessing_functions.py'")
+        print("      2. Define your functions there with proper imports")
+        print("      3. Import them: from preprocessing_functions import your_function")
+        print("      4. This ensures reliable serialization across sessions")
+
+    if functions_analysis["lambda_functions"]:  # pragma: no cover
+        print("     Lambda functions detected:")
+        for i, func_name, func_module in functions_analysis["lambda_functions"]:
+            print(f"     • Step {i + 1}: {func_name}")
+        print("     Lambda functions cannot be serialized!")
+        print()
+        print("     Required fix: Replace lambda functions with named functions:")
+        print("      # Instead of: pre=lambda df: df.with_columns(...)")
+        print("      # Use: ")
+        print("      def my_preprocessing_function(df):")
+        print("          return df.with_columns(...)")
+        print("      # Then: pre=my_preprocessing_function")
+
+    if functions_analysis["unpicklable_functions"]:  # pragma: no cover
+        print("     Unpicklable functions detected:")
+        for i, func_name, func_module in functions_analysis["unpicklable_functions"]:
+            print(f"     • Step {i + 1}: {func_name} (from {func_module})")
+        print("     These functions cannot be serialized")
+
+    # Provide overall assessment
+    total_problematic = (
+        len(functions_analysis["interactive_functions"])
+        + len(functions_analysis["lambda_functions"])
+        + len(functions_analysis["unpicklable_functions"])
+    )
+
+    if total_problematic == 0:  # pragma: no cover
+        print("     All preprocessing functions should serialize reliably!")
+    else:  # pragma: no cover
+        print(
+            f"      {total_problematic} function(s) may cause issues when loading in different sessions"
+        )
+        print()
+        print("     Best Practice Guide:")
+        print("      • Define all preprocessing functions in separate .py modules")
+        print("      • Import functions before creating and loading validations")
+        print("      • Avoid lambda functions and interactive definitions")
+        print("      • Test your validation by loading it in a fresh Python session")
+
+        # Offer to create a template
+        print()
+        print("     Example module structure:")
+        print("      # preprocessing_functions.py")
+        print("      import polars as pl  # or pandas, numpy, etc.")
+        print("      ")
+        print("      def multiply_by_factor(df, factor=10):")
+        print("          return df.with_columns(pl.col('value') * factor)")
+        print("      ")
+        print("      # your_main_script.py")
+        print("      import pointblank as pb")
+        print("      from preprocessing_functions import multiply_by_factor")
+        print("      ")
+        print(
+            "      validation = pb.Validate(data).col_vals_gt('value', 100, pre=multiply_by_factor)"
+        )
+
+
+def write_file(
+    validation: Validate,
+    filename: str,
+    path: str | None = None,
+    keep_tbl: bool = False,
+    keep_extracts: bool = False,
+    quiet: bool = False,
+) -> None:
+    """
+    Write a Validate object to disk as a serialized file.
+
+    Writing a validation object to disk with `write_file()` can be useful for keeping data
+    validation results close at hand for later retrieval (with `read_file()`). By default, any data
+    table that the validation object holds will be removed before writing to disk (not applicable if
+    no data table is present). This behavior can be changed by setting `keep_tbl=True`, but this
+    only works when the table is not of a database type (e.g., DuckDB, PostgreSQL, etc.), as
+    database connections cannot be serialized.
+
+    Extract data from failing validation steps can also be preserved by setting
+    `keep_extracts=True`, which is useful for later analysis of data quality issues.
+
+    The serialized file uses Python's pickle format for storage of the validation object state,
+    including all validation results, metadata, and optionally the source data.
+
+    **Important note.** If your validation uses custom preprocessing functions (via the `pre=`
+    parameter), these functions must be defined at the module level (not interactively or as lambda
+    functions) to ensure they can be properly restored when loading the validation in a different
+    Python session. Read the *Creating Serializable Validations* section below for more information.
+
+    :::{.callout-warning}
+    The `write_file()` function is currently experimental. Please report any issues you encounter in
+    the [Pointblank issue tracker](https://github.com/posit-dev/pointblank/issues).
+    :::
+
+    Parameters
+    ----------
+    validation
+        The `Validate` object to write to disk.
+    filename
+        The filename to create on disk for the validation object. Should not include the file
+        extension as `.pkl` will be added automatically.
+    path
+        An optional directory path where the file should be saved. If not provided, the file will be
+        saved in the current working directory. The directory will be created if it doesn't exist.
+    keep_tbl
+        An option to keep the data table that is associated with the validation object. The default
+        is `False` where the data table is removed before writing to disk. For database tables
+        (e.g., Ibis tables with database backends), the table is always removed even if
+        `keep_tbl=True`, as database connections cannot be serialized.
+    keep_extracts
+        An option to keep any collected extract data for failing rows from validation steps. By
+        default, this is `False` (i.e., extract data is removed to save space).
+    quiet
+        Should the function not inform when the file is written? By default, this is `False`, so a
+        message will be printed when the file is successfully written.
+
+    Returns
+    -------
+    None
+        This function doesn't return anything but saves the validation object to disk.
+
+    Creating Serializable Validations
+    ---------------------------------
+    To ensure your validations work reliably across different Python sessions, the recommended
+    approach is to use module-Level functions. So, create a separate Python file for your
+    preprocessing functions:
+
+    ```python
+    # preprocessing_functions.py
+    import polars as pl
+
+    def multiply_by_100(df):
+        return df.with_columns(pl.col("value") * 100)
+
+    def add_computed_column(df):
+        return df.with_columns(computed=pl.col("value") * 2 + 10)
+    ```
+
+    Then import and use them in your validation:
+
+    ```python
+    # your_main_script.py
+    import pointblank as pb
+    from preprocessing_functions import multiply_by_100, add_computed_column
+
+    validation = (
+        pb.Validate(data=my_data)
+        .col_vals_gt(columns="value", value=500, pre=multiply_by_100)
+        .col_vals_between(columns="computed", left=50, right=1000, pre=add_computed_column)
+        .interrogate()
+    )
+
+    # Save validation and it will work reliably across sessions
+    pb.write_file(validation, "my_validation", keep_tbl=True)
+    ```
+
+    ### Problematic Patterns to Avoid
+
+    Don't use lambda functions as they will cause immediate errors.
+
+    ```python
+    validation = pb.Validate(data).col_vals_gt(
+        columns="value", value=100,
+        pre=lambda df: df.with_columns(pl.col("value") * 2)
+    )
+    ```
+
+    Don't use interactive function definitions (as they may fail when loading).
+
+    ```python
+    def my_function(df):  # Defined in notebook/REPL
+        return df.with_columns(pl.col("value") * 2)
+
+    validation = pb.Validate(data).col_vals_gt(
+        columns="value", value=100, pre=my_function
+    )
+    ```
+
+    ### Automatic Analysis and Guidance
+
+    When you call `write_file()`, it automatically analyzes your validation and provides:
+
+    - confirmation when all functions will work reliably
+    - warnings for functions that may cause cross-session issues
+    - clear errors for unsupported patterns (lambda functions)
+    - specific recommendations and code examples
+    - loading instructions tailored to your validation
+
+    ### Loading Your Validation
+
+    To load a saved validation in a new Python session:
+
+    ```python
+    # In a new Python session
+    import pointblank as pb
+
+    # Import the same preprocessing functions used when creating the validation
+    from preprocessing_functions import multiply_by_100, add_computed_column
+
+    # Upon loading the validation, functions will be automatically restored
+    validation = pb.read_file("my_validation.pkl")
+    ```
+
+    ** Testing Your Validation:**
+
+    To verify your validation works across sessions:
+
+    1. save your validation in one Python session
+    2. start a fresh Python session (restart kernel/interpreter)
+    3. import required preprocessing functions
+    4. load the validation using `read_file()`
+    5. test that preprocessing functions work as expected
+
+    ### Performance and Storage
+
+    - use `keep_tbl=False` (default) to reduce file size when you don't need the original data
+    - use `keep_extracts=False` (default) to save space by excluding extract data
+    - set `quiet=True` to suppress guidance messages in automated scripts
+    - files are saved using pickle's highest protocol for optimal performance
+
+    Examples
+    --------
+    Let's create a simple validation and save it to disk:
+
+    ```{python}
+    import pointblank as pb
+
+    # Create a validation
+    validation = (
+        pb.Validate(data=pb.load_dataset("small_table"), label="My validation")
+        .col_vals_gt(columns="d", value=100)
+        .col_vals_regex(columns="b", pattern=r"[0-9]-[a-z]{3}-[0-9]{3}")
+        .interrogate()
+    )
+
+    # Save to disk (without the original table data)
+    pb.write_file(validation, "my_validation")
+    ```
+
+    To keep the original table data for later analysis:
+
+    ```{python}
+    # Save with the original table data included
+    pb.write_file(validation, "my_validation_with_data", keep_tbl=True)
+    ```
+
+    You can also specify a custom directory and keep extract data:
+
+    ```python
+    pb.write_file(
+        validation,
+        filename="detailed_validation",
+        path="/path/to/validations",
+        keep_tbl=True,
+        keep_extracts=True
+    )
+    ```
+
+    ### Working with Preprocessing Functions
+
+    For validations that use preprocessing functions to be portable across sessions, define your
+    functions in a separate `.py` file:
+
+    ```python
+    # In `preprocessing_functions.py`
+
+    import polars as pl
+
+    def multiply_by_100(df):
+        return df.with_columns(pl.col("value") * 100)
+
+    def add_computed_column(df):
+        return df.with_columns(computed=pl.col("value") * 2 + 10)
+    ```
+
+    Then import and use them in your validation:
+
+    ```python
+    # In your main script
+
+    import pointblank as pb
+    from preprocessing_functions import multiply_by_100, add_computed_column
+
+    validation = (
+        pb.Validate(data=my_data)
+        .col_vals_gt(columns="value", value=500, pre=multiply_by_100)
+        .col_vals_between(columns="computed", left=50, right=1000, pre=add_computed_column)
+        .interrogate()
+    )
+
+    # This validation can now be saved and loaded reliably
+    pb.write_file(validation, "my_validation", keep_tbl=True)
+    ```
+
+    When you load this validation in a new session, simply import the preprocessing functions
+    again and they will be automatically restored.
+
+    See Also
+    --------
+    Use the [`read_file()`](`pointblank.read_file`) function to load a validation object that was
+    previously saved with `write_file()`.
+    """
+    # Construct the full file path
+    if not filename.endswith(".pkl"):
+        filename = f"{filename}.pkl"
+
+    if path is not None:
+        file_path = Path(path) / filename
+    else:
+        file_path = Path(filename)
+
+    # Create directory if it doesn't exist
+    file_path.parent.mkdir(parents=True, exist_ok=True)
+
+    # Create a copy of the validation object to avoid modifying the original
+    validation_copy = copy.deepcopy(validation)
+
+    # Handle data table preservation
+    if not keep_tbl:
+        validation_copy.data = None
+    else:
+        # Check if the data is a database table that cannot be serialized
+        if validation_copy.data is not None:
+            tbl_type = _get_tbl_type(validation_copy.data)
+
+            # Database tables cannot be serialized, so remove them regardless of keep_tbl
+            if tbl_type in [
+                "duckdb",
+                "mysql",
+                "postgresql",
+                "sqlite",
+                "mssql",
+                "snowflake",
+                "databricks",
+                "bigquery",
+            ]:
+                validation_copy.data = None
+                if not quiet:  # pragma: no cover
+                    print(
+                        f"Note: Database table removed from saved validation "
+                        f"(table type: {tbl_type})"
+                    )
+
+    # Handle extract data preservation
+    if not keep_extracts:
+        # Remove extract data from validation_info to save space
+        for validation_info in validation_copy.validation_info:
+            if hasattr(validation_info, "extract"):
+                validation_info.extract = None
+
+    # Provide user guidance about serialization if not quiet
+    if not quiet:
+        _provide_serialization_guidance(validation_copy)
+
+    # Check for unpicklable objects and capture function sources
+    function_sources, lambda_steps = _check_for_unpicklable_objects(validation_copy)
+
+    # Create a validation package that includes both the object and function sources
+    validation_package = {"validation": validation_copy, "function_sources": function_sources}
+
+    # Serialize to disk using pickle
+    try:
+        with open(file_path, "wb") as f:
+            pickle.dump(validation_package, f, protocol=pickle.HIGHEST_PROTOCOL)
+
+        if not quiet:  # pragma: no cover
+            print(f"✅ Validation object written to: {file_path}")
+
+            if function_sources:  # pragma: no cover
+                print(
+                    f"   🔧 Enhanced preservation: Captured source code for {len(function_sources)} function(s)"
+                )
+                for func_name in function_sources.keys():
+                    print(f"      • {func_name}")
+                print("   📥 These functions will be automatically restored when loading")
+
+            # Provide loading instructions
+            preprocessing_funcs = [
+                info
+                for info in validation_copy.validation_info
+                if hasattr(info, "pre") and info.pre is not None
+            ]
+            if preprocessing_funcs:
+                print()
+                print("   💡 To load this validation in a new session:")
+                print("      import pointblank as pb")
+                if any(
+                    hasattr(info.pre, "__module__")
+                    and info.pre.__module__ not in ["__main__", None]
+                    for info in preprocessing_funcs
+                    if hasattr(info, "pre") and info.pre
+                ):
+                    print("      # Import any preprocessing functions from their modules")
+                    modules_mentioned = set()
+                    for info in preprocessing_funcs:
+                        if (
+                            hasattr(info, "pre")
+                            and hasattr(info.pre, "__module__")
+                            and info.pre.__module__ not in ["__main__", None]
+                        ):
+                            if info.pre.__module__ not in modules_mentioned:
+                                print(
+                                    f"      from {info.pre.__module__} import {info.pre.__name__}"
+                                )
+                                modules_mentioned.add(info.pre.__module__)
+                print(f"      validation = pb.read_file('{file_path.name}')")
+            else:
+                print("   📖 To load: validation = pb.read_file('{}')".format(file_path.name))
+
+    except Exception as e:  # pragma: no cover
+        raise RuntimeError(
+            f"Failed to write validation object to {file_path}: {e}"
+        )  # pragma: no cover
+
+
 def get_data_path(
     dataset: Literal["small_table", "game_revenue", "nycflights", "global_sales"] = "small_table",
     file_type: Literal["csv", "parquet", "duckdb"] = "csv",
@@ -2650,6 +3410,48 @@ def get_column_count(data: FrameT | Any) -> int:
             raise ValueError("The input table type supplied in `data=` is not supported.")
 
 
+def _extract_enum_values(set_values: Any) -> list[Any]:
+    """
+    Extract values from Enum classes or collections containing Enum instances.
+
+    This helper function handles:
+    1. Enum classes: extracts all enum values
+    2. Collections containing Enum instances: extracts their values
+    3. Regular collections: returns as-is
+
+    Parameters
+    ----------
+    set_values
+        The input collection that may contain Enum class or Enum instances.
+
+    Returns
+    -------
+    list[Any]
+        A list of extracted values
+    """
+    from collections.abc import Collection
+
+    # Check if set_values is an Enum class (not an instance)
+    if inspect.isclass(set_values) and issubclass(set_values, Enum):
+        # Extract all values from the Enum class
+        return [enum_member.value for enum_member in set_values]
+
+    # Check if set_values is a collection
+    if isinstance(set_values, Collection) and not isinstance(set_values, (str, bytes)):
+        extracted_values = []
+        for item in set_values:
+            if isinstance(item, Enum):
+                # If item is an Enum instance, extract its value
+                extracted_values.append(item.value)
+            else:
+                # If item is not an Enum instance, keep as-is
+                extracted_values.append(item)
+        return extracted_values
+
+    # If set_values is neither an Enum class nor a collection, return as list
+    return [set_values]
+
+
 def get_row_count(data: FrameT | Any) -> int:
     """
     Get the number of rows in a table.
@@ -3401,7 +4203,7 @@ class Validate:
         summary = pb.get_validation_summary()
         if summary["status"] == "CRITICAL":
             send_alert_email(
-                subject=f"CRITICAL validation failures in {summary['table_name']}",
+                subject=f"CRITICAL validation failures in {summary['tbl_name']}",
                 body=f"{summary['critical_steps']} steps failed with critical severity."
             )
 
@@ -3449,6 +4251,11 @@ class Validate:
     - Japanese (`"ja"`)
     - Korean (`"ko"`)
     - Vietnamese (`"vi"`)
+    - Indonesian (`"id"`)
+    - Ukrainian (`"uk"`)
+    - Hebrew (`"he"`)
+    - Thai (`"th"`)
+    - Persian (`"fa"`)
 
     Automatically generated briefs (produced by using `brief=True` or `brief="...{auto}..."`) will
     be written in the selected language. The language setting will also used when generating the
@@ -6332,7 +7139,10 @@ class Validate:
             multiple columns are supplied or resolved, there will be a separate validation step
             generated for each column.
         set
-            A list of values to compare against.
+            A collection of values to compare against. Can be a list of values, a Python Enum class,
+            or a collection containing Enum instances. When an Enum class is provided, all enum
+            values will be used. When a collection contains Enum instances, their values will be
+            extracted automatically.
         pre
             An optional preprocessing function or lambda to apply to the data table during
             interrogation. This function should take a table as input and return a modified table.
@@ -6509,12 +7319,69 @@ class Validate:
 
         The validation table reports two failing test units. The specific failing cases are for the
         column `b` values of `8` and `1`, which are not in the set of `[2, 3, 4, 5, 6]`.
+
+        **Using Python Enums**
+
+        The `col_vals_in_set()` method also supports Python Enum classes and instances, which can
+        make validations more readable and maintainable:
+
+        ```{python}
+        from enum import Enum
+
+        class Color(Enum):
+            RED = "red"
+            GREEN = "green"
+            BLUE = "blue"
+
+        # Create a table with color data
+        tbl_colors = pl.DataFrame({
+            "product": ["shirt", "pants", "hat", "shoes"],
+            "color": ["red", "blue", "green", "yellow"]
+        })
+
+        # Validate using an Enum class (all enum values are allowed)
+        validation = (
+            pb.Validate(data=tbl_colors)
+            .col_vals_in_set(columns="color", set=Color)
+            .interrogate()
+        )
+
+        validation
+        ```
+
+        This validation will fail for the `"yellow"` value since it's not in the `Color` enum.
+
+        You can also use specific Enum instances or mix them with regular values:
+
+        ```{python}
+        # Validate using specific Enum instances
+        validation = (
+            pb.Validate(data=tbl_colors)
+            .col_vals_in_set(columns="color", set=[Color.RED, Color.BLUE])
+            .interrogate()
+        )
+
+        # Mix Enum instances with regular values
+        validation = (
+            pb.Validate(data=tbl_colors)
+            .col_vals_in_set(columns="color", set=[Color.RED, Color.BLUE, "yellow"])
+            .interrogate()
+        )
+
+        validation
+        ```
+
+        In this case, the `"green"` value will cause a failing test unit since it's not part of the
+        specified set.
         """
 
         assertion_type = _get_fn_name()
 
         _check_column(column=columns)
 
+        # Extract values from Enum classes or Enum instances if present
+        set = _extract_enum_values(set)
+
         for val in set:
             if val is None:
                 continue
@@ -6565,7 +7432,7 @@ class Validate:
     def col_vals_not_in_set(
         self,
         columns: str | list[str] | Column | ColumnSelector | ColumnSelectorNarwhals,
-        set: list[float | int],
+        set: Collection[Any],
         pre: Callable | None = None,
         segments: SegmentSpec | None = None,
         thresholds: int | float | bool | tuple | dict | Thresholds = None,
@@ -6589,7 +7456,10 @@ class Validate:
             multiple columns are supplied or resolved, there will be a separate validation step
             generated for each column.
         set
-            A list of values to compare against.
+            A collection of values to compare against. Can be a list of values, a Python Enum class,
+            or a collection containing Enum instances. When an Enum class is provided, all enum
+            values will be used. When a collection contains Enum instances, their values will be
+            extracted automatically.
         pre
             An optional preprocessing function or lambda to apply to the data table during
             interrogation. This function should take a table as input and return a modified table.
@@ -6767,11 +7637,45 @@ class Validate:
 
         The validation table reports two failing test units. The specific failing cases are for the
         column `b` values of `2` and `6`, both of which are in the set of `[2, 3, 4, 5, 6]`.
+
+        **Using Python Enums**
+
+        Like `col_vals_in_set()`, this method also supports Python Enum classes and instances:
+
+        ```{python}
+        from enum import Enum
+
+        class InvalidStatus(Enum):
+            DELETED = "deleted"
+            ARCHIVED = "archived"
+
+        # Create a table with status data
+        status_table = pl.DataFrame({
+            "product": ["widget", "gadget", "tool", "device"],
+            "status": ["active", "pending", "deleted", "active"]
+        })
+
+        # Validate that no values are in the invalid status set
+        validation = (
+            pb.Validate(data=status_table)
+            .col_vals_not_in_set(columns="status", set=InvalidStatus)
+            .interrogate()
+        )
+
+        validation
+        ```
+
+        This `"deleted"` value in the `status` column will fail since it matches one of the invalid
+        statuses in the `InvalidStatus` enum.
         """
 
         assertion_type = _get_fn_name()
 
         _check_column(column=columns)
+
+        # Extract values from Enum classes or Enum instances if present
+        set = _extract_enum_values(set)
+
         _check_set_types(set=set)
         _check_pre(pre=pre)
         # TODO: add check for segments
@@ -7305,6 +8209,7 @@ class Validate:
         columns: str | list[str] | Column | ColumnSelector | ColumnSelectorNarwhals,
         pattern: str,
         na_pass: bool = False,
+        inverse: bool = False,
         pre: Callable | None = None,
         segments: SegmentSpec | None = None,
         thresholds: int | float | bool | tuple | dict | Thresholds = None,
@@ -7332,6 +8237,9 @@ class Validate:
         na_pass
             Should any encountered None, NA, or Null values be considered as passing test units? By
             default, this is `False`. Set to `True` to pass test units with missing values.
+        inverse
+            Should the validation step be inverted? If `True`, then the expectation is that column
+            values should *not* match the specified `pattern=` regex.
         pre
             An optional preprocessing function or lambda to apply to the data table during
             interrogation. This function should take a table as input and return a modified table.
@@ -7518,6 +8426,7 @@ class Validate:
         # _check_segments(segments=segments)
         _check_thresholds(thresholds=thresholds)
         _check_boolean_input(param=na_pass, param_name="na_pass")
+        _check_boolean_input(param=inverse, param_name="inverse")
         _check_boolean_input(param=active, param_name="active")
 
         # Determine threshold to use (global or local) and normalize a local `thresholds=` value
@@ -7537,12 +8446,15 @@ class Validate:
         # Determine brief to use (global or local) and transform any shorthands of `brief=`
         brief = self.brief if brief is None else _transform_auto_brief(brief=brief)
 
+        # Package up the `pattern=` and boolean params into a dictionary for later interrogation
+        values = {"pattern": pattern, "inverse": inverse}
+
         # Iterate over the columns and create a validation step for each
         for column in columns:
             val_info = _ValidationInfo(
                 assertion_type=assertion_type,
                 column=column,
-                values=pattern,
+                values=values,
                 na_pass=na_pass,
                 pre=pre,
                 segments=segments,
@@ -8432,6 +9344,408 @@ class Validate:
 
         return self
 
+    def prompt(
+        self,
+        prompt: str,
+        model: str,
+        columns_subset: str | list[str] | None = None,
+        batch_size: int = 1000,
+        max_concurrent: int = 3,
+        pre: Callable | None = None,
+        segments: SegmentSpec | None = None,
+        thresholds: int | float | bool | tuple | dict | Thresholds = None,
+        actions: Actions | None = None,
+        brief: str | bool | None = None,
+        active: bool = True,
+    ) -> Validate:
+        """
+        Validate rows using AI/LLM-powered analysis.
+
+        The `prompt()` validation method uses Large Language Models (LLMs) to validate rows of data
+        based on natural language criteria. Similar to other Pointblank validation methods, this
+        generates binary test results (pass/fail) that integrate seamlessly with the standard
+        reporting framework.
+
+        Like `col_vals_*()` methods, `prompt()` evaluates data against specific criteria, but
+        instead of using programmatic rules, it uses natural language prompts interpreted by an LLM.
+        Like `rows_distinct()` and `rows_complete()`, it operates at the row level and allows you to
+        specify a subset of columns for evaluation using `columns_subset=`.
+
+        The system automatically combines your validation criteria from the `prompt=` parameter with
+        the necessary technical context, data formatting instructions, and response structure
+        requirements. This is all so you only need to focus on describing your validation logic in
+        plain language.
+
+        Each row becomes a test unit that either passes or fails the validation criteria, producing
+        the familiar True/False results that appear in Pointblank validation reports. This method
+        is particularly useful for complex validation rules that are difficult to express with
+        traditional validation methods, such as semantic checks, context-dependent validation, or
+        subjective quality assessments.
+
+        Parameters
+        ----------
+        prompt
+            A natural language description of the validation criteria. This prompt should clearly
+            describe what constitutes valid vs invalid rows. Some examples:
+            `"Each row should contain a valid email address and a realistic person name"`,
+            `"Values should indicate positive sentiment"`,
+            `"The description should mention a country name"`.
+        columns_subset
+            A single column or list of columns to include in the validation. If `None`, all columns
+            will be included. Specifying fewer columns can improve performance and reduce API costs
+            so try to include only the columns necessary for the validation.
+        model
+            The model to be used. This should be in the form of `provider:model` (e.g.,
+            `"anthropic:claude-3-5-sonnet-latest"`). Supported providers are `"anthropic"`,
+            `"openai"`, `"ollama"`, and `"bedrock"`. The model name should be the specific model to
+            be used from the provider. Model names are subject to change so consult the provider's
+            documentation for the most up-to-date model names.
+        batch_size
+            Number of rows to process in each batch. Larger batches are more efficient but may hit
+            API limits. Default is `1000`.
+        max_concurrent
+            Maximum number of concurrent API requests. Higher values speed up processing but may
+            hit rate limits. Default is `3`.
+        pre
+            An optional preprocessing function or lambda to apply to the data table during
+            interrogation. This function should take a table as input and return a modified table.
+        segments
+            An optional directive on segmentation, which serves to split a validation step into
+            multiple (one step per segment). Can be a single column name, a tuple that specifies a
+            column name and its corresponding values to segment on, or a combination of both
+            (provided as a list).
+        thresholds
+            Set threshold failure levels for reporting and reacting to exceedences of the levels.
+            The thresholds are set at the step level and will override any global thresholds set in
+            `Validate(thresholds=...)`. The default is `None`, which means that no thresholds will
+            be set locally and global thresholds (if any) will take effect.
+        actions
+            Optional actions to take when the validation step meets or exceeds any set threshold
+            levels. If provided, the [`Actions`](`pointblank.Actions`) class should be used to
+            define the actions.
+        brief
+            An optional brief description of the validation step that will be displayed in the
+            reporting table. You can use the templating elements like `"{step}"` to insert
+            the step number, or `"{auto}"` to include an automatically generated brief. If `True`
+            the entire brief will be automatically generated. If `None` (the default) then there
+            won't be a brief.
+        active
+            A boolean value indicating whether the validation step should be active. Using `False`
+            will make the validation step inactive (still reporting its presence and keeping indexes
+            for the steps unchanged).
+
+        Returns
+        -------
+        Validate
+            The `Validate` object with the added validation step.
+
+        Constructing the `model` Argument
+        ---------------------------------
+        The `model=` argument should be constructed using the provider and model name separated by a
+        colon (`provider:model`). The provider text can any of:
+
+        - `"anthropic"` (Anthropic)
+        - `"openai"` (OpenAI)
+        - `"ollama"` (Ollama)
+        - `"bedrock"` (Amazon Bedrock)
+
+        The model name should be the specific model to be used from the provider. Model names are
+        subject to change so consult the provider's documentation for the most up-to-date model
+        names.
+
+        Notes on Authentication
+        -----------------------
+        API keys are automatically loaded from environment variables or `.env` files and are **not**
+        stored in the validation object for security reasons. You should consider using a secure
+        method for handling API keys.
+
+        One way to do this is to load the API key from an environment variable and retrieve it using
+        the `os` module (specifically the `os.getenv()` function). Places to store the API key might
+        include `.bashrc`, `.bash_profile`, `.zshrc`, or `.zsh_profile`.
+
+        Another solution is to store one or more model provider API keys in an `.env` file (in the
+        root of your project). If the API keys have correct names (e.g., `ANTHROPIC_API_KEY` or
+        `OPENAI_API_KEY`) then the AI validation will automatically load the API key from the `.env`
+        file. An `.env` file might look like this:
+
+        ```plaintext
+        ANTHROPIC_API_KEY="your_anthropic_api_key_here"
+        OPENAI_API_KEY="your_openai_api_key_here"
+        ```
+
+        There's no need to have the `python-dotenv` package installed when using `.env` files in
+        this way.
+
+        **Provider-specific setup**:
+
+        - **OpenAI**: set `OPENAI_API_KEY` environment variable or create `.env` file
+        - **Anthropic**: set `ANTHROPIC_API_KEY` environment variable or create `.env` file
+        - **Ollama**: no API key required, just ensure Ollama is running locally
+        - **Bedrock**: configure AWS credentials through standard AWS methods
+
+        AI Validation Process
+        ---------------------
+        The AI validation process works as follows:
+
+        1. data batching: the data is split into batches of the specified size
+        2. row deduplication: duplicate rows (based on selected columns) are identified and only
+        unique combinations are sent to the LLM for analysis
+        3. json conversion: each batch of unique rows is converted to JSON format for the LLM
+        4. prompt construction: the user prompt is embedded in a structured system prompt
+        5. llm processing: each batch is sent to the LLM for analysis
+        6. response parsing: LLM responses are parsed to extract validation results
+        7. result projection: results are mapped back to all original rows using row signatures
+        8. result aggregation: results from all batches are combined
+
+        **Performance Optimization**: the process uses row signature memoization to avoid redundant
+        LLM calls. When multiple rows have identical values in the selected columns, only one
+        representative row is validated, and the result is applied to all matching rows. This can
+        dramatically reduce API costs and processing time for datasets with repetitive patterns.
+
+        The LLM receives data in this JSON format:
+
+        ```json
+        {
+          "columns": ["col1", "col2", "col3"],
+          "rows": [
+            {"col1": "value1", "col2": "value2", "col3": "value3", "_pb_row_index": 0},
+            {"col1": "value4", "col2": "value5", "col3": "value6", "_pb_row_index": 1}
+          ]
+        }
+        ```
+
+        The LLM returns validation results in this format:
+        ```json
+        [
+          {"index": 0, "result": true},
+          {"index": 1, "result": false}
+        ]
+        ```
+
+        Prompt Design Tips
+        ------------------
+        For best results, design prompts that are:
+
+        - boolean-oriented: frame validation criteria to elicit clear valid/invalid responses
+        - specific: clearly define what makes a row valid/invalid
+        - unambiguous: avoid subjective language that could be interpreted differently
+        - context-aware: include relevant business rules or domain knowledge
+        - example-driven: consider providing examples in the prompt when helpful
+
+        **Critical**: Prompts must be designed so the LLM can determine whether each row passes or
+        fails the validation criteria. The system expects binary validation responses, so avoid
+        open-ended questions or prompts that might generate explanatory text instead of clear
+        pass/fail judgments.
+
+        Good prompt examples:
+
+        - "Each row should contain a valid email address in the 'email' column and a non-empty name
+        in the 'name' column"
+        - "The 'sentiment' column should contain positive sentiment words (happy, good, excellent,
+        etc.)"
+        - "Product descriptions should mention at least one technical specification"
+
+        Poor prompt examples (avoid these):
+
+        - "What do you think about this data?" (too open-ended)
+        - "Describe the quality of each row" (asks for description, not validation)
+        - "How would you improve this data?" (asks for suggestions, not pass/fail)
+
+        Provider Setup
+        --------------
+        **OpenAI**: Set `OPENAI_API_KEY` environment variable or create `.env` file.
+        **Anthropic**: Set `ANTHROPIC_API_KEY` environment variable or create `.env` file.
+        **Ollama**: Ensure Ollama is running locally (default: http://localhost:11434).
+        **Bedrock**: Configure AWS credentials and region.
+
+        Performance Considerations
+        --------------------------
+        AI validation is significantly slower than traditional validation methods due to API calls
+        to LLM providers. However, performance varies dramatically based on data characteristics:
+
+        **High Memoization Scenarios** (seconds to minutes):
+
+        - data with many duplicate rows in the selected columns
+        - low cardinality data (repeated patterns)
+        - small number of unique row combinations
+
+        **Low Memoization Scenarios** (minutes to hours):
+
+        - high cardinality data with mostly unique rows
+        - large datasets with few repeated patterns
+        - all or most rows requiring individual LLM evaluation
+
+        The row signature memoization optimization can reduce processing time significantly when
+        data has repetitive patterns. For datasets where every row is unique, expect longer
+        processing times similar to validating each row individually.
+
+        **Strategies to Reduce Processing Time**:
+
+        - test on data slices: define a sampling function like `def sample_1000(df): return df.head(1000)`
+        and use `pre=sample_1000` to validate on smaller samples
+        - filter relevant data: define filter functions like `def active_only(df): return df.filter(df["status"] == "active")`
+        and use `pre=active_only` to focus on a specific subset
+        - optimize column selection: use `columns_subset=` to include only the columns necessary
+        for validation
+        - start with smaller batches: begin with `batch_size=100` for testing, then increase
+        gradually
+        - reduce concurrency: lower `max_concurrent=1` if hitting rate limits
+        - use faster/cheaper models: consider using smaller or more efficient models for initial
+        testing before switching to more capable models
+
+        Examples
+        --------
+        ```{python}
+        #| echo: false
+        #| output: false
+        import pointblank as pb
+        pb.config(report_incl_header=False, report_incl_footer=False, preview_incl_header=False)
+        ```
+        The following examples demonstrate how to use AI validation for different types of data
+        quality checks. These examples show both basic usage and more advanced configurations with
+        custom thresholds and actions.
+
+        **Basic AI validation example:**
+
+        This first example shows a simple validation scenario where we want to check that customer
+        records have both valid email addresses and non-empty names. Notice how we use
+        `columns_subset=` to focus only on the relevant columns, which improves both performance
+        and cost-effectiveness.
+
+        ```python
+        import pointblank as pb
+        import polars as pl
+
+        # Sample data with email and name columns
+        tbl = pl.DataFrame({
+            "email": ["john@example.com", "invalid-email", "jane@test.org"],
+            "name": ["John Doe", "", "Jane Smith"],
+            "age": [25, 30, 35]
+        })
+
+        # Validate using AI
+        validation = (
+            pb.Validate(data=tbl)
+            .prompt(
+                prompt="Each row should have a valid email address and a non-empty name",
+                columns_subset=["email", "name"],  # Only check these columns
+                model="openai:gpt-4o-mini",
+            )
+            .interrogate()
+        )
+
+        validation
+        ```
+
+        In this example, the AI will identify that the second row fails validation because it has
+        an invalid email format (`"invalid-email"`) and the third row also fails because it has an
+        empty name field. The validation results will show 2 out of 3 rows failing the criteria.
+
+        **Advanced example with custom thresholds:**
+
+        This more sophisticated example demonstrates how to use AI validation with custom thresholds
+        and actions. Here we're validating phone number formats to ensure they include area codes,
+        which is a common data quality requirement for customer contact information.
+
+        ```python
+        customer_data = pl.DataFrame({
+            "customer_id": [1, 2, 3, 4, 5],
+            "name": ["John Doe", "Jane Smith", "Bob Johnson", "Alice Brown", "Charlie Davis"],
+            "phone_number": [
+                "(555) 123-4567",  # Valid with area code
+                "555-987-6543",    # Valid with area code
+                "123-4567",        # Missing area code
+                "(800) 555-1234",  # Valid with area code
+                "987-6543"         # Missing area code
+            ]
+        })
+
+        validation = (
+            pb.Validate(data=customer_data)
+            .prompt(
+                prompt="Do all the phone numbers include an area code?",
+                columns_subset="phone_number",  # Only check the `phone_number` column
+                model="openai:gpt-4o",
+                batch_size=500,
+                max_concurrent=5,
+                thresholds=pb.Thresholds(warning=0.1, error=0.2, critical=0.3),
+                actions=pb.Actions(error="Too many phone numbers missing area codes.")
+            )
+            .interrogate()
+        )
+        ```
+
+        This validation will identify that 2 out of 5 phone numbers (40%) are missing area codes,
+        which exceeds all threshold levels. The validation will trigger the specified error action
+        since the failure rate (40%) is above the error threshold (20%). The AI can recognize
+        various phone number formats and determine whether they include area codes.
+        """
+
+        assertion_type = _get_fn_name()
+
+        # Validation of inputs
+        if not isinstance(prompt, str) or not prompt.strip():
+            raise ValueError("prompt must be a non-empty string")
+
+        # Parse the provider and model name from the `model=` argument
+        try:
+            provider, model_name = model.split(sep=":", maxsplit=1)
+        except ValueError:
+            raise ValueError(f"Model must be in format 'provider:model_name', got: {model}")
+
+        # Error if an unsupported provider is used
+        if provider not in MODEL_PROVIDERS:
+            raise ValueError(
+                f"Unsupported provider: {provider}. Supported providers are {MODEL_PROVIDERS}."
+            )
+
+        # Ensure that `batch_size` and `max_concurrent` are positive integers
+        if not isinstance(batch_size, int) or batch_size < 1:
+            raise ValueError("batch_size must be a positive integer")
+        if not isinstance(max_concurrent, int) or max_concurrent < 1:
+            raise ValueError("max_concurrent must be a positive integer")
+
+        _check_pre(pre=pre)
+        _check_thresholds(thresholds=thresholds)
+        _check_boolean_input(param=active, param_name="active")
+
+        # Promote a single column given as a string to a list
+        if columns_subset is not None and isinstance(columns_subset, str):
+            columns_subset = [columns_subset]
+
+        # Determine threshold to use (global or local) and normalize a local `thresholds=` value
+        thresholds = (
+            self.thresholds if thresholds is None else _normalize_thresholds_creation(thresholds)
+        )
+
+        # Determine brief to use (global or local) and transform any shorthands of `brief=`
+        brief = self.brief if brief is None else _transform_auto_brief(brief=brief)
+
+        # Package up the AI-specific parameters as a dictionary for later use
+        ai_config = {
+            "prompt": prompt,
+            "llm_provider": provider,
+            "llm_model": model_name,
+            "batch_size": batch_size,
+            "max_concurrent": max_concurrent,
+        }
+
+        val_info = _ValidationInfo(
+            assertion_type=assertion_type,
+            column=columns_subset,
+            values=ai_config,
+            pre=pre,
+            segments=segments,
+            thresholds=thresholds,
+            actions=actions,
+            brief=brief,
+            active=active,
+        )
+
+        self._add_validation(validation_info=val_info)
+
+        return self
+
     def col_schema_match(
         self,
         schema: Schema,
@@ -9205,13 +10519,17 @@ class Validate:
         We can also use preprocessing to filter the data before applying the conjoint validation:
 
         ```{python}
+        # Define preprocessing function for serialization compatibility
+        def filter_by_c_gt_5(df):
+            return df.filter(pl.col("c") > 5)
+
         validation = (
             pb.Validate(data=tbl)
             .conjointly(
                 lambda df: pl.col("a") > 2,
                 lambda df: pl.col("b") < 7,
                 lambda df: pl.col("a") + pl.col("b") < pl.col("c"),
-                pre=lambda df: df.filter(pl.col("c") > 5)
+                pre=filter_by_c_gt_5
             )
             .interrogate()
         )
@@ -9838,8 +11156,9 @@ class Validate:
                 validation.active = False
                 continue
 
-            # Make a copy of the table for this step
-            data_tbl_step = data_tbl
+            # Make a deep copy of the table for this step to ensure proper isolation
+            # This prevents modifications from one validation step affecting others
+            data_tbl_step = _copy_dataframe(data_tbl)
 
             # ------------------------------------------------
             # Preprocessing stage
@@ -9919,6 +11238,26 @@ class Validate:
                 tbl_type=tbl_type
             )
 
+            # Check if preprocessing or segmentation resulted in zero rows
+            # Only apply this check to row-based validations, not table-level validations
+            # (table-level validations like row_count_match(), col_count_match(), etc.,
+            # operate on the table as a whole, so zero rows is a valid input)
+            table_level_assertions = [
+                "col_exists",
+                "col_schema_match",
+                "row_count_match",
+                "col_count_match",
+            ]
+
+            if validation.n == 0 and assertion_type not in table_level_assertions:
+                # Mark the validation as having an eval_error
+                validation.eval_error = True
+                end_time = datetime.datetime.now(datetime.timezone.utc)
+                validation.proc_duration_s = (end_time - start_time).total_seconds()
+                validation.time_processed = end_time.isoformat(timespec="milliseconds")
+                validation.active = False
+                continue
+
             # ------------------------------------------------
             # Validation stage
             # ------------------------------------------------
@@ -10006,7 +11345,7 @@ class Validate:
 
                         elif assertion_type == "col_vals_regex":
                             results_tbl = interrogate_regex(
-                                tbl=tbl, column=column, pattern=value, na_pass=na_pass
+                                tbl=tbl, column=column, values=value, na_pass=na_pass
                             )
 
                     elif assertion_type == "col_vals_expr":
@@ -10022,6 +11361,13 @@ class Validate:
                     elif assertion_type == "rows_complete":
                         results_tbl = rows_complete(data_tbl=data_tbl_step, columns_subset=column)
 
+                    elif assertion_type == "prompt":
+                        from pointblank._interrogation import interrogate_prompt
+
+                        results_tbl = interrogate_prompt(
+                            tbl=data_tbl_step, columns_subset=column, ai_config=value
+                        )
+
                     elif assertion_type == "col_exists":
                         result_bool = col_exists(
                             data_tbl=data_tbl_step,
@@ -10354,7 +11700,7 @@ class Validate:
                     # Try without order_by first (for DataFrames)
                     validation_extract_nw = validation_extract_nw.with_row_index(name="_row_num_")
                 except TypeError:
-                    # LazyFrames require order_by parameter - use first column for ordering
+                    # LazyFrames require order_by parameter: use first column for ordering
                     first_col = validation_extract_nw.columns[0]
                     validation_extract_nw = validation_extract_nw.with_row_index(
                         name="_row_num_", order_by=first_col
@@ -10953,11 +12299,15 @@ class Validate:
             }
         )
 
+        # Define a preprocessing function
+        def filter_by_a_gt_1(df):
+            return df.filter(pl.col("a") > 1)
+
         validation = (
             pb.Validate(data=tbl)
             .col_vals_gt(columns="a", value=0)
             .col_exists(columns="b")
-            .col_vals_lt(columns="b", value=9, pre=lambda df: df.filter(pl.col("a") > 1))
+            .col_vals_lt(columns="b", value=9, pre=filter_by_a_gt_1)
             .interrogate()
         )
         ```
@@ -12094,7 +13444,7 @@ class Validate:
             # Try without order_by first (for DataFrames)
             data_nw = data_nw.with_row_index(name=index_name)
         except TypeError:  # pragma: no cover
-            # LazyFrames require order_by parameter - use first column for ordering
+            # LazyFrames require order_by parameter: use first column for ordering
             first_col = data_nw.columns[0]  # pragma: no cover
             data_nw = data_nw.with_row_index(
                 name=index_name, order_by=first_col
@@ -12111,7 +13461,7 @@ class Validate:
                 # Try without order_by first (for DataFrames)
                 results_tbl = results_tbl.with_row_index(name=index_name)
             except TypeError:  # pragma: no cover
-                # LazyFrames require order_by parameter - use first column for ordering
+                # LazyFrames require order_by parameter: use first column for ordering
                 first_col = results_tbl.columns[0]  # pragma: no cover
                 results_tbl = results_tbl.with_row_index(
                     name=index_name, order_by=first_col
@@ -12484,7 +13834,7 @@ class Validate:
                 "col_vals_expr",
             ]:
                 columns_upd.append("&mdash;")
-            elif assertion_type[i] in ["rows_distinct", "rows_complete"]:
+            elif assertion_type[i] in ["rows_distinct", "rows_complete", "prompt"]:
                 if not column:
                     # If there is no column subset, then all columns are used
                     columns_upd.append("ALL COLUMNS")
@@ -12569,9 +13919,21 @@ class Validate:
             elif assertion_type[i] in ["specially"]:
                 values_upd.append("EXPR")
 
+            elif assertion_type[i] in ["col_vals_regex"]:
+                pattern = value["pattern"]
+
+                values_upd.append(str(pattern))
+
+            elif assertion_type[i] in ["prompt"]:  # pragma: no cover
+                # For AI validation, show only the prompt, not the full config
+                if isinstance(value, dict) and "prompt" in value:  # pragma: no cover
+                    values_upd.append(value["prompt"])  # pragma: no cover
+                else:  # pragma: no cover
+                    values_upd.append(str(value))  # pragma: no cover
+
             # If the assertion type is not recognized, add the value as a string
-            else:
-                values_upd.append(str(value))
+            else:  # pragma: no cover
+                values_upd.append(str(value))  # pragma: no cover
 
         # Remove the `inclusive` entry from the dictionary
         validation_info_dict.pop("inclusive")
@@ -14110,6 +15472,15 @@ def _create_autobrief_or_failure_text(
     if assertion_type == "specially":
         return _create_text_specially(lang=lang, for_failure=for_failure)
 
+    if assertion_type == "prompt":
+        return _create_text_prompt(
+            lang=lang,
+            prompt=values["prompt"]
+            if isinstance(values, dict) and "prompt" in values
+            else str(values),
+            for_failure=for_failure,
+        )
+
     return None  # pragma: no cover
 
 
@@ -14218,15 +15589,30 @@ def _create_text_null(
 
 
 def _create_text_regex(
-    lang: str, column: str | None, pattern: str, for_failure: bool = False
+    lang: str, column: str | None, pattern: str | dict, for_failure: bool = False
 ) -> str:
     type_ = _expect_failure_type(for_failure=for_failure)
 
     column_text = _prep_column_text(column=column)
 
-    return EXPECT_FAIL_TEXT[f"regex_{type_}_text"][lang].format(
+    # Handle case where pattern is a dictionary containing `pattern` and `inverse`
+    if isinstance(pattern, dict):
+        pattern_str = pattern["pattern"]
+        inverse = pattern.get("inverse", False)
+    else:  # pragma: no cover
+        # For backward compatibility, assume it's just the pattern string
+        pattern_str = pattern  # pragma: no cover
+        inverse = False  # pragma: no cover
+
+    # Use inverse-specific translations if inverse=True
+    if inverse:
+        text_key = f"regex_inverse_{type_}_text"
+    else:
+        text_key = f"regex_{type_}_text"
+
+    return EXPECT_FAIL_TEXT[text_key][lang].format(
         column_text=column_text,
-        values_text=pattern,
+        values_text=pattern_str,
     )
 
 
@@ -14314,6 +15700,11 @@ def _create_text_specially(lang: str, for_failure: bool = False) -> str:
     return EXPECT_FAIL_TEXT[f"specially_{type_}_text"][lang]
 
 
+def _create_text_prompt(lang: str, prompt: str, for_failure: bool = False) -> str:
+    """Create text for prompt validation: just return the prompt."""
+    return prompt
+
+
 def _prep_column_text(column: str | list[str]) -> str:
     if isinstance(column, list):
         return "`" + str(column[0]) + "`"
@@ -15379,7 +16770,8 @@ def _step_report_row_based(
         elements = ", ".join(values)
         text = f"{column} &NotElement; {{{elements}}}"
     elif assertion_type == "col_vals_regex":
-        text = STEP_REPORT_TEXT["column_matches_regex"][lang].format(column=column, values=values)
+        pattern = values["pattern"]
+        text = STEP_REPORT_TEXT["column_matches_regex"][lang].format(column=column, values=pattern)
     elif assertion_type == "col_vals_null":
         text = STEP_REPORT_TEXT["column_is_null"][lang].format(column=column)
     elif assertion_type == "col_vals_not_null":