Implementation Guide: Generate certificate of insurance documents and coverage comparison reports

az login
az group create --name rg-insurance-ai --location eastus2
az cognitiveservices account create --name oai-insurance-coi --resource-group rg-insurance-ai --kind OpenAI --sku S0 --location eastus2
az cognitiveservices account deployment create --name oai-insurance-coi --resource-group rg-insurance-ai --deployment-name gpt-5.4-mini --model-name gpt-5.4-mini --model-version 2024-07-18 --model-format OpenAI --sku-capacity 30 --sku-name Standard
az cognitiveservices account deployment create --name oai-insurance-coi --resource-group rg-insurance-ai --deployment-name gpt-5.4 --model-name gpt-5.4 --model-version 2024-08-06 --model-format OpenAI --sku-capacity 20 --sku-name Standard
az cognitiveservices account keys list --name oai-insurance-coi --resource-group rg-insurance-ai

az storage account create --name stinsuranceaidocs --resource-group rg-insurance-ai --location eastus2 --sku Standard_LRS --kind StorageV2
az storage container create --name generated-cois --account-name stinsuranceaidocs
az storage container create --name comparison-reports --account-name stinsuranceaidocs
az storage container create --name audit-logs --account-name stinsuranceaidocs
az storage container immutability-policy create --account-name stinsuranceaidocs --container-name audit-logs --period 365
az keyvault create --name kv-insurance-ai --resource-group rg-insurance-ai --location eastus2
az keyvault secret set --vault-name kv-insurance-ai --name azure-openai-key --value <YOUR_OPENAI_KEY>
az keyvault secret set --vault-name kv-insurance-ai --name docspring-api-key --value <YOUR_DOCSPRING_KEY>
az keyvault secret set --vault-name kv-insurance-ai --name ams-api-key --value <YOUR_AMS_API_KEY>

# For Applied Epic - example API authentication test
curl -X POST https://api.appliedsystems.com/oauth/token -d 'grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET'
# For HawkSoft - example API connectivity test
curl -X GET https://api.hawksoft.com/v2/policies -H 'Authorization: Bearer YOUR_API_KEY' -H 'Content-Type: application/json'
# Store AMS credentials in Key Vault
az keyvault secret set --vault-name kv-insurance-ai --name ams-client-id --value <AMS_CLIENT_ID>
az keyvault secret set --vault-name kv-insurance-ai --name ams-client-secret --value <AMS_CLIENT_SECRET>

# Install DocSpring CLI tool
npm install -g @docspring/cli
# Authenticate with DocSpring
docspring auth --api-token YOUR_API_TOKEN
# Upload ACORD 25 template (prepare the PDF with mapped fields first)
curl -X POST https://api.docspring.com/api/v1/templates -H 'Authorization: Basic YOUR_BASE64_CREDENTIALS' -F 'template[document]=@acord25_template.pdf' -F 'template[name]=ACORD 25 - Certificate of Liability Insurance'
# List templates to confirm upload
curl -X GET https://api.docspring.com/api/v1/templates -H 'Authorization: Basic YOUR_BASE64_CREDENTIALS'

# Clone the orchestration middleware repository
git clone https://github.com/your-msp/insurance-coi-ai-middleware.git
cd insurance-coi-ai-middleware
# Create Python virtual environment
python -m venv .venv
source .venv/bin/activate  # Linux/Mac
# .venv\Scripts\activate  # Windows
# Install dependencies
pip install -r requirements.txt
# requirements.txt includes:
# openai>=1.35.0
# azure-identity>=1.17.0
# azure-keyvault-secrets>=4.8.0
# azure-storage-blob>=12.20.0
# requests>=2.32.0
# fastapi>=0.111.0
# uvicorn>=0.30.0
# pydantic>=2.7.0
# python-docx>=1.1.0
# openpyxl>=3.1.0
# Create Azure Function App
az functionapp create --name func-insurance-coi --resource-group rg-insurance-ai --consumption-plan-location eastus2 --runtime python --runtime-version 3.11 --functions-version 4 --storage-account stinsuranceaidocs --os-type Linux
# Configure application settings
az functionapp config appsettings set --name func-insurance-coi --resource-group rg-insurance-ai --settings AZURE_OPENAI_ENDPOINT=https://oai-insurance-coi.openai.azure.com/ AZURE_OPENAI_KEY=@Microsoft.KeyVault(SecretUri=https://kv-insurance-ai.vault.azure.net/secrets/azure-openai-key/) DOCSPRING_API_KEY=@Microsoft.KeyVault(SecretUri=https://kv-insurance-ai.vault.azure.net/secrets/docspring-api-key/) AMS_API_KEY=@Microsoft.KeyVault(SecretUri=https://kv-insurance-ai.vault.azure.net/secrets/ams-api-key/)
# Enable managed identity for Key Vault access
az functionapp identity assign --name func-insurance-coi --resource-group rg-insurance-ai
# Grant Key Vault access to managed identity
az keyvault set-policy --name kv-insurance-ai --object-id <MANAGED_IDENTITY_OBJECT_ID> --secret-permissions get list
# Deploy the function app
func azure functionapp publish func-insurance-coi

az logic workflow create --name la-coi-intake --resource-group rg-insurance-ai --location eastus2 --definition @logic-app-definition.json

# Create Azure Static Web App for the review dashboard
az staticwebapp create --name swa-coi-review --resource-group rg-insurance-ai --location eastus2 --source https://github.com/your-msp/coi-review-dashboard --branch main --app-location /src --output-location /build
# The dashboard connects to the orchestration middleware API:
# GET /api/pending-reviews - List COIs awaiting review
# GET /api/coi/{id}/preview - Render PDF preview
# GET /api/coi/{id}/source-data - Show AMS source data
# GET /api/coi/{id}/validation - Show Patra AI check results
# POST /api/coi/{id}/approve - Approve and finalize
# POST /api/coi/{id}/reject - Reject with reason
# POST /api/coi/{id}/edit - Modify fields and regenerate

# Audit log schema (stored as JSON in Azure Blob Storage audit-logs container):
# {
#   'event_id': 'uuid',
#   'timestamp': 'ISO-8601',
#   'event_type': 'coi_generated | comparison_generated | coi_approved | coi_rejected',
#   'model_used': 'gpt-5.4-mini | gpt-5.4',
#   'input_data_hash': 'SHA-256 hash of input payload',
#   'output_document_hash': 'SHA-256 hash of generated PDF',
#   'policy_number': 'masked (last 4 digits only)',
#   'insured_name_hash': 'SHA-256 hash',
#   'patra_validation_score': 0.0-1.0,
#   'patra_warnings': ['list of flagged items'],
#   'reviewer_email': 'user@agency.com',
#   'review_timestamp': 'ISO-8601',
#   'review_decision': 'approved | rejected | edited',
#   'delivery_method': 'email | certificial | portal',
#   'recipient_email': 'holder@company.com'
# }
# Enable Azure Monitor diagnostic logging
az monitor diagnostic-settings create --name diag-coi-functions --resource /subscriptions/<SUB_ID>/resourceGroups/rg-insurance-ai/providers/Microsoft.Web/sites/func-insurance-coi --logs '[{"category":"FunctionAppLogs","enabled":true}]' --storage-account stinsuranceaidocs

# Run integration test suite
cd insurance-coi-ai-middleware
python -m pytest tests/integration/ -v --tb=short
# Test individual components:
python tests/test_ams_connection.py  # Verify AMS API connectivity
python tests/test_openai_extraction.py  # Verify field extraction accuracy
python tests/test_docspring_rendering.py  # Verify PDF generation
python tests/test_patra_validation.py  # Verify policy checking
python tests/test_audit_logging.py  # Verify compliance logging
# Generate a test COI
curl -X POST https://func-insurance-coi.azurewebsites.net/api/generate-coi -H 'Content-Type: application/json' -d '{"policy_number": "TEST-GL-001", "certificate_holder": {"name": "Test Holder LLC", "address": "123 Test St, Anytown, ST 12345"}, "additional_insured": true, "waiver_of_subrogation": true}'

# coi_orchestrator.py - Azure Durable Functions Orchestrator

import azure.functions as func
import azure.durable_functions as df
import json
import hashlib
import logging
from datetime import datetime, timezone

app = df.DFApp(http_auth_level=func.AuthLevel.FUNCTION)

# Orchestrator function
@app.orchestration_trigger(context_name='context')
def coi_generation_orchestrator(context: df.DurableOrchestrationContext):
    """Main orchestration workflow for COI generation."""
    request_data = context.get_input()
    
    # Step 1: Extract policy data from AMS
    policy_data = yield context.call_activity(
        'fetch_policy_from_ams',
        {
            'policy_number': request_data['policy_number'],
            'insured_name': request_data.get('insured_name'),
            'ams_type': request_data.get('ams_type', 'applied_epic')
        }
    )
    
    if not policy_data or policy_data.get('error'):
        yield context.call_activity('log_audit_event', {
            'event_type': 'coi_generation_failed',
            'reason': f"AMS data fetch failed: {policy_data.get('error', 'unknown')}",
            'request_data_hash': hashlib.sha256(json.dumps(request_data, sort_keys=True).encode()).hexdigest()
        })
        return {'status': 'error', 'message': 'Could not retrieve policy data from AMS'}
    
    # Step 2: Extract COI fields using GPT-5.4 mini
    coi_fields = yield context.call_activity(
        'extract_coi_fields_llm',
        {
            'policy_data': policy_data,
            'certificate_holder': request_data['certificate_holder'],
            'special_requirements': request_data.get('special_requirements', {})
        }
    )
    
    # Step 3: Validate with Patra AI
    validation_result = yield context.call_activity(
        'validate_with_patra',
        {
            'coi_fields': coi_fields,
            'policy_data': policy_data
        }
    )
    
    # Step 4: Generate PDF via DocSpring
    pdf_result = yield context.call_activity(
        'generate_coi_pdf',
        {
            'coi_fields': coi_fields,
            'form_type': request_data.get('form_type', 'acord_25'),
            'validation_warnings': validation_result.get('warnings', [])
        }
    )
    
    # Step 5: Store in Azure Blob and create review request
    storage_result = yield context.call_activity(
        'store_and_create_review',
        {
            'pdf_url': pdf_result['pdf_url'],
            'coi_fields': coi_fields,
            'validation_result': validation_result,
            'request_data': request_data
        }
    )
    
    # Step 6: Wait for human approval (with timeout)
    approval_event = yield context.wait_for_external_event(
        'coi_review_decision',
        timeout=timedelta(hours=24)
    )
    
    if approval_event and approval_event.get('decision') == 'approved':
        # Step 7: Deliver COI
        delivery_result = yield context.call_activity(
            'deliver_coi',
            {
                'pdf_url': pdf_result['pdf_url'],
                'certificate_holder_email': request_data['certificate_holder'].get('email'),
                'delivery_method': request_data.get('delivery_method', 'email'),
                'certificial_enabled': request_data.get('use_certificial', False)
            }
        )
        
        # Step 8: Update AMS activity log
        yield context.call_activity(
            'update_ams_activity',
            {
                'policy_number': request_data['policy_number'],
                'activity_type': 'COI Issued',
                'certificate_holder': request_data['certificate_holder']['name'],
                'document_url': pdf_result['pdf_url']
            }
        )
        
        # Step 9: Log audit event
        yield context.call_activity('log_audit_event', {
            'event_type': 'coi_approved_and_delivered',
            'model_used': 'gpt-5.4-mini',
            'input_data_hash': hashlib.sha256(json.dumps(policy_data, sort_keys=True).encode()).hexdigest(),
            'output_document_hash': pdf_result.get('document_hash'),
            'patra_validation_score': validation_result.get('score'),
            'reviewer_email': approval_event.get('reviewer_email'),
            'delivery_method': request_data.get('delivery_method', 'email')
        })
        
        return {'status': 'delivered', 'pdf_url': pdf_result['pdf_url']}
    
    elif approval_event and approval_event.get('decision') == 'rejected':
        yield context.call_activity('log_audit_event', {
            'event_type': 'coi_rejected',
            'reason': approval_event.get('reason', 'No reason provided'),
            'reviewer_email': approval_event.get('reviewer_email')
        })
        return {'status': 'rejected', 'reason': approval_event.get('reason')}
    
    else:
        # Timeout - escalate
        yield context.call_activity('send_escalation_notification', {
            'message': f"COI review timed out for policy {request_data['policy_number']}",
            'request_data': request_data
        })
        return {'status': 'timeout', 'message': 'Review timed out - escalated to manager'}


# Activity: Fetch policy data from AMS
@app.activity_trigger(input_name='input')
def fetch_policy_from_ams(input: dict) -> dict:
    import requests
    from azure.identity import DefaultAzureCredential
    from azure.keyvault.secrets import SecretClient
    
    credential = DefaultAzureCredential()
    kv_client = SecretClient(vault_url='https://kv-insurance-ai.vault.azure.net/', credential=credential)
    
    ams_type = input.get('ams_type', 'applied_epic')
    
    if ams_type == 'applied_epic':
        client_id = kv_client.get_secret('ams-client-id').value
        client_secret = kv_client.get_secret('ams-client-secret').value
        
        # Get OAuth token
        token_resp = requests.post(
            'https://api.appliedsystems.com/oauth/token',
            data={'grant_type': 'client_credentials', 'client_id': client_id, 'client_secret': client_secret}
        )
        token = token_resp.json()['access_token']
        
        # Fetch policy
        policy_resp = requests.get(
            f"https://api.appliedsystems.com/v1/policies/{input['policy_number']}",
            headers={'Authorization': f'Bearer {token}', 'Content-Type': 'application/json'}
        )
        return policy_resp.json()
    
    elif ams_type == 'hawksoft':
        api_key = kv_client.get_secret('ams-api-key').value
        policy_resp = requests.get(
            f"https://api.hawksoft.com/v2/policies/{input['policy_number']}",
            headers={'Authorization': f'Bearer {api_key}', 'Content-Type': 'application/json'}
        )
        return policy_resp.json()
    
    return {'error': f'Unsupported AMS type: {ams_type}'}


# Activity: Extract COI fields using LLM
@app.activity_trigger(input_name='input')
def extract_coi_fields_llm(input: dict) -> dict:
    from openai import AzureOpenAI
    from azure.identity import DefaultAzureCredential
    from azure.keyvault.secrets import SecretClient
    
    credential = DefaultAzureCredential()
    kv_client = SecretClient(vault_url='https://kv-insurance-ai.vault.azure.net/', credential=credential)
    api_key = kv_client.get_secret('azure-openai-key').value
    
    client = AzureOpenAI(
        api_key=api_key,
        api_version='2024-06-01',
        azure_endpoint='https://oai-insurance-coi.openai.azure.com/'
    )
    
    policy_text = json.dumps(input['policy_data'], indent=2)
    cert_holder = input['certificate_holder']
    special_reqs = input.get('special_requirements', {})
    
    # Use the COI Field Extraction Prompt (defined as separate component)
    system_prompt = """You are an expert insurance document processor specializing in Certificate of Insurance (COI) generation. Extract structured data from insurance policy information and return it in precise JSON format matching ACORD certificate form fields. Extract ONLY data explicitly stated. Never infer or fabricate. Set null for unavailable fields. Dates in MM/DD/YYYY. Monetary amounts as numbers only."""
    
    user_prompt = f"""Extract ACORD Certificate of Insurance fields from the following policy data.

Certificate Holder: {cert_holder.get('name')}, {cert_holder.get('address')}
Special Requirements: Additional Insured: {special_reqs.get('additional_insured', False)}, Waiver of Subrogation: {special_reqs.get('waiver_of_subrogation', False)}, Primary & Non-Contributory: {special_reqs.get('primary_noncontributory', False)}

Policy Data:
---
{policy_text}
---"""
    
    response = client.chat.completions.create(
        model='gpt-5.4-mini',
        messages=[
            {'role': 'system', 'content': system_prompt},
            {'role': 'user', 'content': user_prompt}
        ],
        temperature=0.1,
        max_tokens=4000,
        response_format={'type': 'json_object'}
    )
    
    return json.loads(response.choices[0].message.content)


# Activity: Generate PDF via DocSpring
@app.activity_trigger(input_name='input')
def generate_coi_pdf(input: dict) -> dict:
    import requests
    import base64
    from azure.identity import DefaultAzureCredential
    from azure.keyvault.secrets import SecretClient
    
    credential = DefaultAzureCredential()
    kv_client = SecretClient(vault_url='https://kv-insurance-ai.vault.azure.net/', credential=credential)
    api_key = kv_client.get_secret('docspring-api-key').value
    
    # Map form type to DocSpring template ID
    template_map = {
        'acord_25': 'tpl_XXXXXXXXXX',  # Replace with actual template IDs
        'acord_26': 'tpl_YYYYYYYYYY',
        'acord_125': 'tpl_ZZZZZZZZZZ'
    }
    
    template_id = template_map.get(input.get('form_type', 'acord_25'))
    coi_fields = input['coi_fields']
    
    # Map extracted fields to DocSpring template fields
    submission_data = {
        'producer_name': coi_fields.get('producer', {}).get('name'),
        'producer_address': coi_fields.get('producer', {}).get('address'),
        'insured_name': coi_fields.get('insured', {}).get('name'),
        'insured_address': coi_fields.get('insured', {}).get('address'),
        # ... map all fields per DocSpring template configuration
    }
    
    auth = base64.b64encode(f'{api_key}:'.encode()).decode()
    response = requests.post(
        f'https://api.docspring.com/api/v1/templates/{template_id}/submissions',
        headers={'Authorization': f'Basic {auth}', 'Content-Type': 'application/json'},
        json={'data': submission_data, 'wait': True}
    )
    
    result = response.json()
    pdf_url = result.get('submission', {}).get('download_url')
    
    # Calculate document hash for audit
    if pdf_url:
        pdf_content = requests.get(pdf_url).content
        doc_hash = hashlib.sha256(pdf_content).hexdigest()
    else:
        doc_hash = None
    
    return {'pdf_url': pdf_url, 'document_hash': doc_hash, 'submission_id': result.get('submission', {}).get('id')}


# HTTP trigger to start orchestration
@app.route(route='generate-coi', methods=['POST'])
@app.durable_client_input(client_name='client')
async def http_start_coi(req: func.HttpRequest, client: df.DurableOrchestrationClient):
    request_body = req.get_json()
    
    # Validate required fields
    required = ['policy_number', 'certificate_holder']
    for field in required:
        if field not in request_body:
            return func.HttpResponse(json.dumps({'error': f'Missing required field: {field}'}), status_code=400)
    
    instance_id = await client.start_new('coi_generation_orchestrator', None, request_body)
    
    return client.create_check_status_response(req, instance_id)


# HTTP trigger for review decisions
@app.route(route='coi/{instance_id}/review', methods=['POST'])
@app.durable_client_input(client_name='client')
async def submit_review(req: func.HttpRequest, client: df.DurableOrchestrationClient):
    instance_id = req.route_params['instance_id']
    decision = req.get_json()
    
    await client.raise_event(instance_id, 'coi_review_decision', decision)
    
    return func.HttpResponse(json.dumps({'status': 'review submitted'}), status_code=200)

# ams_field_mapper.py

import json
from typing import Dict, Optional, Any

# Field mapping configurations for each AMS platform
AMS_FIELD_MAPPINGS = {
    'applied_epic': {
        'insured_name': 'policy.namedInsured.fullName',
        'insured_address': 'policy.namedInsured.address.streetAddress',
        'insured_city': 'policy.namedInsured.address.city',
        'insured_state': 'policy.namedInsured.address.state',
        'insured_zip': 'policy.namedInsured.address.zipCode',
        'policy_number': 'policy.policyNumber',
        'effective_date': 'policy.effectiveDate',
        'expiration_date': 'policy.expirationDate',
        'carrier_name': 'policy.carrier.name',
        'carrier_naic': 'policy.carrier.naicCode',
        'line_of_business': 'policy.lineOfBusiness',
        'gl_each_occurrence': 'policy.coverages[?type=GL].limits.eachOccurrence',
        'gl_general_aggregate': 'policy.coverages[?type=GL].limits.generalAggregate',
        'gl_products_comp_op': 'policy.coverages[?type=GL].limits.productsCompletedOps',
        'gl_personal_adv_injury': 'policy.coverages[?type=GL].limits.personalAdvertisingInjury',
        'gl_damage_rented_premises': 'policy.coverages[?type=GL].limits.damageRentedPremises',
        'gl_medical_expense': 'policy.coverages[?type=GL].limits.medicalExpense',
        'auto_combined_single_limit': 'policy.coverages[?type=AUTO].limits.combinedSingleLimit',
        'auto_bodily_injury_person': 'policy.coverages[?type=AUTO].limits.bodilyInjuryPerPerson',
        'auto_bodily_injury_accident': 'policy.coverages[?type=AUTO].limits.bodilyInjuryPerAccident',
        'auto_property_damage': 'policy.coverages[?type=AUTO].limits.propertyDamage',
        'wc_statutory': 'policy.coverages[?type=WC].limits.statutory',
        'wc_el_each_accident': 'policy.coverages[?type=WC].limits.elEachAccident',
        'wc_el_disease_employee': 'policy.coverages[?type=WC].limits.elDiseaseEachEmployee',
        'wc_el_disease_policy': 'policy.coverages[?type=WC].limits.elDiseasePolicyLimit',
        'umbrella_each_occurrence': 'policy.coverages[?type=UMBRELLA].limits.eachOccurrence',
        'umbrella_aggregate': 'policy.coverages[?type=UMBRELLA].limits.aggregate',
        'endorsements': 'policy.endorsements[*]',
        'additional_insureds': 'policy.additionalInsureds[*]',
        'description_of_operations': 'policy.descriptionOfOperations'
    },
    'hawksoft': {
        'insured_name': 'PolicyInfo.InsuredName',
        'insured_address': 'PolicyInfo.InsuredAddress.Street',
        'insured_city': 'PolicyInfo.InsuredAddress.City',
        'insured_state': 'PolicyInfo.InsuredAddress.State',
        'insured_zip': 'PolicyInfo.InsuredAddress.Zip',
        'policy_number': 'PolicyInfo.PolicyNumber',
        'effective_date': 'PolicyInfo.EffDate',
        'expiration_date': 'PolicyInfo.ExpDate',
        'carrier_name': 'PolicyInfo.CompanyName',
        'carrier_naic': 'PolicyInfo.NAICCode',
        'line_of_business': 'PolicyInfo.LOB',
        'gl_each_occurrence': 'Coverages.GL.EachOccurrence',
        'gl_general_aggregate': 'Coverages.GL.GenAggregate',
        'gl_products_comp_op': 'Coverages.GL.ProdCompOps',
        'gl_personal_adv_injury': 'Coverages.GL.PersAdvInjury',
        'gl_damage_rented_premises': 'Coverages.GL.DmgRentedPrem',
        'gl_medical_expense': 'Coverages.GL.MedExpense',
        'auto_combined_single_limit': 'Coverages.Auto.CSL',
        'wc_el_each_accident': 'Coverages.WC.ELEachAccident',
        'wc_el_disease_employee': 'Coverages.WC.ELDiseaseEmployee',
        'wc_el_disease_policy': 'Coverages.WC.ELDiseasePolicyLimit',
        'umbrella_each_occurrence': 'Coverages.Umbrella.EachOccurrence',
        'umbrella_aggregate': 'Coverages.Umbrella.Aggregate',
        'endorsements': 'Endorsements[*]',
        'additional_insureds': 'AdditionalInsureds[*]',
        'description_of_operations': 'PolicyInfo.DescOfOps'
    },
    'ams360': {
        'insured_name': 'Policy.Customer.Name',
        'insured_address': 'Policy.Customer.Address1',
        'insured_city': 'Policy.Customer.City',
        'insured_state': 'Policy.Customer.State',
        'insured_zip': 'Policy.Customer.ZipCode',
        'policy_number': 'Policy.PolicyNumber',
        'effective_date': 'Policy.EffectiveDate',
        'expiration_date': 'Policy.ExpirationDate',
        'carrier_name': 'Policy.Company.CompanyName',
        'carrier_naic': 'Policy.Company.NAICNumber',
        'line_of_business': 'Policy.PolicyType',
        'gl_each_occurrence': 'Policy.Limits.GLEachOccurrence',
        'gl_general_aggregate': 'Policy.Limits.GLGeneralAggregate',
        'endorsements': 'Policy.Endorsements[*]',
        'additional_insureds': 'Policy.AdditionalInsureds[*]',
        'description_of_operations': 'Policy.DescriptionOfOperations'
    }
}

def resolve_nested_path(data: dict, path: str) -> Any:
    """Resolve a dot-notation path with array support against a nested dict."""
    parts = path.split('.')
    current = data
    for part in parts:
        if current is None:
            return None
        if '[*]' in part:
            key = part.replace('[*]', '')
            current = current.get(key, [])
        elif '[?' in part:
            # Simple filter: field[?type=VALUE].rest
            key = part.split('[?')[0]
            filter_expr = part.split('[?')[1].rstrip(']')
            filter_key, filter_val = filter_expr.split('=')
            items = current.get(key, [])
            current = next((item for item in items if item.get(filter_key) == filter_val), None)
        else:
            current = current.get(part) if isinstance(current, dict) else None
    return current

def map_ams_to_standard(ams_data: dict, ams_type: str) -> dict:
    """Map AMS-specific field structure to standardized schema."""
    mapping = AMS_FIELD_MAPPINGS.get(ams_type)
    if not mapping:
        raise ValueError(f'Unsupported AMS type: {ams_type}')
    
    result = {}
    for standard_field, ams_path in mapping.items():
        result[standard_field] = resolve_nested_path(ams_data, ams_path)
    
    return result

def get_supported_ams_types() -> list:
    return list(AMS_FIELD_MAPPINGS.keys())

# Usage:
# standardized = map_ams_to_standard(raw_epic_data, 'applied_epic')
# standardized = map_ams_to_standard(raw_hawksoft_data, 'hawksoft')

# Email intake agent with Azure OpenAI integration and validation logic

# coi_email_parser.py - Email intake agent

import json
import re
from openai import AzureOpenAI
from azure.identity import DefaultAzureCredential
from azure.keyvault.secrets import SecretClient
from typing import Dict, Optional

EMAIL_PARSER_SYSTEM_PROMPT = """You are an insurance agency's COI request intake specialist. Parse incoming emails requesting Certificates of Insurance and extract structured data.

Extract the following from the email:
1. certificate_holder_name: The entity requesting the COI (the party that needs proof of insurance)
2. certificate_holder_address: Full mailing address of the certificate holder
3. certificate_holder_email: Email to send the completed COI to
4. insured_name: The agency's client who needs the COI (the insured party)
5. policy_number: If referenced (may not be in the email)
6. coverage_types_requested: List of coverage types needed (GL, Auto, WC, Umbrella, Property)
7. special_requirements: Object with boolean flags:
   - additional_insured: Is the certificate holder requesting to be added as additional insured?
   - waiver_of_subrogation: Is waiver of subrogation requested?
   - primary_noncontributory: Is primary & non-contributory status requested?
   - specific_limits: Any minimum limit requirements mentioned
8. project_description: Description of the project/contract the COI is for (for Description of Operations field)
9. urgency: 'standard' (24hr), 'rush' (4hr), or 'immediate' (1hr) based on language used
10. request_type: 'new_coi', 'update_existing', 'renewal', or 'additional_insured_add'

RULES:
- If a field is not mentioned in the email, set it to null
- For coverage types, infer from context (e.g., 'general liability and auto' = ['GL', 'Auto'])
- Look for contractual language indicating special requirements (e.g., 'must be named as additional insured')
- Flag urgency based on words like 'ASAP', 'urgent', 'needed today', 'rush'
- If the email is unclear or you cannot determine the insured, set confidence to 'low'

Return ONLY valid JSON."""

class COIEmailParser:
    def __init__(self):
        credential = DefaultAzureCredential()
        kv_client = SecretClient(
            vault_url='https://kv-insurance-ai.vault.azure.net/',
            credential=credential
        )
        api_key = kv_client.get_secret('azure-openai-key').value
        
        self.llm_client = AzureOpenAI(
            api_key=api_key,
            api_version='2024-06-01',
            azure_endpoint='https://oai-insurance-coi.openai.azure.com/'
        )
    
    def parse_email(self, subject: str, body: str, sender: str) -> Dict:
        """Parse an incoming COI request email into structured data."""
        user_prompt = f"""Parse this COI request email:

From: {sender}
Subject: {subject}

Body:
{body}"""
        
        response = self.llm_client.chat.completions.create(
            model='gpt-5.4-mini',
            messages=[
                {'role': 'system', 'content': EMAIL_PARSER_SYSTEM_PROMPT},
                {'role': 'user', 'content': user_prompt}
            ],
            temperature=0.1,
            max_tokens=2000,
            response_format={'type': 'json_object'}
        )
        
        parsed = json.loads(response.choices[0].message.content)
        parsed['original_sender'] = sender
        parsed['original_subject'] = subject
        parsed['parse_model'] = 'gpt-5.4-mini'
        
        return parsed
    
    def validate_parsed_request(self, parsed: Dict) -> Dict:
        """Validate parsed data and determine if human intervention is needed."""
        issues = []
        
        if not parsed.get('insured_name'):
            issues.append('Could not determine insured name from email')
        if not parsed.get('certificate_holder_name'):
            issues.append('Could not determine certificate holder')
        if not parsed.get('coverage_types_requested'):
            issues.append('No coverage types identified')
        if parsed.get('confidence') == 'low':
            issues.append('Low confidence parse - manual review recommended')
        
        return {
            'is_valid': len(issues) == 0,
            'issues': issues,
            'can_auto_process': len(issues) == 0 and parsed.get('urgency') != 'immediate',
            'parsed_data': parsed
        }

# Integration with Power Automate / Azure Logic App:
# This class is called by an Azure Function HTTP trigger
# that receives webhook calls from the M365 email flow.
# POST /api/parse-coi-email
# Body: { 'subject': '...', 'body': '...', 'sender': '...' }
# Returns: validated parsed result JSON

# comparison_report_orchestrator.py

import json
from datetime import datetime
from openai import AzureOpenAI
from azure.identity import DefaultAzureCredential
from azure.keyvault.secrets import SecretClient
from azure.storage.blob import BlobServiceClient
from docx import Document
from docx.shared import Inches, Pt, RGBColor
from docx.enum.text import WD_ALIGN_PARAGRAPH
import openpyxl
from io import BytesIO
import hashlib

class CoverageComparisonGenerator:
    def __init__(self):
        credential = DefaultAzureCredential()
        kv_client = SecretClient(
            vault_url='https://kv-insurance-ai.vault.azure.net/',
            credential=credential
        )
        self.openai_key = kv_client.get_secret('azure-openai-key').value
        
        self.llm_client = AzureOpenAI(
            api_key=self.openai_key,
            api_version='2024-06-01',
            azure_endpoint='https://oai-insurance-coi.openai.azure.com/'
        )
        
        self.blob_client = BlobServiceClient(
            account_url='https://stinsuranceaidocs.blob.core.windows.net/',
            credential=credential
        )
    
    def generate_report(self, client_name: str, agency_name: str, agent_name: str, 
                       agent_license: str, quotes: list, contractual_requirements: dict = None) -> dict:
        """Generate a complete coverage comparison report."""
        
        # Step 1: Generate narrative via GPT-5.4
        narrative = self._generate_narrative(
            client_name, agency_name, agent_name, agent_license, quotes, contractual_requirements
        )
        
        # Step 2: Generate Word document
        docx_buffer = self._create_word_document(narrative, agency_name)
        
        # Step 3: Generate Excel summary
        xlsx_buffer = self._create_excel_summary(client_name, quotes)
        
        # Step 4: Upload to Azure Blob Storage
        timestamp = datetime.utcnow().strftime('%Y%m%d_%H%M%S')
        safe_client = client_name.replace(' ', '_').lower()
        
        docx_blob_name = f'{safe_client}/comparison_{timestamp}.docx'
        xlsx_blob_name = f'{safe_client}/comparison_{timestamp}.xlsx'
        
        container = self.blob_client.get_container_client('comparison-reports')
        container.upload_blob(docx_blob_name, docx_buffer.getvalue())
        container.upload_blob(xlsx_blob_name, xlsx_buffer.getvalue())
        
        # Step 5: Audit log
        doc_hash = hashlib.sha256(docx_buffer.getvalue()).hexdigest()
        
        return {
            'status': 'generated',
            'narrative_markdown': narrative,
            'docx_blob': docx_blob_name,
            'xlsx_blob': xlsx_blob_name,
            'document_hash': doc_hash,
            'carriers_compared': [q.get('carrier_name') for q in quotes],
            'generated_at': datetime.utcnow().isoformat()
        }
    
    def _generate_narrative(self, client_name, agency_name, agent_name, 
                           agent_license, quotes, contractual_requirements) -> str:
        quotes_text = ''
        for i, quote in enumerate(quotes, 1):
            quotes_text += f"\n--- Carrier {i}: {quote.get('carrier_name', 'Unknown')} ---\n"
            quotes_text += json.dumps(quote, indent=2)
            quotes_text += '\n'
        
        reqs_text = json.dumps(contractual_requirements, indent=2) if contractual_requirements else 'None specified'
        
        # Uses the Coverage Comparison Report Generator prompt (defined separately)
        system_prompt = """You are an expert insurance advisor generating a professional Coverage Comparison Report. Compare quotes from multiple carriers. Be accurate, thorough, and write in clear business language. Include: Executive Summary, Premium Comparison table, Coverage Comparison by Line (with limits, key differences, gaps, recommendations), Endorsement Analysis, Financial Strength notes, Overall Recommendation, and Disclaimers. NEVER fabricate details. Format as clean Markdown."""
        
        user_prompt = f"""Generate a Coverage Comparison Report:

Client: {client_name}
Agency: {agency_name}
Agent: {agent_name} (License: {agent_license})
Date: {datetime.utcnow().strftime('%B %d, %Y')}

Contractual Requirements: {reqs_text}

Carrier Quotes:
{quotes_text}"""
        
        response = self.llm_client.chat.completions.create(
            model='gpt-5.4',
            messages=[
                {'role': 'system', 'content': system_prompt},
                {'role': 'user', 'content': user_prompt}
            ],
            temperature=0.3,
            max_tokens=8000
        )
        
        return response.choices[0].message.content
    
    def _create_word_document(self, narrative: str, agency_name: str) -> BytesIO:
        doc = Document()
        
        # Set default font
        style = doc.styles['Normal']
        font = style.font
        font.name = 'Calibri'
        font.size = Pt(11)
        
        # Parse markdown narrative into Word formatting
        for line in narrative.split('\n'):
            line = line.strip()
            if line.startswith('# '):
                p = doc.add_heading(line[2:], level=1)
            elif line.startswith('## '):
                p = doc.add_heading(line[3:], level=2)
            elif line.startswith('### '):
                p = doc.add_heading(line[4:], level=3)
            elif line.startswith('- **'):
                doc.add_paragraph(line[2:], style='List Bullet')
            elif line.startswith('- '):
                doc.add_paragraph(line[2:], style='List Bullet')
            elif line.startswith('|'):
                # Simple table row - accumulate and create table
                doc.add_paragraph(line, style='Normal')
            elif line:
                doc.add_paragraph(line)
        
        buffer = BytesIO()
        doc.save(buffer)
        buffer.seek(0)
        return buffer
    
    def _create_excel_summary(self, client_name: str, quotes: list) -> BytesIO:
        wb = openpyxl.Workbook()
        ws = wb.active
        ws.title = 'Premium Comparison'
        
        # Headers
        headers = ['Coverage Line'] + [q.get('carrier_name', f'Carrier {i+1}') for i, q in enumerate(quotes)]
        ws.append(headers)
        
        # Coverage lines
        lines = ['General Liability', 'Commercial Auto', 'Workers Compensation', 'Umbrella/Excess', 'Property', 'TOTAL']
        premium_keys = ['gl_premium', 'auto_premium', 'wc_premium', 'umbrella_premium', 'property_premium']
        
        for line_name, key in zip(lines[:-1], premium_keys):
            row = [line_name]
            for quote in quotes:
                row.append(quote.get(key, 'N/A'))
            ws.append(row)
        
        # Total row
        total_row = ['TOTAL']
        for quote in quotes:
            total = sum(quote.get(k, 0) or 0 for k in premium_keys if isinstance(quote.get(k), (int, float)))
            total_row.append(total)
        ws.append(total_row)
        
        buffer = BytesIO()
        wb.save(buffer)
        buffer.seek(0)
        return buffer

# Azure Function HTTP trigger:
# POST /api/generate-comparison
# Body: { 'client_name': '...', 'agency_name': '...', 'agent_name': '...', 
#         'agent_license': '...', 'quotes': [...], 'contractual_requirements': {...} }