[text analytics] Healthcare n-ary relations (#16997)

Author: iscai-msft

eng/.docsettings.yml

@@ -105,6 +105,7 @@ known_content_issues:
   - ['sdk/monitor/azure-monitor-opentelemetry-exporter/swagger/README.md', '#4554']
   - ['sdk/monitor/azure-monitor-opentelemetry-exporter/README.md', '#4554']
   - ['sdk/digitaltwins/azure-digitaltwins-core/swagger/README.md', '#4554']
+  - ['sdk/textanalytics/azure-ai-textanalytics/swagger/README.md', '#4554']
   - ['sdk/media/azure-media-nspkg/README.md', '#4554']
 
   # nspckg and common.

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

@@ -4,6 +4,7 @@
 
 **Breaking Changes**
 
+- Removed property `related_entities` on `HealthcareEntity` and added `entity_relations` onto the document response level for healthcare
 - Renamed properties `aspect` and `opinions` to `target` and `assessments` respectively in class `MinedOpinion`.
 - Renamed classes `AspectSentiment` and `OpinionSentiment` to `TargetSentiment` and `AssessmentSentiment` respectively.
 
@@ -87,7 +88,7 @@ used in conjunction with the Bing Entity Search API to fetch additional relevant
 - Removed `grapheme_offset` and `grapheme_length` from `CategorizedEntity`, `SentenceSentiment`, and `LinkedEntityMatch`
 - `TextDocumentStatistics` attribute `grapheme_count` has been renamed to `character_count`
 
-## 1.0.0b5 
+## 1.0.0b5
 
 - This was a broken release
 

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

@@ -476,15 +476,14 @@ for idx, doc in enumerate(docs):
             for data_source in entity.data_sources:
                 print("......Entity ID: {}".format(data_source.entity_id))
                 print("......Name: {}".format(data_source.name))
-        if len(entity.related_entities) > 0:
-            print("...Related Entities:")
-            for related_entity, relation_type in entity.related_entities.items():
-                print("......Entity Text: {}".format(related_entity.text))
-                print("......Relation Type: {}".format(relation_type))
+    for relation in doc.entity_relations:
+        print("Relation of type: {} has the following roles".format(relation.relation_type))
+        for role in relation.roles:
+            print("...Role '{}' with entity '{}'".format(role.name, role.entity.text))
     print("------------------------------------------")
 ```
 
-Note: The Healthcare Entities Analysis service is currently available only in API version v3.1-preview.3 in gated preview. Since this is a gated preview, AAD is not supported. More information [here](https://docs.microsoft.com/azure/cognitive-services/text-analytics/how-tos/text-analytics-for-health?tabs=ner#request-access-to-the-public-preview).
+Note: The Healthcare Entities Analysis service is currently available only in the API v3.1 preview versions and is in gated preview. Since this is a gated preview, AAD is not supported. More information [here](https://docs.microsoft.com/azure/cognitive-services/text-analytics/how-tos/text-analytics-for-health?tabs=ner#request-access-to-the-public-preview).
 
 ### Batch Analysis
 
@@ -559,7 +558,7 @@ for idx, doc in enumerate(docs):
 
 The returned response is an object encapsulating multiple iterables, each representing results of individual analyses.
 
-Note: Batch analysis is currently available only in API version v3.1-preview.3.
+Note: Batch analysis is currently available only in the v3.1-preview API version.
 
 ## Optional Configuration
 

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

@@ -42,8 +42,10 @@
     RequestStatistics,
     AnalyzeBatchActionsType,
     AnalyzeBatchActionsError,
+    HealthcareEntityRelationRoleType,
 )
 from ._paging import AnalyzeHealthcareEntitiesResult
+from ._generated.v3_1_preview_4.models import RelationType as HealthcareEntityRelationType
 
 __all__ = [
     'TextAnalyticsApiVersion',
@@ -83,6 +85,8 @@
     'RequestStatistics',
     'AnalyzeBatchActionsType',
     "AnalyzeBatchActionsError",
+    "HealthcareEntityRelationType",
+    "HealthcareEntityRelationRoleType",
 ]
 
 __version__ = VERSION

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

@@ -85,7 +85,7 @@ def __init__(self, *args, **kwargs):
 
     @property
     def _current_body(self):
-        from ._generated.v3_1_preview_3.models import JobMetadata
+        from ._generated.v3_1_preview_4.models import JobMetadata
         return JobMetadata.deserialize(self._pipeline_response)
 
     @property
@@ -170,7 +170,7 @@ class AsyncAnalyzeBatchActionsLROPollingMethod(TextAnalyticsAsyncLROPollingMetho
 
     @property
     def _current_body(self):
-        from ._generated.v3_1_preview_3.models import AnalyzeJobMetadata
+        from ._generated.v3_1_preview_4.models import AnalyzeJobMetadata
         return AnalyzeJobMetadata.deserialize(self._pipeline_response)
 
     @property
@@ -265,4 +265,3 @@ def total_actions_count(self):
     @property
     def id(self):
         return self._polling_method.id
-    

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

@@ -15,7 +15,6 @@ class TextAnalyticsApiVersion(str, Enum):
 
     #: this is the default version
     V3_1_PREVIEW = "v3.1-preview.4"
-    V3_1_PREVIEW_3 = "v3.1-preview.3"
     V3_0 = "v3.0"
 
 def _authentication_policy(credential):

sdk/textanalytics/azure-ai-textanalytics/azure/ai/textanalytics/_generated/_operations_mixin.py

@@ -54,13 +54,11 @@ def analyze_status(
         :type skip: int
         :keyword callable cls: A custom type or function that will be passed the direct response
         :return: AnalyzeJobState, or the result of cls(response)
-        :rtype: ~azure.ai.textanalytics.v3_1_preview_3.models.AnalyzeJobState
+        :rtype: ~azure.ai.textanalytics.v3_1_preview_4.models.AnalyzeJobState
         :raises: ~azure.core.exceptions.HttpResponseError
         """
         api_version = self._get_api_version('analyze_status')
-        if api_version == 'v3.1-preview.3':
-            from .v3_1_preview_3.operations import TextAnalyticsClientOperationsMixin as OperationClass
-        elif api_version == 'v3.1-preview.4':
+        if api_version == 'v3.1-preview.4':
             from .v3_1_preview_4.operations import TextAnalyticsClientOperationsMixin as OperationClass
         else:
             raise ValueError("API version {} does not have operation 'analyze_status'".format(api_version))
@@ -83,21 +81,19 @@ def begin_analyze(
         executed.
 
         :param body: Collection of documents to analyze and tasks to execute.
-        :type body: ~azure.ai.textanalytics.v3_1_preview_3.models.AnalyzeBatchInput
+        :type body: ~azure.ai.textanalytics.v3_1_preview_4.models.AnalyzeBatchInput
         :keyword callable cls: A custom type or function that will be passed the direct response
         :keyword str continuation_token: A continuation token to restart a poller from a saved state.
         :keyword polling: Pass in True if you'd like the AnalyzeBatchActionsLROPollingMethod polling method,
          False for no polling, or your own initialized polling object for a personal polling strategy.
         :paramtype polling: bool or ~azure.core.polling.PollingMethod
         :keyword int polling_interval: Default waiting time between two polls for LRO operations if no Retry-After header is present.
         :return: An instance of AnalyzeBatchActionsLROPoller that returns either AnalyzeJobState or the result of cls(response)
-        :rtype: ~...._lro.AnalyzeBatchActionsLROPoller[~azure.ai.textanalytics.v3_1_preview_3.models.AnalyzeJobState]
+        :rtype: ~...._lro.AnalyzeBatchActionsLROPoller[~azure.ai.textanalytics.v3_1_preview_4.models.AnalyzeJobState]
         :raises ~azure.core.exceptions.HttpResponseError:
         """
         api_version = self._get_api_version('begin_analyze')
-        if api_version == 'v3.1-preview.3':
-            from .v3_1_preview_3.operations import TextAnalyticsClientOperationsMixin as OperationClass
-        elif api_version == 'v3.1-preview.4':
+        if api_version == 'v3.1-preview.4':
             from .v3_1_preview_4.operations import TextAnalyticsClientOperationsMixin as OperationClass
         else:
             raise ValueError("API version {} does not have operation 'begin_analyze'".format(api_version))
@@ -131,9 +127,7 @@ def begin_cancel_health_job(
         :raises ~azure.core.exceptions.HttpResponseError:
         """
         api_version = self._get_api_version('begin_cancel_health_job')
-        if api_version == 'v3.1-preview.3':
-            from .v3_1_preview_3.operations import TextAnalyticsClientOperationsMixin as OperationClass
-        elif api_version == 'v3.1-preview.4':
+        if api_version == 'v3.1-preview.4':
             from .v3_1_preview_4.operations import TextAnalyticsClientOperationsMixin as OperationClass
         else:
             raise ValueError("API version {} does not have operation 'begin_cancel_health_job'".format(api_version))
@@ -158,28 +152,26 @@ def begin_health(
         symptoms, etc) and their relations.
 
         :param documents: The set of documents to process as part of this batch.
-        :type documents: list[~azure.ai.textanalytics.v3_1_preview_3.models.MultiLanguageInput]
+        :type documents: list[~azure.ai.textanalytics.v3_1_preview_4.models.MultiLanguageInput]
         :param model_version: (Optional) This value indicates which model will be used for scoring. If
          a model-version is not specified, the API should default to the latest, non-preview version.
         :type model_version: str
         :param string_index_type: (Optional) Specifies the method used to interpret string offsets.
          Defaults to Text Elements (Graphemes) according to Unicode v8.0.0. For additional information
          see https://aka.ms/text-analytics-offsets.
-        :type string_index_type: str or ~azure.ai.textanalytics.v3_1_preview_3.models.StringIndexType
+        :type string_index_type: str or ~azure.ai.textanalytics.v3_1_preview_4.models.StringIndexType
         :keyword callable cls: A custom type or function that will be passed the direct response
         :keyword str continuation_token: A continuation token to restart a poller from a saved state.
         :keyword polling: Pass in True if you'd like the AnalyzeHealthcareEntitiesLROPollingMethod polling method,
          False for no polling, or your own initialized polling object for a personal polling strategy.
         :paramtype polling: bool or ~azure.core.polling.PollingMethod
         :keyword int polling_interval: Default waiting time between two polls for LRO operations if no Retry-After header is present.
         :return: An instance of AnalyzeHealthcareEntitiesLROPoller that returns either HealthcareJobState or the result of cls(response)
-        :rtype: ~...._lro.AnalyzeHealthcareEntitiesLROPoller[~azure.ai.textanalytics.v3_1_preview_3.models.HealthcareJobState]
+        :rtype: ~...._lro.AnalyzeHealthcareEntitiesLROPoller[~azure.ai.textanalytics.v3_1_preview_4.models.HealthcareJobState]
         :raises ~azure.core.exceptions.HttpResponseError:
         """
         api_version = self._get_api_version('begin_health')
-        if api_version == 'v3.1-preview.3':
-            from .v3_1_preview_3.operations import TextAnalyticsClientOperationsMixin as OperationClass
-        elif api_version == 'v3.1-preview.4':
+        if api_version == 'v3.1-preview.4':
             from .v3_1_preview_4.operations import TextAnalyticsClientOperationsMixin as OperationClass
         else:
             raise ValueError("API version {} does not have operation 'begin_health'".format(api_version))
@@ -220,8 +212,6 @@ def entities_linking(
         api_version = self._get_api_version('entities_linking')
         if api_version == 'v3.0':
             from .v3_0.operations import TextAnalyticsClientOperationsMixin as OperationClass
-        elif api_version == 'v3.1-preview.3':
-            from .v3_1_preview_3.operations import TextAnalyticsClientOperationsMixin as OperationClass
         elif api_version == 'v3.1-preview.4':
             from .v3_1_preview_4.operations import TextAnalyticsClientOperationsMixin as OperationClass
         else:
@@ -264,8 +254,6 @@ def entities_recognition_general(
         api_version = self._get_api_version('entities_recognition_general')
         if api_version == 'v3.0':
             from .v3_0.operations import TextAnalyticsClientOperationsMixin as OperationClass
-        elif api_version == 'v3.1-preview.3':
-            from .v3_1_preview_3.operations import TextAnalyticsClientOperationsMixin as OperationClass
         elif api_version == 'v3.1-preview.4':
             from .v3_1_preview_4.operations import TextAnalyticsClientOperationsMixin as OperationClass
         else:
@@ -285,6 +273,7 @@ def entities_recognition_pii(
         show_stats=None,  # type: Optional[bool]
         domain=None,  # type: Optional[str]
         string_index_type="TextElements_v8",  # type: Optional[Union[str, "_models.StringIndexType"]]
+        pii_categories=None,  # type: Optional[List[Union[str, "_models.PiiCategory"]]]
         **kwargs  # type: Any
     ):
         """Entities containing personal information.
@@ -296,7 +285,7 @@ def entities_recognition_pii(
         list of enabled languages.
 
         :param documents: The set of documents to process as part of this batch.
-        :type documents: list[~azure.ai.textanalytics.v3_1_preview_3.models.MultiLanguageInput]
+        :type documents: list[~azure.ai.textanalytics.v3_1_preview_4.models.MultiLanguageInput]
         :param model_version: (Optional) This value indicates which model will be used for scoring. If
          a model-version is not specified, the API should default to the latest, non-preview version.
         :type model_version: str
@@ -309,16 +298,16 @@ def entities_recognition_pii(
         :param string_index_type: (Optional) Specifies the method used to interpret string offsets.
          Defaults to Text Elements (Graphemes) according to Unicode v8.0.0. For additional information
          see https://aka.ms/text-analytics-offsets.
-        :type string_index_type: str or ~azure.ai.textanalytics.v3_1_preview_3.models.StringIndexType
+        :type string_index_type: str or ~azure.ai.textanalytics.v3_1_preview_4.models.StringIndexType
+        :param pii_categories: (Optional) describes the PII categories to return.
+        :type pii_categories: list[str or ~azure.ai.textanalytics.v3_1_preview_4.models.PiiCategory]
         :keyword callable cls: A custom type or function that will be passed the direct response
         :return: PiiResult, or the result of cls(response)
-        :rtype: ~azure.ai.textanalytics.v3_1_preview_3.models.PiiResult
+        :rtype: ~azure.ai.textanalytics.v3_1_preview_4.models.PiiResult
         :raises: ~azure.core.exceptions.HttpResponseError
         """
         api_version = self._get_api_version('entities_recognition_pii')
-        if api_version == 'v3.1-preview.3':
-            from .v3_1_preview_3.operations import TextAnalyticsClientOperationsMixin as OperationClass
-        elif api_version == 'v3.1-preview.4':
+        if api_version == 'v3.1-preview.4':
             from .v3_1_preview_4.operations import TextAnalyticsClientOperationsMixin as OperationClass
         else:
             raise ValueError("API version {} does not have operation 'entities_recognition_pii'".format(api_version))
@@ -328,7 +317,7 @@ def entities_recognition_pii(
         mixin_instance._serialize = Serializer(self._models_dict(api_version))
         mixin_instance._serialize.client_side_validation = False
         mixin_instance._deserialize = Deserializer(self._models_dict(api_version))
-        return mixin_instance.entities_recognition_pii(documents, model_version, show_stats, domain, string_index_type, **kwargs)
+        return mixin_instance.entities_recognition_pii(documents, model_version, show_stats, domain, string_index_type, pii_categories, **kwargs)
 
     def health_status(
         self,
@@ -355,13 +344,11 @@ def health_status(
         :type show_stats: bool
         :keyword callable cls: A custom type or function that will be passed the direct response
         :return: HealthcareJobState, or the result of cls(response)
-        :rtype: ~azure.ai.textanalytics.v3_1_preview_3.models.HealthcareJobState
+        :rtype: ~azure.ai.textanalytics.v3_1_preview_4.models.HealthcareJobState
         :raises: ~azure.core.exceptions.HttpResponseError
         """
         api_version = self._get_api_version('health_status')
-        if api_version == 'v3.1-preview.3':
-            from .v3_1_preview_3.operations import TextAnalyticsClientOperationsMixin as OperationClass
-        elif api_version == 'v3.1-preview.4':
+        if api_version == 'v3.1-preview.4':
             from .v3_1_preview_4.operations import TextAnalyticsClientOperationsMixin as OperationClass
         else:
             raise ValueError("API version {} does not have operation 'health_status'".format(api_version))
@@ -402,8 +389,6 @@ def key_phrases(
         api_version = self._get_api_version('key_phrases')
         if api_version == 'v3.0':
             from .v3_0.operations import TextAnalyticsClientOperationsMixin as OperationClass
-        elif api_version == 'v3.1-preview.3':
-            from .v3_1_preview_3.operations import TextAnalyticsClientOperationsMixin as OperationClass
         elif api_version == 'v3.1-preview.4':
             from .v3_1_preview_4.operations import TextAnalyticsClientOperationsMixin as OperationClass
         else:
@@ -446,8 +431,6 @@ def languages(
         api_version = self._get_api_version('languages')
         if api_version == 'v3.0':
             from .v3_0.operations import TextAnalyticsClientOperationsMixin as OperationClass
-        elif api_version == 'v3.1-preview.3':
-            from .v3_1_preview_3.operations import TextAnalyticsClientOperationsMixin as OperationClass
         elif api_version == 'v3.1-preview.4':
             from .v3_1_preview_4.operations import TextAnalyticsClientOperationsMixin as OperationClass
         else:
@@ -490,8 +473,6 @@ def sentiment(
         api_version = self._get_api_version('sentiment')
         if api_version == 'v3.0':
             from .v3_0.operations import TextAnalyticsClientOperationsMixin as OperationClass
-        elif api_version == 'v3.1-preview.3':
-            from .v3_1_preview_3.operations import TextAnalyticsClientOperationsMixin as OperationClass
         elif api_version == 'v3.1-preview.4':
             from .v3_1_preview_4.operations import TextAnalyticsClientOperationsMixin as OperationClass
         else:

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

@@ -24,6 +24,7 @@
     from typing import Any, Optional
 
     from azure.core.credentials import TokenCredential
+    from azure.core.pipeline.transport import HttpRequest, HttpResponse
 
 class _SDKClient(object):
     def __init__(self, *args, **kwargs):
@@ -73,8 +74,6 @@ def __init__(
     ):
         if api_version == 'v3.0':
             base_url = '{Endpoint}/text/analytics/v3.0'
-        elif api_version == 'v3.1-preview.3':
-            base_url = '{Endpoint}/text/analytics/v3.1-preview.3'
         elif api_version == 'v3.1-preview.4':
             base_url = '{Endpoint}/text/analytics/v3.1-preview.4'
         else:
@@ -95,15 +94,11 @@ def models(cls, api_version=DEFAULT_API_VERSION):
         """Module depends on the API version:
 
            * v3.0: :mod:`v3_0.models<azure.ai.textanalytics.v3_0.models>`
-           * v3.1-preview.3: :mod:`v3_1_preview_3.models<azure.ai.textanalytics.v3_1_preview_3.models>`
            * v3.1-preview.4: :mod:`v3_1_preview_4.models<azure.ai.textanalytics.v3_1_preview_4.models>`
         """
         if api_version == 'v3.0':
             from .v3_0 import models
             return models
-        elif api_version == 'v3.1-preview.3':
-            from .v3_1_preview_3 import models
-            return models
         elif api_version == 'v3.1-preview.4':
             from .v3_1_preview_4 import models
             return models