Relevator

A content relevance scoring system with user-configured weighted formulas. Calculate content relevance scores based on multiple metrics using customizable weights and normalization methods.

Features

• Configurable weight system
• Multiple normalization methods (linear, logarithmic, bell curve)
• Input validation
• Simple API

Installation

npm install relevator

Basic Usage

import { Relevator } from 'relevator';

// Configure the scoring system
const config = {
  weights: {
    views: 0.4,
    likes: 0.6
  },
  normalizers: {
    views: { type: 'logarithmic', max: 1000 },
    likes: { type: 'linear', max: 100 }
  }
};

// Create scorer instance
const scorer = new Relevator(config);

// Calculate score
const contentData = {
  views: 500,
  likes: 50
};

const score = scorer.calculateScore(contentData);
console.log('Content relevance score:', score); // Output: 0.5

Configuration

Weights

Weights must sum to 1 and represent the importance of each metric:

weights: {
  views: 0.4,    // 40% importance
  likes: 0.6     // 60% importance
}

Normalization Methods

Available methods:

• linear: Simple linear scaling (0 to max)
• logarithmic: Logarithmic scaling for metrics with large ranges
• bellCurve: Normal distribution around an ideal value
• boolean: Binary values (0 or 1)
• plateau: Linear up to ideal value, then exponential decay

Examples:

normalizers: {
  // Linear scaling
  views: { 
    type: 'linear', 
    max: 1000     // Scales linearly from 0 to 1000
  },
  
  // Logarithmic scaling
  followers: { 
    type: 'logarithmic', 
    max: 1000000  // Handles large ranges more gracefully
  },
  
  // Bell curve distribution
  recency: { 
    type: 'bellCurve', 
    ideal: 24,    // Peak score at 24 hours
    max: 168      // Spread over a week
  },
  
  // Boolean values
  isPremium: { 
    type: 'boolean'  // true = 1, false = 0
  },
  
  // Plateau with decay
  engagement: { 
    type: 'plateau',
    ideal: 100,    // Linear until 100
    max: 500       // Controls decay rate after ideal
  }
}

Each normalization method outputs a value between 0 and 1, which is then weighted according to your configuration.

Error Handling

The package validates configuration and throws errors for:

• Missing or empty weights/normalizers
• Weights not summing to 1
• Invalid normalization types
• Missing required parameters

License

MIT

Contributing

Contributions are welcome! Please read our contributing guidelines before submitting pull requests.