Lien Waiver Tracker

Overview

Track and manage lien waivers throughout the construction payment process. Ensure proper waivers are received before releasing payments, monitor waiver status by subcontractor, and minimize lien exposure.

Lien Waiver Types

┌─────────────────────────────────────────────────────────────────┐ │ LIEN WAIVER TYPES │ ├─────────────────────────────────────────────────────────────────┤ │ │ │ CONDITIONAL UNCONDITIONAL │ │ ─────────── ───────────── │ │ 📋 Progress - Conditional ✅ Progress - Unconditional │ │ Effective when paid Immediately effective │ │ Use with payment Use after check clears │ │ │ │ 📋 Final - Conditional ✅ Final - Unconditional │ │ For final payment For final payment │ │ Upon receipt of funds After funds received │ │ │ └─────────────────────────────────────────────────────────────────┘

Technical Implementation

from dataclasses import dataclass, field from typing import List, Dict, Optional from datetime import datetime, timedelta from enum import Enum

class WaiverType(Enum): CONDITIONAL_PROGRESS = "conditional_progress" UNCONDITIONAL_PROGRESS = "unconditional_progress" CONDITIONAL_FINAL = "conditional_final" UNCONDITIONAL_FINAL = "unconditional_final"

class WaiverStatus(Enum): REQUESTED = "requested" RECEIVED = "received" VERIFIED = "verified" REJECTED = "rejected" MISSING = "missing"

class PaymentStatus(Enum): PENDING = "pending" APPROVED = "approved" HELD = "held" RELEASED = "released"

@dataclass class Subcontractor: id: str name: str trade: str contract_amount: float contact_name: str contact_email: str tier: int = 1 # 1 = direct, 2 = sub-sub

@dataclass class LienWaiver: id: str subcontractor_id: str waiver_type: WaiverType payment_application: int # Pay app number through_date: datetime amount: float status: WaiverStatus = WaiverStatus.REQUESTED requested_date: datetime = field(default_factory=datetime.now) received_date: Optional[datetime] = None verified_by: str = "" file_path: str = "" notes: str = ""

@dataclass class PaymentApplication: number: int period_end: datetime subcontractor_id: str amount_requested: float amount_approved: float retainage: float status: PaymentStatus = PaymentStatus.PENDING waivers_complete: bool = False payment_date: Optional[datetime] = None

@dataclass class LienExposure: subcontractor_id: str subcontractor_name: str total_paid: float unconditional_waivers: float conditional_pending: float exposure: float

class LienWaiverTracker: """Track and manage construction lien waivers."""

def __init__(self, project_id: str, project_name: str):
    self.project_id = project_id
    self.project_name = project_name
    self.subcontractors: Dict[str, Subcontractor] = {}
    self.waivers: Dict[str, LienWaiver] = {}
    self.pay_apps: Dict[str, PaymentApplication] = {}

def add_subcontractor(self, id: str, name: str, trade: str,
                     contract_amount: float, contact_name: str,
                     contact_email: str, tier: int = 1) -> Subcontractor:
    """Add subcontractor to tracking."""
    sub = Subcontractor(
        id=id,
        name=name,
        trade=trade,
        contract_amount=contract_amount,
        contact_name=contact_name,
        contact_email=contact_email,
        tier=tier
    )
    self.subcontractors[id] = sub
    return sub

def create_payment_application(self, number: int, period_end: datetime,
                              subcontractor_id: str, amount_requested: float,
                              retainage_rate: float = 0.10) -> PaymentApplication:
    """Create payment application record."""
    if subcontractor_id not in self.subcontractors:
        raise ValueError(f"Subcontractor {subcontractor_id} not found")

    retainage = amount_requested * retainage_rate
    amount_approved = amount_requested - retainage

    pay_app = PaymentApplication(
        number=number,
        period_end=period_end,
        subcontractor_id=subcontractor_id,
        amount_requested=amount_requested,
        amount_approved=amount_approved,
        retainage=retainage
    )

    key = f"{subcontractor_id}-{number}"
    self.pay_apps[key] = pay_app

    # Create waiver request
    self.request_waiver(subcontractor_id, number, period_end, amount_approved)

    return pay_app

def request_waiver(self, subcontractor_id: str, pay_app_number: int,
                  through_date: datetime, amount: float,
                  waiver_type: WaiverType = WaiverType.CONDITIONAL_PROGRESS) -> LienWaiver:
    """Request lien waiver from subcontractor."""
    waiver_id = f"LW-{subcontractor_id}-{pay_app_number}"

    waiver = LienWaiver(
        id=waiver_id,
        subcontractor_id=subcontractor_id,
        waiver_type=waiver_type,
        payment_application=pay_app_number,
        through_date=through_date,
        amount=amount
    )

    self.waivers[waiver_id] = waiver
    return waiver

def receive_waiver(self, waiver_id: str, file_path: str,
                  verified_by: str = "") -> LienWaiver:
    """Record receipt of lien waiver."""
    if waiver_id not in self.waivers:
        raise ValueError(f"Waiver {waiver_id} not found")

    waiver = self.waivers[waiver_id]
    waiver.status = WaiverStatus.RECEIVED
    waiver.received_date = datetime.now()
    waiver.file_path = file_path
    waiver.verified_by = verified_by

    # Check if all waivers for pay app complete
    self._check_pay_app_waivers(waiver.subcontractor_id, waiver.payment_application)

    return waiver

def verify_waiver(self, waiver_id: str, verified_by: str) -> LienWaiver:
    """Verify waiver details are correct."""
    if waiver_id not in self.waivers:
        raise ValueError(f"Waiver {waiver_id} not found")

    waiver = self.waivers[waiver_id]
    waiver.status = WaiverStatus.VERIFIED
    waiver.verified_by = verified_by

    return waiver

def reject_waiver(self, waiver_id: str, reason: str) -> LienWaiver:
    """Reject waiver (incorrect amount, wrong form, etc.)."""
    if waiver_id not in self.waivers:
        raise ValueError(f"Waiver {waiver_id} not found")

    waiver = self.waivers[waiver_id]
    waiver.status = WaiverStatus.REJECTED
    waiver.notes = f"Rejected: {reason}"

    return waiver

def convert_to_unconditional(self, waiver_id: str, payment_date: datetime) -> LienWaiver:
    """Convert conditional waiver to unconditional after payment clears."""
    if waiver_id not in self.waivers:
        raise ValueError(f"Waiver {waiver_id} not found")

    waiver = self.waivers[waiver_id]

    # Create new unconditional waiver
    new_type = (WaiverType.UNCONDITIONAL_PROGRESS
               if waiver.waiver_type == WaiverType.CONDITIONAL_PROGRESS
               else WaiverType.UNCONDITIONAL_FINAL)

    return self.request_waiver(
        waiver.subcontractor_id,
        waiver.payment_application,
        waiver.through_date,
        waiver.amount,
        new_type
    )

def _check_pay_app_waivers(self, subcontractor_id: str, pay_app_number: int):
    """Check if all waivers for pay app are received."""
    key = f"{subcontractor_id}-{pay_app_number}"

    if key not in self.pay_apps:
        return

    pay_app = self.pay_apps[key]

    # Check all related waivers
    related_waivers = [
        w for w in self.waivers.values()
        if w.subcontractor_id == subcontractor_id
        and w.payment_application == pay_app_number
    ]

    pay_app.waivers_complete = all(
        w.status in [WaiverStatus.RECEIVED, WaiverStatus.VERIFIED]
        for w in related_waivers
    )

def calculate_exposure(self, subcontractor_id: str) -> LienExposure:
    """Calculate lien exposure for subcontractor."""
    if subcontractor_id not in self.subcontractors:
        raise ValueError(f"Subcontractor {subcontractor_id} not found")

    sub = self.subcontractors[subcontractor_id]

    # Sum payments
    total_paid = sum(
        pa.amount_approved for pa in self.pay_apps.values()
        if pa.subcontractor_id == subcontractor_id
        and pa.status == PaymentStatus.RELEASED
    )

    # Sum unconditional waivers
    unconditional = sum(
        w.amount for w in self.waivers.values()
        if w.subcontractor_id == subcontractor_id
        and w.waiver_type in [WaiverType.UNCONDITIONAL_PROGRESS, WaiverType.UNCONDITIONAL_FINAL]
        and w.status in [WaiverStatus.RECEIVED, WaiverStatus.VERIFIED]
    )

    # Sum conditional pending
    conditional = sum(
        w.amount for w in self.waivers.values()
        if w.subcontractor_id == subcontractor_id
        and w.waiver_type in [WaiverType.CONDITIONAL_PROGRESS, WaiverType.CONDITIONAL_FINAL]
        and w.status in [WaiverStatus.RECEIVED, WaiverStatus.VERIFIED]
    )

    # Exposure = Paid - Unconditional waivers
    exposure = total_paid - unconditional

    return LienExposure(
        subcontractor_id=subcontractor_id,
        subcontractor_name=sub.name,
        total_paid=total_paid,
        unconditional_waivers=unconditional,
        conditional_pending=conditional,
        exposure=exposure
    )

def get_missing_waivers(self) -> List[Dict]:
    """Get list of missing or pending waivers."""
    missing = []

    for waiver in self.waivers.values():
        if waiver.status in [WaiverStatus.REQUESTED, WaiverStatus.MISSING]:
            sub = self.subcontractors.get(waiver.subcontractor_id)
            missing.append({
                "waiver_id": waiver.id,
                "subcontractor": sub.name if sub else waiver.subcontractor_id,
                "pay_app": waiver.payment_application,
                "amount": waiver.amount,
                "type": waiver.waiver_type.value,
                "requested_date": waiver.requested_date,
                "days_outstanding": (datetime.now() - waiver.requested_date).days
            })

    return sorted(missing, key=lambda x: -x["days_outstanding"])

def get_waiver_status_by_sub(self, subcontractor_id: str) -> Dict:
    """Get waiver status summary for subcontractor."""
    if subcontractor_id not in self.subcontractors:
        raise ValueError(f"Subcontractor {subcontractor_id} not found")

    sub = self.subcontractors[subcontractor_id]

    waivers = [w for w in self.waivers.values() if w.subcontractor_id == subcontractor_id]

    by_status = {}
    for w in waivers:
        s = w.status.value
        by_status[s] = by_status.get(s, 0) + 1

    return {
        "subcontractor": sub.name,
        "total_waivers": len(waivers),
        "by_status": by_status,
        "total_amount": sum(w.amount for w in waivers),
        "verified_amount": sum(w.amount for w in waivers if w.status == WaiverStatus.VERIFIED)
    }

def can_release_payment(self, subcontractor_id: str, pay_app_number: int) -> Dict:
    """Check if payment can be released."""
    key = f"{subcontractor_id}-{pay_app_number}"

    if key not in self.pay_apps:
        return {"can_release": False, "reason": "Payment application not found"}

    pay_app = self.pay_apps[key]

    # Check for conditional waiver
    waivers = [
        w for w in self.waivers.values()
        if w.subcontractor_id == subcontractor_id
        and w.payment_application == pay_app_number
        and w.waiver_type == WaiverType.CONDITIONAL_PROGRESS
    ]

    if not waivers:
        return {"can_release": False, "reason": "No conditional waiver received"}

    for w in waivers:
        if w.status not in [WaiverStatus.RECEIVED, WaiverStatus.VERIFIED]:
            return {"can_release": False, "reason": f"Waiver {w.id} not verified"}

    return {"can_release": True, "reason": "All waivers verified", "amount": pay_app.amount_approved}

def generate_report(self) -> str:
    """Generate lien waiver status report."""
    lines = [
        "# Lien Waiver Status Report",
        "",
        f"**Project:** {self.project_name}",
        f"**Date:** {datetime.now().strftime('%Y-%m-%d')}",
        "",
        "## Summary",
        "",
        f"- Total Subcontractors: {len(self.subcontractors)}",
        f"- Total Waivers Tracked: {len(self.waivers)}",
        f"- Missing Waivers: {len(self.get_missing_waivers())}",
        "",
        "## Exposure by Subcontractor",
        "",
        "| Subcontractor | Paid | Unconditional | Exposure |",
        "|---------------|------|---------------|----------|"
    ]

    total_exposure = 0
    for sub_id in self.subcontractors:
        exposure = self.calculate_exposure(sub_id)
        total_exposure += exposure.exposure
        lines.append(
            f"| {exposure.subcontractor_name} | ${exposure.total_paid:,.0f} | "
            f"${exposure.unconditional_waivers:,.0f} | ${exposure.exposure:,.0f} |"
        )

    lines.extend([
        f"| **TOTAL** | | | **${total_exposure:,.0f}** |",
        "",
        "## Missing Waivers",
        ""
    ])

    missing = self.get_missing_waivers()
    if missing:
        lines.append("| Subcontractor | Pay App | Amount | Days Outstanding |")
        lines.append("|---------------|---------|--------|------------------|")
        for m in missing[:10]:
            lines.append(
                f"| {m['subcontractor']} | #{m['pay_app']} | "
                f"${m['amount']:,.0f} | {m['days_outstanding']} |"
            )
    else:
        lines.append("*No missing waivers*")

    return "\n".join(lines)

Quick Start

Initialize tracker

tracker = LienWaiverTracker("PRJ-001", "Office Tower")

Add subcontractors

tracker.add_subcontractor( "SUB-001", "ABC Mechanical", "HVAC", contract_amount=500000, contact_name="John Smith", contact_email="john@abcmech.com" )

tracker.add_subcontractor( "SUB-002", "XYZ Electric", "Electrical", contract_amount=350000, contact_name="Jane Doe", contact_email="jane@xyzelectric.com" )

Create payment applications

pa1 = tracker.create_payment_application( number=1, period_end=datetime.now(), subcontractor_id="SUB-001", amount_requested=50000 )

Receive waiver

waiver_id = f"LW-SUB-001-1" tracker.receive_waiver(waiver_id, "/waivers/sub001_pa1.pdf", "PM")

Check if can release payment

result = tracker.can_release_payment("SUB-001", 1) print(f"Can release: {result['can_release']} - {result['reason']}")

Calculate exposure

exposure = tracker.calculate_exposure("SUB-001") print(f"Lien exposure: ${exposure.exposure:,.2f}")

Generate report

print(tracker.generate_report())

Requirements

pip install (no external dependencies)