htmlsift 0.1.0__py3-none-any.whl

htmlsift/core/render.py

@@ -0,0 +1,328 @@
+"""
+Readable-markdown renderer with block-level DOM provenance.
+
+One walk of a parsed HTML tree emits markdown lines and, per line, the set of
+source DOM elements that produced it (line_src). That provenance lets a caller
+label or serialize each rendered line by its DOM origin with no marker injection,
+no re-render, and no alignment step. The renderer is board-agnostic: it does not
+sanitize and knows nothing of any benchmark's annotations.
+
+Layout tables (page structure built from <table>) are flowed as ordinary blocks so
+their regions stay independently labelable; data tables render as markdown tables.
+
+    parse(html)             -> lxml tree
+    render_tree(tree)       -> (lines, line_src)      # labeling / serialization
+    render(html)            -> markdown text          # inference
+"""
+
+import re
+
+from lxml import html as lxml_html
+
+COLLAPSE_RE = re.compile(r"\s+")
+SKIP_TAGS = {"head", "script", "style", "title", "meta", "link", "base"}
+SIMPLE_BLOCK_TAGS = {"p", "div", "section", "article", "header", "footer", "main",
+                     "aside", "figure", "figcaption", "fieldset"}
+HEADING_TAGS = {"h1": 1, "h2": 2, "h3": 3, "h4": 4, "h5": 5, "h6": 6}
+WRAP_TAGS = {"em": ("_", "_"), "i": ("_", "_"), "strong": ("**", "**"),
+             "b": ("**", "**"), "code": ("`", "`"), "del": ("~~", "~~"),
+             "s": ("~~", "~~"), "strike": ("~~", "~~")}
+LIST_TAGS = {"ul", "ol"}
+ROW_GROUP_TAGS = {"thead", "tbody", "tfoot"}
+
+# A cell holding any of these is page-structure, not tabular data.
+BLOCKISH_TAGS = (SIMPLE_BLOCK_TAGS | set(HEADING_TAGS) | LIST_TAGS |
+                 {"table", "blockquote"})
+
+
+def parse(html_str):
+    """HTML string -> lxml tree. Bytes-encode when the string carries an encoding
+    declaration, which lxml rejects on a str."""
+    parser = lxml_html.HTMLParser(collect_ids=False, encoding="utf-8",
+                                  remove_blank_text=True, remove_comments=True,
+                                  remove_pis=True)
+    if isinstance(html_str, str) and (
+            "<?xml" in html_str or "<meta charset" in html_str or "encoding=" in html_str):
+        html_str = html_str.encode("utf-8")
+    return lxml_html.fromstring(html_str, parser=parser)
+
+
+def _direct_cells(el):
+    """Cells of this table's own rows (not nested tables')."""
+    def rows(node):
+        for ch in node:
+            t = ch.tag if isinstance(ch.tag, str) else ""
+            if t in ROW_GROUP_TAGS:
+                yield from rows(ch)
+            elif t == "tr":
+                yield ch
+    return [c for tr in rows(el) for c in tr
+            if isinstance(c.tag, str) and c.tag.lower() in ("td", "th")]
+
+
+def _is_layout_table(el):
+    """A <table> used for page layout, not data: no <th> in its OWN cells, and at
+    least one own cell holds block-level content (a nested <table>, <div>, …).
+    Checks own cells only — a nested data table with <th> must not mask an outer
+    layout table."""
+    cells = _direct_cells(el)
+    if any(c.tag.lower() == "th" for c in cells):
+        return False
+    for c in cells:
+        if any(isinstance(d.tag, str) and d.tag.lower() in BLOCKISH_TAGS
+               for d in c.iterdescendants()):
+            return True
+    return False
+
+
+def _cell_text(el):
+    """Flatten a table cell (incl. any nested table) to one readable inline string,
+    dropping script/style subtrees; source = the cell's elements."""
+    parts, src = [], set()
+
+    def rec(node):
+        if isinstance(node.tag, str):
+            if node.tag.lower() in SKIP_TAGS:
+                return
+            src.add(node)
+        if node.text:
+            parts.append(node.text)
+        for c in node:
+            rec(c)
+            if c.tail:
+                parts.append(c.tail)
+
+    rec(el)
+    txt = COLLAPSE_RE.sub(" ", "".join(parts)).strip().replace("|", "\\|")
+    return txt, src
+
+
+class _Renderer:
+    """Accumulates output lines and, per line, the set of source elements."""
+
+    def __init__(self, render_hidden=False, links=False):
+        self.render_hidden = render_hidden
+        self.links = links
+        self.lines = []
+        self.line_src = []
+        self.buf = []
+        self.buf_src = []
+        self.linepfx = ""
+        self.pending = None
+        self.swallow = False
+        self.keep_lead = False
+        self.quote = 0
+        self.list_stack = []
+
+    def _qpfx(self):
+        return "> " * self.quote
+
+    def _append(self, line, src):
+        self.swallow = False
+        if self.pending is not None:
+            self.lines.append(self.pending); self.line_src.append(set())
+            self.pending = None
+        self.lines.append(line); self.line_src.append(src)
+
+    def flush(self):
+        if not self.buf:
+            return
+        src = {s for s in self.buf_src if s is not None}
+        self._append((self._qpfx() + self.linepfx + "".join(self.buf)).rstrip(), src)
+        self.buf = []; self.buf_src = []; self.linepfx = ""
+
+    def blank(self):
+        self.flush()
+        if not self.lines:
+            return
+        self.pending = self._qpfx().rstrip() if self.quote else ""
+
+    def emit(self, line, src):
+        """Emit a standalone line with an explicit source set."""
+        self.flush()
+        self._append(self._qpfx() + line, src if src else set())
+
+    def text(self, s, src):
+        if not s:
+            return
+        s = COLLAPSE_RE.sub(" ", s)
+        if self.swallow:
+            s = s.lstrip(" "); self.swallow = False
+            if not s:
+                return
+        if not self.buf and not self.keep_lead:
+            s = s.lstrip()
+            if not s:
+                return
+        self.buf.append(s); self.buf_src.append(src)
+
+    def raw(self, s, src):
+        self.buf.append(s); self.buf_src.append(src)
+
+    def children(self, el):
+        self.text(el.text, el)
+        for child in el:
+            self.walk(child)
+
+    def inner_keeping_lead(self, el):
+        prev = self.keep_lead; self.keep_lead = True
+        self.children(el); self.keep_lead = prev
+
+    def walk(self, el):
+        tag = el.tag
+        if not isinstance(tag, str):
+            return
+        tag = tag.lower()
+        style = el.get("style") or ""
+        hidden = ("display: none" in style or "display:none" in style) and not self.render_hidden
+        if tag in SKIP_TAGS or hidden:
+            pass                              # skip subtree; tail still renders below
+        elif tag == "br":
+            self.flush()
+        elif tag == "hr":
+            self.blank(); self.emit("* * *", {el}); self.blank()
+        elif tag in HEADING_TAGS:
+            self.blank()
+            self.linepfx = "#" * HEADING_TAGS[tag] + " "
+            self.inner_keeping_lead(el)
+            self.blank()
+        elif tag in LIST_TAGS:
+            self.list(el, tag)
+        elif tag == "li":
+            self.item(el)
+        elif tag == "blockquote":
+            self.blank(); self.quote += 1; self.children(el)
+            self.flush(); self.quote -= 1; self.blank()
+        elif tag == "pre":
+            self.pre(el)
+        elif tag == "table":
+            self.table(el)
+        elif tag == "dt":
+            self.flush(); self.children(el); self.flush()
+        elif tag == "option":                 # <select> options; own block each, else they glue
+            self.flush(); self.children(el); self.flush()
+        elif tag == "dd":
+            self.flush(); self.linepfx = "    "
+            self.inner_keeping_lead(el); self.flush()
+        elif tag in SIMPLE_BLOCK_TAGS:
+            self.blank(); self.children(el); self.blank()
+        elif tag in WRAP_TAGS:
+            open_s, close_s = WRAP_TAGS[tag]
+            inner = _sub_inline(el, self.render_hidden, self.links)
+            if inner:
+                self.raw(open_s + inner + close_s, el)
+            else:
+                self.swallow = True
+        elif tag == "a" and self.links and el.get("href"):
+            inner = _sub_inline(el, self.render_hidden, self.links)
+            if inner:
+                self.raw(f"[{inner}]({el.get('href')})", el)
+        elif tag == "img" and self.links and el.get("src"):
+            self.raw(f"![{el.get('alt', '')}]({el.get('src')})", el)
+        else:
+            self.children(el)                 # a, span, abbr, sectioning-inline, ...
+        # el.tail is stored on el and survives pruning iff el is kept, so it is
+        # el's provenance (not the parent's).
+        self.text(el.tail, el)
+
+    def list(self, el, kind):
+        self.flush()
+        try:
+            start = int(el.get("start", "1"))
+        except ValueError:
+            start = 1
+        self.list_stack.append([kind, start])
+        self.text(el.text, el)
+        for child in el:
+            ctag = child.tag if isinstance(child.tag, str) else ""
+            if ctag.lower() == "li":
+                self.item(child)
+            else:
+                self.walk(child)
+        self.list_stack.pop()
+        self.flush(); self.blank()
+
+    def item(self, el):
+        self.flush()
+        depth = max(len(self.list_stack), 1)
+        indent = "  " * (depth - 1)
+        if self.list_stack and self.list_stack[-1][0] == "ol":
+            n = self.list_stack[-1][1]; self.list_stack[-1][1] = n + 1
+            self.linepfx += f"{indent}{n}. "
+        else:
+            self.linepfx += f"{indent}- "
+        self.children(el)
+        self.flush()
+
+    def pre(self, el):
+        self.blank()
+        self._append("```", {el})
+        for line in el.text_content().split("\n"):
+            self._append(line, {el})
+        self._append("```", {el})
+        self.blank()
+
+    def table(self, el):
+        def rows(node):
+            for child in node:
+                ctag = child.tag if isinstance(child.tag, str) else ""
+                if ctag in ROW_GROUP_TAGS:
+                    yield from rows(child)
+                elif ctag == "tr":
+                    yield child
+        if _is_layout_table(el):
+            self.blank()
+            for tr in rows(el):
+                for c in tr:
+                    if isinstance(c.tag, str) and c.tag.lower() in ("td", "th"):
+                        self.blank(); self.children(c); self.blank()
+            self.blank()
+            return
+        self.blank()
+        first = True
+        for tr in rows(el):
+            cells = [c for c in tr if isinstance(c.tag, str)
+                     and c.tag.lower() in ("td", "th")]
+            if not cells:
+                continue
+            texts, src = [], {tr}
+            for c in cells:
+                t, s = _cell_text(c)
+                texts.append(t); src |= s
+            if not any(texts):                 # skip fully-empty rows
+                continue
+            self.emit("| " + " | ".join(texts) + " |", src)
+            if first:
+                self.emit("| " + " | ".join(["---"] * len(cells)) + " |", src)
+                first = False
+        self.blank()
+
+
+def _sub_inline(el, render_hidden=False, links=False):
+    sub = _Renderer(render_hidden, links); sub.children(el); sub.flush()
+    return " ".join(ln.strip() for ln in sub.lines if ln.strip())
+
+
+def render_tree(root, render_hidden=False, links=False):
+    """Walk a parsed tree -> (lines, line_src). line_src[i] is the set of source
+    DOM elements that produced line i (empty for structural separators).
+
+    render_hidden keeps display:none subtrees instead of skipping them. Default
+    off — a reference built by a pruner that also skips display:none stays
+    symmetric with the render. A reference captured from a hydrated DOM sets it
+    on, so hydration-hidden main content is rendered.
+
+    links=True renders <a>/<img> as markdown ([text](href), ![alt](src)) -- an
+    output-only mode. The model-input render keeps links=False (link-flattened) so
+    training still matches; only serialization sets links=True."""
+    r = _Renderer(render_hidden, links); r.walk(root); r.flush()
+    return r.lines, r.line_src
+
+
+def render(html_str, render_hidden=False, links=False):
+    """HTML string -> readable markdown text (inference; provenance discarded).
+    Does not sanitize — a caller that needs it sanitizes the tree first."""
+    if not html_str or not html_str.strip():
+        return ""
+    lines, _ = render_tree(parse(html_str), render_hidden, links)
+    return "\n".join(lines) + "\n"

htmlsift/core/tokenizer.py

@@ -0,0 +1,38 @@
+"""Adapter: a `tokenizers.Tokenizer` presented with the transformers fast-tokenizer
+call shape that `prep_page` expects, so the default install tokenizes with the small
+`tokenizers` library and needs no `transformers` or `torch`.
+
+`prep_page` calls the tokenizer as
+`tok(text, add_special_tokens=True, return_offsets_mapping=True,
+ return_special_tokens_mask=True, ...)` and reads `input_ids`, `offset_mapping` and
+`special_tokens_mask` off the result. The `tokenizers` library carries the same
+information on its `Encoding` object under different names, so this wraps the two up.
+"""
+from tokenizers import Tokenizer
+
+
+class FastTokenizer:
+    """A `tokenizers.Tokenizer` callable like a transformers fast tokenizer:
+    `tok(text)` -> `{"input_ids", "offset_mapping", "special_tokens_mask"}`.
+
+    Truncation and padding are disabled so a long page reaches the encoder windowing
+    intact -- `prep_page` windows the sequence, the tokenizer must never cut it. The
+    special-token post-processor and normalizer baked into `tokenizer.json` are
+    applied by `encode`, so the ids, offsets and mask match what the model was
+    trained on."""
+
+    def __init__(self, tk):
+        tk.no_truncation()
+        tk.no_padding()
+        self._tk = tk
+
+    @classmethod
+    def from_file(cls, path):
+        """Load `tokenizer.json` at `path` -- the single self-contained tokenizer file."""
+        return cls(Tokenizer.from_file(str(path)))
+
+    def __call__(self, text, add_special_tokens=True, **_ignored):
+        enc = self._tk.encode(text, add_special_tokens=add_special_tokens)
+        return {"input_ids": enc.ids,
+                "offset_mapping": enc.offsets,
+                "special_tokens_mask": enc.special_tokens_mask}

htmlsift/core/torch_infer.py

@@ -0,0 +1,165 @@
+"""Torch backend for the base model: build the truncated granite encoder from a baked
+config (no backbone download), pool block token states, run the BiGRU head. The
+inference forward (pool / stitch / encode_window / pool_page / infer_page) is byte-
+equivalent to the research original; construction uses AutoModel.from_config so the
+package never pulls granite.
+
+Entry point: load_base(...) -> infer_fn, the torch mirror of onnx_infer.load_mini.
+"""
+import warnings
+from pathlib import Path
+
+import numpy as np
+import torch
+import torch.nn as nn
+from transformers import AutoConfig, AutoModel
+
+from .features import feature_dim
+from .prep_page import window_starts
+
+
+def build_encoder(config, device="cpu", attn="sdpa"):
+    """Build the base encoder from a baked (already layer-truncated) config and give it
+    the fresh final LayerNorm the trained weights expect. from_config -- not
+    from_pretrained -- so no granite backbone is downloaded; the weights are loaded by
+    load_base."""
+    model = AutoModel.from_config(config, attn_implementation=attn)
+    model.final_norm = nn.LayerNorm(model.config.hidden_size, eps=1e-5)
+    return model.to(device)
+
+
+class BiGRUHead(nn.Module):
+    """Per-block head: pooled block vectors [1, n, d_in] -> per-block logits [1, n]."""
+
+    def __init__(self, d_in, hidden=256, dropout=0.2):
+        super().__init__()
+        self.gru = nn.GRU(d_in, hidden, num_layers=1, bidirectional=True, batch_first=True)
+        self.drop = nn.Dropout(dropout)
+        self.out = nn.Linear(2 * hidden, 1)
+
+    def forward(self, x, mask=None):
+        h, _ = self.gru(x)
+        return self.out(self.drop(h)).squeeze(-1)
+
+
+def build_head(kind, d_in, hidden=256, dropout=0.2):
+    """The base model ships the BiGRU head only."""
+    if kind == "bigru":
+        return BiGRUHead(d_in, hidden=hidden, dropout=dropout)
+    raise ValueError(f"unknown head {kind!r}; the package ships 'bigru' only")
+
+
+def pool(hidden, members, b_lo, b_hi, tok_off):
+    """Mean-pool encoder states hidden [w, H] into per-block vectors [b_hi-b_lo, H].
+    members hold page-level token indices; tok_off is the page index of hidden[0], so
+    m - tok_off is the window-local row. A block with no tokens pools to a zero vector."""
+    dev = hidden.device
+    blocks = members[b_lo:b_hi]
+    lengths = np.fromiter((len(m) for m in blocks), np.int64, len(blocks))
+    counts = torch.tensor(np.maximum(lengths, 1), device=dev,
+                          dtype=hidden.dtype).unsqueeze(1)
+    pooled = hidden.new_zeros((b_hi - b_lo, hidden.shape[1]))
+    if lengths.sum():
+        mem_idx = np.concatenate([np.asarray(m, np.int64) for m in blocks if m]) - tok_off
+        blk_idx = np.repeat(np.arange(len(blocks), dtype=np.int64), lengths)
+        pooled = pooled.index_add(0, torch.from_numpy(blk_idx).to(dev),
+                                  hidden[torch.from_numpy(mem_idx).to(dev)])
+    return pooled / counts
+
+
+def cat_feats(x, feats, b_lo, b_hi):
+    """Concatenate per-block feature columns onto pooled vectors x [n, H] -> [n, H+K].
+    No-op when feats is None (base is text-only)."""
+    if feats is None:
+        return x
+    f = torch.as_tensor(feats[b_lo:b_hi], dtype=x.dtype, device=x.device)
+    return torch.cat([x, f], dim=1)
+
+
+def stitch_bounds(starts, window, k):
+    """Window-local [lo, hi) slice window k owns under most-interior ownership: each
+    token goes to the window whose centre is nearest. Used by the encoder stitch, so
+    the ownership rule lives in one place."""
+    s = starts[k]
+    lo = 0 if k == 0 else (starts[k - 1] + window + s) // 2 - s
+    hi = window if k == len(starts) - 1 else (s + window + starts[k + 1]) // 2 - s
+    return lo, hi
+
+
+def encode_window(encoder, ids_t, autocast):
+    """Encode a 1-D token window -> hidden states [w, H] (fp32). bf16 autocast on the
+    forward when enabled (CUDA); a no-op on CPU."""
+    with torch.autocast("cuda", dtype=torch.bfloat16, enabled=autocast):
+        h = encoder(input_ids=ids_t[None],
+                    attention_mask=torch.ones_like(ids_t)[None]).last_hidden_state[0]
+    return h.float()
+
+
+@torch.no_grad()
+def pool_page(encoder, page, dev, autocast):
+    """Full-page pooled block vectors [n_blocks, H]. A page within its window encodes in
+    one pass; a longer page encodes in overlapping windows stitched by most-interior
+    ownership, then the whole page is pooled. window/stride come from the page."""
+    window, stride = page["window"], page.get("stride")
+    ids = torch.from_numpy(page["ids"]).to(dev)
+    n = len(ids)
+    if n <= window:
+        hidden = encode_window(encoder, ids, autocast)
+    else:
+        hidden = torch.full((n, encoder.config.hidden_size), float("nan"), device=dev)
+        starts = window_starts(n, window, stride)
+        for k, s in enumerate(starts):
+            h = encode_window(encoder, ids[s:s + window], autocast)
+            lo, hi = stitch_bounds(starts, window, k)
+            hidden[s + lo:s + hi] = h[lo:hi]
+        assert not torch.isnan(hidden).any(), f"stitch gap {page['tid']}"
+    return pool(hidden, page["members"], 0, len(page["members"]), 0)
+
+
+@torch.no_grad()
+def infer_page(encoder, head, page, dev, autocast):
+    """Full-page inference -> per-block probs (np.float32): pool the page, concat any
+    features, run the head."""
+    x = pool_page(encoder, page, dev, autocast)
+    x = cat_feats(x, page.get("feats"), 0, len(page["members"]))
+    probs = torch.sigmoid(head(x[None])[0])
+    return probs.float().cpu().numpy()
+
+
+def load_base(config_path, weights_path, hidden, feats=None, device=None,
+              band=True, threads=None):
+    """Load the base bundle into an infer_fn (page -> per-block probs) -- the torch
+    mirror of onnx_infer.load_mini. Build the architecture from the baked config, load
+    the trained encoder + head weights, optionally enable band attention, and close over
+    the forward. `hidden` is the BiGRU head hidden size; `feats` the feature group (base
+    is text-only -> None). No granite download.
+
+    device=None auto-selects cuda when a GPU is present, else cpu -- and warns on the
+    cpu fallback, so a silent CPU run can't pass for a GPU one. An explicit "cuda" with
+    no GPU is a clear error rather than a cryptic failure deeper in torch."""
+    if device is None:
+        device = "cuda" if torch.cuda.is_available() else "cpu"
+        if device == "cpu":
+            warnings.warn(
+                "htmlsift: base defaulting to CPU (no CUDA device found); "
+                "pass device='cpu' to silence, or device='cuda' to require GPU",
+                stacklevel=2)
+    dev = torch.device(device)
+    if dev.type == "cuda" and not torch.cuda.is_available():
+        raise ValueError(f"device={device!r} requested but no CUDA device is available")
+    if threads and dev.type == "cpu":
+        torch.set_num_threads(threads)
+    config = AutoConfig.from_pretrained(str(Path(config_path).parent))
+    enc = build_encoder(config, device=dev)
+    head = build_head("bigru", d_in=enc.config.hidden_size + feature_dim(feats),
+                      hidden=hidden).to(dev)
+    state = torch.load(weights_path, map_location=dev, weights_only=True)
+    enc.load_state_dict(state["encoder"])
+    enc.eval()
+    head.load_state_dict(state["head_state"])
+    head.eval()
+    if band:
+        from . import band as band_mod
+        band_mod.enable(enc)
+    autocast = dev.type == "cuda"
+    return lambda page: infer_page(enc, head, page, dev, autocast)

htmlsift/extractor.py

@@ -0,0 +1,91 @@
+"""The public extractor: HTML in, main content out. Holds a lazily-loaded Model and
+runs one pipeline per call -- parse, render to lines, score each line, keep the lines
+over threshold, serialize. Mirrors the research inference front-end (render_blocks +
+prep_page + threshold); no sanitize step.
+"""
+import numpy as np
+
+from .core.prep_page import prep_page
+from .core.prune import prune, to_html
+from .core.render import parse, render_tree
+from .loader import load_model
+
+THRESHOLD = 0.5
+
+
+def _selected_srcs(block_src, probs):
+    """DOM elements behind the blocks scoring over threshold (union, in order)."""
+    return [el for src, p in zip(block_src, probs, strict=True) if p > THRESHOLD for el in src]
+
+
+class Extractor:
+    """Main-content extractor for one mode. The model loads on the first extract() call
+    and is reused, so create one Extractor and call it many times."""
+
+    def __init__(self, mode="mini", *, bundle_dir=None, threads=None, device=None):
+        self.mode = mode
+        self._bundle_dir = bundle_dir
+        self._threads = threads
+        self._device = device
+        self._model = None
+
+    @property
+    def model(self):
+        if self._model is None:
+            self._model = load_model(self.mode, bundle_dir=self._bundle_dir,
+                                     threads=self._threads, device=self._device)
+        return self._model
+
+    def extract(self, html, output="text", with_blocks=False):
+        """Extract main content from an HTML string.
+
+        output="text" joins the selected lines; output="html" prunes the DOM to the
+        selected blocks (structure, links, images kept) and serializes. with_blocks=True
+        returns (blocks, probs) -- every block and its probability, unthresholded."""
+        root, blocks, block_src, probs = self._predict(html)
+        if with_blocks:
+            return blocks, probs
+        if output == "text":
+            return "\n".join(b for b, p in zip(blocks, probs, strict=True) if p > THRESHOLD)
+        if output == "html":
+            selected = _selected_srcs(block_src, probs)
+            return to_html(root, selected) if selected else ""
+        if output == "markdown":
+            selected = _selected_srcs(block_src, probs)
+            if not selected:
+                return ""
+            prune(root, selected)
+            lines, _ = render_tree(root, links=True)
+            return "\n".join(lines).strip("\n")
+        raise ValueError(f"unknown output {output!r}; expected 'text', 'html', or 'markdown'")
+
+    def _predict(self, html):
+        """html -> (root, blocks, block_src, probs). blocks are the rstripped non-empty
+        render lines; block_src[i] the DOM elements behind block i. Empty page ->
+        (None, [], [], empty array)."""
+        if not html or not html.strip():
+            return None, [], [], np.empty(0, dtype=np.float32)
+        root = parse(html)
+        lines, line_src = render_tree(root)
+        blocks, block_src = [], []
+        for ln, src in zip(lines, line_src, strict=True):
+            if ln.strip():
+                blocks.append(ln.rstrip())
+                block_src.append(src)
+        if not blocks:
+            return root, [], [], np.empty(0, dtype=np.float32)
+        feats = self.model.features(lines, line_src)          # on RAW lines
+        page = prep_page(self.model.tok, blocks, self.model.window,
+                         cap=self.model.cap, feats=feats)
+        return root, blocks, block_src, self.model.infer_fn(page)
+
+
+_CACHE = {}
+
+
+def extract(html, mode="mini", output="text", with_blocks=False):
+    """Module-level convenience: extract with a per-mode cached Extractor."""
+    ex = _CACHE.get(mode)
+    if ex is None:
+        ex = _CACHE[mode] = Extractor(mode)
+    return ex.extract(html, output=output, with_blocks=with_blocks)