feat: Add support for V1 and V2 classification models (#376)

* feat: Add support for V1 and V2 classification models for the V1 API

PiperOrigin-RevId: 475599241

Source-Link: googleapis/googleapis@05b99f9

Source-Link: https://github.com/googleapis/googleapis-gen/commit/3dcdbed8d968f634be0a2d3107237d232ee8b061
Copy-Tag: eyJwIjoiLmdpdGh1Yi8uT3dsQm90LnlhbWwiLCJoIjoiM2RjZGJlZDhkOTY4ZjYzNGJlMGEyZDMxMDcyMzdkMjMyZWU4YjA2MSJ9

* 🦉 Updates from OwlBot post-processor

See https://github.com/googleapis/repo-automation-bots/blob/main/packages/owl-bot/README.md

* feat: Add support for V1 and V2 classification models for the V1Beta2 API

PiperOrigin-RevId: 475604619

Source-Link: googleapis/googleapis@044a15c

Source-Link: https://github.com/googleapis/googleapis-gen/commit/410020af934c7248f7804770d6f8ec4571bfa551
Copy-Tag: eyJwIjoiLmdpdGh1Yi8uT3dsQm90LnlhbWwiLCJoIjoiNDEwMDIwYWY5MzRjNzI0OGY3ODA0NzcwZDZmOGVjNDU3MWJmYTU1MSJ9

* 🦉 Updates from OwlBot post-processor

See https://github.com/googleapis/repo-automation-bots/blob/main/packages/owl-bot/README.md

* docs: fix docstring formatting

Committer: @parthea
PiperOrigin-RevId: 476410563

Source-Link: googleapis/googleapis@7f579ee

Source-Link: https://github.com/googleapis/googleapis-gen/commit/ae0240e097a196c070e15deaae66464b42c8e014
Copy-Tag: eyJwIjoiLmdpdGh1Yi8uT3dsQm90LnlhbWwiLCJoIjoiYWUwMjQwZTA5N2ExOTZjMDcwZTE1ZGVhYWU2NjQ2NGI0MmM4ZTAxNCJ9

* 🦉 Updates from OwlBot post-processor

See https://github.com/googleapis/repo-automation-bots/blob/main/packages/owl-bot/README.md

Co-authored-by: Owl Bot <gcf-owl-bot[bot]@users.noreply.github.com>

google/cloud/language/__init__.py

@@ -32,6 +32,7 @@
     AnnotateTextRequest,
     AnnotateTextResponse,
     ClassificationCategory,
+    ClassificationModelOptions,
     ClassifyTextRequest,
     ClassifyTextResponse,
     DependencyEdge,
@@ -60,6 +61,7 @@
     "AnnotateTextRequest",
     "AnnotateTextResponse",
     "ClassificationCategory",
+    "ClassificationModelOptions",
     "ClassifyTextRequest",
     "ClassifyTextResponse",
     "DependencyEdge",

google/cloud/language_v1/__init__.py

@@ -27,6 +27,7 @@
     AnnotateTextRequest,
     AnnotateTextResponse,
     ClassificationCategory,
+    ClassificationModelOptions,
     ClassifyTextRequest,
     ClassifyTextResponse,
     DependencyEdge,
@@ -54,6 +55,7 @@
     "AnnotateTextRequest",
     "AnnotateTextResponse",
     "ClassificationCategory",
+    "ClassificationModelOptions",
     "ClassifyTextRequest",
     "ClassifyTextResponse",
     "DependencyEdge",

google/cloud/language_v1/services/language_service/async_client.py

@@ -248,7 +248,7 @@ async def sample_analyze_sentiment():
                 The request object. The sentiment analysis request
                 message.
             document (:class:`google.cloud.language_v1.types.Document`):
-                Input document.
+                Required. Input document.
                 This corresponds to the ``document`` field
                 on the ``request`` instance; if ``request`` is provided, this
                 should not be set.
@@ -367,7 +367,7 @@ async def sample_analyze_entities():
             request (Union[google.cloud.language_v1.types.AnalyzeEntitiesRequest, dict]):
                 The request object. The entity analysis request message.
             document (:class:`google.cloud.language_v1.types.Document`):
-                Input document.
+                Required. Input document.
                 This corresponds to the ``document`` field
                 on the ``request`` instance; if ``request`` is provided, this
                 should not be set.
@@ -485,7 +485,7 @@ async def sample_analyze_entity_sentiment():
                 The request object. The entity-level sentiment analysis
                 request message.
             document (:class:`google.cloud.language_v1.types.Document`):
-                Input document.
+                Required. Input document.
                 This corresponds to the ``document`` field
                 on the ``request`` instance; if ``request`` is provided, this
                 should not be set.
@@ -603,7 +603,7 @@ async def sample_analyze_syntax():
             request (Union[google.cloud.language_v1.types.AnalyzeSyntaxRequest, dict]):
                 The request object. The syntax analysis request message.
             document (:class:`google.cloud.language_v1.types.Document`):
-                Input document.
+                Required. Input document.
                 This corresponds to the ``document`` field
                 on the ``request`` instance; if ``request`` is provided, this
                 should not be set.
@@ -717,7 +717,7 @@ async def sample_classify_text():
                 The request object. The document classification request
                 message.
             document (:class:`google.cloud.language_v1.types.Document`):
-                Input document.
+                Required. Input document.
                 This corresponds to the ``document`` field
                 on the ``request`` instance; if ``request`` is provided, this
                 should not be set.
@@ -829,12 +829,12 @@ async def sample_annotate_text():
                 annotation API, which can perform multiple analysis
                 types (sentiment, entities, and syntax) in one call.
             document (:class:`google.cloud.language_v1.types.Document`):
-                Input document.
+                Required. Input document.
                 This corresponds to the ``document`` field
                 on the ``request`` instance; if ``request`` is provided, this
                 should not be set.
             features (:class:`google.cloud.language_v1.types.AnnotateTextRequest.Features`):
-                The enabled features.
+                Required. The enabled features.
                 This corresponds to the ``features`` field
                 on the ``request`` instance; if ``request`` is provided, this
                 should not be set.

google/cloud/language_v1/services/language_service/client.py

@@ -453,7 +453,7 @@ def sample_analyze_sentiment():
                 The request object. The sentiment analysis request
                 message.
             document (google.cloud.language_v1.types.Document):
-                Input document.
+                Required. Input document.
                 This corresponds to the ``document`` field
                 on the ``request`` instance; if ``request`` is provided, this
                 should not be set.
@@ -562,7 +562,7 @@ def sample_analyze_entities():
             request (Union[google.cloud.language_v1.types.AnalyzeEntitiesRequest, dict]):
                 The request object. The entity analysis request message.
             document (google.cloud.language_v1.types.Document):
-                Input document.
+                Required. Input document.
                 This corresponds to the ``document`` field
                 on the ``request`` instance; if ``request`` is provided, this
                 should not be set.
@@ -670,7 +670,7 @@ def sample_analyze_entity_sentiment():
                 The request object. The entity-level sentiment analysis
                 request message.
             document (google.cloud.language_v1.types.Document):
-                Input document.
+                Required. Input document.
                 This corresponds to the ``document`` field
                 on the ``request`` instance; if ``request`` is provided, this
                 should not be set.
@@ -778,7 +778,7 @@ def sample_analyze_syntax():
             request (Union[google.cloud.language_v1.types.AnalyzeSyntaxRequest, dict]):
                 The request object. The syntax analysis request message.
             document (google.cloud.language_v1.types.Document):
-                Input document.
+                Required. Input document.
                 This corresponds to the ``document`` field
                 on the ``request`` instance; if ``request`` is provided, this
                 should not be set.
@@ -882,7 +882,7 @@ def sample_classify_text():
                 The request object. The document classification request
                 message.
             document (google.cloud.language_v1.types.Document):
-                Input document.
+                Required. Input document.
                 This corresponds to the ``document`` field
                 on the ``request`` instance; if ``request`` is provided, this
                 should not be set.
@@ -984,12 +984,12 @@ def sample_annotate_text():
                 annotation API, which can perform multiple analysis
                 types (sentiment, entities, and syntax) in one call.
             document (google.cloud.language_v1.types.Document):
-                Input document.
+                Required. Input document.
                 This corresponds to the ``document`` field
                 on the ``request`` instance; if ``request`` is provided, this
                 should not be set.
             features (google.cloud.language_v1.types.AnnotateTextRequest.Features):
-                The enabled features.
+                Required. The enabled features.
                 This corresponds to the ``features`` field
                 on the ``request`` instance; if ``request`` is provided, this
                 should not be set.

google/cloud/language_v1/types/__init__.py

@@ -25,6 +25,7 @@
     AnnotateTextRequest,
     AnnotateTextResponse,
     ClassificationCategory,
+    ClassificationModelOptions,
     ClassifyTextRequest,
     ClassifyTextResponse,
     DependencyEdge,
@@ -51,6 +52,7 @@
     "AnnotateTextRequest",
     "AnnotateTextResponse",
     "ClassificationCategory",
+    "ClassificationModelOptions",
     "ClassifyTextRequest",
     "ClassifyTextResponse",
     "DependencyEdge",

google/cloud/language_v1/types/language_service.py

@@ -29,6 +29,7 @@
         "EntityMention",
         "TextSpan",
         "ClassificationCategory",
+        "ClassificationModelOptions",
         "AnalyzeSentimentRequest",
         "AnalyzeSentimentResponse",
         "AnalyzeEntitySentimentRequest",
@@ -728,12 +729,76 @@ class ClassificationCategory(proto.Message):
     )
 
 
+class ClassificationModelOptions(proto.Message):
+    r"""Model options available for classification requests.
+
+    This message has `oneof`_ fields (mutually exclusive fields).
+    For each oneof, at most one member field can be set at the same time.
+    Setting any member of the oneof automatically clears all other
+    members.
+
+    .. _oneof: https://proto-plus-python.readthedocs.io/en/stable/fields.html#oneofs-mutually-exclusive-fields
+
+    Attributes:
+        v1_model (google.cloud.language_v1.types.ClassificationModelOptions.V1Model):
+            Setting this field will use the V1 model and
+            V1 content categories version. The V1 model is a
+            legacy model; support for this will be
+            discontinued in the future.
+
+            This field is a member of `oneof`_ ``model_type``.
+        v2_model (google.cloud.language_v1.types.ClassificationModelOptions.V2Model):
+            Setting this field will use the V2 model with
+            the appropriate content categories version. The
+            V2 model is a better performing model.
+
+            This field is a member of `oneof`_ ``model_type``.
+    """
+
+    class V1Model(proto.Message):
+        r"""Options for the V1 model."""
+
+    class V2Model(proto.Message):
+        r"""Options for the V2 model.
+
+        Attributes:
+            content_categories_version (google.cloud.language_v1.types.ClassificationModelOptions.V2Model.ContentCategoriesVersion):
+                The content categories used for
+                classification.
+        """
+
+        class ContentCategoriesVersion(proto.Enum):
+            r"""The content categories used for classification."""
+            CONTENT_CATEGORIES_VERSION_UNSPECIFIED = 0
+            V1 = 1
+            V2 = 2
+
+        content_categories_version = proto.Field(
+            proto.ENUM,
+            number=1,
+            enum="ClassificationModelOptions.V2Model.ContentCategoriesVersion",
+        )
+
+    v1_model = proto.Field(
+        proto.MESSAGE,
+        number=1,
+        oneof="model_type",
+        message=V1Model,
+    )
+    v2_model = proto.Field(
+        proto.MESSAGE,
+        number=2,
+        oneof="model_type",
+        message=V2Model,
+    )
+
+
 class AnalyzeSentimentRequest(proto.Message):
     r"""The sentiment analysis request message.
 
     Attributes:
         document (google.cloud.language_v1.types.Document):
-            Input document.
+            Required. Input document.
         encoding_type (google.cloud.language_v1.types.EncodingType):
             The encoding type used by the API to
             calculate sentence offsets.
@@ -789,7 +854,7 @@ class AnalyzeEntitySentimentRequest(proto.Message):
 
     Attributes:
         document (google.cloud.language_v1.types.Document):
-            Input document.
+            Required. Input document.
         encoding_type (google.cloud.language_v1.types.EncodingType):
             The encoding type used by the API to
             calculate offsets.
@@ -838,7 +903,7 @@ class AnalyzeEntitiesRequest(proto.Message):
 
     Attributes:
         document (google.cloud.language_v1.types.Document):
-            Input document.
+            Required. Input document.
         encoding_type (google.cloud.language_v1.types.EncodingType):
             The encoding type used by the API to
             calculate offsets.
@@ -887,7 +952,7 @@ class AnalyzeSyntaxRequest(proto.Message):
 
     Attributes:
         document (google.cloud.language_v1.types.Document):
-            Input document.
+            Required. Input document.
         encoding_type (google.cloud.language_v1.types.EncodingType):
             The encoding type used by the API to
             calculate offsets.
@@ -943,14 +1008,22 @@ class ClassifyTextRequest(proto.Message):
 
     Attributes:
         document (google.cloud.language_v1.types.Document):
-            Input document.
+            Required. Input document.
+        classification_model_options (google.cloud.language_v1.types.ClassificationModelOptions):
+            Model options to use for classification.
+            Defaults to v1 options if not specified.
     """
 
     document = proto.Field(
         proto.MESSAGE,
         number=1,
         message="Document",
     )
+    classification_model_options = proto.Field(
+        proto.MESSAGE,
+        number=3,
+        message="ClassificationModelOptions",
+    )
 
 
 class ClassifyTextResponse(proto.Message):
@@ -975,9 +1048,9 @@ class AnnotateTextRequest(proto.Message):
 
     Attributes:
         document (google.cloud.language_v1.types.Document):
-            Input document.
+            Required. Input document.
         features (google.cloud.language_v1.types.AnnotateTextRequest.Features):
-            The enabled features.
+            Required. The enabled features.
         encoding_type (google.cloud.language_v1.types.EncodingType):
             The encoding type used by the API to
             calculate offsets.
@@ -1000,6 +1073,10 @@ class Features(proto.Message):
                 sentiment.
             classify_text (bool):
                 Classify the full document into categories.
+            classification_model_options (google.cloud.language_v1.types.ClassificationModelOptions):
+                The model options to use for classification. Defaults to v1
+                options if not specified. Only used if ``classify_text`` is
+                set to true.
         """
 
         extract_syntax = proto.Field(
@@ -1022,6 +1099,11 @@ class Features(proto.Message):
             proto.BOOL,
             number=6,
         )
+        classification_model_options = proto.Field(
+            proto.MESSAGE,
+            number=10,
+            message="ClassificationModelOptions",
+        )
 
     document = proto.Field(
         proto.MESSAGE,

google/cloud/language_v1beta2/__init__.py

@@ -27,6 +27,7 @@
     AnnotateTextRequest,
     AnnotateTextResponse,
     ClassificationCategory,
+    ClassificationModelOptions,
     ClassifyTextRequest,
     ClassifyTextResponse,
     DependencyEdge,
@@ -54,6 +55,7 @@
     "AnnotateTextRequest",
     "AnnotateTextResponse",
     "ClassificationCategory",
+    "ClassificationModelOptions",
     "ClassifyTextRequest",
     "ClassifyTextResponse",
     "DependencyEdge",

google/cloud/language_v1beta2/services/language_service/async_client.py

@@ -568,7 +568,7 @@ async def analyze_syntax(
         metadata: Sequence[Tuple[str, str]] = (),
     ) -> language_service.AnalyzeSyntaxResponse:
         r"""Analyzes the syntax of the text and provides sentence
-        boundaries and tokenization along with part-of-speech
+        boundaries and tokenization along with part of speech
         tags, dependency trees, and other properties.
 
         .. code-block:: python

google/cloud/language_v1beta2/services/language_service/client.py

@@ -743,7 +743,7 @@ def analyze_syntax(
         metadata: Sequence[Tuple[str, str]] = (),
     ) -> language_service.AnalyzeSyntaxResponse:
         r"""Analyzes the syntax of the text and provides sentence
-        boundaries and tokenization along with part-of-speech
+        boundaries and tokenization along with part of speech
         tags, dependency trees, and other properties.
 
         .. code-block:: python

google/cloud/language_v1beta2/services/language_service/transports/grpc.py

@@ -331,7 +331,7 @@ def analyze_syntax(
         r"""Return a callable for the analyze syntax method over gRPC.
 
         Analyzes the syntax of the text and provides sentence
-        boundaries and tokenization along with part-of-speech
+        boundaries and tokenization along with part of speech
         tags, dependency trees, and other properties.
 
         Returns:

google/cloud/language_v1beta2/services/language_service/transports/grpc_asyncio.py

@@ -335,7 +335,7 @@ def analyze_syntax(
         r"""Return a callable for the analyze syntax method over gRPC.
 
         Analyzes the syntax of the text and provides sentence
-        boundaries and tokenization along with part-of-speech
+        boundaries and tokenization along with part of speech
         tags, dependency trees, and other properties.
 
         Returns: