reference-audit 0.1.0__py3-none-any.whl

reference_audit/__init__.py

@@ -0,0 +1,8 @@
+"""reference_audit — audit .bib/.tex references for correctness and hallucination.
+
+The package is a plain async Python application (project governance uses the
+`constructor-studio` CLI, installed separately; the package does not depend on it). See `architecture/` for the
+governed design artifacts and `README.md` for the audit specification.
+"""
+
+__version__ = "0.1.0"

reference_audit/alignmentcheck.py

@@ -0,0 +1,136 @@
+"""Citation alignment: is a reference cited for a claim its source actually makes?
+
+Once step 1 has matched an entry to exactly one real work, the work's *identity* is settled — but it
+may still be cited for something the work does not claim. This module pairs each citing context (the
+sentence(s) that invoke the reference, from `parsing/tex.py`) with the cited work's ABSTRACT and
+classifies the usage:
+
+  - ``supported``       the abstract corroborates the citing claim.
+  - ``contradicted``    the abstract asserts the opposite — the one "loud" finding.
+  - ``not_in_abstract`` the abstract is silent on the claim. An abstract is only a summary, so its
+                        silence is NOT misuse — the full text may well support the claim.
+  - ``unverifiable``    no abstract was retrievable, the LLM is unavailable, or the check failed.
+
+Per the reliability contract, a silent/absent abstract or ANY failure yields
+``not_in_abstract``/``unverifiable`` — NEVER ``contradicted``. Each citation is judged in isolation
+(one failure never affects the others), and the check is advisory: it never changes the step-1
+verdict. LLM decisions are cached by ``(prompt, kind, model)``.
+"""
+
+from __future__ import annotations
+
+import asyncio
+
+from reference_audit.cache.store import AuditCache, prompt_hash
+from reference_audit.config import AuditConfig
+from reference_audit.llm.client import LLMClient, LLMError
+from reference_audit.llm.prompts import CITATION_ALIGNMENT_SYSTEM, citation_alignment_user
+from reference_audit.models import (
+    AlignmentFinding,
+    BibEntry,
+    CitationAlignmentResult,
+    CitationContext,
+    MatchedArtifact,
+)
+
+_KIND = "citation_alignment"
+
+
+def artifact_abstract(artifact: MatchedArtifact) -> str:
+    """The fullest abstract available anywhere on the matched artifact.
+
+    Scans every record/version (and the best record) rather than trusting one representative, so an
+    abstract that rode in on any merged source is found. Empty string when none carries one — which
+    the caller reports as ``unverifiable``, never a guess.
+    """
+    records = [*artifact.records, *artifact.versions]
+    if artifact.best_record is not None:
+        records.append(artifact.best_record)
+    return max(((r.abstract or "").strip() for r in records), key=len, default="")
+
+
+def _unverifiable(ctx: CitationContext, detail: str) -> AlignmentFinding:
+    return AlignmentFinding(
+        key=ctx.key, context_text=ctx.text, ordinal=ctx.ordinal, status="unverifiable", detail=detail
+    )
+
+
+def _apply(ctx: CitationContext, result: CitationAlignmentResult) -> AlignmentFinding:
+    return AlignmentFinding(
+        key=ctx.key,
+        context_text=ctx.text,
+        ordinal=ctx.ordinal,
+        status=result.classification,
+        evidence_quote=result.evidence_quote,
+        detail=result.reason,
+        confidence=result.confidence,
+        via_llm=True,
+    )
+
+
+async def _classify_one(
+    entry: BibEntry,
+    ctx: CitationContext,
+    abstract: str,
+    llm: LLMClient | None,
+    cache: AuditCache | None,
+) -> AlignmentFinding:
+    """Classify one citing context. Never raises — any failure becomes ``unverifiable`` so a single
+    citation's problem cannot abort the entry or the other citations (per-citation isolation)."""
+    if not abstract:
+        return _unverifiable(ctx, "no abstract available for the cited work; alignment not checked")
+    if llm is None:
+        return _unverifiable(ctx, "LLM unavailable; citation alignment not checked")
+    user = citation_alignment_user(entry, ctx.text, abstract)
+    p_hash = prompt_hash(CITATION_ALIGNMENT_SYSTEM + "\n" + user)
+    if cache is not None:
+        cached = cache.get_llm_decision(p_hash, _KIND)
+        if cached is not None:
+            return _apply(ctx, CitationAlignmentResult.model_validate_json(cached))
+    try:
+        result = await llm.structured(
+            CITATION_ALIGNMENT_SYSTEM, user, CitationAlignmentResult, _KIND
+        )
+    except asyncio.CancelledError:
+        raise
+    except LLMError as exc:
+        return _unverifiable(ctx, f"citation alignment check failed ({exc})")
+    except Exception as exc:  # noqa: BLE001 — advisory; isolate this citation, never abort the entry
+        return _unverifiable(ctx, f"citation alignment check errored ({exc})")
+    if cache is not None:
+        cache.put_llm_decision(p_hash, _KIND, result.model_dump_json())
+    return _apply(ctx, result)
+
+
+async def resolve_alignment_findings(
+    entry: BibEntry,
+    artifact: MatchedArtifact,
+    contexts: list[CitationContext],
+    llm: LLMClient | None,
+    config: AuditConfig,  # noqa: ARG001 — symmetry with resolve_field_findings; reserved
+    cache: AuditCache | None,
+) -> list[AlignmentFinding]:
+    """Alignment findings for every citing context of one matched entry (concurrent, isolated)."""
+    if not contexts:
+        return []
+    abstract = artifact_abstract(artifact)
+    return list(
+        await asyncio.gather(*(_classify_one(entry, c, abstract, llm, cache) for c in contexts))
+    )
+
+
+def alignment_note(f: AlignmentFinding) -> str:
+    """One-line human summary for the text report (only actionable findings are surfaced)."""
+    where = f" [cite #{f.ordinal + 1}]" if f.ordinal else ""
+    if f.status == "contradicted":
+        quote = f" — abstract says: “{f.evidence_quote}”" if f.evidence_quote else ""
+        return (
+            f"citation{where} may misrepresent the source: the cited abstract appears to contradict "
+            f"“{f.context_text}” — {f.detail}{quote}"
+        )
+    if f.status == "not_in_abstract":
+        return (
+            f"citation{where} not confirmed by the abstract (the abstract is silent on "
+            f"“{f.context_text}”; full text may support it) — {f.detail}"
+        )
+    return f"citation{where} alignment could not be verified — {f.detail}"

reference_audit/bookcheck.py

@@ -0,0 +1,98 @@
+"""Edition-aware book verification, grounded in Open Library editions.
+
+A .bib book entry usually cites a *specific edition* — a (year, publisher) pair, sometimes an ISBN.
+The generic step-1 matcher pools whatever records the sources return, and for books that often
+includes a *newer* edition pulled from Crossref (e.g. a 2018 Routledge reprint of a 1976 book). The
+generic field check then compares the cited original edition's year/publisher against that newer
+record and wrongly flags them as mistakes.
+
+This module fixes that by working off the actual Open Library editions of the book:
+
+  1. `match_cited_edition` finds the edition the .bib is citing (by ISBN, else year+publisher, else
+     year). When found, the cited edition "checks out" and its own year/publisher are the canonical
+     values to verify against — so the original edition is no longer flagged against a reprint. When
+     *not* found (Open Library doesn't have the book, or not that edition), the caller reports the
+     gap to the user rather than silently passing — see the reliability contract.
+  2. `latest_edition` / `better_edition_note` then point at the most recent edition as a possible
+     better version to cite (step 2).
+
+Pure and network-free: the editions are fetched by the Open Library adapter and passed in.
+"""
+
+from __future__ import annotations
+
+import re
+
+from reference_audit.models import BibEntry, SourceRecord
+
+
+def _fold(s: str | None) -> str:
+    return re.sub(r"[^a-z0-9]+", " ", (s or "").lower()).strip()
+
+
+def _publisher_compatible(bib_publisher: str, edition_publisher: str) -> bool:
+    """The cited publisher matches the edition's when one folded name contains the other
+    ('W. A. Benjamin' ⊆ 'W. A. Benjamin, Advanced Book Program')."""
+    a, b = _fold(bib_publisher), _fold(edition_publisher)
+    return bool(a and b and (a == b or a in b or b in a))
+
+
+def match_cited_edition(
+    entry: BibEntry, editions: list[SourceRecord]
+) -> SourceRecord | None:
+    """The Open Library edition the .bib cites, or None if no edition corresponds.
+
+    Strongest signal first: the cited ISBN, then year+publisher agreement, then year alone.
+    """
+    if not editions:
+        return None
+    cited_isbns = entry.ids.all_isbn13()
+    if cited_isbns:
+        for e in editions:
+            if e.ids.all_isbn13() & cited_isbns:
+                return e
+    if entry.year is not None:
+        if entry.publisher:
+            for e in editions:
+                if (
+                    e.year == entry.year
+                    and e.publisher
+                    and _publisher_compatible(entry.publisher, e.publisher)
+                ):
+                    return e
+        for e in editions:
+            if e.year == entry.year:
+                return e
+    return None
+
+
+def latest_edition(editions: list[SourceRecord]) -> SourceRecord | None:
+    """The most recently published edition among those carrying a year."""
+    dated = [e for e in editions if e.year is not None]
+    return max(dated, key=lambda e: e.year) if dated else None
+
+
+def better_edition_note(
+    matched: SourceRecord | None, latest: SourceRecord | None
+) -> str | None:
+    """A step-2 upgrade notice when a later edition than the cited one exists; else None."""
+    if matched is None or latest is None or matched.year is None or latest.year is None:
+        return None
+    if latest.year <= matched.year:
+        return None
+    where = ", ".join(p for p in (str(latest.year), latest.publisher) if p)
+    isbn = f" (isbn {latest.ids.isbn13})" if latest.ids.isbn13 else ""
+    return (
+        f"citing the {matched.year} edition; a newer edition is available: {where}{isbn}"
+        " — verify whether you should cite the latest edition"
+    )
+
+
+def describe_cited_edition(entry: BibEntry) -> str:
+    """Human description of the edition the .bib cites, for the could-not-verify report."""
+    bits = [str(entry.year)] if entry.year else []
+    if entry.publisher:
+        bits.append(entry.publisher)
+    if entry.ids.isbn13:
+        bits.append(f"isbn {entry.ids.isbn13}")
+    return ", ".join(bits) or "this edition"

reference_audit/cache/__init__.py

@@ -0,0 +1 @@
+"""SQLite memoization so repeat runs on the same .bib trigger zero DB/LLM calls."""

reference_audit/cache/db.py

@@ -0,0 +1,108 @@
+"""SQLite connection + schema (adapted from sciwrite-lint workspace_db `_core`).
+
+Three cache layers (README: avoid re-running DB/LLM calls):
+- source_query_cache : raw adapter responses, keyed by (entry_hash, source, query_kind).
+  Only successful (ok=1) results are stored; errors are never cached (so they retry), preserving
+  the error≠not-found invariant.
+- llm_decision_cache : LLM verdicts keyed by (prompt_hash, kind, model) — model in key ⇒ a model
+  switch re-runs (added in M4).
+- entry_verdict_cache: whole-entry fast path, keyed by (entry_hash, backend) and gated by
+  (pipeline_version, model). `backend` is the source backend that produced the verdict (`api` or
+  `clickhouse`): the two read different snapshots of the same databases, so neither may serve the
+  other's verdict.
+- doi_resolution_cache: doi.org's verdict on a DOI (does the handle resolve?) — a world-fact, so
+  keyed by the bare DOI and independent of pipeline_version/model. Only definitive True/False are
+  stored; an outage is never cached (mirrors the never-cache-errors invariant).
+- db_quirks          : mirror of docs/db_quirks.md (README principle 2).
+"""
+
+from __future__ import annotations
+
+import sqlite3
+from pathlib import Path
+
+SCHEMA = """
+CREATE TABLE IF NOT EXISTS source_query_cache (
+    entry_hash TEXT NOT NULL,
+    source     TEXT NOT NULL,
+    query_kind TEXT NOT NULL,
+    result_json TEXT NOT NULL,
+    fetched_at TEXT NOT NULL,
+    ok         INTEGER NOT NULL DEFAULT 1,
+    PRIMARY KEY (entry_hash, source, query_kind)
+);
+CREATE TABLE IF NOT EXISTS llm_decision_cache (
+    prompt_hash TEXT NOT NULL,
+    kind        TEXT NOT NULL,
+    model       TEXT NOT NULL,
+    result_json TEXT NOT NULL,
+    created_at  TEXT NOT NULL,
+    PRIMARY KEY (prompt_hash, kind, model)
+);
+CREATE TABLE IF NOT EXISTS entry_verdict_cache (
+    entry_hash       TEXT NOT NULL,
+    backend          TEXT NOT NULL DEFAULT 'api',
+    verdict_json     TEXT NOT NULL,
+    pipeline_version TEXT NOT NULL,
+    model            TEXT NOT NULL,
+    created_at       TEXT NOT NULL,
+    PRIMARY KEY (entry_hash, backend)
+);
+CREATE TABLE IF NOT EXISTS doi_resolution_cache (
+    doi        TEXT PRIMARY KEY,
+    resolves   INTEGER NOT NULL,
+    checked_at TEXT NOT NULL
+);
+CREATE TABLE IF NOT EXISTS db_quirks (
+    source        TEXT NOT NULL,
+    quirk         TEXT NOT NULL,
+    example_entry TEXT,
+    noted_at      TEXT NOT NULL
+);
+"""
+
+
+def _migrate(conn: sqlite3.Connection) -> None:
+    """Bring a cache written by an older version up to the current schema, in place.
+
+    `entry_verdict_cache` gained a `backend` column (part of the key). Every verdict an older cache
+    holds was produced through the public APIs, so it is kept and labelled `api`.
+    """
+    cols = {row["name"] for row in conn.execute("PRAGMA table_info(entry_verdict_cache)")}
+    if cols and "backend" not in cols:
+        conn.executescript(
+            """
+            BEGIN;
+            ALTER TABLE entry_verdict_cache RENAME TO entry_verdict_cache_old;
+            CREATE TABLE entry_verdict_cache (
+                entry_hash       TEXT NOT NULL,
+                backend          TEXT NOT NULL DEFAULT 'api',
+                verdict_json     TEXT NOT NULL,
+                pipeline_version TEXT NOT NULL,
+                model            TEXT NOT NULL,
+                created_at       TEXT NOT NULL,
+                PRIMARY KEY (entry_hash, backend)
+            );
+            INSERT INTO entry_verdict_cache
+                (entry_hash, backend, verdict_json, pipeline_version, model, created_at)
+                SELECT entry_hash, 'api', verdict_json, pipeline_version, model, created_at
+                FROM entry_verdict_cache_old;
+            DROP TABLE entry_verdict_cache_old;
+            COMMIT;
+            """
+        )
+
+
+def connect(path: str | Path) -> sqlite3.Connection:
+    """Open (creating dirs + schema) a WAL-mode connection."""
+    p = Path(path)
+    if p.parent and str(p.parent) not in ("", "."):
+        p.parent.mkdir(parents=True, exist_ok=True)
+    conn = sqlite3.connect(str(p))
+    conn.row_factory = sqlite3.Row
+    conn.execute("PRAGMA journal_mode=WAL")
+    conn.execute("PRAGMA busy_timeout=5000")
+    _migrate(conn)
+    conn.executescript(SCHEMA)
+    conn.commit()
+    return conn

reference_audit/cache/store.py

@@ -0,0 +1,128 @@
+"""Typed CRUD over the cache DB. The pipeline reads here before any network/LLM call."""
+
+from __future__ import annotations
+
+import datetime
+import hashlib
+from pathlib import Path
+
+from reference_audit.cache import db as _db
+from reference_audit.models import SourceQueryResult, Verdict
+
+
+def _now() -> str:
+    # Fixed width (microseconds always present), so stamps order correctly as text.
+    return datetime.datetime.now(datetime.UTC).isoformat(timespec="microseconds")
+
+
+def prompt_hash(text: str) -> str:
+    return hashlib.sha256(text.encode("utf-8")).hexdigest()
+
+
+class AuditCache:
+    """Backed by SQLite. `model`/`pipeline_version` gate the whole-entry verdict fast path, and
+    `backend` (the source backend, `api` or `clickhouse`) keys it.
+
+    `fresh=True` (`--fresh`) ignores every row stored before this cache was opened: reads only see
+    what was written since, and writes overwrite as usual. Nothing is deleted, so other
+    bibliographies sharing the DB keep their cached results."""
+
+    def __init__(
+        self,
+        path: str | Path,
+        *,
+        pipeline_version: str = "0.1",
+        model: str = "",
+        backend: str = "api",
+        fresh: bool = False,
+    ):
+        self.conn = _db.connect(path)
+        self.pipeline_version = pipeline_version
+        self.model = model
+        self.backend = backend
+        # Rows stamped before this are invisible to reads (ISO-8601 UTC stamps compare as text).
+        self.since = _now() if fresh else ""
+
+    # --- source query cache (only successful results are stored) ---
+    def get_source_query(
+        self, entry_hash: str, source: str, query_kind: str
+    ) -> SourceQueryResult | None:
+        row = self.conn.execute(
+            "SELECT result_json FROM source_query_cache "
+            "WHERE entry_hash=? AND source=? AND query_kind=? AND ok=1 AND fetched_at>=?",
+            (entry_hash, source, query_kind, self.since),
+        ).fetchone()
+        return SourceQueryResult.model_validate_json(row["result_json"]) if row else None
+
+    def put_source_query(
+        self, entry_hash: str, result: SourceQueryResult, *, source: str | None = None
+    ) -> None:
+        """Store a successful result under `source` (default `result.source`). An adapter passes its
+        `cache_source`, so a local-mirror response never answers for the public API or vice versa."""
+        if result.error is not None:
+            return  # never cache errors — they must retry (error ≠ not-found)
+        self.conn.execute(
+            "INSERT OR REPLACE INTO source_query_cache "
+            "(entry_hash, source, query_kind, result_json, fetched_at, ok) VALUES (?,?,?,?,?,1)",
+            (entry_hash, source or result.source, result.query_kind, result.model_dump_json(), _now()),
+        )
+        self.conn.commit()
+
+    # --- whole-entry verdict fast path ---
+    def get_entry_verdict(self, entry_hash: str) -> Verdict | None:
+        row = self.conn.execute(
+            "SELECT verdict_json FROM entry_verdict_cache "
+            "WHERE entry_hash=? AND backend=? AND pipeline_version=? AND model=? AND created_at>=?",
+            (entry_hash, self.backend, self.pipeline_version, self.model, self.since),
+        ).fetchone()
+        return Verdict.model_validate_json(row["verdict_json"]) if row else None
+
+    # @cpt-dod:cpt-referenceaudit-dod-identification-caching:p1
+    def put_entry_verdict(self, entry_hash: str, verdict: Verdict) -> None:
+        self.conn.execute(
+            "INSERT OR REPLACE INTO entry_verdict_cache "
+            "(entry_hash, backend, verdict_json, pipeline_version, model, created_at) "
+            "VALUES (?,?,?,?,?,?)",
+            (
+                entry_hash, self.backend, verdict.model_dump_json(), self.pipeline_version,
+                self.model, _now(),
+            ),
+        )
+        self.conn.commit()
+
+    # --- DOI resolution cache (does doi.org's handle system know this DOI?) ---
+    def get_doi_resolution(self, doi: str) -> bool | None:
+        """Cached doi.org verdict for `doi`: True/False if known, None if never checked."""
+        row = self.conn.execute(
+            "SELECT resolves FROM doi_resolution_cache WHERE doi=? AND checked_at>=?",
+            (doi, self.since),
+        ).fetchone()
+        return bool(row["resolves"]) if row else None
+
+    def put_doi_resolution(self, doi: str, resolves: bool) -> None:
+        self.conn.execute(
+            "INSERT OR REPLACE INTO doi_resolution_cache (doi, resolves, checked_at) "
+            "VALUES (?,?,?)",
+            (doi, 1 if resolves else 0, _now()),
+        )
+        self.conn.commit()
+
+    # --- LLM decision cache (used from M4) ---
+    def get_llm_decision(self, p_hash: str, kind: str) -> str | None:
+        row = self.conn.execute(
+            "SELECT result_json FROM llm_decision_cache "
+            "WHERE prompt_hash=? AND kind=? AND model=? AND created_at>=?",
+            (p_hash, kind, self.model, self.since),
+        ).fetchone()
+        return row["result_json"] if row else None
+
+    def put_llm_decision(self, p_hash: str, kind: str, result_json: str) -> None:
+        self.conn.execute(
+            "INSERT OR REPLACE INTO llm_decision_cache "
+            "(prompt_hash, kind, model, result_json, created_at) VALUES (?,?,?,?,?)",
+            (p_hash, kind, self.model, result_json, _now()),
+        )
+        self.conn.commit()
+
+    def close(self) -> None:
+        self.conn.close()

reference_audit/cli.py

@@ -0,0 +1,190 @@
+"""`reference-audit` command-line interface (Typer).
+
+`audit` runs the async pipeline (parse + identify, cached) over either a `.tex` + `.bib` pair or a
+single PDF. `--no-network` gives the parse-only report (for a PDF only when it embeds the BibTeX records
+of its references — otherwise its reference list comes from an HTTP call to GROBID, so there is no
+offline parse for it).
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+import typer
+
+from reference_audit.config import AuditConfig
+from reference_audit.inputs import InvalidInputError, PdfInput, default_cache_path, resolve_input
+from reference_audit.pdf.embedded import read_embedded_references
+from reference_audit.pdf.grobid import GrobidError
+from reference_audit.pipeline import (
+    EmptyBibliographyError,
+    build_embedded_parse_report,
+    build_parse_report,
+    run_audit,
+    run_pdf_audit,
+)
+from reference_audit.report import render_json, render_text
+from reference_audit.sources.clickhouse import ClickHouseUnavailableError
+
+app = typer.Typer(
+    add_completion=False,
+    help="Audit .bib/.tex or PDF references: identify artifacts, screen for hallucinations.",
+)
+
+
+@app.callback()
+def main() -> None:
+    """Reference auditor — identify exact artifacts and screen for hallucinated references."""
+
+
+@app.command()
+def audit(
+    document: Path = typer.Argument(
+        ...,
+        exists=True,
+        dir_okay=False,
+        help="Manuscript .tex (paired with a .bib), or a .pdf whose references GROBID extracts.",
+    ),
+    bib: Path | None = typer.Argument(
+        None,
+        exists=True,
+        dir_okay=False,
+        help="Bibliography .bib to audit. Required with a .tex; must be omitted with a .pdf.",
+    ),
+    fmt: str = typer.Option("text", "--format", "-f", help="Output format: text | json | both."),
+    no_network: bool = typer.Option(
+        False, "--no-network", help="Parse-only: identifiers + cited/uncited, no DB calls."
+    ),
+    no_llm: bool = typer.Option(
+        False, "--no-llm", help="Formal-only: skip LLM adjudication (deterministic)."
+    ),
+    check_citations: bool = typer.Option(
+        False, "--check-citations",
+        help="Advisory: check each citing context against the cited work's abstract (needs the LLM).",
+    ),
+    fresh: bool = typer.Option(False, "--fresh", help="Ignore cached results and re-query."),
+    cache: Path | None = typer.Option(
+        None, "--cache", help="Cache DB path (default: <bib_dir>/.reference_audit/cache.db)."
+    ),
+    model: str | None = typer.Option(None, "--model", help="LLM model override."),
+    backend: str | None = typer.Option(
+        None, "--backend",
+        help="Where Semantic Scholar, OpenAlex and DBLP are read from: api | clickhouse "
+             "(default: SOURCE_BACKEND, else api).",
+    ),
+    grobid: str | None = typer.Option(
+        None, "--grobid", help="GROBID base URL for PDF input (default http://localhost:8070)."
+    ),
+    ignore_embedded: bool = typer.Option(
+        False, "--ignore-embedded",
+        help="For a PDF that embeds the BibTeX records of its cited works (AI4X template), extract "
+             "the references with GROBID anyway.",
+    ),
+    fail_on: str | None = typer.Option(
+        None, "--fail-on", help="Exit non-zero if any verdict matches: hallucinated | multiple."
+    ),
+    partial_authors: str | None = typer.Option(
+        None, "--partial-authors",
+        help="A cited author list that omits some of the work's authors without 'and others': "
+             "ignore | warn | error (default: PARTIAL_AUTHORS, else warn).",
+    ),
+) -> None:
+    """Audit a .bib with its .tex, or a PDF on its own.
+
+    With a PDF, GROBID supplies both the reference list and the in-text citations, so no .bib is
+    needed — unless the PDF embeds the BibTeX records of its cited works (the AI4X template does),
+    which are then audited instead. Either way each reference is identified and screened for
+    hallucinations.
+    """
+    if fmt not in ("text", "json", "both"):
+        raise typer.BadParameter("format must be one of: text, json, both")
+    if backend not in (None, "api", "clickhouse"):
+        raise typer.BadParameter("--backend must be 'api' or 'clickhouse'")
+    if partial_authors not in (None, "ignore", "warn", "error"):
+        raise typer.BadParameter("--partial-authors must be 'ignore', 'warn' or 'error'")
+    if fail_on not in (None, "hallucinated", "multiple"):
+        raise typer.BadParameter("--fail-on must be 'hallucinated' or 'multiple'")
+    if fail_on and no_network:
+        # The parse-only report has no verdicts, so the gate could never trip: a CI job relying on
+        # it would always pass. Reject the combination rather than pass silently.
+        raise typer.BadParameter(
+            "--fail-on cannot be combined with --no-network: the parse-only report has no verdicts "
+            "to check"
+        )
+
+    try:
+        source = resolve_input(document, bib)
+    except InvalidInputError as exc:
+        raise typer.BadParameter(str(exc)) from exc
+
+    embedded_bib: str | None = None
+    if no_network and isinstance(source, PdfInput):
+        # A PDF that embeds its references' BibTeX records parses offline. Any other PDF needs
+        # GROBID, and --no-network is a contract ("this run contacts nothing") — --grobid can point
+        # at any host, so we cannot honestly weaken it to "no *remote* network". Reject it rather
+        # than quietly redefining what the flag promises.
+        embedded = None if ignore_embedded else read_embedded_references(source.pdf_path)
+        if embedded is None or embedded.bib_text is None:
+            why = (
+                "--ignore-embedded was given" if embedded is None
+                else embedded.problem or "it embeds no BibTeX records of its references"
+            )
+            raise typer.BadParameter(
+                f"--no-network cannot be combined with this PDF ({why}): its reference list and "
+                "in-text citations would be extracted by the GROBID service over HTTP, so it has no "
+                "offline parse path. Pass a .tex + .bib pair for the offline parse-only report."
+            )
+        embedded_bib = embedded.bib_text
+
+    try:
+        if no_network and embedded_bib is not None:
+            report = build_embedded_parse_report(source.pdf_path, embedded_bib)
+        elif no_network:
+            report = build_parse_report(source.tex_path, source.bib_path)
+        else:
+            updates: dict = {}
+            if model:
+                updates["model"] = model
+            if no_llm:
+                updates["use_llm"] = False
+            if check_citations:
+                updates["check_alignment"] = True
+            if grobid:
+                updates["grobid_url"] = grobid
+            if ignore_embedded:
+                updates["use_embedded_references"] = False
+            if backend:
+                updates["source_backend"] = backend
+            if partial_authors:
+                updates["partial_authors"] = partial_authors
+            config = AuditConfig().model_copy(update=updates)
+            cache_path = cache or default_cache_path(source)
+            common = {
+                "config": config,
+                "cache_path": cache_path,
+                "fresh": fresh,
+                "progress": sys.stderr.isatty(),
+            }
+            if isinstance(source, PdfInput):
+                report = run_pdf_audit(source.pdf_path, **common)
+            else:
+                report = run_audit(source.tex_path, source.bib_path, **common)
+    except (EmptyBibliographyError, GrobidError, ClickHouseUnavailableError) as exc:
+        typer.echo(f"error: {exc}", err=True)
+        raise typer.Exit(code=2) from exc
+
+    if fmt in ("json", "both"):
+        typer.echo(render_json(report))
+    if fmt in ("text", "both"):
+        typer.echo(render_text(report))
+
+    if fail_on:
+        verdicts = report.summary.get("verdicts", {})
+        trigger = {"hallucinated": "none", "multiple": "multiple"}[fail_on]
+        if verdicts.get(trigger, 0) > 0:
+            raise typer.Exit(code=1)
+
+
+if __name__ == "__main__":
+    app()