Merge pull request #6 from afriedman412/plugin-options

can now pass params through to plugins

Author: afriedman412

README.md

@@ -183,6 +183,8 @@ All fields are nullable — Petey returns `null` for anything it can't find rath
 | `model` | LLM model ID (e.g. `gpt-4.1-mini`, `claude-sonnet-4-6`). Overridden by `--model` or `PETEY_MODEL` env var. |
 | `parser` | Text extraction backend: `pymupdf` (default), `tables`, `pdfplumber`, `tabula`, `marker`, `llamaparse`, or `docling`. Overridden by `--parser`. |
 | `ocr` | OCR backend: `none` (default), `tesseract`, `mistral`, `chandra`. Overridden by `--ocr`. |
+| `parser_options` | Dict of extra kwargs passed to the parser (e.g. `languages: [en, fr]`) |
+| `ocr_options` | Dict of extra kwargs passed to the OCR backend |
 | `instructions` | Extra guidance appended to the prompt (e.g. "ignore the summary row") |
 | `header_pages` | Number of leading pages to treat as a document header (see below) |
 | `pages` | Page range to process, e.g. `"2-5"` or `"1,3,5-7"` (1-indexed) |

petey/cli.py

@@ -283,6 +283,8 @@ def on_result(path, data):
                 print(line)
 
     instructions = spec.get("instructions", "")
+    parser_options = spec.get("parser_options") or None
+    ocr_options = spec.get("ocr_options") or None
 
     # CLI overrides schema, schema overrides defaults
     ocr_backend = (
@@ -362,6 +364,8 @@ def on_chunk(label, data, _name=pdf_name):
                     on_result=on_chunk,
                     parser=parser,
                     ocr_backend=ocr_backend,
+                    parser_options=parser_options,
+                    ocr_options=ocr_options,
                     header_pages=(
                         args.header_pages
                         if args.header_pages is not None
@@ -393,6 +397,8 @@ def on_chunk(label, data, _name=pdf_name):
                 on_result=on_result,
                 parser=parser,
                 ocr_backend=ocr_backend,
+                parser_options=parser_options,
+                ocr_options=ocr_options,
             )
         )
 

petey/extract.py

@@ -484,26 +484,26 @@ def extract_text(
     parser: str = "pymupdf",
     ocr_fallback: bool = False,
     ocr_backend: str = "none",
+    parser_options: dict | None = None,
+    ocr_options: dict | None = None,
 ) -> str:
     """Extract all text from a PDF as a single string.
 
     Args:
         pdf_path: Path to the PDF file.
-        parser: Text extraction backend.
-            "pymupdf"    — markdown via pymupdf4llm (default)
-            "tables"     — PyMuPDF table detection → TSV
-            "pdfplumber" — layout-preserving spatial extraction
-            "tabula"     — tabula-py table extraction → TSV (requires Java)
+        parser: Text extraction backend — see ``PARSERS`` registry.
         ocr_fallback: Deprecated. Use ``ocr_backend="tesseract"`` instead.
         ocr_backend: OCR fallback when text layer is empty/short.
-            "none"       — no OCR (default)
-            "tesseract"  — local pytesseract (requires tesseract binary)
-            "mistral"    — Mistral OCR API (requires MISTRAL_API_KEY)
+        parser_options: Extra kwargs passed to the parser callable.
+        ocr_options: Extra kwargs passed to the OCR callable.
 
     Returns:
         Extracted text as a single string.
     """
-    pages = extract_text_pages(pdf_path, parser, ocr_fallback, ocr_backend)
+    pages = extract_text_pages(
+        pdf_path, parser, ocr_fallback, ocr_backend,
+        parser_options=parser_options, ocr_options=ocr_options,
+    )
     return "\n\n".join(pages)
 
 
@@ -512,6 +512,8 @@ def extract_text_pages(
     parser: str = "pymupdf",
     ocr_fallback: bool = False,
     ocr_backend: str = "none",
+    parser_options: dict | None = None,
+    ocr_options: dict | None = None,
 ) -> list[str]:
     """Extract text from each page of a PDF separately.
 
@@ -521,11 +523,15 @@ def extract_text_pages(
         ocr_fallback: Deprecated. Use ``ocr_backend="tesseract"`` instead.
         ocr_backend: OCR fallback when text layer is empty/short —
             see ``OCR_BACKENDS`` registry.
+        parser_options: Extra kwargs passed to the parser callable.
+        ocr_options: Extra kwargs passed to the OCR callable.
 
     Returns:
         List of strings, one per page.
     """
     ocr_backend = _resolve_ocr_backend(ocr_fallback, ocr_backend)
+    _p_opts = parser_options or {}
+    _o_opts = ocr_options or {}
 
     fn = PARSERS.get(parser)
     if fn is None:
@@ -550,9 +556,9 @@ def extract_text_pages(
                 f"extract_async() or "
                 f"extract_pages_async() instead."
             )
-        pages = asyncio.run(fn(pdf_path))
+        pages = asyncio.run(fn(pdf_path, **_p_opts))
     else:
-        pages = fn(pdf_path)
+        pages = fn(pdf_path, **_p_opts)
 
     # Apply OCR fallback to pages with insufficient text
     if ocr_backend != "none":
@@ -561,7 +567,10 @@ def extract_text_pages(
             if len(text.strip()) < OCR_THRESHOLD:
                 if doc is None:
                     doc = fitz.open(pdf_path)
-                pages[i] = _ocr_page(doc[i], ocr_backend, pdf_path)
+                pages[i] = _ocr_page(
+                    doc[i], ocr_backend, pdf_path,
+                    **_o_opts,
+                )
 
     return pages
 
@@ -599,13 +608,15 @@ def _ocr_page_tesseract(page) -> str:
 def _ocr_page(
     page, ocr_backend: str = "tesseract",
     pdf_path: str | None = None,
+    **ocr_options,
 ) -> str:
     """OCR a single fitz page.
 
     Args:
         page: A fitz page object.
         ocr_backend: OCR backend — see ``OCR_BACKENDS`` registry.
         pdf_path: Path to the source PDF (used by Mistral OCR).
+        **ocr_options: Extra kwargs passed to the OCR callable.
 
     Returns:
         Extracted text from the page.
@@ -627,8 +638,8 @@ def _ocr_page(
                 f"Use extract_async() or "
                 f"extract_pages_async() instead."
             )
-        return asyncio.run(fn(page))
-    return fn(page)
+        return asyncio.run(fn(page, **ocr_options))
+    return fn(page, **ocr_options)
 
 
 def _ocr_full(doc, pdf_path: str, ocr_backend: str) -> str:
@@ -831,6 +842,8 @@ async def extract_async(
     llm_backend: str | None = None,
     text: str | None = None,
     parse_fn=None,
+    parser_options: dict | None = None,
+    ocr_options: dict | None = None,
 ) -> BaseModel:
     """Extract structured data from a single PDF.
 
@@ -852,6 +865,7 @@ async def extract_async(
     Returns:
         Populated Pydantic model instance.
     """
+    _p_opts = parser_options or {}
     mgr = get_manager()
     if text is None:
         if parse_fn is not None:
@@ -866,13 +880,14 @@ async def extract_async(
                 parser_fn
             ):
                 pages = await mgr.run(
-                    parser_fn, pdf_path,
+                    parser_fn, pdf_path, **_p_opts,
                 )
                 text = "\n\n".join(pages)
             else:
                 text = await mgr.run_cpu(
                     extract_text, pdf_path, parser,
                     ocr_fallback, ocr_backend,
+                    _p_opts, ocr_options,
                 )
     if len(text) > TEXT_WARN_THRESHOLD:
         warnings.warn(
@@ -945,6 +960,8 @@ def extract(
     ocr_fallback: bool = False,
     ocr_backend: str = "none",
     llm_backend: str | None = None,
+    parser_options: dict | None = None,
+    ocr_options: dict | None = None,
 ) -> BaseModel:
     """Sync wrapper around ``extract_async``. See that function for args."""
     return asyncio.run(
@@ -953,6 +970,7 @@ def extract(
             model=model, api_key=api_key, instructions=instructions,
             parser=parser, ocr_fallback=ocr_fallback,
             ocr_backend=ocr_backend, llm_backend=llm_backend,
+            parser_options=parser_options, ocr_options=ocr_options,
         )
     )
 
@@ -1132,6 +1150,8 @@ async def extract_pages_async(
     page_range: str | None = None,
     parse_multiplier: int = 5,
     parse_fn=None,
+    parser_options: dict | None = None,
+    ocr_options: dict | None = None,
 ) -> list[dict]:
     """Split a PDF into page chunks and extract each concurrently.
 
@@ -1162,6 +1182,8 @@ async def extract_pages_async(
         parse_fn: Optional async callable(pdf_path, page_index, parser,
             ocr_backend) -> str. When provided, replaces local
             page-level text extraction (no ProcessPoolExecutor used).
+        parser_options: Extra kwargs passed to the parser callable.
+        ocr_options: Extra kwargs passed to the OCR callable.
 
     Returns:
         List of result dicts (with _page and optionally _error).
@@ -1175,6 +1197,8 @@ async def extract_pages_async(
             stacklevel=2,
         )
 
+    _p_opts = parser_options or {}
+
     # Resolve parser from registry
     parser_fn = PARSERS.get(parser)
     if parser_fn is None:
@@ -1210,11 +1234,11 @@ async def extract_pages_async(
         try:
             if parser_is_async:
                 h_pages = await mgr.run(
-                    parser_fn, h_path,
+                    parser_fn, h_path, **_p_opts,
                 )
             else:
                 h_pages = await mgr.run_cpu(
-                    parser_fn, h_path,
+                    parser_fn, h_path, **_p_opts,
                 )
             header_text = "\n\n".join(h_pages)
         finally:
@@ -1270,11 +1294,11 @@ async def _parse_chunk(idx_slice):
         try:
             if parser_is_async:
                 pages = await mgr.run(
-                    parser_fn, chunk_path,
+                    parser_fn, chunk_path, **_p_opts,
                 )
             else:
                 pages = await mgr.run_cpu(
-                    parser_fn, chunk_path,
+                    parser_fn, chunk_path, **_p_opts,
                 )
             return "\n\n".join(pages)
         finally:
@@ -1441,6 +1465,8 @@ async def extract_batch(
     ocr_backend: str = "none",
     llm_backend: str | None = None,
     parse_fn=None,
+    parser_options: dict | None = None,
+    ocr_options: dict | None = None,
 ) -> list[dict]:
     """Extract from multiple PDFs concurrently.
 
@@ -1460,11 +1486,14 @@ async def extract_batch(
         parse_fn: Optional async callable(pdf_path, parser,
             ocr_backend) -> str. When provided, replaces local
             text extraction.
+        parser_options: Extra kwargs passed to the parser callable.
+        ocr_options: Extra kwargs passed to the OCR callable.
 
     Returns:
         List of result dicts (with _source_file and optionally
         _error).
     """
+    _p_opts = parser_options or {}
     mgr = get_manager()
     mgr.configure(api_limit=concurrency)
     client = _make_client(model, api_key, llm_backend)
@@ -1484,13 +1513,14 @@ async def _process(path: str):
                 )
             elif parser_is_async:
                 pages = await mgr.run(
-                    parser_fn, path,
+                    parser_fn, path, **_p_opts,
                 )
                 text = "\n\n".join(pages)
             else:
                 text = await mgr.run_cpu(
                     extract_text, path, parser,
                     ocr_fallback, ocr_backend,
+                    _p_opts, ocr_options,
                 )
             async with mgr.api():
                 result = (

tests/test_extract.py

@@ -1948,3 +1948,45 @@ def test_bad_attr_raises_at_build(self):
         from petey.extract import _make_plugin_loader
         with pytest.raises(AttributeError):
             _make_plugin_loader("json:nonexistent_function_xyz")
+
+
+# ---------------------------------------------------------------------------
+# parser_options / ocr_options passthrough
+# ---------------------------------------------------------------------------
+
+class TestBackendOptions:
+    """Verify parser_options and ocr_options reach the callable."""
+
+    def test_parser_options_passed(self):
+        mock_fn = MagicMock(return_value=["page text"])
+        with patch.dict(
+            "petey.extract.PARSERS", {"mock": mock_fn},
+        ):
+            extract_text_pages(
+                str(MCI_PDF), parser="mock",
+                parser_options={"lang": "fr", "dpi": 300},
+            )
+        mock_fn.assert_called_once()
+        _, kwargs = mock_fn.call_args
+        assert kwargs["lang"] == "fr"
+        assert kwargs["dpi"] == 300
+
+    def test_ocr_options_passed(self):
+        from petey.extract import OCR_THRESHOLD
+        mock_parser = MagicMock(return_value=["x"])
+        mock_ocr = MagicMock(return_value="ocr text")
+        with patch.dict(
+            "petey.extract.PARSERS", {"mock": mock_parser},
+        ):
+            with patch.dict(
+                "petey.extract.OCR_BACKENDS",
+                {"mock_ocr": mock_ocr},
+            ):
+                extract_text_pages(
+                    str(MCI_PDF), parser="mock",
+                    ocr_backend="mock_ocr",
+                    ocr_options={"languages": ["en", "fr"]},
+                )
+        mock_ocr.assert_called_once()
+        _, kwargs = mock_ocr.call_args
+        assert kwargs["languages"] == ["en", "fr"]