pdfluent-extract 0.1.0__py3-none-any.whl

pdfluent_extract/__init__.py

@@ -0,0 +1,222 @@
+# Copyright (c) 2026 Innovation Trigger B.V.
+#
+# PDFluent is available under two licences, at your option: the GNU AGPLv3, or
+# the PDFluent Commercial Licence. See the LICENSE file in this repository --
+# that file travels with the copy you received, which a URL does not.
+"""PDF and Office files to Markdown, JSON and RAG chunks, in three calls.
+
+This package is pure Python: the engine underneath is `pdfluent`, which pip
+pulls in automatically (1.1.0 or later, on every platform the matrix covers).
+There is nothing to compile and no system dependency to install.
+
+>>> from pdfluent_extract import to_markdown
+>>> print(to_markdown("report.pdf"))
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from typing import Any, BinaryIO, Dict, List, Optional, Sequence, Tuple, Union
+
+import pdfluent
+from pdfluent.chunks import Chunk, iter_chunks
+
+__all__ = ["Chunk", "to_chunks", "to_json", "to_markdown"]
+
+#: The only quality level v1 accepts. Anything else is refused by name —
+#: there is no hidden fallback to a slower or a weaker pipeline.
+QUALITIES = ("fast",)
+
+#: Tokens to characters for the chunk budget: ~4 characters per token for
+#: English prose. A heuristic, stated here rather than smuggled into a default.
+CHARS_PER_TOKEN = 4
+
+Source = Union[str, bytes, "os.PathLike[str]", BinaryIO]
+
+
+def _check_quality(quality: str) -> None:
+    if quality not in QUALITIES:
+        allowed = ", ".join(repr(q) for q in QUALITIES)
+        raise ValueError(f"quality must be one of {allowed}, not {quality!r}")
+
+
+def _read_source(source: Source) -> Tuple[bytes, Optional[str], Optional[str]]:
+    """The source as ``(data, path, name)``.
+
+    ``path`` is set for path inputs (so chunks can cite it); ``name`` is the
+    file stem for paths, ``None`` otherwise. File-like objects are read fully;
+    the stream position is left wherever the read ends.
+    """
+    if isinstance(source, os.PathLike):
+        source = os.fspath(source)
+    if isinstance(source, str):
+        with open(source, "rb") as fh:
+            data = fh.read()
+        stem = os.path.splitext(os.path.basename(source))[0]
+        return data, source, stem or "document"
+    if isinstance(source, (bytes, bytearray)):
+        return bytes(source), None, None
+    read = getattr(source, "read", None)
+    if callable(read):
+        data = read()
+        if isinstance(data, bytearray):
+            data = bytes(data)
+        if not isinstance(data, bytes):
+            raise TypeError(
+                "file-like sources must read bytes, "
+                f"not {type(data).__name__}"
+            )
+        return data, None, None
+    raise TypeError(
+        "source must be a path, bytes or a file-like object, "
+        f"not {type(source).__name__}"
+    )
+
+
+def _kind(data: bytes) -> str:
+    """``"pdf"``, ``"office"`` or ``"unknown"``, by magic bytes.
+
+    The extension is never consulted: a workbook saved as `.pdf` extracts as
+    a workbook, and a PDF saved as `.bin` extracts as a PDF. The PDF header
+    is searched in the first 1024 bytes rather than prefix-matched — the PDF
+    spec tolerates leading garbage there. The ZIP match stays a prefix match:
+    Office files open with the local file header, and a PDF must win over a
+    ZIP that merely contains the header bytes further in.
+    """
+    if b"%PDF-" in data[:1024]:
+        return "pdf"
+    if data.startswith(b"PK"):
+        return "office"
+    return "unknown"
+
+
+def _require_office() -> Any:
+    extract_office = getattr(pdfluent, "extract_office", None)
+    if extract_office is None:
+        raise NotImplementedError(
+            "Office files need pdfluent>=1.1.0, which exposes "
+            "pdfluent.extract_office; the installed pdfluent "
+            f"{getattr(pdfluent, '__version__', 'unknown')} does not have it"
+        )
+    return extract_office
+
+
+def _check_pages_for(pages: Optional[Sequence[int]], kind: str) -> None:
+    if pages is not None and kind != "pdf":
+        raise ValueError("pages selects PDF pages; Office files have no pages to select")
+
+
+def to_markdown(
+    source: Source,
+    *,
+    quality: str = "fast",
+    pages: Optional[Sequence[int]] = None,
+) -> str:
+    """The file as Markdown, in reading order.
+
+    ``source`` is a path, ``bytes`` or a file-like object; PDF and Office
+    (``.docx``/``.pptx``/``.xlsx``) are routed by magic bytes. ``pages`` is a
+    list of 0-based PDF page indices (``None`` for the whole file).
+    """
+    _check_quality(quality)
+    data, _, _ = _read_source(source)
+    kind = _kind(data)
+    _check_pages_for(pages, kind)
+    if kind == "pdf":
+        with pdfluent.Document(data) as doc:
+            return doc.extract_markdown(
+                pages=list(pages) if pages is not None else None
+            )
+    if kind == "office":
+        return _require_office()(data, format="markdown")
+    raise pdfluent.PdfluentParseError(
+        "not a PDF or Office file: the bytes start with neither %PDF- nor a ZIP header"
+    )
+
+
+def to_json(
+    source: Source,
+    *,
+    quality: str = "fast",
+    pages: Optional[Sequence[int]] = None,
+) -> Dict[str, Any]:
+    """The file as a Docling ``DoclingDocument``, as a dict.
+
+    Same routing as :func:`to_markdown`; the JSON is what
+    ``DoclingDocument.model_validate_json`` reads. ``name`` is the file's stem
+    for path inputs, ``"document"`` otherwise.
+    """
+    _check_quality(quality)
+    data, _, name = _read_source(source)
+    kind = _kind(data)
+    _check_pages_for(pages, kind)
+    if kind == "pdf":
+        with pdfluent.Document(data) as doc:
+            return json.loads(
+                doc.extract_docling(
+                    name=name or "document",
+                    pages=list(pages) if pages is not None else None,
+                )
+            )
+    if kind == "office":
+        return json.loads(
+            _require_office()(data, format="docling", name=name or "document")
+        )
+    raise pdfluent.PdfluentParseError(
+        "not a PDF or Office file: the bytes start with neither %PDF- nor a ZIP header"
+    )
+
+
+def to_chunks(
+    source: Source,
+    *,
+    quality: str = "fast",
+    max_tokens: int = 512,
+    pages: Optional[Sequence[int]] = None,
+) -> List[Chunk]:
+    """The file as RAG chunks, in reading order.
+
+    One chunk per paragraph, heading and list item, and one per table (a cell
+    on its own is a number without its column). Every chunk carries ``page``,
+    ``section_path`` (the enclosing headings) and ``bbox`` in its metadata,
+    plus ``source`` for path inputs.
+
+    ``max_tokens`` budgets each chunk (about four characters to the token);
+    tables longer than the budget split by rows with the header repeated.
+    ``pages`` lists 0-based page indices; chunks come back per page in the
+    listed order. PDF only in v1.
+    """
+    _check_quality(quality)
+    if not isinstance(max_tokens, int) or max_tokens < 1:
+        raise ValueError(f"max_tokens must be a positive int, not {max_tokens!r}")
+    data, path, _ = _read_source(source)
+    kind = _kind(data)
+    if kind != "pdf":
+        if kind == "office":
+            raise NotImplementedError(
+                "to_chunks reads PDF files in v1; Office chunking is not scheduled yet"
+            )
+        raise pdfluent.PdfluentParseError(
+            "not a PDF or Office file: the bytes start with neither %PDF- nor a ZIP header"
+        )
+    max_chars = max_tokens * CHARS_PER_TOKEN
+    chunks: List[Chunk] = []
+    with pdfluent.Document(data) as doc:
+        if pages is None:
+            chunks = list(iter_chunks(doc, hierarchical=True, max_chars=max_chars))
+        else:
+            for page in pages:
+                chunks.extend(
+                    iter_chunks(
+                        doc,
+                        hierarchical=True,
+                        max_chars=max_chars,
+                        first_page=page,
+                        page_count=1,
+                    )
+                )
+    if path is not None:
+        for chunk in chunks:
+            chunk.metadata = {"source": path, **chunk.metadata}
+    return chunks

pdfluent_extract/cli.py

@@ -0,0 +1,167 @@
+# Copyright (c) 2026 Innovation Trigger B.V.
+#
+# PDFluent is available under two licences, at your option: the GNU AGPLv3, or
+# the PDFluent Commercial Licence. See the LICENSE file in this repository --
+# that file travels with the copy you received, which a URL does not.
+"""The `pdfluent-extract` console script: files to Markdown, JSON and chunks.
+
+`pdfluent-extract <input> [-o OUT] [--format md|json|chunks|text]
+[--quality fast|balanced|best] [--pages SPEC]`
+
+`-` as input reads stdin; `-o -` or no `-o` writes stdout. `--pages` counts
+from 1 (`1-3,5`), like the main CLI. Exit 2 on a usage error, 1 on an
+extraction error, with a message on stderr either way.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from dataclasses import asdict, is_dataclass
+from typing import List, Optional, Sequence
+
+from pdfluent_extract import to_chunks, to_json, to_markdown
+
+FORMATS = ("md", "json", "chunks", "text")
+QUALITIES = ("fast", "balanced", "best")
+
+
+def parse_pages(spec: str) -> List[int]:
+    """`1-3,5` into sorted, deduplicated 0-based page indices.
+
+    Users count from 1; the engine counts from 0. A bad spec raises
+    ValueError naming it — the caller reports that as a usage error.
+    """
+    items = spec.split(",")
+    pages: List[int] = []
+    for raw in items:
+        item = raw.strip()
+        if not item:
+            raise ValueError(f"empty item in page spec {spec!r} (want e.g. `1-3,5`)")
+        if "-" in item:
+            lo_text, _, hi_text = item.partition("-")
+            try:
+                lo, hi = int(lo_text), int(hi_text)
+            except ValueError:
+                raise ValueError(f"not a page range: {item!r} (in {spec!r})")
+            if lo < 1 or hi < 1:
+                raise ValueError(f"pages count from 1, so `0` names nothing (in {spec!r})")
+            if lo > hi:
+                raise ValueError(f"reversed range {item!r} (in {spec!r}; want `lo-hi`)")
+            pages.extend(range(lo - 1, hi))
+        else:
+            try:
+                page = int(item)
+            except ValueError:
+                raise ValueError(f"not a page number: {item!r} (in {spec!r})")
+            if page < 1:
+                raise ValueError(f"pages count from 1, so `0` names nothing (in {spec!r})")
+            pages.append(page - 1)
+    return sorted(set(pages))
+
+
+def _read_input(path: str):
+    """The input as the library wants it: a path stays a path (so chunks
+    cite it and JSON names it), `-` reads stdin as bytes."""
+    if path == "-":
+        data = sys.stdin.buffer.read()
+        if not data:
+            raise ValueError("nothing on stdin")
+        return data
+    with open(path, "rb"):
+        pass
+    return path
+
+
+def _render(
+    source,
+    *,
+    format: str,
+    quality: str,
+    pages: Optional[Sequence[int]],
+) -> str:
+    if format == "md":
+        return to_markdown(source, quality=quality, pages=pages)
+    if format == "json":
+        return json.dumps(to_json(source, quality=quality, pages=pages), indent=2)
+    chunks = to_chunks(source, quality=quality, pages=pages)
+    if format == "text":
+        return "\n\n".join(chunk.text for chunk in chunks)
+    return json.dumps(
+        [
+            asdict(chunk) if is_dataclass(chunk) else chunk
+            for chunk in chunks
+        ],
+        indent=2,
+    )
+
+
+def _write_output(text: str, out: Optional[str]) -> None:
+    if not text.endswith("\n"):
+        text += "\n"
+    if out is None or out == "-":
+        sys.stdout.write(text)
+        return
+    with open(out, "w", encoding="utf-8") as fh:
+        fh.write(text)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="pdfluent-extract",
+        description="PDF and Office files to Markdown, JSON and RAG chunks.",
+    )
+    parser.add_argument("input", help="input file, or - for stdin")
+    parser.add_argument(
+        "-o", "--output", default=None,
+        help="write here instead of stdout (- for stdout)",
+    )
+    parser.add_argument(
+        "--format", choices=FORMATS, default="md",
+        help="output shape (default: md)",
+    )
+    parser.add_argument(
+        "--quality", choices=QUALITIES, default="fast",
+        help="extraction quality (default: fast)",
+    )
+    parser.add_argument(
+        "--pages", default=None, metavar="SPEC",
+        help="pages to extract, counting from 1 (e.g. 1-3,5)",
+    )
+    return parser
+
+
+def main(argv: Optional[Sequence[str]] = None) -> int:
+    args = build_parser().parse_args(argv)
+    try:
+        pages = parse_pages(args.pages) if args.pages is not None else None
+    except ValueError as e:
+        print(f"pdfluent-extract: {e}", file=sys.stderr)
+        return 2
+    try:
+        source = _read_input(args.input)
+    except FileNotFoundError:
+        print(f"pdfluent-extract: no such file: {args.input}", file=sys.stderr)
+        return 1
+    except OSError as e:
+        print(f"pdfluent-extract: cannot read {args.input}: {e}", file=sys.stderr)
+        return 1
+    except ValueError as e:
+        print(f"pdfluent-extract: {e}", file=sys.stderr)
+        return 1
+    try:
+        text = _render(source, format=args.format, quality=args.quality, pages=pages)
+    except Exception as e:  # the engine refusing input it cannot read
+        print(f"pdfluent-extract: extraction failed: {e}", file=sys.stderr)
+        return 1
+    try:
+        _write_output(text, args.output)
+    except OSError as e:
+        print(f"pdfluent-extract: cannot write {args.output}: {e}", file=sys.stderr)
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

pdfluent_extract-0.1.0.dist-info/METADATA

@@ -0,0 +1,142 @@
+Metadata-Version: 2.5
+Name: pdfluent-extract
+Version: 0.1.0
+Summary: PDF to Markdown, JSON and RAG chunks — fast, local, no system dependencies
+Project-URL: Homepage, https://pdfluent.com
+Project-URL: Documentation, https://pdfluent.com/docs
+Project-URL: Pricing, https://pdfluent.com/sdk/pricing/
+Project-URL: Source, https://github.com/pdfluent/pdfluent-sdk
+Project-URL: Changelog, https://github.com/pdfluent/pdfluent-sdk/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/pdfluent/pdfluent-sdk/issues
+Author-email: "Innovation Trigger B.V." <team@pdfluent.com>
+License-Expression: AGPL-3.0-only OR LicenseRef-PDFluent-Commercial
+License-File: LICENSE
+License-File: LICENSE-COMMERCIAL
+Keywords: chunking,docling,langchain,llamaindex,llm,markdown,pdf,pdf-to-text,rag,table-extraction
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Text Processing
+Requires-Python: >=3.8
+Requires-Dist: pdfluent<2,>=1.1.0
+Provides-Extra: langchain
+Requires-Dist: langchain-pdfluent>=0.1; extra == 'langchain'
+Provides-Extra: llamaindex
+Requires-Dist: llama-index-readers-pdfluent>=0.1; extra == 'llamaindex'
+Description-Content-Type: text/markdown
+
+# pdfluent-extract
+
+PDF and Office files to Markdown, JSON and RAG chunks, in three calls. It is
+pure Python: the engine underneath is
+[`pdfluent`](https://pypi.org/project/pdfluent/), which pip pulls in
+automatically. There is nothing to compile and no system dependency to
+install — on Linux arm64 and Alpine/musl as much as anywhere else, because
+`pdfluent` 1.1.0 ships a wheel for every platform in the matrix below.
+
+## Install
+
+```bash
+pip install pdfluent-extract
+```
+
+It needs Python 3.8 or later and `pdfluent` 1.1.0 or later.
+
+## Use
+
+```python
+from pdfluent_extract import to_markdown
+
+print(to_markdown("report.pdf"))
+```
+
+`to_markdown` takes a path, `bytes` or a file-like object, and routes PDF and
+Office (`.docx`/`.pptx`/`.xlsx`) by magic bytes, not by the extension. `pages`
+lists 0-based PDF page indices (`None` for the whole file).
+
+```python
+from pdfluent_extract import to_json
+
+doc = to_json("report.pdf")
+print(doc["name"], len(doc["texts"]))
+```
+
+`to_json` returns the file as a Docling `DoclingDocument`, as a dict — the
+same JSON `DoclingDocument.model_validate_json` reads.
+
+## Command line
+
+```console
+$ pdfluent-extract report.pdf -o report.md
+$ pdfluent-extract report.pdf --format json --pages 1-3 > doc.json
+$ cat report.pdf | pdfluent-extract - --format text
+```
+
+`--format` is one of `md`, `json`, `chunks` or `text`; `--pages` counts
+from 1 (`1-3,5`). Without `-o` (or with `-o -`) the output goes to stdout.
+
+## Chunks for RAG
+
+```python
+from pdfluent_extract import to_chunks
+
+for chunk in to_chunks("report.pdf", max_tokens=512):
+    print(chunk.metadata["page"], chunk.metadata["section_path"], chunk.text[:80])
+```
+
+One chunk per paragraph, heading and list item, and one per table. Every chunk
+carries `page`, `section_path` (the enclosing headings) and `bbox` in its
+metadata, plus `source` for path inputs. Tables longer than the budget split
+by rows with the header repeated. PDF only in v1.
+
+## With LangChain and LlamaIndex
+
+```bash
+pip install "pdfluent-extract[langchain]"
+```
+
+```python
+from langchain_pdfluent import PDFluentLoader
+
+docs = PDFluentLoader("report.pdf").load()
+print(docs[0].page_content, docs[0].metadata["bbox"])
+```
+
+```bash
+pip install "pdfluent-extract[llamaindex]"
+```
+
+```python
+from llama_index.readers.pdfluent import PDFluentReader
+
+docs = PDFluentReader().load_data("report.pdf")
+print(docs[0].text[:200])
+```
+
+## Supported platforms
+
+Every platform `pdfluent` 1.1.0 ships a wheel for: macOS (universal2),
+Windows x64, Linux x86_64 and arm64 on glibc (manylinux2014) and musl
+(musllinux_1_2) — Python 3.8 through 3.13 from one abi3 wheel per platform.
+
+## Quality
+
+`quality="fast"` is the only level in v1; anything else is refused by name.
+Further levels (vision/OCR) are designed later.
+
+## Licence
+
+AGPL-3.0 or a commercial licence, at your option; see `LICENSE` and
+`LICENSE-COMMERCIAL`. The commercial licence is sold yearly and self-service
+at <https://pdfluent.com/sdk/pricing/>.

pdfluent_extract-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+pdfluent_extract/__init__.py,sha256=BrtwtqtV5n7gYZaB70ITmtMzPY0Ve8Cb9A4bLS_O9iM,8055
+pdfluent_extract/cli.py,sha256=u0FMsEeBXtf7u2Ueah5ptl8Si9q3bcma32rQhEEEitQ,5617
+pdfluent_extract-0.1.0.dist-info/METADATA,sha256=lNyc6T_ImIQoqzulQtLuopxZ-ubAfCpeoQn7GckUQwI,4812
+pdfluent_extract-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+pdfluent_extract-0.1.0.dist-info/entry_points.txt,sha256=-IEo7RLPQhDUMdHhaGANvJFxlqEUmxDJYapk9apJrQ8,63
+pdfluent_extract-0.1.0.dist-info/licenses/LICENSE,sha256=DZak_2itbUtvHzD3E7GNUYSRK6jdOJ-GqncQ2weavLA,34523
+pdfluent_extract-0.1.0.dist-info/licenses/LICENSE-COMMERCIAL,sha256=ylTZq0bZnoHQ3S6m7REvPv-n-HzTtlqHaxdAye_lme0,10026
+pdfluent_extract-0.1.0.dist-info/RECORD,,

pdfluent_extract-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

pdfluent_extract-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+pdfluent-extract = pdfluent_extract.cli:main