@bernierllc/chat-analytics

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

Installation

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

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

$3

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

$3

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

$3

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

$3

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

$3

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

$3

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

$3

`typescript
// 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

$3

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

$3

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

$3

`typescript
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: ['admin@company.com', 'analytics@company.com']
}
});
`

NeverHub Integration

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

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

$3

Main class for analytics operations.

#### Methods

- initialize(): Promise> - Initialize analytics system
- shutdown(): Promise> - Shutdown analytics system
- collectEvent(event: AnalyticsEvent): AnalyticsResult - Collect generic event
- collectMessageMetric(data): AnalyticsResult - Collect message metric
- collectUserMetric(data): AnalyticsResult - Collect user metric
- collectPerformanceMetric(data): AnalyticsResult - Collect performance metric
- collectIntentMetric(data): AnalyticsResult - Collect intent metric
- collectProviderMetric(data): AnalyticsResult - Collect provider metric
- generateInsights(): AnalyticsResult - Generate insights from metrics
- getInsights(): InsightCollection - Get all insights
- getActiveAlerts(): Alert[] - Get active alerts
- acknowledgeAlert(alertId: string): AnalyticsResult - Acknowledge alert
- generateReport(options?): AnalyticsResult - Generate report
- exportReport(report: Report): AnalyticsResult - 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

`bash


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.