adeu 0.6.5

Automated DOCX Redlining Engine

Adeu OSS: DOCX Redlining Engine

Adeu allows AI Agents and LLMs to safely "Track Changes" in Microsoft Word documents.

Most LLMs output raw text or Markdown. Legal and compliance professionals need w:ins (insertions) and w:del (deletions) to review changes natively in Word.

Adeu solves this by treating DOCX as a "Virtual DOM". It presents a clean, readable text representation to the AI, and then reconciles the AI's edits back into the original XML structure without breaking formatting, numbering, or images.

⚡ Quick Start (The "Invisible" Setup)

Prerequisite: You must have uv installed.

# One-line setup for Claude Desktop
uvx adeu init

Restart Claude Desktop after running this command.

Adeu will now be available to your Agent as a set of native tools. No manual JSON editing required.

---

Ways to Use Adeu

1. As an Agentic Tool (MCP)

Once initialized, your Agent (Claude, OpenClaw, etc.) gains these capabilities. You don't need to teach it "how" to code Python; you just ask it to perform tasks.

What the Agent sees: The agent receives a text view of the document where comments and changes are clearly marked:

The Vendor shall be liable for {==indirect damages==}{>>[Counsel] We request this be removed.<<}...

Available MCP Tools

Tool	Description
read_docx	Reads a DOCX file. Supports clean_view=True to simulate "Accept All Changes" before reading.
diff_docx_files	Compares two DOCX files and returns a text-based Unified Diff, ignoring formatting noise.
apply_structured_edits	The Core Engine. Applies a list of "Search & Replace" edits, generating native Track Changes (w:ins/w:del).
manage_review_actions	Review workflow. Allows the Agent to ACCEPT, REJECT, or REPLY to specific changes or comments by ID.
accept_all_changes	Creates a clean version of the document by accepting all revisions and removing comments.
apply_edits_as_markdown	New. Extracts text from a DOCX, applies edits as CriticMarkup, and saves as a .md file for preview.

Agent Skills (Prompting Guide)

When defining "Skills" or "System Prompts" for your agent, use this shorthand to describe Adeu's role:

Role: Document Specialist Capabilities:

1. Reading: Always use read_docx(clean_view=True) first to understand the contract context.
2. Reviewing: Use apply_edits_as_markdown to propose changes. Show the user the diff before applying.
3. Editing: Use apply_structured_edits only when the user explicitly confirms changes.
4. Negotiating: Use manage_review_actions to Reply/Accept/Reject existing comments from counterparties.

CriticMarkup Preview Example

The apply_edits_as_markdown tool lets agents preview changes before applying them to the actual DOCX:

# Input: contract.docx containing "The Tenant shall pay rent monthly."
# Edit: target_text="Tenant", new_text="Lessee", comment="Standardizing terminology"

# Output saved to contract_markup.md:
The {--Tenant--}{++Lessee++}{>>Standardizing terminology<<} shall pay rent monthly.

Options:

• highlight_only=True: Only mark targets with {==...==} without showing changes
• include_index=True: Add [Edit:N] markers for tracking

2. For Python Developers & Vibe Coders

Adeu handles the heavy lifting of XML manipulation so you can focus on the logic.

from adeu import RedlineEngine, DocumentEdit
from io import BytesIO

# 1. Load your contract
with open("NDA.docx", "rb") as f:
    stream = BytesIO(f.read())

# 2. Define the change (e.g., from an LLM response)
# Adeu uses "Search & Replace" logic with fuzzy matching
edit = DocumentEdit(
    target_text="State of New York",
    new_text="State of Delaware",
    comment="Standardizing governing law."
)

# 3. Apply the Redline
engine = RedlineEngine(stream, author="AI Associate")
engine.apply_edits([edit])

# 4. Save
with open("NDA_Redlined.docx", "wb") as f:
    f.write(engine.save_to_stream().getvalue())

You can also preview changes as CriticMarkup without modifying the DOCX:

from adeu import apply_edits_to_markdown, DocumentEdit

text = "The Tenant shall pay rent monthly."
edits = [
    DocumentEdit(
        target_text="Tenant",
        new_text="Lessee",
        comment="Standardizing terminology"
    )
]

# Full preview with changes
result = apply_edits_to_markdown(text, edits, include_index=True)
# Output: "The {--Tenant--}{++Lessee++}{>>Standardizing terminology [Edit:0]<<} shall pay rent monthly."

# Highlight-only mode (show what will be changed)
preview = apply_edits_to_markdown(text, edits, highlight_only=True)
# Output: "The {==Tenant==}{>>Standardizing terminology<<} shall pay rent monthly."

3. The CLI

Quickly extract text, apply patches, or preview changes from your terminal.

# Extract text from a DOCX
adeu extract contract.docx -o contract.md

# Compare two docs and get a summary
adeu diff v1.docx v2.docx

# Apply a structured edit list (JSON) to a doc
adeu apply agreement.docx edits.json --author "Reviewer Bot"

# Preview changes as CriticMarkup Markdown (NEW)
adeu markup contract.docx edits.json -o preview.md

# Highlight-only mode (show targets without changes)
adeu markup contract.docx edits.json --highlight

# Include edit indices for tracking
adeu markup contract.docx edits.json --index

CLI Commands Reference

Command	Description
extract	Extract text from a DOCX file to stdout or a file.
diff	Compare two DOCX files and show changes.
apply	Apply edits from a JSON file to a DOCX with Track Changes.
markup	New. Apply edits to a document and output as CriticMarkup Markdown.

Edits JSON Format

Both apply and markup commands accept a JSON file with this structure:

[
  {
    "target_text": "Contract Agreement",
    "new_text": "Service Agreement",
    "comment": "Standardizing terminology"
  },
  {
    "target_text": "30 days",
    "new_text": "60 days",
    "comment": "Extended notice period"
  }
]

---

CriticMarkup Syntax

Adeu uses CriticMarkup for text-based change representation:

Markup	Meaning	Example
{--text--}	Deletion	{--old text--}
{++text++}	Insertion	{++new text++}
{==text==}	Highlight	{==marked text==}
{>>text<<}	Comment	{>>reviewer note<<}

Combined example:

The {--Tenant--}{++Lessee++}{>>Standardizing terminology [Edit:0]<<} shall pay rent.

---

Why Adeu?

• Native Redlines: Generates real Microsoft Word Track Changes. You can "Accept" or "Reject" them in Word.
• Format Safe: Preserves complex numbering, headers, footers, and images. It only touches the text you change.
• Token Efficient: Converts heavy XML into lightweight Markdown for the LLM context window.
• Intelligent Mapping: Handles the messy internal XML of Word documents (e.g., when "Contract" is split into ["Con", "tract"] by spellcheck).
• Preview First: Review changes as CriticMarkup Markdown before committing to the DOCX.

License

MIT License. Open source and free to use in commercial legal tech applications.