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:
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<usize>,
/// Minimum number of text objects or characters expected on a page.
pub min_text_density: Option<usize>,
/// Image coverage threshold used to identify likely scanned pages.
pub image_coverage_threshold: Option<f32>,
}
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.
🤖 Suggested by GitHub Trend-Hacking Pipeline
Description
pdf-inspectorprovides 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:MixeddocumentsIf 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:
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:
Equivalent options could be exposed in Python, Node.js, and WASM bindings.
Documentation should include:
fast,balanced, andconservativeMixedPDFsA possible documentation location could be
docs/classification-tuning.md, linked from the main README.Alternatives Considered
pdf-inspectorto implement custom routing. This duplicates logic and reduces the value of the built-in classifier.🤖 Suggested by GitHub Trend-Hacking Pipeline