Stage_V_0 Path D serve: upload training/citation_utils_v5.py

training/citation_utils_v5.py

@@ -0,0 +1,125 @@
+"""Multiplicity-preserving citation guard — v5 wrapper layer.
+
+Spec: ``humanizer-v5-detector-in-the-loop`` (R9.3, R11, R13.1).
+
+Why this module exists
+----------------------
+R9.3 / design Property 3 require the Citation_Preservation_Guard to be
+*multiplicity-preserving*: a citation pattern that appears ``N`` times in the
+input MUST appear at least ``N`` times in the output, otherwise the check fails.
+"Single-instance preservation MUST NOT be accepted as multi-instance
+preservation."
+
+The shipped predicate
+:func:`training.data.citation_utils.passes_citation_check` does **not** enforce
+this. Its ``missing_citations`` helper contains a substring fallback
+(``if citation in ai_text: continue``) that only flags a citation as missing
+when its output count drops to **zero**. Consequently a reduction such as
+``(Müller 2019)`` appearing 2× in the input but 1× in the output is wrongly
+accepted (returns ``True`` where R9.3 requires ``False``). This was confirmed by
+property test P3.
+
+``training/data/citation_utils.py`` is R11/R13.1-protected and MUST NOT be
+modified. This module is therefore a **thin wrapper** that reuses
+:func:`extract_citations` (import-only — the multiplicity-correct primitive) and
+re-derives the predicate with strict per-citation count comparison via
+:class:`collections.Counter`. No logic is copied from the protected module and
+the protected module is left byte-for-byte unchanged.
+
+Exports
+-------
+- ``passes_citation_check_v5``: strict, multiplicity-preserving predicate
+  (drop-in replacement for ``passes_citation_check`` with an identical
+  ``(human_text, ai_text) -> bool`` contract).
+- ``missing_citations_v5``: citations under-represented in the output, with
+  multiplicity, for diagnostics/logging.
+"""
+
+from __future__ import annotations
+
+from collections import Counter
+
+# Import-only reuse of the multiplicity-correct extraction primitive from the
+# R11/R13.1-protected module. We deliberately do NOT import
+# ``passes_citation_check`` / ``missing_citations`` (the non-multiplicity-aware
+# predicates) — only the raw ``extract_citations`` building block.
+from training.data.citation_utils import extract_citations
+
+__all__ = [
+    "missing_citations_v5",
+    "passes_citation_check_v5",
+]
+
+
+def missing_citations_v5(human_text: str, ai_text: str) -> list[str]:
+    """Return citations under-represented in *ai_text*, counted with multiplicity.
+
+    A citation is "under-represented" when it appears fewer times in *ai_text*
+    than in *human_text*. The shortfall is reported with multiplicity: if a
+    citation occurs 3× in *human_text* and 1× in *ai_text*, it appears twice in
+    the result (the two unmatched occurrences). Output order follows the order
+    of first appearance in *human_text*.
+
+    Unlike :func:`training.data.citation_utils.missing_citations`, there is no
+    substring fallback: presence is measured strictly by *count* of regex
+    matches, so a reduced-but-present citation is correctly reported as missing.
+
+    Parameters
+    ----------
+    human_text:
+        Source text whose citations must all be reproduced.
+    ai_text:
+        Candidate text that should preserve every citation from *human_text*
+        with at least the same multiplicity.
+
+    Returns
+    -------
+    list[str]
+        Citations missing from *ai_text*, with multiplicity. Empty when every
+        citation appears in *ai_text* at least as many times as in *human_text*.
+    """
+    human_counts = Counter(extract_citations(human_text))
+    if not human_counts:
+        return []
+
+    ai_counts = Counter(extract_citations(ai_text))
+
+    missing: list[str] = []
+    # Preserve first-appearance order from the human text for stable diagnostics.
+    for citation in extract_citations(human_text):
+        shortfall = human_counts[citation] - ai_counts.get(citation, 0)
+        if shortfall > 0:
+            missing.append(citation)
+            # Decrement so each of the `shortfall` unmatched occurrences is
+            # reported exactly once as we walk the human-text occurrences.
+            human_counts[citation] -= 1
+            ai_counts[citation] = ai_counts.get(citation, 0)  # no-op clarity
+    return missing
+
+
+def passes_citation_check_v5(human_text: str, ai_text: str) -> bool:
+    """Return ``True`` iff every citation's count in *ai_text* is >= its count in *human_text*.
+
+    This is the strict, multiplicity-preserving form of the
+    Citation_Preservation_Guard required by R9.3 / design Property 3. It is a
+    drop-in replacement for
+    :func:`training.data.citation_utils.passes_citation_check`: same
+    ``(human_text, ai_text) -> bool`` signature and accept/reject contract, but
+    it rejects records where any citation's multiplicity is reduced — including
+    the reduced-but-present case (e.g. 2× → 1×) that the original wrongly
+    accepts.
+
+    Parameters
+    ----------
+    human_text:
+        Source text whose citations must all be preserved.
+    ai_text:
+        Candidate AI paraphrase.
+
+    Returns
+    -------
+    bool
+        ``True`` when no citation is under-represented in *ai_text*, ``False``
+        otherwise. An increased count in *ai_text* still passes.
+    """
+    return not missing_citations_v5(human_text, ai_text)