Skip to content

A fast, helpful, and open-source document parser

63.4 KB
Raw Blame
use std::collections::HashMap;

use pyo3::prelude::*;
use pyo3::types::PyBytes;

use liteparse::config::{
    CropBox, ImageMode, LiteParseConfig, OutputFormat, PageOrientationCorrection,
};
use liteparse::types::PdfInput;

mod cli;

fn parse_output_format(value: &str) -> PyResult<OutputFormat> {
    match value {
        "json" => Ok(OutputFormat::Json),
        "text" => Ok(OutputFormat::Text),
        "markdown" | "md" => Ok(OutputFormat::Markdown),
        _ => Err(PyErr::new::<pyo3::exceptions::PyValueError, _>(format!(
            "invalid output_format: {value} (expected 'json', 'text', or 'markdown')"
        ))),
    }
}

// ---------------------------------------------------------------------------
// Python type wrappers
// ---------------------------------------------------------------------------

#[pyclass(frozen, from_py_object)]
#[derive(Clone)]
struct PyWordBox {
    #[pyo3(get)]
    text: String,
    #[pyo3(get)]
    x: f64,
    #[pyo3(get)]
    y: f64,
    #[pyo3(get)]
    width: f64,
    #[pyo3(get)]
    height: f64,
}

#[pymethods]
impl PyWordBox {
    fn __repr__(&self) -> String {
        format!(
            "WordBox(text={:?}, x={}, y={}, width={}, height={})",
            self.text, self.x, self.y, self.width, self.height
        )
    }
}

impl PyWordBox {
    fn from_rust(word: liteparse::types::WordBox) -> Self {
        Self {
            text: word.text,
            x: word.x as f64,
            y: word.y as f64,
            width: word.width as f64,
            height: word.height as f64,
        }
    }
}

#[pyclass(frozen, from_py_object)]
#[derive(Clone)]
struct PyTextItem {
    #[pyo3(get)]
    text: String,
    #[pyo3(get)]
    x: f64,
    #[pyo3(get)]
    y: f64,
    #[pyo3(get)]
    width: f64,
    #[pyo3(get)]
    height: f64,
    #[pyo3(get)]
    font_name: Option<String>,
    #[pyo3(get)]
    font_size: Option<f64>,
    #[pyo3(get)]
    font_height: Option<f64>,
    #[pyo3(get)]
    font_ascent: Option<f64>,
    #[pyo3(get)]
    font_descent: Option<f64>,
    #[pyo3(get)]
    font_weight: Option<i32>,
    #[pyo3(get)]
    text_width: Option<f64>,
    #[pyo3(get)]
    font_is_buggy: bool,
    #[pyo3(get)]
    mcid: Option<i32>,
    /// Fill color as an eight-character ARGB hex string.
    #[pyo3(get)]
    fill_color: Option<String>,
    /// Stroke color as an eight-character ARGB hex string.
    #[pyo3(get)]
    stroke_color: Option<String>,
    /// Raw PDF content-stream character codes for the source glyphs.
    #[pyo3(get)]
    char_codes: Vec<u32>,
    /// True when the trailing source space was synthesized by PDFium.
    #[pyo3(get)]
    trailing_space_generated: bool,
    /// OCR confidence score (0.0-1.0). None for native PDF text.
    #[pyo3(get)]
    confidence: Option<f64>,
    /// Rotation in degrees (viewport space). Defaults to 0.
    #[pyo3(get)]
    rotation: f64,
    /// Per-word sub-boxes for attribution. Empty unless the parse was
    /// configured with `emit_word_boxes=True`.
    #[pyo3(get)]
    words: Vec<PyWordBox>,
}

#[pymethods]
impl PyTextItem {
    fn __repr__(&self) -> String {
        format!(
            "TextItem(text={:?}, x={}, y={}, width={}, height={})",
            self.text, self.x, self.y, self.width, self.height
        )
    }
}

#[pyclass(frozen, from_py_object)]
#[derive(Clone)]
struct PyAnnotationRect {
    #[pyo3(get)]
    x: f64,
    #[pyo3(get)]
    y: f64,
    #[pyo3(get)]
    width: f64,
    #[pyo3(get)]
    height: f64,
}

impl PyAnnotationRect {
    fn from_rust(rect: liteparse::types::Rect) -> Self {
        Self {
            x: rect.x as f64,
            y: rect.y as f64,
            width: rect.width as f64,
            height: rect.height as f64,
        }
    }
}

#[pyclass(frozen, from_py_object)]
#[derive(Clone)]
struct PyDocumentAnnotation {
    #[pyo3(get)]
    subtype: String,
    #[pyo3(get)]
    contents: Option<String>,
    #[pyo3(get)]
    created: Option<String>,
    #[pyo3(get)]
    modified: Option<String>,
    #[pyo3(get)]
    title: Option<String>,
    #[pyo3(get)]
    rect: Option<PyAnnotationRect>,
    #[pyo3(get)]
    quadpoint_rects: Vec<PyAnnotationRect>,
    #[pyo3(get)]
    uri: Option<String>,
}

#[pyclass(frozen, from_py_object)]
#[derive(Clone)]
struct PyStructureAttribute {
    #[pyo3(get)]
    name: String,
    #[pyo3(get)]
    boolean_value: Option<bool>,
    #[pyo3(get)]
    number_value: Option<f64>,
    #[pyo3(get)]
    string_value: Option<String>,
}

#[pyclass(frozen, from_py_object)]
#[derive(Clone)]
struct PyStructureTreeElement {
    #[pyo3(get)]
    element_type: String,
    #[pyo3(get)]
    id: Option<String>,
    #[pyo3(get)]
    actual_text: Option<String>,
    #[pyo3(get)]
    alt_text: Option<String>,
    #[pyo3(get)]
    title: Option<String>,
    #[pyo3(get)]
    attributes: Vec<PyStructureAttribute>,
    #[pyo3(get)]
    marked_content_ids: Vec<i32>,
    #[pyo3(get)]
    children: Vec<PyStructureTreeElement>,
    #[pyo3(get)]
    annotations: Vec<PyDocumentAnnotation>,
}

#[pyclass(frozen, from_py_object)]
#[derive(Clone)]
struct PyStructureTree {
    #[pyo3(get)]
    roots: Vec<PyStructureTreeElement>,
}

impl PyStructureTreeElement {
    fn from_rust(element: liteparse::types::StructureTreeElement) -> Self {
        Self {
            element_type: element.element_type,
            id: element.id,
            actual_text: element.actual_text,
            alt_text: element.alt_text,
            title: element.title,
            attributes: element
                .attributes
                .into_iter()
                .map(|(name, value)| {
                    let (boolean_value, number_value, string_value) = match value {
                        liteparse::types::StructureAttributeValue::Boolean(value) => {
                            (Some(value), None, None)
                        }
                        liteparse::types::StructureAttributeValue::Number(value) => {
                            (None, Some(f64::from(value)), None)
                        }
                        liteparse::types::StructureAttributeValue::String(value) => {
                            (None, None, Some(value))
                        }
                    };
                    PyStructureAttribute {
                        name,
                        boolean_value,
                        number_value,
                        string_value,
                    }
                })
                .collect(),
            marked_content_ids: element.marked_content_ids,
            children: element.children.into_iter().map(Self::from_rust).collect(),
            annotations: element
                .annotations
                .into_iter()
                .map(PyDocumentAnnotation::from_rust)
                .collect(),
        }
    }
}

impl PyDocumentAnnotation {
    fn from_rust(annotation: liteparse::types::DocumentAnnotation) -> Self {
        Self {
            subtype: annotation.subtype,
            contents: annotation.contents,
            created: annotation.created,
            modified: annotation.modified,
            title: annotation.title,
            rect: annotation.rect.map(PyAnnotationRect::from_rust),
            quadpoint_rects: annotation
                .quadpoint_rects
                .into_iter()
                .map(PyAnnotationRect::from_rust)
                .collect(),
            uri: annotation.uri,
        }
    }
}

/// One table cell: its rendered text and the region it occupied.
///
/// `bbox` is `None` for cells with no ink behind them — padding inserted to
/// square off a ragged grid, or halves of a merged run split at an estimated
/// position rather than an observed boundary.
#[pyclass(frozen, from_py_object)]
#[derive(Clone)]
struct PyLayoutCell {
    #[pyo3(get)]
    text: String,
    #[pyo3(get)]
    bbox: Option<PyAnnotationRect>,
}

impl PyLayoutCell {
    fn from_rust(cell: liteparse::layout::LayoutCell) -> Self {
        Self {
            text: cell.text,
            bbox: cell.bbox.map(PyAnnotationRect::from_rust),
        }
    }
}

/// A classified block plus where it sits on the page.
///
/// `kind` discriminates the block; every field that doesn't apply to a block's
/// kind is `None` (or `False` for the flags). Blocks appear in reading order,
/// matching the order the markdown renderer emits them.
#[pyclass(frozen, from_py_object)]
#[derive(Clone)]
struct PyLayoutBlock {
    /// One of `heading`, `paragraph`, `list_item`, `code`, `table`,
    /// `grid_fallback`, `rule`, `figure`.
    #[pyo3(get)]
    kind: String,
    /// Rendered text for the text-bearing kinds (`heading`, `paragraph`,
    /// `list_item`). Table text lives in `header`/`rows`; code and grid text in
    /// `lines`.
    #[pyo3(get)]
    text: Option<String>,
    /// Heading level (1–6), or list nesting depth for `list_item`.
    #[pyo3(get)]
    level: Option<u8>,
    /// Whether the block's text is uniformly bold / italic. `paragraph` and
    /// `list_item` only.
    #[pyo3(get)]
    bold: bool,
    #[pyo3(get)]
    italic: bool,
    /// `list_item`: whether the list is ordered, and the original marker as it
    /// appeared on the page (`138.`, `iii)`, `•`).
    #[pyo3(get)]
    ordered: Option<bool>,
    #[pyo3(get)]
    marker: Option<String>,
    /// Verbatim source lines for `code` and `grid_fallback`.
    #[pyo3(get)]
    lines: Option<Vec<String>>,
    /// Best-effort language hint for `code`.
    #[pyo3(get)]
    lang: Option<String>,
    /// `table`: the header row, when one was detected.
    #[pyo3(get)]
    header: Option<Vec<PyLayoutCell>>,
    /// `table`: the body rows.
    #[pyo3(get)]
    rows: Option<Vec<Vec<PyLayoutCell>>>,
    /// `figure`: the image's page-scoped id and encoded format, matching the
    /// `img_{id}.{format}` target the markdown renderer emits.
    #[pyo3(get)]
    id: Option<String>,
    #[pyo3(get)]
    format: Option<String>,
    /// Region of the page this block occupies, in the same top-left, 72-DPI
    /// viewport space as `text_items`. `None` when the block has no page
    /// geometry behind it.
    #[pyo3(get)]
    bbox: Option<PyAnnotationRect>,
}

impl PyLayoutBlock {
    fn from_rust(block: liteparse::layout::LayoutBlock) -> Self {
        Self {
            kind: block.kind.to_string(),
            text: block.text,
            level: block.level,
            bold: block.bold,
            italic: block.italic,
            ordered: block.ordered,
            marker: block.marker,
            lines: block.lines,
            lang: block.lang,
            header: block
                .header
                .map(|cells| cells.into_iter().map(PyLayoutCell::from_rust).collect()),
            rows: block.rows.map(|rows| {
                rows.into_iter()
                    .map(|row| row.into_iter().map(PyLayoutCell::from_rust).collect())
                    .collect()
            }),
            id: block.id,
            format: block.format,
            bbox: block.bbox.map(PyAnnotationRect::from_rust),
        }
    }
}

#[pyclass(frozen, from_py_object)]
#[derive(Clone)]
struct PyFormField {
    #[pyo3(get)]
    id: String,
    #[pyo3(get)]
    field_type: String,
    #[pyo3(get)]
    page: u32,
    #[pyo3(get)]
    annotation_index: i32,
    #[pyo3(get)]
    widget_index: i32,
    #[pyo3(get)]
    object_number: Option<i32>,
    #[pyo3(get)]
    name: Option<String>,
    #[pyo3(get)]
    alternate_name: Option<String>,
    #[pyo3(get)]
    value: Option<String>,
    #[pyo3(get)]
    export_value: Option<String>,
    #[pyo3(get)]
    field_flags: i32,
    #[pyo3(get)]
    control_count: Option<i32>,
    #[pyo3(get)]
    control_index: Option<i32>,
    #[pyo3(get)]
    checked: Option<bool>,
    #[pyo3(get)]
    rect: Option<PyAnnotationRect>,
    #[pyo3(get)]
    options: Vec<String>,
    #[pyo3(get)]
    selected_options: Vec<String>,
}

impl PyFormField {
    fn from_rust(field: liteparse::types::FormField) -> Self {
        Self {
            id: field.id,
            field_type: field.field_type,
            page: field.page,
            annotation_index: field.annotation_index,
            widget_index: field.widget_index,
            object_number: field.object_number,
            name: field.name,
            alternate_name: field.alternate_name,
            value: field.value,
            export_value: field.export_value,
            field_flags: field.field_flags,
            control_count: field.control_count,
            control_index: field.control_index,
            checked: field.checked,
            rect: field.rect.map(PyAnnotationRect::from_rust),
            options: field.options,
            selected_options: field.selected_options,
        }
    }
}

impl PyTextItem {
    fn to_rust(&self) -> liteparse::types::TextItem {
        liteparse::types::TextItem {
            text: self.text.clone(),
            x: self.x as f32,
            y: self.y as f32,
            width: self.width as f32,
            height: self.height as f32,
            rotation: self.rotation as f32,
            font_name: self.font_name.clone(),
            font_size: self.font_size.map(|v| v as f32),
            font_height: self.font_height.map(|v| v as f32),
            font_ascent: self.font_ascent.map(|v| v as f32),
            font_descent: self.font_descent.map(|v| v as f32),
            font_weight: self.font_weight,
            text_width: self.text_width.map(|v| v as f32),
            font_is_buggy: self.font_is_buggy,
            mcid: self.mcid,
            fill_color: self.fill_color.clone(),
            stroke_color: self.stroke_color.clone(),
            char_codes: self.char_codes.clone(),
            trailing_space_generated: self.trailing_space_generated,
            confidence: self.confidence.map(|v| v as f32),
            ..Default::default()
        }
    }

    fn from_rust(item: liteparse::types::TextItem) -> Self {
        Self {
            text: item.text,
            x: item.x as f64,
            y: item.y as f64,
            width: item.width as f64,
            height: item.height as f64,
            font_name: item.font_name,
            font_size: item.font_size.map(|v| v as f64),
            font_height: item.font_height.map(|v| v as f64),
            font_ascent: item.font_ascent.map(|v| v as f64),
            font_descent: item.font_descent.map(|v| v as f64),
            font_weight: item.font_weight,
            text_width: item.text_width.map(|v| v as f64),
            font_is_buggy: item.font_is_buggy,
            mcid: item.mcid,
            fill_color: item.fill_color,
            stroke_color: item.stroke_color,
            char_codes: item.char_codes,
            trailing_space_generated: item.trailing_space_generated,
            confidence: item.confidence.map(|v| v as f64),
            rotation: item.rotation as f64,
            words: item.words.into_iter().map(PyWordBox::from_rust).collect(),
        }
    }

    /// `from_rust` with the rich-metadata fields taken from the core-gated
    /// [`liteparse::types::TextMetadata`] view, so the "what counts as text
    /// metadata" list lives in one place instead of per binding. `words` is
    /// left empty unless `word_boxes` (see `LiteParseConfig::output_word_boxes`).
    fn from_rust_for_output(
        mut item: liteparse::types::TextItem,
        extract_text_metadata: bool,
        word_boxes: bool,
    ) -> Self {
        if !word_boxes {
            item.words.clear();
        }
        let meta = item.text_metadata(extract_text_metadata);
        let (fill_color, stroke_color, char_codes) = (
            meta.fill_color.map(str::to_owned),
            meta.stroke_color.map(str::to_owned),
            meta.char_codes.map(<[u32]>::to_vec),
        );
        Self {
            font_height: meta.font_height.map(|v| v as f64),
            font_ascent: meta.font_ascent.map(|v| v as f64),
            font_descent: meta.font_descent.map(|v| v as f64),
            font_weight: meta.font_weight,
            text_width: meta.text_width.map(|v| v as f64),
            font_is_buggy: meta.font_is_buggy.unwrap_or(false),
            mcid: meta.mcid,
            fill_color,
            stroke_color,
            char_codes: char_codes.unwrap_or_default(),
            trailing_space_generated: meta.trailing_space_generated.unwrap_or(false),
            ..Self::from_rust(item)
        }
    }
}

#[pyclass(frozen, from_py_object)]
#[derive(Clone)]
struct PyParsedPage {
    #[pyo3(get)]
    page_num: u32,
    /// The document's `/PageLabels` label for this page ("iv", "A-1"), absent
    /// when the PDF defines none. This is what a reader displays for the page
    /// and is not always its position; fall back to `page_num` when absent.
    #[pyo3(get)]
    page_label: Option<String>,
    #[pyo3(get)]
    width: f64,
    #[pyo3(get)]
    height: f64,
    #[pyo3(get)]
    content_bounds: Option<PyRect>,
    #[pyo3(get)]
    text: String,
    #[pyo3(get)]
    markdown: String,
    #[pyo3(get)]
    text_items: Vec<PyTextItem>,
    #[pyo3(get)]
    complexity: Option<PyPageComplexityStats>,
    #[pyo3(get)]
    vector_graphics: Option<PyVectorGraphics>,
    #[pyo3(get)]
    annotations: Option<Vec<PyDocumentAnnotation>>,
    #[pyo3(get)]
    form_fields: Option<Vec<PyFormField>>,
    #[pyo3(get)]
    structure_tree: Option<PyStructureTree>,
    #[pyo3(get)]
    blocks: Option<Vec<PyLayoutBlock>>,
}

#[pyclass(frozen, from_py_object)]
#[derive(Clone)]
struct PyRect {
    #[pyo3(get)]
    x: f64,
    #[pyo3(get)]
    y: f64,
    #[pyo3(get)]
    width: f64,
    #[pyo3(get)]
    height: f64,
}

#[pyclass(frozen, from_py_object)]
#[derive(Clone)]
struct PyVectorShape {
    #[pyo3(get)]
    bbox: PyRect,
    #[pyo3(get)]
    stroke: bool,
    #[pyo3(get)]
    stroke_color: Option<String>,
    #[pyo3(get)]
    fill: bool,
    #[pyo3(get)]
    fill_color: Option<String>,
    #[pyo3(get)]
    has_curve: bool,
}

#[pyclass(frozen, from_py_object)]
#[derive(Clone)]
struct PyVectorLine {
    #[pyo3(get)]
    x1: f64,
    #[pyo3(get)]
    y1: f64,
    #[pyo3(get)]
    x2: f64,
    #[pyo3(get)]
    y2: f64,
    #[pyo3(get)]
    stroke: bool,
    #[pyo3(get)]
    stroke_width: Option<f64>,
    #[pyo3(get)]
    stroke_color: Option<String>,
    #[pyo3(get)]
    fill: bool,
    #[pyo3(get)]
    fill_color: Option<String>,
}

#[pyclass(frozen, from_py_object)]
#[derive(Clone)]
struct PyVectorGraphics {
    #[pyo3(get)]
    shapes: Vec<PyVectorShape>,
    #[pyo3(get)]
    lines: Vec<PyVectorLine>,
}

impl PyVectorGraphics {
    fn from_rust(v: liteparse::types::VectorGraphics) -> Self {
        Self {
            shapes: v
                .shapes
                .into_iter()
                .map(|s| PyVectorShape {
                    bbox: PyRect {
                        x: s.bbox.x as f64,
                        y: s.bbox.y as f64,
                        width: s.bbox.width as f64,
                        height: s.bbox.height as f64,
                    },
                    stroke: s.stroke,
                    stroke_color: s.stroke_color,
                    fill: s.fill,
                    fill_color: s.fill_color,
                    has_curve: s.has_curve,
                })
                .collect(),
            lines: v
                .lines
                .into_iter()
                .map(|l| PyVectorLine {
                    x1: l.x1 as f64,
                    y1: l.y1 as f64,
                    x2: l.x2 as f64,
                    y2: l.y2 as f64,
                    stroke: l.stroke,
                    stroke_width: l.stroke_width.map(f64::from),
                    stroke_color: l.stroke_color,
                    fill: l.fill,
                    fill_color: l.fill_color,
                })
                .collect(),
        }
    }
}

#[pymethods]
impl PyParsedPage {
    fn __repr__(&self) -> String {
        format!(
            "ParsedPage(page_num={}, width={}, height={}, text_items={})",
            self.page_num,
            self.width,
            self.height,
            self.text_items.len()
        )
    }
}

impl PyParsedPage {
    fn from_rust(
        page: liteparse::types::ParsedPage,
        extract_text_metadata: bool,
        word_boxes: bool,
    ) -> Self {
        Self {
            page_num: page.page_number as u32,
            page_label: page.page_label.clone(),
            width: page.page_width as f64,
            height: page.page_height as f64,
            content_bounds: page.content_bounds.as_ref().map(|b| PyRect {
                x: b.x as f64,
                y: b.y as f64,
                width: b.width as f64,
                height: b.height as f64,
            }),
            text: page.text,
            markdown: page.markdown,
            text_items: page
                .text_items
                .into_iter()
                .map(|item| {
                    PyTextItem::from_rust_for_output(item, extract_text_metadata, word_boxes)
                })
                .collect(),
            complexity: page
                .complexity
                .as_ref()
                .map(PyPageComplexityStats::from_rust),
            vector_graphics: page.vector_graphics.map(PyVectorGraphics::from_rust),
            annotations: page.annotations.map(|annotations| {
                annotations
                    .into_iter()
                    .map(PyDocumentAnnotation::from_rust)
                    .collect()
            }),
            form_fields: page
                .form_fields
                .map(|fields| fields.into_iter().map(PyFormField::from_rust).collect()),
            structure_tree: page.structure_tree.map(|tree| PyStructureTree {
                roots: tree
                    .roots
                    .into_iter()
                    .map(PyStructureTreeElement::from_rust)
                    .collect(),
            }),
            blocks: page
                .blocks
                .map(|blocks| blocks.into_iter().map(PyLayoutBlock::from_rust).collect()),
        }
    }
}

#[pyclass(frozen, from_py_object)]
#[derive(Clone)]
struct PyParseResult {
    #[pyo3(get)]
    total_pages: u32,
    #[pyo3(get)]
    pages: Vec<PyParsedPage>,
    #[pyo3(get)]
    text: String,
    #[pyo3(get)]
    images: Vec<PyExtractedImage>,
    #[pyo3(get)]
    screenshots: Vec<PyScreenshotResult>,
    #[pyo3(get)]
    image_error_count: u32,
    #[pyo3(get)]
    page_errors: Vec<PyPageError>,
    #[pyo3(get)]
    form_type: Option<i32>,
    #[pyo3(get)]
    creator: Option<String>,
    #[pyo3(get)]
    producer: Option<String>,
    #[pyo3(get)]
    doc_meta: Option<PyDocumentMetadata>,
    #[pyo3(get)]
    xfa_packets: Option<Vec<PyXfaPacket>>,
}

#[pyclass(frozen, from_py_object)]
#[derive(Clone)]
struct PyPageError {
    #[pyo3(get)]
    page_num: u32,
    #[pyo3(get)]
    message: String,
}

#[pyclass(frozen, from_py_object)]
#[derive(Clone)]
struct PyDocumentMetadata {
    #[pyo3(get)]
    creation_date: Option<String>,
    #[pyo3(get)]
    mod_date: Option<String>,
    #[pyo3(get)]
    file_version: Option<i32>,
    #[pyo3(get)]
    is_encrypted: Option<bool>,
    #[pyo3(get)]
    security_handler_revision: Option<i32>,
    #[pyo3(get)]
    permissions: Option<u64>,
    #[pyo3(get)]
    eof_section_count: Option<u32>,
    #[pyo3(get)]
    startxref_count: Option<u32>,
    #[pyo3(get)]
    trailer_id_pair_differs: Option<bool>,
    #[pyo3(get)]
    raw_file_size: Option<u64>,
    #[pyo3(get)]
    xmp: Option<String>,
    #[pyo3(get)]
    xmp_truncated: Option<bool>,
    #[pyo3(get)]
    signature_count: Option<u32>,
    #[pyo3(get)]
    signature_byte_range_reaches_eof: Option<bool>,
}

impl From<liteparse::types::DocumentMetadata> for PyDocumentMetadata {
    fn from(metadata: liteparse::types::DocumentMetadata) -> Self {
        Self {
            creation_date: metadata.creation_date,
            mod_date: metadata.mod_date,
            file_version: metadata.file_version,
            is_encrypted: metadata.is_encrypted,
            security_handler_revision: metadata.security_handler_revision,
            permissions: metadata.permissions,
            eof_section_count: metadata.eof_section_count,
            startxref_count: metadata.startxref_count,
            trailer_id_pair_differs: metadata.trailer_id_pair_differs,
            raw_file_size: metadata.raw_file_size,
            xmp: metadata.xmp,
            xmp_truncated: metadata.xmp_truncated,
            signature_count: metadata.signature_count,
            signature_byte_range_reaches_eof: metadata.signature_byte_range_reaches_eof,
        }
    }
}

/// One raw packet from an XFA form document's `/XFA` array.
#[pyclass(frozen, from_py_object)]
#[derive(Clone)]
struct PyXfaPacket {
    #[pyo3(get)]
    index: u32,
    #[pyo3(get)]
    name: Option<String>,
    #[pyo3(get)]
    content_length: u32,
    #[pyo3(get)]
    content: Option<String>,
}

#[pymethods]
impl PyXfaPacket {
    fn __repr__(&self) -> String {
        format!(
            "XfaPacket(index={}, name={:?}, content_length={})",
            self.index, self.name, self.content_length
        )
    }
}

#[pymethods]
impl PyParseResult {
    #[getter]
    fn num_pages(&self) -> usize {
        self.pages.len()
    }

    fn get_page(&self, page_num: u32) -> Option<PyParsedPage> {
        self.pages.iter().find(|p| p.page_num == page_num).cloned()
    }

    fn __repr__(&self) -> String {
        format!(
            "ParseResult(pages={}, text_len={}, images={})",
            self.pages.len(),
            self.text.len(),
            self.images.len()
        )
    }
}

impl PyParseResult {
    fn from_rust(
        result: liteparse::parser::ParseResult,
        extract_text_metadata: bool,
        word_boxes: bool,
    ) -> Self {
        Self {
            total_pages: result.total_pages,
            pages: result
                .pages
                .into_iter()
                .map(|page| PyParsedPage::from_rust(page, extract_text_metadata, word_boxes))
                .collect(),
            text: result.text,
            images: result
                .images
                .into_iter()
                .map(PyExtractedImage::from_rust)
                .collect(),
            screenshots: result
                .screenshots
                .into_iter()
                .map(PyScreenshotResult::from_rust)
                .collect(),
            image_error_count: result.image_error_count,
            page_errors: result
                .page_errors
                .into_iter()
                .map(|error| PyPageError {
                    page_num: error.page_number,
                    message: error.message,
                })
                .collect(),
            form_type: result.form_type,
            creator: result.creator,
            producer: result.producer,
            doc_meta: result.doc_meta.map(Into::into),
            xfa_packets: result.xfa_packets.map(|packets| {
                packets
                    .into_iter()
                    .map(|packet| PyXfaPacket {
                        index: packet.index,
                        name: packet.name,
                        content_length: packet.content_length,
                        content: packet.content,
                    })
                    .collect()
            }),
        }
    }
}

#[pyclass(frozen, from_py_object)]
#[derive(Clone)]
struct PyExtractedImage {
    #[pyo3(get)]
    id: String,
    #[pyo3(get)]
    name: String,
    #[pyo3(get)]
    path: Option<String>,
    #[pyo3(get)]
    page: u32,
    #[pyo3(get)]
    bbox: PyImageRect,
    #[pyo3(get)]
    width: u32,
    #[pyo3(get)]
    height: u32,
    #[pyo3(get)]
    rotation: f32,
    #[pyo3(get)]
    format: String,
    #[pyo3(get)]
    duplicate_of: Option<String>,
    bytes_buffer: std::sync::Arc<Vec<u8>>,
}

#[pyclass(frozen, from_py_object)]
#[derive(Clone)]
struct PyImageRect {
    #[pyo3(get)]
    x: f32,
    #[pyo3(get)]
    y: f32,
    #[pyo3(get)]
    width: f32,
    #[pyo3(get)]
    height: f32,
}

#[pymethods]
impl PyExtractedImage {
    #[getter]
    fn bytes<'py>(&self, py: Python<'py>) -> Bound<'py, PyBytes> {
        PyBytes::new(py, self.bytes_buffer.as_slice())
    }

    fn __repr__(&self) -> String {
        format!(
            "ExtractedImage(id='{}', page={}, format='{}', bytes_len={})",
            self.id,
            self.page,
            self.format,
            self.bytes_buffer.len()
        )
    }
}

impl PyExtractedImage {
    fn from_rust(img: liteparse::types::ExtractedImage) -> Self {
        Self {
            id: img.id,
            name: img.name,
            path: img.path,
            page: img.page,
            bbox: PyImageRect {
                x: img.bbox.x,
                y: img.bbox.y,
                width: img.bbox.width,
                height: img.bbox.height,
            },
            width: img.width,
            height: img.height,
            rotation: img.rotation,
            format: img.format,
            duplicate_of: img.duplicate_of,
            bytes_buffer: img.bytes,
        }
    }
}

#[pyclass(frozen, from_py_object)]
#[derive(Clone)]
struct PyScreenshotResult {
    #[pyo3(get)]
    page_num: u32,
    #[pyo3(get)]
    width: u32,
    #[pyo3(get)]
    height: u32,
    image_buffer: Vec<u8>,
    #[pyo3(get)]
    is_solid_fill: bool,
    #[pyo3(get)]
    rects: Vec<PyScreenshotRect>,
}

/// One solid rectangle (or line) detected in a rendered page bitmap, in
/// viewport coords (top-left origin, 72 DPI).
#[pyclass(frozen, from_py_object)]
#[derive(Clone)]
struct PyScreenshotRect {
    #[pyo3(get)]
    x: f64,
    #[pyo3(get)]
    y: f64,
    #[pyo3(get)]
    width: f64,
    #[pyo3(get)]
    height: f64,
    #[pyo3(get)]
    color: String,
    #[pyo3(get)]
    is_line: bool,
}

#[pymethods]
impl PyScreenshotRect {
    fn __repr__(&self) -> String {
        format!(
            "ScreenshotRect(x={}, y={}, width={}, height={}, color={}, is_line={})",
            self.x, self.y, self.width, self.height, self.color, self.is_line
        )
    }
}

impl PyScreenshotResult {
    fn from_rust(result: liteparse::parser::ScreenshotResult) -> Self {
        Self {
            page_num: result.page_num,
            width: result.width,
            height: result.height,
            image_buffer: result.image_bytes,
            is_solid_fill: result.is_solid_fill,
            rects: result
                .rects
                .into_iter()
                .map(|rect| PyScreenshotRect {
                    x: rect.x as f64,
                    y: rect.y as f64,
                    width: rect.width as f64,
                    height: rect.height as f64,
                    color: rect.color,
                    is_line: rect.is_line,
                })
                .collect(),
        }
    }
}

#[pymethods]
impl PyScreenshotResult {
    #[getter]
    fn image_bytes<'py>(&self, py: Python<'py>) -> Bound<'py, PyBytes> {
        PyBytes::new(py, &self.image_buffer)
    }

    fn __repr__(&self) -> String {
        format!(
            "ScreenshotResult(page_num={}, width={}, height={})",
            self.page_num, self.width, self.height
        )
    }
}

#[pyclass(frozen, from_py_object)]
#[derive(Clone)]
struct PyLayoutComplexityStats {
    #[pyo3(get)]
    column_count: usize,
    #[pyo3(get)]
    ruled_table_count: usize,
    #[pyo3(get)]
    ruled_table_coverage: f32,
    #[pyo3(get)]
    text_table_run_count: usize,
    #[pyo3(get)]
    figure_count: usize,
    #[pyo3(get)]
    figure_coverage: f32,
    #[pyo3(get)]
    is_complex: bool,
    #[pyo3(get)]
    reasons: Vec<String>,
}

#[pymethods]
impl PyLayoutComplexityStats {
    fn __repr__(&self) -> String {
        format!(
            "LayoutComplexityStats(column_count={}, ruled_table_count={}, figure_coverage={:.2}, is_complex={})",
            self.column_count, self.ruled_table_count, self.figure_coverage, self.is_complex
        )
    }
}

impl PyLayoutComplexityStats {
    fn from_rust(stats: &liteparse::ocr_merge::LayoutComplexityStats) -> Self {
        Self {
            column_count: stats.column_count,
            ruled_table_count: stats.ruled_table_count,
            ruled_table_coverage: stats.ruled_table_coverage,
            text_table_run_count: stats.text_table_run_count,
            figure_count: stats.figure_count,
            figure_coverage: stats.figure_coverage,
            is_complex: stats.is_complex,
            reasons: stats
                .reasons
                .iter()
                .map(|r| r.as_str().to_string())
                .collect(),
        }
    }
}

#[pyclass(frozen, from_py_object)]
#[derive(Clone)]
struct PyPageComplexityStats {
    #[pyo3(get)]
    page_number: usize,
    #[pyo3(get)]
    text_length: usize,
    #[pyo3(get)]
    text_coverage: f32,
    #[pyo3(get)]
    has_substantial_images: bool,
    /// Number of counted raster images — inline figures only; full-page
    /// backgrounds are excluded (see `full_page_image`).
    #[pyo3(get)]
    image_block_count: usize,
    /// Summed image-bbox area over page area, clamped to 1. Counts inline
    /// figures only: a full-page scan raster contributes 0 here — check
    /// `full_page_image` for that.
    #[pyo3(get)]
    image_coverage: f32,
    /// Largest single counted image's area over page area, clamped to 1. Same
    /// exclusion as `image_coverage`: a full-page raster contributes 0.
    #[pyo3(get)]
    largest_image_coverage: f32,
    /// A single raster covering ≥90% of the page is present. Such full-page
    /// backgrounds are excluded from `image_coverage`/`largest_image_coverage`
    /// (they're not inline figures), so this flag is the only signal that
    /// distinguishes a scan from a genuinely blank page — both otherwise
    /// report no text and no counted images.
    #[pyo3(get)]
    full_page_image: bool,
    #[pyo3(get)]
    uncovered_vector_area: Option<f32>,
    #[pyo3(get)]
    is_garbled: bool,
    #[pyo3(get)]
    page_area: f32,
    #[pyo3(get)]
    needs_ocr: bool,
    #[pyo3(get)]
    reasons: Vec<String>,
    #[pyo3(get)]
    layout: Option<PyLayoutComplexityStats>,
}

#[pymethods]
impl PyPageComplexityStats {
    fn __repr__(&self) -> String {
        format!(
            "PageComplexityStats(page_number={}, text_length={}, text_coverage={:.2}, needs_ocr={})",
            self.page_number, self.text_length, self.text_coverage, self.needs_ocr
        )
    }
}

impl PyPageComplexityStats {
    fn from_rust(stats: &liteparse::ocr_merge::PageComplexityStats) -> Self {
        Self {
            page_number: stats.page_number,
            text_length: stats.text_length,
            text_coverage: stats.text_coverage,
            has_substantial_images: stats.has_substantial_images,
            image_block_count: stats.image_block_count,
            image_coverage: stats.image_coverage,
            largest_image_coverage: stats.largest_image_coverage,
            full_page_image: stats.full_page_image,
            uncovered_vector_area: stats.uncovered_vector_area,
            is_garbled: stats.is_garbled,
            page_area: stats.page_area,
            needs_ocr: stats.needs_ocr,
            reasons: stats
                .reasons
                .iter()
                .map(|r| r.as_str().to_string())
                .collect(),
            layout: stats
                .layout
                .as_ref()
                .map(PyLayoutComplexityStats::from_rust),
        }
    }
}

// ---------------------------------------------------------------------------
// Config
// ---------------------------------------------------------------------------

#[pyclass(frozen, from_py_object)]
#[derive(Clone)]
struct PyLiteParseConfig {
    #[pyo3(get)]
    ocr_language: String,
    #[pyo3(get)]
    ocr_enabled: bool,
    #[pyo3(get)]
    ocr_server_url: Option<String>,
    #[pyo3(get)]
    ocr_server_headers: Option<HashMap<String, String>>,
    #[pyo3(get)]
    tessdata_path: Option<String>,
    #[pyo3(get)]
    max_pages: usize,
    #[pyo3(get)]
    target_pages: Option<String>,
    #[pyo3(get)]
    extract_screenshots: bool,
    #[pyo3(get)]
    continue_on_page_error: bool,
    #[pyo3(get)]
    dpi: f32,
    #[pyo3(get)]
    output_format: String,
    #[pyo3(get)]
    preserve_very_small_text: bool,
    #[pyo3(get)]
    password: Option<String>,
    #[pyo3(get)]
    quiet: bool,
    #[pyo3(get)]
    num_workers: usize,
    #[pyo3(get)]
    image_mode: String,
    #[pyo3(get)]
    extract_links: bool,
    #[pyo3(get)]
    keep_headers_footers: bool,
    #[pyo3(get)]
    extract_annotations: bool,
    #[pyo3(get)]
    extract_form_fields: bool,
    #[pyo3(get)]
    extract_structure_tree: bool,
    #[pyo3(get)]
    extract_blocks: bool,
    #[pyo3(get)]
    extract_xfa_packets: bool,
    #[pyo3(get)]
    extract_document_metadata: bool,
    #[pyo3(get)]
    extract_content_bounds: bool,
    #[pyo3(get)]
    detect_screenshot_rects: bool,
    #[pyo3(get)]
    render_form_fields: bool,
    #[pyo3(get)]
    ocr_failure_fatal: bool,
    #[pyo3(get)]
    ocr_hedge_delays_ms: Vec<u64>,
    #[pyo3(get)]
    emit_word_boxes: bool,
    #[pyo3(get)]
    crop_box: Option<(f32, f32, f32, f32)>,
    #[pyo3(get)]
    skip_diagonal_text: bool,
    #[pyo3(get)]
    page_orientation_corrections: Vec<(u32, u16)>,
    #[pyo3(get)]
    include_complexity: bool,
    #[pyo3(get)]
    extract_text_metadata: bool,
    #[pyo3(get)]
    image_output_dir: Option<String>,
    #[pyo3(get)]
    extract_images: bool,
    #[pyo3(get)]
    extract_vector_graphics: bool,
}

#[pymethods]
impl PyLiteParseConfig {
    fn __repr__(&self) -> String {
        format!(
            "LiteParseConfig(ocr_enabled={}, dpi={}, max_pages={})",
            self.ocr_enabled, self.dpi, self.max_pages
        )
    }
}

impl PyLiteParseConfig {
    fn from_rust(cfg: &LiteParseConfig) -> Self {
        Self {
            ocr_language: cfg.ocr_language.clone(),
            ocr_enabled: cfg.ocr_enabled,
            ocr_server_url: cfg.ocr_server_url.clone(),
            ocr_server_headers: if cfg.ocr_server_headers.is_empty() {
                None
            } else {
                Some(cfg.ocr_server_headers.iter().cloned().collect())
            },
            tessdata_path: cfg.tessdata_path.clone(),
            max_pages: cfg.max_pages,
            target_pages: cfg.target_pages.clone(),
            extract_screenshots: cfg.extract_screenshots,
            continue_on_page_error: cfg.continue_on_page_error,
            dpi: cfg.dpi,
            output_format: match cfg.output_format {
                OutputFormat::Json => "json".to_string(),
                OutputFormat::Text => "text".to_string(),
                OutputFormat::Markdown => "markdown".to_string(),
            },
            preserve_very_small_text: cfg.preserve_very_small_text,
            password: cfg.password.clone(),
            quiet: cfg.quiet,
            num_workers: cfg.num_workers,
            image_mode: match cfg.image_mode {
                ImageMode::Off => "off".to_string(),
                ImageMode::Placeholder => "placeholder".to_string(),
                ImageMode::Embed => "embed".to_string(),
            },
            extract_links: cfg.extract_links,
            keep_headers_footers: cfg.keep_headers_footers,
            extract_annotations: cfg.extract_annotations,
            extract_form_fields: cfg.extract_form_fields,
            extract_structure_tree: cfg.extract_structure_tree,
            extract_blocks: cfg.extract_blocks,
            extract_xfa_packets: cfg.extract_xfa_packets,
            extract_document_metadata: cfg.extract_document_metadata,
            extract_content_bounds: cfg.extract_content_bounds,
            detect_screenshot_rects: cfg.detect_screenshot_rects,
            render_form_fields: cfg.render_form_fields,
            ocr_failure_fatal: cfg.ocr_failure_fatal,
            ocr_hedge_delays_ms: cfg.ocr_hedge_delays_ms.clone(),
            emit_word_boxes: cfg.emit_word_boxes,
            crop_box: cfg
                .crop_box
                .as_ref()
                .map(|c| (c.top, c.right, c.bottom, c.left)),
            skip_diagonal_text: cfg.skip_diagonal_text,
            page_orientation_corrections: cfg
                .page_orientation_corrections
                .iter()
                .map(|c| (c.page, c.angle))
                .collect(),
            include_complexity: cfg.include_complexity,
            extract_text_metadata: cfg.extract_text_metadata,
            image_output_dir: cfg.image_output_dir.clone(),
            extract_images: cfg.extract_images,
            extract_vector_graphics: cfg.extract_vector_graphics,
        }
    }
}

// ---------------------------------------------------------------------------
// Batch parsing
// ---------------------------------------------------------------------------

/// One batch of pages from a `_ParseSession`. Internal plumbing for the
/// wrapper's `parse_batches()`, which converts it into the public
/// `liteparse.types.ParseBatch` dataclass — the underscore name keeps the
/// two from colliding.
#[pyclass(frozen, name = "_ParseBatch", skip_from_py_object)]
#[derive(Clone)]
struct PyParseBatch {
    /// First source page in this batch (1-indexed).
    #[pyo3(get)]
    start_page: u32,
    /// Last source page in this batch (1-indexed, inclusive).
    #[pyo3(get)]
    end_page: u32,
    /// The pages in `start_page..=end_page`, as an ordinary parse result.
    #[pyo3(get)]
    result: PyParseResult,
}

/// A document opened once and parsed in bounded page batches. Internal
/// plumbing for the wrapper's `parse_batches()` — prefer that.
///
/// Iterate it directly to consume every batch:
///
///     for batch in parser.open_batch_session("large.pdf", batch_size=20):
///         handle(batch.result.pages)
#[pyclass(name = "_ParseSession", unsendable)]
struct PyParseSession {
    inner: liteparse::ParseSession,
    runtime: std::sync::Arc<tokio::runtime::Runtime>,
    extract_text_metadata: bool,
    word_boxes: bool,
}

#[pymethods]
impl PyParseSession {
    /// Total pages in the source document, before `max_pages` or batching.
    #[getter]
    fn total_pages(&self) -> u32 {
        self.inner.total_pages()
    }

    /// Parse and return the next batch, or `None` once every page within
    /// `max_pages` has been yielded.
    fn next_batch(&mut self, py: Python<'_>) -> PyResult<Option<PyParseBatch>> {
        // Releasing the GIL keeps other Python threads running while PDFium
        // extraction and grid projection execute, matching `parse()`.
        let batch = py
            .detach(|| self.runtime.block_on(self.inner.next_batch()))
            .map_err(|e| PyErr::new::<pyo3::exceptions::PyRuntimeError, _>(e.to_string()))?;

        Ok(batch.map(|batch| PyParseBatch {
            start_page: batch.start_page,
            end_page: batch.end_page,
            result: PyParseResult::from_rust(
                batch.result,
                self.extract_text_metadata,
                self.word_boxes,
            ),
        }))
    }

    fn __iter__(slf: PyRef<'_, Self>) -> PyRef<'_, Self> {
        slf
    }

    /// Returning `None` raises `StopIteration`, ending the loop.
    fn __next__(&mut self, py: Python<'_>) -> PyResult<Option<PyParseBatch>> {
        self.next_batch(py)
    }
}

// ---------------------------------------------------------------------------
// Main LiteParse class
// ---------------------------------------------------------------------------

#[pyclass]
struct LiteParse {
    inner: liteparse::parser::LiteParse,
    config: LiteParseConfig,
    runtime: std::sync::Arc<tokio::runtime::Runtime>,
}

#[pymethods]
impl LiteParse {
    #[new]
    #[pyo3(signature = (
        *,
        ocr_language = None,
        ocr_enabled = None,
        ocr_server_url = None,
        ocr_server_headers = None,
        tessdata_path = None,
        max_pages = None,
        target_pages = None,
        extract_screenshots = None,
        continue_on_page_error = None,
        dpi = None,
        output_format = None,
        preserve_very_small_text = None,
        password = None,
        quiet = None,
        num_workers = None,
        image_mode = None,
        extract_images = None,
        image_output_dir = None,
        extract_links = None,
        keep_headers_footers = None,
        extract_annotations = None,
        extract_form_fields = None,
        extract_structure_tree = None,
        extract_blocks = None,
        extract_xfa_packets = None,
        extract_document_metadata = None,
        extract_content_bounds = None,
        detect_screenshot_rects = None,
        render_form_fields = None,
        ocr_failure_fatal = None,
        ocr_hedge_delays_ms = None,
        emit_word_boxes = None,
        extract_text_metadata = None,
        crop_box = None,
        skip_diagonal_text = None,
        page_orientation_corrections = None,
        include_complexity = None,
        extract_vector_graphics = None,
    ))]
    fn new(
        ocr_language: Option<String>,
        ocr_enabled: Option<bool>,
        ocr_server_url: Option<String>,
        ocr_server_headers: Option<HashMap<String, String>>,
        tessdata_path: Option<String>,
        max_pages: Option<usize>,
        target_pages: Option<String>,
        extract_screenshots: Option<bool>,
        continue_on_page_error: Option<bool>,
        dpi: Option<f32>,
        output_format: Option<String>,
        preserve_very_small_text: Option<bool>,
        password: Option<String>,
        quiet: Option<bool>,
        num_workers: Option<usize>,
        image_mode: Option<String>,
        extract_images: Option<bool>,
        image_output_dir: Option<String>,
        extract_links: Option<bool>,
        keep_headers_footers: Option<bool>,
        extract_annotations: Option<bool>,
        extract_form_fields: Option<bool>,
        extract_structure_tree: Option<bool>,
        extract_blocks: Option<bool>,
        extract_xfa_packets: Option<bool>,
        extract_document_metadata: Option<bool>,
        extract_content_bounds: Option<bool>,
        detect_screenshot_rects: Option<bool>,
        render_form_fields: Option<bool>,
        ocr_failure_fatal: Option<bool>,
        ocr_hedge_delays_ms: Option<Vec<u64>>,
        emit_word_boxes: Option<bool>,
        extract_text_metadata: Option<bool>,
        crop_box: Option<(f32, f32, f32, f32)>,
        skip_diagonal_text: Option<bool>,
        page_orientation_corrections: Option<Vec<(u32, u16)>>,
        include_complexity: Option<bool>,
        extract_vector_graphics: Option<bool>,
    ) -> PyResult<Self> {
        let mut cfg = LiteParseConfig::default();
        if let Some(v) = ocr_language {
            cfg.ocr_language = v;
        }
        if let Some(v) = ocr_enabled {
            cfg.ocr_enabled = v;
        }
        if let Some(v) = ocr_server_url {
            cfg.ocr_server_url = Some(v);
        }
        if let Some(v) = ocr_server_headers {
            cfg.ocr_server_headers = v.into_iter().collect();
        }
        if let Some(v) = tessdata_path {
            cfg.tessdata_path = Some(v);
        }
        if let Some(v) = max_pages {
            cfg.max_pages = v;
        }
        if let Some(v) = target_pages {
            cfg.target_pages = Some(v);
        }
        if let Some(v) = extract_screenshots {
            cfg.extract_screenshots = v;
        }
        if let Some(v) = continue_on_page_error {
            cfg.continue_on_page_error = v;
        }
        if let Some(v) = dpi {
            cfg.dpi = v;
        }
        if let Some(v) = output_format {
            cfg.output_format = parse_output_format(&v)?;
        }
        if let Some(v) = preserve_very_small_text {
            cfg.preserve_very_small_text = v;
        }
        if let Some(v) = password {
            cfg.password = Some(v);
        }
        if let Some(v) = quiet {
            cfg.quiet = v;
        }
        if let Some(v) = num_workers {
            cfg.num_workers = v;
        }
        if let Some(v) = image_mode {
            cfg.image_mode = match v.as_str() {
                "off" | "none" => ImageMode::Off,
                "embed" => ImageMode::Embed,
                _ => ImageMode::Placeholder,
            };
        }
        if let Some(v) = extract_images {
            cfg.extract_images = v;
        }
        if let Some(v) = image_output_dir {
            cfg.image_output_dir = Some(v);
        }
        if let Some(v) = extract_links {
            cfg.extract_links = v;
        }
        if let Some(v) = keep_headers_footers {
            cfg.keep_headers_footers = v;
        }
        if let Some(v) = extract_annotations {
            cfg.extract_annotations = v;
        }
        if let Some(v) = extract_form_fields {
            cfg.extract_form_fields = v;
        }
        if let Some(v) = extract_structure_tree {
            cfg.extract_structure_tree = v;
        }
        if let Some(v) = extract_blocks {
            cfg.extract_blocks = v;
        }
        if let Some(v) = extract_xfa_packets {
            cfg.extract_xfa_packets = v;
        }
        if let Some(v) = extract_document_metadata {
            cfg.extract_document_metadata = v;
        }
        if let Some(v) = extract_content_bounds {
            cfg.extract_content_bounds = v;
        }
        if let Some(v) = detect_screenshot_rects {
            cfg.detect_screenshot_rects = v;
        }
        if let Some(v) = render_form_fields {
            cfg.render_form_fields = v;
        }
        if let Some(v) = ocr_failure_fatal {
            cfg.ocr_failure_fatal = v;
        }
        if let Some(v) = ocr_hedge_delays_ms {
            cfg.ocr_hedge_delays_ms = v;
        }
        if let Some(v) = emit_word_boxes {
            cfg.emit_word_boxes = v;
        }
        if let Some(v) = extract_text_metadata {
            cfg.extract_text_metadata = v;
        }
        if let Some((top, right, bottom, left)) = crop_box {
            cfg.crop_box = Some(CropBox {
                top,
                right,
                bottom,
                left,
            });
        }
        if let Some(v) = skip_diagonal_text {
            cfg.skip_diagonal_text = v;
        }
        if let Some(v) = page_orientation_corrections {
            cfg.page_orientation_corrections = v
                .into_iter()
                .map(|(page, angle)| PageOrientationCorrection { page, angle })
                .collect();
        }
        if let Some(v) = include_complexity {
            cfg.include_complexity = v;
        }
        if let Some(v) = extract_vector_graphics {
            cfg.extract_vector_graphics = v;
        }

        let inner = liteparse::parser::LiteParse::new(cfg.clone());
        let runtime = std::sync::Arc::new(
            tokio::runtime::Runtime::new()
                .map_err(|e| PyErr::new::<pyo3::exceptions::PyRuntimeError, _>(e.to_string()))?,
        );

        Ok(Self {
            inner,
            config: cfg,
            runtime,
        })
    }

    /// Parse a document from a file path.
    fn parse(&self, py: Python<'_>, input: String) -> PyResult<PyParseResult> {
        let pdf_input = PdfInput::Path(input);
        let result = py
            .detach(|| self.runtime.block_on(self.inner.parse_input(pdf_input)))
            .map_err(|e| PyErr::new::<pyo3::exceptions::PyRuntimeError, _>(e.to_string()))?;
        Ok(PyParseResult::from_rust(
            result,
            self.config.extract_text_metadata,
            self.config.output_word_boxes(),
        ))
    }

    /// Open a document from a file path for bounded-memory batch parsing.
    /// Internal plumbing for the wrapper's `parse_batches()` — prefer that.
    ///
    /// Converts a non-PDF source once and returns a `_ParseSession` yielding
    /// `batch_size` pages at a time. Cross-page passes (repeated header/footer
    /// removal, image deduplication) see only the pages in their own batch, so
    /// output can differ from a whole-document `parse()`.
    #[pyo3(signature = (input, batch_size = None))]
    fn open_batch_session(
        &self,
        py: Python<'_>,
        input: String,
        batch_size: Option<usize>,
    ) -> PyResult<PyParseSession> {
        self.open_session(py, PdfInput::Path(input), batch_size)
    }

    /// Open a document from raw bytes for bounded-memory batch parsing.
    /// Internal plumbing for the wrapper's `parse_batches()` — prefer that.
    #[pyo3(signature = (data, batch_size = None))]
    fn open_batch_session_bytes(
        &self,
        py: Python<'_>,
        data: Vec<u8>,
        batch_size: Option<usize>,
    ) -> PyResult<PyParseSession> {
        self.open_session(py, PdfInput::Bytes(data), batch_size)
    }

    /// Parse a document from raw bytes.
    fn parse_bytes(&self, py: Python<'_>, data: Vec<u8>) -> PyResult<PyParseResult> {
        let pdf_input = PdfInput::Bytes(data);
        let result = py
            .detach(|| self.runtime.block_on(self.inner.parse_input(pdf_input)))
            .map_err(|e| PyErr::new::<pyo3::exceptions::PyRuntimeError, _>(e.to_string()))?;
        Ok(PyParseResult::from_rust(
            result,
            self.config.extract_text_metadata,
            self.config.output_word_boxes(),
        ))
    }

    /// Determine per-page complexity for a document at the given path. Returns
    /// a list of PageComplexityStats — a cheap pre-OCR check with per-page
    /// signals and a `needs_ocr` verdict.
    fn is_complex(&self, py: Python<'_>, input: String) -> PyResult<Vec<PyPageComplexityStats>> {
        let pdf_input = PdfInput::Path(input);
        let stats = py
            .detach(|| self.runtime.block_on(self.inner.is_complex(pdf_input)))
            .map_err(|e| PyErr::new::<pyo3::exceptions::PyRuntimeError, _>(e.to_string()))?;
        Ok(stats.iter().map(PyPageComplexityStats::from_rust).collect())
    }

    /// Determine per-page complexity for a document from raw bytes.
    fn is_complex_bytes(
        &self,
        py: Python<'_>,
        data: Vec<u8>,
    ) -> PyResult<Vec<PyPageComplexityStats>> {
        let pdf_input = PdfInput::Bytes(data);
        let stats = py
            .detach(|| self.runtime.block_on(self.inner.is_complex(pdf_input)))
            .map_err(|e| PyErr::new::<pyo3::exceptions::PyRuntimeError, _>(e.to_string()))?;
        Ok(stats.iter().map(PyPageComplexityStats::from_rust).collect())
    }

    /// Take screenshots of document pages. Returns a list of ScreenshotResult.
    ///
    /// Non-PDF files are automatically converted to PDF before rendering when
    /// LibreOffice/ImageMagick are available.
    #[pyo3(signature = (input, page_numbers = None))]
    fn screenshot(
        &self,
        py: Python<'_>,
        input: String,
        page_numbers: Option<Vec<u32>>,
    ) -> PyResult<Vec<PyScreenshotResult>> {
        py.detach(|| {
            let results = self
                .runtime
                .block_on(self.inner.screenshot(&input, page_numbers))
                .map_err(|e| PyErr::new::<pyo3::exceptions::PyRuntimeError, _>(e.to_string()))?;

            Ok(results
                .into_iter()
                .map(|r| PyScreenshotResult {
                    page_num: r.page_num,
                    width: r.width,
                    height: r.height,
                    image_buffer: r.image_bytes,
                    is_solid_fill: r.is_solid_fill,
                    rects: r
                        .rects
                        .into_iter()
                        .map(|rect| PyScreenshotRect {
                            x: rect.x as f64,
                            y: rect.y as f64,
                            width: rect.width as f64,
                            height: rect.height as f64,
                            color: rect.color,
                            is_line: rect.is_line,
                        })
                        .collect(),
                })
                .collect())
        })
    }

    /// Get the resolved configuration.
    #[getter]
    fn config(&self) -> PyLiteParseConfig {
        PyLiteParseConfig::from_rust(&self.config)
    }

    fn __repr__(&self) -> String {
        format!(
            "LiteParse(ocr_enabled={}, dpi={}, max_pages={})",
            self.config.ocr_enabled, self.config.dpi, self.config.max_pages
        )
    }
}

impl LiteParse {
    /// Shared body of `open_batch_session` / `open_batch_session_bytes`. Not
    /// a `#[pymethods]` entry, so it stays off the Python surface.
    fn open_session(
        &self,
        py: Python<'_>,
        input: PdfInput,
        batch_size: Option<usize>,
    ) -> PyResult<PyParseSession> {
        let batch_size = batch_size.unwrap_or(liteparse::DEFAULT_PAGE_BATCH_SIZE);
        let session = py
            .detach(|| {
                self.runtime
                    .block_on(self.inner.open_batch_session(input, batch_size))
            })
            .map_err(|e| PyErr::new::<pyo3::exceptions::PyRuntimeError, _>(e.to_string()))?;

        Ok(PyParseSession {
            inner: session,
            runtime: self.runtime.clone(),
            extract_text_metadata: self.config.extract_text_metadata,
            word_boxes: self.config.output_word_boxes(),
        })
    }
}

// ---------------------------------------------------------------------------
// Module
// ---------------------------------------------------------------------------

/// Duck-typed input for [`search_items`]. Extracts by attribute name, so it
/// accepts both the native `PyTextItem` and the pure-Python `TextItem`
/// dataclass that `LiteParse.parse()` hands back (see `parser.py`,
/// `_convert_native_result`).
#[derive(FromPyObject)]
struct SearchInputItem {
    text: String,
    x: f64,
    y: f64,
    width: f64,
    height: f64,
    #[pyo3(default)]
    font_name: Option<String>,
    #[pyo3(default)]
    font_size: Option<f64>,
    #[pyo3(default)]
    confidence: Option<f64>,
    #[pyo3(default)]
    rotation: f64,
}

impl SearchInputItem {
    fn to_rust(&self) -> liteparse::types::TextItem {
        liteparse::types::TextItem {
            text: self.text.clone(),
            x: self.x as f32,
            y: self.y as f32,
            width: self.width as f32,
            height: self.height as f32,
            rotation: self.rotation as f32,
            font_name: self.font_name.clone(),
            font_size: self.font_size.map(|v| v as f32),
            confidence: self.confidence.map(|v| v as f32),
            ..Default::default()
        }
    }
}

/// Search text items for phrase matches, returning merged items with combined bounding boxes.
#[pyfunction]
#[pyo3(signature = (items, phrase, *, case_sensitive = false))]
fn search_items(
    items: Vec<SearchInputItem>,
    phrase: String,
    case_sensitive: bool,
) -> Vec<PyTextItem> {
    let rust_items: Vec<_> = items.iter().map(|i| i.to_rust()).collect();
    let options = liteparse::search::SearchOptions {
        phrase,
        case_sensitive,
    };
    liteparse::search::search_items(&rust_items, &options)
        .into_iter()
        .map(PyTextItem::from_rust)
        .collect()
}

/// Run the `lit` CLI with the given arguments.
#[pyfunction]
fn run_cli(args: Vec<String>) -> PyResult<()> {
    cli::run_cli(args).map_err(|e| PyErr::new::<pyo3::exceptions::PyRuntimeError, _>(e.to_string()))
}

#[pymodule]
fn _liteparse(m: &Bound<'_, PyModule>) -> PyResult<()> {
    m.add_class::<LiteParse>()?;
    m.add_class::<PyLiteParseConfig>()?;
    m.add_class::<PyParseResult>()?;
    m.add_class::<PyPageError>()?;
    m.add_class::<PyParseBatch>()?;
    m.add_class::<PyParseSession>()?;
    m.add_class::<PyDocumentMetadata>()?;
    m.add_class::<PyExtractedImage>()?;
    m.add_class::<PyImageRect>()?;
    m.add_class::<PyParsedPage>()?;
    m.add_class::<PyTextItem>()?;
    m.add_class::<PyWordBox>()?;
    m.add_class::<PyAnnotationRect>()?;
    m.add_class::<PyDocumentAnnotation>()?;
    m.add_class::<PyStructureAttribute>()?;
    m.add_class::<PyStructureTreeElement>()?;
    m.add_class::<PyStructureTree>()?;
    m.add_class::<PyLayoutCell>()?;
    m.add_class::<PyLayoutBlock>()?;
    m.add_class::<PyFormField>()?;
    m.add_class::<PyScreenshotResult>()?;
    m.add_class::<PyScreenshotRect>()?;
    m.add_class::<PyXfaPacket>()?;
    m.add_class::<PyPageComplexityStats>()?;
    m.add_class::<PyLayoutComplexityStats>()?;
    m.add_class::<PyRect>()?;
    m.add_class::<PyVectorShape>()?;
    m.add_class::<PyVectorLine>()?;
    m.add_class::<PyVectorGraphics>()?;
    m.add_function(wrap_pyfunction!(run_cli, m)?)?;
    m.add_function(wrap_pyfunction!(search_items, m)?)?;
    Ok(())
}

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

    #[test]
    fn words_are_returned_only_when_requested() {
        let item = liteparse::types::TextItem {
            text: "a b".into(),
            words: vec![
                liteparse::types::WordBox {
                    text: "a".into(),
                    ..Default::default()
                },
                liteparse::types::WordBox {
                    text: "b".into(),
                    ..Default::default()
                },
            ],
            ..Default::default()
        };
        assert!(
            PyTextItem::from_rust_for_output(item.clone(), false, false)
                .words
                .is_empty()
        );
        assert_eq!(
            PyTextItem::from_rust_for_output(item, false, true)
                .words
                .len(),
            2
        );
    }

    #[test]
    fn text_metadata_round_trips_through_python_type() {
        let item = liteparse::types::TextItem {
            text: "A".into(),
            font_height: Some(12.0),
            font_ascent: Some(9.0),
            font_descent: Some(-3.0),
            font_weight: Some(700),
            text_width: Some(8.0),
            font_is_buggy: true,
            mcid: Some(2),
            fill_color: Some("ff112233".into()),
            stroke_color: Some("ff445566".into()),
            char_codes: vec![65, 32],
            trailing_space_generated: true,
            ..Default::default()
        };

        let py = PyTextItem::from_rust(item);
        assert_eq!(py.char_codes, vec![65, 32]);
        assert!(py.trailing_space_generated);
        assert_eq!(py.fill_color.as_deref(), Some("ff112233"));

        let round_trip = py.to_rust();
        assert_eq!(round_trip.font_height, Some(12.0));
        assert_eq!(round_trip.font_ascent, Some(9.0));
        assert_eq!(round_trip.font_descent, Some(-3.0));
        assert_eq!(round_trip.font_weight, Some(700));
        assert_eq!(round_trip.text_width, Some(8.0));
        assert!(round_trip.font_is_buggy);
        assert_eq!(round_trip.mcid, Some(2));
        assert_eq!(round_trip.stroke_color.as_deref(), Some("ff445566"));
        assert_eq!(round_trip.char_codes, vec![65, 32]);
        assert!(round_trip.trailing_space_generated);
    }

    #[test]
    fn text_metadata_config_defaults_off_and_can_be_enabled() {
        let py = PyLiteParseConfig::from_rust(&LiteParseConfig::default());
        assert!(!py.extract_text_metadata);

        let config = LiteParseConfig {
            extract_text_metadata: true,
            ..Default::default()
        };
        let py = PyLiteParseConfig::from_rust(&config);
        assert!(py.extract_text_metadata);
    }

    #[test]
    fn output_format_rejects_invalid_values() {
        assert_eq!(parse_output_format("json").unwrap(), OutputFormat::Json);
        assert_eq!(parse_output_format("text").unwrap(), OutputFormat::Text);
        assert_eq!(
            parse_output_format("markdown").unwrap(),
            OutputFormat::Markdown
        );
        assert_eq!(parse_output_format("md").unwrap(), OutputFormat::Markdown);

        let error = parse_output_format("yaml").unwrap_err();
        assert!(error.to_string().contains("invalid output_format: yaml"));
    }

    #[test]
    fn converts_vector_graphics_to_python_shape() {
        let rust = liteparse::types::VectorGraphics {
            shapes: vec![liteparse::types::VectorShape {
                bbox: liteparse::types::Rect {
                    x: 1.0,
                    y: 2.0,
                    width: 3.0,
                    height: 4.0,
                },
                stroke: false,
                stroke_color: None,
                fill: true,
                fill_color: Some("ffffffff".into()),
                has_curve: false,
            }],
            lines: vec![],
        };
        let py = PyVectorGraphics::from_rust(rust);
        assert_eq!(py.shapes[0].bbox.height, 4.0);
        assert_eq!(py.shapes[0].fill_color.as_deref(), Some("ffffffff"));
    }
}