| --- |
| license: apache-2.0 |
| library_name: numpy |
| tags: |
| - argument-mining |
| - argument-graph |
| - robustness |
| - interpretability |
| - nli |
| - heuristic |
| - cpu |
| pipeline_tag: text-classification |
| --- |
| |
| # 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 |
| |
| ```bash |
| 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 |
| |
| ```bash |
| 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**: |
| |
| 1. Contradiction edges via antonym pairs. |
| 2. Every prior claim β `supports` β conclusion. |
| 3. Conclusion β `implies` β every subsequent claim. |
| 4. 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 |
