diff --git a/assemblyai/__version__.py b/assemblyai/__version__.py index d6a282f..cbdbd05 100644 --- a/assemblyai/__version__.py +++ b/assemblyai/__version__.py @@ -1 +1 @@ -__version__ = "1.10.12" +__version__ = "1.10.15" diff --git a/assemblyai/types.py b/assemblyai/types.py index 4c36780..24db672 100644 --- a/assemblyai/types.py +++ b/assemblyai/types.py @@ -324,6 +324,10 @@ class RedactPiiAudioOptions(BaseModel): None, description="Override the default audio redaction method (beep) with an alternative (silence).", ) + return_redacted_no_speech_audio: Optional[bool] = Field( + None, + description="If True, also return a redacted audio URL for audio in which no speech is detected. By default one is returned only when speech is detected. Requires `redact_pii_audio`.", + ) class EntityType(str, Enum): @@ -668,6 +672,10 @@ class LanguageDetectionOptions(BaseModel): None, description='Controls behavior when language confidence is below threshold. Either "error" (default) or "fallback".', ) + on_no_speech_detected: Optional[str] = Field( + None, + description='Controls behavior when no speech is detected in the audio. Either "error" (default), which fails the transcript, or "fallback", which completes it with an empty text and the `fallback_language`. "fallback" requires `fallback_language` to be a specific language code.', + ) swiss_german: Optional[bool] = Field( None, description="If True, route German language requests as Swiss German audio. Only applies when language_detection is enabled and German is detected.", @@ -994,6 +1002,10 @@ class SpeakerOptions(BaseModel): None, description="Diarization method for long files. Options: standard (default), experimental", ) + include_speaker_confidence: Optional[bool] = Field( + None, + description="If True, the response includes a `speaker_confidence` for each word and each utterance", + ) if pydantic_v2: @@ -1075,6 +1087,8 @@ class RawTranscriptionConfig(BaseModel): "The replacement logic for detected PII." redact_pii_return_unredacted: Optional[bool] = None "If `redact_pii` is enabled, also return the unredacted text/words/utterances alongside the redacted fields." + redact_static_entities: Optional[Dict[str, List[str]]] = None + "A map of redaction label to the exact terms to redact under it, on top of the PII policies. Requires `redact_pii`." speaker_labels: Optional[bool] = None "Enable Speaker Diarization." @@ -1258,6 +1272,7 @@ def __init__( Union[SpeechUnderstandingRequest, Dict[str, Any]] ] = None, domain: Optional[str] = None, + redact_static_entities: Optional[Dict[str, List[str]]] = None, ) -> None: """ Args: @@ -1307,6 +1322,7 @@ def __init__( remove_audio_tags: When set to 'all', removes all bracketed audio/speaker tags from the transcript. Only supported for Universal-3 Pro. keyterms_prompt_options: Options for controlling keyterms boosting behavior when using `keyterms_prompt`. domain: The domain to use for the transcription (e.g. 'medical-v1'). + redact_static_entities: A map of redaction label to the exact terms to redact under it (e.g. `{"INTERNAL_TOOL": ["Bearclaw"]}`), on top of the PII policies. Requires `redact_pii=True`. """ self._raw_transcription_config = ( raw_transcription_config @@ -1340,6 +1356,7 @@ def __init__( redact_pii_policies, redact_pii_sub, redact_pii_return_unredacted, + redact_static_entities, ) self.set_speaker_diarization(speaker_labels, speakers_expected, speaker_options) self.set_content_safety(content_safety, content_safety_confidence) @@ -1632,6 +1649,12 @@ def redact_pii_return_unredacted(self) -> Optional[bool]: return self._raw_transcription_config.redact_pii_return_unredacted + @property + def redact_static_entities(self) -> Optional[Dict[str, List[str]]]: + "Returns the map of redaction label to the exact terms redacted under it." + + return self._raw_transcription_config.redact_static_entities + @property def speaker_labels(self) -> Optional[bool]: "Returns the status of the Speaker Diarization feature." @@ -2035,6 +2058,7 @@ def set_redact_pii( policies: Optional[List[PIIRedactionPolicy]] = None, substitution: Optional[PIISubstitutionPolicy] = None, return_unredacted: Optional[bool] = None, + static_entities: Optional[Dict[str, List[str]]] = None, ) -> Self: """ Enables Personal Identifiable Information (PII) Redaction feature. @@ -2047,6 +2071,7 @@ def set_redact_pii( policies: A list of PII redaction policies to enable. substitution: The replacement logic for detected PII (`PIISubstutionPolicy.hash` by default). return_unredacted: Also return the unredacted text/words/utterances on the transcript response. Only valid when redaction is enabled. + static_entities: A map of redaction label to the exact terms to redact under it (e.g. `{"INTERNAL_TOOL": ["Bearclaw"]}`), on top of `policies`. Only valid when redaction is enabled. """ if not enable: @@ -2057,6 +2082,7 @@ def set_redact_pii( self._raw_transcription_config.redact_pii_policies = None self._raw_transcription_config.redact_pii_sub = None self._raw_transcription_config.redact_pii_return_unredacted = None + self._raw_transcription_config.redact_static_entities = None return self @@ -2070,6 +2096,7 @@ def set_redact_pii( self._raw_transcription_config.redact_pii_policies = policies self._raw_transcription_config.redact_pii_sub = substitution self._raw_transcription_config.redact_pii_return_unredacted = return_unredacted + self._raw_transcription_config.redact_static_entities = static_entities return self @@ -2157,6 +2184,7 @@ def set_language_detection( fallback_language: Optional[str] = None, on_low_language_confidence: Optional[str] = None, localization: Optional[List[str]] = None, + on_no_speech_detected: Optional[str] = None, ) -> Self: """ Enable Automatic Language Detection with optional configuration. @@ -2168,6 +2196,7 @@ def set_language_detection( fallback_language: The language to fallback to if detection fails. on_low_language_confidence: Controls behavior when language confidence is below threshold. Either "error" (default) or "fallback". localization: Locale codes (e.g. ["en_au"]) to render detected English in a regional spelling variant. Supported values are "en_au" and "en_uk". + on_no_speech_detected: Controls behavior when no speech is detected. Either "error" (default) or "fallback", which needs `fallback_language` to be a specific language code. """ if not enable: @@ -2186,6 +2215,7 @@ def set_language_detection( or fallback_language or on_low_language_confidence or localization + or on_no_speech_detected ): self._raw_transcription_config.language_detection_options = ( LanguageDetectionOptions( @@ -2193,6 +2223,7 @@ def set_language_detection( fallback_language=fallback_language, on_low_language_confidence=on_low_language_confidence, localization=localization, + on_no_speech_detected=on_no_speech_detected, ) ) @@ -2286,6 +2317,8 @@ class Word(BaseModel): confidence: float speaker: Optional[str] = None channel: Optional[str] = None + speaker_confidence: Optional[float] = None + "The confidence in the speaker label, between 0 and 1. Returned for words and utterances only when `speaker_options.include_speaker_confidence` was set." # This is a workaround to address an issue where sentiment_analysis_results # may return contains sentiments where `start` is null. @@ -2537,6 +2570,8 @@ class BaseTranscript(BaseModel): "The replacement logic for detected PII." redact_pii_return_unredacted: Optional[bool] = None "If `redact_pii` is enabled, also return the unredacted text/words/utterances alongside the redacted fields." + redact_static_entities: Optional[Dict[str, List[str]]] = None + "A map of redaction label to the exact terms to redact under it, on top of the PII policies. Requires `redact_pii`." speaker_labels: Optional[bool] = None "Enable Speaker Diarization." diff --git a/tests/unit/test_language_detection_options.py b/tests/unit/test_language_detection_options.py index af6c337..7495b48 100644 --- a/tests/unit/test_language_detection_options.py +++ b/tests/unit/test_language_detection_options.py @@ -1,4 +1,10 @@ +from pytest_httpx import HTTPXMock + import assemblyai as aai +import tests.unit.unit_test_utils as unit_test_utils +from tests.unit import factories + +aai.settings.api_key = "test" def test_language_detection_options_creation(): @@ -240,3 +246,65 @@ def test_localization_default_none(): assert options.localization is None assert "localization" not in options.dict(exclude_none=True) + + +def test_language_detection_options_with_on_no_speech_detected(): + """Test that LanguageDetectionOptions accepts on_no_speech_detected.""" + assert aai.LanguageDetectionOptions().on_no_speech_detected is None + + options = aai.LanguageDetectionOptions( + fallback_language="en", + on_no_speech_detected="fallback", + ) + + assert options.fallback_language == "en" + assert options.on_no_speech_detected == "fallback" + + +def test_set_language_detection_with_on_no_speech_detected(): + """Test the set_language_detection method with on_no_speech_detected.""" + config = aai.TranscriptionConfig().set_language_detection( + fallback_language="en", + on_no_speech_detected="fallback", + ) + + assert config.language_detection is True + assert config.language_detection_options.fallback_language == "en" + assert config.language_detection_options.on_no_speech_detected == "fallback" + + +def test_set_language_detection_on_no_speech_detected_only(): + """Test set_language_detection with only the on_no_speech_detected parameter.""" + config = aai.TranscriptionConfig().set_language_detection( + on_no_speech_detected="error" + ) + + assert config.language_detection is True + assert config.language_detection_options is not None + assert config.language_detection_options.on_no_speech_detected == "error" + + +def test_on_no_speech_detected_in_request(httpx_mock: HTTPXMock): + """ + Tests that `on_no_speech_detected` reaches the request body, so audio with + no speech completes with the fallback language as the caller asked. + """ + request_body, _ = unit_test_utils.submit_mock_transcription_request( + httpx_mock, + mock_response=factories.generate_dict_factory( + factories.TranscriptCompletedResponseFactory + )(), + config=aai.TranscriptionConfig( + language_detection=True, + language_detection_options={ + "fallback_language": "en", + "on_no_speech_detected": "fallback", + }, + ), + ) + + assert request_body.get("language_detection") is True + assert request_body.get("language_detection_options") == { + "fallback_language": "en", + "on_no_speech_detected": "fallback", + } diff --git a/tests/unit/test_redact_pii.py b/tests/unit/test_redact_pii.py index 5a73e2c..81d861f 100644 --- a/tests/unit/test_redact_pii.py +++ b/tests/unit/test_redact_pii.py @@ -152,6 +152,40 @@ def test_redact_pii_audio_options_excluded_when_disabled(httpx_mock: HTTPXMock): assert request_body.get("redact_pii_audio_options") is None +@pytest.mark.parametrize( + "audio_options", + [ + aai.RedactPiiAudioOptions(return_redacted_no_speech_audio=True), + {"return_redacted_no_speech_audio": True}, + ], + ids=["model", "dict"], +) +def test_redact_pii_audio_options_return_redacted_no_speech_audio( + httpx_mock: HTTPXMock, audio_options +): + """ + Tests that `return_redacted_no_speech_audio` reaches the request body, + whether the options are given as a `RedactPiiAudioOptions` or as a dict. + """ + request_body, _ = unit_test_utils.submit_mock_transcription_request( + httpx_mock, + mock_response=factories.generate_dict_factory( + TranscriptWithPIIRedactionResponseFactory + )(), + config=aai.TranscriptionConfig( + redact_pii=True, + redact_pii_audio=True, + redact_pii_audio_options=audio_options, + redact_pii_policies=[aai.types.PIIRedactionPolicy.person_name], + ), + ) + + assert request_body.get("redact_pii_audio") is True + assert request_body.get("redact_pii_audio_options") == { + "return_redacted_no_speech_audio": True, + } + + def test_redact_pii_fails_without_policies(httpx_mock: HTTPXMock): """ Tests that enabling `redact_pii` without specifying any policies @@ -254,6 +288,99 @@ def test_redact_pii_return_unredacted_cleared_on_disable(): assert config.redact_pii_return_unredacted is None +_STATIC_ENTITIES = {"INTERNAL_TOOL": ["Bearclaw", "Cubclaw"]} + + +def test_redact_static_entities_default_absent(httpx_mock: HTTPXMock): + """ + Tests that `redact_static_entities` is absent from the request body when + not set, even when `redact_pii` is enabled. + """ + request_body, _ = unit_test_utils.submit_mock_transcription_request( + httpx_mock, + mock_response=factories.generate_dict_factory( + TranscriptWithPIIRedactionResponseFactory + )(), + config=aai.TranscriptionConfig( + redact_pii=True, + redact_pii_policies=[aai.types.PIIRedactionPolicy.date], + ), + ) + + assert "redact_static_entities" not in request_body + + +def test_redact_static_entities_in_request_from_constructor(httpx_mock: HTTPXMock): + """ + Tests that `redact_static_entities` given to `TranscriptionConfig` reaches + the request body. + """ + config = aai.TranscriptionConfig( + redact_pii=True, + redact_pii_policies=[aai.types.PIIRedactionPolicy.date], + redact_static_entities=_STATIC_ENTITIES, + ) + + request_body, _ = unit_test_utils.submit_mock_transcription_request( + httpx_mock, + mock_response=factories.generate_dict_factory( + TranscriptWithPIIRedactionResponseFactory + )(), + config=config, + ) + + assert config.redact_static_entities == _STATIC_ENTITIES + assert request_body.get("redact_pii") is True + assert request_body.get("redact_static_entities") == _STATIC_ENTITIES + + +def test_redact_static_entities_in_request_from_set_redact_pii(httpx_mock: HTTPXMock): + """ + Tests that `static_entities` on `set_redact_pii` puts + `redact_static_entities` in the request body. + """ + config = aai.TranscriptionConfig().set_redact_pii( + policies=[aai.types.PIIRedactionPolicy.date], + static_entities=_STATIC_ENTITIES, + ) + + request_body, _ = unit_test_utils.submit_mock_transcription_request( + httpx_mock, + mock_response=factories.generate_dict_factory( + TranscriptWithPIIRedactionResponseFactory + )(), + config=config, + ) + + assert request_body.get("redact_static_entities") == _STATIC_ENTITIES + + +def test_redact_static_entities_cleared_on_disable(): + """ + Tests that `set_redact_pii(enable=False)` clears the static entities, which + the API rejects without `redact_pii`. + """ + config = aai.TranscriptionConfig().set_redact_pii( + policies=[aai.types.PIIRedactionPolicy.date], + static_entities=_STATIC_ENTITIES, + ) + assert config.redact_static_entities == _STATIC_ENTITIES + + config.set_redact_pii(enable=False) + assert config.redact_static_entities is None + + +def test_redact_static_entities_ignored_without_redact_pii(): + """ + Tests that `redact_static_entities` without `redact_pii` is not sent, + as for the other redaction options. + """ + config = aai.TranscriptionConfig(redact_static_entities=_STATIC_ENTITIES) + + assert config.redact_static_entities is None + assert "redact_static_entities" not in config.raw.dict(exclude_none=True) + + def test_unredacted_response_fields_surface_on_transcript(httpx_mock: HTTPXMock): """ Tests that `unredacted_text`, `unredacted_words`, and `unredacted_utterances` diff --git a/tests/unit/test_speaker_options.py b/tests/unit/test_speaker_options.py index 3fe937e..d273ae2 100644 --- a/tests/unit/test_speaker_options.py +++ b/tests/unit/test_speaker_options.py @@ -1,6 +1,11 @@ import pytest +from pytest_httpx import HTTPXMock import assemblyai as aai +import tests.unit.unit_test_utils as unit_test_utils +from tests.unit import factories + +aai.settings.api_key = "test" def test_speaker_options_creation(): @@ -202,3 +207,75 @@ def test_transcription_config_with_all_speaker_options(): assert config.speaker_options.use_two_stage_clustering is False assert config.speaker_options.short_file_diarization_method == "conservative" assert config.speaker_options.long_file_diarization_method == "experimental" + + +def test_speaker_options_include_speaker_confidence(): + """Test that SpeakerOptions accepts include_speaker_confidence.""" + assert aai.SpeakerOptions().include_speaker_confidence is None + + speaker_options = aai.SpeakerOptions(include_speaker_confidence=True) + assert speaker_options.include_speaker_confidence is True + + +@pytest.mark.parametrize( + "speaker_options", + [ + aai.SpeakerOptions(include_speaker_confidence=True), + {"include_speaker_confidence": True}, + ], + ids=["model", "dict"], +) +def test_include_speaker_confidence_in_request(httpx_mock: HTTPXMock, speaker_options): + """ + Tests that `include_speaker_confidence` reaches the request body, whether + the options are given as a `SpeakerOptions` or as a dict. + """ + request_body, _ = unit_test_utils.submit_mock_transcription_request( + httpx_mock, + mock_response=factories.generate_dict_factory( + factories.TranscriptCompletedResponseFactory + )(), + config=aai.TranscriptionConfig( + speaker_labels=True, + speaker_options=speaker_options, + ), + ) + + assert request_body.get("speaker_labels") is True + assert request_body.get("speaker_options") == {"include_speaker_confidence": True} + + +def test_speaker_confidence_surfaces_on_words_and_utterances(httpx_mock: HTTPXMock): + """ + Tests that the `speaker_confidence` the API returns per word and per + utterance is readable on the transcript, and is `None` where it is absent. + """ + word = {"text": "hello", "start": 0, "end": 500, "confidence": 0.99, "speaker": "A"} + mock_response = { + **factories.generate_dict_factory( + factories.TranscriptCompletedResponseFactory + )(), + "words": [{**word, "speaker_confidence": 0.97}, word], + "utterances": [ + { + **word, + "speaker_confidence": 0.91, + "words": [{**word, "speaker_confidence": 0.97}], + } + ], + } + + _, transcript = unit_test_utils.submit_mock_transcription_request( + httpx_mock, + mock_response=mock_response, + config=aai.TranscriptionConfig( + speaker_labels=True, + speaker_options=aai.SpeakerOptions(include_speaker_confidence=True), + ), + ) + + assert transcript.words[0].speaker_confidence == 0.97 + assert transcript.words[1].speaker_confidence is None + assert transcript.utterances[0].speaker_confidence == 0.91 + assert transcript.utterances[0].words[0].speaker_confidence == 0.97 + assert transcript.json_response["words"][0]["speaker_confidence"] == 0.97