feat(deepgram): port flux-general-multi STTv2 support from python

[toubatbrian]

Summary

Ports livekit/agents#5486 ("(deepgram sttv2): add flux-general-multi support") from the Python livekit-agents repo into agents-js.

This PR adds support for Deepgram's new flux-general-multi STTv2 model, which performs multi-language detection over an utterance. When this model is active, Deepgram returns a languages array on each transcript message, ordered by prevalence. The most-prevalent language is exposed as the primary language, and the full list is exposed on a new sourceLanguages field.

cc @toubatbrian @livekit/agent-devs for review.

Ported features

1. flux-general-multi model (plugins/deepgram/src/models.ts)

Extended the V2Models union:

// Ref: python livekit-plugins/livekit-plugins-deepgram/livekit/plugins/deepgram/models.py - 38 line
export type V2Models = 'flux-general-en' | 'flux-general-multi';

2. languageHint option on STTv2 (plugins/deepgram/src/stt_v2.ts)

New optional languageHint: string[] option on STTv2Options, serialized into the Deepgram websocket URL as the language_hint query parameter. This option is only meaningful with flux-general-multi; setting it on any other model logs a warning (matching Python's logger.warning(...) behavior). The same warning path is wired into updateOptions so late model/hint changes still surface mismatches.

3. source_languages → sourceLanguages on SpeechData (agents/src/stt/stt.ts)

New optional field on the core SpeechData interface:

// Ref: python livekit-agents/livekit/agents/stt/stt.py - 62-68 lines
sourceLanguages?: LanguageCode[];

The docstring mirrors the updated Python docstring: the field is populated either by translation-capable STT services (where language is the target and sourceLanguages carries the original spoken language(s)) or by multi-language detection services (where language is the dominant detected language and sourceLanguages carries all detected languages sorted by prevalence).

4. parseTranscription updates

The Deepgram STTv2 parser now reads data.languages, runs each entry through normalizeLanguage, and:

• Sets SpeechData.language to the dominant (first) detected language when the array is non-empty, falling back to the stream's configured language otherwise.
• Sets SpeechData.sourceLanguages to the full normalized list (or leaves it undefined when the field is absent).

Implementation nuances vs Python

• Naming: Python's language_hint (snake_case) maps to JS's languageHint (camelCase); the wire parameter stays language_hint. Same for source_languages → sourceLanguages.
• Language normalization: Python stores raw LanguageCode(...) values from Deepgram. The JS plugin has always run language strings through normalizeLanguage(...) before putting them on SpeechData.language (this matches the existing pattern used elsewhere in the Deepgram plugin and the wider codebase), so the port normalizes each entry of the languages array as well.
• Logging: Python uses %s positional formatting; JS uses pino-style structured logging ({ model: ... }, 'message'). The warning content is preserved verbatim.
• source_texts: The Python diff updates the docstring for SpeechData.source_texts too, but the JS SpeechData has never had that field (it was never ported with the translation feature) so nothing to change here. This is noted so we don't silently drift — we can port sourceTexts in a follow-up if/when translation STT lands in JS.
• Docstring-only change to stt.py: The Python PR also tweaks the source_languages docstring in core stt.py. Those clarifications are inlined into the JSDoc on the new JS field.

Files changed

File	Change
agents/src/stt/stt.ts	Add sourceLanguages?: LanguageCode[] to SpeechData with docstring matching Python
plugins/deepgram/src/models.ts	Add flux-general-multi to V2Models
plugins/deepgram/src/stt_v2.ts	Add languageHint option, wire it into the websocket URL, warn on model mismatch in constructor + updateOptions, populate sourceLanguages and override primary language from Deepgram's languages array
.changeset/deepgram-flux-general-multi.md	minor changeset for @livekit/agents-plugin-deepgram and @livekit/agents

Test plan

• pnpm build:agents succeeds
• pnpm --filter "@livekit/agents-plugin-deepgram..." build succeeds
• pnpm format:check passes
• ESLint surfaces no new errors/warnings (pre-existing warnings unchanged)
• Manual: run restaurant_agent.ts with new STTv2({ model: 'flux-general-multi', languageHint: ['en', 'es'] }) and verify sourceLanguages is populated on FINAL_TRANSCRIPT events when switching languages mid-utterance
• Manual: confirm with model: 'flux-general-en' + languageHint the warning is emitted and the stream still succeeds (hint ignored)

---

This PR was created by an automated Claude Code Routine maintained by @toubatbrian. The routine is currently in experimentation stage.

[changeset-bot]

🦋 Changeset detected

Latest commit: 11dd913

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 26 packages

Name	Type
@livekit/agents-plugin-deepgram	Patch
@livekit/agents	Patch
@livekit/agents-plugin-anam	Patch
@livekit/agents-plugin-assemblyai	Patch
@livekit/agents-plugin-baseten	Patch
@livekit/agents-plugin-bey	Patch
@livekit/agents-plugin-cartesia	Patch
@livekit/agents-plugin-cerebras	Patch
@livekit/agents-plugin-elevenlabs	Patch
@livekit/agents-plugin-google	Patch
@livekit/agents-plugin-hedra	Patch
@livekit/agents-plugin-inworld	Patch
@livekit/agents-plugin-lemonslice	Patch
@livekit/agents-plugin-livekit	Patch
@livekit/agents-plugin-mistral	Patch
@livekit/agents-plugin-neuphonic	Patch
@livekit/agents-plugin-openai	Patch
@livekit/agents-plugin-phonic	Patch
@livekit/agents-plugin-resemble	Patch
@livekit/agents-plugin-rime	Patch
@livekit/agents-plugin-runway	Patch
@livekit/agents-plugin-sarvam	Patch
@livekit/agents-plugin-silero	Patch
@livekit/agents-plugins-test	Patch
@livekit/agents-plugin-trugen	Patch
@livekit/agents-plugin-xai	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: e18df61759

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[devin-ai-integration]

✅ Devin Review: No Issues Found

Devin Review analyzed this PR and found no potential bugs to report.

View in Devin Review to see 3 additional findings.

[tinalenguyen]

verified changes