hv-core

Sensitivity-annotated argument graph. Given a text, output what it claims, how much each claim carries, and the single cheapest edit that would break it.

The claim in one sentence

hv-core produces the sensitivity-annotated argument graph:

G = (V, E, d, Φ)

V = claims
E = inference relations
d = per-claim information density
Φ = flip sets (which edits change the conclusion)

What it produces

A CoreReport containing:

graph — nodes (claims) and edges (inference relations)
density — per-claim information weight
critical_path — highest-density path from premises to conclusion
redundant_claims — claims removable without changing the conclusion
low_density_spans — filler claims
gaps — structural inferences that should exist but don't
flip_set — the minimal cut: the set of edges whose simultaneous removal flips the conclusion
min_flip_cost — total cost of the cheapest cut
robustness — the scalar R (total cost of the min-cut)
robustness_tier — weak / medium / strong / trivial
load_bearing_claim — the densest claim on the critical path
redundancy_index — fraction of removable claims

Robustness tier

Tier is assigned by cut size (structural robustness), not by raw cost:

cut size	tier
0 edges (no support reaches the conclusion)	`trivial`
1 edge	`weak`
2–3 edges	`medium`
4+ edges	`strong`

robustness itself is the total cost of the min-cut under c(e) = d(u) + d(v). It scales with both cut size and edge density; the tier is the structural verdict.

Install

pip install numpy

Actually — no dependencies. Pure stdlib.

## Usage

### Analyze a text

```python
from hv_core import HVCore

m = HVCore()
report = m.analyze("The biopsy was negative. The imaging confirmed it. "
                   "Therefore the tumor is benign.")

print(report.robustness)              # total min-cut cost
print(report.robustness_tier)         # 'medium'
print(report.load_bearing_claim)      # {'id': 0, 'density': 0.81, ...}
print(report.redundant_claims)        # [2]

### Just the numbers

```python
m.robustness(text)          # the scalar R
m.conclusion(text)          # detected conclusion
m.load_bearing(text)        # the claim the argument rests on
m.flips(text, top=5)        # the edges of the min-cut

CLI

python hv_core.py                                    # run all demos
python hv_core.py --text "..."                       # analyze a text
python hv_core.py --text "..." --robustness          # just the scalar
python hv_core.py --text "..." --flips 5             # top 5 cut edges
python hv_core.py --text "..." --json                # JSON output

The model

Stage 1 — graph extraction

Sentence splitting. Claim extraction (one proposition per sentence). Discourse-first conclusion detection: a sentence starting with therefore, thus, hence, consequently, … is the conclusion. Fallback is the last sentence if it carries a recommendation marker (should, must, is indicated, …). Final fallback is the last sentence.

Structural edge generation:

Contradiction edges via antonym pairs.
Every prior claim → supports → conclusion.
Conclusion → implies → every subsequent claim.
Adjacency continuity edges between nearby non-conclusion claims when content-word Jaccard ≥ adjacency_overlap.

Stage 2 — density scoring

For each claim, density is the fraction of its content words that are novel relative to the union of its ancestors' content words, weighted by the fraction of rare words it carries:

d(v) = novelty(v | ancestors(v)) · (0.6 + 0.4 · rare_frac(v))

Stage 3 — flip search via min-cut

Robustness is the cheapest set of edges whose simultaneous removal disconnects the conclusion from every leaf premise. Computed by Edmonds–Karp on a flow network with:

edge capacities c(e) = d(u) + d(v) (spec prose: dense edges are expensive to sever)
a super-source connecting all leaf premises with infinite capacity
the conclusion connected to a super-sink with infinite capacity

Heuristic NLI

No transformer. Scoring combines content-word coverage, Jaccard overlap, antonym detection (a fixed lexicon), and negation mismatch.

Benchmarks

Sample texts

text	claims	edges	robustness	tier	cut
Medical (MI diagnosis)	7	6	7.335	strong	5
Science (black hole)	6	6	6.807	strong	5
Legal (contract breach)	6	5	4.542	strong	4
Weak argument (CEO stock)	4	3	3.027	medium	2

Reading the table:

Weak argument is the most fragile: two edges flip it.
Medical has five independent supports — the argument is multiply grounded.
Legal has four supports.
Science is the densest graph.

When to use it

Argument auditing — before acting on a memo, brief, or diagnosis.
Editing — find the sentence the argument rests on.
Peer review — flag conclusions that hinge on one weak claim.
Debate prep — find the cheapest attack on the other side.
Teaching — show students where an argument would break.

When not to use it

As ground truth. The NLI is heuristic. The densities are heuristic. The model ranks; it does not measure.
For non-English text. Lexicons and antonym pairs are English.
For symbolic or code-heavy text. Content-word novelty misses the structure of proofs and programs.
For very long documents. max_claims defaults to 64.

Honest limitations

The NLI is a bag-of-content-words heuristic. It will misclassify examples that depend on syntactic structure, quantifier scope, or discourse relations.
The antonym lexicon is hand-curated (~40 pairs). Real negation is broader.
Density is a novelty proxy, not compression. Real density needs a language model. This is the cheap version.
Short claims that introduce new vocabulary score high on novelty. A one-word claim ("Analysts agree") can outscore a longer one on density even when the longer one is intuitively load-bearing.
The flip set is a set, not a sequence. Every edge in the cut must be severed simultaneously. Severing any strict subset does not flip the conclusion.
Conclusion detection can fail on texts without an explicit conclusion. The model falls back to the last sentence and returns something regardless.

Reference

Part of the reader-model series. Companion to hv-tempo (pace variation), hv-ttu (total comprehension time), and hv-locality (feature-map locality).

hv-tempo answers where will the reader slow down? hv-core answers what is the minimal structural change that would invalidate this argument?

License

Apache-2.0

Downloads last month: -; Downloads are not tracked for this model. How to track