feat(omml): add OMML equation extraction utility for DOCX documents (closes #259)

[Abdeltoto]

Summary

Closes #259.

Adds raganything/omml_extractor.py, a zero-dependency, pure-stdlib utility that extracts OMML (Office Math Markup Language) equations from .docx files and converts them to LaTeX, so the structured math content survives the DOCX → PDF conversion that both the MinerU and Docling parsers rely on.

Why

Word stores inline and display math as <m:oMath> elements inside word/document.xml. When a DOCX is ingested today, both parsers convert it to PDF first (LibreOffice for MinerU, native conversion for Docling). During that conversion, equations are typically rasterized to images or replaced with placeholder glyphs — the structured math text is lost before it ever reaches EquationModalProcessor. This silently degrades retrieval quality for academic papers, lecture notes, and engineering reports — exactly the workloads where structured math matters most.

See #259 for the full motivation and the proposed approach.

What this PR adds

Two public functions and one transformer:

• extract_omml_equations(docx_path) — opens the DOCX as a ZIP, parses word/document.xml with xml.etree, walks every <m:oMath> element in document order, and returns a list of dicts with text (LaTeX), text_format, index, and raw_omml (the source XML, useful for callers that want to plug in their own converter).

• enrich_content_list_with_docx_equations(content_list, docx_path) — takes a parsed MinerU-compatible content list and appends {"type": "equation", "text": "<latex>", "text_format": "latex", ...} blocks for each extracted equation. Deduplicates against equations already present in the list (e.g. those the parser already produced as image placeholders) by default.

• omml_to_latex(element) — recursive transformer covering the most common OMML constructs: runs (m:r/m:t), fractions (m:f), super/subscripts (m:sSup/m:sSub/m:sSubSup/m:sPre), radicals (m:rad), n-ary operators (m:nary with the standard sum/prod/integral characters), applied functions (m:func, with whitelist for \sin, \cos, \log, etc.), delimiters (m:d), matrices (m:m), accents (m:acc, m:bar), limits (m:limLow/m:limUpp), grouping characters (m:groupChr), and phantoms (m:phant). Unknown elements gracefully fall back to their text content rather than raising — for RAG indexing, recall beats fidelity.

Tests

tests/test_omml_extractor.py covers 26 cases, all passing locally:

• Direct OMML → LaTeX conversion for every supported construct (fractions, sup/sub, radicals, summation with bounds, integrals with default operator, known and unknown functions, delimiters with default and explicit braces, 2×2 matrices, overline/underline, Unicode symbol substitution).
• End-to-end extraction from in-memory DOCX archives built with zipfile (single equation, multiple equations preserve document order).
• Enrichment behavior: append, deduplicate against existing equations, opt-out of dedup, empty input returns a defensive copy.
• Error handling: missing file → FileNotFoundError, non-ZIP → ValueError, ZIP missing word/document.xml → ValueError.

All 26 tests pass with the stdlib alone — no python-docx, no lxml, no pandoc.

Backward compatibility

• New module — no changes to existing parsers or processors.
• Strictly opt-in: callers explicitly invoke extract_omml_equations() or enrich_content_list_with_docx_equations().
• Output dicts use the same schema as existing equation blocks, so they slot into EquationModalProcessor without code changes anywhere else.
• No new required dependencies.

Out of scope (possible follow-ups)

• Positional placement: DOCX paragraphs do not carry page numbers, so this PR appends extracted equations at the tail of the content list with the last block's page_idx. Precise positional weaving could be a follow-up using raw_omml as a join key against parser-produced image placeholders.
• Auto-integration into process_document_complete() for .docx inputs — deliberately punted to a second PR so the utility lands first and can be reviewed in isolation.

Test plan

• All 26 unit tests pass locally on Python 3.12 / Windows.
• ruff format and ruff check --ignore=E402 pass on the new files.
• Maintainer-side: try it on a real .docx with mixed inline and display math and confirm the LaTeX is searchable inside the resulting knowledge graph.

Note: the test file is added with git add -f because .gitignore includes a broad test_* pattern that would otherwise hide it; the existing tests/test_*.py files are tracked the same way, so this matches the established convention.

[LarFii]

Thanks for the detailed implementation. The opt-in utility direction makes sense, but I found a few issues that should be addressed or explicitly documented before merge.

1. P1: several OMML conversion paths can crash on malformed or partial OMML. For example, fraction/script/radical helpers call child conversion even when a required child like num or e is missing. Since the extractor is intended to prefer recall and tolerate imperfect documents, these should return an empty string / fallback text rather than raising from _convert_children(None).

2. P1: unknown m:nary operators appear to fall back to \int. That silently turns an unsupported operator into an integral, which is worse than preserving the original Unicode/operator text for retrieval. Please preserve the unknown operator or use an explicit unknown placeholder instead of defaulting to integral.

3. P1/P2: deduplicate_existing_equations is exact-text-only. That is fine for an opt-in utility, but it will not deduplicate parser-produced formula placeholders or image-derived equations from Docling/MinerU. Please document that limitation clearly, or add a test showing the expected behavior when existing equation blocks contain non-LaTeX placeholder text.

4. P2: all appended equations inherit the last content block's page_idx and are appended at the end. Please document this as a known limitation so users do not treat page-level filtering/order as precise for the enriched equations.

The overall approach is useful, and I would be happy to re-review after the crash path and unknown n-ary fallback are fixed or covered by tests/limitations.

[Abdeltoto]

Thanks @LarFii — addressed all four:

1. _convert_children now tolerates None, so fraction/script/radical handlers degrade to "" on missing children instead of crashing.
2. _h_nary preserves the original Unicode character when m:chr is unknown (was silently rewritten to \int). Default-to-\int kept for the no-chr case per ECMA-376 §22.1.2.74.
3. & 4. Added a Limitations block to the enrich helper docstring covering exact-text dedup scope and the tail-append / inherited page_idx.

A few small tests added for the new fallbacks.