Merge pull request #19 from artiz/fix/tableformer-silent-fallback

fix(ci,scripts): fix publish-models.yml export/staging + download_dependencies.sh sidecar gap

Author: artiz

.github/workflows/ci.yml

@@ -33,7 +33,7 @@ jobs:
     name: fmt · clippy (pinned)
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v7
 
       - uses: dtolnay/rust-toolchain@master
         with:
@@ -52,7 +52,7 @@ jobs:
     name: test (stable)
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v7
 
       # Tests stay on the current stable so they catch real compiler breakage.
       - uses: dtolnay/rust-toolchain@stable
@@ -75,7 +75,7 @@ jobs:
     permissions:
       contents: write # push the version-bump commit + tag
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v7
         with:
           fetch-depth: 0 # full history + tags, for the semantic version bump
           # Push the release commit + tag as an admin PAT so it satisfies the

.github/workflows/npm-publish.yml

@@ -61,7 +61,7 @@ jobs:
           - target: x86_64-pc-windows-msvc
             host: windows-latest
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v7
         with:
           ref: ${{ inputs.tag || github.ref }}
 
@@ -75,7 +75,7 @@ jobs:
           key: ${{ matrix.target }}
           workspaces: "."
 
-      - uses: actions/setup-node@v5
+      - uses: actions/setup-node@v6
         with:
           node-version: 20
 
@@ -94,7 +94,7 @@ jobs:
         run: npx napi build --platform --release --target ${{ matrix.target }} --js native.js --dts native.d.ts
 
       - name: Upload prebuilt binary
-        uses: actions/upload-artifact@v5
+        uses: actions/upload-artifact@v7
         with:
           name: bindings-${{ matrix.target }}
           path: crates/fleischwolf-node/fleischwolf.*.node
@@ -104,7 +104,7 @@ jobs:
       # linux-x64 build) for the publish job to include in the main package.
       - name: Upload JS binding
         if: matrix.target == 'x86_64-unknown-linux-gnu'
-        uses: actions/upload-artifact@v5
+        uses: actions/upload-artifact@v7
         with:
           name: js-binding
           path: |
@@ -117,11 +117,11 @@ jobs:
     needs: build
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v7
         with:
           ref: ${{ inputs.tag || github.ref }}
 
-      - uses: actions/setup-node@v5
+      - uses: actions/setup-node@v6
         with:
           node-version: 20
           registry-url: "https://registry.npmjs.org"
@@ -131,14 +131,14 @@ jobs:
 
       # Prebuilt binaries → artifacts/<name>/fleischwolf.<triple>.node
       - name: Download prebuilt binaries
-        uses: actions/download-artifact@v5
+        uses: actions/download-artifact@v8
         with:
           pattern: bindings-*
           path: crates/fleischwolf-node/artifacts
 
       # The JS loader + types → the package root.
       - name: Download JS binding
-        uses: actions/download-artifact@v5
+        uses: actions/download-artifact@v8
         with:
           name: js-binding
           path: crates/fleischwolf-node

.github/workflows/publish-models.yml

@@ -40,9 +40,9 @@ jobs:
       GH_TOKEN: ${{ github.token }}
       TAG: ${{ inputs.tag }}
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v7
 
-      - uses: actions/setup-python@v5
+      - uses: actions/setup-python@v6
         with:
           python-version: "3.11"
 
@@ -57,7 +57,7 @@ jobs:
       - name: Install TableFormer export deps
         continue-on-error: true
         id: tf-deps
-        run: pip install docling_ibm_models onnxscript onnxruntime huggingface_hub
+        run: pip install docling_ibm_models onnxscript onnxruntime huggingface_hub opencv-python-headless
 
       - name: Export TableFormer
         if: steps.tf-deps.outcome == 'success'
@@ -90,8 +90,8 @@ jobs:
         run: |
           mkdir -p release-assets
           stage() { # <source-path> <asset-name>
-            [ -f "$1" ] && cp "$1" "release-assets/$2"
-            [ -f "$1.data" ] && cp "$1.data" "release-assets/$2.data"
+            if [ -f "$1" ]; then cp "$1" "release-assets/$2"; fi
+            if [ -f "$1.data" ]; then cp "$1.data" "release-assets/$2.data"; fi
           }
           stage third-party/lib/libpdfium.so libpdfium.so
           stage third-party/ocr_rec.onnx ocr_rec.onnx

README.md

@@ -192,16 +192,8 @@ const json = await convertFileAsync('report.docx', { to: 'json' })
 
 Declarative formats (Markdown, HTML, DOCX, XLSX, …) work out of the box. The
 PDF/image pipeline needs pdfium + the ONNX models (not bundled), so it throws
-until you fetch them — a one-liner from your app's directory (pdfium and OCR
-from their own upstream releases; the layout model and TableFormer —
-PyTorch→ONNX exports of docling-project's own models,
-Apache-2.0/CDLA-Permissive-2.0, see [`MODELS_NOTICE.md`](./MODELS_NOTICE.md) —
-from fleischwolf's own hosted release), straight into `./models` and
-`./.pdfium`, which the package looks for by default — no env vars needed:
-
-```bash
-curl -fsSL https://raw.githubusercontent.com/artiz/fleischwolf/master/scripts/download_dependencies.sh | sh
-```
+until you fetch them with `scripts/download_dependencies.sh` — see
+[Getting the ML models](#getting-the-ml-models) below.
 
 A reusable `Pipeline` keeps those models warm across many PDFs.
 
@@ -211,6 +203,68 @@ Runnable Node + Bun examples are in
 [`crates/fleischwolf-node/README.md`](./crates/fleischwolf-node/README.md) for
 the full API.
 
+## Getting the ML models
+
+The PDF/image pipeline needs native assets that aren't bundled in the crate or
+the npm addon: [pdfium](https://pdfium.googlesource.com/pdfium/) (text
+extraction + page rendering) and three ONNX models — RT-DETR layout, PP-OCRv3
+recognition, and TableFormer (optional; tables fall back to geometric
+reconstruction without it). `scripts/download_dependencies.sh` fetches all of
+them from this repo's [GitHub Releases](https://github.com/artiz/fleischwolf/releases)
+(tag `models-v1`) straight into `./models` and `./.pdfium`, relative to the
+current directory — both the Rust CLI/library and the Node.js/Bun bindings
+look there by default, so no env vars or extra setup are needed afterwards:
+
+```bash
+# from a checkout of this repo, or any directory you'll run fleischwolf from:
+scripts/download_dependencies.sh
+
+# or, without a checkout — e.g. a container build step, or a fresh npm project:
+curl -fsSL https://raw.githubusercontent.com/artiz/fleischwolf/master/scripts/download_dependencies.sh | sh
+```
+
+| Asset | Destination |
+| --- | --- |
+| pdfium (Linux x64) | `.pdfium/lib/libpdfium.so` |
+| RT-DETR layout | `models/layout_heron.onnx` |
+| PP-OCRv3 rec + dictionary | `models/ocr_rec.onnx`, `models/ppocr_keys_v1.txt` |
+| TableFormer (optional) | `models/tableformer/{encoder,decoder,bbox}.onnx` (+ `.data` sidecars where the export needs them) |
+
+Idempotent — safe to re-run; it skips files already on disk. Pass `--force` to
+re-fetch everything, or set `$FLEISCHWOLF_MODELS_URL` to fetch from a
+different host (your own export, an internal mirror, …). pdfium is Linux x64
+only for now — other platforms, or building the models from source, need
+[`scripts/pdf_setup.sh`](#testing) instead.
+
+Then either:
+
+```bash
+cargo run -p fleischwolf-cli -- document.pdf
+```
+
+or, in a Node.js/Bun app:
+
+```bash
+npm i fleischwolf
+```
+
+```js
+import { convertFileAsync } from 'fleischwolf'
+const { content } = await convertFileAsync('document.pdf', { to: 'markdown' })
+console.log(content)
+```
+
+The layout model and TableFormer are PyTorch→ONNX exports of docling-project's
+own models (Apache-2.0 / CDLA-Permissive-2.0 — see
+[`MODELS_NOTICE.md`](./MODELS_NOTICE.md) for full attribution); pdfium and the
+OCR model are re-hosted, unmodified, from their own public releases — all on
+one host for convenience.
+
+To point at files you exported or placed elsewhere instead, set the env vars
+directly: `DOCLING_LAYOUT_ONNX`, `DOCLING_OCR_REC_ONNX`, `DOCLING_OCR_DICT`,
+`DOCLING_TABLEFORMER_{ENCODER,DECODER,BBOX}`, `PDFIUM_DYNAMIC_LIB_PATH` — an
+env var always wins over the `./models` / `./.pdfium` default.
+
 ## Testing
 
 All commands run from the `fleischwolf/` workspace root.
@@ -268,8 +322,7 @@ cargo run -p fleischwolf-cli -- --strict crates/fleischwolf/sample.html
 cargo run -p fleischwolf-cli -- --to json crates/fleischwolf/sample.html
 cargo run -p fleischwolf-cli -- --to json crates/fleischwolf/sample.html > out.json
 
-# PDF/image conversion needs the ML models: scripts/download_dependencies.sh once,
-# then it just works — models/ and .pdfium/lib are picked up automatically.
+# PDF/image conversion needs the ML models — see "Getting the ML models" above.
 scripts/download_dependencies.sh
 cargo run -p fleischwolf-cli -- document.pdf
 

scripts/download_dependencies.sh

@@ -23,9 +23,9 @@
 #   models/layout_heron.onnx
 #   models/ocr_rec.onnx
 #   models/ppocr_keys_v1.txt
-#   models/tableformer/encoder.onnx
-#   models/tableformer/decoder.onnx (+ decoder.onnx.data, if the export needs it)
-#   models/tableformer/bbox.onnx
+#   models/tableformer/encoder.onnx (+ .data, if the export needs it)
+#   models/tableformer/decoder.onnx (+ .data, if the export needs it)
+#   models/tableformer/bbox.onnx (+ .data, if the export needs it)
 #
 # pdfium is Linux x64 only for now, matching what's hosted in the release; for
 # other platforms (or to build the models from source) see scripts/pdf_setup.sh.
@@ -81,8 +81,10 @@ fetch "$BASE_URL/layout_heron.onnx" models/layout_heron.onnx
 fetch "$BASE_URL/ocr_rec.onnx" models/ocr_rec.onnx
 fetch "$BASE_URL/ppocr_keys_v1.txt" models/ppocr_keys_v1.txt
 fetch "$BASE_URL/encoder.onnx" models/tableformer/encoder.onnx
+fetch_optional "$BASE_URL/encoder.onnx.data" models/tableformer/encoder.onnx.data
 fetch "$BASE_URL/decoder.onnx" models/tableformer/decoder.onnx
 fetch_optional "$BASE_URL/decoder.onnx.data" models/tableformer/decoder.onnx.data
 fetch "$BASE_URL/bbox.onnx" models/tableformer/bbox.onnx
+fetch_optional "$BASE_URL/bbox.onnx.data" models/tableformer/bbox.onnx.data
 
 echo "done — models/ and .pdfium/lib populated in $(pwd)"

scripts/export_layout.py

@@ -8,6 +8,7 @@
     python scripts/export_layout.py models/layout_heron.onnx
 """
 
+import os
 import sys
 
 import torch
@@ -30,6 +31,9 @@ def forward(self, pixel_values):
 
 def main() -> None:
     out = sys.argv[1] if len(sys.argv) > 1 else "models/layout_heron.onnx"
+    out_dir = os.path.dirname(out)
+    if out_dir:
+        os.makedirs(out_dir, exist_ok=True)
     print(f"loading {REPO} ...", flush=True)
     model = RTDetrV2ForObjectDetection.from_pretrained(
         REPO, torch_dtype=torch.float32