How to build an AI agent for contract redlining against a compliance playbook

export const PLAYBOOK_SCHEMA = {
  type: "object",
  properties: {
    payment_terms: {
      type: "object",
      description: "The clause stating how many days after invoice payment is due.",
      properties: {
        clause_text: { type: "string" },
        due_days: {
          type: "integer",
          description: "Number of days after invoice that payment is due.",
        },
      },
      required: ["clause_text", "due_days"],
    },
    liability_cap: {
      type: "object",
      description: "The clause capping total liability under the agreement.",
      properties: {
        clause_text: { type: "string" },
        cap_multiple_of_fees: {
          type: "number",
          description: "The liability cap expressed as a multiple of fees paid under the agreement.",
        },
      },
      required: ["clause_text", "cap_multiple_of_fees"],
    },
    governing_law: {
      type: "object",
      description: "The clause naming the jurisdiction whose law governs the agreement.",
      properties: {
        clause_text: { type: "string" },
        jurisdiction: { type: "string" },
      },
      required: ["clause_text", "jurisdiction"],
    },
  },
  required: ["payment_terms", "liability_cap", "governing_law"],
};

export type PlaybookRule = {
  field: keyof typeof PLAYBOOK_SCHEMA.properties;
  valueField: string;
  constraint: string;
  check: (value: string) => boolean;
  violationMessage: (extracted: any) => string;
};

export const PLAYBOOK_RULES: PlaybookRule[] = [
  {
    field: "payment_terms",
    valueField: "due_days",
    constraint: "Payment must be due within 30 days of the invoice date.",
    check: (value) => Number(value) <= 30,
    violationMessage: (v) => `Payment terms are ${v.due_days} days; playbook caps this at 30 days.`,
  },
  {
    field: "liability_cap",
    valueField: "cap_multiple_of_fees",
    constraint:
      "Liability is capped at two (2) times the fees paid under the agreement in the twelve months preceding the claim.",
    check: (value) => Number(value) <= 2,
    violationMessage: (v) => `Liability cap is ${v.cap_multiple_of_fees}x fees; playbook caps this at 2x.`,
  },
  {
    field: "governing_law",
    valueField: "jurisdiction",
    constraint: "The agreement is governed by the laws of the State of Delaware.",
    check: (value) => value.toLowerCase().includes("delaware"),
    violationMessage: (v) => `Governing law is ${v.jurisdiction}; playbook requires Delaware.`,
  },
];

import { PLAYBOOK_SCHEMA, PLAYBOOK_RULES } from "../../../lib/playbook";

const ENDPOINT = "https://api.nutrient.io/extraction/extract";

type TriageStatus = "compliant" | "violation" | "needs_review";

type TriageResult = {
  field: string;
  status: TriageStatus;
  clauseText: string;
  violationMessage: string;
  constraint: string;
};

export async function POST(req: Request) {
  const incoming = await req.formData();
  const file = incoming.get("file");
  if (!(file instanceof Blob)) {
    return Response.json({ error: "Missing file" }, { status: 400 });
  }

  const form = new FormData();
  form.append("file", file, "contract.docx");
  form.append(
    "instructions",
    JSON.stringify({
      schema: PLAYBOOK_SCHEMA,
      parseConfig: { mode: "understand" },
    }),
  );

  const response = await fetch(ENDPOINT, {
    method: "POST",
    headers: { Authorization: `Bearer ${process.env.NUTRIENT_DWS_API_KEY}` },
    body: form,
  });
  const result = await response.json();

  if (result.status !== 200) {
    return Response.json({ error: result.errorMessage }, { status: 502 });
  }

  const data = result.output.data;
  const results: TriageResult[] = [];

  for (const rule of PLAYBOOK_RULES) {
    const extracted = data[rule.field];
    const value = extracted?.[rule.valueField];

    if (value == null) {
      results.push({
        field: rule.field,
        status: "needs_review",
        clauseText: "",
        violationMessage: `Could not extract "${rule.field}" from the contract — route to manual review.`,
        constraint: rule.constraint,
      });
      continue;
    }

    if (rule.check(String(value))) {
      results.push({
        field: rule.field,
        status: "compliant",
        clauseText: extracted.clause_text,
        violationMessage: "",
        constraint: rule.constraint,
      });
      continue;
    }

    results.push({
      field: rule.field,
      status: "violation",
      clauseText: extracted.clause_text,
      violationMessage: rule.violationMessage(extracted),
      constraint: rule.constraint,
    });
  }

  return Response.json({ results });
}

import {
  createDocAuthSystem,
  type DocAuthEditor,
} from "@nutrient-sdk/document-authoring";
import { getAiToolkit } from "@nutrient-sdk/document-authoring-ai/editor";

export async function openAndLocate(
  host: HTMLElement,
  docxUrl: string,
  flaggedClauses: {
    field: string;
    clauseText: string;
    violationMessage: string;
    constraint: string;
  }[],
) {
  const system = await createDocAuthSystem();
  const document = await system.import(fetch(docxUrl), { fileName: "contract.docx" });
  const editor: DocAuthEditor = await system.createEditor(host, { document });
  editor.setEditorMode("review");
  editor.setAuthor("Compliance Agent");

  const toolkit = getAiToolkit(editor);

  // We already know what we're looking for, so we search for it
  // directly instead of asking the model to find it.
  const located = [];
  for (const clause of flaggedClauses) {
    const searched = await toolkit.executeTool({
      id: `locate-${clause.field}`,
      name: "search_elements",
      args: { query: clause.clauseText.slice(0, 60), kinds: ["paragraph"] },
    });

    const matches = searched.result.matches as { element: { id: string }; score: number; snippets: string[] }[];
    if (matches.length !== 1) {
      throw new Error(
        `Expected exactly one match for field "${clause.field}" in the live document, got ${matches.length}.`,
      );
    }

    located.push({ ...clause, elementId: matches[0].element.id });
  }

  return { system, editor, toolkit, located };
}

import { openai } from "@ai-sdk/openai";
import { generateText, Output } from "ai";
import { z } from "zod";

const DraftSchema = z.object({
  draftedText: z.string(),
});

export async function POST(req: Request) {
  const { clauseText, constraint } = await req.json();

  const result = await generateText({
    model: openai("gpt-5.4-mini"),
    system: `Draft a replacement contract clause that satisfies the given constraint. Preserve the original clause's structure, defined terms, and tone wherever the constraint doesn't require a change.`,
    prompt: `Original clause: "${clauseText}"\nConstraint: ${constraint}`,
    output: Output.object({ schema: DraftSchema }),
    temperature: 0.2,
  });

  return Response.json(result.output);
}

import { openai } from "@ai-sdk/openai";
import { generateText, Output } from "ai";
import { z } from "zod";

const VerifySchema = z.object({
  value: z.string(),
});

export async function POST(req: Request) {
  const { draftedText, constraint } = await req.json();

  const result = await generateText({
    model: openai("gpt-5.4-mini"),
    system: `Read the following contract clause on its own. State the single value in the clause that determines compliance with the given constraint — nothing else.`,
    prompt: `Clause: "${draftedText}"\nConstraint: ${constraint}`,
    output: Output.object({ schema: VerifySchema }),
    temperature: 0,
  });

  return Response.json(result.output);
}

import type { AiToolkit } from "@nutrient-sdk/document-authoring-ai/editor";
import { PLAYBOOK_RULES } from "../lib/playbook";

type LocatedClause = {
  field: string;
  elementId: string;
  clauseText: string;
  violationMessage: string;
  constraint: string;
};

export async function applyRedlines(toolkit: AiToolkit, located: LocatedClause[]) {
  const results = [];

  for (const clause of located) {
    const rule = PLAYBOOK_RULES.find((r) => r.field === clause.field);
    if (!rule) continue;

    const draftResponse = await fetch("/api/draft", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ clauseText: clause.clauseText, constraint: clause.constraint }),
    });
    const { draftedText } = await draftResponse.json();

    const verifyResponse = await fetch("/api/verify-draft", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ draftedText, constraint: clause.constraint }),
    });
    const { value } = await verifyResponse.json();

    if (!rule.check(value)) {
      // Either the independent read found a non-compliant value, or the
      // draft was ambiguous enough that the two model calls disagree with
      // what was intended. Either way, don't apply it — route to review.
      results.push({ field: clause.field, applied: false, reason: "draft_failed_validation" as const });
      continue;
    }

    const executed = await toolkit.executeTool(
      {
        id: crypto.randomUUID(),
        name: "replace_paragraph",
        args: {
          id: clause.elementId,
          text: draftedText,
          reviewComment: clause.violationMessage,
        },
      },
      {
        writeMode: "track_changes",
        reviewComments: "create",
      },
    );
    results.push({ field: clause.field, applied: true as const, executed });
  }

  return results;
}

import { openAndLocate } from "./locate-clauses";
import { applyRedlines } from "./apply-redlines";

export async function runRedlinePass(host: HTMLElement, docxUrl: string) {
  const docxBlob = await fetch(docxUrl).then((res) => res.blob());
  const triageForm = new FormData();
  triageForm.append("file", docxBlob, "contract.docx");

  const triageResponse = await fetch("/api/triage", { method: "POST", body: triageForm });
  const { results: triageResults } = await triageResponse.json();
  const flaggedClauses = triageResults.filter((r: { status: string }) => r.status === "violation");
  const needsReview = triageResults.filter((r: { status: string }) => r.status === "needs_review");

  if (flaggedClauses.length === 0) {
    // No violations doesn't mean "compliant" — a needs_review result means
    // triage couldn't positively evaluate a rule at all, which still needs
    // a human even though there's nothing to redline.
    return { status: needsReview.length === 0 ? ("compliant" as const) : ("needs_review" as const), needsReview };
  }

  const { toolkit, located } = await openAndLocate(host, docxUrl, flaggedClauses);
  const redlineResults = await applyRedlines(toolkit, located);
  return { status: "redlined" as const, results: redlineResults, needsReview };
}