@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: 'my-policy',
  name: 'My Pricing Policy',
  ruleCount: 3,
  rules: [
    { name: 'margin_floor', priority: 10, conditionCount: 1, eventType: 'violation' },
    { name: 'max_discount', priority: 10, conditionCount: 1, eventType: 'violation' },
    { name: 'volume_tier', priority: 5, conditionCount: 2, eventType: 'violation' },
  ],
  hasMarginFloor: true,
  marginFloorValue: 0.15,
  hasMaxDiscountCap: true,
  maxDiscountCapValue: 0.25,
  hasVolumeTiers: true,
  volumeTierThresholds: [100],
  hasSegmentRules: false,
};

const simulation: SimulationSummary = {
  totalOrders: 500, // one per buyer
  totalEvaluations: 1180, // one per negotiation round
  approvalRate: 0.83,
  averageDiscountApproved: 0.12,
  averageDiscountRequested: 0.18,
  averageMarginAfterDiscount: 0.22,
  violationsByRule: { margin_floor: 320, max_discount: 60, volume_tier: 145 },
  limitingFactors: { margin_floor: 100, max_discount: 40, volume_tier: 85 },
  ordersBySegment: { new: 100, gold: 200, platinum: 200 },
};

// 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