feat: add perf tools (#165)

Signed-off-by: Peter Staar <[email protected]>

Author: PeterStaar-IBM

.gitignore

@@ -4,6 +4,7 @@ build
 dist
 extlib_*/
 scratch_*
+perf/results/**
 
 # Created by https://www.toptal.com/developers/gitignore/api/python,macos,emacs,cmake,virtualenv
 # Edit at https://www.toptal.com/developers/gitignore?templates=python,macos,emacs,cmake,virtualenv

README.md

@@ -191,7 +191,8 @@ uv sync
 The latter will only work after a clean `git clone`. If you are developing and updating C++ code, please use,
 
 ```sh
-uv pip install --force-reinstall --no-deps -e .
+# uv pip install --force-reinstall --no-deps -e .
+rm -rf .venv; uv venv; uv pip install --force-reinstall --no-deps -e ".[perf-tools]"
 ```
 
 To test the package, run:

docling_parse/pdf_parser.py

@@ -446,8 +446,8 @@ def _to_segmented_page(
                 "`words` will be created for segmented_page in an inefficient way!"
             )
             self._create_word_cells(segmented_page, enforce_same_font=enforce_same_font)
-        else:
-            logging.warning("No `words` will be created for segmented_page")
+        # else:
+        #    logging.warning("No `words` will be created for segmented_page")
 
         if create_textlines and ("line_cells" in page):
             segmented_page.textline_cells = self._to_cells(page["line_cells"])
@@ -459,8 +459,8 @@ def _to_segmented_page(
             self._create_textline_cells(
                 segmented_page, enforce_same_font=enforce_same_font
             )
-        else:
-            logging.warning("No `text_lines` will be created for segmented_page")
+        # else:
+        #    logging.warning("No `text_lines` will be created for segmented_page")
 
         return segmented_page
 

perf/README.md

@@ -0,0 +1,22 @@
+Perf tools for page-level parsing benchmarking.
+
+Usage
+- Install extras for optional parsers (not part of main package):
+  - pip: `pip install .[perf-tools]`
+  - uv (already configured): `uv sync --group perf-test`
+- Run on a file or directory:
+  - `python perf/run_perf.py ./docs/sample.pdf`
+  - `python perf/run_perf.py ./dataset --recursive -p pdfplumber`
+
+CLI
+- `input`: PDF file or directory of PDFs.
+- `--parser|-p`: one of `docling` (default), `pdfplumber`, `pypdfium2` (alias: `pypdfium`), `pymupdf`.
+- `--recursive|-r`: recurse when input is a directory.
+- `--output|-o`: output CSV path (default under `perf/results`).
+
+CSV columns
+- `filename,page_number,elapsed_sec,success,error`
+
+Statistics
+- Prints totals, avg sec/page, min/max, and percentiles (p50/p90/p95/p99) after the run.
+