reference-audit 0.1.0__py3-none-any.whl

reference_audit/parsing/latex.py

@@ -0,0 +1,83 @@
+r"""LaTeX markup in `.bib` field values → plain Unicode text.
+
+bibtexparser 2 decodes no LaTeX itself (its `LatexDecodingMiddleware` is a thin pylatexenc wrapper).
+Its default decoder reads a field value as a LaTeX *document*, which a BibTeX value is not:
+
+* a bare `%` starts a comment, so `https://x.org/a%20b` loses everything after `a`;
+* `&` is a table column separator, so `d'Amore` becomes `d   apos;Amore` and the HTML reference
+  can no longer be decoded (`parsing.entities`);
+* `~` is a non-breaking space, so `https://x.org/~user` is corrupted;
+* `--`, `---`, ``` `` ``` and `''` become typographic dashes and quotes, so `pages = {65--92}`
+  reads `65–92`.
+
+Here those characters are literal: `%` is escaped before parsing and the context has no "specials".
+What is decoded is the markup that changes how a reference reads in a database: accents
+(`{\'e}` → é, `\"{o}` → ö, `\ss` → ß), text-mode macros (`\textit{Deep}` → Deep, `\&` → &,
+`\url{x}` → x, `\href{x}{X}` → `X <x>`) and symbols inside math (`$\alpha$` → `$α$`).
+"""
+
+from __future__ import annotations
+
+import re
+
+from pylatexenc import latexwalker
+from pylatexenc.latex2text import LatexNodes2Text, MacroTextSpec, get_default_latex_context_db
+from pylatexenc.macrospec import LatexContextDb, MacroSpec
+
+# A `%` that is not already escaped as `\%`.
+_BARE_PERCENT_RE = re.compile(r"(?<!\\)%")
+
+
+class LatexDecodeError(ValueError):
+    """pylatexenc failed on a value; the field cannot be read as text."""
+
+
+def _text_context() -> LatexContextDb:
+    """pylatexenc's default macro → text rules, without its specials (`&`, `~`, `--`, quotes)."""
+    base = get_default_latex_context_db()
+    db = LatexContextDb()
+    # `\url{x}` is the URL itself, not pylatexenc's `<x>`.
+    db.add_context_category("bibtex", macros=[MacroTextSpec("url", simplify_repl="%s")])
+    for cat in base.categories():
+        db.add_context_category(
+            cat,
+            macros=list(base.iter_macro_specs([cat])),
+            environments=list(base.iter_environment_specs([cat])),
+        )
+    db.set_unknown_macro_spec(base.unknown_macro_spec)
+    db.set_unknown_environment_spec(base.unknown_environment_spec)
+    return db
+
+
+def _parse_context() -> LatexContextDb:
+    """The walker's default argument specs, plus `\\href{url}{text}`, which it does not know.
+
+    Without it `\\href` is parsed with no arguments and its text rule raises an `IndexError`.
+    """
+    db = latexwalker.get_default_latex_context_db()
+    db.add_context_category("bibtex", prepend=True, macros=[MacroSpec("href", "{{")])
+    return db
+
+
+_TEXT = LatexNodes2Text(
+    latex_context=_text_context(), math_mode="with-delimiters", keep_braced_groups=False
+)
+_PARSE_CONTEXT = _parse_context()
+
+
+def decode_latex(value: str) -> str:
+    """`value` with its LaTeX markup decoded to Unicode; `%`, `&`, `~` and dashes stay literal.
+
+    Raises `LatexDecodeError` when pylatexenc fails on the value.
+    """
+    if "\\" not in value and "{" not in value and "$" not in value:
+        return value
+    escaped = _BARE_PERCENT_RE.sub(r"\\%", value)
+    try:
+        walker = latexwalker.LatexWalker(
+            escaped, latex_context=_PARSE_CONTEXT, tolerant_parsing=True
+        )
+        nodes, _, _ = walker.get_latex_nodes()
+        return _TEXT.nodelist_to_text(nodes)
+    except Exception as e:  # noqa: BLE001 — any pylatexenc failure means the value is unreadable
+        raise LatexDecodeError(f"{type(e).__name__}: {e}") from e

reference_audit/parsing/tex.py

@@ -0,0 +1,159 @@
+"""LaTeX citation extraction.
+
+`strip_comments`/`strip_verbatim` are lifted from `sciwrite-lint/tex_parser.py`. We extend
+cite extraction to include `\\nocite` (chan2019lenia is nocite-only in the pilot) and to
+resolve `\\input`/`\\include` so multi-file manuscripts aren't miscounted.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+from reference_audit.models import CitationContext
+from reference_audit.parsing.context import MIN_CONTEXT_CHARS, collapse, sentence_span
+
+_VERBATIM_ENVS = ("lstlisting", "verbatim", "minted", "Verbatim", "alltt")
+_VERBATIM_RE = re.compile(
+    r"\\begin\{(" + "|".join(re.escape(e) for e in _VERBATIM_ENVS) + r")\}.*?\\end\{\1\}",
+    re.DOTALL,
+)
+_VERB_INLINE_RE = re.compile(r"\\verb(.)(.*?)\1")
+
+# \cite, \citep, \citet, \citeyearpar, \citeauthor, \citealt, \citealp, \nocite, ...
+_CITE_RE = re.compile(r"\\(?:no)?cite[a-zA-Z]*\s*(?:\[[^\]]*\])*\s*\{([^}]*)\}")
+_NOCITE_RE = re.compile(r"\\nocite\s*\{([^}]*)\}")
+_INPUT_RE = re.compile(r"\\(?:input|include)\s*\{([^}]+)\}")
+
+# Same as _CITE_RE but capturing the command name and (optional) pre/post bracket args, so context
+# extraction can name the command and skip \nocite (which carries no citing prose).
+_CITE_CMD_RE = re.compile(
+    r"\\(?P<cmd>(?:no)?cite[a-zA-Z]*)\s*(?:\[[^\]]*\])*\s*\{(?P<keys>[^}]*)\}"
+)
+_LATEX_CMD_RE = re.compile(r"\\[a-zA-Z]+\*?")
+
+
+def strip_comments(text: str) -> str:
+    r"""Remove LaTeX comments (% to end of line), preserving escaped \%."""
+    out_lines: list[str] = []
+    for line in text.split("\n"):
+        buf: list[str] = []
+        i = 0
+        while i < len(line):
+            if line[i] == "%" and (i == 0 or line[i - 1] != "\\"):
+                break
+            buf.append(line[i])
+            i += 1
+        out_lines.append("".join(buf))
+    return "\n".join(out_lines)
+
+
+def strip_verbatim(text: str) -> str:
+    r"""Blank verbatim-like environments and inline \verb|...| (so cites inside code don't count)."""
+    text = _VERBATIM_RE.sub(lambda m: "\n" * m.group(0).count("\n"), text)
+    text = _VERB_INLINE_RE.sub("", text)
+    return text
+
+
+def _resolve_input(name: str, base_dir: Path) -> Path | None:
+    candidate = (base_dir / name).expanduser()
+    for p in (candidate, candidate.with_suffix(".tex")):
+        if p.suffix == "":
+            p = p.with_suffix(".tex")
+        if p.is_file():
+            return p
+    return None
+
+
+def _read_with_includes(path: Path, seen: set[Path], missing: list[str]) -> str:
+    """Concatenate a tex file with its \\input/\\include targets (depth-first, cycle-safe).
+
+    Unresolved include targets are appended to `missing` so the caller can warn that
+    citation coverage is incomplete.
+    """
+    path = path.resolve()
+    if path in seen or not path.is_file():
+        return ""
+    seen.add(path)
+    text = path.read_text(encoding="utf-8", errors="replace")
+    text = strip_comments(text)  # strip before resolving includes (commented \input ignored)
+
+    def _expand(m: re.Match[str]) -> str:
+        name = m.group(1).strip()
+        target = _resolve_input(name, path.parent)
+        if target is None:
+            missing.append(name)
+            return ""
+        return _read_with_includes(target, seen, missing)
+
+    return _INPUT_RE.sub(_expand, text)
+
+
+def parse_cited_keys(tex_path: str | Path) -> tuple[set[str], bool, list[str]]:
+    """Return (cited_keys, nocite_star, missing_includes).
+
+    `cited_keys` is the union of all `\\cite*` and `\\nocite` keys across the main file and
+    its resolvable includes. `nocite_star` is True if `\\nocite{*}` appears (cite-everything).
+    `missing_includes` lists `\\input`/`\\include` targets that could not be found on disk.
+    """
+    path = Path(tex_path)
+    missing: list[str] = []
+    text = _read_with_includes(path, set(), missing)
+    text = strip_verbatim(text)
+
+    nocite_star = bool(re.search(r"\\nocite\s*\{\s*\*\s*\}", text))
+
+    keys: set[str] = set()
+    for m in _CITE_RE.finditer(text):
+        for raw in m.group(1).split(","):
+            key = raw.strip()
+            if key and key != "*":
+                keys.add(key)
+    return keys, nocite_star, sorted(set(missing))
+
+
+def _clean_context(span: str) -> str:
+    """Strip LaTeX noise from a raw sentence span so what remains is the readable citing claim:
+    drop the cite macros entirely, strip other `\\command` control words (keeping their braced
+    argument *text*), and collapse braces/ties/whitespace."""
+    span = _CITE_CMD_RE.sub(" ", span)     # the citation macro is not part of the claim
+    span = _LATEX_CMD_RE.sub(" ", span)    # \emph, \textbf, ... — keep the argument text, drop the name
+    span = span.replace("{", " ").replace("}", " ").replace("~", " ").replace("\\", " ")
+    return collapse(span)
+
+
+def parse_citation_contexts(tex_path: str | Path) -> dict[str, list[CitationContext]]:
+    """Per-key citing contexts: the sentence(s) around each `\\cite`-family occurrence — the *reason*
+    each work is cited — extracted offline from the `.tex` and its resolvable includes.
+
+    `\\nocite` is skipped (it carries no citing prose). A key cited several times yields several
+    contexts, each with a 0-based `ordinal` in document order. When a citation's own sentence is too
+    short to carry a claim (a bare trailing cite), the preceding sentence is folded in. Keys sharing
+    one sentence each get that whole sentence (v1 is sentence-granular, not clause-granular).
+    """
+    path = Path(tex_path)
+    text = _read_with_includes(path, set(), [])
+    text = strip_verbatim(text)
+
+    contexts: dict[str, list[CitationContext]] = {}
+    counts: dict[str, int] = {}
+    for m in _CITE_CMD_RE.finditer(text):
+        cmd = m.group("cmd")
+        if cmd.startswith("nocite"):
+            continue
+        left, right = sentence_span(text, m.start(), m.end())
+        cleaned = _clean_context(text[left:right])
+        if len(cleaned) < MIN_CONTEXT_CHARS:
+            # fold in the preceding sentence so there is an actual claim to judge
+            prev_left, _ = sentence_span(text, max(left - 2, 0), max(left - 1, 0))
+            cleaned = _clean_context(text[prev_left:right])
+        for raw in m.group("keys").split(","):
+            key = raw.strip()
+            if not key or key == "*":
+                continue
+            ordinal = counts.get(key, 0)
+            counts[key] = ordinal + 1
+            contexts.setdefault(key, []).append(
+                CitationContext(key=key, text=cleaned, ordinal=ordinal, command=cmd)
+            )
+    return contexts

reference_audit/pdf/__init__.py

@@ -0,0 +1,16 @@
+"""PDF input: GROBID turns a PDF into TEI XML, and a pure mapper turns that TEI into the same
+models the `.bib`/`.tex` front end produces.
+
+The split is deliberate and is enforced by `cpt-referenceaudit-constraint-no-network-parse`:
+
+* `pdf.grobid` — the ONLY module here that performs network I/O. It talks to one operator-supplied GROBID
+  service and nothing else.
+* `pdf.tei` — pure. Given the TEI text it returns `BibEntry` and `CitationContext` records, so
+  extraction correctness is verifiable offline from recorded TEI, exactly as the source adapters are
+  verified from recorded responses.
+
+`pdf.embedded` reads a PDF that carries the BibTeX records of its cited works (the AI4X template
+makes such PDFs); then neither GROBID nor `pdf.tei` is involved. It reads the local file only.
+
+`parsing` must not import `pdf.grobid`.
+"""

reference_audit/pdf/embedded.py

@@ -0,0 +1,117 @@
+r"""BibTeX records that a PDF carries for its own references.
+
+A conference template can make the PDF carry the authored records of its cited works, so that they
+are read rather than re-extracted from the typeset text. The AI4X template does: its bibliography
+style (`ai4x.bst`) writes each cited entry's BibTeX record into the `.bbl`, and its class embeds them
+as the PDF attachment `cited-references.bib.hex`:
+
+* only the cited entries (BibTeX sees nothing else), in the printed order;
+* only the fields printed in the reference list plus identifiers (DOI, ISBN, arXiv id, …), with
+  `@string` macros and `crossref` already resolved by BibTeX;
+* hex-encoded, because the records pass through TeX on the way to the attachment and a raw `%`, `#`
+  or `\` in a field would break it. Whitespace is insignificant: BibTeX and TeX wrap the lines.
+
+The records are what the author compiled, not necessarily what is printed — a hand-edited `.bbl`
+can make them differ — so `title_printed` compares each one with the PDF's reference list.
+
+Local file I/O only: nothing here touches the network.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from pathlib import Path
+
+from anyascii import anyascii
+from pypdf import PdfReader
+
+ATTACHMENT_NAME = "cited-references.bib.hex"
+
+# The last heading of the reference list; the text after it is what the titles are looked up in.
+_REFERENCES_HEADING_RE = re.compile(r"(?im)^\s*(?:references|bibliography)\s*$")
+# What breaks a title into separately-checked segments: math, LaTeX commands, escaped characters.
+_TITLE_BREAK_RE = re.compile(r"\$[^$]*\$|\\[a-zA-Z]+\*?|\\.")
+# A title segment shorter than this is too unspecific to look up.
+_MIN_SEGMENT_LETTERS = 4
+
+
+@dataclass(frozen=True)
+class EmbeddedReferences:
+    """The outcome of looking for the attachment.
+
+    `bib_text` is the decoded `.bib`, or None. `problem` says why there is none when that is not the
+    ordinary case of a PDF without the attachment: the PDF could not be read, or the attachment is
+    malformed. Either way the caller falls back to extracting the references, and reports `problem`.
+    """
+
+    bib_text: str | None = None
+    problem: str | None = None
+
+
+def read_embedded_references(pdf_path: str | Path) -> EmbeddedReferences:
+    """Find and decode the `cited-references.bib.hex` attachment of a PDF."""
+    path = Path(pdf_path)
+    try:
+        attachments = PdfReader(path).attachments
+        payloads = attachments.get(ATTACHMENT_NAME, [])
+    except Exception as exc:  # noqa: BLE001 — pypdf raises many types for a damaged PDF
+        return EmbeddedReferences(
+            problem=f"could not look for embedded BibTeX records in {path.name}: "
+            f"{type(exc).__name__}: {exc}"
+        )
+    if not payloads:
+        return EmbeddedReferences()
+    if len(payloads) > 1:
+        return EmbeddedReferences(
+            problem=f"{path.name} embeds {len(payloads)} attachments named {ATTACHMENT_NAME}, so it "
+            "is ambiguous which holds the references"
+        )
+    try:
+        return EmbeddedReferences(bib_text=decode_hex_payload(payloads[0]))
+    except ValueError as exc:
+        return EmbeddedReferences(problem=f"the {ATTACHMENT_NAME} attachment of {path.name} {exc}")
+
+
+def decode_hex_payload(payload: bytes) -> str:
+    """Hex with arbitrary whitespace → text. Raises ValueError (worded as a predicate) if malformed."""
+    digits = re.sub(rb"\s+", b"", payload)
+    if not digits:
+        raise ValueError("is empty")
+    if re.fullmatch(rb"[0-9a-fA-F]+", digits) is None:
+        raise ValueError("is not hex-encoded")
+    if len(digits) % 2:
+        raise ValueError("has an odd number of hex digits (truncated)")
+    # A .bib in another encoding still parses; the replaced bytes are what `parse_bib` would get too.
+    return bytes.fromhex(digits.decode("ascii")).decode("utf-8", errors="replace")
+
+
+def reference_list_text(pdf_path: str | Path) -> str:
+    """The PDF's text after its last References/Bibliography heading (all of it, if there is none).
+
+    Raises whatever pypdf raises when the text cannot be extracted; the caller reports it.
+    """
+    reader = PdfReader(Path(pdf_path))
+    text = "\n".join(page.extract_text() or "" for page in reader.pages)
+    headings = list(_REFERENCES_HEADING_RE.finditer(text))
+    return text[headings[-1].end():] if headings else text
+
+
+def _letters(text: str) -> str:
+    """Lower-case ASCII letters only: hyphenation, line breaks, ligatures and accents fall away."""
+    return re.sub(r"[^a-z]", "", anyascii(text).lower())
+
+
+def title_printed(title: str, printed_text: str) -> bool | None:
+    """Whether an embedded record's title appears in the printed reference list.
+
+    The title is split at math and LaTeX commands, whose typeset form differs from the source, and
+    every remaining segment must appear in the printed text. None when no segment is long enough to
+    be looked up — a title like "$\\alpha$" cannot be checked this way.
+    """
+    printed = _letters(printed_text)
+    segments = [s for s in map(_letters, _TITLE_BREAK_RE.split(title))
+                if len(s) >= _MIN_SEGMENT_LETTERS]
+    if not segments:
+        return None
+    return all(s in printed for s in segments)

reference_audit/pdf/grobid.py

@@ -0,0 +1,234 @@
+"""GROBID client: PDF → TEI XML. The only module in this package that performs I/O.
+
+GROBID is an external service this package does NOT manage. `AuditConfig.grobid_url` points at an
+operator-supplied instance (a local container by default); if it is not answering, that is reported
+with the command to start it — never worked around, and never allowed to degrade into an empty
+reference list.
+
+Modeled on `inspirations/sciwrite-lint/sciwrite_lint/pdf/grobid.py`, with three deliberate
+divergences documented at their call sites: no `consolidateCitations`, no module-global client or
+health cache, and no PDF-producer blacklist in the failure diagnosis.
+"""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+from pathlib import Path
+
+import httpx
+from loguru import logger
+
+from reference_audit.sources.http import (
+    DEFAULT_USER_AGENT,
+    TransientHTTPError,
+    is_transient_status,
+    post_multipart,
+)
+
+GROBID_IMAGE = "docker.io/grobid/grobid:0.9.1-crf"
+GROBID_START_HINT = (
+    # `--replace` swaps out an existing `grobid` container, e.g. one left from an older image.
+    f"podman run -d --replace --name grobid -p 8070:8070 {GROBID_IMAGE}\n"
+    "  (first start takes ~30 s while the models load; then re-run this command)"
+)
+
+FULLTEXT_ENDPOINT = "/api/processFulltextDocument"
+ALIVE_ENDPOINT = "/api/isalive"
+
+# Pinned request parameters. These are part of the extraction contract, not tuning knobs: the
+# committed TEI fixtures and the TEI mapper both depend on them, and `tests/pdf_fixtures.py` asserts
+# it sends the same set.
+#
+# `consolidateCitations=0` is the load-bearing one. With `1` (which the sciwrite-lint client uses)
+# GROBID looks each reference up in Crossref and REWRITES it with the matched canonical record. That
+# would silently repair the exact defect this tool exists to detect — a garbled or hallucinated
+# reference would arrive already corrected — and would smuggle a third-party network dependency into
+# what is otherwise a call to a local service.
+#
+# `includeRawCitations=1` keeps `<note type="raw_reference">`, which is how a reference GROBID could
+# not structure is still reported to a human instead of appearing as a blank record.
+FULLTEXT_PARAMS = {
+    "consolidateHeader": "0",
+    "consolidateCitations": "0",
+    "includeRawCitations": "1",
+}
+
+_ALIVE_TIMEOUT = 5.0
+# GROBID throughput is roughly 1-3 MB/s and slower under concurrent load, so the timeout scales with
+# document size rather than being a flat ceiling that a large report would always trip: a base budget
+# plus a per-megabyte allowance, capped so we refuse to wait indefinitely.
+_TIMEOUT_BASE_S = 60.0
+_TIMEOUT_PER_MB_S = 10.0
+_TIMEOUT_CEILING_S = 600.0
+
+# Markers GROBID puts in a 500 body when it ran fine but could not parse THIS document.
+_UNPARSEABLE_MARKERS = ("NO_BLOCKS", "empty content", "no text", "could not parse")
+
+
+class GrobidError(RuntimeError):
+    """The PDF could not be turned into a reference list. Always fatal for the run.
+
+    There is no partial result to fall back to: without TEI there are no records to process
+    independently, so this is the one place where a failure is whole-run rather than per-record.
+    """
+
+
+class GrobidUnavailableError(GrobidError):
+    """The GROBID service is not answering at all."""
+
+
+class GrobidRequestError(GrobidError):
+    """GROBID answered, but with an error we could not get past (5xx/transport after retries)."""
+
+
+class PdfUnparseableError(GrobidError):
+    """GROBID is healthy but cannot parse *this* PDF (image-only, or unrecognizable structure).
+
+    Kept distinct from `GrobidRequestError` so the message tells the user to fix the input rather
+    than the service, and so it is never retried — the PDF will not become parseable.
+    """
+
+    def __init__(self, pdf_name: str, reason: str) -> None:
+        super().__init__(f"cannot parse {pdf_name}: {reason}")
+        self.pdf_name = pdf_name
+        self.reason = reason
+
+
+def _timeout_for(pdf_bytes: int) -> float:
+    size_mb = pdf_bytes / (1024 * 1024)
+    return min(_TIMEOUT_CEILING_S, _TIMEOUT_BASE_S + _TIMEOUT_PER_MB_S * size_mb)
+
+
+def _is_unparseable_body(body: str) -> bool:
+    lowered = body.lower()
+    return any(marker.lower() in lowered for marker in _UNPARSEABLE_MARKERS)
+
+
+def _diagnose_unparseable(pdf_path: Path) -> str:
+    """Explain WHY a PDF is unparseable, or say plainly that we cannot tell.
+
+    Only one probe: whether there is a text layer at all. `pdftotext` is a poppler tool GROBID itself
+    depends on, but it is not a declared dependency here, so its absence is reported rather than
+    silently skipped.
+
+    The sciwrite-lint original also flags "known-problematic producers" (CorelDRAW, Preview, Quartz).
+    That is deliberately not copied: a producer name correlates with, but does not establish, an
+    unparseable structure, and reporting a guess as a diagnosis is exactly the incomplete-guess
+    behavior this project forbids.
+    """
+    if not shutil.which("pdftotext"):
+        return (
+            "GROBID does not recognize this PDF's structure; the specific reason could not be "
+            "determined (install poppler-utils' pdftotext for a text-layer diagnosis)"
+        )
+    try:
+        text = subprocess.run(
+            ["pdftotext", "-l", "3", str(pdf_path), "-"],
+            capture_output=True,
+            text=True,
+            timeout=15,
+            check=False,
+        ).stdout
+    except (subprocess.TimeoutExpired, OSError) as exc:
+        logger.debug("pdftotext diagnosis failed for {}: {}: {}", pdf_path.name, type(exc).__name__, exc)
+        return (
+            "GROBID does not recognize this PDF's structure; the text-layer probe itself failed "
+            f"({type(exc).__name__})"
+        )
+    if len(text.strip()) < 100:
+        return "image-only PDF (no text layer) — GROBID cannot OCR; run OCR over it first"
+    return "GROBID does not recognize this PDF's structure, though it does contain extractable text"
+
+
+class GrobidClient:
+    """A thin client over one GROBID instance.
+
+    Deliberately an injectable object with no module-level state, unlike the sciwrite-lint original:
+    that client is shared by a long-lived batch process, where a cached health check pays for itself.
+    An audit run parses exactly one PDF, so a TTL cache buys nothing and module globals would leak
+    between tests and rebind across event loops.
+    """
+
+    def __init__(self, base_url: str, *, client: httpx.AsyncClient | None = None) -> None:
+        self.base_url = base_url.rstrip("/")
+        self._client = client or httpx.AsyncClient(headers={"User-Agent": DEFAULT_USER_AGENT})
+        self._owns_client = client is None
+
+    async def aclose(self) -> None:
+        if self._owns_client and not self._client.is_closed:
+            await self._client.aclose()
+
+    async def check_alive(self) -> None:
+        """Raise `GrobidUnavailableError` unless the service answers. Called before the upload.
+
+        Checked up front so an unreachable service fails in seconds with an actionable message,
+        rather than after a multi-minute upload timeout.
+        """
+        url = f"{self.base_url}{ALIVE_ENDPOINT}"
+        try:
+            resp = await self._client.get(url, timeout=_ALIVE_TIMEOUT)
+        except httpx.HTTPError as exc:
+            raise GrobidUnavailableError(
+                f"GROBID is not reachable at {self.base_url} ({type(exc).__name__}: {exc}).\n"
+                f"PDF input needs a running GROBID; start one with:\n  {GROBID_START_HINT}\n"
+                "Or point --grobid / GROBID_URL at an existing instance."
+            ) from exc
+        if resp.status_code != 200:
+            raise GrobidUnavailableError(
+                f"GROBID at {self.base_url} answered {ALIVE_ENDPOINT} with HTTP "
+                f"{resp.status_code}, so it is not ready to accept documents.\n"
+                f"If it is still loading models, wait ~30 s and retry; otherwise restart it:\n"
+                f"  {GROBID_START_HINT}"
+            )
+
+    async def fulltext_tei(self, pdf_path: str | Path) -> str:
+        """Upload a PDF and return its TEI XML.
+
+        Raises `GrobidUnavailableError`, `PdfUnparseableError`, or `GrobidRequestError` — every
+        failure mode is named, and none of them returns an empty string.
+        """
+        path = Path(pdf_path)
+        await self.check_alive()
+
+        pdf_bytes = path.read_bytes()
+        if not pdf_bytes:
+            raise PdfUnparseableError(path.name, "the file is empty (0 bytes)")
+
+        url = f"{self.base_url}{FULLTEXT_ENDPOINT}"
+        # A 500 that names a per-document parse failure is NOT transient: retrying it three times
+        # only adds latency, and calling it an outage would blame the service for a bad input.
+        def _transient(resp: httpx.Response) -> bool:
+            return is_transient_status(resp) and not _is_unparseable_body(resp.text)
+
+        try:
+            resp = await post_multipart(
+                self._client,
+                url,
+                files={"input": (path.name, pdf_bytes, "application/pdf")},
+                data=dict(FULLTEXT_PARAMS),
+                timeout=_timeout_for(len(pdf_bytes)),
+                transient=_transient,
+            )
+        except TransientHTTPError as exc:
+            raise GrobidRequestError(
+                f"GROBID at {self.base_url} kept failing on {path.name} after 3 attempts ({exc}).\n"
+                "Check the service logs:  podman logs grobid"
+            ) from exc
+
+        if resp.status_code == 200:
+            if not resp.text.strip():
+                raise GrobidRequestError(
+                    f"GROBID returned an empty body (HTTP 200) for {path.name} — no TEI to parse."
+                )
+            return resp.text
+
+        if _is_unparseable_body(resp.text):
+            reason = _diagnose_unparseable(path)
+            logger.info("GROBID cannot parse {}: {}", path.name, reason)
+            raise PdfUnparseableError(path.name, reason)
+
+        raise GrobidRequestError(
+            f"GROBID at {self.base_url} returned HTTP {resp.status_code} for {path.name}: "
+            f"{resp.text[:200]!r}\nCheck the service logs:  podman logs grobid"
+        )