readability-scorer

name	readability-scorer
description	Calculate readability scores (Flesch-Kincaid, Gunning Fog, SMOG) and grade levels for text. Analyze writing complexity and get improvement suggestions.

Readability Scorer

Analyze text readability using industry-standard formulas. Get grade level estimates, complexity metrics, and suggestions for improving clarity.

Quick Start

from scripts.readability_scorer import ReadabilityScorer

# Score text
scorer = ReadabilityScorer()
scores = scorer.analyze("Your text to analyze goes here.")
print(f"Grade Level: {scores['grade_level']}")
print(f"Flesch Reading Ease: {scores['flesch_reading_ease']}")

Features

• Multiple Formulas: Flesch-Kincaid, Gunning Fog, SMOG, Coleman-Liau, ARI
• Grade Level: US grade level estimate
• Reading Ease: 0-100 ease score
• Text Statistics: Words, sentences, syllables, complex words
• Batch Analysis: Process multiple documents
• Comparison: Compare readability across texts

API Reference

Initialization

scorer = ReadabilityScorer()

Analysis

scores = scorer.analyze(text)
# Returns:
# {
#     'flesch_reading_ease': 65.2,
#     'flesch_kincaid_grade': 8.1,
#     'gunning_fog': 10.2,
#     'smog_index': 9.5,
#     'coleman_liau': 9.8,
#     'ari': 8.4,
#     'grade_level': 8.5,  # Average
#     'reading_time_minutes': 2.3,
#     'stats': {
#         'words': 250,
#         'sentences': 15,
#         'syllables': 380,
#         'complex_words': 25,
#         'avg_words_per_sentence': 16.7,
#         'avg_syllables_per_word': 1.52
#     }
# }

Individual Scores

# Get specific scores
fre = scorer.flesch_reading_ease(text)
fkg = scorer.flesch_kincaid_grade(text)
fog = scorer.gunning_fog(text)
smog = scorer.smog_index(text)

Batch Analysis

texts = [text1, text2, text3]
results = scorer.analyze_batch(texts)

# From files
results = scorer.analyze_files(["doc1.txt", "doc2.txt"])

Comparison

# Compare two texts
comparison = scorer.compare(text1, text2)
print(f"Text 1 grade: {comparison['text1']['grade_level']}")
print(f"Text 2 grade: {comparison['text2']['grade_level']}")

CLI Usage

# Analyze text
python readability_scorer.py --text "Your text here"

# Analyze file
python readability_scorer.py --input document.txt

# Compare files
python readability_scorer.py --compare doc1.txt doc2.txt

# Batch analyze directory
python readability_scorer.py --input-dir ./docs --output report.csv

# Specific formula only
python readability_scorer.py --input doc.txt --formula flesch

CLI Arguments

Argument	Description	Default
--text	Text to analyze	-
--input	Input file	-
--input-dir	Directory of files	-
--output	Output file (json/csv)	-
--compare	Compare two files	-
--formula	Specific formula	all

Score Interpretation

Flesch Reading Ease

Score	Difficulty	Grade Level
90-100	Very Easy	5th grade
80-89	Easy	6th grade
70-79	Fairly Easy	7th grade
60-69	Standard	8th-9th grade
50-59	Fairly Hard	10th-12th grade
30-49	Difficult	College
0-29	Very Difficult	College graduate

Grade Level Scale

Grade	Audience
1-5	Elementary school
6-8	Middle school
9-12	High school
13-16	College
17+	Graduate level

Examples

Analyze Blog Post

scorer = ReadabilityScorer()

blog_post = """
Writing clear content is essential for engaging readers.
Short sentences help. Simple words work best.
Your audience will thank you for making things easy to understand.
"""

scores = scorer.analyze(blog_post)
print(f"Flesch Reading Ease: {scores['flesch_reading_ease']:.1f}")
print(f"Grade Level: {scores['grade_level']:.1f}")
print(f"Reading Time: {scores['reading_time_minutes']:.1f} minutes")

if scores['grade_level'] > 8:
    print("Consider simplifying for a wider audience.")

Compare Document Versions

scorer = ReadabilityScorer()

original = open("original.txt").read()
simplified = open("simplified.txt").read()

comparison = scorer.compare(original, simplified)

print("Original:")
print(f"  Grade Level: {comparison['text1']['grade_level']:.1f}")
print(f"  Flesch Ease: {comparison['text1']['flesch_reading_ease']:.1f}")

print("\nSimplified:")
print(f"  Grade Level: {comparison['text2']['grade_level']:.1f}")
print(f"  Flesch Ease: {comparison['text2']['flesch_reading_ease']:.1f}")

improvement = comparison['text1']['grade_level'] - comparison['text2']['grade_level']
print(f"\nImprovement: {improvement:.1f} grade levels easier")

Batch Analyze Documentation

scorer = ReadabilityScorer()
import os

results = []
for filename in os.listdir("./docs"):
    if filename.endswith(".md"):
        text = open(f"./docs/{filename}").read()
        scores = scorer.analyze(text)
        results.append({
            'file': filename,
            'grade': scores['grade_level'],
            'ease': scores['flesch_reading_ease']
        })

# Sort by difficulty
results.sort(key=lambda x: x['grade'], reverse=True)

print("Documents by Difficulty:")
for r in results:
    print(f"  {r['file']}: Grade {r['grade']:.1f}")

Dependencies

nltk>=3.8.0

Limitations

• English language only
• Formulas designed for prose (may not work well for lists, code, etc.)
• Syllable counting is estimated (may have minor inaccuracies)
• Doesn't assess comprehension, only surface-level complexity