Implementation Guide: Draft subcontractor agreements, change orders, and project closeout reports

Connect-MgGraph -Scopes 'User.ReadWrite.All','Group.ReadWrite.All','Policy.ReadWrite.ConditionalAccess'
New-MgGroup -DisplayName 'AI-ContractAdmins' -MailEnabled:$false -SecurityEnabled:$true -MailNickname 'ai-contractadmins'
New-MgGroup -DisplayName 'AI-ContractReviewers' -MailEnabled:$false -SecurityEnabled:$true -MailNickname 'ai-contractreviewers'
New-MgGroup -DisplayName 'AI-ContractSigners' -MailEnabled:$false -SecurityEnabled:$true -MailNickname 'ai-contractsigners'
# Assign M365 Business Premium licenses to all users via Entra ID group-based licensing
# Assign Copilot add-on licenses to AI-ContractAdmins group members
Set-MgGroupLicenseAssignment -GroupId <group-id> -AddLicenses @{SkuId='<copilot-sku-id>'}

# PowerShell using PnP.PowerShell module
Connect-PnPOnline -Url https://<tenant>.sharepoint.com -Interactive
New-PnPSite -Type TeamSite -Title 'Construction Contracts AI' -Alias 'contracts-ai' -Description 'AI-powered contract generation and management'
# Create document libraries
New-PnPList -Title 'Contract Templates' -Template DocumentLibrary
New-PnPList -Title 'Subcontractor Agreements' -Template DocumentLibrary
New-PnPList -Title 'Change Orders' -Template DocumentLibrary
New-PnPList -Title 'Closeout Reports' -Template DocumentLibrary
New-PnPList -Title 'Reference Documents' -Template DocumentLibrary
# Add metadata columns to Subcontractor Agreements library
Add-PnPField -List 'Subcontractor Agreements' -DisplayName 'Project Name' -InternalName 'ProjectName' -Type Text
Add-PnPField -List 'Subcontractor Agreements' -DisplayName 'Subcontractor' -InternalName 'SubcontractorName' -Type Text
Add-PnPField -List 'Subcontractor Agreements' -DisplayName 'Contract Status' -InternalName 'ContractStatus' -Type Choice -Choices 'Draft','AI Generated','In Review','Attorney Reviewed','Approved','Sent for Signature','Executed','Archived'
Add-PnPField -List 'Subcontractor Agreements' -DisplayName 'State Jurisdiction' -InternalName 'StateJurisdiction' -Type Choice -Choices 'AL','AK','AZ','AR','CA','CO','CT','DE','FL','GA','HI','ID','IL','IN','IA','KS','KY','LA','ME','MD','MA','MI','MN','MS','MO','MT','NE','NV','NH','NJ','NM','NY','NC','ND','OH','OK','OR','PA','RI','SC','SD','TN','TX','UT','VT','VA','WA','WV','WI','WY'
Add-PnPField -List 'Subcontractor Agreements' -DisplayName 'Contract Value' -InternalName 'ContractValue' -Type Currency
# Enable versioning
Set-PnPList -Identity 'Subcontractor Agreements' -EnableVersioning $true -MajorVersions 50 -EnableMinorVersions $true
# Set permissions - AI-ContractAdmins get Contribute, AI-ContractReviewers get Read, AI-ContractSigners get Contribute
Set-PnPGroupPermissions -Identity 'AI-ContractAdmins' -List 'Subcontractor Agreements' -AddRole 'Contribute'

# Scan paper documents with ScanSnap iX1600 - configure ScanSnap Home software:
# 1. Set scan profile: 'Contract Archive' - Color, Auto Resolution, Searchable PDF
# 2. Set destination: SharePoint Online > Construction Contracts AI > Reference Documents
# 3. Enable OCR: Language = English, Searchable PDF format

# Bulk upload digital templates via PnP PowerShell
$templates = Get-ChildItem -Path 'C:\ClientTemplates\SubcontractorAgreements\' -Filter *.docx
foreach ($template in $templates) {
    Add-PnPFile -Path $template.FullName -Folder 'Contract Templates/Subcontractor Agreements'
    Write-Host "Uploaded: $($template.Name)"
}

# Upload AIA forms (after client purchases AIA Unlimited subscription)
# AIA forms download as .docx from aiacontracts.com
Add-PnPFile -Path 'C:\AIA_Forms\A401-2017_SubcontractorAgreement.docx' -Folder 'Contract Templates/AIA Standard Forms'
Add-PnPFile -Path 'C:\AIA_Forms\G701-2017_ChangeOrder.docx' -Folder 'Contract Templates/AIA Standard Forms'
Add-PnPFile -Path 'C:\AIA_Forms\G704-2017_CertificateSubstantialCompletion.docx' -Folder 'Contract Templates/AIA Standard Forms'

# Install OpenAI Python library (on admin workstation or automation server)
pip install openai

# Test API connectivity with a simple construction contract prompt
python -c "
import openai
client = openai.OpenAI(api_key='sk-proj-XXXXXXXXXXXX')
response = client.chat.completions.create(
    model='gpt-5.4',
    messages=[
        {'role': 'system', 'content': 'You are a construction contract drafting assistant.'},
        {'role': 'user', 'content': 'Generate a one-paragraph scope of work clause for a drywall subcontractor on a commercial office building project.'}
    ],
    max_tokens=500
)
print(response.choices[0].message.content)
print(f'Tokens used: {response.usage.total_tokens}')
"

# Set monthly usage limit in OpenAI dashboard: Settings > Billing > Usage Limits
# Recommended: $200/month hard limit, $150/month soft limit (email alert)

# For Azure OpenAI alternative:
# az cognitiveservices account create --name construction-ai --resource-group rg-construction --kind OpenAI --sku S0 --location eastus2
# az cognitiveservices account deployment create --name construction-ai --resource-group rg-construction --deployment-name gpt-5.4 --model-name gpt-5.4 --model-version 2024-08-06 --model-format OpenAI --sku-capacity 30 --sku-name Standard

# 3. Test API connectivity:
curl -X GET 'https://api.procore.com/rest/v1.0/projects' \
  -H 'Authorization: Bearer <access_token>' \
  -H 'Procore-Company-Id: <company_id>'

# 4. Retrieve subcontractor data for a project:
curl -X GET 'https://api.procore.com/rest/v1.0/projects/<project_id>/vendors?filters[trade]=true' \
  -H 'Authorization: Bearer <access_token>' \
  -H 'Procore-Company-Id: <company_id>'

# 5. Retrieve commitment (subcontract) data:
curl -X GET 'https://api.procore.com/rest/v1.0/projects/<project_id>/commitments' \
  -H 'Authorization: Bearer <access_token>' \
  -H 'Procore-Company-Id: <company_id>'

# 6. Retrieve change order data:
curl -X GET 'https://api.procore.com/rest/v1.0/projects/<project_id>/change_order_packages' \
  -H 'Authorization: Bearer <access_token>' \
  -H 'Procore-Company-Id: <company_id>'

# Create and populate the State Compliance Clauses SharePoint list

# Create SharePoint List: 'State Compliance Clauses'
# Columns: State (choice), ClauseType (choice: Lien Waiver, Prevailing Wage, Retainage, Prompt Payment, Insurance Minimum, OSHA, Notice Requirement), ClauseText (multi-line text), Effective Date, Source (text), MandatoryInclusion (yes/no)

New-PnPList -Title 'State Compliance Clauses' -Template GenericList
Add-PnPField -List 'State Compliance Clauses' -DisplayName 'State' -InternalName 'State' -Type Choice -Choices 'AZ','CA','CO','FL','GA','IL','MI','MN','MO','NV','NY','NC','OH','OR','PA','TN','TX','UT','VA','WA','WI'
Add-PnPField -List 'State Compliance Clauses' -DisplayName 'Clause Type' -InternalName 'ClauseType' -Type Choice -Choices 'Lien Waiver','Prevailing Wage','Retainage Limit','Prompt Payment','Insurance Minimum','OSHA Compliance','Notice Requirement','Indemnification Limitation','Right to Cure','Dispute Resolution'
Add-PnPField -List 'State Compliance Clauses' -DisplayName 'Clause Text' -InternalName 'ClauseText' -Type Note
Add-PnPField -List 'State Compliance Clauses' -DisplayName 'Mandatory' -InternalName 'MandatoryInclusion' -Type Boolean

# Populate with state-specific clauses (example entries):
# State: CA, ClauseType: Lien Waiver, MandatoryInclusion: Yes
# ClauseText: 'This project is located in California. All lien waivers must comply with California Civil Code §8132-8138. Only the statutory forms (Conditional Waiver and Release on Progress Payment, Unconditional Waiver and Release on Progress Payment, Conditional Waiver and Release on Final Payment, Unconditional Waiver and Release on Final Payment) are valid. Any modification to the statutory language renders the waiver unenforceable.'

# State: TX, ClauseType: Retainage Limit, MandatoryInclusion: Yes
# ClauseText: 'Retainage on this subcontract shall not exceed ten percent (10%) of the contract sum per Texas Property Code §53.101. Retainage shall be released within the 30th day after the date the subcontractor completes its work scope, subject to the resolution of any outstanding punch list items.'

# checks SharePoint file metadata, required clauses, placeholder population,
# DocuSign envelope status, and document word count

python3 validate_pipeline.py --project-id <test_project_id> --doc-type subcontractor_agreement --check-all

# Python script for Zapier Code Step or standalone use

import openai
import json
from datetime import datetime

def generate_subcontractor_agreement(project_data: dict, sub_data: dict, state: str, api_key: str) -> str:
    client = openai.OpenAI(api_key=api_key)
    
    # Load state-specific clauses (from SharePoint API or local cache)
    state_clauses = get_state_clauses(state)  # Implement SharePoint Graph API call
    
    user_prompt = f"""Generate a complete Subcontractor Agreement with the following details:

PROJECT INFORMATION:
- Project Name: {project_data.get('name', '[REQUIRES INPUT]')}
- Project Address: {project_data.get('address', '[REQUIRES INPUT]')}
- Project Number: {project_data.get('number', '[REQUIRES INPUT]')}
- Owner: {project_data.get('owner_name', '[REQUIRES INPUT]')}
- Architect: {project_data.get('architect', '[REQUIRES INPUT]')}
- Project Type: {project_data.get('type', 'Commercial')}
- Is Public Works / Prevailing Wage: {project_data.get('prevailing_wage', 'No')}

CONTRACTOR (GC) INFORMATION:
- Company: {project_data.get('gc_name', '[REQUIRES INPUT]')}
- Address: {project_data.get('gc_address', '[REQUIRES INPUT]')}
- License Number: {project_data.get('gc_license', '[REQUIRES INPUT]')}

SUBCONTRACTOR INFORMATION:
- Company: {sub_data.get('name', '[REQUIRES INPUT]')}
- Address: {sub_data.get('address', '[REQUIRES INPUT]')}
- License Number: {sub_data.get('license_number', '[REQUIRES INPUT]')}
- Trade: {sub_data.get('trade', '[REQUIRES INPUT]')}

CONTRACT TERMS:
- Scope of Work: {sub_data.get('scope', '[REQUIRES INPUT]')}
- Contract Sum: ${sub_data.get('contract_value', '[REQUIRES INPUT]')}
- Contract Type: {sub_data.get('contract_type', 'Lump Sum')}
- Start Date: {sub_data.get('start_date', '[REQUIRES INPUT]')}
- Completion Date: {sub_data.get('end_date', '[REQUIRES INPUT]')}
- Retainage: {sub_data.get('retainage_pct', '10')}%
- Payment Terms: {sub_data.get('payment_terms', 'Net 30')}

STATE: {state}
STATE-SPECIFIC CLAUSES TO INCLUDE:
{state_clauses}

Generate the complete agreement following the document structure in your instructions."""
    
    response = client.chat.completions.create(
        model='gpt-5.4',
        messages=[
            {'role': 'system', 'content': SYSTEM_PROMPT},  # Use full system prompt above
            {'role': 'user', 'content': user_prompt}
        ],
        max_tokens=8000,
        temperature=0.3  # Low temperature for consistent, professional output
    )
    
    return response.choices[0].message.content

def get_state_clauses(state: str) -> str:
    """Retrieve state-specific clauses from SharePoint list via Microsoft Graph API"""
    import requests
    graph_url = f"https://graph.microsoft.com/v1.0/sites/{{site-id}}/lists/{{list-id}}/items?$filter=fields/State eq '{state}' and fields/MandatoryInclusion eq true&$expand=fields"
    headers = {'Authorization': f'Bearer {{access_token}}'}
    response = requests.get(graph_url, headers=headers)
    items = response.json().get('value', [])
    clauses = []
    for item in items:
        fields = item.get('fields', {})
        clauses.append(f"[{fields.get('ClauseType', '')}]: {fields.get('ClauseText', '')}")
    return '\n\n'.join(clauses)

def generate_change_order(change_event: dict, original_commitment: dict, project: dict, api_key: str) -> str:
    client = openai.OpenAI(api_key=api_key)
    
    # Calculate running totals
    original_sum = float(original_commitment.get('contract_sum', 0))
    previous_changes = float(original_commitment.get('approved_changes_total', 0))
    current_sum = original_sum + previous_changes
    this_change = float(change_event.get('amount', 0))
    new_sum = current_sum + this_change
    
    user_prompt = f"""Generate a Change Order document with these details:

PROJECT: {project.get('name')} (#{project.get('number')})
CONTRACTOR: {project.get('gc_name')}
SUBCONTRACTOR: {original_commitment.get('vendor_name')}
ORIGINAL SUBCONTRACT: #{original_commitment.get('number')} dated {original_commitment.get('date')}

CHANGE ORDER NUMBER: {change_event.get('co_number', '[NEXT SEQUENTIAL]')}
DATE: {datetime.now().strftime('%B %d, %Y')}

DESCRIPTION OF CHANGE:
{change_event.get('description', '[REQUIRES INPUT]')}

REASON FOR CHANGE: {change_event.get('reason', 'Owner/Architect directed change')}
TRIGGERED BY: {change_event.get('reference', 'Field condition / RFI #[NUMBER]')}

COST BREAKDOWN:
{json.dumps(change_event.get('cost_breakdown', {}), indent=2)}

TOTAL THIS CHANGE: ${this_change:,.2f}
SCHEDULE IMPACT: {change_event.get('schedule_impact_days', '[TO BE DETERMINED]')} days

CONTRACT ADJUSTMENTS:
- Original Contract Sum: ${original_sum:,.2f}
- Previous Approved Changes: ${previous_changes:,.2f}
- Current Contract Sum: ${current_sum:,.2f}
- This Change Order: ${this_change:,.2f}
- New Contract Sum: ${new_sum:,.2f}

Generate the complete change order document following the structure in your instructions."""
    
    response = client.chat.completions.create(
        model='gpt-5.4',
        messages=[
            {'role': 'system', 'content': CHANGE_ORDER_SYSTEM_PROMPT},
            {'role': 'user', 'content': user_prompt}
        ],
        max_tokens=4000,
        temperature=0.2
    )
    
    return response.choices[0].message.content

def generate_closeout_report(project_id: str, procore_token: str, api_key: str) -> str:
    import requests
    
    # Aggregate all project data from Procore
    headers = {'Authorization': f'Bearer {procore_token}', 'Procore-Company-Id': COMPANY_ID}
    base_url = 'https://api.procore.com/rest/v1.0'
    
    # Get project details
    project = requests.get(f'{base_url}/projects/{project_id}', headers=headers).json()
    
    # Get budget summary
    budget = requests.get(f'{base_url}/projects/{project_id}/budget/views', headers=headers).json()
    
    # Get all commitments (subcontracts)
    commitments = requests.get(f'{base_url}/projects/{project_id}/commitments', headers=headers).json()
    
    # Get change order packages
    change_orders = requests.get(f'{base_url}/projects/{project_id}/change_order_packages', headers=headers).json()
    
    # Get punch list items
    punch_items = requests.get(f'{base_url}/projects/{project_id}/punch_items', headers=headers).json()
    
    # Get RFI summary
    rfis = requests.get(f'{base_url}/projects/{project_id}/rfis', headers=headers).json()
    
    # Compile subcontractor status
    sub_status = []
    for commitment in commitments:
        sub_status.append({
            'name': commitment.get('vendor', {}).get('name', 'Unknown'),
            'trade': commitment.get('title', 'Unknown'),
            'original_value': commitment.get('grand_total', 0),
            'approved_cos': commitment.get('approved_change_orders_total', 0),
            'final_value': commitment.get('grand_total', 0) + commitment.get('approved_change_orders_total', 0),
            'paid': commitment.get('paid_to_date', 0),
            'retainage_held': commitment.get('retainage_held', 0)
        })
    
    # Compile punch list summary
    total_punch = len(punch_items)
    completed_punch = len([p for p in punch_items if p.get('status') == 'closed'])
    open_punch = total_punch - completed_punch
    
    user_prompt = f"""Generate a complete Project Closeout Report:

PROJECT DETAILS:
{json.dumps(project, indent=2, default=str)}

BUDGET SUMMARY:
{json.dumps(budget, indent=2, default=str)}

SUBCONTRACTOR STATUS:
{json.dumps(sub_status, indent=2, default=str)}

CHANGE ORDER SUMMARY:
Total COs: {len(change_orders)}
{json.dumps(change_orders[:20], indent=2, default=str)}

PUNCH LIST:
Total items: {total_punch}
Completed: {completed_punch}
Outstanding: {open_punch}
Open items: {json.dumps([p for p in punch_items if p.get('status') != 'closed'][:10], indent=2, default=str)}

RFI SUMMARY:
Total RFIs: {len(rfis)}
Open RFIs: {len([r for r in rfis if r.get('status') != 'closed'])}

Generate the complete closeout report following the structure in your instructions.
"""
    
    client = openai.OpenAI(api_key=api_key)
    response = client.chat.completions.create(
        model='gpt-5.4',
        messages=[
            {'role': 'system', 'content': CLOSEOUT_SYSTEM_PROMPT},
            {'role': 'user', 'content': user_prompt}
        ],
        max_tokens=8000,
        temperature=0.2
    )
    
    return response.choices[0].message.content

import re
from typing import List, Dict, Tuple

class ContractComplianceValidator:
    """Validates AI-generated construction documents for compliance."""
    
    # States with statutory lien waiver forms (MUST use exact statutory language)
    STATUTORY_LIEN_STATES = ['AZ', 'CA', 'FL', 'GA', 'MI', 'MS', 'MO', 'NV', 'TX', 'UT', 'WI', 'WY']
    
    # Minimum insurance requirements (configurable per client)
    DEFAULT_INSURANCE_MINS = {
        'gl_per_occurrence': 1000000,
        'gl_aggregate': 2000000,
        'auto_liability': 1000000,
        'workers_comp': 'statutory',
        'umbrella': 2000000
    }
    
    def __init__(self, state: str, is_prevailing_wage: bool = False, insurance_mins: dict = None):
        self.state = state.upper()
        self.is_prevailing_wage = is_prevailing_wage
        self.insurance_mins = insurance_mins or self.DEFAULT_INSURANCE_MINS
        self.findings: List[Dict] = []
    
    def validate(self, document_text: str, doc_type: str = 'subcontractor_agreement') -> Dict:
        """Run all applicable validations and return results."""
        self.findings = []
        
        # Universal checks
        self._check_unfilled_placeholders(document_text)
        self._check_draft_watermark(document_text)
        self._check_signature_blocks(document_text)
        self._check_governing_law(document_text)
        
        if doc_type == 'subcontractor_agreement':
            self._check_insurance_requirements(document_text)
            self._check_indemnification(document_text)
            self._check_lien_waiver_provisions(document_text)
            self._check_osha_compliance(document_text)
            self._check_retainage(document_text)
            self._check_payment_terms(document_text)
            self._check_dispute_resolution(document_text)
            self._check_termination_clauses(document_text)
            
            if self.is_prevailing_wage:
                self._check_davis_bacon(document_text)
            
            if self.state in self.STATUTORY_LIEN_STATES:
                self._check_statutory_lien_waiver(document_text)
        
        elif doc_type == 'change_order':
            self._check_co_financial_summary(document_text)
            self._check_co_authorization(document_text)
        
        elif doc_type == 'closeout_report':
            self._check_closeout_checklist(document_text)
            self._check_lien_waiver_status(document_text)
        
        # Determine overall result
        critical_findings = [f for f in self.findings if f['severity'] == 'CRITICAL']
        warning_findings = [f for f in self.findings if f['severity'] == 'WARNING']
        
        return {
            'passed': len(critical_findings) == 0,
            'total_findings': len(self.findings),
            'critical': len(critical_findings),
            'warnings': len(warning_findings),
            'findings': self.findings,
            'recommendation': 'BLOCK - Critical issues must be resolved' if critical_findings else 'PROCEED with review of warnings' if warning_findings else 'CLEAN - Ready for human review'
        }
    
    def _check_unfilled_placeholders(self, text: str):
        patterns = [
            r'\[REQUIRES INPUT[^\]]*\]',
            r'\[BLANK\]',
            r'\{\{[^}]+\}\}',
            r'\[TBD\]',
            r'\[INSERT[^\]]*\]',
            r'_____+',
            r'\[DATA NOT PROVIDED[^\]]*\]'
        ]
        for pattern in patterns:
            matches = re.findall(pattern, text, re.IGNORECASE)
            if matches:
                self.findings.append({
                    'severity': 'CRITICAL',
                    'category': 'Unfilled Placeholder',
                    'detail': f'Found {len(matches)} unfilled placeholders matching pattern: {matches[:3]}',
                    'action': 'Fill in all placeholder values before proceeding'
                })
    
    def _check_draft_watermark(self, text: str):
        if 'DRAFT' not in text.upper():
            self.findings.append({
                'severity': 'CRITICAL',
                'category': 'Missing Draft Watermark',
                'detail': 'Document does not contain DRAFT watermark',
                'action': 'Add DRAFT - AI GENERATED - REQUIRES LEGAL REVIEW header'
            })
    
    def _check_insurance_requirements(self, text: str):
        insurance_keywords = ['general liability', 'commercial general liability', 'workers compensation', 'automobile liability']
        missing = [kw for kw in insurance_keywords if kw not in text.lower()]
        if missing:
            self.findings.append({
                'severity': 'CRITICAL',
                'category': 'Missing Insurance Requirements',
                'detail': f'Missing insurance provisions for: {missing}',
                'action': 'Add complete insurance requirements section'
            })
        
        # Check minimum amounts
        gl_match = re.search(r'\$([\d,]+).*per occurrence', text, re.IGNORECASE)
        if gl_match:
            amount = int(gl_match.group(1).replace(',', ''))
            if amount < self.insurance_mins['gl_per_occurrence']:
                self.findings.append({
                    'severity': 'WARNING',
                    'category': 'Insurance Below Minimum',
                    'detail': f'GL per occurrence ${amount:,} is below minimum ${self.insurance_mins["gl_per_occurrence"]:,}',
                    'action': 'Verify insurance minimums with risk management'
                })
    
    def _check_lien_waiver_provisions(self, text: str):
        if 'lien waiver' not in text.lower() and 'lien release' not in text.lower():
            self.findings.append({
                'severity': 'CRITICAL',
                'category': 'Missing Lien Waiver Provisions',
                'detail': 'No lien waiver requirements found in document',
                'action': 'Add lien waiver requirements including state-specific statutory forms'
            })
    
    def _check_statutory_lien_waiver(self, text: str):
        state_references = {
            'CA': 'California Civil Code',
            'TX': 'Texas Property Code',
            'FL': 'Florida Statute',
            'AZ': 'Arizona Revised Statutes',
            'GA': 'Georgia Code'
        }
        if self.state in state_references:
            if state_references[self.state].lower() not in text.lower():
                self.findings.append({
                    'severity': 'CRITICAL',
                    'category': 'Missing Statutory Lien Waiver Reference',
                    'detail': f'{self.state} requires statutory lien waiver forms. Document does not reference {state_references[self.state]}.',
                    'action': f'Add {state_references[self.state]} statutory lien waiver form references and include forms as exhibit'
                })
    
    def _check_osha_compliance(self, text: str):
        if 'osha' not in text.lower() and 'occupational safety' not in text.lower():
            self.findings.append({
                'severity': 'WARNING',
                'category': 'Missing OSHA Compliance',
                'detail': 'No OSHA compliance clause found',
                'action': 'Add OSHA compliance and site safety requirements'
            })
    
    def _check_davis_bacon(self, text: str):
        db_terms = ['davis-bacon', 'prevailing wage', 'certified payroll', 'wage determination']
        missing = [term for term in db_terms if term not in text.lower()]
        if missing:
            self.findings.append({
                'severity': 'CRITICAL',
                'category': 'Missing Prevailing Wage Provisions',
                'detail': f'Prevailing wage project missing required terms: {missing}',
                'action': 'Add Davis-Bacon Act compliance clauses, prevailing wage requirements, and certified payroll obligations'
            })
    
    def _check_retainage(self, text: str):
        if 'retainage' not in text.lower() and 'retention' not in text.lower():
            self.findings.append({
                'severity': 'CRITICAL',
                'category': 'Missing Retainage Provisions',
                'detail': 'No retainage/retention terms found',
                'action': 'Add retainage percentage, release conditions, and state-specific limitations'
            })
    
    def _check_indemnification(self, text: str):
        if 'indemnif' not in text.lower():
            self.findings.append({
                'severity': 'WARNING',
                'category': 'Missing Indemnification',
                'detail': 'No indemnification clause found',
                'action': 'Add indemnification provisions compliant with state anti-indemnity statutes'
            })
    
    def _check_payment_terms(self, text: str):
        if 'payment' not in text.lower():
            self.findings.append({
                'severity': 'CRITICAL',
                'category': 'Missing Payment Terms',
                'detail': 'No payment provisions found',
                'action': 'Add payment application procedures, timing, and state prompt payment act compliance'
            })
    
    def _check_dispute_resolution(self, text: str):
        if not any(term in text.lower() for term in ['mediation', 'arbitration', 'dispute resolution']):
            self.findings.append({
                'severity': 'WARNING',
                'category': 'Missing Dispute Resolution',
                'detail': 'No dispute resolution mechanism found',
                'action': 'Add mediation/arbitration/litigation clause with venue and governing law'
            })
    
    def _check_termination_clauses(self, text: str):
        if 'terminat' not in text.lower():
            self.findings.append({
                'severity': 'WARNING',
                'category': 'Missing Termination Clause',
                'detail': 'No termination provisions found',
                'action': 'Add termination for cause and termination for convenience clauses'
            })
    
    def _check_governing_law(self, text: str):
        if 'governing law' not in text.lower() and 'governed by' not in text.lower():
            self.findings.append({
                'severity': 'WARNING',
                'category': 'Missing Governing Law',
                'detail': 'No governing law clause found',
                'action': 'Add governing law provision specifying project state'
            })
    
    def _check_signature_blocks(self, text: str):
        if 'signature' not in text.lower() and 'sign' not in text.lower():
            self.findings.append({
                'severity': 'CRITICAL',
                'category': 'Missing Signature Blocks',
                'detail': 'No signature blocks found',
                'action': 'Add proper signature blocks for all parties'
            })
    
    def _check_co_financial_summary(self, text: str):
        required_terms = ['original contract sum', 'new contract sum']
        missing = [term for term in required_terms if term not in text.lower()]
        if missing:
            self.findings.append({
                'severity': 'CRITICAL',
                'category': 'Missing Financial Summary',
                'detail': f'Change order missing required financial terms: {missing}',
                'action': 'Add complete contract adjustment summary showing original, previous changes, and new totals'
            })
    
    def _check_co_authorization(self, text: str):
        if 'authorized' not in text.lower() and 'written' not in text.lower():
            self.findings.append({
                'severity': 'WARNING',
                'category': 'Missing Authorization Reference',
                'detail': 'No written authorization reference found',
                'action': 'Add clause stating work shall not proceed until CO is fully executed'
            })
    
    def _check_closeout_checklist(self, text: str):
        required_items = ['lien waiver', 'warranty', 'as-built', 'punch list', 'certificate of occupancy']
        missing = [item for item in required_items if item not in text.lower()]
        if missing:
            self.findings.append({
                'severity': 'WARNING',
                'category': 'Incomplete Closeout Checklist',
                'detail': f'Closeout report missing references to: {missing}',
                'action': 'Ensure all standard closeout items are addressed'
            })
    
    def _check_lien_waiver_status(self, text: str):
        if 'lien waiver' not in text.lower():
            self.findings.append({
                'severity': 'CRITICAL',
                'category': 'Missing Lien Waiver Status',
                'detail': 'Closeout report does not address lien waiver collection status',
                'action': 'Add lien waiver status for every subcontractor and supplier'
            })


# Usage example:
validator = ContractComplianceValidator(state='CA', is_prevailing_wage=True)
results = validator.validate(document_text, doc_type='subcontractor_agreement')
print(json.dumps(results, indent=2))

import requests
import time
import json
from typing import Dict, List, Optional
from datetime import datetime

class ProcoreDataExtractor:
    """Extracts and transforms Procore project data for AI document generation."""
    
    BASE_URL = 'https://api.procore.com/rest/v1.0'
    RATE_LIMIT_DELAY = 0.5  # seconds between requests to avoid rate limits
    
    def __init__(self, access_token: str, company_id: str):
        self.headers = {
            'Authorization': f'Bearer {access_token}',
            'Procore-Company-Id': company_id,
            'Content-Type': 'application/json'
        }
        self.company_id = company_id
    
    def _get(self, endpoint: str, params: dict = None) -> dict:
        """Make authenticated GET request with rate limiting and error handling."""
        time.sleep(self.RATE_LIMIT_DELAY)
        url = f'{self.BASE_URL}{endpoint}'
        response = requests.get(url, headers=self.headers, params=params or {})
        
        if response.status_code == 429:  # Rate limited
            retry_after = int(response.headers.get('Retry-After', 60))
            time.sleep(retry_after)
            return self._get(endpoint, params)
        
        response.raise_for_status()
        return response.json()
    
    def get_project_details(self, project_id: str) -> Dict:
        """Get comprehensive project information."""
        project = self._get(f'/projects/{project_id}')
        return {
            'name': project.get('name', ''),
            'number': project.get('project_number', ''),
            'address': f"{project.get('address', '')} {project.get('city', '')}, {project.get('state_code', '')} {project.get('zip', '')}".strip(),
            'state': project.get('state_code', ''),
            'owner_name': project.get('owner', {}).get('name', '[REQUIRES INPUT]'),
            'start_date': project.get('start_date', ''),
            'completion_date': project.get('completion_date', ''),
            'project_type': project.get('project_type', {}).get('name', 'Commercial'),
            'status': project.get('status', {}).get('name', ''),
            'gc_name': project.get('company', {}).get('name', '[REQUIRES INPUT]'),
            'gc_address': '[FROM COMPANY SETTINGS]',
            'architect': project.get('architect', '[REQUIRES INPUT]')
        }
    
    def get_subcontractor_data(self, project_id: str, vendor_id: str) -> Dict:
        """Get subcontractor details for agreement generation."""
        vendor = self._get(f'/companies/{self.company_id}/vendors/{vendor_id}')
        return {
            'name': vendor.get('name', ''),
            'address': f"{vendor.get('address', '')} {vendor.get('city', '')}, {vendor.get('state_code', '')} {vendor.get('zip', '')}".strip(),
            'license_number': vendor.get('license_number', '[REQUIRES INPUT]'),
            'phone': vendor.get('phone', ''),
            'email': vendor.get('email_address', ''),
            'trade': vendor.get('trade_name', ''),
            'ein': vendor.get('tax_id', '[REQUIRES INPUT]')
        }
    
    def get_commitment_data(self, project_id: str, commitment_id: str) -> Dict:
        """Get commitment (subcontract) details for change orders."""
        commitment = self._get(f'/projects/{project_id}/commitments/{commitment_id}')
        return {
            'number': commitment.get('number', ''),
            'title': commitment.get('title', ''),
            'date': commitment.get('executed_date', commitment.get('created_at', '')[:10]),
            'vendor_name': commitment.get('vendor', {}).get('name', ''),
            'vendor_id': commitment.get('vendor', {}).get('id', ''),
            'contract_sum': commitment.get('grand_total', 0),
            'approved_changes_total': commitment.get('approved_change_orders_total', 0),
            'scope': commitment.get('description', ''),
            'status': commitment.get('status', ''),
            'retainage_pct': commitment.get('retainage_percent', 10)
        }
    
    def get_change_event_data(self, project_id: str, change_event_id: str) -> Dict:
        """Get change event details for change order generation."""
        ce = self._get(f'/projects/{project_id}/change_events/{change_event_id}')
        return {
            'title': ce.get('title', ''),
            'description': ce.get('description', ''),
            'amount': ce.get('grand_total', 0),
            'status': ce.get('status', ''),
            'reason': ce.get('change_reason', {}).get('name', 'Undetermined'),
            'reference': ce.get('number', ''),
            'schedule_impact_days': ce.get('schedule_impact', '[TO BE DETERMINED]'),
            'cost_breakdown': ce.get('line_items', [])
        }
    
    def get_closeout_data(self, project_id: str) -> Dict:
        """Aggregate all project data needed for closeout report."""
        project = self.get_project_details(project_id)
        
        # Get all commitments
        commitments = self._get(f'/projects/{project_id}/commitments')
        
        # Get all change order packages
        cos = self._get(f'/projects/{project_id}/change_order_packages')
        
        # Get punch items
        try:
            punch_items = self._get(f'/projects/{project_id}/punch_items', {'per_page': 500})
        except:
            punch_items = []
        
        # Get RFIs
        try:
            rfis = self._get(f'/projects/{project_id}/rfis', {'per_page': 500})
        except:
            rfis = []
        
        return {
            'project': project,
            'commitments': [{
                'vendor': c.get('vendor', {}).get('name', ''),
                'trade': c.get('title', ''),
                'original_value': c.get('grand_total', 0),
                'changes': c.get('approved_change_orders_total', 0),
                'final_value': c.get('grand_total', 0) + c.get('approved_change_orders_total', 0),
                'paid_to_date': c.get('paid_to_date', 0),
                'retainage_held': c.get('retainage_held', 0),
                'status': c.get('status', '')
            } for c in commitments],
            'change_orders': [{
                'number': co.get('number', ''),
                'title': co.get('title', ''),
                'amount': co.get('grand_total', 0),
                'status': co.get('status', '')
            } for co in cos],
            'punch_list': {
                'total': len(punch_items),
                'completed': len([p for p in punch_items if p.get('status', {}).get('name', '') == 'Closed']),
                'open_items': [{
                    'title': p.get('name', ''),
                    'assignee': p.get('assignee', {}).get('name', 'Unassigned'),
                    'due_date': p.get('due_date', 'No date')
                } for p in punch_items if p.get('status', {}).get('name', '') != 'Closed'][:20]
            },
            'rfis': {
                'total': len(rfis),
                'open': len([r for r in rfis if r.get('status', '') != 'closed'])
            }
        }


# Usage:
extractor = ProcoreDataExtractor(access_token='...', company_id='12345')
project_data = extractor.get_project_details('67890')
sub_data = extractor.get_subcontractor_data('67890', 'vendor_111')
closeout_data = extractor.get_closeout_data('67890')

import json
import logging
from datetime import datetime
from typing import Dict, Optional

logging.basicConfig(level=logging.INFO)
logger = logging.getLogger('DocumentOrchestrator')

class DocumentOrchestrator:
    """Orchestrates the complete AI document generation pipeline."""
    
    def __init__(self, config: Dict):
        self.openai_key = config['openai_api_key']
        self.procore_token = config['procore_access_token']
        self.procore_company_id = config['procore_company_id']
        self.graph_token = config['ms_graph_token']
        self.sharepoint_site_id = config['sharepoint_site_id']
        self.docusign_config = config.get('docusign', {})
        self.teams_webhook_url = config.get('teams_webhook_url', '')
        
        # Initialize sub-components
        from procore_data_extractor import ProcoreDataExtractor
        self.procore = ProcoreDataExtractor(self.procore_token, self.procore_company_id)
    
    def generate_document(self, doc_type: str, project_id: str, **kwargs) -> Dict:
        """Main entry point - generates any document type end-to-end."""
        logger.info(f'Starting {doc_type} generation for project {project_id}')
        result = {'status': 'started', 'doc_type': doc_type, 'timestamp': datetime.now().isoformat()}
        
        try:
            # Step 1: Extract data from Procore
            logger.info('Step 1: Extracting project data from Procore')
            project_data = self.procore.get_project_details(project_id)
            state = project_data.get('state', 'TX')  # Default to TX if not found
            
            # Step 2: Generate document based on type
            logger.info(f'Step 2: Generating {doc_type} via AI')
            if doc_type == 'subcontractor_agreement':
                vendor_id = kwargs.get('vendor_id')
                commitment_id = kwargs.get('commitment_id')
                sub_data = self.procore.get_subcontractor_data(project_id, vendor_id)
                commitment = self.procore.get_commitment_data(project_id, commitment_id)
                sub_data.update(commitment)
                document_text = generate_subcontractor_agreement(project_data, sub_data, state, self.openai_key)
                library = 'Subcontractor Agreements'
                filename = f"SubAgreement_{project_data['number']}_{sub_data['name']}_{datetime.now().strftime('%Y%m%d')}.docx"
            
            elif doc_type == 'change_order':
                change_event_id = kwargs.get('change_event_id')
                commitment_id = kwargs.get('commitment_id')
                change_data = self.procore.get_change_event_data(project_id, change_event_id)
                commitment = self.procore.get_commitment_data(project_id, commitment_id)
                document_text = generate_change_order(change_data, commitment, project_data, self.openai_key)
                library = 'Change Orders'
                filename = f"CO_{project_data['number']}_{change_data.get('reference', 'NEW')}_{datetime.now().strftime('%Y%m%d')}.docx"
            
            elif doc_type == 'closeout_report':
                closeout_data = self.procore.get_closeout_data(project_id)
                document_text = generate_closeout_report(project_id, self.procore_token, self.openai_key)
                library = 'Closeout Reports'
                filename = f"Closeout_{project_data['number']}_{datetime.now().strftime('%Y%m%d')}.docx"
            
            else:
                raise ValueError(f'Unknown document type: {doc_type}')
            
            result['generated'] = True
            
            # Step 3: Validate compliance
            logger.info('Step 3: Running compliance validation')
            is_prevailing = kwargs.get('is_prevailing_wage', False)
            validator = ContractComplianceValidator(state=state, is_prevailing_wage=is_prevailing)
            validation = validator.validate(document_text, doc_type)
            result['validation'] = validation
            
            if not validation['passed']:
                logger.warning(f'Validation FAILED with {validation["critical"]} critical findings')
                # Still save the document but flag it
                filename = f'REVIEW_NEEDED_{filename}'
            
            # Step 4: Save to SharePoint
            logger.info(f'Step 4: Uploading to SharePoint library: {library}')
            file_url = self._upload_to_sharepoint(library, filename, document_text, {
                'ContractStatus': 'AI Generated' if validation['passed'] else 'Needs Review',
                'ProjectName': project_data.get('name', ''),
                'StateJurisdiction': state
            })
            result['sharepoint_url'] = file_url
            
            # Step 5: Send Teams notification
            logger.info('Step 5: Sending Teams notification')
            self._notify_teams(
                title=f'New {doc_type.replace("_", " ").title()} Draft Generated',
                message=f'Project: {project_data["name"]}\nFile: {filename}\nValidation: {validation["recommendation"]}\n\n[Open Document]({file_url})',
                color='attention' if not validation['passed'] else 'good'
            )
            
            result['status'] = 'completed'
            result['filename'] = filename
            logger.info(f'Document generation complete: {filename}')
            
        except Exception as e:
            logger.error(f'Document generation failed: {str(e)}')
            result['status'] = 'failed'
            result['error'] = str(e)
            
            # Notify MSP of failure
            self._notify_teams(
                title=f'FAILED: {doc_type} Generation Error',
                message=f'Project: {project_id}\nError: {str(e)}\n\nMSP action required.',
                color='attention'
            )
        
        return result
    
    def _upload_to_sharepoint(self, library: str, filename: str, content: str, metadata: dict) -> str:
        """Upload document to SharePoint via Microsoft Graph API."""
        import requests
        
        # Convert text to docx (simplified - in production use python-docx)
        from docx import Document
        import io
        doc = Document()
        doc.add_heading('DRAFT - AI GENERATED - REQUIRES LEGAL REVIEW', level=0)
        for para in content.split('\n'):
            doc.add_paragraph(para)
        
        buffer = io.BytesIO()
        doc.save(buffer)
        buffer.seek(0)
        
        # Upload via Graph API
        upload_url = f'https://graph.microsoft.com/v1.0/sites/{self.sharepoint_site_id}/drive/root:/{library}/{filename}:/content'
        headers = {
            'Authorization': f'Bearer {self.graph_token}',
            'Content-Type': 'application/vnd.openxmlformats-officedocument.wordprocessingml.document'
        }
        response = requests.put(upload_url, headers=headers, data=buffer.read())
        response.raise_for_status()
        
        return response.json().get('webUrl', '')
    
    def _notify_teams(self, title: str, message: str, color: str = 'default'):
        """Send notification to Teams channel via webhook."""
        import requests
        if not self.teams_webhook_url:
            return
        
        payload = {
            '@type': 'MessageCard',
            'themeColor': '0076D7' if color == 'good' else 'FF0000',
            'summary': title,
            'sections': [{
                'activityTitle': title,
                'text': message,
                'markdown': True
            }]
        }
        requests.post(self.teams_webhook_url, json=payload)


# Configuration template for MSP deployment:
CONFIG_TEMPLATE = {
    'openai_api_key': 'sk-proj-XXXXX',  # Store in Azure Key Vault
    'procore_access_token': 'XXXXX',     # OAuth2 refresh token flow
    'procore_company_id': '12345',
    'ms_graph_token': 'XXXXX',           # App registration with Sites.ReadWrite.All
    'sharepoint_site_id': 'XXXXX',
    'teams_webhook_url': 'https://outlook.office.com/webhook/XXXXX',
    'docusign': {
        'account_id': 'XXXXX',
        'base_url': 'https://na4.docusign.net',
        'integration_key': 'XXXXX'
    }
}