import { z } from 'zod';
import { createLogger } from '../utils/logger.js';
/**
* Insight Engine Service
*
* Advanced pattern recognition, anomaly detection, and insight generation
* for AI agent optimization.
*/
// Types for insights
export interface PatternInsight {
type: 'trend' | 'correlation' | 'anomaly' | 'benchmark';
confidence: number;
description: string;
impact: 'low' | 'medium' | 'high';
dataPoints?: any[];
}
export interface RiskInsight {
factor: string;
probability: number;
impact: 'low' | 'medium' | 'high';
mitigation: string;
earlyWarnings: string[];
}
export interface OpportunityInsight {
type: 'quick_win' | 'strategic' | 'efficiency' | 'innovation';
description: string;
potentialValue: number;
timeToRealize: string;
requirements: string[];
}
export interface CrossProjectPattern {
pattern: string;
frequency: number;
projects: string[];
recommendation: string;
}
export class InsightEngine {
private logger = createLogger({ component: 'InsightEngine' });
// Thresholds for insight generation
private readonly THRESHOLDS = {
HIGH_ROI: 150,
QUICK_PAYBACK: 12,
HIGH_CONFIDENCE: 0.85,
COMPLEXITY_CONCERN: 0.7,
SYNERGY_THRESHOLD: 0.6
};
/**
* Generate comprehensive insights for ROI predictions
*/
async generateROIInsights(
summary: any,
useCases: any[],
financialMetrics: any,
benchmarks?: any
): Promise<{
patterns: PatternInsight[];
risks: RiskInsight[];
opportunities: OpportunityInsight[];
}> {
this.logger.debug('Generating ROI insights');
const patterns = this.detectROIPatterns(summary, useCases, financialMetrics);
const risks = this.assessROIRisks(summary, useCases, financialMetrics);
const opportunities = this.identifyROIOpportunities(summary, useCases, benchmarks);
return { patterns, risks, opportunities };
}
/**
* Generate insights for project comparisons
*/
async generateComparativeInsights(
projects: any[],
rankings: any,
mlInsights?: any
): Promise<{
patterns: PatternInsight[];
crossProjectPatterns: CrossProjectPattern[];
strategicInsights: string[];
}> {
this.logger.debug('Generating comparative insights', { projectCount: projects.length });
const patterns = this.detectComparativePatterns(projects, rankings);
const crossProjectPatterns = this.findCrossProjectPatterns(projects, mlInsights);
const strategicInsights = this.generateStrategicInsights(projects, patterns);
return { patterns, crossProjectPatterns, strategicInsights };
}
/**
* Detect patterns in ROI data
*/
private detectROIPatterns(
summary: any,
useCases: any[],
financialMetrics: any
): PatternInsight[] {
const patterns: PatternInsight[] = [];
// ROI velocity pattern
if (summary.payback_period_months <= this.THRESHOLDS.QUICK_PAYBACK) {
patterns.push({
type: 'trend',
confidence: 0.9,
description: 'Rapid value realization indicates mature use cases with proven ROI',
impact: 'high'
});
}
// Use case concentration pattern
const categoryDistribution = this.analyzeUseCaseDistribution(useCases);
if (categoryDistribution.concentration > 0.6) {
patterns.push({
type: 'correlation',
confidence: 0.85,
description: `Strong focus on ${categoryDistribution.dominantCategory} use cases (${(categoryDistribution.concentration * 100).toFixed(0)}% of value)`,
impact: 'medium',
dataPoints: categoryDistribution.breakdown
});
}
// Value curve pattern
const valueCurve = this.analyzeValueCurve(financialMetrics);
if (valueCurve.accelerating) {
patterns.push({
type: 'trend',
confidence: 0.8,
description: 'Accelerating value curve suggests network effects or learning curve benefits',
impact: 'high'
});
}
// Benchmark comparison pattern
if (summary.expected_roi > this.THRESHOLDS.HIGH_ROI) {
patterns.push({
type: 'benchmark',
confidence: 0.75,
description: `ROI exceeds industry benchmarks by ${((summary.expected_roi / 75) - 1) * 100}%`,
impact: 'high'
});
}
return patterns;
}
/**
* Assess risks in ROI projections
*/
private assessROIRisks(
summary: any,
useCases: any[],
financialMetrics: any
): RiskInsight[] {
const risks: RiskInsight[] = [];
// Implementation complexity risk
const complexityScore = this.calculateComplexityScore(useCases);
if (complexityScore > this.THRESHOLDS.COMPLEXITY_CONCERN) {
risks.push({
factor: 'Implementation Complexity',
probability: complexityScore,
impact: 'high',
mitigation: 'Phase implementation starting with simplest, highest-value use cases',
earlyWarnings: [
'Timeline slippage in pilot phase',
'Resource requirements exceed initial estimates',
'Integration challenges with existing systems'
]
});
}
// Adoption risk
if (useCases.some(uc => uc.category === 'customer_service' || uc.category === 'hr_recruiting')) {
risks.push({
factor: 'User Adoption',
probability: 0.4,
impact: 'medium',
mitigation: 'Implement comprehensive change management and training programs',
earlyWarnings: [
'Low engagement in training sessions',
'Resistance from key stakeholders',
'Below-target usage metrics in first 30 days'
]
});
}
// Scaling risk
if (summary.total_investment > 500000) {
risks.push({
factor: 'Scaling Challenges',
probability: 0.35,
impact: 'medium',
mitigation: 'Build robust infrastructure and establish center of excellence early',
earlyWarnings: [
'Performance degradation with increased load',
'Governance gaps in expanded deployment',
'Inconsistent results across business units'
]
});
}
// Technology maturity risk
const maturityRisk = this.assessTechnologyMaturity(useCases);
if (maturityRisk.probability > 0.3) {
risks.push(maturityRisk);
}
return risks;
}
/**
* Identify opportunities in ROI data
*/
private identifyROIOpportunities(
summary: any,
useCases: any[],
benchmarks?: any
): OpportunityInsight[] {
const opportunities: OpportunityInsight[] = [];
// Quick win opportunities
const quickWins = useCases
.filter(uc => this.isQuickWin(uc))
.map(uc => ({
type: 'quick_win' as const,
description: `${uc.name}: ${(uc.monthly_benefit * 12 / 1000).toFixed(0)}K annual benefit`,
potentialValue: uc.monthly_benefit * 12,
timeToRealize: '30-60 days',
requirements: ['Dedicated team', 'Executive sponsorship', 'Clear success metrics']
}));
opportunities.push(...quickWins.slice(0, 3));
// Strategic opportunities
if (summary.expected_roi > this.THRESHOLDS.HIGH_ROI) {
opportunities.push({
type: 'strategic',
description: 'Establish AI Center of Excellence to scale success across organization',
potentialValue: summary.total_investment * 0.3, // 30% additional value
timeToRealize: '6-12 months',
requirements: [
'C-level sponsorship',
'Cross-functional team',
'Governance framework',
'Knowledge management system'
]
});
}
// Efficiency opportunities
const efficiencyOpp = this.findEfficiencyOpportunities(useCases, summary);
if (efficiencyOpp) {
opportunities.push(efficiencyOpp);
}
// Innovation opportunities based on benchmarks
if (benchmarks?.emerging_technologies) {
opportunities.push({
type: 'innovation',
description: 'Explore next-gen AI capabilities: ' + benchmarks.emerging_technologies.join(', '),
potentialValue: summary.total_investment * 0.5,
timeToRealize: '12-18 months',
requirements: ['R&D budget', 'Technical expertise', 'Innovation framework']
});
}
return opportunities;
}
/**
* Detect patterns across multiple projects
*/
private detectComparativePatterns(
projects: any[],
rankings: any
): PatternInsight[] {
const patterns: PatternInsight[] = [];
// ROI distribution pattern
const roiValues = projects.map(p => p.financial_summary.expected_roi);
const roiStats = this.calculateStatistics(roiValues);
if (roiStats.cv < 0.2) {
patterns.push({
type: 'correlation',
confidence: 0.85,
description: 'Consistent ROI across projects suggests mature AI capability and predictable value delivery',
impact: 'medium'
});
} else if (roiStats.cv > 0.5) {
patterns.push({
type: 'anomaly',
confidence: 0.8,
description: 'High ROI variance indicates diverse risk-return profiles requiring portfolio approach',
impact: 'high'
});
}
// Investment efficiency pattern
const efficiencyScores = projects.map(p =>
p.financial_summary.expected_roi / p.financial_summary.total_investment * 100000
);
const topEfficiency = Math.max(...efficiencyScores);
const bottomEfficiency = Math.min(...efficiencyScores);
if (topEfficiency / bottomEfficiency > 3) {
patterns.push({
type: 'benchmark',
confidence: 0.75,
description: 'Significant efficiency gaps suggest opportunity for best practice sharing',
impact: 'medium',
dataPoints: efficiencyScores
});
}
// Time-to-value pattern
const paybackPeriods = projects.map(p => p.financial_summary.payback_period_months);
if (Math.min(...paybackPeriods) < 6 && Math.max(...paybackPeriods) > 24) {
patterns.push({
type: 'trend',
confidence: 0.7,
description: 'Wide range of payback periods enables staged investment approach',
impact: 'medium'
});
}
return patterns;
}
/**
* Find patterns across projects
*/
private findCrossProjectPatterns(
projects: any[],
mlInsights?: any
): CrossProjectPattern[] {
const patterns: CrossProjectPattern[] = [];
// Technology synergies
if (mlInsights?.synergies) {
const techSynergies = mlInsights.synergies
.filter((s: any) => s.type === 'technology')
.map((s: any) => ({
pattern: `Shared ${s.description}`,
frequency: s.projects.length,
projects: s.projects,
recommendation: `Consolidate ${s.description} investments for ${s.estimated_savings}% cost reduction`
}));
patterns.push(...techSynergies);
}
// Use case patterns
const useCaseMap = new Map<string, string[]>();
projects.forEach(p => {
p.use_cases?.forEach((uc: any) => {
if (!useCaseMap.has(uc.category)) {
useCaseMap.set(uc.category, []);
}
useCaseMap.get(uc.category)!.push(p.name);
});
});
useCaseMap.forEach((projectNames, category) => {
if (projectNames.length > 1) {
patterns.push({
pattern: `Common ${category} use cases`,
frequency: projectNames.length,
projects: projectNames,
recommendation: `Create shared ${category} platform to serve multiple projects`
});
}
});
// Scaling patterns
const scalingCandidates = projects.filter(p =>
p.financial_summary.expected_roi > 100 &&
p.risk_score < 0.5
);
if (scalingCandidates.length > 1) {
patterns.push({
pattern: 'High-ROI, low-risk profile',
frequency: scalingCandidates.length,
projects: scalingCandidates.map(p => p.name),
recommendation: 'Prioritize these projects for accelerated scaling and resource allocation'
});
}
return patterns;
}
/**
* Generate strategic insights from patterns
*/
private generateStrategicInsights(
projects: any[],
patterns: PatternInsight[]
): string[] {
const insights: string[] = [];
// Portfolio balance insight
const riskReturnBalance = this.assessPortfolioBalance(projects);
insights.push(riskReturnBalance);
// Resource optimization insight
const totalInvestment = projects.reduce((sum, p) => sum + p.financial_summary.total_investment, 0);
const avgROI = projects.reduce((sum, p) => sum + p.financial_summary.expected_roi, 0) / projects.length;
if (totalInvestment > 1000000) {
insights.push(
`Portfolio approach with $${(totalInvestment / 1000000).toFixed(1)}M total investment ` +
`targeting ${avgROI.toFixed(0)}% average ROI requires phased execution and dedicated PMO`
);
}
// Pattern-based insights
const highImpactPatterns = patterns.filter(p => p.impact === 'high');
if (highImpactPatterns.length > 0) {
insights.push(
`Key success factor: ${highImpactPatterns[0].description.toLowerCase()}`
);
}
// Timing insight
const quickPaybacks = projects.filter(p => p.financial_summary.payback_period_months < 12).length;
if (quickPaybacks > projects.length / 2) {
insights.push(
'Majority of projects offer sub-year payback, enabling rapid reinvestment cycles'
);
}
return insights;
}
// Helper methods
private analyzeUseCaseDistribution(useCases: any[]): {
concentration: number;
dominantCategory: string;
breakdown: any[];
} {
const categoryTotals = useCases.reduce((acc, uc) => {
const category = uc.category as string;
acc[category] = (acc[category] || 0) + uc.monthly_benefit;
return acc;
}, {} as Record<string, number>);
const totalBenefit = Object.values(categoryTotals).reduce((sum, val) => (sum as number) + (val as number), 0);
const categories = Object.entries(categoryTotals)
.map(([category, benefit]) => ({
category,
benefit: benefit as number,
percentage: (benefit as number) / (totalBenefit as number)
}))
.sort((a, b) => b.percentage - a.percentage);
return {
concentration: categories[0]?.percentage || 0,
dominantCategory: categories[0]?.category || 'unknown',
breakdown: categories
};
}
private analyzeValueCurve(financialMetrics: any): {
accelerating: boolean;
steady: boolean;
declining: boolean;
} {
// Simplified analysis - in reality would analyze month-by-month projections
const hasNetworkEffects = financialMetrics.optimistic.total_monthly_benefit >
financialMetrics.expected.total_monthly_benefit * 1.3;
return {
accelerating: hasNetworkEffects,
steady: !hasNetworkEffects,
declining: false
};
}
private calculateComplexityScore(useCases: any[]): number {
// Factors: number of use cases, integration requirements, change impact
const factors = {
count: Math.min(useCases.length / 10, 1), // Normalize to 0-1
categories: new Set(useCases.map(uc => uc.category)).size / 5, // Assume 5 categories max
avgComplexity: 0.5 // Default medium complexity
};
return (factors.count + factors.categories + factors.avgComplexity) / 3;
}
private assessTechnologyMaturity(useCases: any[]): RiskInsight {
const hasEmergingTech = useCases.some(uc =>
uc.category === 'analytics' ||
uc.name.toLowerCase().includes('predictive') ||
uc.name.toLowerCase().includes('ml')
);
return {
factor: 'Technology Maturity',
probability: hasEmergingTech ? 0.4 : 0.2,
impact: 'medium',
mitigation: 'Partner with experienced vendors and invest in team training',
earlyWarnings: [
'Vendor technology roadmap changes',
'Skills gap in implementation team',
'Integration complexity higher than estimated'
]
};
}
private isQuickWin(useCase: any): boolean {
// Quick win criteria: high benefit, low complexity, fast implementation
return useCase.monthly_benefit > 10000 &&
(useCase.complexity || 'medium') !== 'high';
}
private findEfficiencyOpportunities(
useCases: any[],
summary: any
): OpportunityInsight | null {
const automationCases = useCases.filter(uc =>
uc.category === 'automation' ||
uc.name.toLowerCase().includes('automat')
);
if (automationCases.length > 0) {
const totalAutomationBenefit = automationCases.reduce((sum, uc) => sum + uc.monthly_benefit, 0);
return {
type: 'efficiency',
description: 'Expand automation footprint across similar processes',
potentialValue: totalAutomationBenefit * 12 * 0.5, // 50% additional value
timeToRealize: '3-6 months',
requirements: [
'Process mapping',
'Automation CoE',
'Change management'
]
};
}
return null;
}
private calculateStatistics(values: number[]): {
mean: number;
std: number;
cv: number; // Coefficient of variation
} {
const mean = values.reduce((sum, val) => sum + val, 0) / values.length;
const variance = values.reduce((sum, val) => sum + Math.pow(val - mean, 2), 0) / values.length;
const std = Math.sqrt(variance);
return {
mean,
std,
cv: std / mean
};
}
private assessPortfolioBalance(projects: any[]): string {
const highROI = projects.filter(p => p.financial_summary.expected_roi > 100).length;
const quickPayback = projects.filter(p => p.financial_summary.payback_period_months < 12).length;
const highRisk = projects.filter(p => p.risk_score > 0.6).length;
if (highROI > projects.length * 0.7 && highRisk < projects.length * 0.3) {
return 'Portfolio shows strong return potential with manageable risk profile';
} else if (quickPayback > projects.length * 0.5) {
return 'Portfolio weighted toward quick wins enables rapid value capture and learning';
} else if (highRisk > projects.length * 0.5) {
return 'Portfolio risk concentration requires careful sequencing and risk mitigation';
} else {
return 'Balanced portfolio provides optionality across risk-return spectrum';
}
}
}
// Export singleton instance
export const insightEngine = new InsightEngine();
