inscriber 0.1.0__py3-none-any.whl

inscriber/__init__.py

@@ -0,0 +1,6 @@
+"""inscriber — local-first PDF → LLM-friendly Markdown via llama.cpp.
+
+See DESIGN.md for the authoritative specification.
+"""
+
+__version__ = "0.1.0"

inscriber/__main__.py

@@ -0,0 +1,8 @@
+"""Enables ``python -m inscriber``."""
+
+import sys
+
+from inscriber.cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

inscriber/bibtex/__init__.py

@@ -0,0 +1 @@
+"""Optional, online BibTeX generation via Semantic Scholar (DESIGN §12)."""

inscriber/bibtex/arxiv.py

@@ -0,0 +1,127 @@
+"""arXiv sources for BibTeX auto mode (DESIGN §12).
+
+``arxiv_id_from_url`` extracts the arXiv ID from a source URL (provenance).
+``arxiv_bibtex`` is the export-API **availability fallback**: Semantic Scholar
+(which knows the *published* version of a preprint) is consulted first; the
+export API is authoritative for identification but can never know about later
+venue publication. ``format_arxiv_misc`` is the standard arXiv ``@misc`` +
+``eprint`` shape, shared with the chain's S2-preprint path.
+"""
+
+from __future__ import annotations
+
+import re
+from urllib.parse import urlparse
+from xml.etree import ElementTree
+
+import httpx
+from defusedxml import DefusedXmlException
+from defusedxml.ElementTree import fromstring as defused_fromstring
+
+from inscriber.bibtex.semantic_scholar import (
+    USER_AGENT,
+    generate_citation_key,
+    sanitize_bibtex_text,
+)
+from inscriber.input.domain_handlers import host_matches
+from inscriber.logging import get_logger
+
+logger = get_logger()
+
+API_URL = "https://export.arxiv.org/api/query"
+_ATOM = {"atom": "http://www.w3.org/2005/Atom", "arxiv": "http://arxiv.org/schemas/atom"}
+
+# The domain handler's FILENAME-RULE pattern shape (input/domain_handlers.py
+# ``_arxiv()``): it preserves ``v2``-style version suffixes and old-style
+# ``cs.AI/0301001`` IDs. (The handler's ``url_patterns`` detection regex is NOT
+# reusable here — its ``\d+\.\d+`` stops before the version suffix.)
+_ARXIV_ID_RE = re.compile(r"/(?:abs|pdf|html)/([\w.-]+/?\d+|\d+\.\d+)")
+
+
+def arxiv_id_from_url(url: str | None) -> str | None:
+    """The arXiv ID (version suffix preserved) from an arxiv.org URL, else None.
+
+    Host matching is by suffix (`host_matches`, DESIGN §6) — a lookalike host
+    must not be treated as arXiv *provenance* (citable by construction, §12.1).
+    """
+    if not url:
+        return None
+    parsed = urlparse(url)
+    if not host_matches(parsed.hostname or "", "arxiv.org"):
+        return None
+    m = _ARXIV_ID_RE.search(parsed.path)
+    return m.group(1) if m else None
+
+
+def format_arxiv_misc(
+    title: str,
+    authors: list[str],
+    year: str | None,
+    arxiv_id: str,
+    *,
+    primary_class: str | None = None,
+) -> str:
+    """The standard arXiv ``@misc`` + ``eprint`` shape (humble entry types)."""
+    key = generate_citation_key(title, authors, year)
+    fields = [f"  title={{{sanitize_bibtex_text(title)}}}"]
+    if authors:
+        fields.append(
+            "  author={" + " and ".join(sanitize_bibtex_text(a) for a in authors) + "}"
+        )
+    if year:
+        fields.append(f"  year={{{year}}}")
+    fields.append(f"  eprint={{{arxiv_id}}}")
+    fields.append("  archivePrefix={arXiv}")
+    if primary_class:
+        fields.append(f"  primaryClass={{{primary_class}}}")
+    fields.append(f"  url={{https://arxiv.org/abs/{arxiv_id}}}")
+    return f"@misc{{{key},\n" + ",\n".join(fields) + "\n}"
+
+
+def arxiv_bibtex(arxiv_id: str, *, timeout: float = 30.0) -> str | None:
+    """Fetch + format the arXiv entry by ID via the export API (Atom, parsed
+    with ``defusedxml`` — this is the one place remote XML is parsed, and the
+    stdlib parser is documented as unsafe for malicious input; DESIGN §12.1);
+    ``None`` on any HTTP/parse failure — log + fall through, mirroring
+    ``search_semantic_scholar``'s degrade style."""
+    try:
+        resp = httpx.get(
+            API_URL,
+            params={"id_list": arxiv_id},
+            timeout=timeout,
+            headers={"User-Agent": USER_AGENT},
+        )
+    except httpx.HTTPError as e:
+        logger.warning("arXiv API request failed: %s", e)
+        return None
+    if resp.status_code != 200:
+        logger.warning("arXiv API returned HTTP %d", resp.status_code)
+        return None
+    try:
+        # forbid_dtd on top of defusedxml's entity/external-reference defaults:
+        # Atom needs no DTD, so a payload carrying one is rejected outright.
+        root = defused_fromstring(resp.text, forbid_dtd=True)
+    except (ElementTree.ParseError, DefusedXmlException) as e:
+        logger.warning("arXiv API returned unparseable XML: %s", e)
+        return None
+    entry = root.find("atom:entry", _ATOM)
+    if entry is None:
+        return None
+    entry_id = entry.findtext("atom:id", default="", namespaces=_ATOM)
+    if "api/errors" in entry_id:  # arXiv reports a bad ID as an <entry> with an error id
+        logger.warning("arXiv API has no record for id %s", arxiv_id)
+        return None
+    raw_title = entry.findtext("atom:title", default="", namespaces=_ATOM)
+    title = re.sub(r"\s+", " ", raw_title).strip()
+    if not title:
+        return None
+    authors = []
+    for a in entry.findall("atom:author", _ATOM):
+        name = (a.findtext("atom:name", default="", namespaces=_ATOM) or "").strip()
+        if name:
+            authors.append(name)
+    published = entry.findtext("atom:published", default="", namespaces=_ATOM)
+    year = published[:4] if published[:4].isdigit() else None
+    primary = entry.find("arxiv:primary_category", _ATOM)
+    primary_class = primary.get("term") if primary is not None else None
+    return format_arxiv_misc(title, authors, year, arxiv_id, primary_class=primary_class)

inscriber/bibtex/chain.py

@@ -0,0 +1,104 @@
+"""BibTeX auto-mode orchestration: citability → ordered source chain (DESIGN §12).
+
+Citability: a URL matching **any of the seven recognized paper repositories**
+settles it — the probe never vetoes provenance (a disagreement is logged,
+nothing more). The probe governs only provenance-less documents, and it is
+abstain-biased: with a default-on feature, a false positive (an unwanted
+``.bib``) is worse than a false negative.
+
+Sources, in order (preprint provenance ≠ preprint citation — many preprints are
+later published at a venue): Semantic Scholar **by arXiv ID** (exact match;
+prefers the published version when one exists) → arXiv export API (``@misc``
+availability fallback) → Semantic Scholar title search → local best-effort.
+Any failure falls through; this module never raises (DESIGN §16: BibTeX never
+fails the run).
+"""
+
+from __future__ import annotations
+
+from inscriber.bibtex.arxiv import arxiv_bibtex, arxiv_id_from_url, format_arxiv_misc
+from inscriber.bibtex.local import best_effort_bibtex
+from inscriber.bibtex.probe import ProbeResult
+from inscriber.bibtex.semantic_scholar import (
+    _format_entry,
+    _mismatch_warning,
+    lookup_arxiv,
+    search_semantic_scholar,
+)
+from inscriber.input.domain_handlers import find_handler
+from inscriber.logging import get_logger
+
+logger = get_logger()
+
+
+def citable_provenance(url: str | None) -> bool:
+    """Whether ``url`` matches any of the seven recognized paper repositories
+    (the domain-handler configs, DESIGN §6) — citable by construction."""
+    if not url:
+        return False
+    return find_handler(url) is not None
+
+
+def _is_preprint_venue(venue) -> bool:
+    return not venue or str(venue).strip().lower().startswith("arxiv")
+
+
+def _s2_arxiv_entry(paper: dict, arxiv_id: str) -> str:
+    """Format an S2 by-ID record: a real publication venue → the published
+    ``@article`` shape (shared with the title-search path); no venue (or an
+    "arXiv.org"-style one) → the preprint ``@misc`` + ``eprint`` shape. No
+    title validation on this path — the ID match is exact."""
+    if not _is_preprint_venue(paper.get("venue")):
+        bibtex, _ = _format_entry(paper, paper.get("title", "") or "")
+        return bibtex
+    authors = [a.get("name", "") for a in paper.get("authors", []) if a.get("name")]
+    year = str(paper["year"]) if paper.get("year") else None
+    return format_arxiv_misc(paper.get("title", "") or "", authors, year, arxiv_id)
+
+
+def generate_bibtex_auto(
+    probe: ProbeResult | None,
+    *,
+    original_url: str | None,
+    online_allowed: bool,
+    fallback_title: str,
+    timeout: float = 30.0,
+) -> tuple[str | None, str]:
+    """Walk the auto-mode chain; returns ``(bibtex | None, source_label)``.
+
+    ``source_label`` ∈ {``s2-arxiv-id``, ``arxiv-export``, ``s2-title``,
+    ``best-effort``} on success; on a skip it is the reason
+    (``not-citable`` / ``unknown`` / ``no usable metadata``).
+    """
+    provenance = citable_provenance(original_url)
+    if provenance and probe is not None and not probe.citable:
+        logger.info(
+            "BibTeX (auto): probe judged the document not citable, but the source "
+            "URL is a recognized paper repository; provenance wins"
+        )
+    if not provenance and (probe is None or not probe.citable):
+        return None, "not-citable" if probe is not None else "unknown"
+
+    if online_allowed:
+        aid = arxiv_id_from_url(original_url)
+        if aid:
+            paper = lookup_arxiv(aid, timeout=timeout)
+            if paper:
+                return _s2_arxiv_entry(paper, aid), "s2-arxiv-id"
+            entry = arxiv_bibtex(aid, timeout=timeout)
+            if entry:
+                return entry, "arxiv-export"
+        # Title search; validation compares against the same string used as the
+        # query (avoids a spurious % WARNING from a mangled OCR `# Title`).
+        title = (probe.title if probe and probe.title else None) or fallback_title
+        results = search_semantic_scholar(title, timeout=timeout)
+        if results:
+            bibtex, matches = _format_entry(results[0], title)
+            if not matches:
+                bibtex = _mismatch_warning(title, results[0].get("title", "")) + bibtex
+            return bibtex, "s2-title"
+
+    entry = best_effort_bibtex(probe)
+    if entry:
+        return entry, "best-effort"
+    return None, "no usable metadata"

inscriber/bibtex/local.py

@@ -0,0 +1,39 @@
+"""Local best-effort BibTeX entry from probe-extracted front matter (DESIGN §12).
+
+The last link in the auto-mode source chain: a clearly-marked ``@misc`` entry
+assembled purely from what the probe transcribed off the document's first page.
+Fully offline — no citation database is consulted. Transcription, not recall
+(decision 5): absent fields are absent, never ``Unknown Journal``-style filler;
+the extracted venue goes in ``note``, not ``journal`` (decision 4 — no
+venue-type guessing).
+"""
+
+from __future__ import annotations
+
+from inscriber.bibtex.probe import ProbeResult
+from inscriber.bibtex.semantic_scholar import generate_citation_key, sanitize_bibtex_text
+
+# Canonical header (pinned by tests/fixtures/bibtex_best_effort.txt).
+BEST_EFFORT_HEADER = (
+    "% NOTE: Best-effort entry generated from the document's own front matter\n"
+    "% by inscriber (no citation database was consulted). Verify before use.\n"
+    "%\n"
+)
+
+
+def best_effort_bibtex(probe: ProbeResult | None) -> str | None:
+    """Assemble the marked ``@misc`` entry, or ``None`` when there is no usable
+    title (an entry without a title is noise, not a citation)."""
+    if probe is None or not probe.title:
+        return None
+    key = generate_citation_key(probe.title, probe.authors, probe.year)
+    fields = [f"  title={{{sanitize_bibtex_text(probe.title)}}}"]
+    if probe.authors:
+        fields.append(
+            "  author={" + " and ".join(sanitize_bibtex_text(a) for a in probe.authors) + "}"
+        )
+    if probe.year:
+        fields.append(f"  year={{{probe.year}}}")
+    if probe.venue:
+        fields.append(f"  note={{{sanitize_bibtex_text(probe.venue)}}}")
+    return BEST_EFFORT_HEADER + f"@misc{{{key},\n" + ",\n".join(fields) + "\n}"

inscriber/bibtex/probe.py

@@ -0,0 +1,125 @@
+"""BibTeX citability + metadata probe (DESIGN §12, auto mode).
+
+One **text-only** VLM call per document: is this a citable scholarly work, and
+what front-matter metadata is visible on its first page? The result drives the
+auto-mode source chain (``chain.py``) and the local best-effort entry
+(``local.py``).
+
+The prompt is pinned, model-facing behavior (the table-pass discipline,
+DESIGN §9.2): assembled exactly once per document via the backend
+(``build_bibtex_probe_prompt``), used verbatim as cache-key material AND as the
+request. Changes require re-validation on real hardware recorded in
+``dev/notes/2026-06-10-bibtex-probe-findings.md``. The phrase "bibliographic metadata" is
+the pinned mock-dispatch discriminator (AGENTS.md) and must survive any tuning.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass, field
+
+# Truncation cap on the page-1 text embedded in the prompt. Front matter
+# (title/authors/venue) fits comfortably; deliberately its own constant, NOT
+# the [figure].context_chars knob (that one is a figure-context setting).
+PROBE_PAGE_CHARS = 3000
+
+_CODE_FENCE_RE = re.compile(r"^```[A-Za-z]*\s*\n(?P<body>.*?)\n?```\s*$", re.DOTALL)
+
+# The pinned probe prompt. Citability is abstain-biased (decision 1: with a
+# default-on feature a false positive is worse than a false negative), and
+# extraction is transcription-not-recall (decision 5: only fields visible in
+# the supplied text; absent fields are omitted, never filled in).
+PROBE_PROMPT_TEMPLATE = """You are extracting bibliographic metadata from the first page of a document.
+
+First decide whether the document is CITABLE: a self-contained scholarly work \
+— a research paper, preprint, thesis, or technical report — whose title and \
+authors are identifiable in the text below. Slides, lecture notes, invoices, \
+forms, manuals, web pages, and other non-scholarly documents are NOT citable. \
+When unsure, answer "citable": false.
+
+Then extract the metadata fields that are VISIBLE in the text. Copy them \
+exactly as written; do not guess and do not recall from memory. Omit any field \
+that is not visible in the text.
+
+Answer with a single JSON object and nothing else, in this shape:
+{{"citable": true, "title": "...", "authors": ["...", "..."], "year": "...", "venue": "..."}}
+
+- "citable": required boolean.
+- "title": the document's full title, when visible.
+- "authors": the list of author names, when visible.
+- "year": the publication year, when visible.
+- "venue": the journal, conference, or repository name, when visible.
+
+First page text:
+<page_text>
+{page_text}
+</page_text>"""
+
+
+@dataclass
+class ProbeResult:
+    """The parsed probe answer (front-matter metadata + citability verdict)."""
+
+    citable: bool
+    title: str | None = None
+    authors: list[str] = field(default_factory=list)
+    year: str | None = None
+    venue: str | None = None
+    raw: str = ""  # the model's JSON (fence-stripped), for debugging + caching
+
+
+def format_probe_prompt(page_text: str) -> str:
+    """Assemble the full probe prompt — also the probe cache key material."""
+    text = page_text.strip()
+    if len(text) > PROBE_PAGE_CHARS:
+        text = text[: PROBE_PAGE_CHARS - 3] + "..."
+    return PROBE_PROMPT_TEMPLATE.format(page_text=text)
+
+
+def parse_probe_response(raw: str | None) -> ProbeResult | None:
+    """Parse + type-check a probe response; ``None`` means "treat as unknown".
+
+    Tolerates a wrapping code fence (like the table pass's sanitizer); otherwise
+    strict: a single JSON object with a boolean ``citable`` and correctly-typed
+    optional fields. Anything malformed → ``None`` (and the caller must NOT
+    cache it).
+    """
+    if not raw:
+        return None
+    text = raw.strip()
+    fence = _CODE_FENCE_RE.match(text)
+    if fence:
+        text = fence.group("body").strip()
+    try:
+        data = json.loads(text)
+    except ValueError:
+        return None
+    if not isinstance(data, dict) or not isinstance(data.get("citable"), bool):
+        return None
+
+    title = data.get("title")
+    if title is not None and not isinstance(title, str):
+        return None
+    authors = data.get("authors", [])
+    if authors is None:
+        authors = []
+    if not isinstance(authors, list) or not all(isinstance(a, str) for a in authors):
+        return None
+    year = data.get("year")
+    if isinstance(year, int):  # tolerate a bare-number year
+        year = str(year)
+    if year is not None and not isinstance(year, str):
+        return None
+    venue = data.get("venue")
+    if venue is not None and not isinstance(venue, str):
+        return None
+
+    return ProbeResult(
+        citable=data["citable"],
+        title=title.strip() or None if title else None,
+        authors=[a.strip() for a in authors if a.strip()],
+        year=year.strip() or None if year else None,
+        venue=venue.strip() or None if venue else None,
+        raw=text,
+    )

inscriber/bibtex/semantic_scholar.py

@@ -0,0 +1,224 @@
+"""BibTeX generation via Semantic Scholar (DESIGN §12) — optional & online.
+
+Ported from paper2llm ``core/utils/bibtex-generator.ts`` + ``content-utils.ts``:
+title→entry lookup, citation key, title validation, and the mock fallback. The
+inscriber **standardizes on the single 4-line mismatch warning** (DESIGN §12) and
+**adds a clean 429 / network degrade path** (the source had none).
+"""
+
+from __future__ import annotations
+
+import re
+from datetime import datetime, timezone
+
+import httpx
+
+from inscriber.logging import get_logger
+
+logger = get_logger()
+
+API_URL = "https://api.semanticscholar.org/graph/v1/paper/search"
+LOOKUP_API_URL = "https://api.semanticscholar.org/graph/v1/paper/arXiv:{arxiv_id}"
+FIELDS = "title,authors,venue,year,abstract,externalIds,url"
+USER_AGENT = "inscriber/0.1 (+https://github.com/lacerbi/inscriber)"
+
+_SKIP_WORDS = {"a", "an", "the", "on", "in", "of", "for", "and", "or"}
+
+
+def _current_year() -> str:
+    return str(datetime.now(timezone.utc).year)
+
+
+def _today() -> str:
+    return datetime.now(timezone.utc).strftime("%Y-%m-%d")
+
+
+def sanitize_bibtex_text(text: str) -> str:
+    """Escape BibTeX special characters (port of ``sanitizeBibTeXText``)."""
+    if not text:
+        return ""
+    text = re.sub(r"[&%$#_{}~^\\\s]", lambda m: m.group() if m.group() == " " else "\\" + m.group(), text)
+    text = text.replace("“", "``").replace("”", "``")  # curly double quotes
+    text = text.replace("‘", "''").replace("’", "''")  # curly single quotes
+    text = text.replace("—", "---").replace("–", "--")  # em / en dash
+    return text
+
+
+def generate_citation_key(title: str, authors: list[str], year: str | None) -> str:
+    """``{firstAuthorLastName}{year}{firstSubstantiveTitleWord}`` (DESIGN §12)."""
+    author_part = "Unknown"
+    if authors:
+        author_part = authors[0].split(" ")[-1].lower()
+
+    title_part = ""
+    title_words = title.split(" ")
+    for word in title_words:
+        clean = re.sub(r"[^a-z0-9]", "", word.lower())
+        if len(clean) > 2 and clean not in _SKIP_WORDS:
+            title_part = clean
+            break
+    if not title_part and title_words:
+        title_part = re.sub(r"[^a-z0-9]", "", title_words[0].lower())
+
+    year_part = year or _current_year()
+    return f"{author_part}{year_part}{title_part}"
+
+
+def normalize_title(title: str) -> str:
+    """lower → strip all but ``[a-z\\s]`` → collapse whitespace → trim (DESIGN §12).
+
+    Whitespace is preserved through the strip and collapsed afterward (matching the
+    TS ``normalizeTitleForComparison``), so an embedded tab/newline keeps words apart
+    rather than fusing them.
+    """
+    if not title:
+        return ""
+    s = re.sub(r"[^a-z\s]", "", title.lower())
+    return re.sub(r"\s+", " ", s).strip()
+
+
+def titles_match(original: str, bibtex_title: str) -> bool:
+    """Validate a retrieved title vs the paper title (DESIGN §12)."""
+    no, nb = normalize_title(original), normalize_title(bibtex_title)
+    if len(no) < 10 or len(nb) < 10:
+        return no == nb  # short titles require exact normalized match
+    orig_words = no.split(" ")
+    bib_words = set(nb.split(" "))
+    common = sum(1 for w in orig_words if w in bib_words)
+    similarity = common / max(len(orig_words), len(bib_words))
+    return similarity > 0.75
+
+
+def search_semantic_scholar(title: str, *, limit: int = 3, timeout: float = 30.0) -> list[dict]:
+    """Query Semantic Scholar; return ``data`` (or ``[]`` on any error/429)."""
+    try:
+        resp = httpx.get(
+            API_URL,
+            params={"query": title, "limit": limit, "fields": FIELDS},
+            timeout=timeout,
+            headers={"User-Agent": USER_AGENT},
+        )
+    except httpx.HTTPError as e:
+        logger.warning("Semantic Scholar request failed: %s; using fallback citation", e)
+        return []
+    if resp.status_code == 429:
+        logger.warning("Semantic Scholar rate-limited (HTTP 429); using fallback citation")
+        return []
+    if resp.status_code != 200:
+        logger.warning("Semantic Scholar returned HTTP %d; using fallback citation", resp.status_code)
+        return []
+    try:
+        return resp.json().get("data", []) or []
+    except ValueError:
+        logger.warning("Semantic Scholar returned non-JSON; using fallback citation")
+        return []
+
+
+def strip_arxiv_version(arxiv_id: str) -> str:
+    """``2510.18234v2`` → ``2510.18234`` (Semantic Scholar indexes the base ID)."""
+    return re.sub(r"v\d+$", "", arxiv_id)
+
+
+def lookup_arxiv(arxiv_id: str, *, timeout: float = 30.0) -> dict | None:
+    """Look a paper up by arXiv ID — an exact match, no title fuzziness; the
+    record carries the publication venue when one exists (the auto chain
+    prefers the published version of a preprint). ``None`` on any error / 429 /
+    no record (never raises)."""
+    url = LOOKUP_API_URL.format(arxiv_id=strip_arxiv_version(arxiv_id))
+    try:
+        resp = httpx.get(
+            url,
+            params={"fields": FIELDS},
+            timeout=timeout,
+            headers={"User-Agent": USER_AGENT},
+        )
+    except httpx.HTTPError as e:
+        logger.warning("Semantic Scholar arXiv lookup failed: %s", e)
+        return None
+    if resp.status_code == 429:
+        logger.warning("Semantic Scholar rate-limited (HTTP 429) on arXiv lookup")
+        return None
+    if resp.status_code == 404:
+        logger.info("Semantic Scholar has no record for arXiv:%s", arxiv_id)
+        return None
+    if resp.status_code != 200:
+        logger.warning("Semantic Scholar arXiv lookup returned HTTP %d", resp.status_code)
+        return None
+    try:
+        data = resp.json()
+    except ValueError:
+        logger.warning("Semantic Scholar arXiv lookup returned non-JSON")
+        return None
+    if not isinstance(data, dict) or not data.get("title"):
+        return None
+    return data
+
+
+def _format_entry(paper: dict, original_title: str) -> tuple[str, bool]:
+    """Format a Semantic Scholar paper as BibTeX; return ``(bibtex, title_matches)``."""
+    authors = [a.get("name", "") for a in paper.get("authors", [])]
+    year = str(paper["year"]) if paper.get("year") else None
+    bib_title = paper.get("title", "") or ""
+    key = generate_citation_key(bib_title, authors, year)
+
+    fields = [f"  title={{{sanitize_bibtex_text(bib_title)}}}"]
+    if authors:
+        fields.append("  author={" + " and ".join(sanitize_bibtex_text(a) for a in authors) + "}")
+    else:
+        fields.append("  author={Unknown}")
+    if year:
+        fields.append(f"  year={{{year}}}")
+    if paper.get("venue"):
+        fields.append(f"  journal={{{sanitize_bibtex_text(paper['venue'])}}}")
+    doi = (paper.get("externalIds") or {}).get("DOI")
+    if doi:
+        fields.append(f"  doi={{{doi}}}")
+    if paper.get("url"):
+        fields.append(f"  url={{{paper['url']}}}")
+
+    bibtex = f"@article{{{key},\n" + ",\n".join(fields) + "\n}"
+    return bibtex, titles_match(original_title, bib_title)
+
+
+def _mismatch_warning(original: str, bibtex_title: str) -> str:
+    # The standardized 4-line form (DESIGN §12); note the trailing "% " line.
+    return (
+        "% WARNING: The retrieved citation title may not match the paper title.\n"
+        f'% Paper title: "{original}"\n'
+        f'% Citation title: "{bibtex_title}"\n'
+        "% \n"
+    )
+
+
+def mock_bibtex(title: str, *, date: str | None = None, year: str | None = None) -> str:
+    """The canonical fallback mock entry (DESIGN §12; review Fix 6)."""
+    return (
+        "% WARNING: This is a fallback mock citation.\n"
+        "% BibTeX generation failed to find this paper in academic databases.\n"
+        "% Please replace with the correct citation if available.\n"
+        "%\n"
+        f"% Generated: {date or _today()}\n"
+        "@article{unknownYear,\n"
+        f"  title={{{title}}},\n"
+        "  author={Unknown Author},\n"
+        "  journal={Unknown Journal},\n"
+        f"  year={{{year or _current_year()}}},\n"
+        "  note={This is an automatically generated fallback citation}\n"
+        "}"
+    )
+
+
+def generate_bibtex(title: str, *, timeout: float = 30.0, date: str | None = None) -> str:
+    """Generate a BibTeX string for ``title`` (DESIGN §12).
+
+    On a confident match → the formatted entry. On a title mismatch → the entry
+    prefixed with the 4-line warning. On no result / API error / 429 → the mock
+    fallback (never raises — BibTeX never fails the whole run).
+    """
+    results = search_semantic_scholar(title, timeout=timeout)
+    if results:
+        bibtex, matches = _format_entry(results[0], title)
+        if not matches:
+            bibtex = _mismatch_warning(title, results[0].get("title", "")) + bibtex
+        return bibtex
+    return mock_bibtex(title, date=date)