@guardrail-sim/insights

Policy insights, health checks, and best practice recommendations for B2B pricing governance.

Installation

npm install @guardrail-sim/insights

Quick Start

import { analyzePolicy, createRecommendationEngine } from '@guardrail-sim/insights';
 
// Quick analysis
const report = await analyzePolicy({
  policy: policyData,
  simulationResults: results,
});
 
console.log(`Found ${report.summary.total} insights`);
console.log(`Critical: ${report.summary.critical}`);
console.log(`Warnings: ${report.summary.warning}`);

RecommendationEngine

For more control, use the recommendation engine directly:

import { createRecommendationEngine } from '@guardrail-sim/insights';
 
const engine = createRecommendationEngine({
  minSeverity: 'warning', // Ignore 'info' level insights
  categories: ['policy-health', 'margin-protection'],
  excludeChecks: ['lowSimulationCoverage'], // Skip specific checks
});
 
const report = await engine.analyze({
  policy: policyData,
  simulationResults: results,
  userSettings: { marginFloor: 0.15 },
});

Insight Categories

Policy Health

Checks for structural issues with your policy:

Check	Description
`noMarginFloor`	Policy has no minimum margin rule
`noMaxDiscountCap`	Policy has no maximum discount cap
`tooFewRules`	Policy has fewer than 2 rules
`conflictingRules`	Rules may contradict each other
`noPrioritySet`	Rules lack priority ordering
`highMarginFloor`	Margin floor may be too restrictive
`lowMarginFloor`	Margin floor may be too permissive
`noVolumeConsideration`	No volume-based rules

Margin Protection

Checks for margin risk based on simulation results:

Check	Description
`highApprovalRate`	> 95% of discounts approved
`lowApprovalRate`	< 50% of discounts approved
`marginFloorFrequentlyHit`	Margin floor is the limiting factor > 30%
`averageMarginDeclining`	Average margin trending down
`singleRuleDominates`	One rule causing > 80% of rejections
`discountGap`	Large gap between requested and max allowed

Simulation Analysis

Insights from simulation coverage:

Check	Description
`lowSimulationCoverage`	< 100 scenarios tested
`segmentImbalance`	Customer segments not evenly tested
`unusedRules`	Rules never triggered in simulation
`volumeTierUnderutilized`	Volume discounts rarely used
`highValueOrderRejection`	Large orders being rejected
`noLimitingFactorVariety`	Same rule always limits discounts

Built-in Checklists

Pre-built checklists for common workflows:

import {
  policySetupChecklist,
  policyReviewChecklist,
  preDeploymentChecklist,
} from '@guardrail-sim/insights';
 
// Use with your policy data
const progress = policySetupChecklist.evaluate(policyData);
console.log(`${progress.completed}/${progress.total} items complete`);

Policy Setup Checklist

For new policy creation:

Has unique policy ID
Has descriptive name
Has at least 2 rules
Rules have priorities set
Margin floor defined
Maximum discount cap defined

Policy Review Checklist

For periodic policy audits:

Margin floor is appropriate (10-20%)
Discount cap is reasonable (< 50%)
Volume tiers are utilized
Customer segments covered
No conflicting rules

Pre-Deployment Checklist

Before going live:

Ran at least 100 simulations
All rules triggered at least once
No critical insights
Approval rate is healthy (60-90%)
Margin floor rarely hit (< 20%)

Insight Structure

Each insight follows this structure:

interface Insight {
  id: string; // 'noMarginFloor'
  category: string; // 'policy-health'
  severity: 'critical' | 'warning' | 'info';
  title: string; // 'Missing Margin Floor'
  description: string; // Detailed explanation
  actions: InsightAction[]; // Suggested fixes
}
 
interface InsightAction {
  label: string; // 'Add margin floor rule'
  type: 'link' | 'code' | 'manual';
  value: string; // URL, code snippet, or instructions
}

Custom Insight Packs

Create your own insight checks:

import type { InsightCheck, InsightPack } from '@guardrail-sim/insights';
 
const myCheck: InsightCheck = {
  id: 'holidaySeasonReady',
  category: 'seasonal',
  check: (context) => {
    const hasHolidayRule = context.policy.rules.some((r) => r.name.includes('holiday'));
 
    if (!hasHolidayRule) {
      return {
        severity: 'warning',
        title: 'No Holiday Rules',
        description: 'Consider adding holiday-specific discount rules',
        actions: [
          { label: 'View example', type: 'link', value: '/docs/examples/promotional-limits' },
        ],
      };
    }
    return null;
  },
};
 
const myPack: InsightPack = {
  name: 'seasonal-checks',
  checks: [myCheck],
};
 
// Register with engine
const engine = createRecommendationEngine({
  additionalPacks: [myPack],
});

Report Structure

The analysis report includes:

interface RecommendationReport {
  summary: {
    total: number;
    critical: number;
    warning: number;
    info: number;
  };
  insights: Insight[];
  checklists: ChecklistProgress[];
  generatedAt: Date;
}

Example Usage

import { analyzePolicy } from '@guardrail-sim/insights';
import type { PolicySummary, SimulationSummary } from '@guardrail-sim/insights';
 
// Prepare your data
const policy: PolicySummary = {
  id: 'default-b2b-policy',
  name: 'Default B2B Pricing Policy',
  rules: [
    { name: 'margin_floor', triggerCount: 45, rejectionCount: 45 },
    { name: 'max_discount', triggerCount: 12, rejectionCount: 12 },
    { name: 'volume_tier', triggerCount: 28, rejectionCount: 28 },
  ],
};
 
const simulation: SimulationSummary = {
  totalScenarios: 500,
  approved: 415,
  rejected: 85,
  averageMargin: 0.22,
  marginDistribution: { min: 0.15, max: 0.38, median: 0.21 },
  segmentBreakdown: {
    new: { count: 100, approved: 70 },
    gold: { count: 200, approved: 185 },
    platinum: { count: 200, approved: 160 },
  },
};
 
// Analyze
const report = await analyzePolicy({ policy, simulationResults: simulation });
 
// Handle results
for (const insight of report.insights) {
  if (insight.severity === 'critical') {
    console.error(`CRITICAL: ${insight.title}`);
    console.error(insight.description);
  }
}

Insights