AI governance and alignment monitoring for the Wundr platform
npm install @wundr.io/governanceAI governance and alignment monitoring for the Wundr platform, implementing the IPRE governance framework: Intent, Policies, Rewards, and Evaluators.
- Overview
- Installation
- IPRE Framework
- Intent
- Policies
- Rewards
- Evaluators
- Quick Start
- API Reference
- IntentParser
- PolicyEngine
- RewardCalculator
- EvaluatorAgent
- VP Daemon Integration
- Configuration
- Examples
The @wundr.io/governance package provides a comprehensive framework for monitoring AI system alignment, ensuring policy compliance, and detecting behavioral drift. It implements the IPRE governance model which structures AI governance into four interconnected layers:
1. Intent - The strategic mission and values that guide AI behavior
2. Policies - Hard constraints that must never be violated (security, compliance, operational)
3. Rewards - Weighted objectives that incentivize desired behaviors
4. Evaluators - Monitoring agents that continuously assess alignment
``bash`
npm install @wundr.io/governanceor
pnpm add @wundr.io/governanceor
yarn add @wundr.io/governance
The Intent layer defines the organization's strategic purpose and core values. It answers the question: "What are we trying to achieve?"
`typescript
import { IntentParser, createIntentParser } from '@wundr.io/governance';
// Parse intent from YAML
const parser = createIntentParser();
const intent = parser.parseFromYAML(
mission: "Build AI systems that augment human capabilities while maintaining safety"
values:
- transparency
- user_privacy
- reliability
- innovation
constraints:
- "Never compromise user data security"
- "Always provide explainable outputs"
goals:
- "Achieve 99.9% uptime"
- "Reduce false positive rate below 1%");
// Validate the intent
const validation = parser.validate(intent);
if (!validation.valid) {
console.error('Intent validation errors:', validation.errors);
}
// Convert to system prompt context
const promptContext = parser.toPromptContext(intent);
`
Intent Interface:
`typescript`
interface Intent {
mission: string; // The organization's primary purpose
values: string[]; // Core principles guiding decisions
constraints?: string[]; // Boundaries that must be respected
goals?: string[]; // Strategic objectives to achieve
}
The Policies layer defines hard constraints that AI agents must never violate. Policies are organized into three categories:
- Security - Prevent security vulnerabilities (secrets in code, SQL injection, XSS, command injection)
- Compliance - Ensure regulatory and process compliance (PR reviews, no force pushes, test coverage)
- Operational - Maintain operational excellence (deployment windows, rollback plans)
`typescript
import { PolicyEngine } from '@wundr.io/governance';
const engine = new PolicyEngine({
debug: true,
maxHistorySize: 10000,
defaultSeverity: 'medium',
defaultBlocking: true,
});
// Check an agent action against all policies
const result = engine.checkAction({
id: 'action-1',
sessionId: 'session-123',
agentId: 'coder-1',
type: 'commit',
description: 'Add user authentication',
timestamp: new Date(),
codeContent: 'const apiKey = "sk-secret123"', // This will trigger sec-001
});
if (!result.allowed) {
console.log('Action blocked!');
for (const violation of result.violations) {
console.log(- [${violation.severity}] ${violation.message});`
}
}
Default Security Policies:
| Policy ID | Name | Description | Severity |
|-----------|------|-------------|----------|
| sec-001 | No secrets in code | Prevents hardcoded secrets, API keys, passwords | Critical |
| sec-002 | No SQL injection | Prevents SQL injection vulnerabilities | Critical |
| sec-003 | No XSS | Prevents cross-site scripting vulnerabilities | High |
| sec-004 | No command injection | Prevents command injection vulnerabilities | Critical |
Default Compliance Policies:
| Policy ID | Name | Description | Severity |
|-----------|------|-------------|----------|
| comp-001 | All changes require PR review | Ensures code goes through review | High |
| comp-002 | No force pushes | Prevents force pushes to protected branches | Critical |
| comp-003 | Test coverage minimum 80% | Ensures adequate test coverage | Medium |
Default Operational Policies:
| Policy ID | Name | Description | Severity |
|-----------|------|-------------|----------|
| ops-001 | No Friday deployments after 2pm | Prevents risky late Friday deployments | High |
| ops-002 | Rollback plan required | Requires rollback plan for production changes | High |
Adding Custom Policies:
`typescript`
engine.loadPolicies({
security: [
{
id: 'sec-custom-001',
name: 'No eval usage',
description: 'Prevents use of eval() which can be a security risk',
pattern: 'eval\\s*\\(',
severity: 'high',
blocking: true,
},
],
compliance: [
{
name: 'Changelog required',
description: 'All PRs must update the changelog',
validatorName: 'changelog_check',
severity: 'medium',
blocking: false,
},
],
});
The Rewards layer implements weighted objective scoring to incentivize desired behaviors. It calculates composite scores across multiple dimensions:
`typescript
import { RewardCalculator, createRewardCalculator } from '@wundr.io/governance';
// Create calculator with default weights
const calculator = createRewardCalculator();
// Or customize weights (must sum to 1.0)
const customCalculator = createRewardCalculator({
customer_value: 0.40, // 40%
code_quality: 0.25, // 25%
delivery_speed: 0.15, // 15%
technical_debt_reduction: 0.15, // 15%
documentation: 0.05, // 5%
});
// Calculate score from metrics (0-100 scale)
const score = calculator.calculateScore({
customer_value: 85,
code_quality: 92,
delivery_speed: 78,
technical_debt_reduction: 65,
documentation: 88,
});
console.log(Overall Score: ${score.overall});`
console.log('Breakdown:', score.byDimension);
Default Weight Configuration:
| Dimension | Weight | Description |
|-----------|--------|-------------|
| customer_value | 0.35 | Value delivered to customers |
| code_quality | 0.25 | Code maintainability and correctness |
| delivery_speed | 0.20 | Velocity of feature delivery |
| technical_debt_reduction | 0.15 | Progress on reducing tech debt |
| documentation | 0.05 | Quality and completeness of docs |
Score Comparison and Analysis:
`typescript
// Compare current score against a baseline
const comparison = calculator.compareToBaseline(currentScore, baselineScore);
console.log(Overall change: ${comparison.overallDelta});Improved: ${comparison.improved}
console.log();
console.log('Significant changes:', comparison.significantChanges);
// Identify areas needing improvement
const improvementAreas = calculator.identifyImprovementAreas(currentScore);
console.log('Focus on:', improvementAreas);
`
The Evaluators layer provides monitoring agents that continuously assess alignment across three dimensions:
1. Policy Compliance - Checks adherence to defined policies
2. Reward Alignment - Verifies scores meet expected thresholds
3. Drift Detection - Monitors for behavioral drift over time
`typescript
import {
EvaluatorAgent,
createEvaluator,
createEvaluatorSuite,
runEvaluatorSuite,
} from '@wundr.io/governance';
// Create individual evaluator
const policyEvaluator = createEvaluator('policy_compliance', {
threshold: 0.8,
frequency: 'per_commit',
action: 'block_on_violation',
});
// Create evaluation context
const context = {
evaluationId: 'eval-001',
timestamp: new Date(),
source: 'commit',
repository: 'my-project',
branch: 'feature/new-feature',
commitSha: 'abc123',
changedFiles: ['src/auth.ts', 'src/utils.ts'],
};
// Run evaluation
const result = await policyEvaluator.evaluate(context);
if (!result.passed) {
console.log('Evaluation failed!');
console.log('Score:', result.score);
console.log('Issues:', result.issues);
console.log('Recommendations:', result.recommendations);
console.log('Action:', result.action);
}
`
Evaluator Types and Defaults:
| Type | Frequency | Threshold | Action |
|------|-----------|-----------|--------|
| policy_compliance | per_commit | 0.8 | block_on_violation |
| reward_alignment | hourly | 0.85 | escalate_to_guardian |
| drift_detection | daily | 0.9 | alert_architect |
Running Multiple Evaluators:
`typescript
// Create a complete evaluator suite
const suite = createEvaluatorSuite();
const evaluators = [
suite.policyCompliance,
suite.rewardAlignment,
suite.driftDetection,
];
// Run all evaluators in parallel
const aggregatedResult = await runEvaluatorSuite(evaluators, context);
console.log(Overall passed: ${aggregatedResult.passed});Overall score: ${aggregatedResult.overallScore}
console.log();Critical issues: ${aggregatedResult.criticalIssues.length}
console.log();`
`typescript
import {
createIntentParser,
PolicyEngine,
createRewardCalculator,
createEvaluatorSuite,
runEvaluatorSuite,
type IPREConfig,
} from '@wundr.io/governance';
// 1. Define Intent
const parser = createIntentParser();
const intent = parser.parseFromYAML(
mission: "Deliver secure, reliable AI-powered trading solutions"
values:
- security_first
- regulatory_compliance
- user_trust);
// 2. Initialize Policy Engine
const policyEngine = new PolicyEngine({ debug: true });
// 3. Set up Reward Calculator
const rewardCalculator = createRewardCalculator();
// 4. Create Evaluator Suite
const evaluators = createEvaluatorSuite();
// 5. Check an action
const action = {
id: 'action-001',
sessionId: 'session-001',
agentId: 'trading-agent',
type: 'commit',
description: 'Update trading algorithm',
timestamp: new Date(),
codeContent: '// safe code here',
};
const policyResult = policyEngine.checkAction(action);
if (policyResult.allowed) {
// Calculate rewards
const metrics = {
customer_value: 90,
code_quality: 85,
delivery_speed: 80,
technical_debt_reduction: 70,
documentation: 75,
};
const score = rewardCalculator.calculateScore(metrics);
console.log(Reward score: ${score.overall});`
} else {
console.log('Action blocked by policy:', policyResult.violations);
}
Constructor:
`typescript`
new IntentParser(config?: IntentParserConfig)
| Config Option | Type | Default | Description |
|---------------|------|---------|-------------|
| strict | boolean | true | Enforce strict validation |
| conflictRules | ConflictRule[] | default rules | Custom conflict detection rules |
| maxValues | number | Infinity | Maximum number of values allowed |
| maxConstraints | number | Infinity | Maximum number of constraints |
| maxGoals | number | Infinity | Maximum number of goals |
Methods:
| Method | Returns | Description |
|--------|---------|-------------|
| parseFromYAML(content: string) | Intent | Parse intent from YAML string |
| parseFromJSON(content: string) | Intent | Parse intent from JSON string |
| parseFromFile(path: string) | Promise\
| validate(intent: Intent) | ValidationResult | Validate an intent object |
| extractValues(intent: Intent) | string[] | Extract values array |
| extractMission(intent: Intent) | string | Extract mission string |
| toPromptContext(intent: Intent) | string | Convert to system prompt context |
Constructor:
`typescript`
new PolicyEngine(config?: PolicyEngineConfig)
| Config Option | Type | Default | Description |
|---------------|------|---------|-------------|
| debug | boolean | false | Enable debug logging |
| maxHistorySize | number | 10000 | Maximum violations to track |
| defaultSeverity | ViolationSeverity | 'medium' | Default severity for new policies |
| defaultBlocking | boolean | true | Default blocking behavior |
| customValidators | Record\
| logger | PolicyEngineLogger | undefined | Custom logger |
Methods:
| Method | Returns | Description |
|--------|---------|-------------|
| loadPolicies(config: PolicyConfig) | void | Load additional policies |
| checkAction(action: AgentAction) | PolicyCheckResult | Check action against all policies |
| isBlocked(action: AgentAction) | boolean | Quick check if action is blocked |
| getViolations(action: AgentAction) | PolicyViolation[] | Get violations without recording |
| recordViolation(violation: PolicyViolation) | void | Record a violation |
| getViolationHistory(sessionId?: string) | PolicyViolation[] | Get violation history |
| getViolationRate(timeWindowMs?: number) | number | Calculate violations per hour |
| getPolicies() | PolicySet | Get all policies |
| setPolicyEnabled(policyId: string, enabled: boolean) | void | Enable/disable a policy |
| clearViolationHistory(sessionId?: string) | void | Clear violation history |
| getViolationStats() | ViolationStats | Get violation statistics |
Constructor:
`typescript`
new RewardCalculator(weights?: Partial
Methods:
| Method | Returns | Description |
|--------|---------|-------------|
| calculateScore(metrics: RewardMetrics) | RewardScore | Calculate weighted score |
| getWeightedScore(dimension: string, value: number) | number | Get single dimension weighted score |
| normalizeScores(scores: Record\
| updateWeights(newWeights: Partial\
| getWeights() | RewardWeights | Get current weights |
| compareToBaseline(current: RewardScore, baseline: RewardScore) | ScoreComparison | Compare against baseline |
| identifyImprovementAreas(score: RewardScore) | string[] | Find areas needing improvement |
Constructor:
`typescript`
new EvaluatorAgent(config: EvaluatorConfig)
| Config Option | Type | Required | Description |
|---------------|------|----------|-------------|
| evaluatorType | EvaluatorType | Yes | Type of evaluator |
| frequency | EvaluationFrequency | Yes | How often to run |
| threshold | number | Yes | Score threshold (0-1) |
| action | ViolationAction | Yes | Action on violation |
| name | string | No | Evaluator instance name |
| options | EvaluatorOptions | No | Additional options |
Methods:
| Method | Returns | Description |
|--------|---------|-------------|
| evaluate(context: EvaluationContext) | Promise\
| checkPolicyCompliance(context: EvaluationContext) | Promise\
| checkRewardAlignment(context: EvaluationContext, rewardScore: RewardScore) | Promise\
| detectDrift(context: EvaluationContext, patterns: string[]) | Promise\
| shouldTriggerAction(result: EvaluationResult) | boolean | Check if action needed |
| getRecommendedAction(result: EvaluationResult) | string | Get recommended action |
| getEvaluatorType() | EvaluatorType | Get evaluator type |
| getFrequency() | EvaluationFrequency | Get frequency |
| getThreshold() | number | Get threshold |
| getAction() | ViolationAction | Get configured action |
| getName() | string | Get evaluator name |
The governance package is designed to integrate with the VP (Virtual Processor) Daemon for real-time policy enforcement. The VP Daemon acts as a middleware layer that intercepts AI agent actions and enforces governance policies.
``
+-------------------+ +------------+ +------------------+
| AI Agent | --> | VP Daemon | --> | Target System |
| (Coder, etc.) | | (Enforcer) | | (Git, Deploy) |
+-------------------+ +------------+ +------------------+
|
v
+-------------------+
| @wundr/governance |
| - PolicyEngine |
| - EvaluatorAgent |
| - RewardCalc |
+-------------------+
`typescript
import { PolicyEngine, createEvaluatorSuite } from '@wundr.io/governance';
class VPDaemon {
private policyEngine: PolicyEngine;
private evaluators: ReturnType
constructor() {
this.policyEngine = new PolicyEngine({
debug: process.env.NODE_ENV === 'development',
});
this.evaluators = createEvaluatorSuite();
}
async interceptAction(action: AgentAction): Promise
// 1. Check against hard policies
const policyResult = this.policyEngine.checkAction(action);
if (!policyResult.allowed) {
return {
allowed: false,
reason: 'Policy violation',
violations: policyResult.violations,
};
}
// 2. Run continuous evaluation (async, non-blocking)
this.runAsyncEvaluation(action);
// 3. Allow the action to proceed
return { allowed: true };
}
private async runAsyncEvaluation(action: AgentAction): Promise
const context = this.actionToContext(action);
// Run policy compliance check
const complianceResult = await this.evaluators.policyCompliance.evaluate(context);
if (!complianceResult.passed) {
this.alertOnViolation(complianceResult);
}
// Run drift detection (daily)
if (this.shouldRunDriftDetection()) {
const driftResult = await this.evaluators.driftDetection.evaluate(context);
if (!driftResult.passed) {
this.alertOnDrift(driftResult);
}
}
}
}
`
`typescript
// .husky/pre-commit or similar
import { PolicyEngine } from '@wundr.io/governance';
async function preCommitCheck(): Promise
const engine = new PolicyEngine();
const stagedFiles = await getStagedFiles();
const codeContent = await getFileContents(stagedFiles);
const result = engine.checkAction({
id: commit-${Date.now()},
sessionId: 'pre-commit',
agentId: 'git-hook',
type: 'commit',
description: 'Pre-commit check',
timestamp: new Date(),
affectedFiles: stagedFiles,
codeContent,
});
if (!result.allowed) {
console.error('Commit blocked due to policy violations:');
for (const violation of result.violations) {
console.error( - [${violation.severity}] ${violation.message});
}
process.exit(1);
}
}
preCommitCheck();
`
`typescript`
interface IPREConfig {
version: string;
intent: Intent;
policies: Policy;
rewards: Rewards;
evaluators: EvaluatorConfig[];
metadata?: IPREMetadata;
}
`yamlipre.config.yaml
version: "1.0.0"
intent:
mission: "Build secure, reliable AI trading systems"
values:
- security_first
- regulatory_compliance
- transparency
- user_trust
constraints:
- "Never expose customer financial data"
- "Always comply with SEC regulations"
goals:
- "Maintain 99.99% uptime"
- "Achieve SOC2 compliance"
policies:
security:
- id: "sec-custom-001"
name: "No raw SQL queries"
pattern: "execute.SELECT.FROM"
severity: "critical"
blocking: true
compliance:
- id: "comp-custom-001"
name: "Require approval for trades > $1M"
validatorName: "large_trade_approval"
severity: "high"
blocking: true
operational:
- id: "ops-custom-001"
name: "No deployments during market hours"
validatorName: "market_hours_check"
severity: "high"
blocking: true
rewards:
weights:
customer_value: 0.30
code_quality: 0.25
security_posture: 0.25
operational_excellence: 0.15
compliance: 0.05
threshold: 75
frequency: "hourly"
evaluators:
- id: "eval-001"
name: "Trading Policy Compliance"
type: "static"
frequency: "realtime"
threshold: 0.95
action: "block"
enabled: true
metadata:
createdAt: "2024-01-01T00:00:00Z"
updatedAt: "2024-01-15T10:30:00Z"
author: "governance-team"
description: "IPRE configuration for Wundr trading platform"
`
`typescript
import {
createIntentParser,
PolicyEngine,
createRewardCalculator,
createEvaluatorSuite,
runEvaluatorSuite,
} from '@wundr.io/governance';
async function runGovernanceWorkflow() {
// Initialize all components
const intentParser = createIntentParser();
const policyEngine = new PolicyEngine({ debug: true });
const rewardCalculator = createRewardCalculator();
const evaluatorSuite = createEvaluatorSuite();
// Load intent from file
const intent = await intentParser.parseFromFile('./ipre-intent.yaml');
const promptContext = intentParser.toPromptContext(intent);
console.log('Intent loaded:', intent.mission);
// Define an agent action
const action = {
id: 'action-trading-001',
sessionId: 'trading-session-001',
agentId: 'trading-agent-alpha',
type: 'trade_execution',
description: 'Execute buy order for AAPL',
timestamp: new Date(),
metadata: {
symbol: 'AAPL',
quantity: 100,
orderType: 'market',
},
};
// Step 1: Policy Check (synchronous, blocking)
const policyResult = policyEngine.checkAction(action);
if (!policyResult.allowed) {
console.error('Action blocked by policies:');
policyResult.violations.forEach(v => {
console.error( - ${v.policy.name}: ${v.message});
});
return;
}
console.log('Policy check passed');
// Step 2: Calculate Reward Score
const metrics = {
customer_value: 88,
code_quality: 92,
delivery_speed: 85,
technical_debt_reduction: 72,
documentation: 80,
};
const rewardScore = rewardCalculator.calculateScore(metrics);
console.log(Reward Score: ${rewardScore.overall.toFixed(2)});
// Step 3: Run Evaluator Suite
const context = {
evaluationId: eval-${Date.now()},
timestamp: new Date(),
source: 'manual' as const,
repository: 'trading-system',
metadata: { action: action.id },
};
const evaluators = [
evaluatorSuite.policyCompliance,
evaluatorSuite.rewardAlignment,
evaluatorSuite.driftDetection,
];
const suiteResult = await runEvaluatorSuite(evaluators, context);
console.log(Suite Result: ${suiteResult.passed ? 'PASSED' : 'FAILED'});Overall Score: ${(suiteResult.overallScore * 100).toFixed(1)}%
console.log();
if (suiteResult.criticalIssues.length > 0) {
console.log('Critical Issues:');
suiteResult.criticalIssues.forEach(issue => {
console.log( - ${issue});
});
}
// Step 4: Get Violation Statistics
const stats = policyEngine.getViolationStats();
console.log('\nViolation Statistics:');
console.log( Total: ${stats.total}); By Category: ${JSON.stringify(stats.byCategory)}
console.log(); Blocking: ${stats.blockingCount}
console.log();
}
runGovernanceWorkflow().catch(console.error);
``
MIT