◇ AI Contract Analyzer Python · PyMuPDF · Claude · YAML · Slack Project Blueprint
Contract Review

Know what you're signing, before you sign it.

Upload a contract and get back every clause in plain English — what it means, how risky it is, and the edit that would fix it. Two to four hours of review becomes ten minutes, and only the genuinely dangerous clauses need a person.

Below, the review pass, the clause playbook, and how it's built.
01

The Review Pass

Four steps, then a triage. Every clause gets scored; where it goes next depends on how much trouble it could cause.

📤 01 Ingest PDF · DOCX · scans 02 Split clause by clause 📑 03 Classify type + obligations 04 Score rules, then model high Escalate Suggest an edit medium Auto-approve low 📄 Report structured + PDF
you upload runs automatically comes back to a person
📤
01
Ingest
PDF, Word, or a scan of a signed page.
02
Split
The document becomes a list of clauses.
📑
03
Classify
Clause type, and who owes what by when.
04
Score
Playbook rules first, the model for the rest.
high → escalate to a person
medium → suggested edit
low → auto-approved
📄
all of it lands in one report
02

Inside Each Step

📤

01 Ingest the document

A contract goes in as a PDF or Word file through a simple upload. Text is extracted directly where the file has a text layer, and scanned pages fall back to OCR — which matters, because the contracts most likely to hide something are often the ones that arrive as a photograph of a signed page.

PyMuPDF · Tesseract OCR

02 Split into clauses

A deterministic splitter walks the document and cuts it on the things contracts actually use to mark a boundary: numbered headers, section and article labels, all-caps titles, and recital language. Each clause then travels as an independent unit — which is what stops a long agreement from quietly losing its last few clauses to a truncated model response.

deterministic splitter · no model in the loop
📑

03 Classify and extract

Every clause gets a type — indemnity, liability cap, termination, IP ownership, and the rest — and its obligations are pulled out in structured form: which party has to do what, by when, and on what condition. The obligations table is often more useful than the risk flags, because it answers the question people actually have after signing.

Claude API · clause type + obligations

04 Score the risk

Two stages, in order. A rules engine matches each clause against a clause library written in YAML, and a matched rule supplies its severity, its plain-English explanation, and its suggested edit directly — identical every run, with no model variance at all. Only the clauses no rule covers go to the model, and it decides with the playbook hits on the surrounding clauses as context.

YAML clause library → Claude API for the remainder
🔄

05 Route by severity

Low-risk clauses are approved automatically and stay in the record without asking for attention. Medium-risk clauses come back with a suggested redline and an explanation of why. High-risk clauses raise an alert, because some things should never be resolved by a summary — the point is to put a person in front of the three clauses that deserve one, not all forty.

Slack webhook · escalation alert
📄

06 Deliver the report

Two outputs from the same analysis: structured data for anything downstream, and a PDF built for reading. The report puts each clause's original text beside its plain-English explanation, its risk classification, and its suggested edit, and opens with a risk summary, the high-risk action items, flags for clauses that should be there but aren't, and the obligations table.

structured JSON · PDF comparison report
Why the rules run first

Deterministic where it can be, model where it must be.

Anything the clause library already knows about gets the same severity, wording, and suggested edit every single time it appears — which is what makes the output auditable and the review defensible. The model handles the long tail, where judgement is genuinely required. Reversing that order would be faster to build and much harder to trust.

03

The Clause Playbook

"Risky" isn't universal — it depends on which side of the contract you're on and what industry you're in. So it's configuration, not code.

DEFAULT
The base library, always loaded

Patterns that apply to any agreement — uncapped liability, one-sided indemnity, automatic renewal, assignment of work product. Every review starts here.

LAYERS
Industry playbooks stack on top

A SaaS vendor agreement and a US employment contract carry different traps. The relevant playbook is selected per review and layers over the default rather than replacing it.

ON MATCH
The rule supplies the whole verdict

Severity, classification, plain-English explanation, and the suggested edit all come from the rule itself. Same clause, same answer, every run — nothing is regenerated.

NO MATCH
The model takes the long tail

Clauses no rule covers get classified by the model, informed by which rules did fire on the clauses around them. Novel drafting still gets read; it just isn't the default path.

EXTENDING
A new rule is a file, not a release

Adding a risky pattern means writing a YAML entry in the playbooks folder. No deploy, no engineer, and clients can encode their own red lines directly.

04

Architecture

A deterministic spine with the model used only where judgement is actually needed.

Intake

PyMuPDF · Tesseract OCR

Pulls text out of PDFs and Word files, and falls back to OCR for scanned or photographed pages.

Splitter

deterministic · numbered headers · all-caps titles · recitals

Turns one long document into a list of independent clauses. Deliberately rule-based rather than model-driven, so the clause count is exact and nothing gets dropped off the end of a long agreement.

First pass

Rules engine

YAML clause library

Matches known risky patterns and returns a fixed verdict. Zero variance between runs, and the whole thing is editable without touching code.

The remainder

Claude API

classification · reasoning · edits

Handles clauses no rule covers, plus obligation extraction and the plain-English writing throughout.

Triage

Severity router

approve · suggest · escalate

Decides what each clause is worth: a silent approval, an edit in the report, or an alert that pulls in a human.

Output

structured JSON · PDF report · Slack alert

One analysis, three destinations: data for whatever comes next, a readable report for the person signing, and an alert for anything that shouldn't wait.

05

How It's Built

Six modular blocks. The clause library changes per client and per industry; the shape of the pass doesn't.

01

Intake

parsing

Text out of PDFs, Word files, and scans.

02

Splitter

segmentation

Cuts the document into clauses, deterministically.

03

Clause library

rules

YAML patterns defining what counts as risky.

04

Analyzer

reasoning

Types each clause and pulls out the obligations.

05

Router

triage

Approve, suggest an edit, or escalate.

06

Reporter

output

Structured data for systems, PDF for people.

06

Stack

Python PyMuPDF Tesseract OCR Claude API YAML playbooks Streamlit Slack