diff --git a/.github/prompts/document-transcribe-params.prompt.md b/.github/prompts/document-transcribe-params.prompt.md new file mode 100644 index 00000000..00037428 --- /dev/null +++ b/.github/prompts/document-transcribe-params.prompt.md @@ -0,0 +1,37 @@ +--- +name: "Document Transcribe Params" +description: "Generate the German Markdown reference for all streaming transcribe provider parameters" +argument-hint: "Optional: output path (default: /tmp/context-switch-transcribe-parameter.md)" +agent: "agent" +--- + +Generate a German parameter reference for every streaming transcribe provider in this workspace. + +Write the result to `/tmp/context-switch-transcribe-parameter.md` unless the user supplies a different output path. + +Treat the current Rust `Params` types as the authoritative contract: + +1. Start from `examples/transcribe.rs` to identify the providers wired by the example. +2. Read each corresponding `services/*/src/transcribe.rs` file and any immediate mapping code needed to determine how every `Params` field is sent to the provider. +3. Include every accepted parameter, including serde aliases, defaults, nested types, and provider-neutral settings that are only partially forwarded. +4. Use the official provider documentation to refine descriptions with verified defaults, valid ranges, constraints, model requirements, audio requirements, or language formats. Do not invent details when no official source is available. +5. Verify external documentation links before including them. Prefer official provider documentation; where unavailable, use the relevant official crate, repository, or example. + +Use this output structure: + +- A German title and a short introduction explaining that JSON names follow the serde wire format and that code blocks are JSONC documentation rather than sendable JSON. +- One `##` section per provider, named after the provider. +- In each provider section, a JSONC block containing every `Params` field. Put an adjacent German `//` comment on each field so the parameters remain the focal point. +- Follow each block with only the relevant provider behavior, integration defaults, audio restrictions, and environment-variable or CLI wiring notes. +- Add a `## CLI-Parameter nach Provider` table for the flags in `examples/transcribe.rs`. Explicitly call out flags that are accepted or validated but not passed into a provider's `Params` instance. +- Include a compact `Quelle` or `Quellen` line in every provider section with working documentation links. + +Keep the document precise and parameter-oriented: + +- Use the exact camelCase JSON field names from serde. +- Mark required versus optional fields, defaults, accepted values, units, and constraints where known. +- Explain adapter-specific transformations near the affected parameter, such as BCP 47 conversion, endpoint aliases, model selection, or ignored turn-detection fields. +- Distinguish clearly between context-switch behavior and external provider API settings. +- Do not modify repository source files for this task unless the user explicitly asks for code documentation updates too. + +Before finishing, validate that the file is non-empty, has a section for every discovered provider, contains the CLI table, and does not retain known-invalid links. Report the output path and validation result concisely. \ No newline at end of file diff --git a/services/aristech/src/transcribe.rs b/services/aristech/src/transcribe.rs index 0719084a..e9037b29 100644 --- a/services/aristech/src/transcribe.rs +++ b/services/aristech/src/transcribe.rs @@ -14,18 +14,23 @@ use tonic::codegen::CompressionEncoding; use context_switch_core::{Conversation, Input, Service}; -/// Authentication configuration +/// API-key authentication for Aristech STT. #[derive(Debug, Deserialize)] #[serde(rename_all = "camelCase")] pub struct ApiKeyAuth { + /// Aristech STT API key. pub api_key: String, } +/// Credential-based authentication for an Aristech STT server. #[derive(Debug, Deserialize)] #[serde(rename_all = "camelCase")] pub struct CredentialsAuth { + /// Aristech STT server address. pub host: String, + /// Credential token. pub token: String, + /// Credential secret. pub secret: String, } @@ -44,15 +49,17 @@ pub enum AuthConfig { #[derive(Debug, Deserialize)] #[serde(rename_all = "camelCase")] pub struct Params { + /// Authentication: either `apiKey`, or the complete `host`/`token`/`secret` credential set. #[serde(flatten)] pub auth_config: AuthConfig, - /// N.B. This is expected to be in locale format, e.g. "en_GB" or "de_DE". - /// A BCP 47 language code (e.g. "en-US") is not expected here. + /// Required locale in underscore form (for example, `en_GB` or `de_DE`). + /// BCP 47 language tags with a hyphen (for example, `en-US`) are not accepted. pub language: String, - // TODO: Determine whether this could really be used in practice, in the future. - // It seems that the language code used, automatically chooses the appropriate model. TBC. + /// Optional recognition model sent as `RecognitionSpec.model`. When omitted, an empty model + /// is sent and the provider generally derives the appropriate model from `language`. pub model: Option, - // TODO: Determine whether this could really be used in practice, in the future. + /// Optional recognition prompt sent as `RecognitionSpec.prompt`. When omitted, an empty + /// prompt is sent. pub prompt: Option, } diff --git a/services/azure/src/transcribe.rs b/services/azure/src/transcribe.rs index d41d0077..91baf5fd 100644 --- a/services/azure/src/transcribe.rs +++ b/services/azure/src/transcribe.rs @@ -18,13 +18,24 @@ use crate::Host; #[derive(Debug, Deserialize)] #[serde(rename_all = "camelCase")] pub struct Params { + /// Optional full Azure Speech endpoint URL. The `host` name is accepted as an alias. + /// Either this field or `region` must be set. #[serde(alias = "host")] pub endpoint: Option, + /// Azure region used for key-based connections (for example, `westeurope`). + /// Used only when `endpoint` is omitted. pub region: Option, + /// Azure Speech subscription key. pub subscription_key: String, + /// One or more comma-separated BCP 47 locale codes (for example, `de-DE,en-US`). + /// A single locale configures recognition directly; multiple locales enable continuous + /// language identification. pub language: String, + /// Enable speaker diarization. Availability depends on the selected Azure locale and feature. #[serde(default)] pub diarization: bool, + /// Enable the local RMS speech gate before audio is sent to Azure. + /// This is a context-switch feature, not an Azure Speech setting. #[serde(default)] pub speech_gate: bool, } diff --git a/services/deepgram/src/transcribe.rs b/services/deepgram/src/transcribe.rs index 918ad114..8cc796fa 100644 --- a/services/deepgram/src/transcribe.rs +++ b/services/deepgram/src/transcribe.rs @@ -21,9 +21,14 @@ use context_switch_core::{ #[derive(Debug, Deserialize)] #[serde(rename_all = "camelCase")] pub struct Params { + /// Deepgram API key. pub api_key: String, + /// Deepgram endpoint base URL. The `host` name is accepted as an alias. + /// A trailing `/v1/listen` or `/v2/listen` path is normalized to the base URL. #[serde(alias = "host")] pub endpoint: String, + /// One or more comma-separated BCP 47 locale codes. A single English language selects + /// `flux-general-en`; all other inputs select `flux-general-multi` with language hints. pub language: String, /// Replace detected profanity with asterisks in the transcript. #[serde(default)] @@ -31,7 +36,8 @@ pub struct Params { /// Format recognized numbers as numerals in the transcript. #[serde(default)] pub numerals: bool, - /// Key terms to boost recognition accuracy for domain-specific vocabulary. + /// Key terms to boost recognition accuracy for domain-specific vocabulary. Flux accepts up + /// to 100 terms; weighting syntax is not supported. #[serde(default)] pub keyterm: Vec, /// Provider-neutral turn-detection configuration. Only `threshold`, `timeoutMs`, and diff --git a/services/elevenlabs/src/transcribe.rs b/services/elevenlabs/src/transcribe.rs index 9840e74c..6e018027 100644 --- a/services/elevenlabs/src/transcribe.rs +++ b/services/elevenlabs/src/transcribe.rs @@ -44,12 +44,15 @@ const DEFAULT_INCLUDE_LANGUAGE_DETECTION: bool = false; pub struct Params { /// ElevenLabs API key for the `xi-api-key` websocket header. pub api_key: String, - /// Optional realtime model. Defaults to `scribe_v2_realtime` when omitted. + /// Optional realtime model sent as the `model_id` query parameter. + /// Defaults to `scribe_v2_realtime` when omitted. pub model: Option, - /// Optional WebSocket endpoint override. + /// Optional WebSocket endpoint override. The `host` name is accepted as an alias. + /// Defaults to `wss://api.elevenlabs.io/v1/speech-to-text/realtime`. #[serde(alias = "host")] pub endpoint: Option, - /// Optional language hint in BCP 47 format (for example `en-US`). + /// Optional BCP 47 language hint (for example, `en-US`). The adapter converts it to the + /// ISO 639-3 `language_code` query parameter. pub language: Option, /// Include detected language in timestamped output. /// When omitted, this integration defaults it to `false`. diff --git a/services/google-transcribe/src/transcribe.rs b/services/google-transcribe/src/transcribe.rs index 397139bc..86bfd384 100644 --- a/services/google-transcribe/src/transcribe.rs +++ b/services/google-transcribe/src/transcribe.rs @@ -20,10 +20,16 @@ use crate::{Host, client::TranscribeClient}; #[derive(Debug, Deserialize)] #[serde(rename_all = "camelCase")] pub struct Params { + /// Google Cloud Speech-to-Text V2 recognition model (for example, `latest_long`). pub model: String, + /// One or more comma-separated BCP 47 locale codes sent as `language_codes`. pub language: String, + /// Enable speaker diarization. Google determines the number of speakers; support depends on + /// the selected model, language, and region. #[serde(default)] pub diarization: bool, + /// Google Cloud location and API endpoint. Only `global`, `eu`, and `us` are supported. + /// Defaults to `global`. #[serde(default)] pub region: Region, } @@ -31,9 +37,12 @@ pub struct Params { #[derive(Debug, Clone, Copy, Default, Deserialize)] #[serde(rename_all = "lowercase")] pub enum Region { + /// Google Cloud global endpoint. #[default] Global, + /// Google Cloud European endpoint. Eu, + /// Google Cloud United States endpoint. Us, } diff --git a/services/microsoft-voice-live/src/transcribe.rs b/services/microsoft-voice-live/src/transcribe.rs index 626261ce..eafb337a 100644 --- a/services/microsoft-voice-live/src/transcribe.rs +++ b/services/microsoft-voice-live/src/transcribe.rs @@ -14,6 +14,7 @@ const DEFAULT_TRANSCRIPTION_MODEL: &str = "azure-speech"; #[derive(Debug, Deserialize)] #[serde(rename_all = "camelCase")] pub struct Params { + /// Voice Live API key. pub api_key: String, /// Resource endpoint URL. Must be a full `wss://` URL. /// The path is used exactly as provided; only the `api-version` and `model` query @@ -21,6 +22,7 @@ pub struct Params { pub endpoint: String, /// Realtime model used for the Voice Live session (URL `model` query parameter). pub model: String, + /// Optional Voice Live API version. Defaults to `2026-06-01-preview` when omitted. pub api_version: Option, /// Transcription model set in `audio.input.transcription.model`. ///