Why every PPTX extractor shreds your slides, and how Kerf fixes it

Imagine your PowerPoint extractor reports 100% text recall and still delivers unusable results. That is exactly what happens with multi-column layouts: every tool sorts shapes by position, top to bottom and left to right, by default. On a four-column card layout that means every heading is separated from its body text. The result is formally complete and semantically destroyed.

The numbers are sobering. Established PowerPoint extraction consistently achieves full text recall, yet fails on 7 of 16 layout blocks. Worse still, naive python-pptx implementations lose every single table, silently and without an error message.

Kerf solves this with a recursive XY-cut algorithm that operates directly on the exact XML geometry of the slide rather than on pixel projections. This article analyses why conventional extractors fail structurally, how Kerf's algorithm works in detail, what the benchmark results against MarkItDown, Docling and Unstructured show, and where the honest limits of the approach lie.

The problem in numbers: 100% text recall, 56% layout recall

Every mature extractor measured in this benchmark achieves close to 100% text recall. That sounds like a solved problem. It is not.

The measure that actually matters is structural integrity: do content blocks that belong together stay together? Of 16 measured multi-column regions, only 9 remained correctly grouped. That is 56%. The other half of the content blocks is textually complete but semantically torn apart.

Why classical sorting fails. The same position-sort algorithm that works on bulleted slides separates every heading from its body on four-column layouts. The extracted text contains all the words, but the mapping from heading to body is wrong.

The template illusion. The dangerous implication of these results lies in the distribution of the test corpus. Across eleven internal templated decks, shape insertion order and visual reading order disagreed on zero slides. Templated decks are structurally benign, because slide authors insert shapes in the order they are meant to appear visually.

On a single hand-designed pitch deck, the two orders diverged on 47% of slides. That is not an edge case. Hand-designed pitch decks and one-page summaries are precisely the documents that are densest in content and most relevant to decisions. Anyone who validates their pipeline on internal templated decks gets a false sense of security that collapses on the one deck that actually matters.

For teams preparing board meeting materials and generating decision-ready briefings from them, this is concrete: a RAG system or search index working on incorrectly grouped chunks delivers answers that are textually correct but contextually wrong. No error is thrown. The pipeline reports success.

Silent failures: how naive python-pptx implementations lose every table

The layout problem mainly affects hand-designed decks. The table problem affects every dataset, regardless of design.

PowerPoint stores tables as graphicFrame elements in the shape tree, not as regular <sp> shapes with a text_frame. Code that iterates over shape.text_frame skips every graphicFrame without comment. No AttributeError, no log entry, no warning. The output looks complete. It is not.

In the measured test corpus that means 0 of 103 table rows are recovered by naive python-pptx implementations. The loss stays invisible until a user asks the index for a figure and gets no answer.

This failure type is structurally more dangerous than a crash. A crash stops the pipeline and forces an investigation. A silent failure returns results that the system treats as correct. Downstream components, whether vector index, retrieval system or AI assistant, have no way of detecting that an entire content type is missing.

officeparser shows the same pattern. Despite 100% text recall and very competitive performance at 1.1 ms per slide, its table recovery is also 0 of 103 rows. Speed is not a quality metric when structurally critical content is systematically missing.

This is especially problematic because tables often contain exactly the content users actively query: budget figures, project milestones, competitive comparisons, quarterly metrics. A search system that indexes text correctly but loses tables entirely fails on a disproportionately important part of the content without producing a single error message.

What is Kerf and where does the name come from?

The failures described share a common cause: no existing general-purpose extraction tool was built with the goal of reconstructing the visual geometry of a slide. Kerf was built for exactly that purpose.

The name is a precise technical metaphor. A kerf is the width of the cut a saw blade leaves in the material. In the algorithmic context this carries over directly: every decision the algorithm makes concerns the width of the whitespace corridor along which a slide is split. The widest corridor determines the primary axis of division. The choice of name is not marketing but a description of the core operation.

Implementation and scope. Kerf consists of two components with a shared behavioural guarantee. The TypeScript package is around 1,050 lines and depends only on fflate and @xmldom/xmldom. The Python reference implementation is 480 lines and builds on python-pptx. A conformance test enforces byte-identical output from both implementations on every test deck. Anyone who develops in Python and later moves to Node gets identical results.

Installation and requirements. Kerf is consumed as a private GitHub git dependency. It is available on neither npm nor PyPI.

API surface. The CLI accepts kerf deck.pptx --report and emits Markdown with an optional diagnostic report. The convert() API takes a path or bytes directly. For slides where the algorithm cannot reconstruct a reliable layout, an onUncertain hook is available; it is covered in a later section.

Why Quorum Tech built it. Kerf is an internal tool at Quorum Tech. The company runs a system that automatically turns company documents into personalised short podcasts for meeting participants. Presentations are a central source document format in that process. If an extraction error silently discards a table row or a card block, that error propagates directly into the audio output without any error being reported. Precise, layout-aware extraction is not an optional quality tier there but a functional baseline requirement.

How Kerf works: recursive XY-cut on exact XML geometry

The algorithmic core is the recursive XY-cut, a top-down segmentation method that divides a page into regions through successive horizontal and vertical cuts. The decisive difference from the classical application: Kerf operates on exact bounding-box coordinates from the slide XML, not on pixel projections of scanned images. That eliminates quantisation errors and makes the method deterministic.

Cut direction by whitespace width. In each region the algorithm looks for the proportionally widest corridor of empty space, horizontal or vertical, and cuts there. The widest corridor defines the primary level of structure. This is the direct geometric counterpart of the name: the kerf, the widest cut, determines the structure.

Extensions over the classical algorithm:

- Group transforms. Nested group coordinates are mapped into slide space before the geometry is used.

- Placeholder geometry. Size and position are inherited from the layout and master slide when a placeholder declares no geometry of its own.

- Grid classifier. Distinguishes self-contained card layouts from faux tables assembled from individual text boxes.

The fallback is not a defeat. On the real pitch deck the document-order fallback produced significantly more correct block assignments than position-based sorting. Deck authors typically insert the shapes of a card together, so insertion order reflects content grouping better than geometric position does.

Output structure. The generated Markdown follows a fixed hierarchy: slides as ## Slide N, title placeholders as ###, prominent labels as ####, tables and chart series as Markdown tables, speaker notes as block quotes. Image alt text and hidden slides are included. This structure is not configurable but deliberately normalised, so that downstream chunkers can rely on a stable schema.

Uncertain slides: the onUncertain hook and the layout-uncertain marker

The XY-cut algorithm presupposes something that is not always present: a measurable whitespace corridor between geometrically separate regions. Stacked animation builds and slides with genuinely overlapping layouts do not meet that condition. There is no consistent cut line, and a forced cut would separate elements that belong together.

Kerf detects this situation and falls back to document order instead of delivering a faulty segmentation. The slide is explicitly marked as uncertain: a <!-- layout-uncertain --> comment appears in the Markdown output directly at the affected slide. A downstream chunker can act on this signal, for instance by indexing the corresponding vector with lower confidence, pushing the slide into a manual review queue, or excluding it from the index entirely. The rest of the pipeline continues unchanged.

For cases where document order is not enough, the onUncertain hook offers an opt-in extension. The hook can render the slide to PNG via LibreOffice and hand the image to a vision model that interprets the reading order visually. This is not the default path; it requires a LibreOffice installation and is only activated when the integrating system explicitly configures it. Anyone who does not want to run LibreOffice still gets the flagged fallback output.

This design is a deliberate acknowledgement of the algorithmic limit. Programmatic segmentation without visual information only works when the geometry carries a clear structure. Where it does not, an honestly flagged result is more informative than a silent, faulty one.

The combination of marker and hook gives the integrating system three options: ignore, review manually, or delegate to a vision model. None of these requires changes to the core conversion; <!-- layout-uncertain --> is the handover point between what Kerf solves reliably and what the downstream system has to decide.

Benchmark results: all methods compared

Measured on 2 September 2026 on 12 real decks (124 slides, 103 table rows, 16 layout blocks) plus 13 synthetic edge-case decks. All speed figures are best of three runs on an M-series Mac.

* Document-order methods pass authored decks by construction.

Kerf is the only method with a perfect score on all three core dimensions at once. The scores do not separate on text recall; they separate on table rows and layout blocks.

MarkItDown is a solid default choice for many pipelines. At 99.9% text recall, complete table recovery and 1.8 ms per slide, the gap to Kerf is small. Anyone processing mainly templated decks without complex multi-column layouts will rarely notice the difference in layout blocks (9/16 versus 16/16).

Docling reaches the same scores as MarkItDown but costs 6.1 ms per slide, four times slower. In addition, Docling escapes Markdown special characters in a way that can impair exact-match search.

Unstructured sits at 17.8 ms per slide, roughly ten times slower than Kerf, delivers no chart data and no speaker notes, and recovers only 97 of 103 table rows.

LibreOffice + pdftotext costs around 1,400 ms per slide, loses a quarter of all table rows (79/103) and preserves only 6 of 16 layout blocks. The rendering detour is slow and inaccurate at the same time.

Both document-order methods (officeparser, python-pptx naive) deliver 0/103 table rows, with no error and no warning, as described in the previous section.

From 8 to 13 edge cases: what the v2 fixes delivered

The benchmark table shows the current state; the development history behind it is just as relevant for use in real pipelines.

An earlier version passed 8 of 13 synthetic edge-case decks. The five failures traced back to concrete algorithmic gaps: missing group transforms left nested group coordinates mapped incorrectly into slide space, incorrectly inherited placeholder geometry produced wrong bounding boxes on layouts with master overrides, overly aggressive shrinking broke apart non-overlapping shapes unnecessarily, and the missing grid classifier left card layouts indistinguishable from flat collections of text boxes.

The v2 fixes, group transforms, background-shape exclusion, overlap-only shrinking, tolerant gaps, grid classifier and document-order flagging (all described in the algorithm section), brought the score to 13/13 edge cases.

Not a single result on the 12 real decks changed. That is the statement that actually matters: the fixes closed gaps without destabilising existing correct output.

Speed stayed at 1.5 ms per slide. That is not a given. Each of the six additions could have introduced runtime cost. They did not, because all extensions are per-slide geometric precomputations, not iterative passes over the entire shape graph.

The grid classifier deserves separate mention. It distinguishes card layouts, where each cell is self-contained, from faux tables assembled from freely placed text boxes. On the real test corpus it produced no false positives. Its recall on slides with genuine faux-table structures, however, has not been measured. Anyone processing decks with many such constructions should treat that as an open variable.

The progression from 8/13 to 13/13 illustrates the validation strategy: synthetic decks were built deliberately to isolate known failure modes. Each fix was then re-tested against the real decks. No regression, no performance loss.

Security and engineering: hardened parsing for untrusted uploads

The algorithmic fixes in v2 were developed under the premise that Kerf runs in upload endpoints and processes untrusted files there. The security architecture is designed explicitly for that, not bolted on afterwards.

Zip bombs and decompression attacks are neutralised by limits that are active by default. A compressed PPTX that exceeds these limits is rejected before any significant amount of memory is allocated. Kerf also decompresses only the zip parts it actually reads; there is no full extraction of the archive up front. A zipFilter hook allows an upstream upload endpoint to apply its own filtering policy before Kerf touches the content at all. Which file types and sizes an endpoint accepts is described in the documentation.

CPU exhaustion through pathological input is addressed by a separate limit: slides with an unusually large number of shapes skip the quadratic overlap pass and are marked as uncertain. The overlap pass has quadratic complexity in the number of shapes; on artificially inflated slides it would bring processing to a standstill without this cap.

XXE attacks are relevant to any library that parses XML from user data. Office Open XML is XML-based. Kerf never resolves XML entities and never fetches external entities. This restriction is not configurable, to rule out accidental deactivation.

Known limits: what Kerf cannot do

No tool is without limits, and Kerf names its own explicitly.

XY-cut needs a geometrically clear whitespace corridor. Slides with stacked animation builds, where several shapes occupy the same position, or with genuinely overlapping layouts cannot be segmented reliably. Where these limits apply, the onUncertain hook (see Uncertain slides) remains the recommended strategy.

The grid classifier produced no false positives on the test corpus, but its recall on real faux tables assembled from text boxes has not yet been measured. Anyone processing decks that regularly contain such pseudo-tables should validate this gap against a representative sample of their own corpus before production use.

Chart categories from numeric caches are read as stored text. If a chart does not hold its category labels in the expected XML form, those categories are lost. This does not affect charts with explicitly stored text categories, only those where PowerPoint reconstructs the labels from a numeric cache.

These three limits are named in the documentation, not hidden between the lines. A serious evaluation for a specific pipeline has to weigh them against the actual deck corpus: how many slides contain genuinely overlapping layouts? How often do faux tables occur? Which chart types dominate?

Governance: hidden slides and speaker notes in the index

Technical limits can be cushioned with fallbacks. Governance questions cannot.

Every method tested in the benchmark extracts hidden slides. Kerf additionally extracts speaker notes. Deck authors generally do not expect either to show up in a search index or an AI assistant.

What sits in those areas is rarely harmless. Speaker notes often contain discussion guides, internal escalation strategies or negotiating positions that were explicitly not intended for an audience. In a RAG system they could be quoted in response to a user query without the original authors ever having intended that. Hidden slides frequently contain withdrawn scenarios, outdated figures or internal comments that were deliberately removed from a pitch. Silently indexing them reverses that decision without warning.

The risk lies not in the extraction behaviour itself but in adopting it unquestioned. The decision on whether speaker notes and hidden slides should flow into an index or an AI assistant must be made deliberately and documented. Anyone who understands what is indexed and what is not can draw that line; anyone who feeds an extractor's default output straight into a pipeline implicitly delegates the decision to the tool.

Kerf makes speaker notes visible in the Markdown output as block quotes. That is not suppression but marking: anyone who wants to exclude them removes block quotes in post-processing or configures the chunker accordingly. For pipelines where the processing status of individual content types must be traceable, this filterability is a prerequisite, not a convenience.

The governance question is the same for every method tested. Kerf is simply the only tool that makes it visible through its output structure.

Conclusion: when Kerf is the right choice

The governance decision is the last organisational step before deployment. What follows is a technical trade-off.

MarkItDown remains a solid choice for template-heavy corpora without complex multi-column layouts (99.9% text recall, 1.8 ms per slide).

Kerf is the right choice when all three dimensions count at once: 103/103 table rows, 16/16 layout blocks and under 2 ms per slide. On the benchmark of 2nd of September 2026 it is the only method that reaches that combined score. The decisive indicator in your own corpus: if hand-designed decks or pitch decks are part of it, there is a high probability that shape insertion order and visual reading order diverge on a substantial share of slides.

The three known limits, overlapping layouts, unmeasured faux-table recall and numeric chart caches, are laid out in the Known limits section and should be assessed against your own corpus.

The governance question on speaker notes and hidden slides (see the Governance section) must be decided and documented before indexing.

For teams that automatically feed presentation content into downstream systems, one basic principle applies: an extraction error without an error message is more expensive than one with. Silent data loss in the extraction layer, whether missing table rows or wrongly grouped layout blocks, propagates unnoticed through the entire pipeline and degrades the quality of every output based on that data. The choice of extractor is therefore not a peripheral decision