# readability-consensus

> Research-backed multi-formula readability and comprehension consensus engine for TypeScript, Node.js, and web browsers. Powering the [Readability Checker at WordCount Pulse](https://wordcountpulse.in/readability-checker/).

[![npm version](https://img.shields.io/npm/v/readability-consensus.svg)](https://www.npmjs.com/package/readability-consensus)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
[![jsDelivr](https://data.jsdelivr.com/v1/package/npm/readability-consensus/badge)](https://www.jsdelivr.com/package/npm/readability-consensus)

## Live Demos & Free Online Tools
Experience the readability inspector live across our localized tools:
- **English:** [Readability Scores Checker](https://wordcountpulse.in/readability-checker/)
- **Spanish:** [Calculadora de Legibilidad](https://wordcountpulse.in/es/calculadora-legibilidad/)
- **German:** [Lesbarkeitsindex-Rechner](https://wordcountpulse.in/de/lesbarkeitsindex-rechner/)
- **French:** [Test de Lisibilité](https://wordcountpulse.in/fr/test-de-lisibilite/)
- **Italian:** [Calcolo Leggibilità Testo](https://wordcountpulse.in/it/calcolo-leggibilita/)
- **Japanese:** [可読性チェッカー・読解難易度判定](https://wordcountpulse.in/ja/readability-checker/)
- **Core Editor:** [WordCount Pulse Home](https://wordcountpulse.in)

## The Consensus Methodology
Single-formula scores frequently produce erratic outliers depending on text length and syllable estimation errors. `readability-consensus` calculates a normalized consensus grade level by harmonizing **6 classic international indices** plus **validated national formulas**:

### Core Formulas Supported
1. **Flesch Reading Ease (FRE):** Standard comprehension scale (0–100).
2. **Flesch-Kincaid Grade Level (FKGL):** US academic school grade equivalent (1–18+).
3. **Gunning Fog Index:** Evaluates sentence length and complex polysyllabic words.
4. **Coleman-Liau Index (CLI):** Character and letter-frequency based metric without syllable ambiguity.
5. **Automated Readability Index (ARI):** Character-per-word typewriter and screen metric.
6. **SMOG Index:** Recommended standard for academic and healthcare texts.

### Country-Specific National Adaptations
- **Spanish (`es`):** Fernández-Huerta Formula ($206.84 - 0.60 \times (\text{Syllables}/100w) - 1.02 \times (\text{Sentences}/100w)$).
- **Portuguese (`pt`):** Flesch Adaptado Brasil / Martins ($248.835 - 1.015 \times \text{WPS} - 84.6 \times \text{SPW}$).
- **French (`fr`):** Kandel-Moles Formula ($207 - 1.015 \times \text{WPS} - 73.6 \times \text{SPW}$).
- **German (`de`):** Toni Amstad Formel ($180 - \text{WPS} - 58.5 \times \text{SPW}$).
- **Italian (`it`):** Indice Gulpease ($89 + (300 \times \text{Sentences} - 10 \times \text{Letters}) / \text{Words}$).
- **Japanese (`ja`):** Kanji-to-Kana density ratio and 400-grid Genko Yoshi manuscript sheet calculations.

## Installation
```bash
npm install readability-consensus
# or
yarn add readability-consensus
# or
pnpm add readability-consensus
```

## Quick Start
```typescript
import { analyzeReadability } from 'readability-consensus';

const text = `
The automated readability consensus engine evaluates multiple linguistic indices simultaneously.
It provides a calibrated consensus score for web writers, academics, and editors.
`;

const analysis = analyzeReadability(text, 'en');

console.log(analysis.consensusGrade);     // e.g. 10.5 (Grade Level)
console.log(analysis.consensusLabel);     // "High School / Sophisticated"
console.log(analysis.targetAudience);     // Target reader demographic
console.log(analysis.isWebOptimal);       // true/false (Optimal for SEO if grades 6-9)

// Individual formula scores
console.log(analysis.fleschReadingEase);  // 52.4
console.log(analysis.fleschKincaidGrade); // 10.8
console.log(analysis.gunningFog);         // 11.2
console.log(analysis.colemanLiau);        // 12.1
console.log(analysis.smogIndex);          // 10.4

// Linguistic diagnostics
console.log(analysis.complexWordsCount);  // Number of 3+ syllable words
console.log(analysis.hardSentencesCount); // Number of long sentences (21+ words)
console.log(analysis.actionableTips);     // Concrete recommendations to improve clarity
```

## Multilingual Usage
```typescript
// German analysis (incorporating Toni Amstad index and 180 WPM pace)
const deAnalysis = analyzeReadability("Wissenschaftliche Texte erfordern präzise Formulierungen.", 'de');
console.log(deAnalysis.indexes.find(i => i.shortName === 'TA')?.score);

// Italian analysis (incorporating Indice Gulpease)
const itAnalysis = analyzeReadability("La leggibilità di un testo è fondamentale per la comunicazione.", 'it');
console.log(itAnalysis.indexes.find(i => i.shortName === 'IG')?.score);
```

## Documentation & Linguistic Benchmarks
For formula derivations and educational grade equivalencies, visit [WordCount Pulse Readability Guide](https://wordcountpulse.in/blog/readability-scores-guide/).

## License
MIT © [WordCount Pulse](https://wordcountpulse.in)
