Controlling Pipeline Depth with ProcessMode (DetectOnly, Analyze, Full) in pdf-inspector

Use pdf-inspector's ProcessMode enum to trade speed for depth: DetectOnly skips text extraction entirely, Analyze extracts text and layout metadata without Markdown generation, and Full runs the complete pipeline for production PDF-to-Markdown conversion.

The pdf-inspector library from Firecrawl provides three distinct processing levels through the ProcessMode enum. This design lets callers optimize for latency when they only need structural information, or enable full extraction when downstream systems require clean Markdown output.

Understanding ProcessMode Values

The ProcessMode enum is defined in src/process_mode.rs and controls how deeply the PDF processing pipeline executes:

/// Controls how far the PDF processing pipeline runs.
#[derive(Debug, Clone, Default, PartialEq)]
pub enum ProcessMode {
    /// Only detect PDF type. Very fast — no text extraction.
    DetectOnly,
    /// Detect type + extract text + compute layout complexity. Skips markdown.
    Analyze,
    /// Full pipeline: detect, extract, convert to markdown (default).
    #[default]
    Full,
}

Each variant gates specific pipeline stages in process_pdf_with_options within src/lib.rs.

Runtime Behavior and Performance Characteristics

The library applies ProcessMode at three key decision points in the processing flow:

Mode	Pipeline stages executed	Typical latency	Best for
DetectOnly	PDF type detection only (detect_pdf)	~10 ms	Quick OCR necessity checks, filtering pipelines
Analyze	Detection + text extraction + layout heuristics (tables, columns)	~30–50 ms	Structural metadata extraction, complexity analysis
Full	All stages + Markdown conversion via src/markdown/convert.rs	~100–200 ms	LLM ingestion, documentation workflows

The mode check in src/lib.rs implements early returns and conditional branching:

if options.mode == ProcessMode::DetectOnly {
    // Only run detection; return early
}
// later…
let md = if options.mode == ProcessMode::Analyze {
    // Skip markdown generation
} else {
    // Full conversion
};

API and Usage Examples

Rust API

The PdfOptions::mode field stores your chosen ProcessMode, defaulting to Full if unspecified:

use pdf_inspector::{PdfOptions, ProcessMode, process_pdf_with_options};

let opts = PdfOptions::new()
    .mode(ProcessMode::Analyze); // only detect + layout, no markdown

let result = process_pdf_with_options("sample.pdf", opts).unwrap();

println!("PDF type: {}", result.pdf_type);
println!("Pages with tables: {:?}", result.layout.pages_with_tables);

Python Bindings

The Python interface exposes the same enum values:

import pdf_inspector

# Fast detection only

info = pdf_inspector.detect_pdf("sample.pdf")
print(info.pdf_type)

# Analyze mode – get layout info without markdown

result = pdf_inspector.process_pdf("sample.pdf", mode=pdf_inspector.ProcessMode.Analyze)
print(result.layout.pages_with_tables)

Command-Line Interface

The pdf2md CLI in src/bin/pdf2md.rs maps flags to enum values:

# Only detect PDF type (~10ms)

pdf2md --detect-only sample.pdf

# Analyze mode – prints JSON with layout details (~30-50ms)

pdf2md --analyze --json sample.pdf

# Full conversion, default behavior (~100-200ms)

pdf2md sample.pdf

Where ProcessMode Is Configured

• src/process_mode.rs — Enum definition and documentation
• src/lib.rs — PdfOptions struct holds the mode; process_pdf_with_options gates pipeline stages
• src/bin/pdf2md.rs — CLI flag parsing (--detect-only, --analyze) mapped to enum variants
• src/detector.rs — Fast type detection implementation used by DetectOnly
• src/markdown/convert.rs — Markdown generation skipped in DetectOnly and Analyze modes

Extending ProcessMode

Adding custom pipeline depths requires three changes:

1. Extend the enum in src/process_mode.rs with a new variant
2. Add conditional logic in process_pdf_with_options to gate relevant extraction steps
3. Update CLI flag handling in src/bin/pdf2md.rs for accessibility

Because PdfOptions stores the mode generically, existing callers automatically recognize new variants after recompilation.

Summary

• ProcessMode in pdf-inspector controls pipeline depth through three variants: DetectOnly, Analyze, and Full
• DetectOnly runs only detect_pdf from src/detector.rs for sub-10ms type identification
• Analyze adds text extraction and layout analysis via src/lib.rs without invoking src/markdown/convert.rs
• Full executes the complete pipeline including Markdown conversion, suitable for production LLM workflows
• Configuration flows through PdfOptions::mode with sensible defaults and CLI parity in pdf2md

Frequently Asked Questions

What is the default ProcessMode if I don't specify one?

The ProcessMode enum derives Default with Full as the default variant. When you construct PdfOptions::new() without calling .mode(), the pipeline runs complete detection, extraction, and Markdown conversion automatically.

Can I switch modes at runtime based on PDF characteristics?

Yes. Since ProcessMode is a plain enum passed to process_pdf_with_options, you can implement your own logic—perhaps using DetectOnly first to check if OCR is needed, then conditionally re-running with Full for complex documents.

How does ProcessMode affect memory usage?

DetectOnly allocates minimal memory since it never parses page content. Analyze holds extracted text and layout structures in memory. Full additionally buffers Markdown output, though all modes stream large PDFs rather than loading entirely into RAM.

Is ProcessMode available in the Python bindings?

Yes. The Python module exposes pdf_inspector.ProcessMode.DetectOnly, Analyze, and Full as enum-like constants. Pass them to process_pdf() via the mode keyword argument exactly as shown in the Python example above.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}