captchaforge 0.2.26

//! Speech-to-text endpoint ladder.
//!
//! The audio-fallback path is pointless if STT fails. A single
//! configured endpoint is a single point of failure: a local Whisper
//! container that crashed mid-day, an OpenAI rate-limit window, or a
//! 2captcha audio quota exhaustion all turn the audio path into
//! silent failures.
//!
//! [`SttPipeline`] runs an ordered ladder of [`SttEndpoint`] entries.
//! Each entry has its own URL, headers, and per-call budget. The
//! pipeline tries them in order; the first endpoint that returns a
//! non-empty transcript wins. If all endpoints fail, the pipeline
//! returns the most informative error from the ladder.
//!
//! Endpoints are intentionally untyped — `headers` is a free-form
//! `Vec<(String, String)>` rather than a per-vendor enum so adding a
//! new vendor (Deepgram, AssemblyAI, etc.) doesn't require a code
//! change. A TOML config file registers the endpoint shape and the
//! response-extraction expression.
//!
//! Response extraction is JSON-pointer driven for JSON responses
//! (the common case) and raw-body for plain-text responses (local
//! Whisper-compatible servers usually emit `text/plain`). The
//! extraction is a per-endpoint setting so one ladder can mix both.

use std::time::Duration;

use anyhow::{anyhow, Result};

/// One entry in the STT ladder.
#[derive(Debug, Clone)]
pub struct SttEndpoint {
    /// Display name for logging / metrics.
    pub name: String,
    /// Full URL to POST audio to.
    pub url: String,
    /// HTTP headers (e.g. `("Authorization", "Bearer …")`).
    pub headers: Vec<(String, String)>,
    /// Content-Type for the audio body.
    pub content_type: String,
    /// Per-call timeout budget.
    pub timeout_ms: u64,
    /// How to extract the transcript from the response.
    pub extract: TranscriptExtract,
}

/// Strategy for pulling the transcript out of an HTTP response body.
#[derive(Debug, Clone)]
pub enum TranscriptExtract {
    /// Treat the body as the transcript verbatim. Used for local
    /// Whisper-compatible servers that emit `text/plain`.
    RawBody,
    /// Parse the body as JSON and extract via JSON-pointer
    /// (RFC 6901). Example: `"/text"` for OpenAI Whisper API,
    /// `"/results/0/alternatives/0/transcript"` for Google STT.
    JsonPointer(String),
}

impl SttEndpoint {
    /// Convenience constructor for local Whisper-compatible servers.
    pub fn local_whisper(url: impl Into<String>) -> Self {
        Self {
            name: "local_whisper".to_string(),
            url: url.into(),
            headers: Vec::new(),
            content_type: "audio/mpeg".to_string(),
            timeout_ms: 60_000,
            extract: TranscriptExtract::RawBody,
        }
    }

    /// Convenience constructor for the OpenAI Whisper API. Caller
    /// supplies the API key; the rest of the wiring (URL, model,
    /// JSON-pointer) is set up.
    ///
    /// # Examples
    ///
    /// ```
    /// use captchaforge::stt::{SttEndpoint, TranscriptExtract};
    /// let e = SttEndpoint::openai_whisper("sk-test");
    /// assert_eq!(e.name, "openai_whisper");
    /// assert!(matches!(e.extract, TranscriptExtract::JsonPointer(_)));
    /// assert!(e.headers.iter().any(|(k, _)| k == "Authorization"));
    /// ```
    pub fn openai_whisper(api_key: impl Into<String>) -> Self {
        Self {
            name: "openai_whisper".to_string(),
            url: "https://api.openai.com/v1/audio/transcriptions".to_string(),
            headers: vec![
                ("Authorization".to_string(), format!("Bearer {}", api_key.into())),
            ],
            content_type: "audio/mpeg".to_string(),
            timeout_ms: 30_000,
            extract: TranscriptExtract::JsonPointer("/text".to_string()),
        }
    }

    /// Pre-configured endpoint for [Deepgram](https://deepgram.com)
    /// Listen REST. Authentication is `Token <key>`. Response shape:
    /// `{"results":{"channels":[{"alternatives":[{"transcript": "..."}]}]}}`.
    ///
    /// # Example
    ///
    /// ```rust
    /// use captchaforge::stt::SttEndpoint;
    /// let ep = SttEndpoint::deepgram(std::env::var("DEEPGRAM_API_KEY").unwrap_or_default());
    /// assert_eq!(ep.url, "https://api.deepgram.com/v1/listen");
    /// ```
    pub fn deepgram(api_key: impl Into<String>) -> Self {
        Self {
            name: "deepgram".to_string(),
            url: "https://api.deepgram.com/v1/listen".to_string(),
            headers: vec![(
                "Authorization".to_string(),
                format!("Token {}", api_key.into()),
            )],
            content_type: "audio/mpeg".to_string(),
            timeout_ms: 30_000,
            extract: TranscriptExtract::JsonPointer(
                "/results/channels/0/alternatives/0/transcript".to_string(),
            ),
        }
    }

    /// Pre-configured endpoint for [Speechmatics](https://www.speechmatics.com)
    /// real-time transcription REST. Auth `Bearer <key>`. Response shape:
    /// `{"results":[{"alternatives":[{"content": "..."}]}, ...]}` —
    /// note the response is a **list** of phrase-level alternatives,
    /// not a single transcript string. Callers needing a single string
    /// should join the list themselves; this endpoint extracts only
    /// the first phrase.
    pub fn speechmatics(api_key: impl Into<String>) -> Self {
        Self {
            name: "speechmatics".to_string(),
            url: "https://asr.api.speechmatics.com/v2/jobs".to_string(),
            headers: vec![(
                "Authorization".to_string(),
                format!("Bearer {}", api_key.into()),
            )],
            content_type: "audio/mpeg".to_string(),
            timeout_ms: 30_000,
            extract: TranscriptExtract::JsonPointer(
                "/results/0/alternatives/0/content".to_string(),
            ),
        }
    }

    /// Pre-configured endpoint for [AssemblyAI](https://www.assemblyai.com)
    /// transcription REST. Auth via `Authorization: <key>` (no Bearer
    /// prefix per their docs). Response shape: `{"text": "..."}`.
    pub fn assemblyai(api_key: impl Into<String>) -> Self {
        Self {
            name: "assemblyai".to_string(),
            url: "https://api.assemblyai.com/v2/transcript".to_string(),
            headers: vec![("Authorization".to_string(), api_key.into())],
            content_type: "audio/mpeg".to_string(),
            timeout_ms: 30_000,
            extract: TranscriptExtract::JsonPointer("/text".to_string()),
        }
    }

    /// Pre-configured endpoint for [Groq](https://groq.com)
    /// `whisper-large-v3` (their fastest STT, often <1s).
    /// Auth `Bearer <key>`. Same wire shape as OpenAI Whisper —
    /// response: `{"text": "..."}`.
    pub fn groq_whisper(api_key: impl Into<String>) -> Self {
        Self {
            name: "groq_whisper".to_string(),
            url: "https://api.groq.com/openai/v1/audio/transcriptions".to_string(),
            headers: vec![(
                "Authorization".to_string(),
                format!("Bearer {}", api_key.into()),
            )],
            content_type: "audio/mpeg".to_string(),
            timeout_ms: 15_000,
            extract: TranscriptExtract::JsonPointer("/text".to_string()),
        }
    }
}

/// Ordered STT endpoint ladder.
#[derive(Debug, Clone, Default)]
pub struct SttPipeline {
    pub endpoints: Vec<SttEndpoint>,
}

impl SttPipeline {
    pub fn new() -> Self {
        Self::default()
    }

    /// Builder-style append.
    pub fn with(mut self, endpoint: SttEndpoint) -> Self {
        self.endpoints.push(endpoint);
        self
    }

    /// Run the ladder against `audio_bytes`. Returns the first
    /// non-empty transcript. If all endpoints fail or return empty,
    /// returns the last collected error.
    pub async fn transcribe(&self, audio_bytes: Vec<u8>) -> Result<String> {
        if self.endpoints.is_empty() {
            return Err(anyhow!("SttPipeline has no endpoints configured"));
        }
        let mut last_err: Option<String> = None;
        for ep in &self.endpoints {
            let client = match reqwest::Client::builder()
                .timeout(Duration::from_millis(ep.timeout_ms))
                .build()
            {
                Ok(c) => c,
                Err(e) => {
                    last_err = Some(format!("{}: client build: {e}", ep.name));
                    continue;
                }
            };
            let mut req = client
                .post(&ep.url)
                .header("Content-Type", ep.content_type.clone())
                .body(audio_bytes.clone());
            for (k, v) in &ep.headers {
                req = req.header(k.as_str(), v.as_str());
            }
            let resp = match req.send().await {
                Ok(r) => r,
                Err(e) => {
                    last_err = Some(format!("{}: send: {e}", ep.name));
                    continue;
                }
            };
            if !resp.status().is_success() {
                last_err = Some(format!("{}: HTTP {}", ep.name, resp.status().as_u16()));
                continue;
            }
            let body = match resp.text().await {
                Ok(b) => b,
                Err(e) => {
                    last_err = Some(format!("{}: read body: {e}", ep.name));
                    continue;
                }
            };
            match extract_transcript(&body, &ep.extract) {
                Ok(t) if !t.trim().is_empty() => return Ok(t),
                Ok(_) => {
                    last_err = Some(format!("{}: empty transcript", ep.name));
                }
                Err(e) => {
                    last_err = Some(format!("{}: extract: {e}", ep.name));
                }
            }
        }
        Err(anyhow!(
            "all {} STT endpoints failed; last error: {}",
            self.endpoints.len(),
            last_err.unwrap_or_else(|| "no error captured".to_string()),
        ))
    }
}

/// Apply a [`TranscriptExtract`] to a raw response body. Pure
/// function — fully covered by unit tests.
///
/// # Examples
///
/// ```
/// use captchaforge::stt::{extract_transcript, TranscriptExtract};
/// let raw = TranscriptExtract::RawBody;
/// assert_eq!(extract_transcript("hello", &raw).unwrap(), "hello");
///
/// let json = TranscriptExtract::JsonPointer("/text".to_string());
/// let body = r#"{"text": "five seven nine"}"#;
/// assert_eq!(extract_transcript(body, &json).unwrap(), "five seven nine");
/// ```
pub fn extract_transcript(body: &str, extract: &TranscriptExtract) -> Result<String> {
    match extract {
        TranscriptExtract::RawBody => Ok(body.trim().to_string()),
        TranscriptExtract::JsonPointer(ptr) => {
            let parsed: serde_json::Value = serde_json::from_str(body)
                .map_err(|e| anyhow!("response is not valid JSON: {e}"))?;
            let v = parsed.pointer(ptr).ok_or_else(|| {
                anyhow!("JSON pointer {ptr} did not resolve in response")
            })?;
            // Accept string OR a JSON value coercible to string
            // (some APIs return raw `"text"` at the pointer).
            v.as_str()
                .map(|s| s.trim().to_string())
                .ok_or_else(|| anyhow!("pointer {ptr} did not resolve to a string"))
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn vendor_endpoints_have_distinct_urls() {
        let key = "test-key";
        let endpoints = [
            SttEndpoint::openai_whisper(key),
            SttEndpoint::deepgram(key),
            SttEndpoint::speechmatics(key),
            SttEndpoint::assemblyai(key),
            SttEndpoint::groq_whisper(key),
        ];
        let urls: std::collections::HashSet<&str> =
            endpoints.iter().map(|e| e.url.as_str()).collect();
        assert_eq!(
            urls.len(),
            endpoints.len(),
            "vendor STT endpoints must have distinct URLs"
        );
    }

    #[test]
    fn vendor_endpoints_have_distinct_names() {
        let key = "test-key";
        let endpoints = [
            SttEndpoint::openai_whisper(key),
            SttEndpoint::deepgram(key),
            SttEndpoint::speechmatics(key),
            SttEndpoint::assemblyai(key),
            SttEndpoint::groq_whisper(key),
        ];
        let names: std::collections::HashSet<&str> =
            endpoints.iter().map(|e| e.name.as_str()).collect();
        assert_eq!(names.len(), endpoints.len());
    }

    #[test]
    fn assemblyai_uses_bare_authorization_header() {
        // AssemblyAI's docs require `Authorization: <key>` (no `Bearer`).
        // Other vendors use Bearer / Token; keep the contracts straight.
        let ep = SttEndpoint::assemblyai("ak_xyz");
        let auth = ep
            .headers
            .iter()
            .find(|(k, _)| k == "Authorization")
            .expect("assemblyai must set Authorization");
        assert_eq!(auth.1, "ak_xyz", "assemblyai must NOT prefix with Bearer");
    }

    #[test]
    fn deepgram_uses_token_prefix_authorization() {
        let ep = SttEndpoint::deepgram("dg_key");
        let auth = ep
            .headers
            .iter()
            .find(|(k, _)| k == "Authorization")
            .expect("deepgram must set Authorization");
        assert_eq!(auth.1, "Token dg_key");
    }

    #[test]
    fn raw_body_returns_trimmed_input() {
        assert_eq!(
            extract_transcript("  hello world\n", &TranscriptExtract::RawBody).unwrap(),
            "hello world",
        );
    }

    #[test]
    fn json_pointer_extracts_string_at_pointer() {
        let body = r#"{"text": "two three four"}"#;
        let extract = TranscriptExtract::JsonPointer("/text".to_string());
        assert_eq!(
            extract_transcript(body, &extract).unwrap(),
            "two three four",
        );
    }

    #[test]
    fn json_pointer_handles_nested_paths() {
        let body = r#"{"results":[{"alternatives":[{"transcript":"one two three"}]}]}"#;
        let extract = TranscriptExtract::JsonPointer(
            "/results/0/alternatives/0/transcript".to_string(),
        );
        assert_eq!(
            extract_transcript(body, &extract).unwrap(),
            "one two three",
        );
    }

    #[test]
    fn json_pointer_errors_on_missing_path() {
        let body = r#"{"text": "x"}"#;
        let extract = TranscriptExtract::JsonPointer("/wrong".to_string());
        assert!(extract_transcript(body, &extract).is_err());
    }

    #[test]
    fn json_pointer_errors_on_non_string_value() {
        let body = r#"{"text": 42}"#;
        let extract = TranscriptExtract::JsonPointer("/text".to_string());
        assert!(extract_transcript(body, &extract).is_err());
    }

    #[test]
    fn json_pointer_errors_on_invalid_json() {
        let body = "not json";
        let extract = TranscriptExtract::JsonPointer("/text".to_string());
        assert!(extract_transcript(body, &extract).is_err());
    }

    #[test]
    fn local_whisper_constructor_defaults() {
        let e = SttEndpoint::local_whisper("http://localhost:9000/asr");
        assert_eq!(e.name, "local_whisper");
        assert_eq!(e.url, "http://localhost:9000/asr");
        assert_eq!(e.content_type, "audio/mpeg");
        assert!(e.headers.is_empty());
        assert!(matches!(e.extract, TranscriptExtract::RawBody));
    }

    #[test]
    fn openai_whisper_constructor_sets_auth() {
        let e = SttEndpoint::openai_whisper("sk-test-1234");
        assert!(e
            .headers
            .iter()
            .any(|(k, v)| k == "Authorization" && v == "Bearer sk-test-1234"));
        assert_eq!(e.url, "https://api.openai.com/v1/audio/transcriptions");
        if let TranscriptExtract::JsonPointer(p) = &e.extract {
            assert_eq!(p, "/text");
        } else {
            panic!("expected JsonPointer extract");
        }
    }

    #[test]
    fn pipeline_builder_chains_endpoints_in_order() {
        let p = SttPipeline::new()
            .with(SttEndpoint::local_whisper("http://a"))
            .with(SttEndpoint::openai_whisper("k"));
        assert_eq!(p.endpoints.len(), 2);
        assert_eq!(p.endpoints[0].name, "local_whisper");
        assert_eq!(p.endpoints[1].name, "openai_whisper");
    }

    #[tokio::test]
    async fn empty_pipeline_returns_error() {
        let p = SttPipeline::new();
        let err = p.transcribe(vec![1, 2, 3]).await.unwrap_err().to_string();
        assert!(err.contains("no endpoints"));
    }

    #[tokio::test]
    async fn pipeline_returns_aggregated_error_when_all_fail() {
        // All endpoints point at unreachable hosts. The error message
        // names the count and last failure.
        let p = SttPipeline::new()
            .with(SttEndpoint::local_whisper(
                "http://127.0.0.1:1/unreachable-1",
            ))
            .with(SttEndpoint::local_whisper(
                "http://127.0.0.1:1/unreachable-2",
            ));
        let err = p.transcribe(vec![1, 2, 3]).await.unwrap_err().to_string();
        assert!(err.contains("all 2 STT endpoints failed"), "got: {err}");
    }
}