Merge pull request #149 from artiz/claude/pages-and-referenced-images

pdf: --pages A-B window + memory-bounded referenced images (#80)

Author: artiz

CLAUDE.md

@@ -0,0 +1,103 @@
+# CLAUDE.md — working notes for AI-assisted sessions
+
+Rust port of [docling](https://github.com/docling-project/docling): document
+conversion (PDF/Office/HTML/audio/video/…) to Markdown / docling-JSON / DCLX,
+validated for byte-for-byte conformance against upstream Python docling.
+
+## Workflow rules
+
+- **Every commit must be signed off by the author.** End each commit message
+  with `Signed-off-by: name <email>`.
+- Claude Web: **Never open pull requests on `artiz/docling.rs`.** Push a `claude/<topic>`
+  branch and hand back a compare link
+  (`https://github.com/docling-project/docling.rs/compare/master...artiz:docling.rs:<branch>?expand=1`);
+  the maintainer opens/merges PRs themself (usually into the upstream
+  `docling-project/docling.rs`; `artiz/docling.rs` is their working fork).
+- One feature = one branch off fresh `origin/master`. Don't stack unrelated
+  work.
+- Issue numbers (`#80`, `#138`, …) refer to `docling-project/docling.rs`
+  issues; reference them in commit messages (`Refs #NN`).
+- **Slack notifications** (when the Slack MCP connector is available): post to
+  **#claude-code** (channel ID `C0BKAHN0BSM`) when (a) a question blocks the
+  work and needs the maintainer's answer, (b) a long task finishes — include
+  the outcome and the compare link, (c) idle/bored — the queue is empty;
+  suggest what to pick up next. Keep it to these events; don't narrate
+  routine progress there.
+
+## Workspace map
+
+| Crate | What it is |
+|---|---|
+| `crates/docling-core` | `DoclingDocument` model, Markdown/JSON/DCLX serializers, `MarkdownStreamer`, chunkers |
+| `crates/docling` | `DocumentConverter` (format routing), declarative backends (`src/backend/`), streaming (`src/stream.rs`), video (`src/video.rs`) |
+| `crates/docling-pdf` | ML pipeline: pdfium + RT-DETR layout + TableFormer + PP-OCRv3 + enrichment (`ml` feature); pure-Rust text-layer path compiles for wasm without it |
+| `crates/docling-asr` | Whisper ASR: symphonia decode (audio + video containers) → log-mel → ONNX encoder/decoder |
+| `crates/docling-cli` | `docling-rs` binary (also `serve` subcommand behind `--features serve`) |
+| `crates/docling-serve` | axum HTTP conversion API (+ Dockerfile with ffmpeg) |
+| `crates/docling-py` / `docling-node` / `docling-wasm` | pyo3 / napi-rs / wasm-bindgen bindings — **excluded from the workspace default-members; py and wasm build from their own directories** |
+| `crates/docling-rag` | RAG subsystem (embedder, store, web UI) |
+
+## Build & test
+
+```bash
+cargo test --lib --tests -p docling-core -p docling -p docling-asr -p docling-serve -p docling-pdf
+cargo clippy --lib --tests --bins <same -p list>   # keep it warning-free
+cargo fmt --all
+cargo check -p docling --no-default-features        # pdf-text/wasm path
+(cd crates/docling-py && cargo check)               # pyo3 binding
+(cd crates/docling-wasm && cargo check)             # wasm binding
+```
+
+- Prefer `--lib --tests` over bare `cargo test`: it skips example binaries,
+  each of which statically links onnxruntime (~0.3–5 GB of `target/` churn).
+- **Disk discipline (remote container!):** `target/debug` balloons past 15 GB.
+  When "No space left on device" hits, delete `target/debug/examples`,
+  `target/debug/incremental`, oldest `target/debug/deps` files — deletes work
+  even at 0 free. `CARGO_INCREMENTAL=0` helps. Old rustup toolchains and
+  `~/.cargo/registry/cache` are also safe to drop.
+- Tests run with CWD = the crate dir, but shared fixtures and runtime assets
+  live at the **repo root**. Resolve fixtures via
+  `Path::new(env!("CARGO_MANIFEST_DIR")).join("../..")` and gate asset-needing
+  tests with a skip (see `crates/docling/tests/pages.rs::pdfium_ready`,
+  `crates/docling/src/video.rs::asr_models_ready`) — CI without models/pdfium
+  must stay green.
+
+## Runtime assets & env
+
+- `models/` (repo root): layout, TableFormer, OCR, ASR (`models/asr/`,
+  presets in subdirs), enrichment, embedder. `.pdfium/lib/libpdfium.so` for
+  page rendering. Fetch: `scripts/install/download_dependencies.sh`.
+- Resolution is CWD-relative with exe-dir fallback; env overrides:
+  `PDFIUM_DYNAMIC_LIB_PATH`, `DOCLING_ASR_{ENCODER,DECODER,VOCAB}`,
+  `DOCLING_FFMPEG` (video frames — ffmpeg is a runtime binary, never a build
+  dep), `DOCLING_RS_PDF_WORKERS/_THREADS/_INTRA`, `DOCLING_RS_FP32`,
+  `DOCLING_RS_EP` (GPU execution providers), `DOCLING_RS_ASR_LANG`,
+  `DOCLING_CHUNK_TOKENIZER`.
+
+## Conformance & fixtures
+
+- `tests/data/<format>/sources/` + `groundtruth/` (+ `groundtruth_dclx/`,
+  `-enriched/`): the corpus mirrored from upstream docling. Declarative
+  formats must match Python docling **byte-for-byte**; the ML pipeline is
+  pinned by deterministic snapshots (`tests/snapshots/`,
+  `scripts/conformance/`, see `docs/PDF_CONFORMANCE.md`).
+- Output-regression suite: `crates/docling/tests/regression.rs` over
+  `crates/docling/tests/data`; regenerate intentional changes with
+  `DOCLING_RS_REGEN=1`.
+- When touching serializers, keep the streaming and buffered paths
+  byte-identical — `MarkdownStreamer` tests assert exactly that.
+
+## Conventions that keep recurring
+
+- Options plumb through **every** surface in one PR: lib builder on
+  `DocumentConverter` → CLI flag → serve option (multipart field + JSON body +
+  query param) → Python kwarg → Node option struct. Grep `video_frames` or
+  `page_range` for the full pattern.
+- Degradation over failure: a missing optional tool/model (ffmpeg, enrichment
+  model) warns and degrades; only "nothing convertible at all" errors.
+- Docs live in `README.md` (user-facing) + `docs/MIGRATION.md` (parity table
+  with real conformance numbers) — update both with behavior changes;
+  `docs/PDF_CONFORMANCE.md` for pipeline/model changes.
+- Rust 1.96, edition 2021, `cargo fmt` + clippy clean; comments explain *why*
+  (docling parity, perf tradeoffs), matching the existing dense doc-comment
+  style.

README.md

@@ -350,13 +350,21 @@ it cancels the work. Concatenating every chunk is **byte-identical** to the
 buffered `export_to_markdown()`.
 
 Streaming is Markdown-only — JSON serializes docling-core's reference-based tree
-and needs every node up front. Picture placeholders and `embedded` data-URI
-images stream; the `referenced` mode writes sidecar files, so it stays on the
-buffered `export_to_markdown_with_images` path. Use
-`convert_streaming_images(source, ImageMode::Embedded)` to pick the image mode.
+and needs every node up front. Every image mode streams
+(`convert_streaming_images(source, mode)` picks it): placeholders and `embedded`
+data URIs render inline, and `referenced` (issue #80) writes each page's image
+files under the converter's `artifacts_dir` **as that page's Markdown is
+emitted**, then drops the bytes — an image-heavy PDF holds ~one page of images
+in memory instead of all of them until export.
+
+`--pages A-B` (issue #80; also `Pipeline::pages` /
+`DocumentConverter::page_range`, `pages` in serve/Node, `page_range=` in
+Python) converts only that 1-based inclusive PDF page window. Out-of-window
+pages are skipped *before* rasterization, so 3 pages of a 500-page PDF cost 3
+pages; `B` past the end clamps, and a window that selects nothing is an error.
 
 The CLI streams Markdown by default (`--no-stream` opts back into buffering;
-`--to json` and `--images referenced` always buffer). `--no-table-former` skips
+`--to json` always buffers). `--no-table-former` skips
 loading/running the TableFormer table-structure model, falling back to simple
 geometric table reconstruction from cell positions — no model load, no
 per-table inference, which can noticeably speed up parsing (especially in

crates/docling-cli/src/main.rs

@@ -3,13 +3,19 @@
 //! The docling.rs counterpart of `docling.cli.main`; `docling-rs serve`
 //! (with `--features serve`) starts the HTTP conversion API.
 //!
-//! Usage: docling-rs [--strict] [--to md|json] [--images MODE] [--fetch-images] [--no-stream] [--no-table-former] [--no-ocr] [--asr-model PRESET] [--video-frames N] [--use-web-browser] [--enrich-picture-classes] [--enrich-code] [--enrich-formula] <input-file>
+//! Usage: docling-rs [--strict] [--to md|json] [--pages A-B] [--images MODE] [--fetch-images] [--no-stream] [--no-table-former] [--no-ocr] [--asr-model PRESET] [--video-frames N] [--use-web-browser] [--enrich-picture-classes] [--enrich-code] [--enrich-formula] <input-file>
 //!   --to md|json       output format (default: md). `json` emits docling-core's
 //!                      native DoclingDocument JSON (export_to_dict).
+//!   --pages A-B        convert only PDF pages A through B (1-based, inclusive;
+//!                      a single page number also works). Skipped pages are
+//!                      never rasterized, so a small window over a huge PDF is
+//!                      cheap. Non-PDF inputs ignore this.
 //!   --images MODE      picture handling for Markdown (mirrors docling's
 //!                      image_mode): placeholder (default) | embedded | referenced.
-//!                      `referenced` writes image files under ./artifacts/.
-//!                      JSON always embeds extracted images as data URIs.
+//!                      `referenced` writes image files under ./artifacts/ —
+//!                      streamed to disk page by page, so image-heavy PDFs stay
+//!                      memory-bounded. JSON always embeds extracted images as
+//!                      data URIs.
 //!   --fetch-images     for HTML/EPUB, resolve external <img src> (data: URIs,
 //!                      local files, http(s) URLs, EPUB archive entries) and embed
 //!                      the bytes. Off by default; fetches over the network.
@@ -87,6 +93,7 @@ fn main() -> ExitCode {
     let mut enrich_code = false;
     let mut enrich_formula = false;
     let mut bench_warm: Option<usize> = None;
+    let mut pages: Option<(usize, usize)> = None;
     let mut path: Option<String> = None;
     let mut args = std::env::args().skip(1);
     while let Some(arg) = args.next() {
@@ -111,6 +118,18 @@ fn main() -> ExitCode {
             // 0 = transcript only). Default 8.
             "--video-frames" => video_frames = args.next().and_then(|v| v.parse().ok()),
             "--images" => images = args.next().unwrap_or_default(),
+            // PDF page window, 1-based inclusive: `--pages 3-7` or `--pages 3`.
+            "--pages" => match args.next().as_deref().map(docling::parse_page_range) {
+                Some(Ok(range)) => pages = Some(range),
+                Some(Err(e)) => {
+                    eprintln!("error: --pages: {e}");
+                    return ExitCode::from(2);
+                }
+                None => {
+                    eprintln!("error: --pages needs a range like 1-10 (or a single page)");
+                    return ExitCode::from(2);
+                }
+            },
             // Hidden benchmarking aid: load the PDF/image pipeline once, then time
             // N warm conversions (models already loaded), printing the avg seconds
             // per conversion to stdout. This is the startup-excluded counterpart to
@@ -192,13 +211,17 @@ fn main() -> ExitCode {
     if let Some(max) = video_frames {
         converter = converter.video_frames(max);
     }
+    if let Some((first, last)) = pages {
+        converter = converter.page_range(first, last);
+    }
 
     // Stream Markdown by default: print each chunk as the converter produces it
-    // (page by page for PDF). JSON needs the whole tree, and the referenced image
-    // mode writes sidecar files, so both keep the buffered path. `--no-stream` opts
-    // back into buffering for the streamable cases too.
+    // (page by page for PDF). Referenced images stream too (#80): each page's
+    // files land under ./artifacts/ as that page is printed, so image bytes
+    // never accumulate. JSON needs the whole tree, so it keeps the buffered
+    // path. `--no-stream` opts back into buffering.
     let is_markdown = matches!(to.as_str(), "md" | "markdown");
-    if is_markdown && image_mode != ImageMode::Referenced && !no_stream {
+    if is_markdown && !no_stream {
         let stream = match converter.convert_streaming_images(source, image_mode) {
             Ok(s) => s,
             Err(e) => {
@@ -227,6 +250,9 @@ fn main() -> ExitCode {
             eprintln!("error: writing output: {e}");
             return ExitCode::FAILURE;
         }
+        if image_mode == ImageMode::Referenced {
+            eprintln!("referenced images (if any) written to ./artifacts/ as pages completed");
+        }
         return ExitCode::SUCCESS;
     }