reference-audit 0.1.0__py3-none-any.whl

reference_audit/matching/webcheck.py

@@ -0,0 +1,189 @@
+"""Web-artifact verification funnel for URL-only ``@misc`` references.
+
+Given the page fetched from the cited URL (`sources.web.WebAdapter`), decide the verdict with a
+cheap-first funnel that mirrors the rest of the pipeline:
+
+  1. **Fetch outcome.** A transport error / bot-wall leaves the entry UNRESOLVED (reported, retried —
+     never a false 'no match'). A dead link (404/410) is a real finding, also reported, and likewise
+     leaves the entry unresolved (a rotted or wrong URL is not, by itself, proof the work never
+     existed — reliability: report the gap, never guess a hallucination). A client-side-rendered
+     (single-page-app) shell we could not render (no browser, or empty even after rendering) is the
+     same: reported and left unresolved, NEVER read as a different/`none` resource.
+  2. **HTML metadata (deterministic).** If the page's self-declared title matches the cited title
+     (and authors corroborate, when both sides list them), the page IS the cited resource →
+     ``exactly_one``, with no LLM call (the 100%-match short-circuit).
+  3. **LLM fallback.** When the metadata is absent or inconclusive, ask the model whether the page is
+     the cited resource (affirmative polarity, cached). A confident yes → ``exactly_one``; a
+     high-confidence no → ``none`` (a live page that is positively a different/`not found`/login
+     resource — a likely wrong or fabricated URL); anything else stays UNRESOLVED.
+
+Returns ``(verdict, issues)`` — the pipeline owns the audit object. A ``None`` verdict means
+unresolved (never cached, retried next run).
+"""
+
+from __future__ import annotations
+
+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 WEB_MATCH_SYSTEM, web_match_user
+from reference_audit.matching.features import title_ratio
+from reference_audit.matching.names import author_overlap, author_subset
+from reference_audit.models import (
+    BibEntry,
+    Identifiers,
+    MatchedArtifact,
+    SourceQueryResult,
+    SourceRecord,
+    Verdict,
+    WebMatchResult,
+)
+
+
+def _confirmed(page: SourceRecord, confidence: str, rationale: str) -> Verdict:
+    """An ``exactly_one`` verdict whose single artifact is the fetched web page itself."""
+    artifact = MatchedArtifact(
+        records=[page],
+        versions=[page],
+        best_record=page,
+        merged_ids=page.ids or Identifiers(),
+    )
+    return Verdict(
+        kind="exactly_one",
+        artifacts=[artifact],
+        confidence=confidence,
+        rationale=f"confirmed via web page — {rationale}",
+    )
+
+
+def _metadata_confirms(entry: BibEntry, page: SourceRecord, config: AuditConfig) -> bool:
+    """Deterministic step 2: page's self-declared title (and authors, if any) match the citation."""
+    if not page.title or title_ratio(entry.title, page.title) < config.web_title_accept:
+        return False
+    # When both sides list authors they must corroborate; a missing list on either side never blocks
+    # (many legitimate pages omit author metadata — that case is what the LLM fallback is for, but a
+    # strong title match alone is enough to confirm here).
+    if entry.authors and page.authors:
+        return (
+            author_overlap(entry.authors, page.authors) >= config.author_accept
+            or author_subset(entry.authors, page.authors)
+        )
+    return True
+
+
+async def _ask_llm(
+    entry: BibEntry,
+    page: SourceRecord,
+    llm: LLMClient,
+    cache: AuditCache | None,
+) -> WebMatchResult:
+    system = WEB_MATCH_SYSTEM
+    user = web_match_user(entry, page)
+    p_hash = prompt_hash(system + "\n" + user)
+    if cache is not None:
+        cached = cache.get_llm_decision(p_hash, "web_match")
+        if cached is not None:
+            return WebMatchResult.model_validate_json(cached)
+    result = await llm.structured(system, user, WebMatchResult, "web_match")
+    if cache is not None:
+        cache.put_llm_decision(p_hash, "web_match", result.model_dump_json())
+    return result
+
+
+async def check_web_reference(
+    entry: BibEntry,
+    fetched: SourceQueryResult,
+    llm: LLMClient | None,
+    config: AuditConfig,
+    cache: AuditCache | None,
+) -> tuple[Verdict | None, list[str]]:
+    """Run the web funnel over the fetched page. Returns (verdict | None-for-unresolved, issues)."""
+    issues: list[str] = []
+
+    if fetched.error:
+        issues.append(
+            f"could not check the cited URL (left unresolved, will retry next run): {fetched.error}"
+        )
+        return None, issues
+
+    page = fetched.records[0] if fetched.records else None
+    if page is None:
+        issues.append("no URL to check for this web reference")
+        return None, issues
+
+    raw = page.raw or {}
+    if raw.get("dead"):
+        issues.append(
+            f"cited URL is a dead link (HTTP {raw.get('status')} — page no longer exists); "
+            "the reference could not be verified"
+        )
+        return None, issues
+
+    # A client-side-rendered (single-page-app) shell whose real content we could not read: NEVER a
+    # `none`. An empty app shell is not positive evidence of a different resource — feeding it to the
+    # LLM (which sees only a generic landing/spinner page) yields a false "wrong/fabricated URL"
+    # verdict. Report the gap and leave it unresolved, per the reliability rule. See `sources.web`.
+    render = raw.get("render")
+    if render == "unavailable":
+        issues.append(
+            "cited URL returns a JavaScript-rendered page whose content loads only in a browser, "
+            "and no headless browser is available to render it; left unresolved (install/configure "
+            "a headless browser to verify these — see web_render_browser_path)"
+        )
+        return None, issues
+    if render == "rendered_empty":
+        issues.append(
+            "cited URL returns a JavaScript-rendered page that stayed empty even after headless "
+            "rendering; the reference could not be verified (left unresolved, will retry next run)"
+        )
+        return None, issues
+
+    # Step 2 — deterministic HTML-metadata check (no LLM cost on a clean match). A clean confirm is
+    # NOT a problem: it is reported on the verdict line (rationale) only, never appended to `issues`
+    # — `issues` drives the report's needs-attention grouping + ⚠, so a success there is misleading.
+    if _metadata_confirms(entry, page, config):
+        author_note = " + author" if (entry.authors and page.authors) else ""
+        return _confirmed(page, "high", f"page HTML metadata matches the citation (title{author_note})"), issues
+
+    # Step 3 — metadata absent or inconclusive → LLM.
+    if llm is None:
+        issues.append(
+            "cited URL is live but its HTML metadata did not confirm the reference; "
+            "LLM check is disabled (--no-llm), so it is left unresolved"
+        )
+        return None, issues
+
+    try:
+        decision = await _ask_llm(entry, page, llm, cache)
+    except LLMError:
+        issues.append(
+            "cited URL is live but could not be confirmed: the LLM check failed "
+            "(left unresolved, will retry next run)"
+        )
+        return None, issues
+
+    if decision.corresponds and decision.confidence in ("high", "medium"):
+        # As with the metadata confirm: a success is carried by the verdict rationale, not `issues`.
+        return _confirmed(page, decision.confidence, f"LLM-verified ({decision.reason})"), issues
+
+    if not decision.corresponds and decision.confidence == "high":
+        # Positive evidence the live page is a *different* resource (a wrong/fabricated URL): the
+        # README's `none`. A weaker rejection is not enough to cry hallucination — it stays unresolved.
+        issues.append(
+            "the cited URL is live but its content does NOT correspond to the reference "
+            f"(LLM-judged: {decision.reason}) — possible wrong or fabricated URL"
+        )
+        return (
+            Verdict(
+                kind="none",
+                confidence="high",
+                rationale=f"the live page at the cited URL is not the cited resource ({decision.reason})",
+            ),
+            issues,
+        )
+
+    issues.append(
+        "cited URL is live but could not be confirmed as the reference "
+        f"(LLM uncertain: {decision.reason}) — left unresolved"
+    )
+    return None, issues

reference_audit/models.py

@@ -0,0 +1,412 @@
+"""All pydantic data models — the single source of truth.
+
+Seeded from `paper-search-mcp` `Paper` and `sciwrite-lint` `Citation`, promoted to pydantic
+with an explicit `Identifiers` value object and a version graph (`version_links`,
+`openalex_work_id`) that lets the matcher recover preprint↔published relations (the T1 fix).
+"""
+
+from __future__ import annotations
+
+import hashlib
+import re
+from enum import StrEnum
+from typing import Literal
+
+from pydantic import BaseModel, Field, field_validator, model_validator
+
+from reference_audit.parsing.entities import decode_html_entities
+
+
+class EntryType(StrEnum):
+    ARTICLE = "article"
+    INPROCEEDINGS = "inproceedings"
+    BOOK = "book"
+    INCOLLECTION = "incollection"
+    MISC = "misc"
+    UNKNOWN = "unknown"
+
+
+# bib type string -> EntryType
+_BIB_TYPE_MAP = {
+    "article": EntryType.ARTICLE,
+    "inproceedings": EntryType.INPROCEEDINGS,
+    "conference": EntryType.INPROCEEDINGS,
+    "book": EntryType.BOOK,
+    "inbook": EntryType.INCOLLECTION,
+    "incollection": EntryType.INCOLLECTION,
+    "misc": EntryType.MISC,
+    "online": EntryType.MISC,
+    "electronic": EntryType.MISC,
+    "unpublished": EntryType.MISC,
+    "techreport": EntryType.MISC,
+}
+
+
+def entry_type_from_bib(bib_type: str) -> EntryType:
+    return _BIB_TYPE_MAP.get((bib_type or "").strip().lower(), EntryType.UNKNOWN)
+
+
+def _norm_token_string(s: str) -> str:
+    """Lowercase, collapse non-alphanumerics to single spaces — for stable hashing."""
+    return re.sub(r"[^a-z0-9]+", " ", (s or "").lower()).strip()
+
+
+class Identifiers(BaseModel):
+    """Normalized identifiers. DOIs are stored bare + lowercased (opaque-token equality)."""
+
+    doi: str | None = None          # bare, e.g. "10.1073/pnas.2004976117" (no https://doi.org/)
+    arxiv_id: str | None = None     # e.g. "2412.17799"
+    isbn13: str | None = None       # primary 13-digit, separators stripped
+    # Every ISBN-13 this record carries. One physical book registers several (print + electronic, and
+    # per-edition), so a single `isbn13` scalar makes the *same* book look like an ISBN *conflict*
+    # when the cite and the source happen to pick different printings. `isbn13` stays the canonical
+    # one for display/lookup/backfill; matching and pooling use the whole set via `all_isbn13()`.
+    isbn13s: tuple[str, ...] = ()
+    pmid: str | None = None
+    bibcode: str | None = None      # NASA ADS
+    openalex: str | None = None     # OpenAlex Work id, bare + upper, e.g. "W3034344071"
+    google_books: str | None = None  # Google Books volume id, e.g. "yIV_NMDDIvYC"
+    url: str | None = None
+
+    def primary_kind(self) -> Literal["doi", "isbn", "arxiv", "openalex", "google_books", "url"] | None:
+        if self.doi:
+            return "doi"
+        if self.isbn13:
+            return "isbn"
+        if self.arxiv_id:
+            return "arxiv"
+        if self.openalex:
+            return "openalex"
+        if self.google_books:
+            return "google_books"
+        if self.url:
+            return "url"
+        return None
+
+    def all_isbn13(self) -> frozenset[str]:
+        """Every ISBN-13 this record carries (primary + the rest), deduplicated.
+
+        Robust to whether the primary is also listed in `isbn13s`, so callers can populate either
+        field without double-bookkeeping."""
+        return frozenset(i for i in (self.isbn13, *self.isbn13s) if i)
+
+    def any_present(self) -> bool:
+        return any(
+            (
+                self.doi, self.arxiv_id, self.isbn13, self.pmid, self.bibcode,
+                self.openalex, self.google_books, self.url,
+            )
+        )
+
+    def has_strong_id(self) -> bool:
+        """True if a *scholarly anchor* is present — a DOI / ISBN / arXiv / PMID / bibcode /
+        OpenAlex Work id / Google Books volume id. A bare `url` does NOT count: no matching feature
+        compares it, so for scoring an entry identified only by a URL is as anchorless as one with no
+        identifier at all, and must be eligible for the strict title+author backfill path."""
+        return any(
+            (
+                self.doi, self.arxiv_id, self.isbn13, self.pmid, self.bibcode,
+                self.openalex, self.google_books,
+            )
+        )
+
+
+def compute_content_hash(
+    title: str, authors: list[str], year: int | None, venue: str, ids: Identifiers
+) -> str:
+    """sha256 over normalized identifying fields. Cosmetic edits don't bust the cache;
+    a real metadata change does."""
+    parts = [
+        _norm_token_string(title),
+        "|".join(sorted(_norm_token_string(a) for a in authors)),
+        str(year or ""),
+        _norm_token_string(venue),
+        ids.doi or "",
+        ids.arxiv_id or "",
+        ids.isbn13 or "",
+        ids.openalex or "",
+    ]
+    return hashlib.sha256("␟".join(parts).encode("utf-8")).hexdigest()
+
+
+class BibEntry(BaseModel):
+    """One parsed .bib entry, with derived/normalized identifiers."""
+
+    key: str
+    entry_type: EntryType = EntryType.UNKNOWN
+    title: str = ""
+    authors: list[str] = Field(default_factory=list)   # surface strings, as written
+    year: int | None = None
+    venue: str = ""                                     # journal OR booktitle
+    publisher: str = ""                                 # NOT a match feature (gavrilets typo)
+    pages: str = ""
+    ids: Identifiers = Field(default_factory=Identifiers)
+    raw_fields: dict[str, str] = Field(default_factory=dict)
+    cited: bool = False                                 # set by parsing/tex
+    is_commented: bool = False                          # the bagrov2024visual twin; informational
+    content_hash: str = ""
+
+    @model_validator(mode="after")
+    def _fill_hash(self) -> BibEntry:
+        if not self.content_hash:
+            self.content_hash = compute_content_hash(
+                self.title, self.authors, self.year, self.venue, self.ids
+            )
+        return self
+
+
+class UnparsedEntry(BaseModel):
+    """A live `.bib` entry the BibTeX parser could not read. It is reported, never audited: its fields
+    are unknown, so any check would be a guess."""
+
+    key: str
+    entry_type: str = ""
+    line: int = 0                     # 1-based line of the `@type{key` header
+    reason: str
+
+
+class SourceRecord(BaseModel):
+    """One candidate, normalized across sources."""
+
+    source: str
+    source_native_id: str = ""        # OpenAlex Wxxx / S2 id / crossref DOI — dedupe within source
+    title: str = ""
+    authors: list[str] = Field(default_factory=list)
+    year: int | None = None
+    venue: str = ""
+    volume: str = ""
+    issue: str = ""                   # the canonical issue/number
+    pages: str = ""
+    publisher: str = ""
+    abstract: str = ""                # the work's abstract, when the source supplies one (OpenAlex/S2)
+    ids: Identifiers = Field(default_factory=Identifiers)
+    is_preprint: bool = False
+    edition: int | None = None
+    citation_count: int = 0
+    version_links: list[str] = Field(default_factory=list)  # locations + relation targets (version graph)
+    openalex_work_id: str | None = None                     # merge anchor (M4)
+    raw: dict = Field(default_factory=dict)
+    # A pooled record's own source records (preprint and published versions, one per source), each
+    # without `raw`, `abstract` or members of its own. The pooled fields above are a compilation; the
+    # field check reads these to compare an entry against the version it cites. Empty for a leaf.
+    members: list[SourceRecord] = Field(default_factory=list)
+
+    @field_validator("title", "venue", "publisher", mode="after")
+    @classmethod
+    def _decode_text(cls, v: str) -> str:
+        """Sources return HTML-escaped text (Crossref's `Allocation & Regularization`). Decoded
+        here, once for every adapter and for records reloaded from the cache, so that the field check
+        compares — and reports — the real value; see `parsing.entities`."""
+        return decode_html_entities(v)
+
+    @field_validator("authors", mode="after")
+    @classmethod
+    def _decode_authors(cls, v: list[str]) -> list[str]:
+        return [decode_html_entities(a) for a in v]
+
+
+class SourceQueryResult(BaseModel):
+    """Result of one adapter call. `error` is distinct from an empty record list:
+    an outage must never be cached/treated as 'not found'."""
+
+    source: str
+    query_kind: Literal["id", "metadata", "editions", "web"]
+    records: list[SourceRecord] = Field(default_factory=list)
+    error: str | None = None
+
+
+class FeatureVector(BaseModel):
+    """Interpretable features for one (entry, candidate) pair."""
+
+    title_ratio: float = 0.0
+    title_prefix_trap: bool = False
+    author_overlap: float = 0.0
+    author_set_jaccard: float = 0.0
+    author_subset: bool = False           # one author set ⊆ other (abbreviation, not distinct work)
+    year_factor: float = 1.0
+    venue_compatible: float = 1.0
+    id_agreement: Literal["match", "conflict", "absent"] = "absent"
+    pages_conflict: bool = False
+    composite: float = 0.0
+
+
+class CanCorrespondResult(BaseModel):
+    """LLM per-candidate filter verdict (strict json_schema)."""
+
+    can_correspond: bool
+    confidence: Literal["high", "medium", "low"]
+    reason: str
+    distinguishing_evidence: str = ""
+
+
+class SameWorkResult(BaseModel):
+    """LLM equivalence verdict for two records (strict json_schema)."""
+
+    relation: Literal[
+        "same_artifact", "versions_of_same_work", "distinct_works", "uncertain"
+    ]
+    confidence: Literal["high", "medium", "low"]
+    reason: str
+
+
+class WebMatchResult(BaseModel):
+    """LLM verdict on whether a fetched web page IS the resource a URL-only @misc entry cites
+    (strict json_schema). Affirmative polarity: ``corresponds`` is true only on positive evidence
+    the page is that resource, false only on positive evidence it is something else (a different
+    article, a homepage/index, a login/paywall/404 notice); otherwise low confidence.
+    """
+
+    corresponds: bool
+    confidence: Literal["high", "medium", "low"]
+    reason: str
+
+
+class FieldJudgment(BaseModel):
+    """LLM classification of one ambiguous field discrepancy (strict json_schema).
+
+    `formatting_variant` = the .bib value denotes the same thing as the database value, differing
+    only in style (abbreviation, capitalization, accents, punctuation, braces). `error` = the .bib
+    value is genuinely wrong (a different/garbled/truncated value). `uncertain` when neither can be
+    affirmatively concluded — the entry is then surfaced for manual review, never silently passed.
+    """
+
+    classification: Literal["formatting_variant", "error", "uncertain"]
+    confidence: Literal["high", "medium", "low"]
+    reason: str
+
+
+class CitationAlignmentResult(BaseModel):
+    """LLM classification of one citing context against the cited work's abstract (strict json_schema).
+
+    Affirmative polarity for `contradicted`: choose it ONLY on positive evidence the abstract asserts
+    the opposite of the citing claim. `supported` when the abstract corroborates the claim.
+    `not_in_abstract` when the abstract neither supports nor contradicts it — the abstract is not the
+    full paper, so its silence is NOT misuse. The system, not the model, owns `unverifiable` (no
+    abstract / error). `evidence_quote` is the span of the abstract that justifies a
+    supported/contradicted call (empty for `not_in_abstract`).
+    """
+
+    classification: Literal["supported", "contradicted", "not_in_abstract"]
+    confidence: Literal["high", "medium", "low"]
+    reason: str
+    evidence_quote: str = ""
+
+
+class FieldFinding(BaseModel):
+    """Step-3 correctness check of one .bib field against the identified canonical record.
+
+    Runs only on an `exactly_one` match (the artifact is confirmed to be the cited work), so a
+    difference is a property of the *field*, not evidence about identity. `status`:
+      - ``ok``           value agrees with the canonical record (after normalization).
+      - ``formatting``   differs only in formatting/style — not a mistake, a cosmetic fix at most.
+      - ``error``        a genuine mistake (wrong, garbled, or empty/placeholder value).
+      - ``uncertain``    could not be classified confidently — surfaced for manual review.
+      - ``unverifiable`` the .bib has a value but no source returned this field to check it against.
+    """
+
+    field: str
+    bib_value: str = ""
+    canonical_value: str = ""
+    sources: list[str] = Field(default_factory=list)  # source(s) carrying the canonical value
+    status: Literal["ok", "formatting", "error", "uncertain", "unverifiable"]
+    detail: str = ""
+    via_llm: bool = False
+
+
+class CitationContext(BaseModel):
+    """One in-text citing occurrence of a `.bib` key: the surrounding sentence(s) that state *why*
+    the work is cited, plus where it occurred. Extracted offline from the `.tex` (and its includes).
+
+    A key cited in several places yields several contexts, each judged independently. `ordinal` is
+    the 0-based occurrence order for that key (stable, so findings are reproducible)."""
+
+    key: str
+    text: str                          # the citing sentence(s) — the claim attached to the citation
+    ordinal: int = 0
+    # The cite-family command used (cite / citep / citet / nocite). `bibr` marks a context recovered
+    # from a PDF, where the TEI marker `<ref type="bibr">` is all the provenance there is.
+    command: str = "cite"
+
+
+class AlignmentFinding(BaseModel):
+    """Citation-alignment check of one citing context against the cited work's abstract.
+
+    Runs only on an `exactly_one` match with a retrievable abstract. `status`:
+      - ``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 (NOT misuse; full text may support it).
+      - ``unverifiable``    no abstract available, the entry did not resolve, or the check failed.
+    A silent/absent abstract or any failure is NEVER reported as ``contradicted``.
+    """
+
+    key: str
+    context_text: str = ""             # the citing sentence(s) judged
+    ordinal: int = 0
+    status: Literal["supported", "contradicted", "not_in_abstract", "unverifiable"]
+    evidence_quote: str = ""           # the abstract span justifying a supported/contradicted call
+    detail: str = ""
+    confidence: Literal["high", "medium", "low"] = "low"
+    via_llm: bool = False
+
+
+class CandidateAssessment(BaseModel):
+    record: SourceRecord
+    features: FeatureVector
+    bucket: Literal["auto_accept", "auto_reject", "adjudicate"]
+    llm: CanCorrespondResult | None = None
+
+
+class MatchedArtifact(BaseModel):
+    """One real-world object an entry matched (possibly several merged source records)."""
+
+    records: list[SourceRecord] = Field(default_factory=list)
+    merged_ids: Identifiers = Field(default_factory=Identifiers)
+    versions: list[SourceRecord] = Field(default_factory=list)  # preprint + published / editions
+    best_record: SourceRecord | None = None
+
+
+class Verdict(BaseModel):
+    """README 5.1 / 5.2 / 5.3."""
+
+    kind: Literal["none", "exactly_one", "multiple"]
+    artifacts: list[MatchedArtifact] = Field(default_factory=list)
+    confidence: Literal["high", "medium", "low"] = "low"
+    rationale: str = ""
+
+
+class EntryAudit(BaseModel):
+    entry: BibEntry
+    candidates: list[CandidateAssessment] = Field(default_factory=list)
+    verdict: Verdict | None = None          # None until step-1 matching has run
+    field_findings: list[FieldFinding] = Field(default_factory=list)  # step 3 field correctness
+    alignment_findings: list[AlignmentFinding] = Field(default_factory=list)  # citation alignment
+    canonical_bibtex: str = ""              # step 3 (follow-on)
+    issues: list[str] = Field(default_factory=list)
+    # Why the verdict is None, one line per cause (a named source error, an LLM failure, an
+    # adjudication that stayed inconclusive). Empty once a verdict is reached. Each is also an issue.
+    unresolved_reasons: list[str] = Field(default_factory=list)
+    from_cache: bool = False
+
+
+class AuditReport(BaseModel):
+    entries: list[EntryAudit] = Field(default_factory=list)
+    cited_but_missing: list[str] = Field(default_factory=list)  # in .tex, absent from .bib
+    uncited: list[str] = Field(default_factory=list)            # in .bib, never cited
+    commented_twins: list[str] = Field(default_factory=list)    # informational (T1 context)
+    missing_includes: list[str] = Field(default_factory=list)   # \input targets not found on disk
+    unparsed: list[UnparsedEntry] = Field(default_factory=list)  # .bib entries that could not be read
+    summary: dict = Field(default_factory=dict)
+
+    # --- provenance of the input itself ---
+    # `pdf`: the entries and contexts were EXTRACTED by GROBID rather than read from authored source
+    # files, so several fields above change meaning. `commented_twins` and `missing_includes` are
+    # structurally inapplicable (a PDF has neither), and `uncited` depends on GROBID having linked
+    # in-text markers to bibliography items — hence `citation_linking`, which is `unavailable` when
+    # it linked none (bookkeeping is then unknown, not "everything is cited"). `notes` carries the
+    # document-level caveats the renderer must show so no reader mistakes an extraction artifact for
+    # an error in the manuscript. Defaults reproduce the .bib/.tex behavior exactly.
+    # `pdf_embedded`: the entries are the BibTeX records the PDF embeds for its cited works
+    # (`pdf.embedded`) — authored source like a .bib, every one of them cited, no citing contexts.
+    input_kind: Literal["tex_bib", "pdf", "pdf_embedded"] = "tex_bib"
+    citation_linking: Literal["available", "unavailable", "not_applicable"] = "available"
+    notes: list[str] = Field(default_factory=list)

reference_audit/parsing/__init__.py

@@ -0,0 +1 @@
+"""Parsing layer: .bib entries, .tex citations, and identifier normalization."""