refactor: introduce ai operator namespace and deprecated semantics (#1511)

* refactor: introduce ai operator namespace and deprecated semantics

* duplicate semantic op options too

* improve test coverage

* relax test condition

* clean up semantics and add public docs

* addressing comments

* use FutureWarning for deprecation

* copy over recent top_k changes

Author: sycai

bigframes/_config/compute_options.py

@@ -60,19 +60,31 @@ class ComputeOptions:
             bytes billed beyond this limit will fail (without incurring a
             charge). If unspecified, this will be set to your project default.
             See `maximum_bytes_billed`: https://cloud.google.com/python/docs/reference/bigquery/latest/google.cloud.bigquery.job.QueryJobConfig#google_cloud_bigquery_job_QueryJobConfig_maximum_bytes_billed.
+
         enable_multi_query_execution (bool, Options):
             If enabled, large queries may be factored into multiple smaller queries
             in order to avoid generating queries that are too complex for the query
             engine to handle. However this comes at the cost of increase cost and latency.
+
         extra_query_labels (Dict[str, Any], Options):
             Stores additional custom labels for query configuration.
-        semmantic_ops_confirmation_threshold (int, optional):
-            Guards against unexepcted processing of large amount of rows by semantic operators.
+
+        semantic_ops_confirmation_threshold (int, optional):
+            .. deprecated:: 1.42.0
+                Semantic operators are deprecated. Please use AI operators instead
+
+        semantic_ops_threshold_autofail (bool):
+            .. deprecated:: 1.42.0
+                Semantic operators are deprecated. Please use AI operators instead
+
+        ai_ops_confirmation_threshold (int, optional):
+            Guards against unexpected processing of large amount of rows by semantic operators.
             If the number of rows exceeds the threshold, the user will be asked to confirm
             their operations to resume. The default value is 0. Set the value to None
             to turn off the guard.
-        semantic_ops_threshold_autofail (bool):
-            Guards against unexepcted processing of large amount of rows by semantic operators.
+
+        ai_ops_threshold_autofail (bool):
+            Guards against unexpected processing of large amount of rows by semantic operators.
             When set to True, the operation automatically fails without asking for user inputs.
     """
 
@@ -84,6 +96,9 @@ class ComputeOptions:
     semantic_ops_confirmation_threshold: Optional[int] = 0
     semantic_ops_threshold_autofail = False
 
+    ai_ops_confirmation_threshold: Optional[int] = 0
+    ai_ops_threshold_autofail = False
+
     def assign_extra_query_labels(self, **kwargs: Any) -> None:
         """
         Assigns additional custom labels for query configuration. The method updates the

bigframes/_config/experiment_options.py

@@ -24,6 +24,7 @@ class ExperimentOptions:
 
     def __init__(self):
         self._semantic_operators: bool = False
+        self._ai_operators: bool = False
         self._blob: bool = False
         self._udf: bool = False
 
@@ -35,11 +36,24 @@ def semantic_operators(self) -> bool:
     def semantic_operators(self, value: bool):
         if value is True:
             msg = bfe.format_message(
-                "Semantic operators are still under experiments, and are subject "
+                "Semantic operators are deprecated, and will be removed in the future"
+            )
+            warnings.warn(msg, category=FutureWarning)
+        self._semantic_operators = value
+
+    @property
+    def ai_operators(self) -> bool:
+        return self._ai_operators
+
+    @ai_operators.setter
+    def ai_operators(self, value: bool):
+        if value is True:
+            msg = bfe.format_message(
+                "AI operators are still under experiments, and are subject "
                 "to change in the future."
             )
             warnings.warn(msg, category=bfe.PreviewWarning)
-        self._semantic_operators = value
+        self._ai_operators = value
 
     @property
     def blob(self) -> bool:

bigframes/dataframe.py

@@ -74,6 +74,7 @@
 import bigframes.operations as ops
 import bigframes.operations.aggregations
 import bigframes.operations.aggregations as agg_ops
+import bigframes.operations.ai
 import bigframes.operations.plotting as plotting
 import bigframes.operations.semantics
 import bigframes.operations.structs
@@ -4574,4 +4575,13 @@ def _throw_if_null_index(self, opname: str):
 
     @property
     def semantics(self):
+        msg = bfe.format_message(
+            "The 'semantics' property will be removed. Please use 'ai' instead."
+        )
+        warnings.warn(msg, category=FutureWarning)
         return bigframes.operations.semantics.Semantics(self)
+
+    @property
+    def ai(self):
+        """Returns the accessor for AI operators."""
+        return bigframes.operations.ai.AIAccessor(self)