diff --git a/docs/source/redact/redacting_text.rst b/docs/source/redact/redacting_text.rst index 4528102..4c3f86d 100644 --- a/docs/source/redact/redacting_text.rst +++ b/docs/source/redact/redacting_text.rst @@ -65,8 +65,6 @@ This produces the following output: "new_text": "[ORGANIZATION_P5XLAH]" } -You can also record ``redact`` calls, so that you can view and analyze results in the Textual application. To learn more, go to :ref:`record-api-call-section` - Bulk redact raw text --------------------- In the same way that you use the ``redact`` method to redact strings, you can use the ``redact_bulk`` method to redact many strings at the same time. @@ -138,13 +136,14 @@ This produces the following output: .. _record-api-call-section: -Recording API requests ----------------------- -When you use the :meth:`redact` method to redact text, you can optionally record these requests to view and analyze later in the Textual application. +Tagging API requests for auditing +--------------------------------- +When you use the :meth:`redact` method to redact text, and Request Auditor is enabled for your organization, you can optionally tag requests to assist +with looking up requests selected for auditing in the Textual application. The ``redact`` method takes an optional ``record_options`` (:class:`RecordApiRequestOptions`) argument. -To record an API request: +To specify tags for an API request: .. code-block:: python @@ -154,16 +153,20 @@ To record an API request: ner = TextualNer() ner.redact("My name is John Doe", record_options=RecordApiRequestOptions( - record=True, - retention_time_in_hours=1, tags=["my_first_request"]) ) -The above code runs the redaction in the same way as any other redaction request, and then records the API request and its results. +The above code runs the redaction in the same way as any other redaction request. It is sampled based upon Request Auditor settings defined in the Textual application. -The request itself is automatically purged after 1 hour. +You can view the results from the **Request Auditor** page in Textual. -You can view the results from the **API Explorer** page in Textual. The retention time for the results specified in hours and can be set to a value between 1 and 720. +To opt out of recording a request, set ``record`` to ``False``. The request is then never recorded, regardless of the Request Auditor settings defined for your organization: + +.. code-block:: python + + ner.redact("My name is John Doe", record_options=RecordApiRequestOptions( + record=False) + ) Replacing values in your redaction response diff --git a/tonic_textual/classes/record_api_request_options.py b/tonic_textual/classes/record_api_request_options.py index b396864..61452f0 100644 --- a/tonic_textual/classes/record_api_request_options.py +++ b/tonic_textual/classes/record_api_request_options.py @@ -1,39 +1,35 @@ -from typing import List +from typing import List, Optional class RecordApiRequestOptions(dict): """ - Class to denote whether to record an API request. + Class to denote whether/how to record an API request for the Request Auditor. Parameters ---------- - record : bool - Whether to record the request. - - retention_time_in_hours: int - The number of hours to store the request. The request is then purged automatically. + record : Optional[bool] + Whether to record the request. When True or None (the default), the request is + recorded based on the Request Auditor settings defined for your organization. When + False, the request is never recorded, regardless of the Request Auditor settings. tags : List[str] - A list of tags to assign to the request. Used to help search for the request on the API Explorer page. The default is the empty list [], which corresponds to assigning no tags to the request. + A list of tags to assign to the request. Used to help search for the request on the Request Auditor page. The default is the empty list [], which corresponds to assigning no tags to the request. """ def __init__( - self, record: bool, retention_time_in_hours: int, tags: List[str] = [] + self, record: Optional[bool] = None, tags: List[str] = [] ): self.record = record - self.retention_time_in_hours = retention_time_in_hours self.tags = tags dict.__init__( self, record=record, - retention_time_in_hours=retention_time_in_hours, tags=tags, ) def to_dict(self): return { "record": self.record, - "retention_time_in_hours": self.retention_time_in_hours, "tags": self.tags, } diff --git a/tonic_textual/generator_utils.py b/tonic_textual/generator_utils.py index e3cad75..34feb57 100644 --- a/tonic_textual/generator_utils.py +++ b/tonic_textual/generator_utils.py @@ -14,13 +14,12 @@ from tonic_textual.classes.generator_metadata.person_age_generator_metadata import PersonAgeGeneratorMetadata from tonic_textual.classes.generator_metadata.phone_number_generator_metadata import PhoneNumberGeneratorMetadata from tonic_textual.classes.record_api_request_options import RecordApiRequestOptions -from tonic_textual.classes.tonic_exception import BadArgumentsException from tonic_textual.enums.custom_entity_ranking_mode import CustomEntityRankingMode from tonic_textual.enums.generator_type import GeneratorType from tonic_textual.enums.pii_state import PiiState from tonic_textual.enums.pii_type import PiiType -default_record_options = RecordApiRequestOptions(False, 0, []) +default_record_options = RecordApiRequestOptions(tags=[]) def utf16len(c): """Returns the length of the single character 'c' @@ -360,7 +359,7 @@ def generate_redact_payload( payload["llmClassificationPolicy"] = ( "Enabled" if enable_llm_classification else "Disabled" ) - + if custom_entity_ranking_modes is not None: payload["customEntityRankingModes"] = { k: CustomEntityRankingMode(v).value @@ -378,19 +377,10 @@ def generate_redact_payload( for k, v in label_allow_lists.items() } - if record_options is not None and record_options.record: - if ( - record_options.retention_time_in_hours <= 0 - or record_options.retention_time_in_hours > 720 - ): - raise BadArgumentsException( - "The retention time must be set between 1 and 720 hours" - ) - + if record_options is not None: record_payload = { - "retentionTimeInHours": record_options.retention_time_in_hours, + "record": record_options.record, "tags": record_options.tags, - "record": True, } payload["recordApiRequestOptions"] = record_payload else: diff --git a/tonic_textual/redact_api.py b/tonic_textual/redact_api.py index e8f9fbe..ab640ac 100644 --- a/tonic_textual/redact_api.py +++ b/tonic_textual/redact_api.py @@ -392,9 +392,11 @@ def redact( entity type and is included in the redaction or synthesis. record_options: RecordApiRequestOptions - A value to record the API request and results for analysis in the - Textual application. The default value is to not record the API - request. Must specify a time between 1 and 720 hours (inclusive). + Options that control recording of the API request for the Request Auditor. + By default, the request is recorded based on the Request Auditor settings + defined for your organization. Set ``record=False`` to opt out of recording + this request regardless of those settings. Use ``tags`` to help search for + the request on the Request Auditor page. custom_entities: Optional[List[str]] A list of custom entity type identifiers to include. Each custom @@ -955,9 +957,11 @@ def redact_html( are not specified in the generator config. record_options: RecordApiRequestOptions - A value to record the API request and results for analysis in the - Textual application. The default value is to not record the API - request. Must specify a time between 1 and 720 hours (inclusive). + Options that control recording of the API request for the Request Auditor. + By default, the request is recorded based on the Request Auditor settings + defined for your organization. Set ``record=False`` to opt out of recording + this request regardless of those settings. Use ``tags`` to help search for + the request on the Request Auditor page. enable_llm_classification: Optional[bool] = None When True, an LLM reviews the detected entities to remove false