fix(sanitize): prose underscores + orphan $ from truncated LLM output

Real-run demo produced a 6-page PDF only after three manual fixes. Two
were systematic sanitize gaps; this commit closes both.

1. escape.py — _BARE_UNDERSCORE rule.
   The LLM writes Greek letter names as prose ("lambda and epsilon_target")
   instead of math ($\lambda$ and $\epsilon_{target}$). The prose escape
   pass handled %, &, <, > but not _. pdflatex then sees `_t` in text
   mode, tries to open a subscript, and bails with the misleading
   "Missing $ inserted". Added \_ escape with `(?<!\\)_(?!\{)` so
   already-escaped \_ and legitimate `_{...}` subscript-like forms
   (left as-is; the author can wrap in $ if they meant math) pass through.

2. sanitize/math_balance.py — drop orphan `$`.
   LLM truncates an inline equation mid-sentence: "...compare with $"
   immediately followed by \section{...}. The half-open math mode
   cascades into spurious "Missing $ inserted" errors pages later.
   New pass counts unescaped `$` outside display/tabular math blocks;
   if odd, drops the last one. Log-warns with offset so the author can
   fix the truncated prose by hand if they care.
   Wired into SANITIZE_PIPELINE BEFORE escape_prose_specials, because
   escape's math-segment scanner assumes balanced inline math.

Non-fix (documented): the third demo failure — a structurally mangled
equation with \emph{} inside math and malformed \frac — is an LLM
generation-quality problem, not something sanitize can recover from.
The existing log-driven retry pass already attempts that; stronger
retries belong in writeup.py, not here.

Tests: 15 new cases. Total suite now 58 passing.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: easyvibecoding

skills/hermes-sci/package/hermes_sci/sanitize/escape.py

@@ -41,6 +41,10 @@
 _BARE_LT = re.compile(r"(?<![\\$])<(?!=)(?=\s|\d|[A-Za-z])")
 _BARE_GT = re.compile(r"(?<![\\$])>(?!=)(?=\s|\d|[A-Za-z])")
 _BARE_AMP = re.compile(r"(?<!\\)&(?![A-Za-z]{2,6};)")
+# Prose underscores: `epsilon_target`, `file_name` → must be \_ or LaTeX tries
+# to open a subscript (which only works in math mode). Skip `\_` (already
+# escaped) and `_{...}` (common math-like usage the LLM forgot to wrap in $).
+_BARE_UNDERSCORE = re.compile(r"(?<!\\)_(?!\{)")
 
 
 def _unescape_table_amps(s: str) -> str:
@@ -55,6 +59,7 @@ def _escape_chunk(prose: str) -> str:
     prose = _BARE_AMP.sub(r"\\&", prose)
     prose = _BARE_LT.sub(r"$<$", prose)
     prose = _BARE_GT.sub(r"$>$", prose)
+    prose = _BARE_UNDERSCORE.sub(r"\\_", prose)
     return prose
 
 

skills/hermes-sci/package/hermes_sci/sanitize/math_balance.py

@@ -0,0 +1,67 @@
+"""Drop orphan `$` signs left behind by truncated LLM output.
+
+Failure mode this targets: MiniMax / any LLM sometimes truncates an inline
+equation mid-sentence, e.g.
+
+    We compare against the ensemble variant with $
+
+followed immediately by `\\section{Experiments}`. The unmatched `$` opens
+math mode that never closes, so pdflatex fails with "Missing $ inserted"
+anywhere downstream — producing a cascade of misleading errors.
+
+We can't reliably guess what the LLM intended to write, so we don't try to
+reconstruct the equation. We drop the orphan instead: outside a section the
+unclosed `$` is unsalvageable prose anyway, and leaving it breaks the whole
+paper. A logged warning surfaces the event so the author can fix the prose
+by hand if they care about that sentence.
+
+Scope: only considers `$` that are NOT inside a display-math or tabular
+environment (those match as a whole via _MATH_BLOCK below and are preserved
+verbatim). Paired `$...$` inline math is fine — we remove only the last
+unmatched `$` when the count is odd.
+"""
+from __future__ import annotations
+
+import logging
+import re
+
+log = logging.getLogger("hermes_sci.sanitize.math_balance")
+
+# Display / block math environments whose internal `$` we must NOT count.
+_MATH_BLOCK = re.compile(
+    r"\\begin\{equation\*?\}.*?\\end\{equation\*?\}"
+    r"|\\begin\{align\*?\}.*?\\end\{align\*?\}"
+    r"|\\begin\{gather\*?\}.*?\\end\{gather\*?\}"
+    r"|\\begin\{multline\*?\}.*?\\end\{multline\*?\}"
+    r"|\\begin\{tabular\*?\}.*?\\end\{tabular\*?\}"
+    r"|\\begin\{array\}.*?\\end\{array\}"
+    r"|\\\[.*?\\\]"
+    r"|\$\$.*?\$\$",
+    re.DOTALL,
+)
+
+# Escaped dollar (literal `$` character) — already fine, must be ignored by
+# the counter. Matches `\$`.
+_ESCAPED_DOLLAR = re.compile(r"\\\$")
+
+
+def balance_inline_math(s: str) -> str:
+    """If the prose section has an odd number of unescaped `$`, drop the
+    last one. Returns input unchanged when already balanced.
+    """
+    # Black out regions the scanner must ignore: math blocks + literal \$.
+    blanked = _MATH_BLOCK.sub(lambda m: " " * len(m.group(0)), s)
+    blanked = _ESCAPED_DOLLAR.sub("  ", blanked)
+
+    dollar_positions = [i for i, ch in enumerate(blanked) if ch == "$"]
+    if len(dollar_positions) % 2 == 0:
+        return s
+
+    # Odd count → drop the LAST unpaired `$`. Heuristic: most LLM-truncation
+    # cases leave the stray `$` at the very end of a sentence. Dropping the
+    # last occurrence recovers the balanced state and preserves any earlier
+    # `$x$` pairs the author did finish.
+    last = dollar_positions[-1]
+    log.warning("dropping orphan $ at offset %d (odd count = %d)",
+                last, len(dollar_positions))
+    return s[:last] + s[last + 1:]

skills/hermes-sci/package/hermes_sci/sanitize/pipeline.py

@@ -9,7 +9,9 @@
   5. markdown → LaTeX (bold / italic / heading)
   6. strip bad \\input \\include
   7. wrap lonely \\item
-  8. escape prose specials (%, &, <, >) — runs last so earlier passes'
+  8. balance inline math — drop orphan `$` from truncated LLM output
+     BEFORE the escape pass, whose math-segment scanner assumes balanced `$`
+  9. escape prose specials (%, &, <, >, _) — runs last so earlier passes'
      output is also escaped
 
 To add a pass: write a module with a `str → str` function, append to
@@ -26,6 +28,7 @@
 from .fences import strip_code_fences
 from .items import wrap_lonely_items
 from .markdown import md_to_latex
+from .math_balance import balance_inline_math
 from .packages import apply_package_fallbacks
 from .reasoning import strip_reasoning
 
@@ -39,6 +42,7 @@
     md_to_latex,
     strip_bad_commands,
     wrap_lonely_items,
+    balance_inline_math,
     escape_prose_specials,
 ]
 

skills/hermes-sci/package/tests/test_escape_underscore.py

@@ -0,0 +1,70 @@
+"""Prose-level underscore escape.
+
+Regression for the demo paper pipeline run where the LLM wrote
+`(lambda and epsilon_target)` in running prose. Unescaped `_` outside
+math mode makes pdflatex emit "Missing $ inserted" and bail.
+"""
+from __future__ import annotations
+
+from hermes_sci.sanitize.escape import escape_prose_specials
+
+
+def test_prose_underscore_escaped():
+    src = "hyperparameters (lambda and epsilon_target) require tuning"
+    out = escape_prose_specials(src)
+    assert r"epsilon\_target" in out
+    assert "epsilon_target" not in out.replace(r"\_", "@")
+
+
+def test_inline_math_underscores_preserved():
+    src = r"the threshold $\epsilon_{target}$ is set to $x_1$"
+    out = escape_prose_specials(src)
+    # Everything inside $...$ survives untouched.
+    assert r"$\epsilon_{target}$" in out
+    assert r"$x_1$" in out
+
+
+def test_display_math_underscores_preserved():
+    src = (
+        r"See eq:" "\n"
+        r"\begin{equation}" "\n"
+        r"  f(x) = w_i^\top x_1" "\n"
+        r"\end{equation}" "\n"
+        r"end."
+    )
+    out = escape_prose_specials(src)
+    assert "w_i^\\top x_1" in out  # untouched inside equation
+    assert out.endswith("end.")
+
+
+def test_already_escaped_underscore_untouched():
+    src = r"see file\_name for details"
+    out = escape_prose_specials(src)
+    assert out == src
+
+
+def test_subscript_like_underscore_in_prose_kept_raw():
+    r"""`word_{sub}` in prose probably means the LLM forgot `$...$`.
+    We leave it alone — escaping to `word\_{sub}` would look worse, and
+    `_{` is almost always followed by math content; the author can fix
+    the math-mode wrapping themselves. Documented behavior, not an oversight.
+    """
+    src = r"the term x_{target} appears unescaped"
+    out = escape_prose_specials(src)
+    # `_{` is NOT escaped — regex requires lookahead `(?!\{)`.
+    assert r"x_{target}" in out
+
+
+def test_underscore_in_textbf_argument_escaped():
+    src = r"\textbf{epsilon_target} is our hyperparam"
+    out = escape_prose_specials(src)
+    assert r"\textbf{epsilon\_target}" in out
+
+
+def test_all_prose_specials_together():
+    src = "100% improvement in R&D; compare A<B, use file_name for x>y"
+    out = escape_prose_specials(src)
+    assert r"100\%" in out
+    assert r"R\&D" in out
+    assert r"file\_name" in out
+    assert "$<$" in out and "$>$" in out

skills/hermes-sci/package/tests/test_math_balance.py

@@ -0,0 +1,74 @@
+"""Orphan `$` detection & removal.
+
+Regression for the demo paper run where MiniMax truncated an inline
+equation mid-sentence (`with $` followed by `\\section{...}`), leaving an
+unclosed math mode that crashed pdflatex with a misleading error pointing
+far downstream.
+"""
+from __future__ import annotations
+
+from hermes_sci.sanitize.math_balance import balance_inline_math
+
+
+def test_balanced_inline_math_unchanged():
+    src = r"we set $x = 1$ and $y = 2$; done."
+    assert balance_inline_math(src) == src
+
+
+def test_no_math_unchanged():
+    src = "plain text with no dollar signs at all."
+    assert balance_inline_math(src) == src
+
+
+def test_orphan_dollar_at_sentence_end_dropped():
+    src = "We compare against the ensemble variant with $\n\n\\section{Experiments}"
+    out = balance_inline_math(src)
+    assert "$" not in out
+    assert r"\section{Experiments}" in out
+
+
+def test_orphan_dollar_preserves_earlier_balanced_pair():
+    src = r"we have $x=1$ and later a stray $ appears."
+    out = balance_inline_math(src)
+    # Earlier balanced `$x=1$` must survive.
+    assert "$x=1$" in out
+    # Stray one removed.
+    assert out.count("$") == 2
+
+
+def test_display_math_ignored_by_counter():
+    src = (
+        r"prose $x$ more." "\n"
+        r"\begin{equation}" "\n"
+        r"a = b" "\n"
+        r"\end{equation}" "\n"
+        r"\[ c = d \]" "\n"
+        r"final."
+    )
+    # Two `$` in prose (balanced) + `$$` inside display shouldn't confuse us.
+    assert balance_inline_math(src) == src
+
+
+def test_escaped_dollar_ignored():
+    src = r"literal \$100 sign and paired $x$ — balanced."
+    # `\$` is a LaTeX literal dollar, must not be counted as inline-math delim.
+    assert balance_inline_math(src) == src
+
+
+def test_triple_dollar_in_prose_drops_last():
+    src = "three stray $ dollars $ in $ a row"
+    out = balance_inline_math(src)
+    assert out.count("$") == 2  # one removed → even count restored
+
+
+def test_dollar_inside_display_math_does_not_mask_prose_orphan():
+    """A bare `$` in prose + a self-contained display-math block
+    should still detect the prose `$` as orphan."""
+    src = (
+        r"prose $ orphan here." "\n"
+        r"\begin{equation}" "\n"
+        r"x + y = z" "\n"
+        r"\end{equation}"
+    )
+    out = balance_inline_math(src)
+    assert "$" not in out.split(r"\begin{equation}")[0]