firecrawl / firecrawl/pdf-inspector

Document and expose configurable classification thresholds and sampling options for OCR routing

Open
#247 4 comments 0 reactions 0 assignees View on GitHub
Dominant language
Rust
Stars
19.1k
Forks
1.3k
Avg merge
9h 21m
Merged PRs (30d)
51

Description

## Description

`pdf-inspector` provides smart PDF classification, confidence scores, and per-page OCR routing, but the README does not currently explain how users can tune or control these decisions. In production workflows, it is often necessary to adjust thresholds such as:

- minimum confidence required to treat a PDF/page as text-based
- maximum number of pages or content streams sampled
- minimum text density or text object count per page
- image coverage thresholds used to detect scanned pages
- handling of `Mixed` documents

If these knobs already exist, they should be documented clearly. If they are not yet exposed, it would be valuable to provide a public configuration API across Rust, Python, Node.js, and WASM.

## Motivation

Classification decisions directly affect cost and latency because they determine whether a document can be processed locally or should be routed to OCR. Different document corpora may require different tradeoffs:

- **Cost-sensitive pipelines** may want a more aggressive threshold to avoid OCR whenever possible.
- **High-recall pipelines** may prefer conservative text detection to avoid missing scanned content.
- **Large documents** may need control over how many pages are sampled to keep inspection fast.
- **Mixed PDFs** may require page-level routing rather than a single global decision.

Without documented tuning options, users may rely on defaults that are not optimal for their use case, or they may implement fragile post-processing logic around confidence scores.

## Proposed Solution

Add documentation and, if needed, a public configuration surface for classification behavior.

Possible API shape in Rust:

```rust
pub struct ClassificationOptions {
/// Confidence threshold for treating a page/document as text-based.
pub confidence_threshold: f32,

/// Maximum number of pages to sample during classification.
pub max_sample_pages: Option,

/// Minimum number of text objects or characters expected on a page.
pub min_text_density: Option,

/// Image coverage threshold used to identify likely scanned pages.
pub image_coverage_threshold: Option,
}

impl Default for ClassificationOptions {
fn default() -> Self {
Self {
confidence_threshold: 0.8,
max_sample_pages: None,
min_text_density: None,
image_coverage_threshold: None,
}
}
}
```

Equivalent options could be exposed in Python, Node.js, and WASM bindings.

Documentation should include:

- recommended presets, such as `fast`, `balanced`, and `conservative`
- examples showing how to route pages to OCR based on confidence and per-page results
- guidance for handling `Mixed` PDFs
- performance implications of sampling more pages
- examples for each supported binding

A possible documentation location could be `docs/classification-tuning.md`, linked from the main README.

## Alternatives Considered

- Keep the current defaults and ask users to post-process confidence scores manually. This is less reliable because users cannot control sampling behavior or internal heuristics.
- Build external wrappers around `pdf-inspector` to implement custom routing. This duplicates logic and reduces the value of the built-in classifier.
- Document only the meaning of confidence scores without exposing configuration. This helps interpretation but does not solve the need for workload-specific tuning.

Contributor guide

No contributing guide indexed for this repository

Research direction

Start with the README and the proposed docs/classification-tuning.md location, then inspect the existing classification behavior and Rust, Python, Node.js, and WASM binding surfaces. Done means users can understand and configure the relevant thresholds and sampling behavior, with documented presets, OCR-routing examples, Mixed-PDF guidance, and performance notes for each supported binding.

Written by the indexing model from the issue text.

Assessment

Tech stack
node.js, python, rust, wasm
Domain
api, documentation
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Needs clarification
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.