[HealthDataAiService.Deid] 2025-07-15-preview version (#42371)

* Adding new API version support

* Add samples and update READMEs

* Update CHANGELOG.md

* Update sdk/healthdataaiservices/azure-health-deidentification/CHANGELOG.md

Co-authored-by: Copilot <[email protected]>

* Updating test recordings

* Update README and CHANGELOG

* Update CHANGELOG

* release date

* Fix formatting

---------

Co-authored-by: Josiah Vinson <[email protected]>
Co-authored-by: Copilot <[email protected]>

Author: 3 people

sdk/healthdataaiservices/azure-health-deidentification/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Release History
 
+## 1.1.0b1 (2025-08-05)
+
+### Features Added
+
+- Added `SURROGATE_ONLY` operation type in `DeidentificationOperationType`, which returns output text where user-defined PHI entities are replaced with realistic replacement values.
+- Added `input_locale` parameter to `DeidentificationCustomizationOptions` to allow for specifying the locale of the input text for `TAG` and `REDACT` operations.
+
 ## 1.0.0 (2025-05-19)
 
 ### Features Added
@@ -33,4 +40,4 @@
 
 ### Features Added
 
-- Azure Health Deidentification client library
+- Azure Health Deidentification client library

sdk/healthdataaiservices/azure-health-deidentification/README.md

@@ -4,7 +4,7 @@ This package contains a client library for the de-identification service in Azur
 enables users to tag, redact, or surrogate health data containing Protected Health Information (PHI).
 For more on service functionality and important usage considerations, see [the de-identification service overview][product_documentation].
 
-This library support API versions `2024-11-15` and earlier.
+This library supports API versions `2025-07-15-preview` and earlier.
 
 Use the client library for the de-identification service to:
 - Discover PHI in unstructured text
@@ -72,10 +72,11 @@ client = DeidentificationClient(endpoint, credential)
 ## Key concepts
 
 ### De-identification operations:
-Given an input text, the de-identification service can perform three main operations:
+Given an input text, the de-identification service can perform four main operations:
 - `Tag` returns the category and location within the text of detected PHI entities.
-- `Redact` returns output text where detected PHI entities are replaced with placeholder text. For example `John` replaced with `[name]`.
+- `Redact` returns output text where detected PHI entities are replaced with placeholder text. For example, `John` would be replaced with `[name]`.
 - `Surrogate` returns output text where detected PHI entities are replaced with realistic replacement values. For example, `My name is John Smith` could become `My name is Tom Jones`.
+- `SurrogateOnly` returns output text where user-defined PHI entities are replaced with realistic replacement values.
 
 ### String Encoding
 When using the `Tag` operation, the service will return the locations of PHI entities in the input text. These locations will be represented as offsets and lengths, each of which is a [StringIndex][string_index] containing
@@ -197,6 +198,7 @@ The following sections provide code samples covering some of the most common cli
 - [Discover PHI in unstructured text](#discover-phi-in-unstructured-text)
 - [Replace PHI in unstructured text with placeholder values](#replace-phi-in-unstructured-text-with-placeholder-values)
 - [Replace PHI in unstructured text with realistic surrogate values](#replace-phi-in-unstructured-text-with-realistic-surrogate-values)
+- [Replace only specific PHI entities with surrogate values](#replace-only-specific-phi-entities-with-surrogate-values)
 
 See the [samples][samples] for code files illustrating common patterns, including creating and managing jobs to de-identify documents in Azure Storage. 
 
@@ -292,6 +294,52 @@ print(f'Surrogated Text:   "{result.output_text}"')  # Surrogated output: Hello,
 
 <!-- END SNIPPET -->
 
+### Replace only specific PHI entities with surrogate values
+The `SURROGATE_ONLY` operation returns output text where user-defined PHI entities are replaced with realistic replacement values.
+<!-- SNIPPET: deidentify_text_surrogate_only.surrogate_only -->
+
+```python
+from azure.health.deidentification import DeidentificationClient
+from azure.health.deidentification.models import (
+    DeidentificationContent,
+    DeidentificationCustomizationOptions,
+    DeidentificationOperationType,
+    DeidentificationResult,
+    PhiCategory,
+    SimplePhiEntity,
+    TaggedPhiEntities,
+    TextEncodingType,
+)
+from azure.identity import DefaultAzureCredential
+import os
+
+endpoint = os.environ["HEALTHDATAAISERVICES_DEID_SERVICE_ENDPOINT"]
+credential = DefaultAzureCredential()
+client = DeidentificationClient(endpoint, credential)
+
+# Define the entities to be surrogated - targeting "John Smith" at position 18-28
+tagged_entities = TaggedPhiEntities(
+    encoding=TextEncodingType.CODE_POINT,
+    entities=[SimplePhiEntity(category=PhiCategory.PATIENT, offset=18, length=10)],
+)
+
+# Use SurrogateOnly operation with input locale specification
+body = DeidentificationContent(
+    input_text="Hello, my name is John Smith.",
+    operation_type=DeidentificationOperationType.SURROGATE_ONLY,
+    tagged_entities=tagged_entities,
+    customizations=DeidentificationCustomizationOptions(
+        input_locale="en-US"  # Specify input text locale for better PHI detection
+    ),
+)
+
+result: DeidentificationResult = client.deidentify_text(body)
+print(f'\nOriginal Text:        "{body.input_text}"')
+print(f'Surrogate Only Text:  "{result.output_text}"')  # Surrogated output: Hello, my name is <synthetic name>.
+```
+
+<!-- END SNIPPET -->
+
 ### Troubleshooting
 The `DeidentificationClient` raises various `AzureError` [exceptions][azure_error]. For example, if you
 provide an invalid service URL, an `ServiceRequestError` would be raised with a message indicating the failure cause.

sdk/healthdataaiservices/azure-health-deidentification/_metadata.json

@@ -0,0 +1,3 @@
+{
+  "apiVersion": "2025-07-15-preview"
+}

sdk/healthdataaiservices/azure-health-deidentification/apiview-properties.json

@@ -11,16 +11,24 @@
         "azure.health.deidentification.models.DeidentificationResult": "HealthDataAIServices.DeidServices.DeidentificationResult",
         "azure.health.deidentification.models.PhiEntity": "HealthDataAIServices.DeidServices.PhiEntity",
         "azure.health.deidentification.models.PhiTaggerResult": "HealthDataAIServices.DeidServices.PhiTaggerResult",
+        "azure.health.deidentification.models.SimplePhiEntity": "HealthDataAIServices.DeidServices.SimplePhiEntity",
         "azure.health.deidentification.models.SourceStorageLocation": "HealthDataAIServices.DeidServices.SourceStorageLocation",
         "azure.health.deidentification.models.StringIndex": "HealthDataAIServices.DeidServices.StringIndex",
+        "azure.health.deidentification.models.TaggedPhiEntities": "HealthDataAIServices.DeidServices.TaggedPhiEntities",
         "azure.health.deidentification.models.TargetStorageLocation": "HealthDataAIServices.DeidServices.TargetStorageLocation",
         "azure.health.deidentification.models.DeidentificationOperationType": "HealthDataAIServices.DeidServices.DeidentificationOperationType",
         "azure.health.deidentification.models.OperationStatus": "Azure.Core.Foundations.OperationState",
         "azure.health.deidentification.models.PhiCategory": "HealthDataAIServices.DeidServices.PhiCategory",
+        "azure.health.deidentification.models.TextEncodingType": "HealthDataAIServices.DeidServices.TextEncodingType",
         "azure.health.deidentification.DeidentificationClient.get_job": "HealthDataAIServices.DeidServices.getJob",
+        "azure.health.deidentification.aio.DeidentificationClient.get_job": "HealthDataAIServices.DeidServices.getJob",
         "azure.health.deidentification.DeidentificationClient.begin_deidentify_documents": "HealthDataAIServices.DeidServices.deidentifyDocuments",
+        "azure.health.deidentification.aio.DeidentificationClient.begin_deidentify_documents": "HealthDataAIServices.DeidServices.deidentifyDocuments",
         "azure.health.deidentification.DeidentificationClient.cancel_job": "HealthDataAIServices.DeidServices.cancelJob",
+        "azure.health.deidentification.aio.DeidentificationClient.cancel_job": "HealthDataAIServices.DeidServices.cancelJob",
         "azure.health.deidentification.DeidentificationClient.delete_job": "HealthDataAIServices.DeidServices.deleteJob",
-        "azure.health.deidentification.DeidentificationClient.deidentify_text": "HealthDataAIServices.DeidServices.deidentifyText"
+        "azure.health.deidentification.aio.DeidentificationClient.delete_job": "HealthDataAIServices.DeidServices.deleteJob",
+        "azure.health.deidentification.DeidentificationClient.deidentify_text": "HealthDataAIServices.DeidServices.deidentifyText",
+        "azure.health.deidentification.aio.DeidentificationClient.deidentify_text": "HealthDataAIServices.DeidServices.deidentifyText"
     }
 }

sdk/healthdataaiservices/azure-health-deidentification/assets.json

@@ -2,5 +2,5 @@
   "AssetsRepo": "Azure/azure-sdk-assets",
   "AssetsRepoPrefixPath": "python",
   "TagPrefix": "python/healthdataaiservices/azure-health-deidentification",
-  "Tag": "python/healthdataaiservices/azure-health-deidentification_a9eda6ed27"
+  "Tag": "python/healthdataaiservices/azure-health-deidentification_db46426ffa"
 }

sdk/healthdataaiservices/azure-health-deidentification/azure/health/deidentification/_client.py

@@ -15,22 +15,23 @@
 from azure.core.rest import HttpRequest, HttpResponse
 
 from ._configuration import DeidentificationClientConfiguration
-from ._operations import DeidentificationClientOperationsMixin
-from ._serialization import Deserializer, Serializer
+from ._operations import _DeidentificationClientOperationsMixin
+from ._utils.serialization import Deserializer, Serializer
 
 if TYPE_CHECKING:
     from azure.core.credentials import TokenCredential
 
 
-class DeidentificationClient(DeidentificationClientOperationsMixin):
+class DeidentificationClient(_DeidentificationClientOperationsMixin):
     """DeidentificationClient.
 
     :param endpoint: Url of your De-identification Service. Required.
     :type endpoint: str
     :param credential: Credential used to authenticate requests to the service. Required.
     :type credential: ~azure.core.credentials.TokenCredential
-    :keyword api_version: The API version to use for this operation. Default value is "2024-11-15".
-     Note that overriding this default value may result in unsupported behavior.
+    :keyword api_version: The API version to use for this operation. Default value is
+     "2025-07-15-preview". Note that overriding this default value may result in unsupported
+     behavior.
     :paramtype api_version: str
     :keyword int polling_interval: Default waiting time between two polls for LRO operations if no
      Retry-After header is present.

sdk/healthdataaiservices/azure-health-deidentification/azure/health/deidentification/_configuration.py

@@ -26,13 +26,14 @@ class DeidentificationClientConfiguration:  # pylint: disable=too-many-instance-
     :type endpoint: str
     :param credential: Credential used to authenticate requests to the service. Required.
     :type credential: ~azure.core.credentials.TokenCredential
-    :keyword api_version: The API version to use for this operation. Default value is "2024-11-15".
-     Note that overriding this default value may result in unsupported behavior.
+    :keyword api_version: The API version to use for this operation. Default value is
+     "2025-07-15-preview". Note that overriding this default value may result in unsupported
+     behavior.
     :paramtype api_version: str
     """
 
     def __init__(self, endpoint: str, credential: "TokenCredential", **kwargs: Any) -> None:
-        api_version: str = kwargs.pop("api_version", "2024-11-15")
+        api_version: str = kwargs.pop("api_version", "2025-07-15-preview")
 
         if endpoint is None:
             raise ValueError("Parameter 'endpoint' must not be None.")

sdk/healthdataaiservices/azure-health-deidentification/azure/health/deidentification/_model_base.py

@@ -1,4 +1,4 @@
-# pylint: disable=too-many-lines
+# pylint: disable=too-many-lines,line-too-long,useless-suppression
 # coding=utf-8
 # --------------------------------------------------------------------------
 # Copyright (c) Microsoft Corporation. All rights reserved.

sdk/healthdataaiservices/azure-health-deidentification/azure/health/deidentification/_operations/__init__.py

@@ -12,14 +12,12 @@
 if TYPE_CHECKING:
     from ._patch import *  # pylint: disable=unused-wildcard-import
 
-from ._operations import DeidentificationClientOperationsMixin  # type: ignore
+from ._operations import _DeidentificationClientOperationsMixin  # type: ignore # pylint: disable=unused-import
 
 from ._patch import __all__ as _patch_all
 from ._patch import *
 from ._patch import patch_sdk as _patch_sdk
 
-__all__ = [
-    "DeidentificationClientOperationsMixin",
-]
+__all__ = []
 __all__.extend([p for p in _patch_all if p not in __all__])  # pyright: ignore
 _patch_sdk()

sdk/healthdataaiservices/azure-health-deidentification/azure/health/deidentification/_operations/_operations.py

@@ -8,9 +8,10 @@
 from collections.abc import MutableMapping
 from io import IOBase
 import json
-from typing import Any, Callable, Dict, IO, Iterable, Iterator, List, Optional, TypeVar, Union, cast, overload
+from typing import Any, Callable, Dict, IO, Iterator, List, Optional, TypeVar, Union, cast, overload
 import urllib.parse
 
+from azure.core import PipelineClient
 from azure.core.exceptions import (
     ClientAuthenticationError,
     HttpResponseError,
@@ -30,9 +31,10 @@
 from azure.core.utils import case_insensitive_dict
 
 from .. import models as _models
-from .._model_base import SdkJSONEncoder, _deserialize
-from .._serialization import Serializer
-from .._vendor import DeidentificationClientMixinABC
+from .._configuration import DeidentificationClientConfiguration
+from .._utils.model_base import SdkJSONEncoder, _deserialize
+from .._utils.serialization import Serializer
+from .._utils.utils import ClientMixinABC
 
 JSON = MutableMapping[str, Any]
 T = TypeVar("T")
@@ -46,7 +48,7 @@ def build_deidentification_get_job_request(job_name: str, **kwargs: Any) -> Http
     _headers = case_insensitive_dict(kwargs.pop("headers", {}) or {})
     _params = case_insensitive_dict(kwargs.pop("params", {}) or {})
 
-    api_version: str = kwargs.pop("api_version", _params.pop("api-version", "2024-11-15"))
+    api_version: str = kwargs.pop("api_version", _params.pop("api-version", "2025-07-15-preview"))
     accept = _headers.pop("Accept", "application/json")
 
     # Construct URL
@@ -73,7 +75,7 @@ def build_deidentification_deidentify_documents_request(  # pylint: disable=name
     _params = case_insensitive_dict(kwargs.pop("params", {}) or {})
 
     content_type: Optional[str] = kwargs.pop("content_type", _headers.pop("Content-Type", None))
-    api_version: str = kwargs.pop("api_version", _params.pop("api-version", "2024-11-15"))
+    api_version: str = kwargs.pop("api_version", _params.pop("api-version", "2025-07-15-preview"))
     accept = _headers.pop("Accept", "application/json")
 
     # Construct URL
@@ -101,7 +103,7 @@ def build_deidentification_list_jobs_internal_request(  # pylint: disable=name-t
     _headers = case_insensitive_dict(kwargs.pop("headers", {}) or {})
     _params = case_insensitive_dict(kwargs.pop("params", {}) or {})
 
-    api_version: str = kwargs.pop("api_version", _params.pop("api-version", "2024-11-15"))
+    api_version: str = kwargs.pop("api_version", _params.pop("api-version", "2025-07-15-preview"))
     accept = _headers.pop("Accept", "application/json")
 
     # Construct URL
@@ -132,7 +134,7 @@ def build_deidentification_list_job_documents_internal_request(  # pylint: disab
     _headers = case_insensitive_dict(kwargs.pop("headers", {}) or {})
     _params = case_insensitive_dict(kwargs.pop("params", {}) or {})
 
-    api_version: str = kwargs.pop("api_version", _params.pop("api-version", "2024-11-15"))
+    api_version: str = kwargs.pop("api_version", _params.pop("api-version", "2025-07-15-preview"))
     accept = _headers.pop("Accept", "application/json")
 
     # Construct URL
@@ -164,7 +166,7 @@ def build_deidentification_cancel_job_request(  # pylint: disable=name-too-long
     _headers = case_insensitive_dict(kwargs.pop("headers", {}) or {})
     _params = case_insensitive_dict(kwargs.pop("params", {}) or {})
 
-    api_version: str = kwargs.pop("api_version", _params.pop("api-version", "2024-11-15"))
+    api_version: str = kwargs.pop("api_version", _params.pop("api-version", "2025-07-15-preview"))
     accept = _headers.pop("Accept", "application/json")
 
     # Construct URL
@@ -190,7 +192,7 @@ def build_deidentification_delete_job_request(  # pylint: disable=name-too-long
     _headers = case_insensitive_dict(kwargs.pop("headers", {}) or {})
     _params = case_insensitive_dict(kwargs.pop("params", {}) or {})
 
-    api_version: str = kwargs.pop("api_version", _params.pop("api-version", "2024-11-15"))
+    api_version: str = kwargs.pop("api_version", _params.pop("api-version", "2025-07-15-preview"))
     accept = _headers.pop("Accept", "application/json")
 
     # Construct URL
@@ -215,7 +217,7 @@ def build_deidentification_deidentify_text_request(**kwargs: Any) -> HttpRequest
     _params = case_insensitive_dict(kwargs.pop("params", {}) or {})
 
     content_type: Optional[str] = kwargs.pop("content_type", _headers.pop("Content-Type", None))
-    api_version: str = kwargs.pop("api_version", _params.pop("api-version", "2024-11-15"))
+    api_version: str = kwargs.pop("api_version", _params.pop("api-version", "2025-07-15-preview"))
     accept = _headers.pop("Accept", "application/json")
 
     # Construct URL
@@ -232,7 +234,9 @@ def build_deidentification_deidentify_text_request(**kwargs: Any) -> HttpRequest
     return HttpRequest(method="POST", url=_url, params=_params, headers=_headers, **kwargs)
 
 
-class DeidentificationClientOperationsMixin(DeidentificationClientMixinABC):
+class _DeidentificationClientOperationsMixin(
+    ClientMixinABC[PipelineClient[HttpRequest, HttpResponse], DeidentificationClientConfiguration]
+):
 
     @distributed_trace
     def get_job(self, job_name: str, **kwargs: Any) -> _models.DeidentificationJob:
@@ -518,7 +522,7 @@ def get_long_running_output(pipeline_response):
     @distributed_trace
     def _list_jobs_internal(
         self, *, continuation_token_parameter: Optional[str] = None, **kwargs: Any
-    ) -> Iterable["_models.DeidentificationJob"]:
+    ) -> ItemPaged["_models.DeidentificationJob"]:
         """List de-identification jobs.
 
         Resource list operation template.
@@ -610,7 +614,7 @@ def get_next(next_link=None):
     @distributed_trace
     def _list_job_documents_internal(
         self, job_name: str, *, continuation_token_parameter: Optional[str] = None, **kwargs: Any
-    ) -> Iterable["_models.DeidentificationDocumentDetails"]:
+    ) -> ItemPaged["_models.DeidentificationDocumentDetails"]:
         """List processed documents within a job.
 
         Resource list operation template.