@wundr.io/governance

AI governance and alignment monitoring for the Wundr platform, implementing the IPRE governance framework: Intent, Policies, Rewards, and Evaluators.

Table of Contents

- Overview
- Installation
- IPRE Framework
- Intent
- Policies
- Rewards
- Evaluators
- Quick Start
- API Reference
- IntentParser
- PolicyEngine
- RewardCalculator
- EvaluatorAgent
- VP Daemon Integration
- Configuration
- Examples

Overview

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

Installation

``bash
npm install @wundr.io/governance


or

pnpm add @wundr.io/governance

or

yarn add @wundr.io/governance
`

IPRE Framework

$3

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
}
`

$3

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,
},
],
});
`

$3

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});
console.log(Improved: ${comparison.improved});
console.log('Significant changes:', comparison.significantChanges);

// Identify areas needing improvement
const improvementAreas = calculator.identifyImprovementAreas(currentScore);
console.log('Focus on:', improvementAreas);
`

$3

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});
console.log(Overall score: ${aggregatedResult.overallScore});
console.log(Critical issues: ${aggregatedResult.criticalIssues.length});
`

Quick Start

`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);
}
`

API Reference

$3

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\ | Parse intent from file (.yaml, .yml, .json) |
| 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 |

$3

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\ | {} | Custom validator functions |
| 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 |

$3

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\) | Record\ | Normalize scores to sum to 100 |
| updateWeights(newWeights: Partial\) | void | Update weight configuration |
| getWeights() | RewardWeights | Get current weights |
| compareToBaseline(current: RewardScore, baseline: RewardScore) | ScoreComparison | Compare against baseline |
| identifyImprovementAreas(score: RewardScore) | string[] | Find areas needing improvement |

$3

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\ | Run evaluation |
| checkPolicyCompliance(context: EvaluationContext) | Promise\ | Check policy compliance |
| checkRewardAlignment(context: EvaluationContext, rewardScore: RewardScore) | Promise\ | Check reward alignment |
| detectDrift(context: EvaluationContext, patterns: string[]) | Promise\ | Detect drift |
| 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 |

VP Daemon Integration

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.

$3

`
+-------------------+ +------------+ +------------------+
| AI Agent | --> | VP Daemon | --> | Target System |
| (Coder, etc.) | | (Enforcer) | | (Git, Deploy) |
+-------------------+ +------------+ +------------------+
|
v
+-------------------+
| @wundr/governance |
| - PolicyEngine |
| - EvaluatorAgent |
| - RewardCalc |
+-------------------+
`

$3

`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);
}
}
}
}
`

$3

`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();
`

Configuration

$3

`typescript
interface IPREConfig {
version: string;
intent: Intent;
policies: Policy;
rewards: Rewards;
evaluators: EvaluatorConfig[];
metadata?: IPREMetadata;
}
`

$3

`yaml


ipre.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"
`

Examples

$3

`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'});
console.log(Overall Score: ${(suiteResult.overallScore * 100).toFixed(1)}%);

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});
console.log( By Category: ${JSON.stringify(stats.byCategory)});
console.log( Blocking: ${stats.blockingCount});
}

runGovernanceWorkflow().catch(console.error);
``

License

MIT