redline-buddy

Local-first contract red-flag checker. Paste in a vendor MSA, get a plain-language risk memo — with zero data leaving your machine.

Existing contract AI tools send your documents to someone else's LLM. redline-buddy is the opposite: deterministic, auditable YAML playbooks, pure-Python heuristics, no API keys, no network calls. What you lose in nuance you gain in privacy and predictability — and every finding links back to the exact rule that fired.

Not legal advice. Heuristic checks, not a lawyer's judgment. Treat the memo as a draft for attorney review.

Quickstart

pip install -e .
redline review examples/sample-msa.md
# no --playbook? redline auto-detects the best bundled playbook (clear winner
# only — ambiguous docs fall back to saas-vendor and say so on stderr)
# or with your own playbook:
redline review contract.pdf --playbook saas-vendor
# see the playbook ranking without reviewing:
redline suggest contract.pdf
# list all bundled playbooks:
redline playbooks
# batch review: point at a directory of contracts, get a summary table + per-file memos
# (omit --playbook and each file is auto-detected independently)
redline review ./contracts/
redline review ./contracts/ --playbook lease-tenant
# machine-readable output for CI gates:
redline review contract.pdf --format json | jq '.finding_count'
# fail CI when a high-or-worse finding appears:
redline review contract.pdf --fail-on high || echo "contract gate failed"
# fail CI when the risk grade drops below B:
redline review contract.pdf --fail-below B || echo "risk gate failed"
# minimal local web UI (paste text, pick a playbook, get the memo —
# or switch to drafting-hygiene mode):
redline serve
# the web UI now shows playbook descriptions in the picker, one-click
# "Copy fallback" buttons per finding, severity filters on memos, a
# "Download Word redline" link after every review, a "Download Word letter"
# link after every negotiation letter, and a round-2 follow-up mode (paste
# both drafts, get the follow-up letter plus a Word download)
# validate a playbook you wrote, optionally against a sample contract:
redline validate my-playbook.yaml --sample examples/sample-msa.md
# redline diff view: their language vs. your fallback, per finding:
redline review contract.pdf --format diff
# compare two negotiation rounds — what changed, what risk changed:
redline compare round1.pdf round2.pdf --playbook saas-vendor
# fail CI when the new draft introduces new high-or-worse red flags:
redline compare round1.pdf round2.pdf --fail-on-gain high
# Word redline with tracked changes — a counter-draft you can send back:
redline review contract.pdf --format docx   # writes contract.redline.docx
# compare two negotiation rounds — text changes plus flags gained/resolved/reworded:
redline compare round1.pdf round2.pdf
# round-2 follow-up letter — thank them for the concessions won, re-press what's still open:
redline followup round1.pdf round2.pdf --to "Acme Corp" --from "Alex" --format docx
# drafting-hygiene check — defined terms, cross-references, consistency:
redline hygiene contract.pdf
# fail CI when hygiene drops below medium:
redline hygiene contract.pdf --fail-on medium
# draft negotiation letter — turn the findings into change requests you can send:
redline letter contract.pdf --to "Acme Corp" --from "Alex" --format txt -o letter.txt
redline letter contract.pdf --to "Acme Corp" --from "Alex" --format docx   # sendable Word letter

Comparing negotiation rounds

Contracts move in rounds: the other side sends "draft v2" and you need to know what they quietly edited. redline compare diffs the two drafts at the paragraph level and re-runs the playbook on both, reporting:

• 🚨 New red flags — findings present in the new draft but not the old one (with the offending language, why it matters, and quotable fallback text),
• ✅ Resolved — findings the new draft fixed (their concessions),
• 🔁 Reworded but still flagged — a rule still fires, but on rewritten language (they redrafted the clause; it's still risky),
• 📝 Text changes — every paragraph added, removed, or reworded, as +/- diff hunks.

Use --format json for machine-readable output and --fail-on-gain high as a CI gate: fail the pipeline when a new round introduces new red flags at or above a severity. Add --format html for a shareable comparison page you can send to your attorney, or --format docx for a Word redline of the new draft — gained and reworded flags as tracked changes, concessions won, and paragraph-level text changes, ready to send back as your counter to their round. Try it on the bundled example:

redline compare examples/compare-round1.md examples/compare-round2.md

Negotiation letter

redline review tells you what's wrong; redline letter drafts what to send back. It turns each finding into a numbered change request — the contract's current language, the concern in plain words, and the playbook's quotable fallback text as proposed replacement language — addressed to the counterparty. --format txt gives you plain text for pasting into an email, --format docx gives you a sendable Word letter (date, addressee block, salutation, numbered change requests with quoted excerpts and proposed language, signature), and --min-severity keeps the letter focused (default: medium and up). The redline serve web UI offers the letter as a .docx download too, plus a round-2 follow-up mode that takes both drafts and returns the follow-up letter with its own Word download. The output is a starting draft for attorney review, not legal advice.

redline letter contract.pdf --to "Acme Corp" --from "Alex" --format txt -o letter.txt
redline letter contract.pdf --to "Acme Corp" --from "Alex" --format docx   # writes contract.letter.docx

When the counterparty sends back a revised draft, redline followup compares the two rounds and drafts the next letter for you: it thanks them for the concessions won (resolved findings), then re-presses everything still open — each change request tagged NEW IN THIS DRAFT, STILL FLAGGED AFTER REDRAFTING, or NOT ADDRESSED, worst-severity first. When nothing remains, it drafts the short ready-to-move-forward letter instead. Same --to/--from/--min-severity/--format options as letter (--format docx writes <new-draft>.followup.docx).

redline followup round1.pdf round2.pdf --to "Acme Corp" --from "Alex" --format docx

Drafting hygiene

Playbooks judge a contract's substance; redline hygiene judges its plumbing — whether the draft is internally consistent, regardless of which side you're on:

• dead definitions — a term is defined but never used again,
• undefined terms — a capitalized phrase is used 3+ times but never defined,
• inconsistent case — a defined Agreement also appears as lowercase agreement,
• defined twice — the same term gets two definitions,
• dangling references — Section 7.3 or Exhibit B points at a target that doesn't exist in the document,
• used before defined — the reader meets the term before its definition.

redline hygiene contract.pdf                 # human-readable report
redline hygiene contract.pdf --format json   # machine-readable, for CI gates
redline hygiene contract.pdf --fail-on medium

Try it on the bundled example: redline hygiene examples/hygiene-sample.md. The checks are deterministic heuristics, not legal analysis — every finding links back to the exact line that triggered it, so review each one in context.

How it works

1. A playbook (src/redline/playbooks/saas-vendor.yaml) declares rules: severity, plain-language explanation, and checks (requires_any, forbids_any, forbids_unless, max_value).
2. The review engine runs every rule against the contract text and collects findings with excerpts.
3. Findings render five ways: a markdown memo (default), JSON (--format json) for CI gates, a redline diff (--format diff) — each finding as a unified-diff hunk with the flagged contract language as - lines and quotable fallback clause language as + lines, ready to paste into your counter-draft — a Word redline (--format docx), the full contract as a .docx with each finding's flagged language struck through and the fallback inserted as real tracked changes (open Review → All Markup to accept/reject each edit, then send it back), or a self-contained HTML memo (--format html), a single file with inline CSS (no JS, no network) you can email to your attorney or save as a PDF from the browser.

Every rule carries a fallback: field: concrete, quotable clause language — not just advice — so the diff view gives you something you can actually propose back.

Optional LLM second reader

The deterministic engine is the default: offline, no API keys, nothing leaves your machine. Regex rules can still miss paraphrased clauses or get fooled by negations, so review accepts an opt-in second pass:

pip install "redline-buddy[llm]"   # adds litellm (optional dependency)
export OPENAI_API_KEY=...          # or ANTHROPIC_API_KEY, etc. — your key, your provider

redline review contract.md --playbook saas-vendor --second-reader gpt-4o-mini

The model re-reads the contract against the same playbook. Rule hits it independently flags are marked ✓ confirmed by second reader; genuinely new observations are appended as 🤖 second-reader observations (anything referencing an unknown rule, lacking a verbatim quote, or carrying a bogus severity is dropped — a hallucinating model must not invent findings).

⚠️ --second-reader sends your contract text to the model provider. Redact or skip it for documents you can't share. Single-file review only; batch mode ignores the flag with a warning. Output is still a first-pass draft for human attorney review — never legal advice.

Risk score

Every memo opens with a headline: Risk score: 63/100 · Grade C — a deterministic 0–100 score (critical findings cost 30 points, high 15, medium 7, low 3) mapped to ToS;DR-style letter grades (A ≥ 90, B ≥ 75, C ≥ 60, D ≥ 40, else F). It also appears in JSON output (risk_score, risk_grade), in the batch summary table, in the web UI banner, and — most usefully — in redline compare, which reports the risk delta between negotiation rounds (Risk: C (63) → B (78) — improved).

Playbooks

Write your own playbook in YAML — see src/redline/playbooks/saas-vendor.yaml for the schema, or scaffold one:

redline new-playbook equipment-lease --description "Lessee-side review of equipment leases."

Input formats

Markdown, plain text, .docx (Word), and PDF files are accepted — all text is extracted locally with no network calls.

Scanned/image-only PDFs are rejected with a clear error instead of silently reviewing nothing. Pass --ocr to run those pages through Tesseract OCR instead — it needs the tesseract and pdftoppm system binaries (e.g. apt install tesseract-ocr poppler-utils), still fully local, no extra Python packages. If a readable PDF contains pages with no extractable text, the memo notes which pages were skipped.

Development

pip install -e ".[dev]" 2>/dev/null || pip install -e .
python -m pytest

License

MIT — see LICENSE.