captchaforge/

backends.rs

//! Auto-detect available solver backends and configure the chain.
//!
//! Production captchaforge ergonomics: a developer should be able to
//! `cargo add captchaforge && captchaforge::auto_solve(page).await` and
//! have it Just Work, no manual VLM endpoint configuration, no STT
//! server URLs, no tesseract path hunting. This module does the
//! probing and surfaces the result as [`Capabilities`].
//!
//! # What gets probed
//!
//! - **Ollama**: HTTP probe `localhost:11434/api/tags`. If reachable,
//!   the response lists locally-pulled models. We pick the first
//!   model whose name matches a known vision-model pattern
//!   (`qwen3-vl`, `llava`, `bakllava`, `qwen2-vl`,
//!   `qwen3-vl`, `gemma3-vl`, `pixtral`, `minicpm-v`).
//! - **Whisper CLI**: `which whisper` on PATH. The OpenAI Whisper
//!   reference CLI; `whisper <audio.mp3> --model tiny` returns a
//!   transcript on stdout.
//! - **Tesseract**: `which tesseract` on PATH. Used for canvas /
//!   SVG / static-text CAPTCHAs.
//! - **OpenAI**: `OPENAI_API_KEY` env var. If set, OpenAI Whisper
//!   API is available as STT fallback.
//!
//! # Auto-install
//!
//! [`Capabilities::ensure_vlm_model`] will `ollama pull` a default
//! vision model if Ollama is present but no vision model is. Disabled
//! by default; opt in by calling `ensure_vlm_model()` directly.
//!
//! # Example
//!
//! ```rust,no_run
//! # async fn run() {
//! let caps = captchaforge::backends::probe().await;
//! if caps.vlm.is_some() {
//!     println!("VLM ready: {}", caps.vlm.as_ref().unwrap().model);
//! }
//! # }
//! ```

use std::time::Duration;

use serde::{Deserialize, Serialize};

/// Set of vendor model-name fragments that identify a vision-capable
/// Ollama model. Order matters: earlier entries are preferred when
/// multiple match.
pub const VISION_MODEL_PATTERNS: &[&str] = &[
    "qwen3-vl",
    "llava",
    "bakllava",
    "qwen2-vl",
    "gemma3-vl",
    "pixtral",
    "minicpm-v",
    "moondream",
];

/// Default vision model to auto-pull when Ollama is present but no
/// vision model is. Picked for size/quality tradeoff: ~7GB, runs on
/// most consumer GPUs and decent CPUs.
pub const DEFAULT_VLM_AUTO_PULL: &str = "qwen3-vl:8b-thinking";

/// Default Whisper model size to use when invoking the local CLI.
///
/// `base` (~142MB) reliably transcribes spelled digits where `tiny` often
/// hallucinates homophones ("four" → "for", "two" → "to/too", "nine" →
/// "high"). For CAPTCHA audio, usually 3-6 spoken digits, accuracy
/// matters more than the ~70MB size delta. CPU latency stays under 1s.
pub const DEFAULT_WHISPER_MODEL: &str = "base";

/// Detected backend capabilities. Populated by [`probe`]; consumed by
/// [`crate::config::Config::build_chain`] to wire solvers conditionally.
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
pub struct Capabilities {
    pub vlm: Option<VlmBackend>,
    pub stt: Option<SttBackend>,
    pub ocr: Option<OcrBackend>,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct VlmBackend {
    /// Endpoint for chat-completion (Ollama-compatible).
    pub endpoint: String,
    /// Model name to send in the request body.
    pub model: String,
    /// Source: `"ollama"`, `"openai"`, etc. (for logging/telemetry).
    pub source: String,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct SttBackend {
    pub kind: SttKind,
    /// For `WhisperCli` this is the path to the binary; for
    /// `OpenAIApi` the API base URL; for `LocalServer` the HTTP URL.
    pub endpoint: String,
    /// For `WhisperCli` the model size (`tiny`/`base`/`small`/...).
    pub model: Option<String>,
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum SttKind {
    WhisperCli,
    OpenAIApi,
    LocalServer,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct OcrBackend {
    /// Path to the `tesseract` binary.
    pub binary: String,
}

/// Probe the local environment for available backends. Cheap (~50ms
/// total) (three parallel HTTP/PATH checks).
pub async fn probe() -> Capabilities {
    let (vlm, stt, ocr) = tokio::join!(probe_vlm(), probe_stt(), probe_ocr());
    Capabilities { vlm, stt, ocr }
}

async fn probe_vlm() -> Option<VlmBackend> {
    let client = match crate::http_client::timed_client(Duration::from_millis(800)) {
        Ok(c) => c,
        Err(_) => return None,
    };

    // Tier 1: Ollama on the default port.
    let ollama_endpoint = "http://localhost:11434";
    if let Some(backend) = probe_vlm_ollama(&client, ollama_endpoint).await {
        return Some(backend);
    }

    // Tier 2: llama.cpp server on the conventional port (8000).
    let llama_endpoint = std::env::var("LLAMACPP_VLM_ENDPOINT")
        .unwrap_or_else(|_| "http://localhost:8000".to_string());
    if let Some(backend) = probe_vlm_llamacpp(&client, &llama_endpoint).await {
        return Some(backend);
    }

    None
}

async fn probe_vlm_ollama(client: &reqwest::Client, endpoint: &str) -> Option<VlmBackend> {
    let resp = client
        .get(format!("{endpoint}/api/tags"))
        .send()
        .await
        .ok()?;
    if !resp.status().is_success() {
        return None;
    }
    #[derive(Deserialize)]
    struct OllamaTags {
        models: Vec<OllamaModel>,
    }
    #[derive(Deserialize)]
    struct OllamaModel {
        name: String,
    }
    let body: OllamaTags = resp.json().await.ok()?;
    let model = pick_best_vision_model(
        &body
            .models
            .iter()
            .map(|m| m.name.as_str())
            .collect::<Vec<_>>(),
    )?;
    Some(VlmBackend {
        endpoint: endpoint.to_string(),
        model: model.to_string(),
        source: "ollama".to_string(),
    })
}

async fn probe_vlm_llamacpp(client: &reqwest::Client, endpoint: &str) -> Option<VlmBackend> {
    // llama.cpp server exposes /v1/models (OpenAI-compatible) when running.
    let resp = client
        .get(format!("{endpoint}/v1/models"))
        .send()
        .await
        .ok()?;
    if !resp.status().is_success() {
        return None;
    }
    #[derive(Deserialize)]
    struct LlamaModels {
        data: Vec<LlamaModel>,
    }
    #[derive(Deserialize)]
    struct LlamaModel {
        id: String,
    }
    let body: LlamaModels = resp.json().await.ok()?;
    let model = body.data.first()?;
    Some(VlmBackend {
        endpoint: endpoint.to_string(),
        model: model.id.clone(),
        source: "llamacpp".to_string(),
    })
}

/// Pure helper: pick the best vision model from a list of Ollama
/// model names by matching against [`VISION_MODEL_PATTERNS`] in
/// priority order.
///
/// # Examples
///
/// ```
/// use captchaforge::backends::pick_best_vision_model;
/// let names = ["llama3.1:8b", "llava:13b", "qwen2.5-coder:14b"];
/// assert_eq!(pick_best_vision_model(&names), Some("llava:13b"));
/// // No vision model → None.
/// let names = ["llama3.1:8b", "qwen2.5-coder:14b"];
/// assert_eq!(pick_best_vision_model(&names), None);
/// // Highest-priority pattern wins (qwen3-vl before llava).
/// let names = ["llava:13b", "qwen3-vl:8b-thinking"];
/// assert_eq!(pick_best_vision_model(&names), Some("qwen3-vl:8b-thinking"));
/// ```
pub fn pick_best_vision_model<'a>(model_names: &[&'a str]) -> Option<&'a str> {
    for pattern in VISION_MODEL_PATTERNS {
        for name in model_names {
            if name.contains(pattern) {
                return Some(name);
            }
        }
    }
    None
}

async fn probe_stt() -> Option<SttBackend> {
    // Tier 1: local whisper CLI on PATH.
    if let Some(path) = which("whisper").or_else(|| which("whisper-cli")) {
        return Some(SttBackend {
            kind: SttKind::WhisperCli,
            endpoint: path,
            model: Some(DEFAULT_WHISPER_MODEL.to_string()),
        });
    }
    // Tier 2: OpenAI Whisper API via env var.
    if std::env::var("OPENAI_API_KEY").is_ok() {
        return Some(SttBackend {
            kind: SttKind::OpenAIApi,
            endpoint: "https://api.openai.com/v1/audio/transcriptions".to_string(),
            model: Some("whisper-1".to_string()),
        });
    }
    // Tier 3: classic local server on the conventional port.
    let client = crate::http_client::timed_client(Duration::from_millis(300)).ok()?;
    if client
        .get("http://localhost:9000/")
        .send()
        .await
        .map(|r| r.status().is_success() || r.status().as_u16() == 405)
        .unwrap_or(false)
    {
        return Some(SttBackend {
            kind: SttKind::LocalServer,
            endpoint: "http://localhost:9000/asr".to_string(),
            model: None,
        });
    }
    None
}

async fn probe_ocr() -> Option<OcrBackend> {
    which("tesseract").map(|binary| OcrBackend { binary })
}

/// Locate a binary on PATH. Returns the absolute path on hit, `None`
/// on miss. Pure helper used by both `probe_stt` and `probe_ocr`.
///
/// # Examples
///
/// ```
/// use captchaforge::backends::which;
/// // Almost-certainly-present binary on a Unix system.
/// // Skipped on Windows / locked-down environments.
/// # if cfg!(unix) {
/// assert!(which("sh").is_some(), "sh should be on PATH");
/// # }
/// // Definitely-not-present binary.
/// assert!(which("definitely-not-a-real-binary-xyzzy").is_none());
/// ```
pub fn which(binary: &str) -> Option<String> {
    let path = std::env::var_os("PATH")?;
    for dir in std::env::split_paths(&path) {
        let candidate = dir.join(binary);
        if candidate.is_file() {
            return Some(candidate.to_string_lossy().into_owned());
        }
    }
    None
}

impl Capabilities {
    /// Returns true if any solver-backing capability is present. Used
    /// by the chain to short-circuit the "no backends installed,
    /// chain will only handle passive Turnstile" log message.
    pub fn any(&self) -> bool {
        self.vlm.is_some() || self.stt.is_some() || self.ocr.is_some()
    }

    /// Human-readable one-liner describing what was detected. Used by
    /// `auto_solve` to log on first call.
    pub fn summary(&self) -> String {
        let mut parts = Vec::new();
        if let Some(v) = &self.vlm {
            parts.push(format!("vlm:{} ({})", v.model, v.source));
        }
        if let Some(s) = &self.stt {
            parts.push(format!("stt:{:?}", s.kind));
        }
        if self.ocr.is_some() {
            parts.push("ocr:tesseract".to_string());
        }
        if parts.is_empty() {
            "no backends detected".to_string()
        } else {
            parts.join(", ")
        }
    }

    /// Returns a one-line install hint per missing backend, suitable
    /// for surfacing to a user who needs higher solve coverage. Empty
    /// when every backend is already present.
    ///
    /// # Examples
    ///
    /// ```
    /// use captchaforge::backends::Capabilities;
    /// let caps = Capabilities::default();
    /// let hints = caps.install_hints();
    /// assert!(!hints.is_empty(), "no backends ⇒ at least one hint");
    /// assert!(hints.iter().any(|h| h.contains("ollama")));
    /// ```
    pub fn install_hints(&self) -> Vec<String> {
        let mut out = Vec::new();
        if self.vlm.is_none() {
            out.push(
                "vlm: install ollama (https://ollama.com/download) and run \
                 `ollama pull qwen3-vl:8b-thinking`: captchaforge will then \
                 auto-detect it. Solves canvas / SVG / image-grid CAPTCHAs."
                    .to_string(),
            );
        }
        if self.stt.is_none() {
            out.push(
                "stt: install OpenAI Whisper CLI (`pip install -U openai-whisper`) \
                 OR set OPENAI_API_KEY for the hosted Whisper API. Solves \
                 reCAPTCHA v2 audio + generic spoken-digit CAPTCHAs."
                    .to_string(),
            );
        }
        if self.ocr.is_none() {
            out.push(
                "ocr: install tesseract (`apt install tesseract-ocr` / \
                 `brew install tesseract`). Used as a fallback when no VLM \
                 is available."
                    .to_string(),
            );
        }
        out
    }

    /// Auto-install a default vision model when Ollama is reachable
    /// but no vision model is present. Returns `Ok(true)` if pull
    /// succeeded, `Ok(false)` if Ollama isn't reachable, or `Err` on
    /// pull failure.
    ///
    /// Spawns `ollama pull <DEFAULT_VLM_AUTO_PULL>`. Pull progress is
    /// inherited stdio; the call blocks until pull completes (~5-10
    /// minutes for an 11B model on first run).
    pub async fn ensure_vlm_model(&mut self) -> anyhow::Result<bool> {
        if self.vlm.is_some() {
            return Ok(true);
        }
        let ollama = which("ollama");
        let Some(ollama_bin) = ollama else {
            return Ok(false);
        };
        // Verify Ollama daemon is up before spawning a pull.
        let client = crate::http_client::timed_client(Duration::from_millis(800))?;
        if client
            .get("http://localhost:11434/api/tags")
            .send()
            .await
            .map(|r| !r.status().is_success())
            .unwrap_or(true)
        {
            return Ok(false);
        }
        tracing::info!(
            model = DEFAULT_VLM_AUTO_PULL,
            "auto-pulling vision model via Ollama (first-run install)"
        );
        let status = std::process::Command::new(&ollama_bin)
            .arg("pull")
            .arg(DEFAULT_VLM_AUTO_PULL)
            .status()?;
        if !status.success() {
            anyhow::bail!("ollama pull {DEFAULT_VLM_AUTO_PULL} exited {status}");
        }
        // Re-probe so the caller sees the new vlm.
        self.vlm = probe_vlm().await;
        Ok(self.vlm.is_some())
    }
}

#[cfg(test)]
#[path = "backends/tests.rs"]
mod tests;