snowflake-ml-python 1.16.0__py3-none-any.whl → 1.18.0__py3-none-any.whl

snowflake/ml/feature_store/feature_store.py

@@ -1199,10 +1199,10 @@ class FeatureStore:
         """Get refresh history for online feature table."""
         online_table_name = FeatureView._get_online_table_name(feature_view.name, feature_view.version)
         select_cols = "*" if verbose else "name, state, refresh_start_time, refresh_end_time, refresh_action"
-        prefix = (
-            f"{self._config.database.resolved()}."
-            f"{self._config.schema.resolved()}."
-            f"{online_table_name.resolved()}"
+        name = (
+            f"{self._config.database.identifier()}."
+            f"{self._config.schema.identifier()}."
+            f"{online_table_name.identifier()}"
         )
         return self._session.sql(
             f"""
@@ -1210,9 +1210,8 @@ class FeatureStore:
                 {select_cols}
             FROM TABLE (
                 {self._config.database}.INFORMATION_SCHEMA.ONLINE_FEATURE_TABLE_REFRESH_HISTORY (
-                    NAME_PREFIX => '{prefix}'
+                    NAME => '{name}'
                 )
-
             )
             """
         )
@@ -1591,6 +1590,7 @@ class FeatureStore:
         spine_timestamp_col: Optional[str] = None,
         exclude_columns: Optional[list[str]] = None,
         include_feature_view_timestamp_col: bool = False,
+        join_method: Literal["sequential", "cte"] = "sequential",
     ) -> DataFrame:
         """
         Enrich spine dataframe with feature values. Mainly used to generate inference data input.
@@ -1604,6 +1604,8 @@ class FeatureStore:
             exclude_columns: Column names to exclude from the result dataframe.
             include_feature_view_timestamp_col: Generated dataset will include timestamp column of feature view
                 (if feature view has timestamp column) if set true. Default to false.
+            join_method: Method for feature joins. "sequential" for layer-by-layer joins (default),
+                "cte" for CTE method. (Internal use only - subject to change)
 
         Returns:
             Snowpark DataFrame containing the joined results.
@@ -1641,6 +1643,7 @@ class FeatureStore:
             cast(list[Union[FeatureView, FeatureViewSlice]], features),
             spine_timestamp_col,
             include_feature_view_timestamp_col,
+            join_method,
         )
 
         if exclude_columns is not None:
@@ -1659,6 +1662,7 @@ class FeatureStore:
         spine_label_cols: Optional[list[str]] = None,
         exclude_columns: Optional[list[str]] = None,
         include_feature_view_timestamp_col: bool = False,
+        join_method: Literal["sequential", "cte"] = "sequential",
     ) -> DataFrame:
         """
         Generate a training set from the specified Spine DataFrame and Feature Views. Result is
@@ -1676,6 +1680,8 @@ class FeatureStore:
             exclude_columns: Name of column(s) to exclude from the resulting training set.
             include_feature_view_timestamp_col: Generated dataset will include timestamp column of feature view
                 (if feature view has timestamp column) if set true. Default to false.
+            join_method: Method for feature joins. "sequential" for layer-by-layer joins (default),
+                "cte" for CTE method. (Internal use only - subject to change)
 
         Returns:
             Returns a Snowpark DataFrame representing the training set.
@@ -1709,7 +1715,7 @@ class FeatureStore:
             spine_label_cols = to_sql_identifiers(spine_label_cols)  # type: ignore[assignment]
 
         result_df, join_keys = self._join_features(
-            spine_df, features, spine_timestamp_col, include_feature_view_timestamp_col
+            spine_df, features, spine_timestamp_col, include_feature_view_timestamp_col, join_method
         )
 
         if exclude_columns is not None:
@@ -1757,6 +1763,7 @@ class FeatureStore:
         include_feature_view_timestamp_col: bool = False,
         desc: str = "",
         output_type: Literal["dataset"] = "dataset",
+        join_method: Literal["sequential", "cte"] = "sequential",
     ) -> dataset.Dataset:
         ...
 
@@ -1774,6 +1781,7 @@ class FeatureStore:
         exclude_columns: Optional[list[str]] = None,
         include_feature_view_timestamp_col: bool = False,
         desc: str = "",
+        join_method: Literal["sequential", "cte"] = "sequential",
     ) -> DataFrame:
         ...
 
@@ -1791,6 +1799,7 @@ class FeatureStore:
         include_feature_view_timestamp_col: bool = False,
         desc: str = "",
         output_type: Literal["dataset", "table"] = "dataset",
+        join_method: Literal["sequential", "cte"] = "sequential",
     ) -> Union[dataset.Dataset, DataFrame]:
         """
         Generate dataset by given source table and feature views.
@@ -1811,6 +1820,8 @@ class FeatureStore:
                 (if feature view has timestamp column) if set true. Default to false.
             desc: A description about this dataset.
             output_type: (Deprecated) The type of Snowflake storage to use for the generated training data.
+            join_method: Method for feature joins. "sequential" for layer-by-layer joins (default),
+                "cte" for CTE method. (Internal use only - subject to change)
 
         Returns:
             If output_type is "dataset" (default), returns a Dataset object.
@@ -1874,6 +1885,7 @@ class FeatureStore:
             exclude_columns=exclude_columns,
             include_feature_view_timestamp_col=include_feature_view_timestamp_col,
             save_as=table_name,
+            join_method=join_method,
         )
         if output_type == "table":
             warnings.warn(
@@ -2596,91 +2608,254 @@ class FeatureStore:
         found_rows = self._find_object("TAGS", full_entity_tag_name)
         return len(found_rows) == 1
 
+    def _build_cte_query(
+        self,
+        feature_views: list[FeatureView],
+        feature_columns: list[str],
+        spine_ref: str,
+        spine_timestamp_col: Optional[SqlIdentifier],
+        include_feature_view_timestamp_col: bool = False,
+    ) -> str:
+        """
+        Build a CTE query with the spine query and the feature views.
+
+        This method supports feature views with different join keys by:
+        1. Creating a spine CTE that includes all possible join keys
+        2. Performing ASOF JOINs for each feature view using only its specific join keys when timestamp columns exist
+        3. Performing LEFT JOINs for each feature view when timestamp columns are missing
+        4. Combining results using INNER JOINs on each feature view's specific join keys
+
+        Args:
+            feature_views: A list of feature views to join.
+            feature_columns: A list of feature column strings for each feature view.
+            spine_ref: The spine query.
+            spine_timestamp_col: The timestamp column from spine. Can be None if spine has no timestamp column.
+            include_feature_view_timestamp_col: Whether to include the timestamp column of
+                the feature view in the result. Default to false.
+
+        Note: This method does NOT work when there are duplicate combinations of join keys and timestamp columns
+        in spine.
+
+        Returns:
+            A SQL query string with CTE structure for joining feature views.
+        """
+        if not feature_views:
+            return f"SELECT * FROM ({spine_ref})"
+
+        # Create spine CTE with the spine query for reuse
+        spine_cte = f"""SPINE AS (
+            SELECT * FROM ({spine_ref})
+        )"""
+
+        ctes = [spine_cte]
+        cte_names = []
+        for i, feature_view in enumerate(feature_views):
+            cte_name = f"FV{i:03d}"
+            cte_names.append(cte_name)
+
+            feature_timestamp_col = feature_view.timestamp_col
+
+            # Get the specific join keys for this feature view
+            fv_join_keys = list({k for e in feature_view.entities for k in e.join_keys})
+            join_keys_str = ", ".join(fv_join_keys)
+
+            # Build the JOIN condition using only this feature view's join keys
+            join_conditions = [f'SPINE."{col}" = FEATURE."{col}"' for col in fv_join_keys]
+
+            # Use ASOF JOIN if both spine and feature view have timestamp columns, otherwise use LEFT JOIN
+            if spine_timestamp_col is not None and feature_timestamp_col is not None:
+                if include_feature_view_timestamp_col:
+                    f_ts_col_alias = identifier.concat_names(
+                        [feature_view.name, "_", str(feature_view.version), "_", feature_timestamp_col]
+                    )
+                    f_ts_col_str = f"FEATURE.{feature_timestamp_col} AS {f_ts_col_alias},"
+                else:
+                    f_ts_col_str = ""
+                ctes.append(
+                    f"""{cte_name} AS (
+    SELECT
+        SPINE.*,
+        {f_ts_col_str}
+        FEATURE.* EXCLUDE ({join_keys_str}, {feature_timestamp_col})
+    FROM
+        SPINE
+    ASOF JOIN (
+        SELECT {join_keys_str}, {feature_timestamp_col}, {feature_columns[i]}
+        FROM {feature_view.fully_qualified_name()}
+    ) FEATURE
+    MATCH_CONDITION (SPINE."{spine_timestamp_col}" >= FEATURE."{feature_timestamp_col}")
+    ON {" AND ".join(join_conditions)}
+)"""
+                )
+            else:
+                ctes.append(
+                    f"""{cte_name} AS (
+    SELECT
+        SPINE.*,
+        FEATURE.* EXCLUDE ({join_keys_str})
+    FROM
+        SPINE
+    LEFT JOIN (
+        SELECT {join_keys_str}, {feature_columns[i]}
+        FROM {feature_view.fully_qualified_name()}
+    ) FEATURE
+    ON {" AND ".join(join_conditions)}
+)"""
+                )
+
+        # Build final SELECT with individual joins to each FV CTE
+        select_columns = []
+        join_clauses = []
+
+        for i, cte_name in enumerate(cte_names):
+            feature_view = feature_views[i]
+            fv_join_keys = list({k for e in feature_view.entities for k in e.join_keys})
+            join_conditions = [f'SPINE."{col}" = {cte_name}."{col}"' for col in fv_join_keys]
+            if spine_timestamp_col is not None:
+                join_conditions.append(f'SPINE."{spine_timestamp_col}" = {cte_name}."{spine_timestamp_col}"')
+            if include_feature_view_timestamp_col and feature_view.timestamp_col is not None:
+                f_ts_col_alias = identifier.concat_names(
+                    [feature_view.name, "_", str(feature_view.version), "_", feature_view.timestamp_col]
+                )
+                f_ts_col_str = f"{cte_name}.{f_ts_col_alias} AS {f_ts_col_alias}"
+                select_columns.append(f_ts_col_str)
+            select_columns.append(feature_columns[i])
+            # Create join condition using only this feature view's join keys
+            join_clauses.append(
+                f"""
+    INNER JOIN {cte_name}
+    ON {" AND ".join(join_conditions)}"""
+            )
+
+        query = f"""WITH
+{', '.join(ctes)}
+SELECT
+    SPINE.*,
+    {', '.join(select_columns)}
+FROM SPINE{' '.join(join_clauses)}
+"""
+
+        return query
+
     def _join_features(
         self,
         spine_df: DataFrame,
         features: list[Union[FeatureView, FeatureViewSlice]],
         spine_timestamp_col: Optional[SqlIdentifier],
         include_feature_view_timestamp_col: bool,
+        join_method: Literal["sequential", "cte"] = "sequential",
     ) -> tuple[DataFrame, list[SqlIdentifier]]:
-        for f in features:
-            f = f.feature_view_ref if isinstance(f, FeatureViewSlice) else f
-            if f.status == FeatureViewStatus.DRAFT:
+        # Validate join_method parameter
+        if join_method not in ["sequential", "cte"]:
+            raise ValueError(f"Invalid join_method '{join_method}'. Must be 'sequential' or 'cte'.")
+
+        feature_views: list[FeatureView] = []
+        # Extract column selections for each feature view
+        feature_columns: list[str] = []
+        for feature in features:
+            fv = feature.feature_view_ref if isinstance(feature, FeatureViewSlice) else feature
+            if fv.status == FeatureViewStatus.DRAFT:
                 raise snowml_exceptions.SnowflakeMLException(
                     error_code=error_codes.NOT_FOUND,
-                    original_exception=ValueError(f"FeatureView {f.name} has not been registered."),
+                    original_exception=ValueError(f"FeatureView {fv.name} has not been registered."),
                 )
-            for e in f.entities:
+            for e in fv.entities:
                 for k in e.join_keys:
                     if k not in to_sql_identifiers(spine_df.columns):
                         raise snowml_exceptions.SnowflakeMLException(
                             error_code=error_codes.INVALID_ARGUMENT,
                             original_exception=ValueError(
-                                f"join_key {k} from Entity {e.name} in FeatureView {f.name} is not found in spine_df."
+                                f"join_key {k} from Entity {e.name} in FeatureView {fv.name} "
+                                "is not found in spine_df."
                             ),
                         )
-
+            feature_views.append(fv)
+            if isinstance(feature, FeatureViewSlice):
+                cols = feature.names
+            else:
+                cols = feature.feature_names
+            feature_columns.append(", ".join(col.resolved() for col in cols))
+        # TODO (SNOW-2396184): remove this check and the non-ASOF join path as ASOF join is enabled by default now.
         if self._asof_join_enabled is None:
             self._asof_join_enabled = self._is_asof_join_enabled()
 
         # TODO: leverage Snowpark dataframe for more concise syntax once it supports AsOfJoin
         query = spine_df.queries["queries"][-1]
-        layer = 0
-        for f in features:
-            if isinstance(f, FeatureViewSlice):
-                cols = f.names
-                f = f.feature_view_ref
-            else:
-                cols = f.feature_names
-
-            join_keys = list({k for e in f.entities for k in e.join_keys})
-            join_keys_str = ", ".join(join_keys)
-            assert f.version is not None
-            join_table_name = f.fully_qualified_name()
-
-            if spine_timestamp_col is not None and f.timestamp_col is not None:
-                if self._asof_join_enabled:
-                    if include_feature_view_timestamp_col:
-                        f_ts_col_alias = identifier.concat_names([f.name, "_", f.version, "_", f.timestamp_col])
-                        f_ts_col_str = f"r_{layer}.{f.timestamp_col} AS {f_ts_col_alias},"
+        join_keys: list[SqlIdentifier] = []
+
+        if join_method == "cte":
+
+            logger.info(f"Using the CTE method with {len(features)} feature views")
+
+            query = self._build_cte_query(
+                feature_views,
+                feature_columns,
+                spine_df.queries["queries"][-1],
+                spine_timestamp_col,
+                include_feature_view_timestamp_col,
+            )
+        else:
+            # Use sequential joins layer by layer
+            logger.info(f"Using the sequential join method with {len(features)} feature views")
+            layer = 0
+            for feature in features:
+                if isinstance(feature, FeatureViewSlice):
+                    cols = feature.names
+                    feature = feature.feature_view_ref
+                else:
+                    cols = feature.feature_names
+
+                join_keys = list({k for e in feature.entities for k in e.join_keys})
+                join_keys_str = ", ".join(join_keys)
+                assert feature.version is not None
+                join_table_name = feature.fully_qualified_name()
+
+                if spine_timestamp_col is not None and feature.timestamp_col is not None:
+                    if self._asof_join_enabled:
+                        if include_feature_view_timestamp_col:
+                            f_ts_col_alias = identifier.concat_names(
+                                [feature.name, "_", feature.version, "_", feature.timestamp_col]
+                            )
+                            f_ts_col_str = f"r_{layer}.{feature.timestamp_col} AS {f_ts_col_alias},"
+                        else:
+                            f_ts_col_str = ""
+                        query = f"""
+                            SELECT
+                                l_{layer}.*,
+                                {f_ts_col_str}
+                                r_{layer}.* EXCLUDE ({join_keys_str}, {feature.timestamp_col})
+                            FROM ({query}) l_{layer}
+                            ASOF JOIN (
+                                SELECT {join_keys_str}, {feature.timestamp_col},
+                                    {', '.join(col.resolved() for col in cols)}
+                                FROM {join_table_name}
+                            ) r_{layer}
+                            MATCH_CONDITION (l_{layer}.{spine_timestamp_col} >= r_{layer}.{feature.timestamp_col})
+                            ON {' AND '.join([f'l_{layer}.{k} = r_{layer}.{k}' for k in join_keys])}
+                        """
                     else:
-                        f_ts_col_str = ""
+                        query = self._composed_union_window_join_query(
+                            layer=layer,
+                            s_query=query,
+                            s_ts_col=spine_timestamp_col,
+                            f_df=feature.feature_df,
+                            f_table_name=join_table_name,
+                            f_ts_col=feature.timestamp_col,
+                            join_keys=join_keys,
+                        )
+                else:
                     query = f"""
                         SELECT
                             l_{layer}.*,
-                            {f_ts_col_str}
-                            r_{layer}.* EXCLUDE ({join_keys_str}, {f.timestamp_col})
+                            r_{layer}.* EXCLUDE ({join_keys_str})
                         FROM ({query}) l_{layer}
-                        ASOF JOIN (
-                            SELECT {join_keys_str}, {f.timestamp_col}, {', '.join(cols)}
+                        LEFT JOIN (
+                            SELECT {join_keys_str}, {', '.join(col.resolved() for col in cols)}
                             FROM {join_table_name}
                         ) r_{layer}
-                        MATCH_CONDITION (l_{layer}.{spine_timestamp_col} >= r_{layer}.{f.timestamp_col})
                         ON {' AND '.join([f'l_{layer}.{k} = r_{layer}.{k}' for k in join_keys])}
                     """
-                else:
-                    query = self._composed_union_window_join_query(
-                        layer=layer,
-                        s_query=query,
-                        s_ts_col=spine_timestamp_col,
-                        f_df=f.feature_df,
-                        f_table_name=join_table_name,
-                        f_ts_col=f.timestamp_col,
-                        join_keys=join_keys,
-                    )
-            else:
-                query = f"""
-                    SELECT
-                        l_{layer}.*,
-                        r_{layer}.* EXCLUDE ({join_keys_str})
-                    FROM ({query}) l_{layer}
-                    LEFT JOIN (
-                        SELECT {join_keys_str}, {', '.join(cols)}
-                        FROM {join_table_name}
-                    ) r_{layer}
-                    ON {' AND '.join([f'l_{layer}.{k} = r_{layer}.{k}' for k in join_keys])}
-                """
-            layer += 1
+                layer += 1
 
         # TODO: construct result dataframe with datframe APIs once ASOF join is supported natively.
         # Below code manually construct result dataframe from private members of spine dataframe, which

snowflake/ml/jobs/__init__.py

@@ -1,3 +1,4 @@
+from snowflake.ml.jobs._interop.exception_utils import install_exception_display_hooks
 from snowflake.ml.jobs._utils.types import JOB_STATUS
 from snowflake.ml.jobs.decorators import remote
 from snowflake.ml.jobs.job import MLJob
@@ -10,6 +11,9 @@ from snowflake.ml.jobs.manager import (
     submit_from_stage,
 )
 
+# Initialize exception display hooks for remote job error handling
+install_exception_display_hooks()
+
 __all__ = [
     "remote",
     "submit_file",

snowflake/ml/jobs/_interop/data_utils.py

@@ -0,0 +1,124 @@
+import io
+import json
+from typing import Any, Literal, Optional, Protocol, Union, cast, overload
+
+from snowflake import snowpark
+from snowflake.ml.jobs._interop import dto_schema
+
+
+class StageFileWriter(io.IOBase):
+    """
+    A context manager IOBase implementation that proxies writes to an internal BytesIO
+    and uploads to Snowflake stage on close.
+    """
+
+    def __init__(self, session: snowpark.Session, path: str) -> None:
+        self._session = session
+        self._path = path
+        self._buffer = io.BytesIO()
+        self._closed = False
+        self._exception_occurred = False
+
+    def write(self, data: Union[bytes, bytearray]) -> int:
+        """Write data to the internal buffer."""
+        if self._closed:
+            raise ValueError("I/O operation on closed file")
+        return self._buffer.write(data)
+
+    def close(self, write_contents: bool = True) -> None:
+        """Close the file and upload the buffer contents to the stage."""
+        if not self._closed:
+            # Only upload if buffer has content and no exception occurred
+            if write_contents and self._buffer.tell() > 0:
+                self._buffer.seek(0)
+                self._session.file.put_stream(self._buffer, self._path)
+            self._buffer.close()
+            self._closed = True
+
+    def __enter__(self) -> "StageFileWriter":
+        return self
+
+    def __exit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
+        exception_occurred = exc_type is not None
+        self.close(write_contents=not exception_occurred)
+
+    @property
+    def closed(self) -> bool:
+        return self._closed
+
+    def writable(self) -> bool:
+        return not self._closed
+
+    def readable(self) -> bool:
+        return False
+
+    def seekable(self) -> bool:
+        return not self._closed
+
+
+def _is_stage_path(path: str) -> bool:
+    return path.startswith("@") or path.startswith("snow://")
+
+
+def open_stream(path: str, mode: str = "rb", session: Optional[snowpark.Session] = None) -> io.IOBase:
+    if _is_stage_path(path):
+        if session is None:
+            raise ValueError("Session is required when opening a stage path")
+        if "r" in mode:
+            stream: io.IOBase = session.file.get_stream(path)  # type: ignore[assignment]
+            return stream
+        elif "w" in mode:
+            return StageFileWriter(session, path)
+        else:
+            raise ValueError(f"Unsupported mode '{mode}' for stage path")
+    else:
+        result: io.IOBase = open(path, mode)  # type: ignore[assignment]
+        return result
+
+
+class DtoCodec(Protocol):
+    @overload
+    @staticmethod
+    def decode(stream: io.IOBase, as_dict: Literal[True]) -> dict[str, Any]:
+        ...
+
+    @overload
+    @staticmethod
+    def decode(stream: io.IOBase, as_dict: Literal[False] = False) -> dto_schema.ResultDTO:
+        ...
+
+    @staticmethod
+    def decode(stream: io.IOBase, as_dict: bool = False) -> Union[dto_schema.ResultDTO, dict[str, Any]]:
+        pass
+
+    @staticmethod
+    def encode(dto: dto_schema.ResultDTO) -> bytes:
+        pass
+
+
+class JsonDtoCodec(DtoCodec):
+    @overload
+    @staticmethod
+    def decode(stream: io.IOBase, as_dict: Literal[True]) -> dict[str, Any]:
+        ...
+
+    @overload
+    @staticmethod
+    def decode(stream: io.IOBase, as_dict: Literal[False] = False) -> dto_schema.ResultDTO:
+        ...
+
+    @staticmethod
+    def decode(stream: io.IOBase, as_dict: bool = False) -> Union[dto_schema.ResultDTO, dict[str, Any]]:
+        data = cast(dict[str, Any], json.load(stream))
+        if as_dict:
+            return data
+        return dto_schema.ResultDTO.model_validate(data)
+
+    @staticmethod
+    def encode(dto: dto_schema.ResultDTO) -> bytes:
+        # Temporarily extract the value to avoid accidentally applying model_dump() on it
+        result_value = dto.value
+        dto.value = None  # Clear value to avoid serializing it in the model_dump
+        result_dict = dto.model_dump()
+        result_dict["value"] = result_value  # Put back the value
+        return json.dumps(result_dict).encode("utf-8")

snowflake/ml/jobs/_interop/dto_schema.py

@@ -0,0 +1,95 @@
+from typing import Any, Optional, Union
+
+from pydantic import BaseModel, model_validator
+from typing_extensions import NotRequired, TypedDict
+
+
+class BinaryManifest(TypedDict):
+    """
+    Binary data manifest schema.
+    Contains one of: path, bytes, or base64 for the serialized data.
+    """
+
+    path: NotRequired[str]  # Path to file
+    bytes: NotRequired[bytes]  # In-line byte string (not supported with JSON codec)
+    base64: NotRequired[str]  # Base64 encoded string
+
+
+class ParquetManifest(TypedDict):
+    """Protocol manifest schema for parquet files."""
+
+    paths: list[str]  # File paths
+
+
+# Union type for all manifest types, including catch-all dict[str, Any] for backward compatibility
+PayloadManifest = Union[BinaryManifest, ParquetManifest, dict[str, Any]]
+
+
+class ProtocolInfo(BaseModel):
+    """
+    The protocol used to serialize the result and the manifest of the result.
+    """
+
+    name: str
+    version: Optional[str] = None
+    metadata: Optional[dict[str, str]] = None
+    manifest: Optional[PayloadManifest] = None
+
+    def __str__(self) -> str:
+        result = self.name
+        if self.version:
+            result += f"-{self.version}"
+        return result
+
+    def with_manifest(self, manifest: PayloadManifest) -> "ProtocolInfo":
+        """
+        Return a new ProtocolInfo object with the manifest.
+        """
+        return ProtocolInfo(
+            name=self.name,
+            version=self.version,
+            metadata=self.metadata,
+            manifest=manifest,
+        )
+
+
+class ResultMetadata(BaseModel):
+    """
+    The metadata of a result.
+    """
+
+    type: str
+    repr: str
+
+
+class ExceptionMetadata(ResultMetadata):
+    message: str
+    traceback: str
+
+
+class ResultDTO(BaseModel):
+    """
+    A JSON representation of an execution result.
+
+    Args:
+        success: Whether the execution was successful.
+        value: The value of the execution or the exception if the execution failed.
+        protocol: The protocol used to serialize the result.
+        metadata: The metadata of the result.
+    """
+
+    success: bool
+    value: Optional[Any] = None
+    protocol: Optional[ProtocolInfo] = None
+    metadata: Optional[Union[ResultMetadata, ExceptionMetadata]] = None
+    serialize_error: Optional[str] = None
+
+    @model_validator(mode="before")
+    @classmethod
+    def validate_fields(cls, data: Any) -> Any:
+        """Ensure at least one of value, protocol, or metadata keys is specified."""
+        if isinstance(data, dict):
+            required_fields = {"value", "protocol", "metadata"}
+            if not any(field in data for field in required_fields):
+                raise ValueError("At least one of 'value', 'protocol', or 'metadata' must be specified")
+        return data