Implementation Guide: Generate employee handbook updates and policy communications

# run to verify connectivity meets requirements

curl -o /dev/null -s -w '%{time_total}' https://api.openai.com/v1/models

# Create audit spreadsheet structure (PowerShell - creates SharePoint list)
Import-Module PnP.PowerShell
Connect-PnPOnline -Url https://[tenant].sharepoint.com/sites/HRDocs -Interactive
New-PnPList -Title 'Handbook Audit' -Template GenericList
Add-PnPField -List 'Handbook Audit' -DisplayName 'Policy Section' -InternalName 'PolicySection' -Type Text -AddToDefaultView
Add-PnPField -List 'Handbook Audit' -DisplayName 'Current Status' -InternalName 'CurrentStatus' -Type Choice -Choices 'Current','Outdated','Missing','Needs Legal Review' -AddToDefaultView
Add-PnPField -List 'Handbook Audit' -DisplayName 'Applicable Jurisdictions' -InternalName 'Jurisdictions' -Type Note -AddToDefaultView
Add-PnPField -List 'Handbook Audit' -DisplayName 'Compliance Risk Level' -InternalName 'RiskLevel' -Type Choice -Choices 'Low','Medium','High','Critical' -AddToDefaultView
Add-PnPField -List 'Handbook Audit' -DisplayName 'AI Generation Priority' -InternalName 'AIPriority' -Type Number -AddToDefaultView

# Connect to SharePoint Online
Connect-PnPOnline -Url https://[tenant]-admin.sharepoint.com -Interactive

# Create dedicated HR Policy site (if not existing)
New-PnPSite -Type TeamSite -Title 'HR Policy Management' -Alias 'HRPolicyMgmt' -Description 'Central repository for employee handbook and policy documents'

# Connect to the new site
Connect-PnPOnline -Url https://[tenant].sharepoint.com/sites/HRPolicyMgmt -Interactive

# Create document libraries with versioning
New-PnPList -Title 'Policy Drafts' -Template DocumentLibrary
Set-PnPList -Identity 'Policy Drafts' -EnableVersioning $true -MajorVersions 50

New-PnPList -Title 'Approved Policies' -Template DocumentLibrary
Set-PnPList -Identity 'Approved Policies' -EnableVersioning $true -MajorVersions 100 -EnableMinorVersions $true

New-PnPList -Title 'Policy Templates' -Template DocumentLibrary
Set-PnPList -Identity 'Policy Templates' -EnableVersioning $true -MajorVersions 20

New-PnPList -Title 'Archived Handbooks' -Template DocumentLibrary

# Create metadata columns for policy tracking
Add-PnPField -List 'Approved Policies' -DisplayName 'Policy Category' -InternalName 'PolicyCategory' -Type Choice -Choices 'Employment Basics','Compensation & Benefits','Leave Policies','Workplace Conduct','Safety & Security','Technology & Data','Anti-Discrimination','State-Specific' -AddToDefaultView
Add-PnPField -List 'Approved Policies' -DisplayName 'Applicable States' -InternalName 'ApplicableStates' -Type Note -AddToDefaultView
Add-PnPField -List 'Approved Policies' -DisplayName 'Last Legal Review' -InternalName 'LastLegalReview' -Type DateTime -AddToDefaultView
Add-PnPField -List 'Approved Policies' -DisplayName 'Next Review Due' -InternalName 'NextReviewDue' -Type DateTime -AddToDefaultView
Add-PnPField -List 'Approved Policies' -DisplayName 'AI Generated' -InternalName 'AIGenerated' -Type Boolean -AddToDefaultView

# Set permissions - restrict Approved Policies library
Set-PnPList -Identity 'Approved Policies' -BreakRoleInheritance -CopyRoleAssignments

# Step 3a: Create Azure Key Vault for API key storage
az login
az group create --name rg-hr-ai-integration --location eastus
az keyvault create --name kv-hr-handbook-ai --resource-group rg-hr-ai-integration --location eastus --sku standard

# Step 3b: Store the OpenAI API key (replace with actual key from platform.openai.com)
az keyvault secret set --vault-name kv-hr-handbook-ai --name openai-api-key --value 'sk-proj-XXXXXXXXXXXXXXXXXXXXXXXX'

# Step 3c: Store Anthropic API key as backup provider
az keyvault secret set --vault-name kv-hr-handbook-ai --name anthropic-api-key --value 'sk-ant-XXXXXXXXXXXXXXXXXXXXXXXX'

# Step 3d: Create a service principal for the integration application
az ad app create --display-name 'HR Handbook AI Integration'
# Note the appId from output, then:
az ad sp create --id [appId]
az keyvault set-policy --name kv-hr-handbook-ai --spn [appId] --secret-permissions get list

# Step 3e: Set OpenAI usage limits via API (Python)
python3 -c "
import openai
# Configure at platform.openai.com/account/limits:
# - Set monthly budget cap to $50 (adjust based on client size)
# - Set per-request token limit to 16000 output tokens
# - Enable usage alerts at 50% and 80% of budget
print('Configure limits at: https://platform.openai.com/account/limits')
print('Recommended monthly cap: $50 for typical SMB HR usage')
"

Connect-PnPOnline -Url https://[tenant].sharepoint.com/sites/HRPolicyMgmt -Interactive
Get-ChildItem -Path './sixfifty-exports/*.docx' | ForEach-Object {
    Add-PnPFile -Path $_.FullName -Folder 'Policy Templates'
}

# Step 5a: Install required Python packages
pip install pinecone-client openai langchain langchain-openai tiktoken python-docx

# Step 5b: Initialize Pinecone index
python3 << 'EOF'
import pinecone
from pinecone import Pinecone, ServerlessSpec

pc = Pinecone(api_key='YOUR_PINECONE_API_KEY')  # Store in Key Vault in production

# Create index for policy document embeddings
pc.create_index(
    name='hr-handbook-policies',
    dimension=3072,  # text-embedding-3-large dimension
    metric='cosine',
    spec=ServerlessSpec(cloud='aws', region='us-east-1'))

print('Pinecone index created: hr-handbook-policies')
EOF

# Step 5c: Ingest existing handbook and SixFifty templates
python3 << 'INGEST_EOF'
import os
from pinecone import Pinecone
from openai import OpenAI
from docx import Document
import hashlib

# Initialize clients
pc = Pinecone(api_key=os.environ.get('PINECONE_API_KEY'))
index = pc.Index('hr-handbook-policies')
oai = OpenAI(api_key=os.environ.get('OPENAI_API_KEY'))

def chunk_document(filepath, chunk_size=1000, overlap=200):
    doc = Document(filepath)
    full_text = '\n'.join([p.text for p in doc.paragraphs if p.text.strip()])
    chunks = []
    for i in range(0, len(full_text), chunk_size - overlap):
        chunk = full_text[i:i + chunk_size]
        if len(chunk.strip()) > 50:
            chunks.append({
                'text': chunk,
                'source': os.path.basename(filepath),
                'chunk_index': len(chunks),
                'doc_hash': hashlib.md5(full_text.encode()).hexdigest()[:8]
            })
    return chunks

def embed_and_upsert(chunks, namespace='handbook'):
    batch_size = 50
    for i in range(0, len(chunks), batch_size):
        batch = chunks[i:i+batch_size]
        texts = [c['text'] for c in batch]
        response = oai.embeddings.create(
            model='text-embedding-3-large',
            input=texts
        )
        vectors = []
        for j, emb in enumerate(response.data):
            vec_id = f"{batch[j]['source']}_{batch[j]['chunk_index']}"
            vectors.append({
                'id': vec_id,
                'values': emb.embedding,
                'metadata': {
                    'text': batch[j]['text'],
                    'source': batch[j]['source'],
                    'chunk_index': batch[j]['chunk_index']
                }
            })
        index.upsert(vectors=vectors, namespace=namespace)
    print(f'Upserted {len(chunks)} vectors to namespace: {namespace}')

# Ingest all .docx files from policy templates directory
policy_dir = './policy-templates/'
for filename in os.listdir(policy_dir):
    if filename.endswith('.docx'):
        filepath = os.path.join(policy_dir, filename)
        chunks = chunk_document(filepath)
        embed_and_upsert(chunks, namespace='compliance-templates')
        print(f'Ingested: {filename} ({len(chunks)} chunks)')

print('RAG knowledge base initialization complete.')
INGEST_EOF

# Step 6a: Create the project directory structure
mkdir -p hr-handbook-ai/{api,prompts,config,tests}
cd hr-handbook-ai
python3 -m venv venv
source venv/bin/activate
pip install fastapi uvicorn openai pinecone-client python-docx azure-identity azure-keyvault-secrets pydantic jinja2

# Step 6b: Create main API service (save as api/main.py)
cat > api/main.py << 'API_EOF'
from fastapi import FastAPI, HTTPException
from pydantic import BaseModel
from typing import Optional, List
import os
from openai import OpenAI
from pinecone import Pinecone
import json

app = FastAPI(title='HR Handbook AI Generator', version='1.0.0')

# Initialize clients (use Key Vault in production)
oai = OpenAI(api_key=os.environ.get('OPENAI_API_KEY'))
pc = Pinecone(api_key=os.environ.get('PINECONE_API_KEY'))
index = pc.Index('hr-handbook-policies')

class PolicyRequest(BaseModel):
    policy_topic: str
    states: List[str]
    company_name: str
    employee_count: int
    action: str = 'generate'  # generate | update | simplify
    existing_text: Optional[str] = None
    tone: str = 'professional'  # professional | friendly | formal
    additional_context: Optional[str] = None

class PolicyResponse(BaseModel):
    policy_title: str
    generated_content: str
    state_specific_notes: dict
    compliance_warnings: List[str]
    sources_referenced: List[str]
    model_used: str
    requires_legal_review: bool

def retrieve_context(query: str, namespace: str = 'compliance-templates', top_k: int = 8) -> str:
    query_embedding = oai.embeddings.create(
        model='text-embedding-3-large',
        input=[query]
    ).data[0].embedding
    
    results = index.query(
        vector=query_embedding,
        namespace=namespace,
        top_k=top_k,
        include_metadata=True
    )
    
    context_parts = []
    sources = []
    for match in results.matches:
        if match.score > 0.3:
            context_parts.append(match.metadata.get('text', ''))
            sources.append(match.metadata.get('source', 'unknown'))
    
    return '\n---\n'.join(context_parts), list(set(sources))

@app.post('/generate-policy', response_model=PolicyResponse)
async def generate_policy(request: PolicyRequest):
    # Retrieve relevant context from RAG
    context, sources = retrieve_context(
        f"{request.policy_topic} {' '.join(request.states)} employment policy"
    )
    
    system_prompt = f"""You are an expert HR policy writer for {request.company_name}, a company with {request.employee_count} employees operating in: {', '.join(request.states)}.

CRITICAL RULES:
1. Generate ONLY policy language — no legal advice.
2. Every policy MUST include the disclaimer: 'This policy has been drafted with AI assistance and must be reviewed by qualified employment counsel before adoption.'
3. Include state-specific variations where laws differ across the listed states.
4. Use {request.tone} tone appropriate for an employee handbook.
5. Flag any areas where state laws conflict or where legal counsel review is especially critical.
6. Reference applicable federal laws (FLSA, FMLA, ADA, Title VII, NLRA, OSHA) where relevant.
7. Never fabricate specific legal citations — if unsure of a specific statute number, describe the requirement generally and flag for legal review.
8. Include effective date placeholder: [EFFECTIVE DATE].
9. Include signature/acknowledgment block at the end of each policy.
"""
    
    user_prompt = f"""ACTION: {request.action.upper()}

POLICY TOPIC: {request.policy_topic}

APPLICABLE STATES: {', '.join(request.states)}

{'EXISTING POLICY TEXT TO UPDATE:\n' + request.existing_text if request.existing_text else 'No existing policy — generate from scratch.'}

{'ADDITIONAL CONTEXT: ' + request.additional_context if request.additional_context else ''}

REFERENCE MATERIAL FROM COMPLIANCE DATABASE:
{context}

Please generate the complete policy section with:
1. Policy title
2. Purpose statement
3. Scope (who this applies to)
4. Detailed policy provisions
5. State-specific variations (if applicable)
6. Employee responsibilities
7. Employer responsibilities
8. Violation consequences
9. Related policies cross-references
10. Acknowledgment block
"""
    
    response = oai.chat.completions.create(
        model='gpt-4.1',
        messages=[
            {'role': 'system', 'content': system_prompt},
            {'role': 'user', 'content': user_prompt}
        ],
        temperature=0.3,
        max_tokens=4000
    )
    
    generated = response.choices[0].message.content
    
    # Extract state-specific notes (simplified parsing)
    state_notes = {}
    for state in request.states:
        if state.upper() in generated.upper():
            state_notes[state] = f'State-specific provisions included for {state}'
        else:
            state_notes[state] = 'No state-specific variation identified — verify with counsel'
    
    warnings = [
        'AI-generated content — MUST be reviewed by employment attorney before publication',
        f'Multi-state employer ({len(request.states)} states) — verify jurisdiction-specific requirements'
    ]
    if request.employee_count >= 50:
        warnings.append('FMLA-covered employer (50+ employees) — ensure leave policies comply')
    if 'CA' in [s.upper() for s in request.states]:
        warnings.append('California employer — state has extensive additional employment requirements')
    
    return PolicyResponse(
        policy_title=request.policy_topic,
        generated_content=generated,
        state_specific_notes=state_notes,
        compliance_warnings=warnings,
        sources_referenced=sources,
        model_used='gpt-4.1',
        requires_legal_review=True
    )

@app.get('/health')
async def health():
    return {'status': 'healthy', 'version': '1.0.0'}
API_EOF

# Step 6c: Create Dockerfile for containerized deployment
cat > Dockerfile << 'DOCKER_EOF'
FROM python:3.11-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY api/ ./api/
COPY prompts/ ./prompts/
EXPOSE 8000
CMD ["uvicorn", "api.main:app", "--host", "0.0.0.0", "--port", "8000"]
DOCKER_EOF

# Step 6d: Create requirements.txt
cat > requirements.txt << 'REQ_EOF'
fastapi==0.115.0
uvicorn==0.32.0
openai==1.55.0
pinecone-client==5.0.0
python-docx==1.1.0
azure-identity==1.19.0
azure-keyvault-secrets==4.9.0
pydantic==2.10.0
jinja2==3.1.4
REQ_EOF

# Step 6e: Test locally
uvicorn api.main:app --host 0.0.0.0 --port 8000 --reload

# Step 7a: Assign Copilot licenses via Microsoft 365 Admin Center PowerShell
Install-Module Microsoft.Graph -Scope CurrentUser
Connect-MgGraph -Scopes 'User.ReadWrite.All','Organization.Read.All'

# Get the Copilot SKU ID
Get-MgSubscribedSku | Where-Object { $_.SkuPartNumber -like '*Copilot*' } | Select-Object SkuPartNumber, SkuId

# Assign to HR users (replace with actual UPNs and SKU ID)
$HRUsers = @(
    'hr.director@client.com',
    'hr.manager@client.com',
    'hr.generalist@client.com'
)

$CopilotSkuId = 'XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX'  # from Get-MgSubscribedSku output

foreach ($user in $HRUsers) {
    $userId = (Get-MgUser -Filter "userPrincipalName eq '$user'").Id
    $addLicenses = @(
        @{SkuId = $CopilotSkuId}
    )
    Set-MgUserLicense -UserId $userId -AddLicenses $addLicenses -RemoveLicenses @()
    Write-Host "Copilot license assigned to: $user"
}

# Step 8a: Create Merge.dev account and configure HRIS integration
# Navigate to https://app.merge.dev and create account
# Add HRIS integration for client's specific platform (e.g., BambooHR, Rippling, ADP)
# Merge provides a Link Token workflow for secure OAuth connection

# Step 8b: Generate Link Token and connect client's HRIS
python3 << 'MERGE_EOF'
import requests
import os

MERGE_API_KEY = os.environ.get('MERGE_API_KEY')
MERGE_ACCOUNT_TOKEN = os.environ.get('MERGE_ACCOUNT_TOKEN')

headers = {
    'Authorization': f'Bearer {MERGE_API_KEY}',
    'X-Account-Token': MERGE_ACCOUNT_TOKEN,
    'Content-Type': 'application/json'
}

# List employees with work locations (for state-specific policy assignment)
response = requests.get(
    'https://api.merge.dev/api/hris/v1/employees',
    headers=headers,
    params={'include_remote_data': 'true', 'page_size': 100}
)

employees = response.json().get('results', [])
for emp in employees[:5]:  # Preview first 5
    name = f"{emp.get('first_name', '')} {emp.get('last_name', '')}"
    location = emp.get('work_location', {})
    state = location.get('state', 'Unknown') if location else 'Unknown'
    dept = emp.get('department', {})
    dept_name = dept.get('name', 'Unknown') if dept else 'Unknown'
    print(f'{name} | State: {state} | Dept: {dept_name}')

print(f'\nTotal employees found: {len(employees)}')
MERGE_EOF

# Step 8c: Create webhook for new hire events
python3 << 'WEBHOOK_EOF'
import requests
import os

headers = {
    'Authorization': f"Bearer {os.environ.get('MERGE_API_KEY')}",
    'Content-Type': 'application/json'
}

# Register webhook for new hire events
webhook_data = {
    'event': 'Employee.created',
    'target_url': 'https://[your-n8n-instance]/webhook/new-hire-handbook'
}

response = requests.post(
    'https://api.merge.dev/api/hris/v1/webhook-receivers',
    headers=headers,
    json=webhook_data
)
print(f'Webhook registered: {response.status_code}')
WEBHOOK_EOF

# Step 9a: Deploy n8n via Docker
docker run -d --name n8n \
  -p 5678:5678 \
  -v n8n_data:/home/node/.n8n \
  -e N8N_BASIC_AUTH_ACTIVE=true \
  -e N8N_BASIC_AUTH_USER=admin \
  -e N8N_BASIC_AUTH_PASSWORD='[STRONG_PASSWORD]' \
  -e WEBHOOK_URL=https://[your-domain]/n8n/ \
  n8nio/n8n:latest

# Step 10a: Register the bot in Azure
az bot create \
  --resource-group rg-hr-ai-integration \
  --name hr-policy-qa-bot \
  --kind registration \
  --display-name 'Policy Assistant' \
  --description 'Ask questions about company policies and employee handbook' \
  --endpoint 'https://[your-api-domain]/bot/messages' \
  --sku F0

# Step 10b: Create Teams app manifest (save as manifest.json)
cat > teams-bot/manifest.json << 'MANIFEST_EOF'
{
  "$schema": "https://developer.microsoft.com/en-us/json-schemas/teams/v1.17/MicrosoftTeams.schema.json",
  "manifestVersion": "1.17",
  "version": "1.0.0",
  "id": "[BOT_APP_ID]",
  "developer": {
    "name": "[MSP Company Name]",
    "websiteUrl": "https://[msp-website].com",
    "privacyUrl": "https://[msp-website].com/privacy",
    "termsOfUseUrl": "https://[msp-website].com/terms"
  },
  "name": { "short": "Policy Assistant", "full": "Employee Policy Q&A Assistant" },
  "description": {
    "short": "Ask questions about company policies",
    "full": "AI-powered assistant that answers questions about company policies, employee handbook, and HR procedures based on approved policy documents."
  },
  "icons": { "outline": "outline.png", "color": "color.png" },
  "accentColor": "#4F6BED",
  "bots": [{
    "botId": "[BOT_APP_ID]",
    "scopes": ["personal", "team"],
    "commandLists": [{
      "scopes": ["personal"],
      "commands": [
        { "title": "PTO Policy", "description": "Ask about paid time off" },
        { "title": "Leave Policy", "description": "Ask about leave policies" },
        { "title": "Remote Work", "description": "Ask about remote work policy" },
        { "title": "Benefits", "description": "Ask about employee benefits" }
      ]
    }]
  }],
  "validDomains": ["[your-api-domain]"]
}
MANIFEST_EOF

# Step 10c: Deploy bot backend endpoint (add to existing FastAPI app)
# Add to api/main.py - see custom_ai_components for full bot handler code

# Option A: Using Blissbook's built-in e-signature (if Blissbook is the handbook platform)
# Configure at https://app.blissbook.com > Settings > E-Signatures
# Enable 'Require acknowledgment for all policy updates'
# Set reminder cadence: 3 days, 7 days, 14 days

# Option B: Using Power Automate with Approvals (for M365-native approach)
# Step 11a: Create a Power Automate flow:
# Trigger: When a file is modified in 'Approved Policies' SharePoint library
# Action 1: Get all employees from HRIS (via Merge.dev HTTP connector)
# Action 2: For each employee, create an Approval request
# Action 3: Send adaptive card via Teams with policy summary + acknowledge button
# Action 4: Log acknowledgment to SharePoint list 'Policy Acknowledgments'
# Action 5: Send reminder if not acknowledged within 7 days
# Action 6: Escalate to HR manager if not acknowledged within 14 days

# Step 11b: Create acknowledgment tracking list
Connect-PnPOnline -Url https://[tenant].sharepoint.com/sites/HRPolicyMgmt -Interactive
New-PnPList -Title 'Policy Acknowledgments' -Template GenericList
Add-PnPField -List 'Policy Acknowledgments' -DisplayName 'Employee Name' -InternalName 'EmployeeName' -Type Text -AddToDefaultView
Add-PnPField -List 'Policy Acknowledgments' -DisplayName 'Employee Email' -InternalName 'EmployeeEmail' -Type Text -AddToDefaultView
Add-PnPField -List 'Policy Acknowledgments' -DisplayName 'Policy Name' -InternalName 'PolicyName' -Type Text -AddToDefaultView
Add-PnPField -List 'Policy Acknowledgments' -DisplayName 'Policy Version' -InternalName 'PolicyVersion' -Type Text -AddToDefaultView
Add-PnPField -List 'Policy Acknowledgments' -DisplayName 'Sent Date' -InternalName 'SentDate' -Type DateTime -AddToDefaultView
Add-PnPField -List 'Policy Acknowledgments' -DisplayName 'Acknowledged Date' -InternalName 'AcknowledgedDate' -Type DateTime -AddToDefaultView
Add-PnPField -List 'Policy Acknowledgments' -DisplayName 'Status' -InternalName 'AckStatus' -Type Choice -Choices 'Pending','Acknowledged','Overdue','Escalated' -AddToDefaultView

# Step 12a: Deploy API to Azure Container Apps
az containerapp env create \
  --name hr-handbook-env \
  --resource-group rg-hr-ai-integration \
  --location eastus

az containerapp create \
  --name hr-handbook-api \
  --resource-group rg-hr-ai-integration \
  --environment hr-handbook-env \
  --image [your-acr].azurecr.io/hr-handbook-api:1.0.0 \
  --target-port 8000 \
  --ingress external \
  --min-replicas 1 \
  --max-replicas 3 \
  --secrets openai-key=[KEY_VAULT_REF] pinecone-key=[KEY_VAULT_REF] \
  --env-vars OPENAI_API_KEY=secretref:openai-key PINECONE_API_KEY=secretref:pinecone-key

# Step 12b: Configure custom domain and TLS
az containerapp hostname add \
  --name hr-handbook-api \
  --resource-group rg-hr-ai-integration \
  --hostname api-hr.[client-domain].com

# Step 12c: Enable Azure AD authentication on the API
az containerapp auth update \
  --name hr-handbook-api \
  --resource-group rg-hr-ai-integration \
  --enabled true \
  --action RequireAuthentication \
  --provider MicrosoftIdentityPlatform \
  --client-id [APP_CLIENT_ID] \
  --tenant-id [TENANT_ID]

# Step 12d: Run go-live checklist
echo '=== GO-LIVE CHECKLIST ==='
echo '[ ] All API keys stored in Azure Key Vault (never in code/config)'
echo '[ ] MFA enforced for all HR users accessing handbook platforms'
echo '[ ] SharePoint permissions verified (no external sharing on HR docs)'
echo '[ ] Copilot data boundaries configured (no external data access)'
echo '[ ] Bot disclaimer text verified in all responses'
echo '[ ] Acknowledgment workflow tested end-to-end with test employee'
echo '[ ] Backup of existing handbook archived in Archived Handbooks library'
echo '[ ] Client employment attorney has signed off on initial AI-generated content'
echo '[ ] OpenAI usage limits configured ($50/month cap)'
echo '[ ] Monitoring alerts configured for API errors and usage spikes'
echo '[ ] Client HR team has completed training (see training checklist)'
echo '[ ] DNS and TLS configured for API endpoint'
echo '[ ] Incident response contact list documented and shared'

# store in prompts/policy_templates.json

# HR Policy Generation Prompt Library
# Store these templates in: prompts/policy_templates.json

{
  "system_prompts": {
    "policy_drafter": {
      "id": "sys-policy-drafter-v1",
      "template": "You are a professional HR policy writer assisting {{company_name}}, a {{industry}} company with {{employee_count}} employees operating in: {{states_list}}.\n\nYour role is to draft clear, professional employee handbook policy language. You are NOT providing legal advice.\n\nCRITICAL RULES:\n1. Every policy you generate MUST include this disclaimer at the top: 'DRAFT — AI-ASSISTED CONTENT — REQUIRES LEGAL REVIEW BEFORE ADOPTION'\n2. Include state-specific variations when laws differ across the listed states\n3. Flag areas requiring employment attorney review with [LEGAL REVIEW NEEDED] markers\n4. Use {{tone}} tone (professional/friendly/formal)\n5. Never fabricate specific statute numbers or case citations\n6. Always include an effective date placeholder: [EFFECTIVE DATE]\n7. Always include an acknowledgment signature block at the end\n8. Reference applicable federal laws by name (FLSA, FMLA, ADA, Title VII, NLRA, OSHA) where relevant\n9. For multi-state employers, present state-specific variations in a clearly marked table or section\n10. If you are uncertain about a specific legal requirement, state 'Consult with employment counsel regarding [specific topic]' rather than guessing",
      "variables": ["company_name", "industry", "employee_count", "states_list", "tone"]
    },
    "policy_updater": {
      "id": "sys-policy-updater-v1",
      "template": "You are an HR policy revision specialist for {{company_name}}. Your task is to update existing policy language while preserving the company's established voice and intent.\n\nRULES:\n1. Clearly mark all changes using [ADDED], [MODIFIED], and [REMOVED] tags\n2. Preserve existing policy structure where possible\n3. Include a 'Summary of Changes' section at the top listing every modification\n4. Maintain the disclaimer: 'DRAFT — AI-ASSISTED UPDATE — REQUIRES LEGAL REVIEW'\n5. If updating for compliance with new legislation, cite the legislation by name and effective date\n6. Never remove safety-related provisions without flagging them\n7. Preserve all existing state-specific accommodations unless explicitly instructed to remove them",
      "variables": ["company_name"]
    },
    "communication_writer": {
      "id": "sys-comms-writer-v1",
      "template": "You are an internal communications specialist for {{company_name}}. You write clear, engaging employee communications about policy changes and HR updates.\n\nSTYLE GUIDELINES:\n1. Write at an 8th-grade reading level for maximum accessibility\n2. Lead with what employees need to know and do\n3. Explain WHY the change is happening (without legalese)\n4. Include clear action items with deadlines\n5. Provide contact information for questions\n6. Keep emails under 500 words; link to full policy for details\n7. Use bullet points and headers for scannability\n8. Tone: {{tone}} and supportive — never condescending",
      "variables": ["company_name", "tone"]
    }
  },
  "user_prompt_templates": {
    "pto_policy": {
      "id": "usr-pto-v1",
      "topic": "Paid Time Off (PTO) Policy",
      "template": "Generate a comprehensive PTO policy with the following parameters:\n- PTO model: {{pto_model}} (accrual / lump-sum / unlimited)\n- Accrual rate (if applicable): {{accrual_rate}}\n- Maximum carryover: {{max_carryover}}\n- Payout on termination: {{payout_on_term}} (yes/no/state-dependent)\n- Blackout periods: {{blackout_periods}}\n- Minimum notice required: {{notice_period}}\n\nInclude state-specific requirements for: {{states_list}}\nNote: California, Montana, and several other states have specific PTO payout requirements.",
      "variables": ["pto_model", "accrual_rate", "max_carryover", "payout_on_term", "blackout_periods", "notice_period", "states_list"]
    },
    "remote_work_policy": {
      "id": "usr-remote-v1",
      "topic": "Remote Work / Telecommuting Policy",
      "template": "Generate a remote work policy covering:\n- Eligibility criteria: {{eligibility}}\n- Remote work arrangement types: {{arrangement_types}} (fully remote / hybrid / occasional)\n- Equipment and technology provisions: {{equipment_provisions}}\n- Work hours and availability expectations: {{availability}}\n- Home office safety and ergonomics: {{safety_reqs}}\n- Data security requirements: {{data_security}}\n- Communication and collaboration expectations: {{comm_expectations}}\n- Performance measurement approach: {{performance}}\n- Expense reimbursement: {{expense_policy}}\n\nInclude state-specific considerations for: {{states_list}}\nNote: Several states (CA, IL, NY, etc.) have specific remote work expense reimbursement requirements.",
      "variables": ["eligibility", "arrangement_types", "equipment_provisions", "availability", "safety_reqs", "data_security", "comm_expectations", "performance", "expense_policy", "states_list"]
    },
    "harassment_policy": {
      "id": "usr-harassment-v1",
      "topic": "Anti-Harassment and Anti-Discrimination Policy",
      "template": "Generate a comprehensive anti-harassment and anti-discrimination policy covering:\n- Protected classes (federal + state-specific): {{protected_classes}}\n- Types of prohibited conduct (with examples): harassment, discrimination, retaliation\n- Reporting procedures: {{reporting_channels}}\n- Investigation process overview\n- Confidentiality commitments\n- Anti-retaliation protections\n- Training requirements: {{training_reqs}}\n- Consequences for violations\n\nSTATES: {{states_list}}\n[LEGAL REVIEW NEEDED] This policy area is especially sensitive and jurisdiction-specific. CA, NY, IL, CT, DE, ME have mandatory anti-harassment training requirements.",
      "variables": ["protected_classes", "reporting_channels", "training_reqs", "states_list"]
    },
    "social_media_policy": {
      "id": "usr-social-v1",
      "topic": "Social Media Policy",
      "template": "Generate an employee social media policy that balances company interests with employee rights:\n- Company social media accounts management\n- Personal social media use guidelines\n- Confidentiality and proprietary information protections\n- Disclaimer requirements for personal posts about the company\n- Prohibited conduct on social media\n\n[LEGAL REVIEW NEEDED] NLRA Section 7 protects employees' rights to engage in protected concerted activity, including discussing working conditions on social media. This policy MUST NOT unlawfully restrict protected activity. Include explicit NLRA savings clause.",
      "variables": []
    },
    "policy_change_email": {
      "id": "usr-change-email-v1",
      "topic": "Policy Change Communication Email",
      "template": "Draft an employee communication email announcing the following policy change:\n\nPolicy: {{policy_name}}\nType of change: {{change_type}} (new policy / update / removal)\nEffective date: {{effective_date}}\nSummary of changes: {{change_summary}}\nAction required from employees: {{employee_action}}\nDeadline for action: {{action_deadline}}\nContact for questions: {{hr_contact}}\n\nKeep under 500 words. Include link placeholder [HANDBOOK LINK] for full policy.",
      "variables": ["policy_name", "change_type", "effective_date", "change_summary", "employee_action", "action_deadline", "hr_contact"]
    }
  }
}

# Policy RAG Retrieval Agent
# File: api/rag_agent.py

import os
from typing import List, Dict, Optional, Tuple
from openai import OpenAI
from pinecone import Pinecone
import json

class PolicyRAGAgent:
    """
    Intelligent retrieval agent for HR policy content generation.
    Searches multiple vector database namespaces and assembles
    relevant context for policy drafting.
    """
    
    NAMESPACES = {
        'handbook': 'Client\'s existing handbook content',
        'compliance-templates': 'SixFifty/BLR compliant policy templates',
        'employment-law': 'Employment law summaries and requirements',
        'best-practices': 'HR best practice guides and SHRM resources'
    }
    
    # Map policy topics to relevant search queries
    TOPIC_QUERY_MAP = {
        'pto': ['paid time off policy', 'vacation accrual', 'PTO payout requirements', 'sick leave policy'],
        'remote_work': ['remote work policy', 'telecommuting', 'work from home', 'expense reimbursement remote'],
        'harassment': ['anti-harassment policy', 'discrimination prevention', 'Title VII compliance', 'hostile work environment'],
        'leave': ['FMLA leave', 'parental leave', 'medical leave', 'state paid leave requirements'],
        'compensation': ['compensation policy', 'pay transparency', 'overtime FLSA', 'equal pay requirements'],
        'termination': ['termination policy', 'at-will employment', 'severance', 'final paycheck requirements'],
        'social_media': ['social media policy', 'NLRA protected activity', 'online conduct', 'company reputation'],
        'safety': ['workplace safety', 'OSHA requirements', 'injury reporting', 'emergency procedures'],
        'benefits': ['employee benefits', 'health insurance', 'COBRA', 'ERISA requirements', '401k policy'],
        'onboarding': ['new hire onboarding', 'orientation', 'I-9 verification', 'employment eligibility']
    }
    
    # States with notably complex employment law
    HIGH_COMPLEXITY_STATES = ['CA', 'NY', 'MA', 'WA', 'CO', 'IL', 'CT', 'NJ', 'OR']
    
    def __init__(self):
        self.oai = OpenAI(api_key=os.environ.get('OPENAI_API_KEY'))
        self.pc = Pinecone(api_key=os.environ.get('PINECONE_API_KEY'))
        self.index = self.pc.Index('hr-handbook-policies')
    
    def classify_topic(self, user_query: str) -> str:
        """Use LLM to classify the policy topic from free-form input."""
        response = self.oai.chat.completions.create(
            model='gpt-5.4-mini',
            messages=[
                {'role': 'system', 'content': f'Classify the following HR policy request into one of these categories: {list(self.TOPIC_QUERY_MAP.keys())}. Respond with ONLY the category key.'},
                {'role': 'user', 'content': user_query}
            ],
            temperature=0,
            max_tokens=20
        )
        topic = response.choices[0].message.content.strip().lower()
        return topic if topic in self.TOPIC_QUERY_MAP else 'general'
    
    def get_embeddings(self, texts: List[str]) -> List[List[float]]:
        """Generate embeddings for a list of texts."""
        response = self.oai.embeddings.create(
            model='text-embedding-3-large',
            input=texts
        )
        return [item.embedding for item in response.data]
    
    def retrieve_from_namespace(
        self,
        query_embedding: List[float],
        namespace: str,
        top_k: int = 5,
        min_score: float = 0.3
    ) -> List[Dict]:
        """Retrieve relevant documents from a specific namespace."""
        results = self.index.query(
            vector=query_embedding,
            namespace=namespace,
            top_k=top_k,
            include_metadata=True
        )
        return [
            {
                'text': match.metadata.get('text', ''),
                'source': match.metadata.get('source', 'unknown'),
                'score': match.score,
                'namespace': namespace
            }
            for match in results.matches
            if match.score >= min_score
        ]
    
    def build_context(
        self,
        policy_topic: str,
        states: List[str],
        existing_text: Optional[str] = None
    ) -> Tuple[str, List[str], List[str]]:
        """
        Build comprehensive context for policy generation.
        Returns: (context_text, sources_list, compliance_flags)
        """
        # Determine search queries based on topic
        topic_key = self.classify_topic(policy_topic)
        search_queries = self.TOPIC_QUERY_MAP.get(topic_key, [policy_topic])
        
        # Add state-specific queries for high-complexity states
        for state in states:
            if state.upper() in self.HIGH_COMPLEXITY_STATES:
                search_queries.append(f'{policy_topic} {state} state requirements')
        
        # Generate embeddings for all queries
        all_embeddings = self.get_embeddings(search_queries)
        
        # Retrieve from all relevant namespaces
        all_results = []
        for query_emb in all_embeddings:
            for namespace in self.NAMESPACES:
                results = self.retrieve_from_namespace(
                    query_emb, namespace, top_k=3
                )
                all_results.extend(results)
        
        # Deduplicate and sort by relevance score
        seen_texts = set()
        unique_results = []
        for r in sorted(all_results, key=lambda x: x['score'], reverse=True):
            text_hash = hash(r['text'][:100])
            if text_hash not in seen_texts:
                seen_texts.add(text_hash)
                unique_results.append(r)
        
        # Take top 10 most relevant chunks
        top_results = unique_results[:10]
        
        # Build context string
        context_parts = []
        sources = []
        for i, r in enumerate(top_results):
            context_parts.append(
                f"[Source {i+1}: {r['source']} (relevance: {r['score']:.2f})]\n{r['text']}"
            )
            sources.append(f"{r['source']} ({r['namespace']})")
        
        context_text = '\n\n---\n\n'.join(context_parts)
        
        # Generate compliance flags
        compliance_flags = []
        if any(s.upper() == 'CA' for s in states):
            compliance_flags.append('CALIFORNIA: Extensive additional requirements — meal/rest breaks, PTO payout, expense reimbursement, anti-harassment training, pay transparency')
        if any(s.upper() == 'NY' for s in states):
            compliance_flags.append('NEW YORK: NYC-specific requirements may apply — paid safe/sick leave, salary transparency, AI bias audit (Local Law 144)')
        if len(states) > 3:
            compliance_flags.append(f'MULTI-STATE ({len(states)} states): High complexity — consider state-specific policy addendum approach')
        if topic_key in ['harassment', 'termination', 'compensation']:
            compliance_flags.append(f'HIGH-SENSITIVITY TOPIC ({topic_key}): Mandatory legal review before publication')
        
        return context_text, list(set(sources)), compliance_flags


# Integration with main API
def get_rag_agent() -> PolicyRAGAgent:
    """Factory function for dependency injection."""
    return PolicyRAGAgent()

from api.rag_agent import PolicyRAGAgent
agent = PolicyRAGAgent()
context, sources, flags = agent.build_context(
    policy_topic=request.policy_topic,
    states=request.states,
    existing_text=request.existing_text
)

{
  "name": "New Hire Webhook",
  "type": "n8n-nodes-base.webhook",
  "parameters": {
    "httpMethod": "POST",
    "path": "new-hire-handbook",
    "authentication": "headerAuth",
    "responseMode": "onReceived",
    "responseCode": 200
  }
}

{
  "name": "Parse Employee",
  "type": "n8n-nodes-base.set",
  "parameters": {
    "values": {
      "string": [
        {"name": "employee_name", "value": "={{$json.data.first_name}} {{$json.data.last_name}}"},
        {"name": "employee_email", "value": "={{$json.data.work_email}}"},
        {"name": "work_state", "value": "={{$json.data.work_location.state}}"},
        {"name": "department", "value": "={{$json.data.department.name}}"},
        {"name": "start_date", "value": "={{$json.data.start_date}}"}
      ]
    }
  }
}

{
  "name": "Generate Welcome Email",
  "type": "n8n-nodes-base.openAi",
  "parameters": {
    "resource": "chat",
    "model": "gpt-5.4-mini",
    "messages": {
      "values": [
        {
          "role": "system",
          "content": "You are an internal communications specialist. Write a warm, professional welcome email for a new employee receiving their employee handbook. Keep under 300 words. Include: welcome message, brief handbook overview, instruction to read and acknowledge, and HR contact for questions."
        },
        {
          "role": "user",
          "content": "Write a welcome email for {{$node['Parse Employee'].json.employee_name}} joining the {{$node['Parse Employee'].json.department}} department starting {{$node['Parse Employee'].json.start_date}}. Company: [CLIENT COMPANY NAME]. HR contact: [HR_CONTACT_EMAIL]."
        }
      ]
    },
    "options": {
      "temperature": 0.5,
      "maxTokens": 500
    }
  }
}

{
  "name": "Send Handbook Email",
  "type": "n8n-nodes-base.microsoftOutlook",
  "parameters": {
    "resource": "message",
    "operation": "send",
    "toRecipients": "={{$node['Parse Employee'].json.employee_email}}",
    "subject": "Welcome to [Company Name] — Your Employee Handbook",
    "bodyContent": "={{$node['Generate Welcome Email'].json.message.content}}",
    "bodyContentType": "HTML"
  }
}

{
  "name": "Create Ack Record",
  "type": "n8n-nodes-base.microsoftSharePoint",
  "parameters": {
    "operation": "create",
    "siteId": "[SHAREPOINT_SITE_ID]",
    "listId": "[POLICY_ACKNOWLEDGMENTS_LIST_ID]",
    "fields": {
      "EmployeeName": "={{$node['Parse Employee'].json.employee_name}}",
      "EmployeeEmail": "={{$node['Parse Employee'].json.employee_email}}",
      "PolicyName": "Employee Handbook — Full",
      "SentDate": "={{$now.toISO()}}",
      "AckStatus": "Pending"
    }
  }
}

# Employee Policy Q&A Bot Handler
# File: api/bot_handler.py
# Add this to the existing FastAPI application

from fastapi import Request, HTTPException
from pydantic import BaseModel
from typing import Optional
import os
import json
from openai import OpenAI
from pinecone import Pinecone

# Bot configuration
BOT_DISCLAIMER = (
    "\n\n---\n"
    "ℹ️ *This response is based on current company policy documents and is for "
    "informational purposes only. It does not constitute legal or HR advice. "
    "For specific situations or questions, please contact your HR representative "
    "at [HR_CONTACT_EMAIL].*"
)

NO_ANSWER_RESPONSE = (
    "I wasn't able to find a clear answer to your question in our current policy "
    "documents. Please reach out to your HR representative at [HR_CONTACT_EMAIL] "
    "for assistance with this question."
)

class BotMessage(BaseModel):
    type: str
    text: Optional[str] = None
    from_id: Optional[str] = None
    from_name: Optional[str] = None
    conversation_id: Optional[str] = None

oai = OpenAI(api_key=os.environ.get('OPENAI_API_KEY'))
pc = Pinecone(api_key=os.environ.get('PINECONE_API_KEY'))
index = pc.Index('hr-handbook-policies')

def retrieve_policy_context(question: str, top_k: int = 5) -> tuple:
    """Retrieve relevant policy content for the employee's question."""
    embedding = oai.embeddings.create(
        model='text-embedding-3-large',
        input=[question]
    ).data[0].embedding
    
    # Search approved handbook content only (not drafts)
    results = index.query(
        vector=embedding,
        namespace='handbook',
        top_k=top_k,
        include_metadata=True
    )
    
    context_chunks = []
    sources = []
    for match in results.matches:
        if match.score > 0.35:  # Higher threshold for Q&A accuracy
            context_chunks.append(match.metadata.get('text', ''))
            sources.append(match.metadata.get('source', 'Company Policy'))
    
    return '\n\n'.join(context_chunks), list(set(sources))

def generate_answer(question: str, context: str, sources: list) -> str:
    """Generate an answer grounded in policy documents."""
    if not context.strip():
        return NO_ANSWER_RESPONSE
    
    system_prompt = """You are a helpful employee policy assistant. Your ONLY job is to answer employee questions based on the provided company policy documents.

RULES:
1. ONLY answer based on the provided policy context — never make up or infer policy details
2. If the context doesn't contain enough information to fully answer, say so clearly
3. Quote relevant policy language when possible
4. Use simple, clear language (8th-grade reading level)
5. If the question involves a specific personal situation (e.g., 'Can I take leave for X?'), direct them to HR for personalized guidance
6. Never provide legal advice or interpret laws
7. Be friendly and helpful in tone
8. Keep answers concise (under 300 words)
9. If multiple policies are relevant, reference each by name"""
    
    user_prompt = f"""Employee question: {question}

Relevant policy documents:
{context}

Sources: {', '.join(sources)}

Provide a helpful, accurate answer based ONLY on the above policy content."""
    
    response = oai.chat.completions.create(
        model='gpt-5.4-mini',  # Cost-optimized for Q&A
        messages=[
            {'role': 'system', 'content': system_prompt},
            {'role': 'user', 'content': user_prompt}
        ],
        temperature=0.2,  # Low temperature for factual accuracy
        max_tokens=500
    )
    
    return response.choices[0].message.content

# FastAPI endpoint for Teams bot
# This handles the Bot Framework webhook
async def handle_bot_message(request: Request):
    """Process incoming Teams bot messages."""
    body = await request.json()
    
    if body.get('type') != 'message':
        return {'status': 'ok'}  # Ignore non-message activities
    
    question = body.get('text', '').strip()
    user_name = body.get('from', {}).get('name', 'Employee')
    
    if not question:
        return {
            'type': 'message',
            'text': 'Please type a question about company policies and I\'ll do my best to help! 📋'
        }
    
    # Log the query (for analytics, not storing PII)
    print(f'Policy Q&A query from {user_name}: {question[:100]}...')
    
    # Retrieve and generate
    context, sources = retrieve_policy_context(question)
    answer = generate_answer(question, context, sources)
    
    # Add source references and disclaimer
    if sources:
        answer += f"\n\n📄 *Sources: {', '.join(sources)}*"
    answer += BOT_DISCLAIMER
    
    return {
        'type': 'message',
        'text': answer
    }

# Register in main.py:
# app.post('/bot/messages')(handle_bot_message)

# api/compliance_monitor.py. Runs as a scheduled task via n8n cron trigger
# or Azure Functions timer.

import os
import json
from datetime import datetime, timedelta
from typing import List, Dict
from openai import OpenAI
from pinecone import Pinecone
import requests

class ComplianceMonitor:
    """
    Monitors for potential compliance issues by cross-referencing
    the client's handbook content against known compliance topics
    and generating update recommendations.
    """
    
    # Key compliance areas to monitor
    COMPLIANCE_TOPICS = [
        {
            'area': 'Pay Transparency',
            'states': ['CA', 'CO', 'NY', 'WA', 'IL', 'HI', 'MD', 'NV', 'RI', 'CT'],
            'check_prompt': 'Review the company pay transparency policy for compliance with current state requirements. Check for: salary range disclosure requirements, pay equity provisions, prohibition on salary history inquiries.'
        },
        {
            'area': 'Paid Leave',
            'states': ['CA', 'CO', 'CT', 'MA', 'MD', 'NJ', 'NY', 'OR', 'RI', 'WA'],
            'check_prompt': 'Review the company leave policies for compliance with state paid family and medical leave laws, paid sick leave requirements, and any new leave entitlements.'
        },
        {
            'area': 'AI in Employment',
            'states': ['NY', 'IL', 'CO', 'CA'],
            'check_prompt': 'Check if the company uses any AI/automated tools for hiring, performance evaluation, or employment decisions that may require disclosure, bias audits, or impact assessments under current state laws.'
        },
        {
            'area': 'Remote Work',
            'states': ['ALL'],
            'check_prompt': 'Review remote work and telecommuting policies for compliance with expense reimbursement requirements, tax nexus implications, and state-specific remote worker protections.'
        },
        {
            'area': 'Anti-Harassment Training',
            'states': ['CA', 'CT', 'DE', 'IL', 'ME', 'NY'],
            'check_prompt': 'Verify that anti-harassment training requirements are being met per state mandates, including frequency, content requirements, and recordkeeping.'
        },
        {
            'area': 'Cannabis/Marijuana',
            'states': ['CA', 'CO', 'IL', 'NJ', 'NY', 'VA', 'CT', 'MT', 'NM', 'AZ'],
            'check_prompt': 'Review drug testing and substance abuse policies for compliance with state cannabis legalization laws and employee protections for off-duty use.'
        }
    ]
    
    def __init__(self, client_states: List[str], company_name: str):
        self.oai = OpenAI(api_key=os.environ.get('OPENAI_API_KEY'))
        self.pc = Pinecone(api_key=os.environ.get('PINECONE_API_KEY'))
        self.index = self.pc.Index('hr-handbook-policies')
        self.client_states = [s.upper() for s in client_states]
        self.company_name = company_name
    
    def get_applicable_topics(self) -> List[Dict]:
        """Filter compliance topics to those relevant to client's states."""
        applicable = []
        for topic in self.COMPLIANCE_TOPICS:
            if topic['states'] == ['ALL'] or any(
                s in self.client_states for s in topic['states']
            ):
                matching_states = (
                    self.client_states if topic['states'] == ['ALL']
                    else [s for s in topic['states'] if s in self.client_states]
                )
                applicable.append({**topic, 'matching_states': matching_states})
        return applicable
    
    def retrieve_current_policy(self, topic_area: str) -> str:
        """Retrieve the client's current policy for a given topic."""
        embedding = self.oai.embeddings.create(
            model='text-embedding-3-large',
            input=[topic_area]
        ).data[0].embedding
        
        results = self.index.query(
            vector=embedding,
            namespace='handbook',
            top_k=5,
            include_metadata=True
        )
        
        texts = [m.metadata.get('text', '') for m in results.matches if m.score > 0.3]
        return '\n'.join(texts) if texts else 'NO EXISTING POLICY FOUND'
    
    def analyze_compliance_gap(self, topic: Dict, current_policy: str) -> Dict:
        """Use AI to analyze potential compliance gaps."""
        prompt = f"""You are an HR compliance analyst reviewing {self.company_name}'s employee handbook.

COMPLIANCE AREA: {topic['area']}
APPLICABLE STATES: {', '.join(topic['matching_states'])}

CURRENT POLICY TEXT:
{current_policy}

ANALYSIS REQUEST:
{topic['check_prompt']}

Provide your analysis in this JSON format:
{{
  "risk_level": "low|medium|high|critical",
  "findings": ["List of specific findings"],
  "recommended_actions": ["List of specific recommended actions"],
  "states_requiring_attention": ["List of specific states with issues"],
  "urgency": "immediate|within_30_days|within_90_days|next_review_cycle"
}}

IMPORTANT: Be conservative in your assessment. Flag potential issues rather than dismissing them. Note: Your analysis is preliminary and should be verified by employment counsel."""
        
        response = self.oai.chat.completions.create(
            model='gpt-4.1',
            messages=[{'role': 'user', 'content': prompt}],
            temperature=0.2,
            response_format={'type': 'json_object'}
        )
        
        try:
            analysis = json.loads(response.choices[0].message.content)
        except json.JSONDecodeError:
            analysis = {
                'risk_level': 'medium',
                'findings': ['Analysis could not be parsed — manual review recommended'],
                'recommended_actions': ['Manually review this compliance area'],
                'states_requiring_attention': topic['matching_states'],
                'urgency': 'within_30_days'
            }
        
        analysis['area'] = topic['area']
        analysis['matching_states'] = topic['matching_states']
        return analysis
    
    def run_compliance_scan(self) -> Dict:
        """Execute full compliance scan and return results."""
        applicable_topics = self.get_applicable_topics()
        results = []
        
        for topic in applicable_topics:
            current_policy = self.retrieve_current_policy(topic['area'])
            analysis = self.analyze_compliance_gap(topic, current_policy)
            results.append(analysis)
        
        # Sort by risk level
        risk_order = {'critical': 0, 'high': 1, 'medium': 2, 'low': 3}
        results.sort(key=lambda x: risk_order.get(x.get('risk_level', 'low'), 3))
        
        scan_report = {
            'scan_date': datetime.now().isoformat(),
            'company': self.company_name,
            'states_covered': self.client_states,
            'topics_scanned': len(results),
            'critical_findings': len([r for r in results if r['risk_level'] == 'critical']),
            'high_findings': len([r for r in results if r['risk_level'] == 'high']),
            'results': results,
            'disclaimer': 'This AI-generated compliance scan is preliminary and does not constitute legal advice. All findings should be reviewed by qualified employment counsel.'
        }
        
        return scan_report
    
    def format_alert_email(self, scan_report: Dict) -> str:
        """Format scan results as an HTML email for the HR team."""
        critical_count = scan_report['critical_findings']
        high_count = scan_report['high_findings']
        
        html = f"""<h2>Weekly HR Compliance Scan Report</h2>
<p><strong>Company:</strong> {scan_report['company']}</p>
<p><strong>Scan Date:</strong> {scan_report['scan_date'][:10]}</p>
<p><strong>States Covered:</strong> {', '.join(scan_report['states_covered'])}</p>
<p><strong>Summary:</strong> {critical_count} critical, {high_count} high-priority findings</p>
<hr>"""
        
        for result in scan_report['results']:
            color = {'critical': '#d32f2f', 'high': '#f57c00', 'medium': '#fbc02d', 'low': '#388e3c'}
            level_color = color.get(result['risk_level'], '#666')
            
            html += f"""
<h3 style='color: {level_color}'>[{result['risk_level'].upper()}] {result['area']}</h3>
<p><strong>States:</strong> {', '.join(result.get('matching_states', []))}</p>
<p><strong>Urgency:</strong> {result.get('urgency', 'N/A')}</p>
<p><strong>Findings:</strong></p><ul>"""
            for finding in result.get('findings', []):
                html += f'<li>{finding}</li>'
            html += '</ul><p><strong>Recommended Actions:</strong></p><ul>'
            for action in result.get('recommended_actions', []):
                html += f'<li>{action}</li>'
            html += '</ul><hr>'
        
        html += f"""<p style='color: #666; font-size: 12px'><em>{scan_report['disclaimer']}</em></p>"""
        return html


# Usage (called by n8n cron workflow or Azure Functions timer):
# monitor = ComplianceMonitor(
#     client_states=['CA', 'NY', 'TX', 'IL'],
#     company_name='Acme Staffing Inc.'
# )
# report = monitor.run_compliance_scan()
# email_html = monitor.format_alert_email(report)
# Send email_html via Microsoft Graph API to HR team