feat(flux): support flux-general-multi and mid-session reconfiguration

Adds the API surface needed to use Deepgram's multilingual Flux model
from the Rust SDK:

- Model::FluxGeneralMulti selects the multilingual model.
- OptionsBuilder::language_hint takes an iterable of BCP-47 codes,
  emitted as repeated language_hint=... query params per spec.
- FluxResponse::TurnInfo now exposes languages (detected on the turn)
  and languages_hinted (the hints that were active for the request).
- FluxHandle::configure(ConfigureRequest) lets callers adjust
  thresholds, keyterms, and language hints without tearing down the
  WebSocket. Server replies surface as FluxResponse::ConfigureSuccess
  or ConfigureFailure.

ConfigureRequest fields are all optional so unset fields mean "leave
unchanged"; ConfigureThresholds groups eager_eot_threshold /
eot_threshold / eot_timeout_ms. New variants/fields are
non_exhaustive and existing payloads without the new TurnInfo fields
still deserialize, so this is additive only.

Examples:
- examples/transcription/flux/multi_language.rs - flux-general-multi
  with hints, prints the languages Flux returned per turn.
- examples/transcription/flux/dynamic_configure.rs - sends Configure
  mid-session and prints the ConfigureSuccess reply.

Author: GregHolmes

Cargo.toml

@@ -119,6 +119,16 @@ name = "microphone_flux"
 path = "examples/transcription/flux/microphone_flux.rs"
 required-features = ["listen"]
 
+[[example]]
+name = "flux_multi_language"
+path = "examples/transcription/flux/multi_language.rs"
+required-features = ["listen"]
+
+[[example]]
+name = "flux_dynamic_configure"
+path = "examples/transcription/flux/dynamic_configure.rs"
+required-features = ["listen"]
+
 [[example]]
 name = "text_to_speech_to_file"
 path = "examples/speak/rest/text_to_speech_to_file.rs"

examples/audio/bueller-mono.wav

@@ -0,0 +1,153 @@
+/* Expected result from running this example program.
+Flux Request ID: <uuid>
+Connected: <uuid> (seq: 0)
+[Turn 0] update: hello
+[Turn 0] EndOfTurn: Hello.
+Sending Configure: eot_threshold=0.85, keyterms=["weather", "forecast"]
+ConfigureSuccess: thresholds eot=Some(0.85) keyterms=["weather", "forecast"]
+[Turn 1] EndOfTurn: What's the weather forecast?
+*/
+
+//! Dynamic Flux `Configure` example.
+//!
+//! Pumps a file into the Flux WebSocket and, after the first turn ends,
+//! sends a `Configure` message to update the EOT threshold and
+//! keyterms mid-session. Demonstrates the
+//! [`crate::common::flux_response::FluxResponse::ConfigureSuccess`]
+//! acknowledgement.
+//!
+//! Single-task `tokio::select!` over the [`FluxHandle`]: audio frames
+//! are sent on a paced timer while events are received from the
+//! handle's response queue.
+//!
+//! Run with:
+//!
+//! ```bash
+//! DEEPGRAM_API_KEY=<your-key> \
+//!     cargo run --features listen --example flux_dynamic_configure
+//! ```
+
+use std::env;
+use std::time::Duration;
+
+use deepgram::{
+    common::{
+        flux_response::{ConfigureThresholds, FluxResponse, TurnEvent},
+        options::{Encoding, Model, Options},
+    },
+    listen::flux::ConfigureRequest,
+    Deepgram, DeepgramError,
+};
+
+static PATH_TO_FILE: &str = "examples/audio/bueller-mono.wav";
+static AUDIO_CHUNK_SIZE: usize = 8_820; // 100ms @ 44.1 kHz Linear16 mono
+static FRAME_DELAY: Duration = Duration::from_millis(100);
+
+#[tokio::main]
+async fn main() -> Result<(), DeepgramError> {
+    let api_key = env::var("DEEPGRAM_API_KEY").expect("DEEPGRAM_API_KEY environment variable");
+    let dg = Deepgram::new(&api_key)?;
+
+    let options = Options::builder()
+        .model(Model::FluxGeneralEn)
+        .eot_threshold(0.75)
+        .eot_timeout_ms(5_000)
+        .build();
+
+    let mut handle = dg
+        .transcription()
+        .flux_request_with_options(options)
+        .encoding(Encoding::Linear16)
+        .sample_rate(44_100)
+        .handle()
+        .await?;
+
+    println!("Flux Request ID: {}", handle.request_id());
+
+    // Read the file up front and slice it into pacable chunks.
+    let audio_bytes = tokio::fs::read(PATH_TO_FILE).await?;
+    let mut offset = 0usize;
+    let mut audio_done = false;
+    let mut sent_configure = false;
+
+    let mut frame_timer = tokio::time::interval(FRAME_DELAY);
+    frame_timer.set_missed_tick_behavior(tokio::time::MissedTickBehavior::Skip);
+
+    loop {
+        tokio::select! {
+            _ = frame_timer.tick(), if !audio_done => {
+                if offset >= audio_bytes.len() {
+                    handle.close_stream().await?;
+                    audio_done = true;
+                    continue;
+                }
+                let end = (offset + AUDIO_CHUNK_SIZE).min(audio_bytes.len());
+                let chunk = audio_bytes[offset..end].to_vec();
+                offset = end;
+                handle.send_data(chunk).await?;
+            }
+            response = handle.receive() => {
+                let Some(response) = response else { break };
+                match response? {
+                    FluxResponse::Connected {
+                        request_id,
+                        sequence_id,
+                    } => {
+                        println!("Connected: {} (seq: {})", request_id, sequence_id);
+                    }
+                    FluxResponse::TurnInfo {
+                        event,
+                        turn_index,
+                        transcript,
+                        ..
+                    } => match event {
+                        TurnEvent::Update => {
+                            if !transcript.is_empty() {
+                                println!("[Turn {}] update: {}", turn_index, transcript);
+                            }
+                        }
+                        TurnEvent::EndOfTurn => {
+                            println!("[Turn {}] EndOfTurn: {}", turn_index, transcript);
+                            if !sent_configure {
+                                sent_configure = true;
+                                println!(
+                                    "Sending Configure: eot_threshold=0.85, \
+                                     keyterms=[\"weather\", \"forecast\"]"
+                                );
+                                let req = ConfigureRequest::new()
+                                    .with_thresholds(
+                                        ConfigureThresholds::new().with_eot_threshold(0.85),
+                                    )
+                                    .with_keyterms(["weather", "forecast"]);
+                                handle.configure(req).await?;
+                            }
+                        }
+                        _ => {}
+                    },
+                    FluxResponse::ConfigureSuccess {
+                        thresholds,
+                        keyterms,
+                        ..
+                    } => {
+                        println!(
+                            "ConfigureSuccess: thresholds eot={:?} keyterms={:?}",
+                            thresholds.eot_threshold, keyterms
+                        );
+                    }
+                    FluxResponse::ConfigureFailure { sequence_id, .. } => {
+                        eprintln!("ConfigureFailure (seq={sequence_id})");
+                    }
+                    FluxResponse::FatalError {
+                        code, description, ..
+                    } => {
+                        eprintln!("FatalError {code}: {description}");
+                        break;
+                    }
+                    _ => {}
+                }
+            }
+        }
+    }
+
+    Ok(())
+}

examples/transcription/flux/dynamic_configure.rs

@@ -0,0 +1,127 @@
+/* Expected result from running this example program.
+Flux Request ID: <uuid>
+Connected: <uuid> (seq: 0)
+
+▶ [Turn 0] START — hint=[en, es]
+✓ [Turn 0] END (conf: 0.92): Hola, ¿cómo estás?
+  Detected languages: ["es"]
+  Active hints: ["en", "es"]
+*/
+
+//! Multilingual Flux example.
+//!
+//! Uses the `flux-general-multi` model with two language hints (`en`,
+//! `es`) and prints the per-turn `languages` and `languages_hinted`
+//! fields populated by the server.
+//!
+//! Run with:
+//!
+//! ```bash
+//! DEEPGRAM_API_KEY=<your-key> \
+//!     cargo run --features listen --example flux_multi_language
+//! ```
+
+use std::env;
+use std::io::Write;
+use std::time::Duration;
+
+use futures::stream::StreamExt;
+
+use deepgram::{
+    common::{
+        flux_response::{FluxResponse, TurnEvent},
+        options::{Encoding, Model, Options},
+    },
+    Deepgram, DeepgramError,
+};
+
+static PATH_TO_FILE: &str = "examples/audio/bueller-mono.wav";
+static AUDIO_CHUNK_SIZE: usize = 8_820; // 100ms @ 44.1 kHz Linear16 mono
+static FRAME_DELAY: Duration = Duration::from_millis(100);
+
+#[tokio::main]
+async fn main() -> Result<(), DeepgramError> {
+    let api_key = env::var("DEEPGRAM_API_KEY").expect("DEEPGRAM_API_KEY environment variable");
+    let dg = Deepgram::new(&api_key)?;
+
+    let options = Options::builder()
+        .model(Model::FluxGeneralMulti)
+        .language_hint(["en", "es"])
+        .eot_threshold(0.75)
+        .eot_timeout_ms(5_000)
+        .build();
+
+    let mut results = dg
+        .transcription()
+        .flux_request_with_options(options)
+        .encoding(Encoding::Linear16)
+        .sample_rate(44_100)
+        .file(PATH_TO_FILE, AUDIO_CHUNK_SIZE, FRAME_DELAY)
+        .await?;
+
+    println!("Flux Request ID: {}", results.request_id());
+
+    while let Some(result) = results.next().await {
+        match result? {
+            FluxResponse::Connected {
+                request_id,
+                sequence_id,
+            } => {
+                println!("Connected: {} (seq: {})", request_id, sequence_id);
+            }
+            FluxResponse::TurnInfo {
+                event,
+                turn_index,
+                transcript,
+                end_of_turn_confidence,
+                languages,
+                languages_hinted,
+                ..
+            } => match event {
+                TurnEvent::StartOfTurn => {
+                    println!(
+                        "\n▶ [Turn {}] START — hint={:?}",
+                        turn_index, languages_hinted
+                    );
+                }
+                TurnEvent::EndOfTurn => {
+                    println!(
+                        "\n✓ [Turn {}] END (conf: {:.2}): {}",
+                        turn_index, end_of_turn_confidence, transcript
+                    );
+                    if !languages.is_empty() {
+                        println!("  Detected languages: {:?}", languages);
+                    }
+                    if !languages_hinted.is_empty() {
+                        println!("  Active hints: {:?}", languages_hinted);
+                    }
+                }
+                TurnEvent::EagerEndOfTurn => {
+                    println!("\n⚡ [Turn {}] EAGER END: {}", turn_index, transcript);
+                }
+                TurnEvent::TurnResumed => {
+                    println!("\n↻ [Turn {}] RESUMED: {}", turn_index, transcript);
+                }
+                TurnEvent::Update => {
+                    if !transcript.is_empty() {
+                        print!("\r[Turn {}] UPDATE: {}", turn_index, transcript);
+                        std::io::stdout().flush().unwrap();
+                    }
+                }
+                _ => println!("\n[Turn {}] Unknown event: {:?}", turn_index, event),
+            },
+            FluxResponse::FatalError {
+                code, description, ..
+            } => {
+                eprintln!("Error {}: {}", code, description);
+                break;
+            }
+            FluxResponse::ConfigureSuccess { .. } | FluxResponse::ConfigureFailure { .. } => {
+                // Not used in this example — see dynamic_configure.rs.
+            }
+            _ => {}
+        }
+    }
+
+    Ok(())
+}