InsightLab SDK

Turn raw datasets into insights automatically with AI-powered analysis.

Features

• Dataset Profiling: Comprehensive statistical analysis of your data

• AI-Generated Insights: Intelligent insights powered by OpenAI

• Automatic Trend Detection: Identify patterns and trends in your data

• Predictive Analysis: Multiple prediction models including linear regression, moving averages, and AI-based forecasting

• AI-Generated Reports: Beautiful reports in Markdown, HTML, or JSON format

Installation

npm  install  @thebadlab/insightlab

Quick Start

import { InsightLab } from  '@thebadlab/insightlab';

  

// Initialize the SDK

const  lab = new  InsightLab({

openAIApiKey:  'your-openai-api-key'

});

  

// Your dataset (array of arrays, first row is headers)

const  data = [

['Date', 'Sales', 'Revenue', 'Customers'],

['2024-01-01', 100, 5000, 25],

['2024-01-02', 120, 6000, 30],

['2024-01-03', 110, 5500, 28],

// ... more data

];

  

// Get complete analysis

const  analysis = await  lab.analyzeComplete(data, 'Sales');

  

console.log('Profile:', analysis.profile);

console.log('Insights:', analysis.insights);

console.log('Trends:', analysis.trends);

console.log('Predictions:', analysis.predictions);

  

// Export report as Markdown

const  markdown = lab.exportReportAsMarkdown(analysis.report);

console.log(markdown);

API Reference

Constructor

new  InsightLab(config: InsightLabConfig)

Parameters:

• config.openAIApiKey (string, required): Your OpenAI API key

• config.model (string, optional): OpenAI model to use (default: 'gpt-4o-mini')

Dataset Profiling

profileDataset(data: Dataset): DatasetProfile

Analyzes the structure and statistics of your dataset.

const  profile = lab.profileDataset(data);

  

console.log(profile.rowCount); // Number of rows

console.log(profile.columnCount); // Number of columns

console.log(profile.columns); // Detailed column statistics

console.log(profile.missingValues); // Missing values per column

console.log(profile.duplicateRows); // Number of duplicate rows

Returns: DatasetProfile object containing:

• rowCount: Total number of rows

• columnCount: Total number of columns

• columns: Array of column profiles with statistics

• missingValues: Object mapping column names to missing value counts

• duplicateRows: Number of duplicate rows found

• memoryUsage: Estimated memory usage

• summary: Text summary of the dataset

Insights Generation

generateInsights(data: Dataset, profile?: DatasetProfile): Promise<Insight[]>

Generates AI-powered insights from your dataset.

const  insights = await  lab.generateInsights(data);

  

insights.forEach(insight  => {

console.log(insight.title);

console.log(insight.description);

console.log(insight.confidence); // 'high', 'medium', or 'low'

console.log(insight.type); // 'correlation', 'anomaly', 'pattern', etc.

});

Returns: Array of Insight objects containing:

• title: Brief insight title

• description: Detailed description

• type: Type of insight (correlation, anomaly, pattern, recommendation, observation)

• confidence: Confidence level (high, medium, low)

• relatedColumns: Array of related column names

Trend Detection

detectTrends(data: Dataset): Trend[]

Automatically detects trends in numeric columns.

const  trends = lab.detectTrends(data);

  

trends.forEach(trend  => {

console.log(trend.column); // Column name

console.log(trend.type); // 'increasing', 'decreasing', 'seasonal', etc.

console.log(trend.strength); // Strength of the trend (0-1)

console.log(trend.description); // Human-readable description

});

detectTimeSeriesTrends(data: Dataset, timeColumn: string, valueColumn: string): Trend | null

Analyzes trends in time series data with forecasting.

const  trend = lab.detectTimeSeriesTrends(data, 'Date', 'Sales');

  

if (trend) {

console.log(trend.dataPoints); // Historical data points

console.log(trend.forecast); // Future predictions

}

Predictive Analysis

predict(data: Dataset, targetColumn: string, options?): Promise<PredictionResult>

AI-powered predictions for any column.

const  prediction = await  lab.predict(data, 'Sales', {

featureColumns: ['Revenue', 'Customers'],

predictionCount:  5

});

  

console.log(prediction.predictions); // Array of predicted values

console.log(prediction.confidence); // Confidence score (0-1)

console.log(prediction.insights); // AI-generated insights about predictions

predictLinearRegression(data: Dataset, xColumn: string, yColumn: string): PredictionResult

Linear regression predictions.

const  prediction = lab.predictLinearRegression(data, 'Customers', 'Revenue');

console.log(prediction.accuracy); // R² value

predictMovingAverage(data: Dataset, column: string, window?: number): PredictionResult

Moving average prediction (default window: 3).

const  prediction = lab.predictMovingAverage(data, 'Sales', 7);

predictExponentialSmoothing(data: Dataset, column: string, alpha?: number): PredictionResult

Exponential smoothing prediction (default alpha: 0.3).

const  prediction = lab.predictExponentialSmoothing(data, 'Sales', 0.5);

Report Generation

generateReport(data: Dataset, options?): Promise<Report>

Generates a comprehensive analysis report.

const  report = await  lab.generateReport(data, {

includeProfile:  true,

includeInsights:  true,

includeTrends:  true,

includePredictions:  true,

targetColumn:  'Sales'

});

  

console.log(report.title);

console.log(report.summary);

console.log(report.sections);

console.log(report.recommendations);

Report Export Methods

// Export as Markdown

const  markdown = lab.exportReportAsMarkdown(report);

  

// Export as JSON

const  json = lab.exportReportAsJSON(report);

  

// Export as HTML

const  html = lab.exportReportAsHTML(report);

Complete Analysis

analyzeComplete(data: Dataset, targetColumn?: string): Promise<CompleteAnalysis>

Performs all analyses in one call.

const  analysis = await  lab.analyzeComplete(data, 'Sales');

  

// Returns object with:

// - profile: DatasetProfile

// - insights: Insight[]

// - trends: Trend[]

// - predictions: PredictionResult (if targetColumn provided)

// - report: Report

Data Format

InsightLab expects data in a simple 2D array format where the first row contains headers:

const  data = [

['Column1', 'Column2', 'Column3'], // Headers

['value1', 'value2', 'value3'], // Row 1

['value4', 'value5', 'value6'], // Row 2

// ... more rows

];

Examples

Example 1: Sales Data Analysis

import { InsightLab } from  '@thebadlab/insightlab';

  

const  lab = new  InsightLab({ openAIApiKey:  process.env.OPENAI_API_KEY });

  

const  salesData = [

['Date', 'Sales', 'Marketing', 'Region'],

['2024-01-01', 1000, 200, 'North'],

['2024-01-02', 1200, 250, 'South'],

['2024-01-03', 950, 180, 'North'],

// ... more data

];

  

// Profile the dataset

const  profile = lab.profileDataset(salesData);

console.log(`Dataset has ${profile.rowCount} rows and ${profile.columnCount} columns`);

  

// Get insights

const  insights = await  lab.generateInsights(salesData);

console.log(`Found ${insights.length} insights`);

  

// Detect trends

const  trends = lab.detectTrends(salesData);

trends.forEach(t  =>  console.log(`${t.column}: ${t.type} trend`));

  

// Generate predictions

const  predictions = await  lab.predict(salesData, 'Sales');

console.log('Next 5 predictions:', predictions.predictions);

Example 2: Time Series Analysis

const  timeSeriesData = [

['Date', 'Temperature'],

['2024-01-01', 20],

['2024-01-02', 22],

['2024-01-03', 21],

// ... more data

];

  

// Analyze time series trends

const  trend = lab.detectTimeSeriesTrends(timeSeriesData, 'Date', 'Temperature');

  

if (trend && trend.forecast) {

console.log('Historical data:', trend.dataPoints);

console.log('Forecast:', trend.forecast);

}

  

// Use moving average for prediction

const  prediction = lab.predictMovingAverage(timeSeriesData, 'Temperature', 7);

console.log('7-day moving average prediction:', prediction.predictions[0]);

Example 3: Generate Complete Report

const  analysis = await  lab.analyzeComplete(salesData, 'Sales');

  

// Export as HTML for viewing

const  html = lab.exportReportAsHTML(analysis.report);

require('fs').writeFileSync('report.html', html);

  

// Export as Markdown for documentation

const  markdown = lab.exportReportAsMarkdown(analysis.report);

require('fs').writeFileSync('report.md', markdown);

Advanced Usage

Custom AI Model

const  lab = new  InsightLab({

openAIApiKey:  'your-key',

model:  'gpt-4'  // Use GPT-4 for better insights

});

Individual Module Usage

You can also use individual modules directly:

import { DatasetProfiler, InsightsGenerator, TrendDetector } from  '@thebadlab/insightlab';

  

const  profiler = new  DatasetProfiler();

const  profile = profiler.profile(data);

  

const  insightsGen = new  InsightsGenerator('your-api-key');

const  insights = await  insightsGen.generateInsights(data, profile);

  

const  trendDetector = new  TrendDetector();

const  trends = trendDetector.detectTrends(data);

TypeScript Support

InsightLab is written in TypeScript and includes full type definitions. All types are exported:

import  type {

Dataset,

DatasetProfile,

Insight,

Trend,

PredictionResult,

Report

} from  '@thebadlab/insightlab';

Requirements

• Node.js 16 or higher

• OpenAI API key

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Support

For issues and questions, please open an issue on GitHub.