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

> Master pdf-inspector's ProcessMode. Choose DetectOnly, Analyze, or Full to control pipeline depth and optimize PDF to Markdown conversion speed and detail.

- Repository: [Firecrawl/pdf-inspector](https://github.com/firecrawl/pdf-inspector)
- Tags: how-to-guide
- Published: 2026-08-10

---

**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`](https://github.com/firecrawl/pdf-inspector/blob/main/src/process_mode.rs) and controls how deeply the PDF processing pipeline executes:

```rust
/// 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`](https://github.com/firecrawl/pdf-inspector/blob/main/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`](https://github.com/firecrawl/pdf-inspector/blob/main/src/markdown/convert.rs) | ~100–200 ms | LLM ingestion, documentation workflows |

The mode check in [`src/lib.rs`](https://github.com/firecrawl/pdf-inspector/blob/main/src/lib.rs) implements early returns and conditional branching:

```rust
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:

```rust
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:

```python
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`](https://github.com/firecrawl/pdf-inspector/blob/main/src/bin/pdf2md.rs) maps flags to enum values:

```bash

# 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`](https://github.com/firecrawl/pdf-inspector/blob/main/src/process_mode.rs)** — Enum definition and documentation
- **[`src/lib.rs`](https://github.com/firecrawl/pdf-inspector/blob/main/src/lib.rs)** — `PdfOptions` struct holds the mode; `process_pdf_with_options` gates pipeline stages
- **[`src/bin/pdf2md.rs`](https://github.com/firecrawl/pdf-inspector/blob/main/src/bin/pdf2md.rs)** — CLI flag parsing (`--detect-only`, `--analyze`) mapped to enum variants
- **[`src/detector.rs`](https://github.com/firecrawl/pdf-inspector/blob/main/src/detector.rs)** — Fast type detection implementation used by `DetectOnly`
- **[`src/markdown/convert.rs`](https://github.com/firecrawl/pdf-inspector/blob/main/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`](https://github.com/firecrawl/pdf-inspector/blob/main/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`](https://github.com/firecrawl/pdf-inspector/blob/main/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`](https://github.com/firecrawl/pdf-inspector/blob/main/src/detector.rs) for sub-10ms type identification
- **`Analyze`** adds text extraction and layout analysis via [`src/lib.rs`](https://github.com/firecrawl/pdf-inspector/blob/main/src/lib.rs) without invoking [`src/markdown/convert.rs`](https://github.com/firecrawl/pdf-inspector/blob/main/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.