Adeu: AI를 위한 네이티브 변경 내용 추적(Track Changes)

PyPI version Python versions License: MIT MCP Compatible

LLM은 마크다운으로 말하고, 변호사는 "변경 내용 추적"으로 말합니다.

Adeu는 Microsoft Word용 "가상 DOM" 역할을 하는 MCP(Model Context Protocol) 서버이자 Python SDK입니다. 이 도구는 AI 에이전트가 기본 서식이나 복잡한 DOCX XML을 손상시키지 않고 자유롭게 문서 텍스트를 편집할 수 있도록 양방향 추상화 계층을 제공합니다.

python-docx와 같은 표준 라이브러리는 처음부터 문서를 생성하는 데는 탁월하지만, 비파괴적인 수정(redlining)에는 취약합니다. Adeu는 .docx 파일을 토큰 효율적인 마크다운 표현으로 변환하여 이 문제를 해결합니다. 이를 통해 AI 에이전트는 OpenXML과 씨름하며 토큰을 낭비하는 대신 문서의 의미론적 내용에만 집중할 수 있습니다.

Adeu는 지능형 프록시로서 AI의 편집 내용을 안전하고 원자적인 트랜잭션으로 처리합니다:

추출(Extract): 문서를 (디스크 또는 실시간 Word에서) 정의된 용어, 상호 참조, 오타 가능성 등이 포함된 **의미론적 부록(Semantic Appendix)**과 함께 LLM 친화적인 CriticMarkup으로 변환합니다. 에이전트는 원시 데이터가 아닌 의미론적 구조부터 작업을 시작합니다.
검증(Validate): 엄격한 안전 게이트 역할을 합니다. 모호한 텍스트 일치나 유효하지 않은 구조적 변경을 파일에 적용하기 전에 자동으로 차단하여 문서의 무결성을 보호합니다.
커밋(Commit): AI의 텍스트 편집 내용을 네이티브 Word 변경 내용 추적(Track Changes)으로 변환합니다. Adeu는 내부적으로 복잡한 XML을 처리하여 기존 레이아웃, 글꼴, 여백 주석이 완벽하게 유지되도록 합니다.

Adeu에서 유지 관리합니다.

설정

전제 조건: Adeu는 빠르고 격리된 실행을 위해 uv를 사용합니다. pip를 통해 설치하는 것이 가장 쉽습니다:

pip install uv

macOS

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Claude Desktop 통합

Adeu를 Claude Desktop에 즉시 추가하려면 다음을 실행하세요:

uvx adeu init

IMPORTANT

이 명령은claude_desktop_config.json을 자동으로 감지하고 업데이트합니다. 이후 Claude Desktop을 재시작하여 새 도구를 로드하세요.

작동 확인

Claude Desktop이 재시작되면 Claude에게 직접 다음 메시지를 입력하여 Adeu가 연결되었는지 확인할 수 있습니다:

"Adeu 도구를 사용하여 DOCX 파일을 읽을 수 있나요?"

설정이 올바르게 완료되었다면, Claude는 Adeu 도구에 액세스할 수 있음을 확인하고 수행 가능한 작업을 설명할 것입니다. Adeu에 대한 언급이 없거나 파일 도구가 없다고 표시되면 uvx adeu init 실행 후 Claude Desktop을 재시작했는지 다시 확인하세요.

Adeu는 Python 3.12+가 필요하므로 uvx가 자동으로 올바른 Python 버전을 다운로드하고 서버를 실행합니다:

{
  "mcpServers": {
    "adeu": {
      "command": "uvx",
      "args": ["--from", "adeu", "adeu-server"]
    }
  }
}

워크플로우

1. 에이전트용 (Claude / MCP)

Adeu는 MCP(Model Context Protocol) 서버로 실행됩니다. 에이전트에게 문서를 안전하게 읽고, 검토하고, 편집할 수 있는 특정 도구를 제공합니다.

MCP Apps UI: read_docx 도구는 최신 MCP Apps UI 프로토콜을 지원합니다. 에이전트가 문서를 읽을 때, Adeu는 Claude 채팅 창 내에 사용자 지정 대화형 마크다운 UI 뷰를 동적으로 렌더링하여 AI의 추론과 함께 추출된 텍스트 및 서식을 시각적으로 검토할 수 있게 합니다!

권장 에이전트 프롬프트: Adeu의 도구는 LLM에 자체 스키마를 자동으로 설명하지만, Claude의 **프로젝트 지침(Project Instructions)**이나 에이전트의 시스템 프롬프트에 다음 컨텍스트를 추가하면 최상의 결과를 보장할 수 있습니다:

역할: 문서 전문가 도구:
read_docx(clean_view=True): 텍스트의 최종 "깔끔한" 버전을 읽어 컨텍스트를 파악합니다.
process_document_batch: 커밋 및 협상 모드. 통합된 변경 목록을 적용합니다. 특정 검색 및 바꾸기 텍스트 편집에는 type: "modify"를 사용하고, 기존 변경 내용 추적 및 주석을 ID별로 관리하려면 type: "accept", "reject", "reply"를 사용합니다.
sanitize_docx: 전송 전 정리. 공유하기 전에 위험한 메타데이터, 작성자 이름, 내부 추적 ID를 제거합니다. 기존 마크업을 유지(keep_markup=True)하거나 기준선 대비 깔끔한 델타를 생성할 수 있습니다.

실시간 MS Word 통합

Microsoft Word가 설치된 Windows 환경에서 실행 중인 경우, Adeu는 실시간 부조종사(copilot) 역할을 하여 활성 문서를 바로 앞에서 편집할 수 있습니다.

read_active_word_document: 열려 있는 Word 창에서 텍스트, 변경 내용 추적, 주석을 직접 추출합니다.
process_active_word_batch: LLM의 편집 내용을 네이티브 COM 매크로로 변환하여 Word가 캔버스에서 자동으로 텍스트를 입력, 삭제하고 주석을 추가하도록 합니다.

2. 빌더용 (Python SDK)

법률 기술 애플리케이션이나 자동화된 파이프라인을 구축하는 경우 RedlineEngine을 직접 사용하세요. XML 조작의 복잡한 작업을 처리합니다.

from adeu import RedlineEngine, ModifyText
from io import BytesIO

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

# 2. Define the edit (e.g., from an LLM response)
# Adeu uses fuzzy matching to locate the target text, even if whitespace varies.
edit = ModifyText(
    target_text="State of New York",
    new_text="State of Delaware",
    comment="Standardizing governing law."
)

# 3. Apply changes
engine = RedlineEngine(stream, author="AI Copilot")
engine.apply_edits([edit])

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

3. CLI

터미널에서 빠르게 문서를 검사하거나 편집 배치를 적용하세요.

# Extract clean text for RAG or prompting
adeu extract contract.docx -o contract.md

# Generate a visual diff between two versions
adeu diff v1.docx v2.docx

# Preview what an edit list (JSON) would look like
adeu markup contract.docx edits.json --output preview.md

# Apply edits to the DOCX
adeu apply contract.docx edits.json --author "Review Bot"

# Scrub author metadata and internal trackers, but keep the visual redlines for the counterparty
adeu sanitize redline.docx -o clean.docx --keep-markup --author "My Firm" --report

주요 기능

서식 안전성

Adeu는 문서를 "다시 작성"하지 않습니다. 패치(patch)합니다.

이미지 및 레이아웃: 건드리지 않습니다.
번호 매기기 및 머리글: 유지됩니다.
표 및 목록: 복잡한 그리드 스팬과 다단계 법률 번호 매기기는 명시적으로 보호됩니다.
복잡한 XML: 편집 대상인 텍스트 실행(run)만 수정합니다.

CriticMarkup 표현

중간 표현은 중요합니다. Adeu는 CriticMarkup을 사용하여 변경 사항을 시각화합니다.

마크업	의미	예시
`{--text--}`	삭제	`{--Tenant--}`
`{++text++}`	삽입	`{++Lessee++}`
`{>>text<<}`	주석	`{>>이 용어를 명확히 하세요<<}`

의미론적 부록

계약서에는 LLM이 첫 번째 패스에서 놓칠 수 있는 지뢰가 가득합니다(일관성 없이 사용된 정의된 용어, 깨진 상호 참조, 지저분한 문서의 OCR 스타일 오타 등). Adeu는 추출 시 이를 미리 계산하여 텍스트와 함께 구조화된 부록을 에이전트에게 제공합니다.

지능형 매핑

Word 문서는 복잡합니다. "Contract"와 같은 단어는 맞춤법 검사나 서식 기록으로 인해 ["Con", "tract"]와 같은 XML 실행으로 분할될 수 있습니다.

실행 병합(Run Coalescing): Adeu는 이러한 분할을 정규화하여 AI가 "Contract"로 인식하도록 합니다.
퍼지 매칭(Fuzzy Matching): LLM의 메모리와 실제 문서 내용 간의 사소한 공백 차이를 처리합니다.

메타데이터 정리

기존 메타데이터 제거 도구는 레드라인을 깨뜨리거나 데이터를 조용히 삭제합니다. Adeu의 sanitize 명령은 유효한 변경 내용 추적은 유지하면서 위험한 추적기(rsid, 템플릿, 내부 경로, 타임스탬프)와 고아 콘텐츠를 외과적으로 제거합니다. 결정적으로, 무엇이 제거되었고 수신자에게 무엇이 보일지 정확히 증명하는 투명한 감사 보고서를 생성합니다.

Adeu Cloud

기본적으로 핵심 Adeu 레드라인 엔진과 로컬 파일 도구는 완전히 오픈 소스이며 사용자의 컴퓨터에서 완전히 실행됩니다. Adeu는 로컬 문서를 외부로 전송하지 않습니다 (물론 선택한 LLM 제공업체는 에이전트가 읽는 텍스트를 처리하게 됩니다).

하지만 다음 기능을 잠금 해제하기 위해 MCP 서버를 Adeu Cloud에 연결하도록 명시적으로 선택할 수 있습니다:

엔드 투 엔드 워크플로우 (이메일): 계약서는 이메일을 통해 이동하므로, Adeu Cloud를 사용하면 에이전트가 이메일 스레드를 안전하게 가져오고, 검토를 위해 상대방의 DOCX 첨부 파일을 추출하며, 새로 정리된 레드라인이 첨부된 답장을 작성할 수 있습니다.
고급 문서 검증: 복잡한 다중 문서 의미론적 검증 작업을 비동기적으로 실행합니다. 이러한 방대한 컨텍스트를 Adeu Cloud로 안전하게 라우팅하여 처리함으로써 로컬 AI 에이전트가 컨텍스트 창을 소진하거나 속도 제한에 걸리는 것을 방지합니다.

Adeu Cloud에 대해 더 알아보기.

기여

커뮤니티의 기여를 환영합니다! 버그 수정, 기능 추가, 문서 개선 등 무엇이든 좋습니다. 로컬 uv 환경 설정, 테스트 실행, 프로젝트의 엄격한 XML 안전 지침 이해에 대한 지침은 기여 가이드를 참조하세요.

라이선스

MIT 라이선스. 오픈 소스이며 상업용 애플리케이션에서 무료로 사용할 수 있습니다.

adeu