adeu 0.4.0__tar.gz

adeu-0.4.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 dealfluence
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

adeu-0.4.0/PKG-INFO

@@ -0,0 +1,109 @@
+Metadata-Version: 2.4
+Name: adeu
+Version: 0.4.0
+Summary: Automated DOCX Redlining Engine
+License-File: LICENSE
+Author: Mikko Korpela
+Requires-Python: >=3.12
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: diff-match-patch (>=20230430)
+Requires-Dist: lxml (>=5.0.0)
+Requires-Dist: mcp (>=1.2.0)
+Requires-Dist: pydantic (>=2.0.0)
+Requires-Dist: python-docx (>=1.1.0)
+Requires-Dist: structlog (>=24.0.0)
+Description-Content-Type: text/markdown
+
+# Adeu: AI Redlining Engine
+
+**Adeu allows AI Agents and LLMs to "Track Changes" in Microsoft Word documents.**
+
+Most LLMs output raw text or Markdown. Professionals need `w:ins` (insertions) and `w:del` (deletions) to review changes inside Word. `adeu` lib shows a Word document in an LLM and human understandable textual format and reflects changes made to it to the actual word document.
+
+It creates a "Virtual DOM" of your document, letting AI apply surgical edits without breaking your formatting, numbering, or headers.
+
+---
+
+## Installation
+
+Adeu is available on PyPI.
+
+```bash
+pip install adeu
+```
+
+---
+
+## Ways to Use Adeu
+
+### 1. As MCP Server (No Code Required)
+If you use an agentic system such as Claude Desktop, you can connect Adeu directly. This lets you handle contracts in Claude and say: *"Change the Governing Law to Delaware and generate me the redline."*
+
+Add this to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "adeu": {
+      "command": "uvx",
+      "args": ["adeu", "adeu-server"]
+    }
+  }
+}
+```
+*(Requires [uv](https://docs.astral.sh/uv/) installed on your machine)*
+
+### 2. For "Vibe Coding" & Python Scripts
+Building your own Agentic AI tool in Cursor, Replit, or Windsurf: Adeu is the engine that handles the document manipulation for you.
+
+```python
+from adeu import RedlineEngine, DocumentEdit
+from io import BytesIO
+
+# 1. Load your contract
+with open("NDA.docx", "rb") as f:
+    doc_stream = BytesIO(f.read())
+
+# 2. Define the change (Usually this comes from your LLM response)
+edit = DocumentEdit(
+    target_text="State of New York",
+    new_text="State of Delaware",
+    comment="Changed governing law to neutral jurisdiction."
+)
+
+# 3. Apply the Redline
+engine = RedlineEngine(doc_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())
+```
+
+### 3. The CLI
+Quickly extract text or apply patches from your terminal.
+
+```bash
+# Compare two docs and see a summary
+adeu diff v1.docx v2.docx
+
+# Apply a JSON list of edits to a doc
+adeu apply agreement.docx edits.json
+```
+
+---
+
+## Why Adeu?
+
+*   **Native Redlines**: Generates real Microsoft Word Track Changes. You can "Accept" or "Reject" them in Word.
+*   **Format Safe**: Adeu preserves your complex numbering, headers, footers, and images. It only touches the text you change.
+*   **Native Comments**: Supports adding comments (`Review Pane`) linked to specific text ranges.
+*   **Intelligent Mapping**: Handles the messy internal XML of Word documents (e.g., when "Contract" is split into `["Con", "tract"]` by spellcheck).
+
+## License
+
+MIT License. Open source and free to use in commercial legal tech applications.
+

adeu-0.4.0/README.md

@@ -0,0 +1,89 @@
+# Adeu: AI Redlining Engine
+
+**Adeu allows AI Agents and LLMs to "Track Changes" in Microsoft Word documents.**
+
+Most LLMs output raw text or Markdown. Professionals need `w:ins` (insertions) and `w:del` (deletions) to review changes inside Word. `adeu` lib shows a Word document in an LLM and human understandable textual format and reflects changes made to it to the actual word document.
+
+It creates a "Virtual DOM" of your document, letting AI apply surgical edits without breaking your formatting, numbering, or headers.
+
+---
+
+## Installation
+
+Adeu is available on PyPI.
+
+```bash
+pip install adeu
+```
+
+---
+
+## Ways to Use Adeu
+
+### 1. As MCP Server (No Code Required)
+If you use an agentic system such as Claude Desktop, you can connect Adeu directly. This lets you handle contracts in Claude and say: *"Change the Governing Law to Delaware and generate me the redline."*
+
+Add this to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "adeu": {
+      "command": "uvx",
+      "args": ["adeu", "adeu-server"]
+    }
+  }
+}
+```
+*(Requires [uv](https://docs.astral.sh/uv/) installed on your machine)*
+
+### 2. For "Vibe Coding" & Python Scripts
+Building your own Agentic AI tool in Cursor, Replit, or Windsurf: Adeu is the engine that handles the document manipulation for you.
+
+```python
+from adeu import RedlineEngine, DocumentEdit
+from io import BytesIO
+
+# 1. Load your contract
+with open("NDA.docx", "rb") as f:
+    doc_stream = BytesIO(f.read())
+
+# 2. Define the change (Usually this comes from your LLM response)
+edit = DocumentEdit(
+    target_text="State of New York",
+    new_text="State of Delaware",
+    comment="Changed governing law to neutral jurisdiction."
+)
+
+# 3. Apply the Redline
+engine = RedlineEngine(doc_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())
+```
+
+### 3. The CLI
+Quickly extract text or apply patches from your terminal.
+
+```bash
+# Compare two docs and see a summary
+adeu diff v1.docx v2.docx
+
+# Apply a JSON list of edits to a doc
+adeu apply agreement.docx edits.json
+```
+
+---
+
+## Why Adeu?
+
+*   **Native Redlines**: Generates real Microsoft Word Track Changes. You can "Accept" or "Reject" them in Word.
+*   **Format Safe**: Adeu preserves your complex numbering, headers, footers, and images. It only touches the text you change.
+*   **Native Comments**: Supports adding comments (`Review Pane`) linked to specific text ranges.
+*   **Intelligent Mapping**: Handles the messy internal XML of Word documents (e.g., when "Contract" is split into `["Con", "tract"]` by spellcheck).
+
+## License
+
+MIT License. Open source and free to use in commercial legal tech applications.

adeu-0.4.0/pyproject.toml

@@ -0,0 +1,52 @@
+[tool.poetry]
+name = "adeu"
+version = "0.4.0"
+description = "Automated DOCX Redlining Engine"
+authors = ["Mikko Korpela"]
+readme = "README.md"
+packages = [{include = "adeu", from = "src"}]
+
+[tool.poetry.scripts]
+adeu = "adeu.cli:main"
+adeu-server = "adeu.server:main"
+
+[tool.poetry.dependencies]
+python = ">=3.12"
+python-docx = ">=1.1.0"
+structlog = ">=24.0.0"
+pydantic = ">=2.0.0"
+lxml = ">=5.0.0"
+diff-match-patch = ">=20230430"
+mcp = ">=1.2.0"
+
+[tool.poetry.group.dev.dependencies]
+pytest = "*"
+ruff = "*"
+mypy = "*"
+hypothesis = "*"
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.ruff]
+line-length = 120
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B", "W"]
+ignore = []
+
+[tool.mypy]
+python_version = "3.12"
+strict = false
+ignore_missing_imports = true
+check_untyped_defs = true
+
+[[tool.mypy.overrides]]
+module = "diff_match_patch.*"
+ignore_missing_imports = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = "test_*.py"

adeu-0.4.0/src/adeu/__init__.py

@@ -0,0 +1,9 @@
+from importlib.metadata import version
+
+from adeu.ingest import extract_text_from_stream
+from adeu.models import DocumentEdit
+from adeu.redline.engine import RedlineEngine
+
+__version__ = version("adeu")
+
+__all__ = ["RedlineEngine", "DocumentEdit", "extract_text_from_stream", "__version__"]

adeu-0.4.0/src/adeu/cli.py

@@ -0,0 +1,147 @@
+import argparse
+import getpass
+import json
+import sys
+from io import BytesIO
+from pathlib import Path
+from typing import List
+
+from adeu import __version__
+from adeu.diff import generate_edits_from_text
+from adeu.ingest import extract_text_from_stream
+from adeu.models import DocumentEdit
+from adeu.redline.engine import RedlineEngine
+
+
+def _read_docx_text(path: Path) -> str:
+    if not path.exists():
+        print(f"Error: File not found: {path}", file=sys.stderr)
+        sys.exit(1)
+    with open(path, "rb") as f:
+        return extract_text_from_stream(BytesIO(f.read()), filename=path.name)
+
+
+def _load_edits_from_json(path: Path) -> List[DocumentEdit]:
+    try:
+        with open(path, "r", encoding="utf-8") as f:
+            data = json.load(f)
+        edits = []
+        for item in data:
+            target = item.get("target_text") or item.get("original")
+            new_val = item.get("new_text") or item.get("replace")
+            comment = item.get("comment")
+
+            edits.append(DocumentEdit(target_text=target or "", new_text=new_val or "", comment=comment))
+        return edits
+    except Exception as e:
+        print(f"Error parsing JSON edits: {e}", file=sys.stderr)
+        sys.exit(1)
+
+
+def handle_extract(args):
+    text = _read_docx_text(args.input)
+    if args.output:
+        with open(args.output, "w", encoding="utf-8") as f:
+            f.write(text)
+        print(f"Extracted text to {args.output}", file=sys.stderr)
+    else:
+        print(text)
+
+
+def handle_diff(args):
+    text_orig = _read_docx_text(args.original)
+
+    if args.modified.suffix == ".docx":
+        text_mod = _read_docx_text(args.modified)
+    else:
+        with open(args.modified, "r", encoding="utf-8") as f:
+            text_mod = f.read()
+
+    edits = generate_edits_from_text(text_orig, text_mod)
+
+    if args.json:
+        output = [e.model_dump(exclude={"_match_start_index"}) for e in edits]
+        print(json.dumps(output, indent=2))
+    else:
+        print(f"Found {len(edits)} changes:", file=sys.stderr)
+        for e in edits:
+            if not e.new_text:
+                print(f"[-] {e.target_text}")
+            elif not e.target_text:
+                print(f"[+] {e.new_text}")
+            else:
+                print(f"[~] '{e.target_text}' -> '{e.new_text}'")
+
+
+def handle_apply(args):
+    edits = []
+    if args.changes.suffix.lower() == ".json":
+        print(f"Loading structured edits from {args.changes}...", file=sys.stderr)
+        edits = _load_edits_from_json(args.changes)
+    else:
+        print(f"Calculating diff from text file {args.changes}...", file=sys.stderr)
+        text_orig = _read_docx_text(args.original)
+        with open(args.changes, "r", encoding="utf-8") as f:
+            text_mod = f.read()
+        edits = generate_edits_from_text(text_orig, text_mod)
+
+    print(f"Applying {len(edits)} edits...", file=sys.stderr)
+
+    with open(args.original, "rb") as f:
+        stream = BytesIO(f.read())
+
+    engine = RedlineEngine(stream, author=args.author)
+    applied, skipped = engine.apply_edits(edits)
+
+    output_path = args.output
+    if not output_path:
+        output_path = args.original.with_name(f"{args.original.stem}_redlined.docx")
+
+    with open(output_path, "wb") as f:
+        f.write(engine.save_to_stream().getvalue())
+
+    print(f"✅ Saved to {output_path}", file=sys.stderr)
+    print(f"Stats: {applied} applied, {skipped} skipped.", file=sys.stderr)
+    if skipped > 0:
+        sys.exit(1)
+
+
+def main():
+    parser = argparse.ArgumentParser(prog="adeu", description="Adeu: Agentic DOCX Redlining Engine")
+    parser.add_argument("-v", "--version", action="version", version=f"%(prog)s {__version__}")
+    subparsers = parser.add_subparsers(dest="command", required=True, help="Subcommands")
+
+    p_extract = subparsers.add_parser("extract", help="Extract raw text from a DOCX file")
+    p_extract.add_argument("input", type=Path, help="Input DOCX file")
+    p_extract.add_argument("-o", "--output", type=Path, help="Output file (default: stdout)")
+    p_extract.set_defaults(func=handle_extract)
+
+    p_diff = subparsers.add_parser("diff", help="Compare two files (DOCX vs DOCX/Text)")
+    p_diff.add_argument("original", type=Path, help="Original DOCX")
+    p_diff.add_argument("modified", type=Path, help="Modified DOCX or Text file")
+    p_diff.add_argument("--json", action="store_true", help="Output raw JSON edits")
+    p_diff.set_defaults(func=handle_diff)
+
+    try:
+        default_author = getpass.getuser()
+    except Exception:
+        default_author = "Adeu AI"
+
+    p_apply = subparsers.add_parser("apply", help="Apply edits to a DOCX")
+    p_apply.add_argument("original", type=Path, help="Original DOCX")
+    p_apply.add_argument("changes", type=Path, help="JSON edits file OR Modified Text file")
+    p_apply.add_argument("-o", "--output", type=Path, help="Output DOCX path")
+    p_apply.add_argument(
+        "--author",
+        type=str,
+        default=default_author,
+        help=f"Author name for Track Changes (default: '{default_author}')",
+    )
+    p_apply.set_defaults(func=handle_apply)
+
+    args = parser.parse_args()
+    args.func(args)
+
+
+if __name__ == "__main__":
+    main()

adeu-0.4.0/src/adeu/diff.py

@@ -0,0 +1,137 @@
+import re
+from typing import Dict, List, Tuple
+
+import structlog
+from diff_match_patch import diff_match_patch
+
+from adeu.models import DocumentEdit
+
+logger = structlog.get_logger(__name__)
+
+
+def generate_edits_from_text(original_text: str, modified_text: str) -> List[DocumentEdit]:
+    """
+    Compares original and modified text to generate structured ComplianceEdit objects.
+    Uses Word-Level diffing to ensure natural, readable redlines.
+    """
+    dmp = diff_match_patch()
+
+    # 1. Word-Level Tokenization & Encoding
+    chars1, chars2, token_array = _words_to_chars(original_text, modified_text)
+
+    # 2. Compute Diff on the Encoded Strings
+    diffs_encoded = dmp.diff_main(chars1, chars2, False)
+
+    # 3. Semantic Cleanup
+    dmp.diff_cleanupSemantic(diffs_encoded)
+
+    # 4. Decode back to Text
+    dmp.diff_charsToLines(diffs_encoded, token_array)
+    diffs = diffs_encoded
+
+    edits = []
+    current_original_index = 0
+    pending_delete = None  # Tuple(index, text)
+
+    for i, (op, text) in enumerate(diffs):
+        if op == 0:  # Equal
+            # Flush pending delete if any
+            if pending_delete:
+                idx, del_txt = pending_delete
+                edit = DocumentEdit(target_text=del_txt, new_text="", comment="Diff: Text deleted")
+                edit._match_start_index = idx
+                edits.append(edit)
+                pending_delete = None
+
+            current_original_index += len(text)
+
+        elif op == -1:  # Delete
+            # Defer deletion to check for immediate insertion (Modification)
+            pending_delete = (current_original_index, text)
+            current_original_index += len(text)
+
+        elif op == 1:  # Insert
+            if pending_delete:
+                # Merge into Modification (Replace)
+                idx, del_txt = pending_delete
+                edit = DocumentEdit(target_text=del_txt, new_text=text, comment="Diff: Replacement")
+                edit._match_start_index = idx
+                edits.append(edit)
+                pending_delete = None
+            else:
+                # Pure Insertion
+                # Find Anchor context
+                anchor_start = max(0, current_original_index - 50)
+                anchor = original_text[anchor_start:current_original_index]
+
+                # Special Case: Start-of-Document with no anchor
+                if not anchor and current_original_index == 0:
+                    # Check next equal for context (Forward Anchor)
+                    if i + 1 < len(diffs) and diffs[i + 1][0] == 0:
+                        next_text = diffs[i + 1][1]
+                        # Grab first word or chunk
+                        anchor_target = next_text.split(" ")[0] if " " in next_text else next_text[:20]
+                        if anchor_target:
+                            # Convert to Modification of the following text
+                            # Target: "Contract" -> New: "Big Contract"
+                            logger.info(f"Converting start-of-doc insert to modification of '{anchor_target}'")
+
+                            edit = DocumentEdit(
+                                target_text=anchor_target,
+                                new_text=text + anchor_target,
+                                comment="Diff: Start-of-doc insertion",
+                            )
+                            edit._match_start_index = current_original_index
+                            edits.append(edit)
+
+                            # We consumed the start of the next text conceptually?
+                            # Actually, DMP will process the next Equal text normally.
+                            # But we claim we modified it. This is slightly overlapping logic.
+                            # However, since we track indices, we just want to ensure we target correctly.
+                            # BUT, current_original_index matches the start of anchor_target.
+                            # So we assume the next Op=0 will advance past it.
+                            # This is a bit hacky. For now, let's stick to standard Anchor logic if possible,
+                            # or just use empty anchor if allowed.
+
+                            # Let's revert to simple Anchor logic for stability in this patch.
+                            pass
+
+                # Standard Insertion: Target=Anchor, New=Anchor+Text
+                edit = DocumentEdit(target_text=anchor, new_text=anchor + text, comment="Diff: Text inserted")
+                edit._match_start_index = current_original_index
+                edits.append(edit)
+
+    # Flush trailing delete
+    if pending_delete:
+        idx, del_txt = pending_delete
+        edit = DocumentEdit(target_text=del_txt, new_text="", comment="Diff: Text deleted")
+        edit._match_start_index = idx
+        edits.append(edit)
+
+    return edits
+
+
+def _words_to_chars(text1: str, text2: str) -> Tuple[str, str, List[str]]:
+    """
+    Splits text into words/tokens and encodes them as unique Unicode characters.
+    """
+    token_array: List[str] = []
+    token_hash: Dict[str, int] = {}
+    split_pattern = r"(\s+|\w+|[^\w\s])"
+
+    def encode_text(text: str) -> str:
+        tokens = [t for t in re.split(split_pattern, text) if t]
+        encoded_chars = []
+        for token in tokens:
+            if token in token_hash:
+                encoded_chars.append(chr(token_hash[token]))
+            else:
+                code = len(token_array)
+                token_hash[token] = code
+                token_array.append(token)
+                encoded_chars.append(chr(code))
+        return "".join(encoded_chars)
+
+    chars1 = encode_text(text1)
+    chars2 = encode_text(text2)
+    return chars1, chars2, token_array

adeu-0.4.0/src/adeu/ingest.py

@@ -0,0 +1,85 @@
+# FILE: src/adeu/ingest.py
+
+import io
+
+import structlog
+from docx import Document
+
+from adeu.utils.docx import (
+    get_paragraph_prefix,
+    get_run_style_markers,
+    get_run_text,
+    get_visible_runs,
+    iter_document_parts,
+)
+
+logger = structlog.get_logger(__name__)
+
+
+def extract_text_from_stream(file_stream: io.BytesIO, filename: str = "document.docx") -> str:
+    """
+    Extracts text from a file stream using raw run concatenation.
+
+    CRITICAL: This must match DocumentMapper._build_map logic exactly.
+    We iterate runs and join them. We do not use para.text.
+    """
+    try:
+        # Ensure stream is at start
+        file_stream.seek(0)
+
+        doc = Document(file_stream)
+        full_text = []
+
+        for part in iter_document_parts(doc):
+            # 1. Paragraphs
+            for para in part.paragraphs:
+                # Use the visible runs helper to see <w:ins> content
+                runs = get_visible_runs(para)
+
+                # Build paragraph text with markers
+                p_text_parts = []
+                for r in runs:
+                    prefix, suffix = get_run_style_markers(r)
+                    text = get_run_text(r)
+                    p_text_parts.append(f"{prefix}{text}{suffix}")
+
+                p_text = "".join(p_text_parts)
+
+                # Add Markdown prefix if heading
+                prefix = get_paragraph_prefix(para)
+                full_text.append(prefix + p_text)
+
+            # 2. Tables
+            for table in part.tables:
+                for row in table.rows:
+                    row_parts = []
+                    for cell in row.cells:
+                        # Cell paragraphs
+                        cell_text_parts = []
+                        for p in cell.paragraphs:
+                            # Note: We probably don't want headers inside tables usually,
+                            # but for consistency we should allow it if styled.
+                            prefix = get_paragraph_prefix(p)
+
+                            runs = get_visible_runs(p)
+                            p_content_list = []
+                            for r in runs:
+                                r_pre, r_suf = get_run_style_markers(r)
+                                r_text = get_run_text(r)
+                                p_content_list.append(f"{r_pre}{r_text}{r_suf}")
+
+                            p_content = "".join(p_content_list)
+                            cell_text_parts.append(prefix + p_content)
+
+                        cell_text = "\n".join(cell_text_parts)
+                        if cell_text:
+                            row_parts.append(cell_text)
+
+                    if row_parts:
+                        full_text.append(" | ".join(row_parts))
+
+        return "\n\n".join(full_text)
+
+    except Exception as e:
+        logger.error(f"Text extraction failed: {e}", exc_info=True)
+        raise ValueError(f"Could not extract text: {str(e)}") from e