lean-claudient-core 0.1.0

package/src/metrics/grafanaExport.ts

@@ -0,0 +1,347 @@
+/**
+ * Grafana Metrics Export
+ * Generates Grafana-compatible JSON for monitoring dashboards
+ */
+
+import { BusinessMetrics } from './businessMetrics.js';
+import { ROIOutput } from './roiCalculator.js';
+
+export interface GrafanaMetric {
+  name: string;
+  value: number;
+  timestamp: number;
+  labels: Record<string, string>;
+}
+
+export interface GrafanaDashboard {
+  dashboard: {
+    title: string;
+    uid: string;
+    version: number;
+    timezone: string;
+    panels: GrafanaPanel[];
+    refresh: string;
+    time: {
+      from: string;
+      to: string;
+    };
+  };
+  overwrite: boolean;
+}
+
+export interface GrafanaPanel {
+  id: number;
+  title: string;
+  type: string;
+  targets: GrafanaTarget[];
+  fieldConfig: {
+    defaults: Record<string, any>;
+    overrides: any[];
+  };
+  options: Record<string, any>;
+  gridPos: {
+    h: number;
+    w: number;
+    x: number;
+    y: number;
+  };
+}
+
+export interface GrafanaTarget {
+  refId: string;
+  expr: string;
+}
+
+export function businessMetricsToGrafana(metrics: BusinessMetrics, roi?: ROIOutput): GrafanaMetric[] {
+  const metricsArray: GrafanaMetric[] = [
+    {
+      name: 'lean_claudient_leads_identified',
+      value: metrics.leadsIdentified,
+      timestamp: metrics.timestamp,
+      labels: { type: 'business_metric', source: 'lean_claudient' },
+    },
+    {
+      name: 'lean_claudient_competitor_vulnerabilities',
+      value: metrics.competitorVulnerabilitiesFound,
+      timestamp: metrics.timestamp,
+      labels: { type: 'security_metric', source: 'lean_claudient' },
+    },
+    {
+      name: 'lean_claudient_market_trends',
+      value: metrics.marketTrendsDetected,
+      timestamp: metrics.timestamp,
+      labels: { type: 'market_metric', source: 'lean_claudient' },
+    },
+  ];
+
+  if (roi) {
+    metricsArray.push(
+      {
+        name: 'lean_claudient_revenue_potential',
+        value: roi.revenuePotential,
+        timestamp: metrics.timestamp,
+        labels: { type: 'financial_metric', scenario: 'baseline' },
+      },
+      {
+        name: 'lean_claudient_roi_percentage',
+        value: roi.roiPercentage,
+        timestamp: metrics.timestamp,
+        labels: { type: 'financial_metric', metric: 'roi' },
+      },
+      {
+        name: 'lean_claudient_profit_margin',
+        value: roi.profitMargin,
+        timestamp: metrics.timestamp,
+        labels: { type: 'financial_metric', metric: 'margin' },
+      }
+    );
+  }
+
+  return metricsArray;
+}
+
+export function generateGrafanaDashboard(metrics: BusinessMetrics, roi?: ROIOutput): GrafanaDashboard {
+  const panels: GrafanaPanel[] = [
+    // Leads Identified Panel
+    {
+      id: 1,
+      title: 'Leads Identified',
+      type: 'gauge',
+      targets: [
+        {
+          refId: 'A',
+          expr: 'lean_claudient_leads_identified',
+        },
+      ],
+      fieldConfig: {
+        defaults: {
+          color: { mode: 'palette-classic' },
+          custom: { hideFrom: { tooltip: false, viz: false, legend: false } },
+          mappings: [],
+          unit: 'short',
+        },
+        overrides: [],
+      },
+      options: {
+        orientation: 'auto',
+        showThresholdLabels: false,
+        showThresholdMarkers: true,
+      },
+      gridPos: { h: 8, w: 12, x: 0, y: 0 },
+    },
+
+    // Competitor Vulnerabilities Panel
+    {
+      id: 2,
+      title: 'Competitor Vulnerabilities',
+      type: 'stat',
+      targets: [
+        {
+          refId: 'A',
+          expr: 'lean_claudient_competitor_vulnerabilities',
+        },
+      ],
+      fieldConfig: {
+        defaults: {
+          color: { mode: 'palette-classic' },
+          custom: { hideFrom: { tooltip: false, viz: false, legend: false } },
+          mappings: [],
+          unit: 'short',
+        },
+        overrides: [],
+      },
+      options: {
+        colorMode: 'background',
+        graphMode: 'area',
+        justifyMode: 'auto',
+        orientation: 'auto',
+        textMode: 'auto',
+      },
+      gridPos: { h: 8, w: 12, x: 12, y: 0 },
+    },
+
+    // Market Trends Panel
+    {
+      id: 3,
+      title: 'Market Trends Detected',
+      type: 'timeseries',
+      targets: [
+        {
+          refId: 'A',
+          expr: 'lean_claudient_market_trends',
+        },
+      ],
+      fieldConfig: {
+        defaults: {
+          color: { mode: 'palette-classic' },
+          custom: {
+            axisLabel: '',
+            axisPlacement: 'auto',
+            barAlignment: 0,
+            drawStyle: 'line',
+            fillOpacity: 10,
+            gradientMode: 'none',
+            hideFrom: { tooltip: false, viz: false, legend: false },
+            lineInterpolation: 'linear',
+            lineWidth: 1,
+            pointSize: 5,
+            scaleDistribution: { type: 'linear' },
+            showPoints: 'auto',
+            spanNulls: true,
+            stacking: { group: 'A', mode: 'none' },
+            thresholdsStyle: { mode: 'off' },
+          },
+          mappings: [],
+          unit: 'short',
+        },
+        overrides: [],
+      },
+      options: {
+        legend: { calcs: [], displayMode: 'list', placement: 'bottom' },
+        tooltip: { mode: 'single' },
+      },
+      gridPos: { h: 8, w: 24, x: 0, y: 8 },
+    },
+  ];
+
+  if (roi) {
+    panels.push(
+      {
+        id: 4,
+        title: 'Revenue Potential',
+        type: 'stat',
+        targets: [
+          {
+            refId: 'A',
+            expr: 'lean_claudient_revenue_potential',
+          },
+        ],
+        fieldConfig: {
+          defaults: {
+            color: { mode: 'palette-classic' },
+            custom: { hideFrom: { tooltip: false, viz: false, legend: false } },
+            mappings: [],
+            unit: 'currencyUSD',
+          },
+          overrides: [],
+        },
+        options: {
+          colorMode: 'background',
+          graphMode: 'area',
+          justifyMode: 'auto',
+          orientation: 'auto',
+          textMode: 'auto',
+        },
+        gridPos: { h: 8, w: 12, x: 0, y: 16 },
+      },
+      {
+        id: 5,
+        title: 'ROI Percentage',
+        type: 'gauge',
+        targets: [
+          {
+            refId: 'A',
+            expr: 'lean_claudient_roi_percentage',
+          },
+        ],
+        fieldConfig: {
+          defaults: {
+            color: { mode: 'palette-classic' },
+            custom: { hideFrom: { tooltip: false, viz: false, legend: false } },
+            mappings: [],
+            unit: 'percent',
+          },
+          overrides: [],
+        },
+        options: {
+          orientation: 'auto',
+          showThresholdLabels: false,
+          showThresholdMarkers: true,
+        },
+        gridPos: { h: 8, w: 12, x: 12, y: 16 },
+      }
+    );
+  }
+
+  return {
+    dashboard: {
+      title: 'Lean Claudient - Business Metrics',
+      uid: 'lean-claudient-business',
+      version: 1,
+      timezone: 'browser',
+      panels,
+      refresh: '30s',
+      time: {
+        from: 'now-7d',
+        to: 'now',
+      },
+    },
+    overwrite: true,
+  };
+}
+
+export function formatPrometheusMetrics(metrics: GrafanaMetric[]): string {
+  const lines = metrics.map(m => {
+    const labels = Object.entries(m.labels)
+      .map(([k, v]) => `${k}="${v}"`)
+      .join(',');
+
+    return `${m.name}{${labels}} ${m.value} ${m.timestamp}`;
+  });
+
+  return lines.join('\n');
+}
+
+export function generatePrometheusAlerts(roi?: ROIOutput): string {
+  const rules = [`
+# Lean Claudient Business Metrics Alerts
+
+groups:
+  - name: lean_claudient
+    interval: 1m
+    rules:
+      - alert: LowLeadConversionRate
+        expr: (lean_claudient_leads_identified - lean_claudient_leads_converted) > 100
+        for: 7d
+        annotations:
+          summary: "Low lead conversion detected"
+          description: "More than 100 unconverted leads pending"
+
+      - alert: HighCompetitorThreat
+        expr: lean_claudient_competitor_vulnerabilities > 10
+        for: 1d
+        annotations:
+          summary: "High number of competitor vulnerabilities"
+          description: "Market threat score elevated"
+
+      - alert: SlowMarketAdoption
+        expr: rate(lean_claudient_market_trends[7d]) < 0.1
+        for: 3d
+        annotations:
+          summary: "Market trend velocity declining"
+          description: "Few new market signals detected in past week"
+  `];
+
+  if (roi) {
+    rules.push(`
+      - alert: LowROI
+        expr: lean_claudient_roi_percentage < 50
+        for: 30d
+        annotations:
+          summary: "ROI below threshold"
+          description: "Business metrics showing poor return on investment"
+
+      - alert: NegativeProfitMargin
+        expr: lean_claudient_profit_margin < 0
+        for: 1d
+        annotations:
+          summary: "Negative profit margin detected"
+          description: "Costs exceeding revenue projections"
+    `);
+  }
+
+  rules.push(`
+    `);
+
+  return rules.join('');
+}

package/src/metrics/index.ts

@@ -0,0 +1,17 @@
+/**
+ * Metrics Module Index
+ * Centralizes all business metrics, financial calculations, and dashboard generation
+ */
+
+export * from './businessMetrics.js';
+export { BusinessMetrics, createBusinessMetrics } from './businessMetricsAgg.js';
+export * from './metricsTypes.js';
+export { generateDashboardHTML, saveDashboardHTML } from './dashboardGenerator.js';
+export * from './leadsMetrics.js';
+export * from './competitorMetrics.js';
+export * from './trendMetrics.js';
+export * from './roiCalculator.js';
+export * from './dashboardHTML.js';
+export * from './grafanaExport.js';
+export * from './revenueProjection.js';
+export * from './revenueTypes.js';

package/src/metrics/leadsMetrics.ts

@@ -0,0 +1,145 @@
+/**
+ * Lead Tracking & Pipeline Analytics
+ * Tracks lead volume, quality, conversion, and pipeline value
+ */
+
+export interface LeadQuality {
+  score: number; // 0-100
+  confidence: number; // 0-100
+  category: 'hot' | 'warm' | 'cold';
+}
+
+export interface Lead {
+  id: string;
+  source: string;
+  createdAt: number;
+  quality: LeadQuality;
+  status: 'new' | 'contacted' | 'qualified' | 'converted' | 'lost';
+  estimatedDealSize?: number;
+}
+
+export interface LeadsMetrics {
+  totalLeads: number;
+  leadsBySource: Record<string, number>;
+  qualityDistribution: {
+    hot: number;
+    warm: number;
+    cold: number;
+  };
+  averageQualityScore: number;
+  conversionRate: number; // 0-1
+  conversionsBySource: Record<string, number>;
+  pipelineValue: number;
+  leads: Lead[];
+}
+
+export function createLead(
+  id: string,
+  source: string,
+  quality: LeadQuality,
+  estimatedDealSize?: number
+): Lead {
+  return {
+    id,
+    source,
+    createdAt: Date.now(),
+    quality,
+    status: 'new',
+    estimatedDealSize,
+  };
+}
+
+export function calculateLeadsMetrics(
+  leads: Lead[],
+  options?: {
+    avgDealSize?: number;
+    targetConversionRate?: number;
+  }
+): LeadsMetrics {
+  const avgDealSize = options?.avgDealSize || 50000;
+  const targetConversionRate = options?.targetConversionRate || 0.02;
+
+  // Group by source
+  const leadsBySource: Record<string, number> = {};
+  leads.forEach(lead => {
+    leadsBySource[lead.source] = (leadsBySource[lead.source] || 0) + 1;
+  });
+
+  // Quality distribution
+  const qualityDistribution = {
+    hot: leads.filter(l => l.quality.category === 'hot').length,
+    warm: leads.filter(l => l.quality.category === 'warm').length,
+    cold: leads.filter(l => l.quality.category === 'cold').length,
+  };
+
+  // Average quality score
+  const avgQuality = leads.length > 0 ? leads.reduce((sum, l) => sum + l.quality.score, 0) / leads.length : 0;
+
+  // Conversion rate (leads in 'converted' status)
+  const converted = leads.filter(l => l.status === 'converted').length;
+  const conversionRate = leads.length > 0 ? converted / leads.length : targetConversionRate;
+
+  // Conversions by source
+  const conversionsBySource: Record<string, number> = {};
+  Object.keys(leadsBySource).forEach(source => {
+    const sourceLeads = leads.filter(l => l.source === source);
+    const sourceConverted = sourceLeads.filter(l => l.status === 'converted').length;
+    conversionsBySource[source] = sourceLeads.length > 0 ? sourceConverted / sourceLeads.length : 0;
+  });
+
+  // Pipeline value = total leads × conversion rate × avg deal size
+  const pipelineValue = leads.length * conversionRate * avgDealSize;
+
+  return {
+    totalLeads: leads.length,
+    leadsBySource,
+    qualityDistribution,
+    averageQualityScore: Math.round(avgQuality * 10) / 10,
+    conversionRate: Math.round(conversionRate * 10000) / 10000,
+    conversionsBySource,
+    pipelineValue: Math.round(pipelineValue),
+    leads,
+  };
+}
+
+export function estimatePipelineValue(
+  totalLeads: number,
+  conversionRate: number,
+  avgDealSize: number = 50000
+): number {
+  return Math.round(totalLeads * conversionRate * avgDealSize);
+}
+
+export function analyzeLeadQuality(leads: Lead[]): {
+  hotPercentage: number;
+  warmPercentage: number;
+  coldPercentage: number;
+  topSources: Array<{ source: string; count: number; avgQuality: number }>;
+} {
+  const total = leads.length || 1;
+
+  const sourceStats: Record<string, { count: number; quality: number }> = {};
+  leads.forEach(lead => {
+    if (!sourceStats[lead.source]) {
+      sourceStats[lead.source] = { count: 0, quality: 0 };
+    }
+    sourceStats[lead.source].count++;
+    sourceStats[lead.source].quality += lead.quality.score;
+  });
+
+  const topSources = Object.entries(sourceStats)
+    .map(([source, stats]) => ({
+      source,
+      count: stats.count,
+      avgQuality: Math.round((stats.quality / stats.count) * 10) / 10,
+    }))
+    .sort((a, b) => b.count - a.count)
+    .slice(0, 5);
+
+  return {
+    hotPercentage: Math.round((leads.filter(l => l.quality.category === 'hot').length / total) * 100),
+    warmPercentage: Math.round((leads.filter(l => l.quality.category === 'warm').length / total) * 100),
+    coldPercentage: Math.round((leads.filter(l => l.quality.category === 'cold').length / total) * 100),
+    topSources,
+  };
+}

package/src/metrics/metricsTypes.ts

@@ -0,0 +1,129 @@
+/**
+ * Business Metrics Type Definitions
+ * Dashboard, funnel, and aggregation types
+ * Phase 8B Task 4
+ */
+
+import { RevenueProjection, PortfolioForecast } from './revenueTypes.js';
+import { EnrichedLead } from '../intelligence/leadEnrichmentTypes.js';
+
+/**
+ * Lead funnel stage
+ */
+export type FunnelStage = 'cold' | 'warm' | 'hot' | 'sales-ready';
+
+/**
+ * Funnel metrics
+ */
+export interface FunnelMetrics {
+  stage: FunnelStage;
+  count: number;
+  percentage: number;
+  conversionRate: number; // To next stage
+  avgQuality: number;
+  avgRevenue: number;
+}
+
+/**
+ * Revenue aggregation
+ */
+export interface RevenueBySource {
+  source: string;
+  totalRevenue: number;
+  leadCount: number;
+  avgRevenue: number;
+  confidence: number;
+}
+
+export interface RevenueByStage {
+  stage: FunnelStage;
+  totalRevenue: number;
+  leadCount: number;
+  avgRevenue: number;
+  confidence: number;
+}
+
+/**
+ * Competitor threat distribution
+ */
+export interface ThreatDistribution {
+  CRITICAL: number;
+  HIGH: number;
+  MEDIUM: number;
+  LOW: number;
+  NONE: number;
+}
+
+/**
+ * Signal effectiveness
+ */
+export interface SignalEffectiveness {
+  signal: string;
+  matchCount: number;
+  conversionRate: number;
+  avgQuality: number;
+  avgRevenue: number;
+  roi: number;
+}
+
+/**
+ * Dashboard metrics aggregate
+ */
+export interface DashboardMetrics {
+  generatedAt: string;
+  totalLeads: number;
+  totalProjectedRevenue: number;
+
+  funnel: {
+    stages: FunnelMetrics[];
+    coldToSalesReady: number; // Total conversion rate
+  };
+
+  revenue: {
+    bySource: RevenueBySource[];
+    byStage: RevenueByStage[];
+    topLeads: Array<{
+      leadId: string;
+      name: string;
+      company: string;
+      projectedRevenue: number;
+      quality: number;
+      stage: FunnelStage;
+    }>;
+  };
+
+  threats: {
+    distribution: ThreatDistribution;
+    percentByCritical: number;
+    percentByHigh: number;
+  };
+
+  signals: {
+    effectiveness: SignalEffectiveness[];
+    topPerforming: SignalEffectiveness[];
+    totalSignalMatches: number;
+  };
+
+  timeline: {
+    avgDaysColdToSalesReady?: number;
+    estimatedTimeToConversion?: number;
+  };
+
+  portfolio: PortfolioForecast;
+}
+
+/**
+ * Export CSV row
+ */
+export interface MetricsCSVRow {
+  leadId: string;
+  name: string;
+  company: string;
+  quality: number;
+  stage: FunnelStage;
+  projectedRevenue: number;
+  threatLevel: string;
+  signalCount: number;
+  source: string;
+  enrichedAt: string;
+}