Rewrite card: PDF to Markdown positioning, quick start, licence in plain words

README.md

@@ -15,30 +15,29 @@ tags:
   - lightgbm
   - rag
   - pdf-to-markdown
+  - document-parsing
 ---
 
-# PDFluent heading level classifier: heading levels 1 to 3 for PDF documents
+# PDF Heading Level Classifier: heading detection for PDF to Markdown
 
-A small LightGBM model that assigns heading level 1, 2 or 3 to heading blocks detected by the PDFluent SDK in PDFs, for developers converting PDFs to structured formats.
+Assigns heading level 1, 2 or 3 to every heading block detected in PDFs. A small LightGBM model for #, ## and ### structure in PDF to Markdown output, compiled into PDFluent SDK 1.3.0 and on by default with no separate install. PDFluent SDK 1.3.0 scores the highest overall on opendataloader-bench of the engines on its public leaderboard*: 0.9168 against 0.907 for opendataloader [hybrid], 0.885 for nutrient and 0.882 for docling.
 
-Model name: `heading_level_979`. The weights are `model.json.gz`, a compressed LightGBM tree dump. This is not an ONNX model.
+\* Measured with the benchmark's own harness and evaluator on its 200 documents, PDFluent SDK 1.3.0, `quality="auto"` with `keep_furniture=True`, on Linux (CPU only), 29 October 2026: 0.9168 overall against 0.907 for opendataloader [hybrid], 0.885 for nutrient and 0.882 for docling. Competitor figures are taken from the benchmark's public README (read 2 November 2026), not re-run by us (our own re-run of opendataloader [hybrid] on 28 October 2026 gave 0.9068). PDFluent is not on that leaderboard; the results are submitted in a pull request: https://github.com/opendataloader-project/opendataloader-bench/pull/37. Development was optimised for this benchmark among its targets. The scores are measured on the benchmark's own 200 documents. The 19-measure result on our own held-out half and the separate checks are on pdfluent.com/benchmarks. The scores come from a release candidate wheel of 1.3.0 that reported version 1.2.0. Speed is not published. The run keeps page headers and footers, because the benchmark's ground truth counts them as content. The difference is one run without a confidence interval.
 
-## Quick start
-
-With the PDFluent SDK (Python, SDK 1.3.0 or newer), the model is compiled in and on by default:
+## Use it in two lines
 
 ```bash
 pip install pdfluent
 ```
 
 ```python
-import pdfluent
-
-doc = pdfluent.open("report.pdf")
-markdown = doc.extract_markdown()  # headings come out as #, ## and ###
-print(markdown)
+import pdfluent; print(pdfluent.open("report.pdf").extract_markdown())  # headings come out as #, ## and ###
 ```
 
+The model is compiled into SDK 1.3.0 and on by default.
+
+## Inspect the weights without the SDK
+
 To inspect the weights without the SDK:
 
 ```python
@@ -52,6 +51,13 @@ print(model["feature_names"])     # the features the SDK computes per heading bl
 print(model["num_class"], len(model["tree_info"]))
 ```
 
+## What you get
+
+- Assign heading level 1, 2 or 3 to every heading block the SDK detects
+- Trained on arXiv (CC BY 4.0, CC0), PubMed Central (CC BY) and synthetic pages
+- One feature row per heading block in, class scores for level 1, 2 and 3 out
+- Weights published here for inspection, with the attribution list for every training paper
+
 ## Inputs and outputs
 
 The model takes a feature row per heading block from the PDFluent SDK. Features include font size, position and neighbouring blocks. It outputs a level per heading. It is compiled into the PDFluent SDK since version 1.3.0 and runs by default there. No separate install is needed. The SDK handles heading detection and feature extraction.
@@ -71,11 +77,13 @@ The CC BY attribution list is [attribution.json](attribution.json); [PMC-AUTHORS
 
 Validated only on a held-out part of the same development data, not on a separate sealed benchmark. Synthetic layouts did not improve performance. Behaviour on unrelated PDFs is not established. Only assigns levels, does not detect headings. Requires the PDFluent SDK's heading detection and feature extraction to be useful.
 
-## Licence
+## Licence in plain words
+
+The heading level classifier is part of the PDFluent SDK, licensed under AGPL-3.0-only or the PDFluent Commercial Licence at your option. The model weights are available under these licences. See https://pdfluent.com/license for terms.
 
-Weights are offered under AGPL-3.0-only or the PDFluent Commercial Licence. Commercial use without AGPL obligations requires the commercial licence: https://pdfluent.com/license. Copyright 2026 Innovation Trigger B.V.
+## Try PDFluent
 
-Licence texts: [LICENSE](LICENSE) (AGPL-3.0) and [LICENSE-COMMERCIAL](LICENSE-COMMERCIAL).
+Run pip install pdfluent to process your PDFs into structured Markdown. The docs at pdfluent.com/docs show how to use extract_markdown with the classifier.
 
 ## Citation
 
@@ -94,9 +102,11 @@ Licence texts: [LICENSE](LICENSE) (AGPL-3.0) and [LICENSE-COMMERCIAL](LICENSE-CO
 
 - Website: https://pdfluent.com
 - Documentation: https://pdfluent.com/docs
-- Licence: https://pdfluent.com/license
+- SDK on PyPI: https://pypi.org/project/pdfluent/
 - SDK source and releases: https://github.com/pdfluent/pdfluent-sdk
+- Licence: https://pdfluent.com/license
 - Organisation: https://huggingface.co/PDFluent
 - Formula recognition model: https://huggingface.co/PDFluent/formula-recognition-onnx
 - Heading level classifier: https://huggingface.co/PDFluent/pdf-heading-level-classifier
-- Layout ground-truth sample: https://huggingface.co/datasets/PDFluent/pdf-document-layout-ground-truth
+- Layout ground-truth dataset: https://huggingface.co/datasets/PDFluent/pdf-document-layout-ground-truth
+- Collection: https://huggingface.co/collections/PDFluent/pdfluent-document-ai-6ae99736adab8c6d90781ab5