feat(regen): speak v2 barge-in and speed/expressivity controls, listen v2 redaction

[GregHolmes]

Python SDK regeneration from the jherlihy/flux-tts-ga docs branch (fern-python-sdk 5.23.0).

What this adds

Speak v2

• send_interrupt() — barge-in, optionally with a playback_offset ({type: "time_ms", value: N})
• send_configure() — mid-stream speed changes, acknowledged by ConfigureSuccess / ConfigureFailure
• SpeechInterrupted server message, with metadata incl. a new controls_applied.breaks_applied counter
• speed and expressivity connect query parameters

Listen v2

• redact connect parameter (ListenV2Redact: numbers, aggressive_numbers)
• send_configure() is now properly typed (ListenV2Configure + ListenV2ConfigureSuccess in the response union), replacing the previous typing.Any shim

Other

• GoogleThinkProviderVersion (adds ai-studio-v1beta, gemini-enterprise-agent-v1)
• AgentV1UpdateListenListenProvider discriminated union (_V1/_V2, discriminant version)
• deepgram speak provider version widened from Literal["v1"] to str
• client_wrapper now derives its version from importlib.metadata instead of a hardcoded string

Manual patch reconciliation

Re-applied (generator still misses these): socket-client broad except (required for custom transports, which raise non-websockets errors) and the optional no-payload control params; agent-settings and language_hint back-compat validators; query_encoder bool coercion; the 10 __init__.py legacy alias re-exports (merged with the new generated exports); wire-test legacy create-key alias coverage.

Dropped (generator now covers them, entries removed from .fernignore):

• agent_v1latency_report — stt_latency is emitted natively again
• core/client_wrapper — dynamic versioning supersedes the x-release-please-version annotations; its generic extra-file entry is also removed from release-please-config.json

Recovered: the agent_v1update_listen_listen.py provider-coercion validator was missing from .fernignore and was overwritten by the generator. Restored and now frozen — a regression test caught it.

listen/v2 send_configure keeps runtime tolerance for a raw dict (sent verbatim) for back-compat with pre-typed-model callers.

Compatibility

No breaking changes against the last release (v7.6.0): 0 removed public exports, 0 deleted modules, all baseline socket-client signatures intact, and enum changes are widenings only. Compat alias shims still pass.

The one change that would have broken callers is AgentV1UpdateListenListen.provider (bare DeepgramListenProviderV2 -> required discriminated union). The restored validator coerces a legacy provider instance or a legacy bare dict into the new shape, verified at runtime — both produce version: "v2" on the wire.

Review follow-ups (b8b2e78)

• AGENTS.md freeze ledger synced with .fernignore. Removed the now-unfrozen client_wrapper.py entry, added the newly-frozen agent_v1update_listen_listen.py (with a note that this patch was silently lost once by a regen), added the three language_hint provider validators and the new frozen test file, and corrected the listen/v2/socket_client.py entry which still described the superseded typing.Any send_configure shim. Verified zero drift in both directions.
• speak/v2 send_interrupt now takes an optional message, matching the sibling no-payload controls (send_flush/send_close) — SpeakV2Interrupt has no required fields, so send_interrupt() is meaningful. send_configure deliberately keeps its required argument (a Configure with no settings is meaningless). Covered by new sync + async tests.

Version bump

The branch carries 7.6.1 (a patch) but this is a feat. That's expected: the generator patch-bumps pyproject.toml on every regen and release-please recomputes the correct minor at release time from the conventional-commit type. Verified across three cycles — e.g. #750 left 7.6.1 and release-please's PR proposed 7.7.0. This only holds because the squash-merge message is feat(...), which is why the PR title matters here.

Review follow-ups (round 2)

[B1] blocking — fixed. Passing provider as a plain dict to AgentV1UpdateListenListen skipped the language_hint → language_hints remap, so the deprecated singular key reached the wire. The API uses deny_unknown_fields, so the whole UpdateListen was rejected with no client-side signal. The dict branch now routes through DeepgramListenProviderV1/V2 so their own before-validators run — one remap implementation instead of two. [S1] fixed in the same edit: the version is inferred from the dict's own keys (language/smart_format are v1-only) rather than blanket-stamped v2.

One deviation from the suggested fix: constructing the shim model raises on a malformed dict (e.g. missing the required model), which would have made the compat shim a new source of exceptions. Wrapped with a pass-through fallback, so behaviour is never worse than pre-regen. The downstream union rejection of a genuinely-invalid payload was confirmed pre-existing (the old code produced an identical payload, rejected identically).

[S3] restored wire coverage. The regen dropped all ten optional query params from the manage.v1.projects.requests.list wire test (Fern derives the test from the spec example, which was simplified upstream), leaving their serialisation — including datetime → ISO-8601 Z — unverified while the client still forwarded them. Restored and frozen in .fernignore with the same rationale as the _keys.py entry.

[S2] reference.md updated. Added the five missing entries (redact, send_configure for listen v2; speed, expressivity, send_interrupt, send_configure for speak v2). The param entries spell out accepted values, since the spec's numeric enums are dropped in codegen.

[S7] barge-in example added — examples/26-text-to-speech-barge-in-v2.py, async (the sync client blocks in start_listening(), so mid-stream interrupt can't be shown). ⚠️ Not yet verifiable: speak.v2.connect(model="flux-alexis-en") returns HTTP 400 on api.deepgram.com today, consistent with the API not being in production yet.

[S8] documented — AGENTS.md now records the residual concerns on the two newly-unfrozen files, notably that client_wrapper's version fallback literal is refreshed only by regen.

Security fix (found while running the new example)

Every websocket connect() path raises ApiError(headers=dict(headers), ...) with the full request headers, and both ApiError and ParsingError stringify that dict. A failed connect therefore printed:

headers: {'Authorization': 'Token <live key>', ...}, status_code: 400, ...

so any application logging the exception — print(e), a traceback, a log aggregator, an error tracker — wrote the customer's API key in clear text. This is the same threat _secure_logging.py already covers for the websockets DEBUG handshake logs; the exception path is simply the other route to it, and was uncovered. It also defeats the telemetry scrubber, which strips request.headers but not the exception message.

Both error types now mask credential values at construction (so repr() and attribute serialisation are covered too, not just __str__), reusing _secure_logging's existing sensitive-header set and scheme-preserving mask. Non-sensitive headers are kept — dg-request-id is the main reason to inspect them. Both files are generated, so they're frozen with the rationale and documented in the ledger. 14 new tests, mutation-checked.

Pre-existing, not introduced by this regen, and it affects all five socket clients.

Core / generator upgrade (5.14.18 → 5.23.0)

Nine generator minors also changed core HTTP behaviour that the feature summary above doesn't cover:

1. RequestOptions gains timeout, and timeout_in_seconds becomes a deprecated alias — a new public option plus a deprecation.
2. Behaviour change for custom httpx_client users. The SDK previously adopted your client's .timeout.read as the base timeout for every request; the base timeout is now None, resolving to httpx.USE_CLIENT_DEFAULT. This is an improvement — the old path flattened a granular httpx.Timeout(connect=5, read=30, …) down to a single 30, silently widening the connect timeout — but if you tuned around that flattening, expect connect timeouts to tighten to what you actually configured.
3. get_keepalive_socket_options() is a new public helper in core/http_client.py that nothing in the SDK calls.
4. stream_reconnection_enabled / max_stream_reconnection_attempts are added to both client constructors and to RequestOptions, documented as "Defaults to True" — but they are consumed only by core/http_sse/_api.py, and nothing wires http_sse to an endpoint, so they are inert today and do not apply to the WebSocket clients. Worth knowing, since DeepgramClient already has an unrelated hand-written reconnect flag. (Not patched in the docstring: those files are generated and now unfrozen, so a comment there would be lost next regen.)

Spec copy fixes — [S4] / [S5] (done, not deferred)

Both are spec description fields, so the durable fix is in deepgram-docs: deepgram-docs#1094, stacked on the Flux GA PR #1090 (SpeakV2Speed/SpeakV2Expressivity don't exist on docs main yet, so there was nothing to edit there).

To avoid this release shipping stale copy while waiting on a regen, the same text is applied by hand here:

• [S4] Flux TTS "Early Access" wording removed from the Deepgram agent speak-provider descriptions (types/deepgram.py + requests/deepgram.py). Flux is GA; the direct Speak V2 path had already been updated, so the Agent path was the only surface still telling developers Flux might change before GA. src/ now has zero "Early Access" occurrences. No "GA" wording added in its place.
• [S5] accepted values stated for speed and expressivity. Both are enums in the spec — the problem is downstream: Fern drops numeric enums, so speed's "Only the multipliers listed here are accepted" pointed at a list that wasn't there and expressivity gave no range at all. Both now spell the values out, and speed names the two failure codes (SPEED_OUT_OF_RANGE, SPEED_INCREMENT_INVALID).

These four files are not frozen. The hand-applied text was verified to match #1094 byte-for-byte — the spec YAML was parsed, folded scalars normalised the way Fern renders them, and all five descriptions (provider, version, model, speed, expressivity) compared equal — so the next regen emits identical output and a freeze would protect nothing. Fern keeps ownership; no maintenance debt once #1094 merges.

Known issues NOT fixed here

• Numeric spec enums lose their constraints in codegen (SpeakV2Speed → bare float, SpeakV2Expressivity → bare int; string enums keep their Literal unions), so out-of-range values are caught only by the server. Documented rather than hand-validated — the reference.md entries and the corrected docstrings now state the accepted values. Worth raising with Fern, since it affects every Deepgram SDK.
• [N2] .fern/metadata.json records originGitCommitIsDirty: true — the spec input isn't reproducible from version control. Pre-existing practice (main carries the same flag) and unchanged here, since fixing it needs a spec commit plus a regen.
• [S7] the new barge-in example is unverified against a live API. speak.v2.connect(model="flux-alexis-en") returns HTTP 400 on api.deepgram.com today, consistent with the merge gate below.

Note on the ApiError fix and the other SDKs

The credential leak above is Python-specific and does not need porting. It required two Python-only things to coincide: ApiError.__str__ printing self.headers, and the websocket connect() paths passing the request headers. Checked both siblings: the JS DeepgramError.buildMessage({message, statusCode, body}) takes no headers and none of its construction sites pass request headers; Java's DeepgramHttpException populates its header map from rawResponse.headers() (response headers) and has no toString that dumps them.

Verification

• pytest — 375 passed, 1 skipped
• ruff check src/ clean; mypy src/ (882 files) and mypy tests/typecheck/ clean
• 18 new tests covering the added surface, each mutation-verified (deliberately broke the source and confirmed the test fails). Note these models are extra="allow", so asserting a field's value does not detect a dropped field declaration — the metadata tests assert the declared field set as well.
• 16 examples run against the live API, including 25-text-to-speech-streaming-v2.py (Speak v2 streaming) and 30-voice-agent.py. Management examples were intentionally skipped; 5 others need a local audio file, a microphone, or the separate deepgram-sagemaker package.

Rebased onto main after #757 (the listen-v2 revert) merged, so the revert is no longer duplicated on this branch.

[dg-coreylweathers]

Blocking findings resolved and verified on 9929ca1.

Verified: Sec-WebSocket-Protocol credentials are masked on both the error-header path (ApiError/ParsingError: absent from str, repr, and .headers) and the websockets debug-log filter, with non-sensitive headers such as dg-request-id preserved. language_hint remap and version inference confirmed by probe on the UpdateListen raw-dict path. Zero 'Early Access' occurrences in src/. reference.md documents the new speak v2 and listen v2 surface. Gates: 378 passed / 1 skipped, ruff clean, mypy clean.

Approving the content. Merge remains gated on the API being in production, and note deepgram-docs #1090 is still open (the SDK is generated from jherlihy/flux-tts-ga, so main's spec still carries the Early Access wording until it lands).

Non-blocking follow-ups, fine to take after the launch: [S9] the malformed-dict test asserts on the private coercion helper while the public constructor still raises; [S10] add a freeze-independent test guarding the GA copy now that the four copy-fix files are unfrozen; [N4] a dict mixing a v1-only key with language_hint still ships the singular key.

[dg-coreylweathers]

Re-reviewed on 9929ca1 (unchanged since the previous approval). Content approved — hold merge until the Flux TTS API is confirmed in production.

[B2] verified fixed, by probe rather than attestation: sec-websocket-protocol is now in _SENSITIVE_HEADERS, and credentials mask correctly across all five header shapes — the documented "token, <key>" form (masks to token, [REDACTED], dg-request-id preserved), no-scheme values, lowercase header names, list values, and on ParsingError as well as ApiError. Both mutation paths are covered: removing the header from the frozenset trips test_secure_logging.py:83, removing the redact call trips test_api_error_redaction.py.

Also verified on this head: CI green on 3.10–3.13, base fresh against main (48c88fc), .fernignore at 95 entries with 0 ghosts and no .bak leftovers, zero "Early Access" in src/, and the speed/expressivity accepted-value copy present.

Two corrections to my round-2 review:

1. The [S10] regression test I recommended does not work as written — it asserts on __doc__, but Fern emits those descriptions as PEP 224 variable docstrings, which Python discards at runtime (module __doc__ is None; SpeakV2Speed.__doc__ is float's). A corrected source-reading version, verified passing against this tree, is in the review notes.

2. My claim that [B2] "applies to the JS SDK with more force" was wrong. Parity pass run against both sibling checkouts: the leak needed an error type that stringifies headers and connect paths passing outbound request headers into it. JS's DeepgramError carries no headers field; Java's DeepgramHttpException carries only response headers and omits them from toString(). Greg's read in the PR description was correct — this is Python-specific and does not need porting. What remains for the JS repo is defense-in-depth only (sec-websocket-protocol absent from its SENSITIVE_HEADERS, latent today since that helper is wired only into the HTTP fetcher).

Gates cleared since the last round: release-please #751 is closed with no open release PR, and deepgram-docs #1090 is now approved and green — which downgrades [S10] from live exposure to residual hygiene.

Deferred to post-launch, unchanged: [S9] the malformed-dict test asserts on the private helper while the public constructor still raises; [S10] the freeze-independent GA-copy guard; [N4] a dict mixing a v1-only key with language_hint still ships the singular key; [N2] dirty spec tree; [N3] breaks_applied typed int but None at runtime.

One ask for the release notes: add the key-rotation line. The fix stops new leaks but does nothing about keys already written to a customer's error tracker or log archive — anyone with events from a failed connect should treat those keys as exposed and rotate.

[dg-coreylweathers]

Re-reviewed on 9929ca1 (unchanged since the previous approval). Content approved — hold merge until the Flux TTS API is confirmed in production.

[B2] verified fixed, by probe rather than attestation: sec-websocket-protocol is now in _SENSITIVE_HEADERS, and credentials mask correctly across all five header shapes — the documented "token, <key>" form (masks to token, [REDACTED], dg-request-id preserved), no-scheme values, lowercase header names, list values, and on ParsingError as well as ApiError. Both mutation paths are covered: removing the header from the frozenset trips test_secure_logging.py:83, removing the redact call trips test_api_error_redaction.py.

Also verified on this head: CI green on 3.10–3.13, base fresh against main (48c88fc), .fernignore at 95 entries with 0 ghosts and no .bak leftovers, zero "Early Access" in src/, and the speed/expressivity accepted-value copy present.

Two corrections to my round-2 review:

1. The [S10] regression test I recommended does not work as written — it asserts on __doc__, but Fern emits those descriptions as PEP 224 variable docstrings, which Python discards at runtime (module __doc__ is None; SpeakV2Speed.__doc__ is float's). A corrected source-reading version, verified passing against this tree, is in the review notes.

2. My claim that [B2] "applies to the JS SDK with more force" was wrong. Parity pass run against both sibling checkouts: the leak needed an error type that stringifies headers and connect paths passing outbound request headers into it. JS's DeepgramError carries no headers field; Java's DeepgramHttpException carries only response headers and omits them from toString(). Greg's read in the PR description was correct — this is Python-specific and does not need porting. What remains for the JS repo is defense-in-depth only (sec-websocket-protocol absent from its SENSITIVE_HEADERS, latent today since that helper is wired only into the HTTP fetcher).

Gates cleared since the last round: release-please #751 is closed with no open release PR, and deepgram-docs #1090 is now approved and green — which downgrades [S10] from live exposure to residual hygiene.

Deferred to post-launch, unchanged: [S9] the malformed-dict test asserts on the private helper while the public constructor still raises; [S10] the freeze-independent GA-copy guard; [N4] a dict mixing a v1-only key with language_hint still ships the singular key; [N2] dirty spec tree; [N3] breaks_applied typed int but None at runtime.

One ask for the release notes: add the key-rotation line. The fix stops new leaks but does nothing about keys already written to a customer's error tracker or log archive — anyone with events from a failed connect should treat those keys as exposed and rotate.