@bernierllc/chat-analytics

ML-powered chat analytics and insights for performance optimization and user behavior analysis.

Installation

npm install @bernierllc/chat-analytics

Features

• Metrics Collection - Message, user, performance, intent, and provider metrics
• ML-Powered Analysis - User behavior, performance optimization, sentiment analysis
• Insight Generation - Automated actionable insights with confidence scoring
• Alert Management - Smart alerting based on thresholds and trends
• Report Generation - Comprehensive reports in JSON, CSV, HTML, and PDF formats
• NeverHub Integration - Optional service discovery and event integration
• Real-time Analytics - Live metrics collection and processing
• Trend Analysis - Time-series analysis and forecasting
• Data Aggregation - Multi-level aggregation (minute, hour, day, week, month)

Quick Start

import { ChatAnalytics } from '@bernierllc/chat-analytics';

// Initialize analytics
const analytics = new ChatAnalytics({
  enabled: true,
  metrics: {
    collectionInterval: 60000, // 1 minute
    retentionPeriod: 90 // 90 days
  }
});

await analytics.initialize();

// Collect metrics
analytics.collectMessageMetric({
  timestamp: new Date(),
  messageId: 'msg-001',
  userId: 'user-123',
  volume: 1,
  responseTime: 150,
  success: true
});

// Generate insights
const insights = analytics.generateInsights();
console.log('Generated insights:', insights.data);

// Create report
const report = analytics.generateReport({ format: 'json' });
console.log('Report:', report.data);

// Cleanup
await analytics.shutdown();

Usage Examples

Collecting Different Metric Types

// Message metrics
analytics.collectMessageMetric({
  timestamp: new Date(),
  messageId: 'msg-001',
  userId: 'user-123',
  volume: 1,
  responseTime: 150,
  success: true,
  metadata: { provider: 'openai', model: 'gpt-4' }
});

// User metrics
analytics.collectUserMetric({
  timestamp: new Date(),
  userId: 'user-123',
  sessionId: 'session-001',
  activity: 'chat',
  duration: 5000,
  engagementScore: 0.85
});

// Performance metrics
analytics.collectPerformanceMetric({
  timestamp: new Date(),
  operation: 'chat-completion',
  duration: 250,
  success: true,
  resourceUsage: {
    cpu: 45.2,
    memory: 128
  }
});

// Intent metrics
analytics.collectIntentMetric({
  timestamp: new Date(),
  messageId: 'msg-001',
  intent: 'task-creation',
  confidence: 0.92,
  routedTo: 'task-handler',
  success: true
});

// Provider metrics
analytics.collectProviderMetric({
  timestamp: new Date(),
  provider: 'openai',
  operation: 'chat-completion',
  duration: 180,
  success: true
});

Analyzing User Behavior

const userAnalysis = analytics.analyzeUserBehavior('user-123', {
  start: new Date(Date.now() - 7 * 24 * 60 * 60 * 1000), // Last 7 days
  end: new Date()
});

if (userAnalysis.success) {
  const analysis = userAnalysis.data;
  console.log('Peak usage times:', analysis.patterns.peakUsageTimes);
  console.log('Preferred features:', analysis.patterns.preferredFeatures);
  console.log('Engagement level:', analysis.patterns.engagementLevel);
  console.log('Satisfaction score:', analysis.patterns.satisfactionScore);
  console.log('Insights:', analysis.insights);
  console.log('Recommendations:', analysis.recommendations);
}

Performance Analysis

const perfAnalysis = analytics.analyzePerformance({
  start: new Date(Date.now() - 24 * 60 * 60 * 1000), // Last 24 hours
  end: new Date()
});

if (perfAnalysis.success) {
  const { analysis } = perfAnalysis.data;
  console.log('Avg Response Time:', analysis.responseTime.avg, 'ms');
  console.log('Response Time Trend:', analysis.responseTime.trend);
  console.log('Error Rate:', (analysis.errorRate.current * 100).toFixed(2), '%');
  console.log('Bottlenecks:', analysis.bottlenecks);
  console.log('Recommendations:', perfAnalysis.data.recommendations);
}

Intent Analysis

const intentAnalysis = analytics.analyzeIntents();

if (intentAnalysis.success) {
  const { distribution, accuracy, topIntents } = intentAnalysis.data;
  console.log('Intent Distribution:', distribution);
  console.log('Overall Accuracy:', (accuracy * 100).toFixed(2), '%');
  console.log('Top Intents:', topIntents);
}

Trend Analysis and Forecasting

const trendAnalysis = analytics.analyzeTrends(7); // Predict next 7 periods

if (trendAnalysis.success) {
  const { trends, predictions, insights } = trendAnalysis.data;
  console.log('Trends:', trends);
  console.log('Predictions:', predictions);
  console.log('Insights:', insights);
}

Working with Insights and Alerts

// Generate insights
const insights = analytics.generateInsights();

if (insights.success) {
  for (const insight of insights.data) {
    console.log(`[${insight.priority}] ${insight.title}`);
    console.log(`  ${insight.description}`);
    console.log(`  Confidence: ${(insight.confidence * 100).toFixed(0)}%`);

    if (insight.recommendations) {
      console.log('  Recommendations:');
      insight.recommendations.forEach(rec => console.log(`    - ${rec}`));
    }
  }
}

// Check active alerts
const alerts = analytics.getActiveAlerts();
console.log(`Active alerts: ${alerts.length}`);

for (const alert of alerts) {
  console.log(`Alert: ${alert.insight.title}`);

  // Acknowledge alert
  analytics.acknowledgeAlert(alert.id);
}

Generating Reports

// JSON report
const jsonReport = analytics.generateReport({
  format: 'json',
  includeCharts: false,
  maxInsights: 10
});

// CSV report
const csvReport = analytics.generateReport({
  format: 'csv'
});

// Export report
if (jsonReport.success && jsonReport.data) {
  const exported = analytics.exportReport(jsonReport.data);
  console.log('Exported report:', exported.data);
}

Configuration

Basic Configuration

const analytics = new ChatAnalytics({
  enabled: true,

  metrics: {
    collectionInterval: 60000, // 1 minute
    retentionPeriod: 90, // 90 days
    aggregationLevels: ['minute', 'hour', 'day', 'week', 'month'],
    metrics: {
      messageVolume: { enabled: true, priority: 'high' },
      responseTime: { enabled: true, priority: 'high' },
      userEngagement: { enabled: true, priority: 'medium' },
      errorRate: { enabled: true, priority: 'high' },
      intentAccuracy: { enabled: true, priority: 'medium' }
    }
  },

  insights: {
    enabled: true,
    generationInterval: 300000, // 5 minutes
    alertThresholds: {
      errorRate: 0.05,      // 5%
      responseTime: 2000,   // 2 seconds
      userSatisfaction: 0.7 // 70%
    }
  }
});

ML Configuration

const analytics = new ChatAnalytics({
  ml: {
    enabled: true,
    models: {
      userBehavior: { enabled: true, retrainInterval: 86400000 }, // 24 hours
      performance: { enabled: true, retrainInterval: 3600000 },   // 1 hour
      sentiment: { enabled: true, retrainInterval: 43200000 },    // 12 hours
      trends: { enabled: true, retrainInterval: 86400000 }        // 24 hours
    },
    features: [
      'message_length',
      'response_time',
      'user_activity',
      'time_of_day',
      'day_of_week',
      'intent_confidence',
      'provider_performance'
    ],
    predictionHorizon: 7,
    confidenceThreshold: 0.8
  }
});

Reporting Configuration

const analytics = new ChatAnalytics({
  reporting: {
    enabled: true,
    formats: ['json', 'csv', 'pdf'],
    schedules: {
      daily: { enabled: true, time: '09:00' },
      weekly: { enabled: true, day: 'monday', time: '09:00' },
      monthly: { enabled: true, day: 1, time: '09:00' }
    },
    recipients: ['[email protected]', '[email protected]']
  }
});

NeverHub Integration

The package supports optional NeverHub integration for service discovery and event-based communication:

const analytics = new ChatAnalytics({
  neverhub: {
    enabled: true,
    serviceName: 'chat-analytics',
    capabilities: [
      { type: 'analytics', name: 'chat-metrics', version: '1.0.0' },
      { type: 'ml', name: 'behavior-analysis', version: '1.0.0' },
      { type: 'insights', name: 'performance-insights', version: '1.0.0' }
    ],
    dependencies: ['chat-provider-*', 'chat-ai-router']
  }
});

await analytics.initialize();

// Check NeverHub status
const status = analytics.getNeverHubStatus();
console.log('NeverHub enabled:', status.enabled);
console.log('NeverHub registered:', status.registered);

Note: The package works perfectly without NeverHub - it will gracefully degrade if NeverHub is not available.

API Reference

ChatAnalytics

Main class for analytics operations.

Methods

• initialize(): Promise<AnalyticsResult<void>> - Initialize analytics system
• shutdown(): Promise<AnalyticsResult<void>> - Shutdown analytics system
• collectEvent(event: AnalyticsEvent): AnalyticsResult<void> - Collect generic event
• collectMessageMetric(data): AnalyticsResult<void> - Collect message metric
• collectUserMetric(data): AnalyticsResult<void> - Collect user metric
• collectPerformanceMetric(data): AnalyticsResult<void> - Collect performance metric
• collectIntentMetric(data): AnalyticsResult<void> - Collect intent metric
• collectProviderMetric(data): AnalyticsResult<void> - Collect provider metric
• generateInsights(): AnalyticsResult<Insight[]> - Generate insights from metrics
• getInsights(): InsightCollection - Get all insights
• getActiveAlerts(): Alert[] - Get active alerts
• acknowledgeAlert(alertId: string): AnalyticsResult<void> - Acknowledge alert
• generateReport(options?): AnalyticsResult<Report> - Generate report
• exportReport(report: Report): AnalyticsResult<string> - Export report
• analyzeUserBehavior(userId, timeRange): AnalyticsResult - Analyze user behavior
• analyzePerformance(timeRange): AnalyticsResult - Analyze performance
• analyzeIntents(): AnalyticsResult - Analyze intents
• analyzeTrends(periods?): AnalyticsResult - Analyze trends
• getMetrics(type?): Metric[] - Get metrics
• getConfig(): AnalyticsConfig - Get configuration
• getNeverHubStatus() - Get NeverHub integration status

Integration Status

• Logger: Optional - Can be integrated for analytics logging
• Docs-Suite: Ready - Full API documentation via TypeDoc
• NeverHub: Optional - Graceful degradation when unavailable

Testing

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Run linting
npm run lint

# Build package
npm run build

Dependencies

• @bernierllc/neverhub-adapter - NeverHub integration (optional)
• @bernierllc/retry-policy - Retry logic
• @bernierllc/rate-limiter - Rate limiting
• @bernierllc/logger - Logging (optional)
• @bernierllc/config-manager - Configuration management
• zod - Schema validation

License

Copyright (c) 2025 Bernier LLC. All rights reserved.

This file is licensed to the client under a limited-use license. The client may use and modify this code only within the scope of the project it was delivered for. Redistribution or use in other products or commercial offerings is not permitted without written consent from Bernier LLC.