Adeu: Control de cambios nativo para IA

Los LLM hablan Markdown; los abogados hablan "Control de cambios".

Adeu es un servidor del Protocolo de Contexto de Modelos (MCP) y un SDK de Python que actúa como un "DOM virtual" para Microsoft Word. Proporciona una capa de abstracción bidireccional que permite a los agentes de IA editar libremente el texto del documento sin destruir el formato subyacente o el complejo XML de DOCX.

Aunque las bibliotecas estándar como python-docx son excelentes para generar documentos desde cero, fallan en la revisión no destructiva. Adeu resuelve esto traduciendo archivos .docx a una representación Markdown eficiente en tokens. Esto libera a los agentes de IA para que se centren totalmente en la semántica del documento en lugar de desperdiciar tokens lidiando con OpenXML.

Adeu actúa como un proxy inteligente, procesando las ediciones de la IA como transacciones seguras y atómicas:

1. Extraer: Traduce el documento (desde el disco o Word en vivo) a CriticMarkup amigable para LLM con un Apéndice Semántico de términos definidos, referencias cruzadas y posibles errores tipográficos. El agente comienza con una estructura semántica, no con datos sin procesar.

2. Validar: Actúa como una puerta de seguridad estricta. Protege la integridad del documento bloqueando automáticamente coincidencias de texto ambiguas o cambios estructurales no válidos antes de que afecten al archivo.

3. Confirmar: Traduce las ediciones de texto de la IA al Control de cambios nativo de Word. Adeu maneja el complejo XML subyacente, asegurando que los diseños, fuentes y comentarios en los márgenes existentes se conserven perfectamente.

Mantenido por Adeu.

Configuración

Requisito previo: Adeu utiliza uv para una ejecución rápida y aislada. La forma más fácil de instalarlo es a través de 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"

Integración con Claude Desktop

Para añadir Adeu instantáneamente a Claude Desktop, ejecuta:

uvx adeu init

Verificar que funciona

Una vez que Claude Desktop se haya reiniciado, puedes confirmar que Adeu está conectado escribiendo el siguiente mensaje directamente en Claude:

"¿Puedes leer un archivo DOCX usando la herramienta Adeu?"

Si todo está configurado correctamente, Claude confirmará que tiene acceso a las herramientas de Adeu y describirá lo que puede hacer. Si no menciona a Adeu o dice que no tiene herramientas de archivo, verifica dos veces que reiniciaste Claude Desktop después de ejecutar uvx adeu init.

Debido a que Adeu requiere Python 3.12+, uvx manejará automáticamente la descarga de la versión correcta de Python y la ejecución del servidor:

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

Flujos de trabajo

1. Para agentes (Claude / MCP)

Adeu se ejecuta como un servidor del Protocolo de Contexto de Modelos (MCP). Proporciona a los agentes herramientas específicas para leer, revisar y editar documentos de forma segura.

UI de aplicaciones MCP: La herramienta read_docx es compatible con el protocolo de UI de aplicaciones MCP más reciente. Cuando un agente lee un documento, Adeu renderiza dinámicamente una vista de UI de Markdown personalizada e interactiva directamente dentro de tu ventana de chat de Claude, ¡permitiéndote revisar visualmente el texto extraído y el formato junto con el razonamiento de la IA!

Instrucciones recomendadas para el agente: Aunque las herramientas de Adeu describen automáticamente sus propios esquemas al LLM, puedes garantizar los mejores resultados de comportamiento añadiendo este contexto a las Instrucciones del proyecto de Claude o al Mensaje del sistema de tu agente:

Rol: Especialista en documentos Herramientas:

• read_docx(clean_view=True): Lee la versión "limpia" final del texto para entender el contexto.

• process_document_batch: Modo de confirmación y negociación. Aplica una lista unificada de cambios. Usa type: "modify" para ediciones de texto específicas de buscar y reemplazar, y type: "accept", "reject" o "reply" para gestionar el Control de cambios y comentarios existentes por ID.

• sanitize_docx: Limpieza previa al envío. Elimina metadatos peligrosos, nombres de autor e IDs de seguimiento internos antes de compartir. Puede conservar el marcado existente (keep_markup=True) o generar una diferencia limpia frente a una línea base.

Integración con MS Word en vivo

Si estás ejecutando en Windows con Microsoft Word instalado, Adeu puede actuar como un copiloto en tiempo real, editando el documento activo justo frente a ti.

• read_active_word_document: Extrae texto, cambios rastreados y comentarios directamente desde la ventana de Word abierta y activa.

• process_active_word_batch: Traduce las ediciones del LLM a macros COM nativas, observando cómo Word escribe, elimina y añade comentarios en el lienzo automáticamente.

2. Para desarrolladores (SDK de Python)

Si estás creando una aplicación de tecnología legal o una canalización automatizada, utiliza RedlineEngine directamente. Se encarga del trabajo pesado de la manipulación 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. La CLI

Inspecciona rápidamente documentos o aplica lotes de ediciones desde tu terminal.

# 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

Características clave

Seguridad de formato

Adeu no "reescribe" el documento. Lo parchea.

• Imágenes y diseños: Intactos.

• Numeración y encabezados: Conservados.

• Tablas y listas: Las combinaciones de celdas complejas y la numeración legal multinivel están explícitamente protegidas.

• XML complejo: Solo modifica los fragmentos de texto objetivo de la edición.

Representación CriticMarkup

Las representaciones intermedias importan. Adeu utiliza CriticMarkup para visualizar los cambios.

Apéndice semántico

Los contratos están llenos de minas terrestres que un LLM pasará por alto en una primera pasada: términos definidos usados de forma inconsistente, referencias cruzadas rotas y errores tipográficos estilo OCR en documentos desordenados. Adeu precalcula esto al extraer y entrega al agente un apéndice estructurado junto con el texto.

Mapeo inteligente

Los documentos de Word son desordenados. Una palabra como "Contrato" podría dividirse en fragmentos XML como ["Con", "trato"] debido al corrector ortográfico o al historial de formato.

• Coalescencia de fragmentos: Adeu normaliza estas divisiones para que la IA vea "Contrato".

• Coincidencia difusa: Maneja discrepancias menores de espacios en blanco entre la memoria del LLM y el contenido real del documento.

Sanitización de metadatos

Los limpiadores de metadatos existentes rompen las revisiones o eliminan datos silenciosamente. El comando sanitize de Adeu elimina quirúrgicamente los rastreadores peligrosos (rsids, plantillas, rutas internas, marcas de tiempo) y el contenido huérfano mientras conserva los cambios rastreados válidos. Fundamentalmente, genera un informe de auditoría transparente que demuestra exactamente qué se eliminó y qué será visible para el destinatario.

Adeu Cloud

Por defecto, el motor de revisión central de Adeu y las herramientas de archivos locales son totalmente de código abierto y se ejecutan completamente en tu máquina. Adeu nunca envía tus documentos locales a casa (aunque tu proveedor de LLM elegido procesará naturalmente el texto que lee el agente).

Sin embargo, puedes optar explícitamente por conectar tu servidor MCP a Adeu Cloud para desbloquear:

• Flujos de trabajo de extremo a extremo (correo electrónico): Debido a que los contratos viajan por correo electrónico, Adeu Cloud permite a los agentes obtener de forma segura hilos de correo electrónico, extraer archivos adjuntos DOCX de la contraparte para su revisión y redactar respuestas con tus nuevas revisiones sanitizadas adjuntas.

• Validación avanzada de documentos: Ejecuta tareas de validación semántica complejas y de múltiples documentos de forma asíncrona. Al enrutar de forma segura estos contextos masivos a Adeu Cloud para su procesamiento, evitas que tu agente de IA local agote su ventana de contexto o alcance los límites de tasa.

Aprende más sobre Adeu Cloud.

Contribución

¡Damos la bienvenida a las contribuciones de la comunidad! Ya sea corrigiendo errores, añadiendo capacidades o mejorando la documentación, consulta nuestra Guía de contribución para obtener instrucciones sobre cómo configurar el entorno local uv, ejecutar pruebas y comprender las estrictas directrices de seguridad XML del proyecto.

Licencia

Licencia MIT. Código abierto y de uso gratuito en aplicaciones comerciales.