Plain Language skill for Codex

Gives the Codex app a display name, a one-line description and a starter prompt for this skill.

interface:
  display_name: "Plain Language"
  short_description: "Understood on the first read by anyone"
  default_prompt: "$plain-language Rewrite this benefits letter so someone with a grade 6 reading level understands it"

#!/usr/bin/env python3
"""Readability report for plain-language rewriting (English text or Markdown).

Usage:
  python3 readability.py FILE [--max-grade 8] [--jargon WORDS.txt] [--top 10]
  cat draft.txt | python3 readability.py - --max-grade 6

Reports Flesch Reading Ease, Flesch-Kincaid grade, sentence-length stats, long words,
likely passive constructions, and the longest sentences. Markdown code blocks, inline
code, URLs and HTML tags are ignored. Exit 1 if the grade exceeds --max-grade, 2 on usage
errors. Standard library only. Formulas are rough guides: use them to find hard spots,
never as proof that text is clear.
"""
from __future__ import annotations

import re
import sys
from pathlib import Path

ABBREV = re.compile(r"\b(e\.g|i\.e|etc|vs|Mr|Mrs|Ms|Dr|No|approx|Inc|Ltd)\.", re.I)
PASSIVE = re.compile(
    r"\b(am|is|are|was|were|be|been|being)\s+(\w+ly\s+)?(\w+ed|\w+en|made|done|sent|paid|held|kept|set|put|told|given|taken|shown|known|seen|built|found|lost|sold)\b",
    re.I,
)
NOT_PARTICIPLE = {"open", "often", "even", "seven", "eleven", "garden", "kitchen", "token", "hidden", "chicken", "listen", "happen", "need", "used", "red", "bed", "speed", "seed", "feed", "indeed", "hundred"}


def clean(text: str) -> str:
    text = re.sub(r"```.*?```|~~~.*?~~~", " ", text, flags=re.S)
    text = re.sub(r"`[^`]*`", " ", text)
    text = re.sub(r"<[^>]+>", " ", text)
    text = re.sub(r"!?\[([^\]]*)\]\([^)]*\)", r"\1", text)
    text = re.sub(r"https?://\S+", " ", text)
    text = re.sub(r"^\s*([#>*+-]|\d+\.)\s*", "", text, flags=re.M)
    text = re.sub(r"^\s*\|.*\|\s*$", " ", text, flags=re.M)  # tables
    # headings and list items without terminal punctuation still end a sentence
    text = re.sub(r"([^.!?:;\s])\s*\n\s*\n", r"\1.\n\n", text)
    return text


def sentences(text: str) -> list[str]:
    text = ABBREV.sub(lambda m: m.group(0).replace(".", ""), text)
    parts = re.split(r"(?<=[.!?])\s+(?=[\"'(\[]?[A-Z0-9])", text)
    return [re.sub(r"\s+", " ", p).strip() for p in parts if re.search(r"[A-Za-z]", p)]


def words(sentence: str) -> list[str]:
    return re.findall(r"[A-Za-z]+(?:['’-][A-Za-z]+)*", sentence)


def syllables(word: str) -> int:
    w = word.lower().replace("’", "'")
    if len(w) <= 3:
        return 1
    w = re.sub(r"(?:[^laeiouy]es|ed|[^laeiouy]e)$", "", w)
    w = re.sub(r"^y", "", w)
    count = len(re.findall(r"[aeiouy]{1,2}", w))
    return max(1, count)


def main(argv: list[str]) -> int:
    if not argv or argv[0] in ("-h", "--help"):
        print(__doc__.strip())
        return 2
    opts = {"--max-grade": "8", "--jargon": "", "--top": "10"}
    pos = []
    i = 0
    while i < len(argv):
        if argv[i] in opts and i + 1 < len(argv):
            opts[argv[i]] = argv[i + 1]
            i += 2
        else:
            pos.append(argv[i])
            i += 1
    if len(pos) != 1:
        print("error: give exactly one FILE or '-'", file=sys.stderr)
        return 2
    try:
        raw = sys.stdin.read() if pos[0] == "-" else Path(pos[0]).read_text(encoding="utf-8")
        max_grade = float(opts["--max-grade"])
        top = int(opts["--top"])
    except (OSError, ValueError) as exc:
        print(f"error: {exc}", file=sys.stderr)
        return 2

    sents = sentences(clean(raw))
    if not sents:
        print("error: no prose found", file=sys.stderr)
        return 2
    per = [(s, words(s)) for s in sents]
    per = [(s, w) for s, w in per if w]
    all_words = [w for _, ws in per for w in ws]
    n_s, n_w = len(per), len(all_words)
    n_syl = sum(syllables(w) for w in all_words)
    wps, spw = n_w / n_s, n_syl / n_w
    ease = 206.835 - 1.015 * wps - 84.6 * spw
    grade = 0.39 * wps + 11.8 * spw - 15.59
    long_words = [w for w in all_words if syllables(w) >= 3]
    lengths = sorted(len(ws) for _, ws in per)
    over25 = sum(1 for x in lengths if x > 25)
    passive = []
    for s, _ in per:
        for m in PASSIVE.finditer(s):
            if m.group(3).lower() not in NOT_PARTICIPLE:
                passive.append(s)
                break

    print(f"Sentences: {n_s}   Words: {n_w}   Avg words/sentence: {wps:.1f}   Median: {lengths[len(lengths) // 2]}")
    print(f"Flesch Reading Ease: {ease:.0f}  (60-70 plain English; higher is easier)")
    print(f"Flesch-Kincaid grade: {grade:.1f}  (target <= {max_grade:g})")
    print(f"Sentences over 25 words: {over25} ({100 * over25 / n_s:.0f}%)")
    print(f"Words of 3+ syllables: {100 * len(long_words) / n_w:.0f}%")
    print(f"Likely passive sentences: {len(passive)} ({100 * len(passive) / n_s:.0f}%)")

    if opts["--jargon"]:
        terms = [t.strip().lower() for t in Path(opts["--jargon"]).read_text(encoding="utf-8").splitlines() if t.strip() and not t.startswith("#")]
        low = clean(raw).lower()
        hits = {t: len(re.findall(r"\b" + re.escape(t) + r"\b", low)) for t in terms}
        hits = {t: c for t, c in hits.items() if c}
        if hits:
            print("Jargon found: " + ", ".join(f"{t} x{c}" for t, c in sorted(hits.items(), key=lambda kv: -kv[1])))
        else:
            print("Jargon found: none from list")

    print(f"\nLongest sentences (top {top}):")
    for s, ws in sorted(per, key=lambda p: -len(p[1]))[:top]:
        print(f"  [{len(ws)} words] {s[:220]}{'...' if len(s) > 220 else ''}")
    if passive:
        print("\nPassive candidates (check each; some are fine):")
        for s in passive[:top]:
            print(f"  - {s[:200]}{'...' if len(s) > 200 else ''}")
    return 1 if grade > max_grade else 0


if __name__ == "__main__":
    sys.exit(main(sys.argv[1:]))