From 41d6bfbb3d60220e439cd43d1c6b125300bc3125 Mon Sep 17 00:00:00 2001 From: Carter Campbell Date: Mon, 16 Nov 2026 17:49:02 -0700 Subject: [PATCH 1/2] fix(streaming): send mode mid-session and reject unknown session params RealTimeSessionParameters had no `mode` field and pydantic's default extra="ignore" dropped it, so set_params(mode="manual") sent nothing for mode. Add `mode` and `continuous_partials` (both accepted by the server's UpdateConfiguration), forbid unknown fields on the session/connect parameter models, and add a keyword `update_configuration(**kwargs)` wrapper on StreamingClient and AsyncStreamingClient. Fixes #296 Co-Authored-By: Claude Opus 5.5 --- CLAUDE.md | 5 +- assemblyai/__version__.py | 2 +- assemblyai/streaming/v3/async_client.py | 5 + assemblyai/streaming/v3/client.py | 5 + assemblyai/streaming/v3/models.py | 40 ++++--- tests/unit/test_streaming.py | 142 +++++++++++++++++++++++- tests/unit/test_streaming_async.py | 90 +++++++++++++++ 7 files changed, 273 insertions(+), 16 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index a919fbd..1f85096 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -414,7 +414,10 @@ RealTimeParameters( Use `pcm_s16le` (default) + `sample_rate=16000` for microphone capture. `agent_context` (like `prompt`) can also be updated mid-stream after each agent -turn: `client.set_params(RealTimeSessionParameters(agent_context="..."))`. +turn: `client.set_params(RealTimeSessionParameters(agent_context="..."))`, or the +keyword form `client.update_configuration(agent_context="...")`. `mode` (including +`"manual"`) is updatable the same way. `RealTimeSessionParameters` and +`RealTimeParameters` reject unknown fields with a validation error. **Error codes**: `RealTimeErrorCodes` is a `dict[int, str]` mapping wire codes to human messages. Use `.get(...)` for lookup — not enum-style attribute access: ```python diff --git a/assemblyai/__version__.py b/assemblyai/__version__.py index 5ffe4c1..f9a3061 100644 --- a/assemblyai/__version__.py +++ b/assemblyai/__version__.py @@ -1 +1 @@ -__version__ = "1.10.10" +__version__ = "1.10.11" diff --git a/assemblyai/streaming/v3/async_client.py b/assemblyai/streaming/v3/async_client.py index 8a2b9cc..f2c02eb 100644 --- a/assemblyai/streaming/v3/async_client.py +++ b/assemblyai/streaming/v3/async_client.py @@ -308,6 +308,11 @@ async def set_params(self, params: RealTimeSessionParameters) -> None: message = UpdateConfiguration(**message_dict) await write_queue.put(message) + async def update_configuration(self, **kwargs: Any) -> None: + """Keyword form of `set_params`: `update_configuration(mode="manual")` + equals `set_params(RealTimeSessionParameters(mode="manual"))`.""" + await self.set_params(RealTimeSessionParameters(**kwargs)) + async def force_endpoint(self) -> None: write_queue, stop_event = self._ensure_connected("force_endpoint") if stop_event.is_set(): diff --git a/assemblyai/streaming/v3/client.py b/assemblyai/streaming/v3/client.py index fa78e05..8f492ab 100644 --- a/assemblyai/streaming/v3/client.py +++ b/assemblyai/streaming/v3/client.py @@ -239,6 +239,11 @@ def set_params(self, params: RealTimeSessionParameters): message = UpdateConfiguration(**message_dict) self._write_queue.put(message) + def update_configuration(self, **kwargs: Any) -> None: + """Keyword form of `set_params`: `update_configuration(mode="manual")` + equals `set_params(RealTimeSessionParameters(mode="manual"))`.""" + self.set_params(RealTimeSessionParameters(**kwargs)) + def force_endpoint(self): message = ForceEndpoint() self._write_queue.put(message) diff --git a/assemblyai/streaming/v3/models.py b/assemblyai/streaming/v3/models.py index 956de19..927c1f9 100644 --- a/assemblyai/streaming/v3/models.py +++ b/assemblyai/streaming/v3/models.py @@ -4,7 +4,7 @@ try: # pydantic v2 import - from pydantic import BaseModel, Field, model_validator + from pydantic import BaseModel, ConfigDict, Field, model_validator pydantic_v2 = True except ImportError: @@ -168,7 +168,32 @@ class KeepAlive(BaseModel): type: Literal["KeepAlive"] = "KeepAlive" +class StreamingMode(str, Enum): + max_accuracy = "max_accuracy" + min_latency = "min_latency" + balanced = "balanced" + manual = "manual" + + def __str__(self): + return self.value + + class RealTimeSessionParameters(BaseModel): + """Session settings that `set_params` sends mid-session as an + `UpdateConfiguration` message. `RealTimeParameters` extends this model with + the connect-only settings. + + Unknown fields raise a validation error instead of being dropped. + """ + + if pydantic_v2: + model_config = ConfigDict(extra="forbid") + else: + + class Config: + extra = "forbid" + + mode: Optional[StreamingMode] = None end_of_turn_confidence_threshold: Optional[float] = None min_end_of_turn_silence_when_confident: Optional[int] = ( None # Deprecated: Use min_turn_silence instead @@ -185,6 +210,7 @@ class RealTimeSessionParameters(BaseModel): turn_left_pad_ms: Optional[int] = None language_codes: Optional[List[str]] = None session_heartbeat: Optional[bool] = None + continuous_partials: Optional[bool] = None # Opt in to Silence messages during silence (U3Pro only). When True, the # server emits a Silence message roughly once per second while no speech is # being transcribed, carrying `start_ms` and `end_ms`, the audio positions @@ -247,16 +273,6 @@ def __str__(self): return self.value -class StreamingMode(str, Enum): - max_accuracy = "max_accuracy" - min_latency = "min_latency" - balanced = "balanced" - manual = "manual" - - def __str__(self): - return self.value - - class StreamingPiiSubstitution(str, Enum): hash = "hash" entity_name = "entity_name" @@ -361,13 +377,11 @@ class RealTimeParameters(RealTimeSessionParameters): # Deprecated: use voice_focus / voice_focus_threshold instead. noise_suppression_model: Optional[NoiseSuppressionModel] = None noise_suppression_threshold: Optional[float] = None - continuous_partials: Optional[bool] = None customer_support_audio_capture: Optional[bool] = None include_partial_turns: Optional[bool] = None redact_pii: Optional[bool] = None redact_pii_policies: Optional[List[StreamingPiiPolicy]] = None redact_pii_sub: Optional[StreamingPiiSubstitution] = None - mode: Optional[StreamingMode] = None if pydantic_v2: diff --git a/tests/unit/test_streaming.py b/tests/unit/test_streaming.py index 7726ed7..d8e25d7 100644 --- a/tests/unit/test_streaming.py +++ b/tests/unit/test_streaming.py @@ -26,10 +26,11 @@ StreamingParameters, StreamingPiiPolicy, StreamingPiiSubstitution, + StreamingSessionParameters, TurnEvent, Word, ) -from assemblyai.streaming.v3._base import _build_uri +from assemblyai.streaming.v3._base import _build_uri, _dump_model_json from assemblyai.streaming.v3.models import ( HeartbeatEvent, KeepAlive, @@ -2768,3 +2769,142 @@ def test_unknown_domain_is_rejected(): speech_model=SpeechModel.universal_3_5_pro, domain="vet", ) + + +def _connected_client_without_io(mocker: MockFixture) -> StreamingClient: + mocker.patch( + "assemblyai.streaming.v3.client.websocket_connect", + return_value=None, + ) + _disable_rw_threads(mocker) + client = StreamingClient( + StreamingClientOptions(api_key="test", api_host="api.example.com") + ) + client.connect( + StreamingParameters( + sample_rate=16000, + speech_model=SpeechModel.universal_3_5_pro, + ) + ) + return client + + +def _enqueued_update_payload(client: StreamingClient) -> dict: + assert client._write_queue.qsize() == 1 + message = client._write_queue.get(timeout=1) + assert isinstance(message, UpdateConfiguration) + return json.loads(_dump_model_json(message)) + + +def test_set_params_sends_mode_in_update_configuration(mocker: MockFixture): + # Given: a connected client + client = _connected_client_without_io(mocker) + + # When: set_params switches to manual mode with a new silence cap + client.set_params( + StreamingSessionParameters( + mode=StreamingMode.manual, + max_turn_silence=1500, + ) + ) + + # Then: the UpdateConfiguration frame carries both fields + assert _enqueued_update_payload(client) == { + "type": "UpdateConfiguration", + "mode": "manual", + "max_turn_silence": 1500, + } + + +def test_set_params_accepts_mode_as_string(mocker: MockFixture): + # Given: a connected client + client = _connected_client_without_io(mocker) + + # When: mode is passed as its wire string + client.set_params(StreamingSessionParameters(mode="max_accuracy")) + + # Then: it is serialized unchanged + assert _enqueued_update_payload(client)["mode"] == "max_accuracy" + + +def test_set_params_sends_continuous_partials(mocker: MockFixture): + # Given: a connected client + client = _connected_client_without_io(mocker) + + # When: continuous_partials is toggled mid-session + client.set_params(StreamingSessionParameters(continuous_partials=False)) + + # Then: the frame carries the explicit False + assert _enqueued_update_payload(client) == { + "type": "UpdateConfiguration", + "continuous_partials": False, + } + + +def test_set_params_without_mode_sends_only_set_fields(mocker: MockFixture): + # Given: a connected client + client = _connected_client_without_io(mocker) + + # When: set_params is called with pre-existing fields only + client.set_params( + StreamingSessionParameters( + end_of_turn_confidence_threshold=0.5, + min_turn_silence=200, + keyterms_prompt=["AssemblyAI"], + ) + ) + + # Then: exactly those fields are sent, with no mode key + assert _enqueued_update_payload(client) == { + "type": "UpdateConfiguration", + "end_of_turn_confidence_threshold": 0.5, + "min_turn_silence": 200, + "keyterms_prompt": ["AssemblyAI"], + } + + +def test_session_parameters_reject_unknown_field(): + # When/Then: a misspelled field raises instead of being dropped + with pytest.raises(ValueError, match="max_turn_silense"): + StreamingSessionParameters(max_turn_silense=1500) + + +def test_session_parameters_reject_unknown_mode(): + # When/Then: a mode value the API does not define raises + with pytest.raises(ValueError): + StreamingSessionParameters(mode="warpspeed") + + +def test_streaming_parameters_reject_unknown_field(): + # When/Then: connect parameters reject unknown fields too + with pytest.raises(ValueError, match="sampel_rate"): + StreamingParameters(sample_rate=16000, sampel_rate=8000) + + +def test_update_configuration_sends_keyword_fields(mocker: MockFixture): + # Given: a connected client + client = _connected_client_without_io(mocker) + + # When: update_configuration is called with keyword arguments + client.update_configuration(mode="manual", max_turn_silence=1500) + + # Then: the same frame as set_params is enqueued + assert _enqueued_update_payload(client) == { + "type": "UpdateConfiguration", + "mode": "manual", + "max_turn_silence": 1500, + } + + +def test_update_configuration_unknown_field_raises_and_sends_nothing( + mocker: MockFixture, +): + # Given: a connected client + client = _connected_client_without_io(mocker) + + # When/Then: an unknown keyword raises + with pytest.raises(ValueError, match="max_turn_silense"): + client.update_configuration(max_turn_silense=1500) + + # Then: nothing is enqueued + assert client._write_queue.qsize() == 0 diff --git a/tests/unit/test_streaming_async.py b/tests/unit/test_streaming_async.py index cdbe9bf..6548c98 100644 --- a/tests/unit/test_streaming_async.py +++ b/tests/unit/test_streaming_async.py @@ -1753,3 +1753,93 @@ async def test_stream_accepts_bytes_like_buffer(mocker: MockFixture, wrap): assert fake_ws.sent == [b"\x01\x02\x03", b"ab", b"cd"] await client.disconnect() + + +async def _wait_for_update_frames(fake_ws) -> list: + for _ in range(100): + update_frames = [ + s for s in fake_ws.sent if isinstance(s, str) and "UpdateConfiguration" in s + ] + if update_frames: + return update_frames + await asyncio.sleep(0.01) + return [] + + +async def test_set_params_sends_mode(mocker: MockFixture): + # Given: a connected async streaming client + fake_ws = _FakeAsyncWebSocket() + _patch_connect(mocker, fake_ws) + client = AsyncStreamingClient( + StreamingClientOptions(api_key="test", api_host="api.example.com") + ) + await client.connect(_default_params()) + + from assemblyai.streaming.v3.models import ( + StreamingMode, + StreamingSessionParameters, + ) + + # When: set_params switches to manual mode with a new silence cap + await client.set_params( + StreamingSessionParameters(mode=StreamingMode.manual, max_turn_silence=1500) + ) + + # Then: one UpdateConfiguration frame carries both fields + update_frames = await _wait_for_update_frames(fake_ws) + assert len(update_frames) == 1 + assert json.loads(update_frames[0]) == { + "type": "UpdateConfiguration", + "mode": "manual", + "max_turn_silence": 1500, + } + + await client.disconnect() + + +async def test_update_configuration_sends_keyword_fields(mocker: MockFixture): + # Given: a connected async streaming client + fake_ws = _FakeAsyncWebSocket() + _patch_connect(mocker, fake_ws) + client = AsyncStreamingClient( + StreamingClientOptions(api_key="test", api_host="api.example.com") + ) + await client.connect(_default_params()) + + # When: update_configuration is called with keyword arguments + await client.update_configuration(mode="balanced", continuous_partials=True) + + # Then: one UpdateConfiguration frame carries both fields + update_frames = await _wait_for_update_frames(fake_ws) + assert len(update_frames) == 1 + assert json.loads(update_frames[0]) == { + "type": "UpdateConfiguration", + "mode": "balanced", + "continuous_partials": True, + } + + await client.disconnect() + + +async def test_update_configuration_unknown_field_raises_and_sends_nothing( + mocker: MockFixture, +): + # Given: a connected async streaming client + fake_ws = _FakeAsyncWebSocket() + _patch_connect(mocker, fake_ws) + client = AsyncStreamingClient( + StreamingClientOptions(api_key="test", api_host="api.example.com") + ) + await client.connect(_default_params()) + + # When/Then: an unknown keyword raises + with pytest.raises(ValueError, match="max_turn_silense"): + await client.update_configuration(max_turn_silense=1500) + + # Then: no UpdateConfiguration frame is sent + await asyncio.sleep(0.05) + assert not [ + s for s in fake_ws.sent if isinstance(s, str) and "UpdateConfiguration" in s + ] + + await client.disconnect() From fb155b2b9a8cd51b00786ca1c6de8c6eab6595c5 Mon Sep 17 00:00:00 2001 From: Carter Campbell Date: Mon, 16 Nov 2026 18:01:54 -0700 Subject: [PATCH 2/2] fix(streaming): forbid unknown fields mid-session only, add max_turn_duration Connect parameters drop unknown fields with a logged warning instead of raising; session parameters still raise. Add max_turn_duration (accepted at connect and mid-session). set_params warns when format_turns or filter_profanity is set, since the server applies them only at connect, and still sends them. Fix README/CLAUDE.md, which said format_turns can be switched mid-session. Co-Authored-By: Claude Opus 5.5 --- CLAUDE.md | 7 +- README.md | 14 +-- assemblyai/streaming/v3/_base.py | 11 +++ assemblyai/streaming/v3/async_client.py | 2 + assemblyai/streaming/v3/client.py | 2 + assemblyai/streaming/v3/models.py | 40 +++++++++ tests/unit/test_streaming.py | 114 +++++++++++++++++++++++- tests/unit/test_streaming_async.py | 31 +++++++ 8 files changed, 209 insertions(+), 12 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 1f85096..f739d6f 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -416,8 +416,9 @@ Use `pcm_s16le` (default) + `sample_rate=16000` for microphone capture. `agent_context` (like `prompt`) can also be updated mid-stream after each agent turn: `client.set_params(RealTimeSessionParameters(agent_context="..."))`, or the keyword form `client.update_configuration(agent_context="...")`. `mode` (including -`"manual"`) is updatable the same way. `RealTimeSessionParameters` and -`RealTimeParameters` reject unknown fields with a validation error. +`"manual"`) and `max_turn_duration` are updatable the same way. +`RealTimeSessionParameters` rejects unknown fields with a validation error; +`RealTimeParameters` (connect) drops them with a logged warning. **Error codes**: `RealTimeErrorCodes` is a `dict[int, str]` mapping wire codes to human messages. Use `.get(...)` for lookup — not enum-style attribute access: ```python @@ -462,7 +463,7 @@ async with AsyncRealTimeTranscriber(RealTimeTranscriberOptions(token=token_from_ **Other gotchas**: - Don't feed `AsyncRealTimeTranscriber.stream()` from a sync generator that blocks (e.g. `time.sleep` pacing) — it starves the read task. Use an `async def` generator with `await asyncio.sleep(...)` instead. -- `format_turns=True` enables punctuation/casing on confirmed end-of-turns. Toggle mid-session via `client.set_params(RealTimeSessionParameters(format_turns=True))`. +- `format_turns=True` enables punctuation/casing on end-of-turns. Set it at connect: the server ignores `format_turns` and `filter_profanity` in a mid-session `UpdateConfiguration`, and `set_params` logs a warning when either is set. - `AsyncRealTimeTranscriber` used as `async with` calls `disconnect(terminate=True)` on normal block exit and `disconnect(terminate=False)` on exception — no explicit `disconnect()` needed inside the block. ## Text-to-Speech diff --git a/README.md b/README.md index 0d419b1..885864f 100644 --- a/README.md +++ b/README.md @@ -2003,16 +2003,20 @@ Common codes: `4001` Not Authorized, `4002` Insufficient Funds, `4029` Client se
Change settings mid-session -`set_params` updates an active session. Typical use: enable turn formatting (punctuation, casing) only on confirmed end-of-turn so partial transcripts stay raw: +`set_params` updates an active session. Typical use: switch a voice agent to manual turn detection and raise the silence cap mid-session: ```python -from assemblyai.streaming.v3 import RealTimeSessionParameters +from assemblyai.streaming.v3 import RealTimeSessionParameters, StreamingMode -def on_turn(client, event): - if event.end_of_turn and not event.turn_is_formatted: - client.set_params(RealTimeSessionParameters(format_turns=True)) +client.set_params( + RealTimeSessionParameters(mode=StreamingMode.manual, max_turn_silence=1500) +) +# Keyword form of the same call: +client.update_configuration(mode="manual", max_turn_silence=1500) ``` +Updatable mid-session: `mode`, `max_turn_duration`, `min_turn_silence`, `max_turn_silence`, `end_of_turn_confidence_threshold`, `vad_threshold`, `turn_left_pad_ms`, `keyterms_prompt`, `prompt`, `agent_context`, `interruption_delay`, `language_codes`, `continuous_partials`, `session_heartbeat`, and `acknowledge_silence`. An unknown field raises a validation error. `format_turns` and `filter_profanity` take effect only at connect; `set_params` sends them but logs a warning, and the server ignores them. + For voice agents, `force_endpoint()` flushes the current turn — useful when an external signal (UI button, barge-in detection) determines the user has stopped speaking before VAD does: ```python diff --git a/assemblyai/streaming/v3/_base.py b/assemblyai/streaming/v3/_base.py index 02b1f29..b0f71d5 100644 --- a/assemblyai/streaming/v3/_base.py +++ b/assemblyai/streaming/v3/_base.py @@ -93,6 +93,17 @@ def _normalize_min_turn_silence(params_dict: dict) -> dict: return params_dict +def _warn_connect_only_session_params(params_dict: dict) -> None: + """Warn for fields `set_params` sends that the server applies only at + connect. The fields are still sent.""" + for key in ("format_turns", "filter_profanity"): + if params_dict.get(key) is not None: + logger.warning( + f"`{key}` only takes effect at connect; the server ignores it " + "in a mid-session UpdateConfiguration." + ) + + def _normalize_voice_focus(params_dict: dict) -> dict: """Collapse `noise_suppression_model` / `noise_suppression_threshold` into `voice_focus` / `voice_focus_threshold` so only the new wire keys are sent. diff --git a/assemblyai/streaming/v3/async_client.py b/assemblyai/streaming/v3/async_client.py index f2c02eb..5e089f0 100644 --- a/assemblyai/streaming/v3/async_client.py +++ b/assemblyai/streaming/v3/async_client.py @@ -34,6 +34,7 @@ _normalize_min_turn_silence, _resolve_options, _user_agent, + _warn_connect_only_session_params, ) from .models import ( ErrorEvent, @@ -305,6 +306,7 @@ async def set_params(self, params: RealTimeSessionParameters) -> None: if stop_event.is_set(): return message_dict = _normalize_min_turn_silence(_dump_model(params)) + _warn_connect_only_session_params(message_dict) message = UpdateConfiguration(**message_dict) await write_queue.put(message) diff --git a/assemblyai/streaming/v3/client.py b/assemblyai/streaming/v3/client.py index 8f492ab..1b47f0c 100644 --- a/assemblyai/streaming/v3/client.py +++ b/assemblyai/streaming/v3/client.py @@ -24,6 +24,7 @@ _normalize_min_turn_silence, _resolve_options, _user_agent, + _warn_connect_only_session_params, ) from ._tls import _create_tls_context from .models import ( @@ -236,6 +237,7 @@ def stream( def set_params(self, params: RealTimeSessionParameters): message_dict = _normalize_min_turn_silence(_dump_model(params)) + _warn_connect_only_session_params(message_dict) message = UpdateConfiguration(**message_dict) self._write_queue.put(message) diff --git a/assemblyai/streaming/v3/models.py b/assemblyai/streaming/v3/models.py index 927c1f9..6ec4249 100644 --- a/assemblyai/streaming/v3/models.py +++ b/assemblyai/streaming/v3/models.py @@ -1,3 +1,4 @@ +import logging from datetime import datetime from enum import Enum from typing import Any, List, Literal, Optional, Union @@ -13,6 +14,8 @@ pydantic_v2 = False +logger = logging.getLogger(__name__) + class LLMGatewayMessage(BaseModel): role: str @@ -184,6 +187,8 @@ class RealTimeSessionParameters(BaseModel): the connect-only settings. Unknown fields raise a validation error instead of being dropped. + `format_turns` and `filter_profanity` take effect only at connect; the + server ignores them mid-session. """ if pydantic_v2: @@ -208,6 +213,8 @@ class Config: agent_context: Optional[str] = None interruption_delay: Optional[int] = None turn_left_pad_ms: Optional[int] = None + # Server-validated range: 16000-128000 ms. + max_turn_duration: Optional[int] = None language_codes: Optional[List[str]] = None session_heartbeat: Optional[bool] = None continuous_partials: Optional[bool] = None @@ -352,7 +359,40 @@ def __str__(self): return self.value +def _warn_unknown_connect_params(model_cls: Any, values: Any) -> None: + if not isinstance(values, dict): + return + fields = model_cls.model_fields if pydantic_v2 else model_cls.__fields__ + for key in values: + if key not in fields: + logger.warning( + f"Ignoring unknown streaming connection parameter `{key}`; " + "it is not sent to the server." + ) + + class RealTimeParameters(RealTimeSessionParameters): + """Connection parameters. Unknown fields are dropped with a warning.""" + + if pydantic_v2: + model_config = ConfigDict(extra="ignore") + + @model_validator(mode="before") + @classmethod + def _warn_unknown_fields(cls, values: Any) -> Any: + _warn_unknown_connect_params(cls, values) + return values + + else: + + class Config: + extra = "ignore" + + @root_validator(pre=True) + def _warn_unknown_fields(cls, values): + _warn_unknown_connect_params(cls, values) + return values + # Required for PCM encodings. May be omitted for Opus encodings # (opus, ogg_opus) — the stream is self-describing and the server # ignores the value. diff --git a/tests/unit/test_streaming.py b/tests/unit/test_streaming.py index d8e25d7..6e3bc0b 100644 --- a/tests/unit/test_streaming.py +++ b/tests/unit/test_streaming.py @@ -2875,10 +2875,116 @@ def test_session_parameters_reject_unknown_mode(): StreamingSessionParameters(mode="warpspeed") -def test_streaming_parameters_reject_unknown_field(): - # When/Then: connect parameters reject unknown fields too - with pytest.raises(ValueError, match="sampel_rate"): - StreamingParameters(sample_rate=16000, sampel_rate=8000) +def test_streaming_parameters_warn_on_unknown_field(caplog): + # When: connect parameters include a misspelled field + with caplog.at_level(logging.WARNING, logger="assemblyai.streaming.v3.models"): + params = StreamingParameters(sample_rate=16000, sampel_rate=8000) + + # Then: it does not raise, warns once naming the key, and is not sent + warnings = [ + r.getMessage() for r in caplog.records if "sampel_rate" in r.getMessage() + ] + assert warnings == [ + "Ignoring unknown streaming connection parameter `sampel_rate`; " + "it is not sent to the server." + ] + assert "sampel_rate" not in _build_uri("api.example.com", params) + + +def test_streaming_parameters_known_fields_do_not_warn(caplog): + # When: connect parameters use only known fields + with caplog.at_level(logging.WARNING, logger="assemblyai.streaming.v3.models"): + StreamingParameters(sample_rate=16000, format_turns=True) + + # Then: nothing is logged + assert caplog.records == [] + + +def test_set_params_sends_max_turn_duration(mocker: MockFixture): + # Given: a connected client + client = _connected_client_without_io(mocker) + + # When: max_turn_duration is updated mid-session + client.set_params(StreamingSessionParameters(max_turn_duration=30000)) + + # Then: the frame carries it unchanged + assert _enqueued_update_payload(client) == { + "type": "UpdateConfiguration", + "max_turn_duration": 30000, + } + + +def test_build_uri_includes_max_turn_duration(): + # When: max_turn_duration is set at connect + uri = _build_uri( + "api.example.com", + StreamingParameters(sample_rate=16000, max_turn_duration=30000), + ) + + # Then: it is a query parameter + assert "max_turn_duration=30000" in uri + + +@pytest.mark.parametrize("field", ["format_turns", "filter_profanity"]) +def test_set_params_warns_on_connect_only_field_and_still_sends_it( + mocker: MockFixture, caplog, field: str +): + # Given: a connected client + client = _connected_client_without_io(mocker) + + # When: set_params carries a field the server applies only at connect + with caplog.at_level(logging.WARNING, logger="assemblyai.streaming.v3._base"): + client.set_params(StreamingSessionParameters(**{field: True})) + + # Then: a warning names the field and the frame still carries it + assert [r.getMessage() for r in caplog.records] == [ + f"`{field}` only takes effect at connect; the server ignores it " + "in a mid-session UpdateConfiguration." + ] + assert _enqueued_update_payload(client) == { + "type": "UpdateConfiguration", + field: True, + } + + +def test_connect_only_fields_do_not_warn_at_connect(mocker: MockFixture, caplog): + # Given: a client whose websocket connect is stubbed + mocker.patch( + "assemblyai.streaming.v3.client.websocket_connect", + return_value=None, + ) + _disable_rw_threads(mocker) + client = StreamingClient( + StreamingClientOptions(api_key="test", api_host="api.example.com") + ) + + # When: format_turns and filter_profanity are set at connect + with caplog.at_level(logging.WARNING): + client.connect( + StreamingParameters( + sample_rate=16000, + speech_model=SpeechModel.universal_3_5_pro, + format_turns=True, + filter_profanity=True, + ) + ) + + # Then: nothing is logged + assert caplog.records == [] + + +def test_set_params_without_connect_only_fields_does_not_warn( + mocker: MockFixture, caplog +): + # Given: a connected client + client = _connected_client_without_io(mocker) + + # When: set_params carries only mid-session fields + with caplog.at_level(logging.WARNING): + client.set_params(StreamingSessionParameters(mode="manual")) + + # Then: nothing is logged + assert caplog.records == [] def test_update_configuration_sends_keyword_fields(mocker: MockFixture): diff --git a/tests/unit/test_streaming_async.py b/tests/unit/test_streaming_async.py index 6548c98..a98b50e 100644 --- a/tests/unit/test_streaming_async.py +++ b/tests/unit/test_streaming_async.py @@ -1843,3 +1843,34 @@ async def test_update_configuration_unknown_field_raises_and_sends_nothing( ] await client.disconnect() + + +async def test_set_params_warns_on_format_turns_and_still_sends_it( + mocker: MockFixture, caplog +): + # Given: a connected async streaming client + fake_ws = _FakeAsyncWebSocket() + _patch_connect(mocker, fake_ws) + client = AsyncStreamingClient( + StreamingClientOptions(api_key="test", api_host="api.example.com") + ) + await client.connect(_default_params()) + + # When: update_configuration carries format_turns + with caplog.at_level(logging.WARNING, logger="assemblyai.streaming.v3._base"): + await client.update_configuration(format_turns=True, max_turn_duration=30000) + + # Then: a warning is logged and the frame still carries both fields + assert [r.getMessage() for r in caplog.records] == [ + "`format_turns` only takes effect at connect; the server ignores it " + "in a mid-session UpdateConfiguration." + ] + update_frames = await _wait_for_update_frames(fake_ws) + assert len(update_frames) == 1 + assert json.loads(update_frames[0]) == { + "type": "UpdateConfiguration", + "format_turns": True, + "max_turn_duration": 30000, + } + + await client.disconnect()