lixity 0.4.2__py3-none-any.whl

lixity/__init__.py

@@ -0,0 +1,29 @@
+"""Lixity – Quantitative text linguistics, stylometry and self-calibrating style passports."""
+
+from ._version import __version__
+from .analyzer import CorpusAnalyzer
+from .formatters import ReportFormatter
+from .io import FileUtils
+from .models import (
+    ChapterMetrics,
+    CorpusAuditReport,
+    CorpusConfig,
+    CorpusMetrics,
+    DossierStatus,
+    SentenceDistribution,
+)
+from .style_fingerprint import StyleFingerprint
+
+__all__ = [
+    "ChapterMetrics",
+    "CorpusAnalyzer",
+    "CorpusAuditReport",
+    "CorpusConfig",
+    "CorpusMetrics",
+    "DossierStatus",
+    "FileUtils",
+    "ReportFormatter",
+    "SentenceDistribution",
+    "StyleFingerprint",
+    "__version__",
+]

lixity/__main__.py

@@ -0,0 +1,5 @@
+"""Run the installed Lixity CLI with ``python -m lixity``."""
+
+from .cli import main
+
+raise SystemExit(main())

lixity/_version.py

@@ -0,0 +1,3 @@
+"""Single source of truth for the package version (readable by setuptools without imports)."""
+
+__version__ = "0.4.2"

lixity/analyzer.py

@@ -0,0 +1,569 @@
+"""lixity.analyzer – High-performance text analysis and corpus linguistics engine.
+
+Computes sentence-length architecture (ASL, CV, short/long sentence shares), lexical diversity
+(TTR, Guiraud R, HD-D, MTLD, MATTR, Maas, Yule's K), language-calibrated readability
+(Flesch family, LIX), dialogue ratios, register signals, and per-chapter metrics
+with standard errors.
+"""
+
+import math
+import os
+import re
+from collections import Counter
+from dataclasses import dataclass
+
+from .diversity import (
+    hd_d as hd_d_value,
+)
+from .diversity import (
+    maas_a2 as maas_a2_value,
+)
+from .diversity import (
+    mattr as mattr_value,
+)
+from .diversity import (
+    mtld as mtld_value,
+)
+from .diversity import (
+    yules_k as yules_k_value,
+)
+from .language import compile_pattern, compile_word_pattern, count_nominal_matches, resolve_language
+from .language_data import READABILITY
+from .markdown_parser import chapter_heading_spans, prose_paragraphs, prose_text, split_chapters
+from .math_core import binomial_se_percent, per_mille, poisson_se_per_mille
+from .models import (
+    ChapterMetrics,
+    CorpusConfig,
+    CorpusMetrics,
+    SentenceDistribution,
+)
+from .sentences import (
+    LONG_SENTENCE_MAX,
+    MEDIUM_SENTENCE_MAX,
+    SHORT_SENTENCE_MAX,
+    split_sentences,
+)
+from .style_profile import dominance_from_hits
+from .syllables import count_syllables as count_syllables_for
+
+_RE_HTML_COMMENT = re.compile(r"<!--.*?-->", re.DOTALL)
+_RE_HEADING_LINE = re.compile(r"(?m)^#+.*$")
+_RE_DASHES = re.compile(r"[–—]")
+_RE_ELLIPSES = re.compile(r"(?:…|\.{3})")
+
+
+@dataclass(frozen=True)
+class SentenceStats:
+    """Sentence-length architecture of a text (shared by corpus and chapters)."""
+
+    total: int
+    asl: float
+    median: int
+    median_exact: float
+    std: float
+    cv: float
+    distribution: SentenceDistribution
+    staccato_pct: float
+    kaskade_pct: float
+
+
+def share_se(pct: float, n: int) -> float:
+    """Binomial standard error of a share in percentage points (plug-in)."""
+    return binomial_se_percent(pct, n)
+
+
+def count_se(cnt: int, words: int) -> float:
+    """Poisson standard error of a count density (per 1,000 words)."""
+    return poisson_se_per_mille(cnt, words)
+
+
+class CorpusAnalyzer:
+    """
+    Stateless, thread-safe analysis engine for literary Markdown texts.
+    Performs quantitative corpus linguistics, stylometry and chapter segmentation.
+    """
+
+    def __init__(self, config: CorpusConfig | None = None, *, sample_text: str | None = None):
+        """Initialises the analyzer with a configuration.
+
+        If no configuration is passed, the default parameters apply.
+        ``sample_text`` lets an explicit ``language="auto"`` resolve against
+        the text to analyse; without it ``auto`` falls back to ``generic``
+        (documented in docs/LOCALIZATION.md).
+        """
+        self.config = config or CorpusConfig()
+        self.lang = resolve_language(self.config, sample_text=sample_text)
+        self._praes_re = compile_pattern(self.lang.praesens_regex)
+        self._praet_re = compile_pattern(self.lang.praeteritum_regex)
+        self._filter_re = compile_pattern(self.lang.filter_verbs_regex)
+        self._word_re = compile_word_pattern(self.lang.word_regex)
+        self._dialogue_re = compile_pattern(self.lang.dialogue_regex)
+        # Style heuristics (self-calibrating house-style fingerprint)
+        self._passive_re = compile_pattern(self.lang.passive_regex)
+        self._nominal_re = compile_pattern(self.lang.nominal_regex)
+        self._nominal_exclusions = (
+            self.lang.function_words if self.config.nominal_regex is None else frozenset()
+        )
+        self._adjective_re = compile_pattern(self.lang.adjective_regex)
+        self._modals = frozenset(w.lower() for w in self.lang.lexicon.get("modals", ()))
+        self._starters = frozenset(w.lower() for w in self.lang.first_person_starters)
+        self._content_blacklist = self.lang.function_words | self.lang.stopwords
+
+    @staticmethod
+    def _entropy(counts: Counter[str]) -> float:
+        """Shannon entropy in bits over a token-type counter."""
+        total = sum(counts.values())
+        if not total:
+            return 0.0
+        return math.fsum(-(c / total) * math.log2(c / total) for c in counts.values())
+
+    def _starter_stats(self, sentences: list[str]) -> tuple[float, float, float]:
+        """(start entropy in bits, first-person-start rate, entropy standard error).
+
+        Entropy uncertainty uses a first-order plug-in variance approximation:
+        Var(H) = [sum(p*log2^2(p)) - H^2] / n. It is not a calibrated interval.
+        """
+        starters: Counter[str] = Counter()
+        first_person = 0
+        for s in sentences:
+            tokens = self._word_re.findall(s)
+            if not tokens:
+                continue
+            # Elision-aware match (fr: "J'aime" -> "je"/"j", en: "I'm" -> "i")
+            first = tokens[0].lower()
+            stem = first.split("'", 1)[0]
+            starters[first] += 1
+            if first in self._starters or stem in self._starters:
+                first_person += 1
+        total = sum(starters.values())
+        rate = (first_person / total * 100.0) if total else 0.0
+        entropy = self._entropy(starters)
+        if not total:
+            return entropy, rate, 0.0
+        second = math.fsum(
+            (c / total) * math.log2(c / total) ** 2 for c in starters.values()
+        )
+        variance = (second - entropy**2) / total
+        return entropy, rate, math.sqrt(max(0.0, variance))
+
+    @staticmethod
+    def _density(matches: int, words: int) -> float:
+        """Occurrences per 1,000 tokens (length-comparable density)."""
+        return per_mille(matches, words)
+
+    def _jsd_chapter(
+        self,
+        chapter_counter: Counter[str],
+        corpus_counter: Counter[str],
+        n_chapter: int,
+        n_corpus: int,
+        top_n: int = 5,
+    ) -> tuple[float, list[str]]:
+        """
+        Jensen-Shannon divergence of the chapter's word distribution to the rest
+        of the corpus (leave-one-out, so small chapters are not self-biased).
+
+        Returns (jsd, top driver words): contributions are additive per type,
+        so the most divergent content words are interpretable.
+
+        Only the chapter's own vocabulary is iterated. Types the chapter does
+        not contain contribute exactly ``q * ln(2) / 2`` each, so their total
+        is ``ln(2)/2 * (1 - covered_rest_mass)`` in closed form – an O(chapter
+        types) computation instead of O(corpus types).
+        """
+        rest = n_corpus - n_chapter
+        if rest < 1 or n_chapter < 1:
+            return 0.0, []
+        jsd = 0.0
+        contribs: dict[str, float] = {}
+        covered_rest_mass = 0.0
+        for w in sorted(chapter_counter):  # deterministic order: bit-identical across runs
+            p = chapter_counter[w] / n_chapter
+            q = (corpus_counter[w] - chapter_counter[w]) / rest
+            covered_rest_mass += q
+            m = 0.5 * (p + q)
+            term = p * math.log(p / m)
+            if q > 0.0:
+                term += q * math.log(q / m)
+            contrib = 0.5 * term
+            contribs[w] = contrib
+            jsd += contrib
+        # Types absent from the chapter: p = 0, m = q/2 -> contribution q*ln(2)/2.
+        jsd += 0.5 * math.log(2.0) * max(0.0, 1.0 - covered_rest_mass)
+        top = [
+            w
+            for w, _ in sorted(contribs.items(), key=lambda kv: kv[1], reverse=True)
+            if len(w) > 1 and w not in self._content_blacklist
+        ][:top_n]
+        return jsd, top
+
+    def count_syllables(self, word: str) -> int:
+        """Language-sensitive syllable counting (see :mod:`lixity.syllables`)."""
+        return count_syllables_for(word, self.lang.key)
+
+    def readability(self, asl: float, asw: float) -> tuple[float, str]:
+        """Language-calibrated Reading Ease score and formula name; not clipped to 0–100."""
+        rd = READABILITY.get(self.lang.key, READABILITY["generic"])
+        if asl == 0.0 and asw == 0.0:
+            return 0.0, rd["name"]
+        score = rd["constant"] - rd["asl_coef"] * asl - rd["asw_coef"] * asw
+        return score, rd["name"]
+
+    def long_word_min(self) -> int:
+        """Language-calibrated minimum letter count for LIX 'long words' (Björnsson)."""
+        rd = READABILITY.get(self.lang.key, READABILITY["generic"])
+        return int(rd["long_word_min"])
+
+    def _sentence_stats(self, sentences: list[str]) -> SentenceStats:
+        """Sentence-length architecture (lengths, ASL, median, CV, distribution)."""
+        lengths = [n for n in (len(self._word_re.findall(s)) for s in sentences) if n > 0]
+        total = len(lengths)
+        asl = sum(lengths) / total if total else 0.0
+        sorted_lengths = sorted(lengths)
+        median_sl = sorted_lengths[total // 2] if total else 0
+        median_exact = (
+            (sorted_lengths[(total - 1) // 2] + sorted_lengths[total // 2]) / 2.0
+            if total
+            else 0.0
+        )
+        variance = sum((x - asl) ** 2 for x in lengths) / total if total else 0.0
+        std = math.sqrt(variance)
+        short = sum(1 for x in lengths if x <= SHORT_SENTENCE_MAX)
+        medium = sum(1 for x in lengths if SHORT_SENTENCE_MAX < x <= MEDIUM_SENTENCE_MAX)
+        long_ = sum(1 for x in lengths if MEDIUM_SENTENCE_MAX < x <= LONG_SENTENCE_MAX)
+        complex_ = sum(1 for x in lengths if x > LONG_SENTENCE_MAX)
+
+        def _pct(count: int) -> float:
+            return (count / total * 100.0) if total else 0.0
+
+        return SentenceStats(
+            total=total,
+            asl=asl,
+            median=median_sl,
+            median_exact=median_exact,
+            std=std,
+            cv=(std / asl) if asl else 0.0,
+            distribution=SentenceDistribution(
+                short_count=short,
+                short_pct=_pct(short),
+                medium_count=medium,
+                medium_pct=_pct(medium),
+                long_count=long_,
+                long_pct=_pct(long_),
+                complex_count=complex_,
+                complex_pct=_pct(complex_),
+            ),
+            staccato_pct=_pct(short),
+            kaskade_pct=_pct(complex_),
+        )
+
+    def _paragraph_stats(self, paragraphs: list[str]) -> tuple[int, float, int]:
+        """(prose paragraphs, average words per paragraph, one-liner count)."""
+        lengths = [len(p.split()) for p in paragraphs]
+        total = len(lengths)
+        average = sum(lengths) / total if total else 0.0
+        one_liners = sum(
+            1
+            for length in lengths
+            if length <= self.config.min_paragraph_length_for_oneliner
+        )
+        return total, average, one_liners
+
+    def _punctuation_profile(self, text: str) -> dict[str, int]:
+        """Language-neutral punctuation counts for the JSON contract."""
+        return {
+            "periods": text.count("."),
+            "commas": text.count(","),
+            "dashes": len(_RE_DASHES.findall(text)),
+            "colons": text.count(":"),
+            "semicolons": text.count(";"),
+            "questions": text.count("?"),
+            "exclamations": text.count("!"),
+            "ellipses": len(_RE_ELLIPSES.findall(text)),
+        }
+
+    def measure_unit(self, text: str) -> ChapterMetrics | None:
+        """Measure one prose unit using the chapter feature engine once.
+
+        This omits corpus-level readability, cross-chapter divergence and title
+        parsing. It is useful for scenes already segmented by the shared parser.
+        """
+        return self._chapter_metrics(1, "", text, self.long_word_min())[0]
+
+    def _chapter_metrics(
+        self, num: int, title: str, body: str, lw_min: int
+    ) -> tuple[ChapterMetrics | None, list[str]]:
+        """Per-chapter metrics (style features, uncertainty, tense, JSD input)."""
+        cl_b = prose_text(body, _front_matter=False)
+        c_words = self._word_re.findall(cl_b)
+        if not c_words:
+            return None, []
+
+        n_cw = len(c_words)
+        c_lower = [w.lower() for w in c_words]
+        c_sentences = split_sentences(cl_b, self.lang.key)
+        stats = self._sentence_stats(c_sentences)
+
+        c_dial = self._dialogue_re.findall(cl_b)
+        c_dial_words = sum(len(self._word_re.findall(m)) for m in c_dial)
+        c_dial_pct = (c_dial_words / n_cw) * 100.0 if n_cw else 0.0
+        c_ttr = len(set(c_lower)) / n_cw if n_cw else 0.0
+        c_signals = {
+            s_name: len(re.findall(s_pat, cl_b, re.IGNORECASE))
+            for s_name, s_pat in self.lang.signal_keywords.items()
+        }
+        c_motifs = {
+            m_name: len(re.findall(m_pat, cl_b, re.IGNORECASE))
+            for m_name, m_pat in self.config.motif_regexes.items()
+        }
+        c_fil = len(self._filter_re.findall(cl_b))
+        dominance = dominance_from_hits(
+            len(self._praes_re.findall(cl_b)), len(self._praet_re.findall(cl_b))
+        )
+
+        c_start_entropy, c_first_rate, c_entropy_se = self._starter_stats(c_sentences)
+        c_passive_cnt = len(self._passive_re.findall(cl_b))
+        c_nominal_cnt = count_nominal_matches(cl_b, self._nominal_re, self._nominal_exclusions)
+        c_adjective_cnt = len(self._adjective_re.findall(cl_b))
+        c_modal_cnt = sum(1 for t in c_lower if t in self._modals)
+        c_long_words = sum(1 for t in c_words if len(t) > lw_min)
+        c_long_pct = (c_long_words / n_cw * 100.0) if n_cw else 0.0
+        c_guiraud = len(set(c_lower)) / math.sqrt(n_cw) if n_cw else 0.0
+        c_hd_d = hd_d_value(c_lower)
+        c_func_pct = (
+            sum(1 for t in c_lower if t in self.lang.function_words) / n_cw * 100.0 if n_cw else 0.0
+        )
+
+        # Measurement uncertainty per feature (documented plug-ins)
+        c_se: dict[str, float] = {
+            "asl": (stats.std / math.sqrt(stats.total)) if stats.total else 0.0,
+            "staccato_pct": share_se(stats.staccato_pct, stats.total),
+            "kaskade_pct": share_se(stats.kaskade_pct, stats.total),
+            "sentence_cv": (
+                (stats.cv / math.sqrt(2.0 * stats.total)) * math.sqrt(1.0 + 2.0 * stats.cv**2)
+                if stats.total
+                else 0.0
+            ),
+            "dialog_pct": share_se(c_dial_pct, n_cw),
+            "function_word_pct": share_se(c_func_pct, n_cw),
+            "filter_density": count_se(c_fil, n_cw),
+            "modal_density": count_se(c_modal_cnt, n_cw),
+            "passive_density": count_se(c_passive_cnt, n_cw),
+            "nominalization_density": count_se(c_nominal_cnt, n_cw),
+            "adjective_density": count_se(c_adjective_cnt, n_cw),
+            "long_word_pct": share_se(c_long_pct, n_cw),
+            "start_entropy": c_entropy_se,
+            "first_person_start_rate": share_se(c_first_rate, stats.total),
+            "guiraud_r": (0.5 * c_guiraud / math.sqrt(n_cw)) if n_cw else 0.0,
+        }
+        # Exact rarefaction has no Monte Carlo SE; population uncertainty is not estimated.
+
+        chapter = ChapterMetrics(
+            num=num,
+            title=title,
+            words=n_cw,
+            sentences=stats.total,
+            asl=stats.asl,
+            dialog_pct=c_dial_pct,
+            ttr=c_ttr,
+            motif_counts=c_motifs,
+            filter_verbs=c_fil,
+            dominance=dominance,
+            signal_matches=c_signals,
+            staccato_pct=stats.staccato_pct,
+            kaskade_pct=stats.kaskade_pct,
+            sentence_cv=stats.cv,
+            start_entropy=c_start_entropy,
+            first_person_start_rate=c_first_rate,
+            passive_density=self._density(c_passive_cnt, n_cw),
+            nominalization_density=self._density(c_nominal_cnt, n_cw),
+            adjective_density=self._density(c_adjective_cnt, n_cw),
+            modal_density=self._density(c_modal_cnt, n_cw),
+            filter_density=self._density(c_fil, n_cw),
+            long_word_pct=c_long_pct,
+            guiraud_r=c_guiraud,
+            hd_d=c_hd_d,
+            function_word_pct=c_func_pct,
+            style_se=c_se,
+        )
+        return chapter, c_lower
+
+    def analyze_text(self, full_text: str) -> CorpusMetrics:
+        """
+        Performs the complete stylometric and quantitative analysis on
+        a passed text string.
+
+        Workflow:
+        1. Separation of the scholarly appendix (single source of truth).
+        2. Filtering of Markdown HTML comments (<!-- ... -->).
+        3. Tokenisation and capture of vocabulary types.
+        4. Computation of lexical diversity metrics (TTR, Guiraud, Yule).
+        5. Sentence segmentation and sentence-length architecture (without heading artefacts).
+        6. Readability indices (Flesch family, LIX).
+        7. Dialogue and paragraph economy.
+        8. Punctuation and signal word frequencies.
+        9. Chapter-wise segmentation and tense classification.
+
+        Returns:
+            CorpusMetrics object with all computed metrics.
+        """
+        # 1. Main text vs. appendix, comments removed
+        if self.config.appendix_marker and self.config.appendix_marker in full_text:
+            main_text, _ = full_text.split(self.config.appendix_marker, 1)
+        else:
+            main_text = full_text
+        cleaned_full = _RE_HTML_COMMENT.sub("", full_text)
+        cleaned_main = _RE_HTML_COMMENT.sub("", main_text)
+        # Configured chapter headings are metadata, just like Markdown headings.
+        # Retain line separators so removing one never joins adjacent prose.
+        prose_parts: list[str] = []
+        cursor = 0
+        for start, end, _line, _title in chapter_heading_spans(cleaned_main, self.config):
+            prose_parts.append(cleaned_main[cursor:start])
+            prose_parts.append("\n" if cleaned_main[end - 1:end] == "\n" else "")
+            cursor = end
+        prose_parts.append(cleaned_main[cursor:])
+        legacy_clean_main = _RE_HEADING_LINE.sub("", "".join(prose_parts))
+
+        raw_words = len(cleaned_full.split())
+        clean_words = len(legacy_clean_main.split())
+        raw_chars = len(cleaned_full)
+        clean_chars = len(legacy_clean_main)
+        # Token-based measurements share the supported semantic-block scope.
+        # Legacy whitespace words/chars intentionally retain their own contract.
+        prose_units = prose_paragraphs(main_text, self.config)
+        prose_main = "\n\n".join(prose_units)
+
+        # 2. Tokenisation
+        tokens = self._word_re.findall(prose_main)
+        n_tokens = len(tokens)
+        lower_tokens = [t.lower() for t in tokens]
+        v_types = len(set(lower_tokens))
+        freqs = Counter(lower_tokens)
+
+        # 3. Lexical range & stability
+        ttr = v_types / n_tokens if n_tokens else 0.0
+        guiraud_r = v_types / math.sqrt(n_tokens) if n_tokens else 0.0
+
+        # 4. Sentence-length architecture on the same prose as other metrics.
+        sentences = split_sentences(prose_main, self.lang.key)
+        stats = self._sentence_stats(sentences)
+        start_entropy, first_person_start_rate, _entropy_se = self._starter_stats(sentences)
+
+        # 5. Readability & complexity (language-calibrated Flesch family + LIX)
+        total_syllables = sum(self.count_syllables(t) * count for t, count in freqs.items())
+        asw = total_syllables / n_tokens if n_tokens else 0.0
+        if n_tokens == 0 or stats.total == 0:
+            flesch_de = 0.0
+            flesch_variant = self.readability(0.0, 0.0)[1]
+            lix = 0.0
+        else:
+            flesch_de, flesch_variant = self.readability(stats.asl, asw)
+            lw_min = self.long_word_min()
+            long_words = sum(1 for t in tokens if len(t) > lw_min)
+            pct_long_words = (long_words / n_tokens) * 100.0 if n_tokens else 0.0
+            lix = stats.asl + pct_long_words
+
+        # 6. Dialogue ratio
+        dialog_matches = self._dialogue_re.findall(prose_main)
+        dialog_words = sum(len(self._word_re.findall(m)) for m in dialog_matches)
+        dialog_ratio = (dialog_words / n_tokens) * 100.0 if n_tokens else 0.0
+
+        # 7. Paragraph economy, punctuation, signals
+        total_paras, avg_para_len, single_line_paras = self._paragraph_stats(prose_units)
+        punctuation = self._punctuation_profile(prose_main)
+        signal_counts = {
+            name: len(re.findall(pat, prose_main, re.IGNORECASE))
+            for name, pat in self.lang.signal_keywords.items()
+        }
+        filter_cnt = len(self._filter_re.findall(prose_main))
+
+        # 8. Style densities (per 1,000 tokens, length-comparable)
+        passive_density = self._density(len(self._passive_re.findall(prose_main)), n_tokens)
+        nominalization_density = self._density(
+            count_nominal_matches(prose_main, self._nominal_re, self._nominal_exclusions), n_tokens
+        )
+        adjective_density = self._density(len(self._adjective_re.findall(prose_main)), n_tokens)
+        modal_density = self._density(sum(1 for t in lower_tokens if t in self._modals), n_tokens)
+        filter_density = self._density(filter_cnt, n_tokens)
+
+        # 9. Chapter-wise segmentation (shared split_chapters: front matter +
+        #    appendix + empty-body rules identical to the structure modules).
+        chapters: list[ChapterMetrics] = []
+        chapter_tokens: list[list[str]] = []
+        for _split_num, title, body in split_chapters(main_text, self.config):
+            chapter, c_lower = self._chapter_metrics(len(chapters) + 1, title, body, lw_min)
+            if chapter is None:
+                continue
+            chapters.append(chapter)
+            chapter_tokens.append(c_lower)
+
+        # 10. Jensen-Shannon divergence per chapter vs. the rest (leave-one-out)
+        for chapter, c_lower in zip(chapters, chapter_tokens, strict=False):
+            chapter.jsd, chapter.jsd_top_words = self._jsd_chapter(
+                Counter(c_lower), freqs, len(c_lower), n_tokens
+            )
+
+        return CorpusMetrics(
+            raw_words=raw_words,
+            clean_words=clean_words,
+            raw_chars=raw_chars,
+            clean_chars=clean_chars,
+            tokens=n_tokens,
+            vocab_types=v_types,
+            ttr=ttr,
+            guiraud_r=guiraud_r,
+            yules_k=yules_k_value(lower_tokens),
+            total_sentences=stats.total,
+            asl=stats.asl,
+            median_sl=stats.median,
+            median_sl_exact=stats.median_exact,
+            std_sl=stats.std,
+            sentence_dist=stats.distribution,
+            asw=asw,
+            flesch_de=flesch_de,
+            flesch_variant=flesch_variant,
+            lix=lix,
+            dialog_words=dialog_words,
+            dialog_ratio=dialog_ratio,
+            total_paragraphs=total_paras,
+            avg_paragraph_len=avg_para_len,
+            single_line_paragraphs=single_line_paras,
+            punctuation=punctuation,
+            signal_counts=signal_counts,
+            filter_count=filter_cnt,
+            chapters=chapters,
+            staccato_pct=stats.staccato_pct,
+            kaskade_pct=stats.kaskade_pct,
+            sentence_cv=stats.cv,
+            start_entropy=start_entropy,
+            first_person_start_rate=first_person_start_rate,
+            passive_density=passive_density,
+            nominalization_density=nominalization_density,
+            adjective_density=adjective_density,
+            modal_density=modal_density,
+            filter_density=filter_density,
+            hd_d=hd_d_value(lower_tokens),
+            mtld=mtld_value(lower_tokens),
+            mattr=mattr_value(lower_tokens),
+            maas_a2=maas_a2_value(n_tokens, v_types),
+        )
+
+    def analyze_file(self, filepath: str) -> CorpusMetrics:
+        """
+        Reads a UTF-8 text file and delegates to analyze_text.
+
+        Parameters:
+            filepath: Absolute or relative file path to the Markdown manuscript.
+
+        Returns:
+            CorpusMetrics object.
+
+        Raises:
+            FileNotFoundError: If the file does not exist at the given path.
+        """
+        if not os.path.isfile(filepath):
+            raise FileNotFoundError(f"Manuscript file not found: {filepath}")
+        with open(filepath, encoding="utf-8") as f:
+            content = f.read()
+        return self.analyze_text(content)