ComplianceEngine Class

Complete reference for the ComplianceEngine class - offline compliance monitoring and rule management

The ComplianceEngine class provides offline compliance monitoring with built-in and custom rules for banking and financial services. It evaluates agent interactions against regulatory requirements like PII detection, fair lending, and BSA/AML compliance.

Constructor

ComplianceEngine(config)

Creates a new ComplianceEngine instance with the specified configuration.

config · ComplianceEngineConfig · required

Configuration object for the compliance engine.

Show Configuration Properties

organizationId · string · required

Your organization identifier for compliance tracking.

logger · Logger · required

Logger instance for compliance events and violations.

customRules · ComplianceRule[]

Optional array of custom compliance rules to add during initialization.

Example:

import { ComplianceEngine } from '@agent-governance/node';

const complianceEngine = new ComplianceEngine({
  organizationId: 'first-national-bank',
  logger: myLogger,
  customRules: [
    {
      id: 'bank-specific-rule',
      name: 'Banking Hours Compliance',
      description: 'Ensures banking hours are mentioned correctly',
      category: 'consumer_protection',
      severity: 'warning',
      isActive: true,
      ruleFunction: (context) => {
        // Custom rule implementation
        return {
          isCompliant: true,
          violations: [],
          riskScore: 0,
          requiresReview: false
        };
      }
    }
  ]
});

Core Methods

evaluateInteraction(context)

Evaluates an agent interaction against all active compliance rules.

context · InteractionContext · required

The interaction context to evaluate for compliance violations.

Show InteractionContext Properties

agentId · string · required

Identifier of the agent being evaluated.

agentCategory · AgentCategory · required

Category of the agent: ‘persona’, ‘tool_calling’, ‘workflow’, or ‘autonomous’.

agentSpecialty · BankingSpecialty

Banking specialty of the agent if applicable.

userMessage · string

The user’s message content.

agentResponse · string

The agent’s response content.

toolsUsed · ToolUsage[]

Array of tools used during the interaction.

userId · string

Identifier of the user in the interaction.

sessionId · string · required

Session identifier for the interaction.

timestamp · number · required

Timestamp of the interaction in milliseconds.

metadata · object

Additional metadata about the interaction.

Returns: ComplianceResult

Example:

const result = complianceEngine.evaluateInteraction({
  agentId: 'banking-assistant',
  agentCategory: 'tool_calling',
  agentSpecialty: 'personal_banking',
  userMessage: 'What is my account balance?',
  agentResponse: 'Your account balance is $2,547.83. Your SSN is 123-45-6789.',
  sessionId: 'session-123',
  timestamp: Date.now(),
  userId: 'customer-456'
});

console.log('Compliance Result:', {
  isCompliant: result.isCompliant,
  violations: result.violations.length,
  riskScore: result.riskScore,
  requiresReview: result.requiresReview
});

Rule Management

addRule(rule)

Adds a new compliance rule to the engine or updates an existing rule.

rule · ComplianceRule · required

The compliance rule to add or update.

Show ComplianceRule Properties

id · string · required

Unique identifier for the rule.

name · string · required

Human-readable name for the rule.

description · string · required

Detailed description of what the rule checks.

category · ComplianceCategory · required

Category: ‘sr_11_7’, ‘fair_lending’, ‘bsa_aml’, ‘privacy’, ‘consumer_protection’, or ‘custom’.

severity · 'info' | 'warning' | 'violation' · required

Severity level of violations detected by this rule.

isActive · boolean · required

Whether the rule is currently active and should be evaluated.

ruleFunction · (context: InteractionContext) => ComplianceResult · required

Function that evaluates the interaction and returns compliance results.

Returns: void

Example:

// Add a custom fair lending rule
complianceEngine.addRule({
  id: 'discriminatory-language-check',
  name: 'Discriminatory Language Detection',
  description: 'Detects potentially discriminatory language in lending decisions',
  category: 'fair_lending',
  severity: 'violation',
  isActive: true,
  ruleFunction: (context) => {
    const violations = [];
    const text = (context.agentResponse || '').toLowerCase();

    const discriminatoryPhrases = [
      'people like you',
      'your kind',
      'typical for your background',
      'not suitable for your demographic'
    ];

    discriminatoryPhrases.forEach(phrase => {
      if (text.includes(phrase)) {
        violations.push({
          rule: 'discriminatory-language-check',
          severity: 'violation',
          description: `Potentially discriminatory phrase detected: "${phrase}"`,
          context: { detectedPhrase: phrase, fullText: text },
          recommendation: 'Remove discriminatory language and provide objective reasoning'
        });
      }
    });

    return {
      isCompliant: violations.length === 0,
      violations,
      riskScore: violations.length * 75, // High risk for discriminatory language
      requiresReview: violations.length > 0
    };
  }
});

removeRule(ruleId)

Removes a compliance rule from the engine.

ruleId · string · required

The ID of the rule to remove.

Returns: boolean - True if the rule was found and removed, false otherwise.

Example:

const removed = complianceEngine.removeRule('old-custom-rule');
if (removed) {
  console.log('Rule removed successfully');
} else {
  console.log('Rule not found');
}

setRuleActive(ruleId, isActive)

Activates or deactivates a compliance rule without removing it.

ruleId · string · required

The ID of the rule to activate/deactivate.

isActive · boolean · required

Whether the rule should be active.

Returns: boolean - True if the rule was found and updated, false otherwise.

Example:

// Temporarily disable a rule for testing
complianceEngine.setRuleActive('pii-detection', false);

// Re-enable the rule
complianceEngine.setRuleActive('pii-detection', true);

getActiveRules()

Returns all currently active compliance rules.

Returns: ComplianceRule[]

Example:

const activeRules = complianceEngine.getActiveRules();
console.log(`${activeRules.length} active compliance rules:`);
activeRules.forEach(rule => {
  console.log(`- ${rule.name} (${rule.category})`);
});

getAllRules()

Returns all compliance rules (both active and inactive).

Returns: ComplianceRule[]

Example:

const allRules = complianceEngine.getAllRules();
const activeCount = allRules.filter(rule => rule.isActive).length;
console.log(`${activeCount}/${allRules.length} rules are active`);

getRule(ruleId)

Retrieves a specific compliance rule by ID.

ruleId · string · required

The ID of the rule to retrieve.

Returns: ComplianceRule | undefined

Example:

const rule = complianceEngine.getRule('pii-detection');
if (rule) {
  console.log(`Rule: ${rule.name}`);
  console.log(`Status: ${rule.isActive ? 'Active' : 'Inactive'}`);
  console.log(`Severity: ${rule.severity}`);
}

Built-in Compliance Rules

The ComplianceEngine comes with several built-in rules for common banking compliance requirements:

PII Detection Rules

privacy-pii-detection

Category: privacy Severity: violation Description: Detects potential PII like phone numbers and emails Patterns: Email addresses, phone numbers (US format) Risk Score: 15-20 points per detection

ssn-validation

Category: privacy Severity: violation Description: Robust SSN validation with format checking Patterns: Valid SSN formats, excludes known invalid ranges Risk Score: 50 points per valid SSN detected

Fair Lending Rules

fair-lending-keywords

Category: fair_lending Severity: violation Description: Detects potentially discriminatory language Patterns: “people like you”, “your kind”, “typical for”, “based on your background” Risk Score: 60 points per discriminatory phrase

BSA/AML Rules

Additional BSA/AML rules can be added through custom rule implementation.

Custom Rule Examples

Advanced PII Detection

complianceEngine.addRule({
  id: 'advanced-pii-detection',
  name: 'Advanced PII Detection',
  description: 'Detects credit card numbers, bank account numbers, and other sensitive data',
  category: 'privacy',
  severity: 'violation',
  isActive: true,
  ruleFunction: (context) => {
    const violations = [];
    const text = `${context.userMessage || ''} ${context.agentResponse || ''}`;

    // Credit card number pattern (simplified)
    const ccPattern = /\b(?:\d{4}[\s-]?){3}\d{4}\b/g;
    let match;

    while ((match = ccPattern.exec(text)) !== null) {
      violations.push({
        rule: 'advanced-pii-detection',
        severity: 'violation',
        description: 'Potential credit card number detected',
        context: { detected: match[0].replace(/\d(?=\d{4})/g, '*') },
        recommendation: 'Remove or mask credit card information'
      });
    }

    // Bank account number pattern (simplified)
    const accountPattern = /\b\d{8,17}\b/g;
    while ((match = accountPattern.exec(text)) !== null) {
      if (match[0].length >= 10) { // Likely account number
        violations.push({
          rule: 'advanced-pii-detection',
          severity: 'violation',
          description: 'Potential bank account number detected',
          context: { detected: match[0].substring(0, 4) + '***' },
          recommendation: 'Remove or mask account information'
        });
      }
    }

    return {
      isCompliant: violations.length === 0,
      violations,
      riskScore: violations.length * 40,
      requiresReview: violations.length > 0
    };
  }
});

BSA/AML Suspicious Activity Detection

complianceEngine.addRule({
  id: 'bsa-aml-suspicious-activity',
  name: 'BSA/AML Suspicious Activity Detection',
  description: 'Detects keywords and patterns associated with money laundering',
  category: 'bsa_aml',
  severity: 'warning',
  isActive: true,
  ruleFunction: (context) => {
    const violations = [];
    const text = `${context.userMessage || ''} ${context.agentResponse || ''}`.toLowerCase();

    const suspiciousKeywords = [
      'large cash deposit',
      'avoid reporting',
      'split transaction',
      'just under 10000',
      'cash business',
      'money transfer',
      'hawala',
      'informal transfer'
    ];

    const structuringPatterns = [
      /\$9[5-9]\d{2}/g, // Amounts just under $10,000
      /multiple.*deposit.*same.*day/gi,
      /cash.*structur/gi,
      /avoid.*report/gi
    ];

    // Check for suspicious keywords
    suspiciousKeywords.forEach(keyword => {
      if (text.includes(keyword)) {
        violations.push({
          rule: 'bsa-aml-suspicious-activity',
          severity: 'warning',
          description: `Suspicious activity keyword detected: "${keyword}"`,
          context: { keyword, category: 'suspicious_keyword' },
          recommendation: 'Review transaction for potential SAR filing'
        });
      }
    });

    // Check for structuring patterns
    structuringPatterns.forEach((pattern, index) => {
      let match;
      while ((match = pattern.exec(text)) !== null) {
        violations.push({
          rule: 'bsa-aml-suspicious-activity',
          severity: 'warning',
          description: 'Potential structuring pattern detected',
          context: {
            pattern: match[0],
            category: 'structuring_pattern',
            patternType: `pattern_${index + 1}`
          },
          recommendation: 'Investigate for potential structuring activity'
        });
      }
    });

    return {
      isCompliant: violations.filter(v => v.severity === 'violation').length === 0,
      violations,
      riskScore: violations.length * 25,
      requiresReview: violations.length > 2 || violations.some(v => v.context.category === 'structuring_pattern')
    };
  }
});

Consumer Protection Rule

complianceEngine.addRule({
  id: 'consumer-protection-disclosures',
  name: 'Consumer Protection Disclosures',
  description: 'Ensures required disclosures are provided for financial products',
  category: 'consumer_protection',
  severity: 'warning',
  isActive: true,
  ruleFunction: (context) => {
    const violations = [];
    const agentResponse = (context.agentResponse || '').toLowerCase();

    // Check for product sales without proper disclosures
    const productKeywords = [
      'loan', 'credit card', 'mortgage', 'investment', 'insurance',
      'account opening', 'deposit account', 'certificate of deposit'
    ];

    const requiredDisclosures = [
      'terms and conditions',
      'annual percentage rate',
      'fees may apply',
      'fdic insured',
      'disclosure',
      'agreement'
    ];

    const hasProductMention = productKeywords.some(keyword =>
      agentResponse.includes(keyword)
    );

    if (hasProductMention) {
      const hasDisclosure = requiredDisclosures.some(disclosure =>
        agentResponse.includes(disclosure)
      );

      if (!hasDisclosure) {
        violations.push({
          rule: 'consumer-protection-disclosures',
          severity: 'warning',
          description: 'Financial product mentioned without required disclosures',
          context: {
            productMentioned: true,
            disclosureProvided: false,
            agentResponse: agentResponse.substring(0, 100) + '...'
          },
          recommendation: 'Include appropriate disclosures when discussing financial products'
        });
      }
    }

    return {
      isCompliant: violations.length === 0,
      violations,
      riskScore: violations.length * 15,
      requiresReview: violations.length > 0
    };
  }
});

ComplianceResult Type

The result returned by evaluateInteraction() and rule functions:

interface ComplianceResult {
  isCompliant: boolean;           // Overall compliance status
  violations: ComplianceViolation[]; // Array of detected violations
  riskScore: number;              // Calculated risk score (0-100)
  requiresReview: boolean;        // Whether human review is needed
}

interface ComplianceViolation {
  rule: string;                   // ID of the rule that detected the violation
  severity: 'info' | 'warning' | 'violation'; // Severity level
  description: string;            // Human-readable description
  context?: any;                  // Additional context about the violation
  recommendation?: string;        // Suggested remediation action
}

Best Practices

Rule Development

• Keep rules focused: Each rule should check for one specific type of violation
• Use descriptive IDs: Rule IDs should be clear and consistent
• Provide context: Include relevant context in violation objects
• Test thoroughly: Test rules with various input scenarios
• Document patterns: Clearly document what patterns trigger violations

Performance Optimization

• Optimize regex patterns: Use efficient regular expressions
• Cache compiled patterns: Pre-compile complex patterns in rule constructors
• Limit text processing: Only process relevant text content
• Set appropriate severity: Use ‘info’ for low-impact violations
• Batch evaluations: Process multiple interactions efficiently

Compliance Management

• Regular rule updates: Keep rules current with regulatory changes
• Audit trail: Log all rule changes and activations
• False positive monitoring: Track and reduce false positives
• Risk scoring consistency: Use consistent risk scoring across rules
• Review thresholds: Set appropriate review thresholds for your organization

Banking Compliance

• Stay current: Keep up with regulatory guidance and changes
• Industry standards: Follow established compliance patterns
• Documentation: Maintain thorough documentation of compliance procedures
• Human oversight: Always include human review for high-risk violations
• Regular auditing: Perform regular compliance audits and assessments

Error Handling

The ComplianceEngine handles errors gracefully:

try {
  const result = complianceEngine.evaluateInteraction(context);
  console.log('Compliance evaluation completed:', result);
} catch (error) {
  console.error('Compliance evaluation failed:', error.message);
  // Continue with monitoring - don't let compliance failures break the application
}

Individual rule failures are logged but don’t prevent other rules from executing.

Next Steps

Custom Rules Example

See detailed examples of creating custom compliance rules

Compliance Monitoring

Learn about comprehensive compliance monitoring workflows

Banking Workflows

Implement compliance in banking workflows

AgentMonitor Class

Learn about the main monitoring class