# Contract redlining example

Change one payment term in an existing DOCX from **30** to **45** days, preserving
bold formatting and a separate reviewer's pending confidentiality revisions.
The agreement is fictional and is supplied only as an integration test fixture.

This example uses Vespper's DOCX MCP Server. It supplies two execution paths:

- Default: a fixed sequence of `search_document` and `edit_document` calls.
  Requires a Vespper API key, with Vespper usage billed to that account. No
  separate agent-model call is made; Vespper's service uses its own reconciler.
- `--agent`: an OpenAI Agents SDK agent chooses the tools for the same instruction.
  Also requires an OpenAI key and a model available to your account. Model usage
  is billed by the provider. Tracing is disabled; model requests still reach it.

## Setup

Use Python 3.10 or newer. From the extracted example directory:

```bash
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt
```

On Windows, activate with `.venv\Scripts\activate` instead.

Get a Vespper key from https://app.vespper.com and put it in a local `.env`:

```dotenv
VESPPER_API_KEY=your_key
```

Keep `.env` out of version control. You can supply a different file with
`--env-file /path/to/your.env`. Existing environment variables take precedence.

## Run the document integration

```bash
python redline_contract.py
```

This opens a session, searches for one unique payment clause, edits its current
HTML with tracking enabled, saves the returned bytes, checks the output, and
closes the session in `finally`. It writes:

- `service-agreement-redlined.docx`: the returned candidate document.
- `service-agreement-redlined.checks.json`: the structural verification report.

The process exits unsuccessfully if a check fails. A file existing on disk does
not mean verification passed. The script refuses to overwrite existing outputs;
use a different `--output` name to rerun it.

Recorded API outputs are in `results/`, so they do not conflict with these
default output filenames. To inspect the supplied result without an API key:

```bash
python verify_contract.py service-agreement.docx results/service-agreement-redlined.docx
```

## Run the agent

Add `OPENAI_API_KEY` and `OPENAI_MODEL` to `.env`, then:

```bash
python redline_contract.py --agent --output service-agreement-agent.docx
```

You can choose the model with `--model` instead of `OPENAI_MODEL`. The model
receives the server's current tool descriptions and this instruction:

> Change the payment term from 30 to 45 days. Preserve the number's bold
> formatting. Leave all other content and the Counterparty reviewer's
> pending confidentiality revisions unchanged.

## Check tracking disabled

```bash
python redline_contract.py --tracking-off --output service-agreement-direct.docx
```

Expect a direct payment-term replacement and no new text revisions. The
Counterparty reviewer's existing insertion and deletion must remain pending.

## Verify independently

The verifier uses only the Python standard library and needs no API key:

```bash
python verify_contract.py service-agreement.docx service-agreement-redlined.docx
python verify_contract.py service-agreement.docx service-agreement-direct.docx --tracking-off
```

It checks proposed and original text, native insertion/deletion markup,
revision author/date/ID preservation, bold payment terms, unedited body
structure, selected package-part bytes, and existing relationships.

`passed_with_normalization` means those checks pass, but the service added
matching `w:bCs` or `w:szCs` font properties to ASCII-only runs outside the
target. These additions are listed in the JSON; this is not byte-for-byte
preservation. The verifier permits only those additions when they match the
original `w:b` or `w:sz`. It still rejects conflicting values, non-ASCII run
normalization and other changes. Body comparisons also ignore Word's `rsid`
editing-session attributes. See `RESULTS.md` for the original stricter failures.

Open each output in Word as well. Check the payment clause with revisions
visible, inspect the table/list/image/header/footer, and accept or reject the
payment change on a copy. Confirm the confidentiality revisions remain pending.
The verifier is specific to this fixture and does not certify layout fidelity,
all revision types, or general DOCX validity.

## Validation status

On 29 September 2026, Vespper generated both recorded outputs through the
default MCP path. The tracked output passes 15 fixture checks and the direct
output passes 13, both with the normalization qualification above. The
one-page input and both outputs were rendered with LibreOffice and visually
inspected. Native Microsoft Word accept/reject interaction and the optional
agent-model path are not part of these recorded results.

`RESULTS.md` records the method and limits. `results/` contains the actual DOCX
outputs, current check reports and the initial strict check reports. These
are two runs on one small synthetic fixture, not a benchmark or a guarantee
for arbitrary customer documents. The input and API output files are unmodified.

Guide: https://www.vespper.com/guides/tracked-changes-api

API reference: https://docs.vespper.com/primitives/edit-document

Agent integration: https://docs.vespper.com/quickstart