mineru 0.5.0

Rust client, CLI, and API server for OpenAI-compatible MinerU document parsing
Documentation
use serde::{Deserialize, Serialize};
use std::{fmt, path::PathBuf};

#[derive(Clone, Copy, Debug, Eq, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "lowercase")]
#[non_exhaustive]
pub enum OfficialTier {
    Flash,
    Basic,
    Standard,
    Advanced,
}
impl OfficialTier {
    pub(crate) fn as_str(self) -> &'static str {
        match self {
            Self::Flash => "flash",
            Self::Basic => "basic",
            Self::Standard => "standard",
            Self::Advanced => "advanced",
        }
    }
}
impl Default for OfficialTier {
    fn default() -> Self {
        Self::Standard
    }
}

#[derive(Clone, Copy, Debug, Eq, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "lowercase")]
#[non_exhaustive]
pub enum OfficialOcrMode {
    Auto,
    Txt,
    Ocr,
}
impl OfficialOcrMode {
    pub(crate) fn as_str(self) -> &'static str {
        match self {
            Self::Auto => "auto",
            Self::Txt => "txt",
            Self::Ocr => "ocr",
        }
    }
}
impl Default for OfficialOcrMode {
    fn default() -> Self {
        Self::Auto
    }
}

#[derive(Clone, Default, Serialize, Deserialize)]
#[serde(default, rename_all = "snake_case")]
#[non_exhaustive]
pub struct HtmlSourceContext {
    pub source_uri: Option<String>,
    pub local_resource_root: Option<PathBuf>,
    pub transport_encoding: Option<String>,
}
impl HtmlSourceContext {
    pub fn new() -> Self {
        Self::default()
    }
    pub fn with_source_uri(mut self, value: impl Into<String>) -> Self {
        self.source_uri = Some(value.into());
        self
    }
    pub fn with_local_resource_root(mut self, value: impl Into<PathBuf>) -> Self {
        self.local_resource_root = Some(value.into());
        self
    }
    pub fn with_transport_encoding(mut self, value: impl Into<String>) -> Self {
        self.transport_encoding = Some(value.into());
        self
    }
}
impl fmt::Debug for HtmlSourceContext {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_struct("HtmlSourceContext")
            .field(
                "source_uri",
                &self
                    .source_uri
                    .as_ref()
                    .map(|value| crate::official::error::redact_secret(value, 1024)),
            )
            .field(
                "local_resource_root",
                &self.local_resource_root.as_ref().map(|_| "[trusted root]"),
            )
            .field("transport_encoding", &self.transport_encoding)
            .finish()
    }
}

#[derive(Clone, Serialize, Deserialize)]
#[serde(default, rename_all = "snake_case")]
#[non_exhaustive]
pub struct OfficialVlmConfig {
    pub engine: String,
    pub server_url: String,
    pub api_key: String,
    pub model: String,
    pub http_timeout: u64,
    pub max_concurrency: usize,
}
impl Default for OfficialVlmConfig {
    fn default() -> Self {
        Self {
            engine: "auto".into(),
            server_url: String::new(),
            api_key: String::new(),
            model: String::new(),
            http_timeout: 600,
            max_concurrency: 100,
        }
    }
}
impl OfficialVlmConfig {
    pub fn new() -> Self {
        Self::default()
    }
    pub fn with_engine(mut self, value: impl Into<String>) -> Self {
        self.engine = value.into();
        self
    }
    pub fn with_server_url(mut self, value: impl Into<String>) -> Self {
        self.server_url = value.into();
        self
    }
    pub fn with_api_key(mut self, value: impl Into<String>) -> Self {
        self.api_key = value.into();
        self
    }
    pub fn with_model(mut self, value: impl Into<String>) -> Self {
        self.model = value.into();
        self
    }
    pub fn with_http_timeout(mut self, value: u64) -> Self {
        self.http_timeout = value;
        self
    }
    pub fn with_max_concurrency(mut self, value: usize) -> Self {
        self.max_concurrency = value;
        self
    }
}
impl fmt::Debug for OfficialVlmConfig {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_struct("OfficialVlmConfig")
            .field("engine", &self.engine)
            .field(
                "server_url",
                &crate::official::error::redact_secret(&self.server_url, 1024),
            )
            .field(
                "api_key",
                &(!self.api_key.is_empty()).then_some("[redacted]"),
            )
            .field("model", &self.model)
            .field("http_timeout", &self.http_timeout)
            .field("max_concurrency", &self.max_concurrency)
            .finish()
    }
}

#[derive(Clone, Default, Serialize, Deserialize)]
#[serde(default, rename_all = "snake_case")]
#[non_exhaustive]
pub struct OfficialParseOptions {
    pub tier: Option<OfficialTier>,
    pub ocr_mode: Option<OfficialOcrMode>,
    pub image_analysis: Option<bool>,
    pub page_range: Option<String>,
    pub source_context: Option<HtmlSourceContext>,
    pub vlm_config: Option<OfficialVlmConfig>,
    pub vlm_server_url: Option<String>,
    pub vlm_api_key: Option<String>,
    pub vlm_model: Option<String>,
}
impl fmt::Debug for OfficialParseOptions {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_struct("OfficialParseOptions")
            .field("tier", &self.tier)
            .field("ocr_mode", &self.ocr_mode)
            .field("image_analysis", &self.image_analysis)
            .field("page_range", &self.page_range)
            .field("source_context", &self.source_context)
            .field("vlm_config", &self.vlm_config)
            .field(
                "vlm_server_url",
                &self
                    .vlm_server_url
                    .as_ref()
                    .map(|value| crate::official::error::redact_secret(value, 1024)),
            )
            .field(
                "vlm_api_key",
                &self.vlm_api_key.as_ref().map(|_| "[redacted]"),
            )
            .field("vlm_model", &self.vlm_model)
            .finish()
    }
}

impl OfficialParseOptions {
    pub fn new() -> Self {
        Self::default()
    }
    pub fn with_tier(mut self, value: OfficialTier) -> Self {
        self.tier = Some(value);
        self
    }
    pub fn with_ocr_mode(mut self, value: OfficialOcrMode) -> Self {
        self.ocr_mode = Some(value);
        self
    }
    pub fn with_image_analysis(mut self, value: bool) -> Self {
        self.image_analysis = Some(value);
        self
    }
    pub fn with_page_range(mut self, value: impl Into<String>) -> Self {
        self.page_range = Some(value.into());
        self
    }
    pub fn with_source_context(mut self, value: HtmlSourceContext) -> Self {
        self.source_context = Some(value);
        self
    }
    pub fn with_vlm_config(mut self, value: OfficialVlmConfig) -> Self {
        self.vlm_config = Some(value);
        self
    }
    pub fn with_vlm_server_url(mut self, value: impl Into<String>) -> Self {
        self.vlm_server_url = Some(value.into());
        self
    }
    pub fn with_vlm_api_key(mut self, value: impl Into<String>) -> Self {
        self.vlm_api_key = Some(value.into());
        self
    }
    pub fn with_vlm_model(mut self, value: impl Into<String>) -> Self {
        self.vlm_model = Some(value.into());
        self
    }

    pub(crate) fn validate(&self, suffix: &str) -> Result<(), String> {
        let tier = self.tier.unwrap_or_default();
        if !crate::official::input::suffixes().contains(&suffix) {
            return Err("unsupported official input format".into());
        }
        let native = !matches!(
            suffix,
            "pdf" | "png" | "jpg" | "jpeg" | "webp" | "gif" | "bmp" | "tiff" | "jp2"
        );
        if native && tier != OfficialTier::Flash {
            return Err("native document formats require the flash tier".into());
        }
        if self.page_range.as_deref().is_some_and(str::is_empty) {
            return Err("page_range must be nonempty".into());
        }
        if suffix != "pdf" && self.page_range.is_some() {
            return Err("page ranges are supported for PDF input only".into());
        }
        if self.vlm_config.is_some()
            && (self.vlm_server_url.is_some()
                || self.vlm_api_key.is_some()
                || self.vlm_model.is_some())
        {
            return Err("vlm_config replacement cannot be combined with legacy VLM aliases".into());
        }
        if let Some(config) = &self.vlm_config {
            if !["auto", "llama-cpp", "vllm", "lmdeploy", "mlx"].contains(&config.engine.as_str()) {
                return Err("unsupported VLM engine".into());
            }
            if config.http_timeout == 0 || config.max_concurrency == 0 {
                return Err("VLM timeout and concurrency must be positive".into());
            }
        }
        Ok(())
    }
}

#[cfg(test)]
mod tests {
    use super::{OfficialParseOptions, OfficialVlmConfig};

    #[test]
    fn debug_redacts_vlm_url_secrets_and_preserves_useful_fields() {
        let options = OfficialParseOptions::new()
            .with_vlm_server_url(
                "https://user:password@vlm.example/v1?api_key=query-secret&token=token-secret",
            )
            .with_page_range("1-3")
            .with_vlm_model("public-model");
        let debug = format!("{options:?}");

        for secret in ["user", "password", "query-secret", "token-secret"] {
            assert!(!debug.contains(secret), "{secret} leaked in {debug}");
        }
        assert!(debug.contains("vlm_server_url: Some"));
        assert!(debug.contains("page_range: Some(\"1-3\")"));
        assert!(debug.contains("vlm_model: Some(\"public-model\")"));
    }

    #[test]
    fn debug_keeps_config_url_redaction() {
        let options = OfficialParseOptions::new().with_vlm_config(
            OfficialVlmConfig::new()
                .with_server_url("https://user:password@vlm.example/v1?api_key=config-secret"),
        );
        let debug = format!("{options:?}");

        for secret in ["user", "password", "config-secret"] {
            assert!(!debug.contains(secret), "{secret} leaked in {debug}");
        }
    }
}