ruvnet--ruflo/v3/plugins/financial-risk

@claude-flow/plugin-financial-risk

A high-performance financial risk analysis plugin combining sparse inference for efficient market signal processing with graph neural networks for transaction network analysis. The plugin enables real-time anomaly detection, portfolio risk scoring, and automated compliance reporting while maintaining the explainability required by financial regulators (SEC, FINRA, Basel III).

Features

• Portfolio Risk Analysis: Calculate VaR, CVaR, Sharpe ratio, Sortino ratio, and max drawdown
• Anomaly Detection: Detect fraud, AML violations, and market manipulation in transactions
• Market Regime Classification: Identify current market regime through historical pattern matching
• Compliance Checking: Automated verification against Basel III, MiFID II, Dodd-Frank, AML, and KYC
• Stress Testing: Run historical and hypothetical stress scenarios on portfolios

Installation

npm

npm install @claude-flow/plugin-financial-risk

CLI

npx claude-flow plugins install --name @claude-flow/plugin-financial-risk

Quick Start

import { FinancialRiskPlugin } from '@claude-flow/plugin-financial-risk';

// Initialize the plugin
const finance = new FinancialRiskPlugin({
  marketDataPath: './data/market',
  modelPath: './data/models',
  auditLogPath: './logs/audit'
});

// Analyze portfolio risk
const risk = await finance.portfolioRisk({
  holdings: [
    { symbol: 'AAPL', quantity: 100, assetClass: 'equity' },
    { symbol: 'GOOGL', quantity: 50, assetClass: 'equity' },
    { symbol: 'TLT', quantity: 200, assetClass: 'bond' }
  ],
  riskMetrics: ['var', 'cvar', 'sharpe'],
  confidenceLevel: 0.95,
  horizon: '1d'
});

// Detect anomalies in transactions
const anomalies = await finance.anomalyDetect({
  transactions: [
    { id: 'tx-001', amount: 50000, timestamp: '2024-01-15T10:30:00Z', parties: ['ACC-123', 'ACC-456'] },
    { id: 'tx-002', amount: 1000000, timestamp: '2024-01-15T10:31:00Z', parties: ['ACC-123', 'ACC-789'] }
  ],
  sensitivity: 0.8,
  context: 'fraud'
});

// Check regulatory compliance
const compliance = await finance.complianceCheck({
  entity: 'FUND-001',
  regulations: ['basel3', 'mifid2'],
  scope: 'capital',
  asOfDate: '2024-01-15'
});

MCP Tools

1. finance/portfolio-risk

Calculate comprehensive portfolio risk metrics.

const result = await mcp.invoke('finance/portfolio-risk', {
  holdings: [
    { symbol: 'SPY', quantity: 1000, assetClass: 'equity' },
    { symbol: 'BND', quantity: 500, assetClass: 'bond' },
    { symbol: 'GLD', quantity: 200, assetClass: 'commodity' }
  ],
  riskMetrics: ['var', 'cvar', 'sharpe', 'max_drawdown'],
  confidenceLevel: 0.99,
  horizon: '1w'
});

// Returns:
// {
//   var: { value: 0.023, confidenceLevel: 0.99 },
//   cvar: { value: 0.031 },
//   sharpe: { value: 1.45 },
//   maxDrawdown: { value: 0.082, period: '2023-10-01 to 2023-10-15' }
// }

2. finance/anomaly-detect

Detect anomalies in financial transactions and market data.

const result = await mcp.invoke('finance/anomaly-detect', {
  transactions: [
    {
      id: 'tx-12345',
      amount: 250000,
      timestamp: '2024-01-15T14:30:00Z',
      parties: ['CORP-A', 'CORP-B'],
      metadata: { type: 'wire', currency: 'USD' }
    }
  ],
  sensitivity: 0.9,
  context: 'aml'
});

// Returns:
// {
//   anomalies: [{
//     transactionId: 'tx-12345',
//     score: 0.87,
//     reasons: ['unusual_amount', 'first_time_counterparty', 'velocity_spike'],
//     recommendation: 'review'
//   }]
// }

3. finance/market-regime

Identify current market regime through pattern matching.

const result = await mcp.invoke('finance/market-regime', {
  marketData: {
    prices: [100, 102, 99, 101, 103, 105, 104],
    volumes: [1000000, 1200000, 900000, 1100000, 1300000, 1500000, 1400000],
    volatility: [0.15, 0.16, 0.18, 0.17, 0.14, 0.13, 0.14]
  },
  lookbackPeriod: 252,
  regimeTypes: ['bull', 'bear', 'high_vol', 'crisis']
});

// Returns:
// {
//   currentRegime: 'bull',
//   confidence: 0.82,
//   similarHistoricalPeriods: ['2017-Q3', '2019-Q4'],
//   transitionProbabilities: { bull: 0.75, bear: 0.15, high_vol: 0.10 }
// }

4. finance/compliance-check

Automated regulatory compliance verification.

const result = await mcp.invoke('finance/compliance-check', {
  entity: 'BANK-001',
  regulations: ['basel3', 'dodd_frank'],
  scope: 'capital',
  asOfDate: '2024-01-15'
});

// Returns:
// {
//   compliant: true,
//   metrics: {
//     tier1Capital: { value: 0.125, requirement: 0.06, status: 'pass' },
//     leverageRatio: { value: 0.05, requirement: 0.03, status: 'pass' }
//   },
//   warnings: ['tier1 buffer approaching minimum']
// }

5. finance/stress-test

Run stress testing scenarios on portfolios.

const result = await mcp.invoke('finance/stress-test', {
  portfolio: {
    holdings: [
      { symbol: 'SPY', quantity: 1000 },
      { symbol: 'QQQ', quantity: 500 }
    ]
  },
  scenarios: [
    { name: '2008 Financial Crisis', type: 'historical', shocks: {} },
    { name: 'Interest Rate +300bp', type: 'hypothetical', shocks: { rateShock: 0.03 } }
  ],
  metrics: ['pnl', 'var_change', 'margin_call_risk']
});

Configuration Options

interface FinancialRiskConfig {
  // Data paths
  marketDataPath: string;         // Path to market data cache
  modelPath: string;              // Path to trained models

  // Compliance
  auditLogPath: string;           // Path for SOX-compliant audit logs
  regulatoryReporting: boolean;   // Enable auto-generated reports

  // Performance
  maxMemoryMB: number;            // WASM memory limit (default: 1024)
  maxCpuTimeSeconds: number;      // Operation timeout (default: 60)

  // Security
  encryptionEnabled: boolean;     // AES-256 encryption (default: true)
  hsmKeyId?: string;              // HSM key identifier for production

  // Rate limiting
  rateLimits: {
    requestsPerMinute: number;
    maxConcurrent: number;
  };
}

Security Considerations

Regulatory Compliance

This plugin is designed for financial regulatory compliance:

Requirement	Implementation
PCI-DSS Compliance	No storage of PAN/CVV in plugin memory
SOX Compliance	Immutable audit logs for all risk calculations
Data Encryption	AES-256 for data at rest, TLS 1.3 in transit
Key Management	HSM or secure enclave for cryptographic keys
Segregation of Duties	Separate roles for trading, risk, and compliance

Role-Based Access Control

const roles = {
  TRADER: ['portfolio-risk', 'market-regime'],
  RISK_MANAGER: ['portfolio-risk', 'anomaly-detect', 'stress-test', 'market-regime'],
  COMPLIANCE_OFFICER: ['compliance-check', 'anomaly-detect'],
  AUDITOR: ['compliance-check'],  // Read-only with full audit access
  QUANT: ['portfolio-risk', 'market-regime', 'stress-test']
};

Audit Logging (SOX/MiFID II)

All calculations are logged with:

• Timestamp with microsecond precision
• User ID and role
• Transaction IDs affected
• Portfolio state hash
• Model version used
• Input/output hashes for reproducibility

Logs are retained for 7 years per MiFID II requirements and available for regulatory inspection within 72 hours.

WASM Security Constraints

Constraint	Value	Rationale
Memory Limit	1GB max	Handle large transaction datasets
CPU Time Limit	60 seconds	Allow complex risk calculations
No Network Access	Enforced	Prevent data exfiltration
No File System Write	Enforced	Analysis-only mode
Sandboxed Data Access	Enforced	No direct database queries

Input Validation

All inputs are validated using Zod schemas:

• Stock symbols: /^[A-Z0-9.]{1,10}$/
• Position quantities: between -1 billion and 1 billion
• Transaction amounts: between -1 trillion and 1 trillion
• Batch limits: maximum 100,000 transactions per request
• Timestamps: ISO 8601 format, within reasonable date range
• Entity identifiers: Alphanumeric with limited special characters

Rate Limiting

const rateLimits = {
  'portfolio-risk': { requestsPerMinute: 60, maxConcurrent: 5 },
  'anomaly-detect': { requestsPerMinute: 100, maxConcurrent: 10 },
  'stress-test': { requestsPerMinute: 10, maxConcurrent: 2 },
  'market-regime': { requestsPerMinute: 120, maxConcurrent: 10 },
  'compliance-check': { requestsPerMinute: 30, maxConcurrent: 3 }
};

Performance

Metric	Target
Portfolio VaR calculation	<100ms for 10K positions
Transaction anomaly scoring	<5ms per transaction
Market regime classification	<50ms for 1-year history
Compliance check	<1s for full entity scan

Dependencies

• micro-hnsw-wasm: Fast similarity search for historical pattern matching
• ruvector-sparse-inference-wasm: Efficient processing of sparse financial features
• ruvector-gnn-wasm: Transaction network analysis for fraud detection
• ruvector-economy-wasm: Token economics and market microstructure modeling
• ruvector-learning-wasm: Reinforcement learning for adaptive risk thresholds

Related Plugins

Plugin	Description	Use Case
@claude-flow/plugin-legal-contracts	Contract analysis	Financial agreements, derivatives documentation
@claude-flow/plugin-healthcare-clinical	Clinical decision support	Healthcare portfolio analysis
@claude-flow/plugin-perf-optimizer	Performance optimization	High-frequency trading latency optimization

License

MIT License

Copyright (c) 2026 Claude Flow

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.