[textanalytics] support for healthcare action + FHIR (Azure#24298)

* add impl for healthcare action + fhir and tests

* update changelog

* updates for validate + tests

Author: kristapratico

sdk/textanalytics/azure-ai-textanalytics/CHANGELOG.md

@@ -2,8 +2,15 @@
 
 ## 5.2.0b4 (Unreleased)
 
+This version of the client library defaults to the latest supported API version, which currently is `2022-04-01-preview`.
+
 ### Features Added
 
+- Added support for Healthcare Entities Analysis through the `begin_analyze_actions` API with the `AnalyzeHealthcareEntitiesAction` type.
+- Added keyword argument `fhir_version` to `begin_analyze_healthcare_entities` and `AnalyzeHealthcareEntitiesAction`. Use the keyword to indicate the version for the `fhir_bundle` contained on the `AnalyzeHealthcareEntitiesResult`.
+- Added property `fhir_bundle` to `AnalyzeHealthcareEntitiesResult`.
+- Added keyword argument `display_name` to `begin_analyze_healthcare_entities`.
+
 ### Breaking Changes
 
 ### Bugs Fixed

sdk/textanalytics/azure-ai-textanalytics/azure/ai/textanalytics/__init__.py

@@ -59,6 +59,7 @@
     MultiCategoryClassifyAction,
     MultiCategoryClassifyResult,
     ClassificationCategory,
+    AnalyzeHealthcareEntitiesAction,
 )
 
 from ._lro import AnalyzeHealthcareEntitiesLROPoller, AnalyzeActionsLROPoller
@@ -120,6 +121,7 @@
     "MultiCategoryClassifyAction",
     "MultiCategoryClassifyResult",
     "ClassificationCategory",
+    "AnalyzeHealthcareEntitiesAction",
 ]
 
 __version__ = VERSION

sdk/textanalytics/azure-ai-textanalytics/azure/ai/textanalytics/_models.py

@@ -491,8 +491,15 @@ class AnalyzeHealthcareEntitiesResult(DictMixin):
         field will contain information about the document payload.
     :vartype statistics:
         ~azure.ai.textanalytics.TextDocumentStatistics
+    :ivar fhir_bundle: If `fhir_version` is passed, this will contain a
+        FHIR compatible object for consumption in other Healthcare tools. For additional
+        information see https://www.hl7.org/fhir/overview.html.
+    :vartype fhir_bundle: dict[str, any]
     :ivar bool is_error: Boolean check for error item when iterating over list of
         results. Always False for an instance of a AnalyzeHealthcareEntitiesResult.
+
+    .. versionadded:: 2022-04-01-preview
+        The *fhir_bundle* property.
     """
 
     def __init__(self, **kwargs):
@@ -501,6 +508,7 @@ def __init__(self, **kwargs):
         self.entity_relations = kwargs.get("entity_relations", None)
         self.warnings = kwargs.get("warnings", [])
         self.statistics = kwargs.get("statistics", None)
+        self.fhir_bundle = kwargs.get("fhir_bundle", None)
         self.is_error = False
 
     @classmethod
@@ -516,6 +524,8 @@ def _from_generated(cls, healthcare_result):
             for r in healthcare_result.relations
         ]
 
+        fhir_bundle = healthcare_result.fhir_bundle if hasattr(healthcare_result, "fhir_bundle") else None
+
         return cls(
             id=healthcare_result.id,
             entities=entities,
@@ -529,17 +539,19 @@ def _from_generated(cls, healthcare_result):
             statistics=TextDocumentStatistics._from_generated(  # pylint: disable=protected-access
                 healthcare_result.statistics
             ),
+            fhir_bundle=fhir_bundle,
         )
 
     def __repr__(self):
         return (
             "AnalyzeHealthcareEntitiesResult(id={}, entities={}, entity_relations={}, warnings={}, "
-            "statistics={}, is_error={})".format(
+            "statistics={}, fhir_bundle={}, is_error={})".format(
                 self.id,
                 repr(self.entities),
                 repr(self.entity_relations),
                 repr(self.warnings),
                 repr(self.statistics),
+                self.fhir_bundle,
                 self.is_error,
             )[:1024]
         )
@@ -2683,3 +2695,74 @@ def _from_generated(cls, result):
             category=result.category,
             confidence_score=result.confidence_score
         )
+
+
+class AnalyzeHealthcareEntitiesAction(DictMixin):
+    """AnalyzeHealthcareEntitiesAction encapsulates the parameters for starting a long-running
+    healthcare entities analysis operation.
+
+    If you just want to analyze healthcare entities in a list of documents, and not perform multiple
+    long running actions on the input of documents, call method `begin_analyze_healthcare_entities` instead
+    of interfacing with this model.
+
+    :keyword str model_version: The model version to use for the analysis.
+    :keyword str string_index_type: Specifies the method used to interpret string offsets.
+        `UnicodeCodePoint`, the Python encoding, is the default. To override the Python default,
+        you can also pass in `Utf16CodeUnit` or TextElement_v8`. For additional information
+        see https://aka.ms/text-analytics-offsets
+    :keyword bool disable_service_logs: If set to true, you opt-out of having your text input
+        logged on the service side for troubleshooting. By default, Text Analytics logs your
+        input text for 48 hours, solely to allow for troubleshooting issues in providing you with
+        the Text Analytics natural language processing functions. Setting this parameter to true,
+        disables input logging and may limit our ability to remediate issues that occur. Please see
+        Cognitive Services Compliance and Privacy notes at https://aka.ms/cs-compliance for
+        additional details, and Microsoft Responsible AI principles at
+        https://www.microsoft.com/ai/responsible-ai.
+    :keyword str fhir_version: The FHIR Spec version that the result will use to format the fhir_bundle
+        on the result object. For additional information see https://www.hl7.org/fhir/overview.html.
+        The only acceptable values to pass in are None and "4.0.1". The default value is None.
+    :ivar str model_version: The model version to use for the analysis.
+    :ivar str string_index_type: Specifies the method used to interpret string offsets.
+        `UnicodeCodePoint`, the Python encoding, is the default. To override the Python default,
+        you can also pass in `Utf16CodeUnit` or TextElement_v8`. For additional information
+        see https://aka.ms/text-analytics-offsets
+    :ivar bool disable_service_logs: If set to true, you opt-out of having your text input
+        logged on the service side for troubleshooting. By default, Text Analytics logs your
+        input text for 48 hours, solely to allow for troubleshooting issues in providing you with
+        the Text Analytics natural language processing functions. Setting this parameter to true,
+        disables input logging and may limit our ability to remediate issues that occur. Please see
+        Cognitive Services Compliance and Privacy notes at https://aka.ms/cs-compliance for
+        additional details, and Microsoft Responsible AI principles at
+        https://www.microsoft.com/ai/responsible-ai.
+    :ivar str fhir_version: The FHIR Spec version that the result will use to format the fhir_bundle
+        on the result object. For additional information see https://www.hl7.org/fhir/overview.html.
+        The only acceptable values to pass in are None and "4.0.1". The default value is None.
+    """
+
+    def __init__(self, **kwargs):
+        self.model_version = kwargs.get("model_version", None)
+        self.string_index_type = kwargs.get("string_index_type", "UnicodeCodePoint")
+        self.disable_service_logs = kwargs.get("disable_service_logs", None)
+        self.fhir_version = kwargs.get("fhir_version", None)
+
+    def __repr__(self):
+        return (
+            "AnalyzeHealthcareEntitiesAction(model_version={}, string_index_type={}, disable_service_logs={}, "
+            "fhir_version={})".format(
+                self.model_version,
+                self.string_index_type,
+                self.disable_service_logs,
+                self.fhir_version
+            )[:1024]
+        )
+
+    def _to_generated(self, api_version, task_id):  # pylint: disable=unused-argument
+        return _v2022_04_01_preview_models.HealthcareLROTask(
+            task_name=task_id,
+            parameters=_v2022_04_01_preview_models.HealthcareTaskParameters(
+                model_version=self.model_version,
+                string_index_type=string_index_type_compatibility(self.string_index_type),
+                logging_opt_out=self.disable_service_logs,
+                fhir_version=self.fhir_version
+            )
+        )

sdk/textanalytics/azure-ai-textanalytics/azure/ai/textanalytics/_request_handlers.py

@@ -97,4 +97,6 @@ def _determine_action_type(action):  # pylint: disable=too-many-return-statement
         return _AnalyzeActionsType.SINGLE_CATEGORY_CLASSIFY
     if action.__class__.__name__ == "CustomMultiLabelClassificationLROTask":
         return _AnalyzeActionsType.MULTI_CATEGORY_CLASSIFY
+    if action.__class__.__name__ == "HealthcareLROTask":
+        return _AnalyzeActionsType.ANALYZE_HEALTHCARE_ENTITIES
     return _AnalyzeActionsType.EXTRACT_KEY_PHRASES

sdk/textanalytics/azure-ai-textanalytics/azure/ai/textanalytics/_text_analytics_client.py

@@ -65,6 +65,7 @@
     SingleCategoryClassifyResult,
     MultiCategoryClassifyAction,
     MultiCategoryClassifyResult,
+    AnalyzeHealthcareEntitiesAction,
     _AnalyzeActionsType,
 )
 from ._check import is_language_api, string_index_type_compatibility
@@ -577,7 +578,7 @@ def _healthcare_result_callback(
     @distributed_trace
     @validate_multiapi_args(
         version_method_added="v3.1",
-        args_mapping={"2022-04-01-preview": ["display_name"]}
+        args_mapping={"2022-04-01-preview": ["display_name", "fhir_version"]}
     )
     def begin_analyze_healthcare_entities(
         self,
@@ -610,6 +611,9 @@ def begin_analyze_healthcare_entities(
             take precedence over whole batch language. See https://aka.ms/talangs for
             supported languages in Text Analytics API.
         :keyword str display_name: An optional display name to set for the requested analysis.
+        :keyword str fhir_version: The FHIR Spec version that the result will use to format the fhir_bundle
+            on the result object. For additional information see https://www.hl7.org/fhir/overview.html.
+            The only acceptable values to pass in are None and "4.0.1". The default value is None.
         :keyword str string_index_type: Specifies the method used to interpret string offsets.
             `UnicodeCodePoint`, the Python encoding, is the default. To override the Python default,
             you can also pass in `Utf16CodeUnit` or `TextElement_v8`. For additional information
@@ -639,7 +643,7 @@ def begin_analyze_healthcare_entities(
         .. versionadded:: v3.1
             The *begin_analyze_healthcare_entities* client method.
         .. versionadded:: 2022-04-01-preview
-            The *display_name* keyword argument.
+            The *display_name* and *fhir_version* keyword arguments.
 
         .. admonition:: Example:
 
@@ -659,6 +663,7 @@ def begin_analyze_healthcare_entities(
         string_index_type = kwargs.pop("string_index_type", self._string_index_type_default)
         disable_service_logs = kwargs.pop("disable_service_logs", None)
         display_name = kwargs.pop("display_name", None)
+        fhir_version = kwargs.pop("fhir_version", None)
 
         if continuation_token:
             def get_result_from_cont_token(initial_response, pipeline_response):
@@ -704,7 +709,8 @@ def get_result_from_cont_token(initial_response, pipeline_response):
                                 parameters=models.HealthcareTaskParameters(
                                     model_version=model_version,
                                     logging_opt_out=disable_service_logs,
-                                    string_index_type=string_index_type_compatibility(string_index_type)
+                                    string_index_type=string_index_type_compatibility(string_index_type),
+                                    fhir_version=fhir_version,
                                 )
                             )
                         ]
@@ -1000,6 +1006,7 @@ def begin_analyze_actions(
                 RecognizeCustomEntitiesAction,
                 SingleCategoryClassifyAction,
                 MultiCategoryClassifyAction,
+                AnalyzeHealthcareEntitiesAction,
             ]
         ],
         **kwargs: Any,
@@ -1016,6 +1023,7 @@ def begin_analyze_actions(
                     RecognizeCustomEntitiesResult,
                     SingleCategoryClassifyResult,
                     MultiCategoryClassifyResult,
+                    AnalyzeHealthcareEntitiesResult,
                     DocumentError,
                 ]
             ]
@@ -1043,7 +1051,8 @@ def begin_analyze_actions(
         :type actions:
             list[RecognizeEntitiesAction or RecognizePiiEntitiesAction or ExtractKeyPhrasesAction or
             RecognizeLinkedEntitiesAction or AnalyzeSentimentAction or ExtractSummaryAction or
-            RecognizeCustomEntitiesAction or SingleCategoryClassifyAction or MultiCategoryClassifyAction]
+            RecognizeCustomEntitiesAction or SingleCategoryClassifyAction or
+            MultiCategoryClassifyAction or AnalyzeHealthcareEntitiesAction]
         :keyword str display_name: An optional display name to set for the requested analysis.
         :keyword str language: The 2 letter ISO 639-1 representation of language for the
             entire batch. For example, use "en" for English; "es" for Spanish etc.
@@ -1072,16 +1081,17 @@ def begin_analyze_actions(
             ~azure.ai.textanalytics.AnalyzeActionsLROPoller[~azure.core.paging.ItemPaged[
             list[RecognizeEntitiesResult or RecognizeLinkedEntitiesResult or RecognizePiiEntitiesResult or
             ExtractKeyPhrasesResult or AnalyzeSentimentResult or ExtractSummaryAction or RecognizeCustomEntitiesResult
-            or SingleCategoryClassifyResult or MultiCategoryClassifyResult or DocumentError]]]
+            or SingleCategoryClassifyResult or MultiCategoryClassifyResult or AnalyzeHealthcareEntitiesResult or
+            DocumentError]]]
         :raises ~azure.core.exceptions.HttpResponseError or TypeError or ValueError or NotImplementedError:
 
         .. versionadded:: v3.1
             The *begin_analyze_actions* client method.
         .. versionadded:: 2022-04-01-preview
             The *ExtractSummaryAction*, *RecognizeCustomEntitiesAction*, *SingleCategoryClassifyAction*,
-            and *MultiCategoryClassifyAction* input options and the corresponding *ExtractSummaryResult*,
-            *RecognizeCustomEntitiesResult*, *SingleCategoryClassifyResult*, and *MultiCategoryClassifyResult*
-            result objects
+            *MultiCategoryClassifyAction*, and *AnalyzeHealthcareEntitiesAction* input options and the
+            corresponding *ExtractSummaryResult*, *RecognizeCustomEntitiesResult*, *SingleCategoryClassifyResult*,
+            *MultiCategoryClassifyResult*, and *AnalyzeHealthcareEntitiesResult* result objects
 
         .. admonition:: Example:
 

sdk/textanalytics/azure-ai-textanalytics/azure/ai/textanalytics/_validate.py

@@ -27,7 +27,8 @@ def check_for_unsupported_actions_types(*args, **kwargs):
             "ExtractSummaryAction",
             "RecognizeCustomEntitiesAction",
             "SingleCategoryClassifyAction",
-            "MultiCategoryClassifyAction"
+            "MultiCategoryClassifyAction",
+            "AnalyzeHealthcareEntitiesAction"
         ]
     }