Adeu: The Virtual DOM for Word Redlines

How this docx-to-Markdown bridge lets LLMs edit contracts safely, preserve formatting, and write native Track Changes back into Microsoft Word.

8 to 10 min read • View on GitHub • More from dealfluence

A formal contract page is suspended above a lattice of document nodes and XML gears while a hand writes Markdown notes on a clean pad below. A thin bridge carries edits between the two layers, explaining how Adeu translates model-friendly text into Word-native redlines without flattening the document. — Adeu is not a file converter. It is a bridge that lets LLMs work in a Markdown-shaped space and then return changes to Word as native tracked edits.

Key Takeaways

Adeu treats redlining as a two-way transaction, not a one-way conversion, which is why it can preserve Word-native Track Changes without flattening the document.
Its core abstraction is a virtual document layer that gives LLMs a Markdown-facing surface while keeping the underlying OOXML structure intact.
The safety machinery matters as much as the bridge itself, because uniqueness checks and boundary matching keep edits atomic and reversible.
MCP turns the engine into usable infrastructure, letting agents call the same document workflow from tools like Claude Desktop or Cursor.

The problem is not editing Word. It is surviving the round trip. LLMs are comfortable in Markdown, but contracts live in OOXML, where formatting, comments, and tracked changes are part of the record, not decorative extras.

Layer	What it does well	Where it breaks	Best fit
Open XML SDK / python-docx	Low-level document creation and XML access	Redlining is brittle because you must manage structure by hand	Library authors and document generators
Commercial CLM suites	Opinionated review workflows and playbooks	Closed systems with limited developer control	Legal teams that want a packaged workflow
Adeu	Safe round-trip editing between LLMs and Word	Niche by design, focused on redlining and agent workflows	Developers building AI document agents

The problem is not editing Word. It is surviving the round trip.

A plain text converter can make a document readable to an LLM in seconds. It cannot make the result trustworthy. Once formatting, comments, and tracked changes matter, the hard part becomes preserving meaning on the way out, not on the way in.

That is why Adeu is interesting. It does not ask the model to understand OpenXML. It gives the model a working surface that looks like Markdown, then maps those edits back into Word with the original document structure still recognizable.

Adeu turns a document into a virtual DOM

The ingest pipeline acts like a projector. It converts a `.docx` file into a Markdown-like view, but it does not throw away the document’s semantic scaffolding. Tracked changes, comments, and structure survive as signals the model can use.

This pipeline is the real product. Adeu projects Word into a model-friendly surface, validates the edit, then writes the result back as a native redline.

Adeu is a docx ↔ LLM translator: a Model Context Protocol (MCP) server (Python and Node.js implementations) and accompanying SDKs that act as a Virtual DOM for Microsoft Word.

dealfluence, Project Maintainer · dealfluence/adeu: docx ↔ LLM translator

The structural appendix is the quiet trick

Adeu also appends document context, like defined terms and cross-references, so the model can reason with more than the visible paragraph in front of it. That matters in legal text, where the meaning of a clause often lives elsewhere in the file.

A close-up of a Markdown fragment on the left is pushed through a narrow mechanical gate in the middle and lands as a clean Word paragraph with tracked insertion marks on the right. The gate measures exact phrase boundaries, showing how Adeu protects structure while translating model edits into native redlines. — The safety layer is the difference between a useful redline engine and a fragile text replacer.

The redline engine makes edits atomic

On the way back, Adeu stops behaving like a converter and starts behaving like a transaction layer. The redline engine checks whether a target span is uniquely matchable before it applies the edit, which keeps one ambiguous instruction from mutating the wrong sentence.

# Conceptual shape of the apply step
for change in batch:
    match = find_unique_target(document, change.target_text)
    if not match:
        raise ValueError("Target text must match uniquely")

    apply_track_change(
        document=document,
        span=match,
        replacement=change.replacement,
        preserve_formatting=True,
    )

That uniqueness check is the point. Adeu is not trying to be clever by guessing. It is trying to be safe by refusing edits that cannot be matched with confidence.

The real trick is making Markdown safe enough to trust

Markdown is convenient for models, but it is noisy for a redline engine. Formatting markers drift. Spaces disappear. Bold spans get split. Adeu’s markup layer looks for safe boundaries, then refines the match so the engine does not leave broken syntax behind.

boundary = _find_safe_boundaries(text, target)
boundary = _refine_match_boundaries(text, boundary)
regex = _make_fuzzy_regex(target)
match = regex.search(text)

That is a small set of functions with a large effect. They let Adeu treat markdown noise as a tolerated mismatch, not as a reason to corrupt the underlying document. In practice, that is what makes LLM edits usable in a legal workflow.

MCP turns the bridge into a usable agent tool

Adeu is exposed through Model Context Protocol tools, so the bridge can live inside Claude Desktop, Cursor, and other agent environments. That shifts the project from a library you call manually to an interface agents can negotiate with directly.

The parity between Python and Node matters here. It means the same core workflow can serve different runtimes without forcing the team to maintain two incompatible mental models for the same document operation.

While standard libraries like python-docx excel at generating documents from scratch, they fail at non-destructive redlining. Adeu solves this by translating .docx files into a token-efficient Markdown representation.

dealfluence, Project Maintainer · dealfluence/adeu: docx ↔ LLM translator

Why Adeu beats generic document libraries and closed CLM suites

Adeu is easiest to understand when you place it in the stack. It is not competing with low-level libraries on raw XML access, and it is not trying to be a full commercial contract platform. It sits between them as a safe editing protocol for agents.

Criterion	Adeu	Generic doc libraries	Commercial CLM suites
Primary job	Round-trip redlining for LLMs	XML-level document manipulation	End-to-end legal review workflow
Input and output	DOCX in, Markdown-like working view, DOCX back out	DOCX and XML	Word or web app workflows
Redlining support	Native Track Changes	Manual and brittle	Usually built in, but proprietary
Fidelity preservation	Designed to preserve structure and formatting	Possible, but developer-managed	High, but within a closed system
Agent integration	Built around MCP	Not native	Limited or vendor-controlled
Best fit	AI document agents	Infrastructure code	Legal teams buying software

What this means for LegalTech

Adeu points at a practical future for legal document automation. The system stays local, auditable, and Word-native, while the model works in a representation it can actually handle. That combination is more important than it sounds.

The deeper idea is simple. If a machine is going to negotiate text, it needs a transaction protocol, not just a parser. Adeu is that protocol for Word, and that is why it feels less like a converter and more like infrastructure.