README.md

---
license: apache-2.0
library_name: numpy
tags:
  - reading
  - reading-time
  - comprehension
  - memory
  - attention
  - discourse
  - heuristic
  - cpu
pipeline_tag: text-classification
language:
  - en
---

# hv-reader

**The reading experience, in one call.**

Given a text, produce a `ReadingProfile`: pace, memory, passes, slip, and
wall — the five axes that describe what it is like to read a text.

## The claim in one sentence

The seven `hv-` models each describe one aspect of reading. `hv-reader`
describes the *experience*: a five-axis signature that no single axis can
produce.

## What it produces

A `ReadingProfile` containing:

- **pace** — mean reading speed, normalized to `[0, 1]`
- **memory** — fraction of the text surviving a week
- **passes** — how many reads are required to resolve the text
- **slip** — probability of an attention lapse mid-read
- **wall** — probability of reader refusal

Plus two derived scalars:

- **ttu_s** — total reading time in seconds
- **hunger_final** — unresolved curiosity at the end

And per-sentence detail: WPM, density, retention, fold load, slip, wall,
wall type, reasons.

## Install

```bash
pip install numpy

Actually — no dependencies. Pure stdlib.

## Usage

### Demo

```bash
python hv_reader.py

Runs four synthetic samples — fiction, academic, overclaim, monotone —
and prints the full profile for each.

### Analyze a text

```bash
python hv_reader.py --text "The old man walked slowly to the boat."
python hv_reader.py --text - < essay.txt
python hv_reader.py --text "..." --profile   # five-axis summary only
python hv_reader.py --text "..." --json      # full JSON
```

### Python

```python
from hv_reader import HVReader

m = HVReader()
profile = m.analyze(text)

print(profile.pace)           # 0.672
print(profile.memory)         # 0.269
print(profile.passes)         # 1.167
print(profile.slip)           # 0.615
print(profile.wall)           # 0.000
print(profile.summary)
```

## The five axes

### pace — from `hv-tempo`

Weighted sum of surface features (sentence length, clause density, rare
vocabulary, numerals, negation, hedges, conditionals, passive voice).
Normalized by `baseline_wpm = 220`.

```
pace = mean_wpm / 400
```

A text at 400 WPM or faster has `pace = 1.0`. Fiction runs at ~0.67.
Academic prose at ~0.30.

### memory — from `hv-forget`

Per-sentence stability grows with density, rare-word ratio, and salience
(numbers, proper nouns). Retention after 7 days follows Ebbinghaus decay:

```
stability = 1.0 + 5.0 × density + 3.0 × rare_ratio + 2.0 × salience
retention = exp(−7 / stability)
```

Memory is the mean retention over all sentences. Dense, specific sentences
last longer. Filler vanishes.

### passes — from `hv-fold`

Novelty-based load: orphan definites, forward references, reentry markers.
Fold grows with load:

```
passes = 1 + total_load / n_sentences
```

Fold of 1.0 = perfectly linear. Fold of 2.0+ = the text must be read twice
to be understood.

### slip — from `hv-slip`

Attention-lapse probability. Three signals:

1. **monotone** — sentences of similar length create drowsiness
2. **repetition** — content-word overlap with the previous sentence
3. **absence** — no numbers or proper nouns to anchor attention

Slip is per-sentence, then averaged. A text of short similar sentences
scores high. A text with varied rhythm and specific content scores low.

### wall — from `hv-wall`

Highest per-sentence wall score. Three wall types, in priority order:

1. **contradiction** — the sentence contradicts an earlier claim
2. **overclaim** — certainty exceeds evidence
3. **gap** — a conclusion is drawn without prior support

Wall is the *maximum*, not the mean. A single wall is a single wall.

## Benchmarks

### Four samples

| sample | words | pace | memory | passes | slip | wall | TTU |
|---|---:|---:|---:|---:|---:|---:|---:|
| Fiction | 51 | 0.67 | 0.27 | 1.17 | 0.62 | 0.00 | 11.4 s |
| Academic | 100 | 0.30 | 0.33 | 1.62 | 0.46 | 0.00 | 50.8 s |
| Overclaim | 51 | 0.40 | 0.40 | 2.40 | 0.54 | 0.77 | 19.2 s |
| Monotone | 30 | 0.71 | 0.19 | 1.67 | 0.87 | 0.00 | 6.3 s |

**Reading the table:**

- **Fiction** — fast pace, low memory, moderate slip. The reader finishes.
- **Academic** — slow pace, moderate memory, moderate slip. The reader
  works but stays engaged.
- **Overclaim** — mid pace, high memory, *high wall*. The reader stops.
- **Monotone** — fast pace, low memory, *highest slip*. The reader's eye
  moves but the mind drifts.

The five-axis profile separates all four, even where individual axes
overlap. Fiction and monotone have similar pace. Academic and overclaim
have similar memory. The *shape* of the profile differs.

### Why the profile is not the sum of its parts

Two texts with identical pace can have different memory, slip, or wall.
Two texts with identical wall can have very different slip. The profile is
the *joint* description. Every single-axis model in the series collapses
to one of the five. The profile is the artifact.

## When to use it

- **Editing.** Find where the text breaks the reading experience.
- **Prescription.** "Your essay has pace 0.72 and slip 0.81 — it reads
  fast but won't stick."
- **Comparative analysis.** Rank texts by *reading difficulty shape*, not
  by a single readability score.
- **Reader simulation.** Feed the profile into a decision model that
  predicts whether a reader finishes.
- **Learning design.** Predict where students will zone out.
- **Marketing copy.** Predict where attention drops before conversion.

## When *not* to use it

- **As a reader study.** The axes are heuristic. The profile ranks; it
  does not measure.
- **For non-English text.** All lexicons are English.
- **For very short text.** Fewer than three sentences gives unstable
  per-axis values.
- **As ground truth on comprehension.** `memory` predicts *what survives*,
  not *what is understood*.
- **For poetry or experimental prose.** The models assume propositional
  content.

## Honest limitations

- **The five axes are independent by construction.** A text can be slow
  and forgettable. A text can be fast and memorable. A text can be slow
  and unforgettable. The profile reports the joint shape, but the axes
  do not automatically produce a single scalar. Combining them into a
  "reader burden" or "expected completion" score is left to the caller.
- **The pace model uses hand-tuned weights.** Not calibrated against
  eye-tracking or reading-time studies.
- **The memory model uses Ebbinghaus decay with a specific half-life
  formula.** Real memory is content-dependent and reader-dependent.
- **The slip model conflates monotony with attention lapse.** A reader
  can be lulled by a beautiful monotonous passage (Whitman) as easily as
  bored by filler. The model does not distinguish.
- **The wall model's antonym table is hand-curated.** Contradictions that
  rely on entailment or world knowledge will not be detected.
- **No calibration against real readers.** The demo samples are
  synthetic. The profile has not been validated against reader
  self-reports, completion rates, or comprehension tests.
- **Fiction shows a slip score higher than intuition suggests.** Short
  sentences with similar lengths trigger the monotone detector even when
  the passage is engaging. The reason is the same as above: monotony and
  attention lapse are correlated but not identical.

## Reference

Part of the reader-model series. Unifies seven component models into a
single profile:

| axis | component model |
|---|---|
| pace | `hv-tempo` |
| memory | `hv-forget` |
| passes | `hv-fold` |
| slip | `hv-slip` |
| wall | `hv-wall` |

The component models remain independently useful. `hv-reader` is the
joint signature.

## License

Apache-2.0