ref-verify 1.1.2__py3-none-any.whl

ref_verify/cli.py

@@ -0,0 +1,162 @@
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from typing import Sequence
+
+from ref_verify.abstract_lookup import (
+    AbstractSourceClient,
+    lookup_abstract,
+    lookup_selected_abstract,
+)
+from ref_verify.claim_check import check_claim_support
+from ref_verify.crossref import CrossrefClient
+from ref_verify.doi_check import normalize_doi, verify_doi_metadata
+from ref_verify.models import CitationInput, ClaimSupportResult
+from ref_verify.pubmed import PubMedClient
+from ref_verify.semantic_scholar import SemanticScholarClient
+
+
+def main(
+    argv: Sequence[str] | None = None,
+    *,
+    client: CrossrefClient | None = None,
+    abstract_clients: Sequence[AbstractSourceClient] | None = None,
+) -> int:
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+    lookup_client = client or CrossrefClient()
+    fallback_clients = list(abstract_clients) if abstract_clients is not None else _default_abstract_clients()
+
+    try:
+        if args.command == "verify-doi":
+            return _verify_doi(args, lookup_client)
+        if args.command == "check-claim":
+            return _check_claim(args, lookup_client, fallback_clients)
+    except Exception as exc:
+        _emit({"error": str(exc)}, as_json=getattr(args, "json", False))
+        return 1
+
+    parser.print_help()
+    return 2
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="ref-verify",
+        description="Verify citation metadata and abstract-grounded claims.",
+    )
+    subparsers = parser.add_subparsers(dest="command")
+
+    verify = subparsers.add_parser("verify-doi", help="Check DOI metadata")
+    verify.add_argument("doi")
+    verify.add_argument("--title")
+    verify.add_argument("--first-author")
+    verify.add_argument("--year", type=int)
+    verify.add_argument("--json", action="store_true")
+
+    claim = subparsers.add_parser("check-claim", help="Check a claim against a DOI abstract")
+    claim.add_argument("doi")
+    claim.add_argument("--claim", required=True)
+    claim.add_argument(
+        "--source",
+        choices=("auto", "crossref", "semantic-scholar", "pubmed"),
+        default="auto",
+        help="Select an abstract source for debugging; default tries DOI-bound fallback sources.",
+    )
+    claim.add_argument("--json", action="store_true")
+
+    return parser
+
+
+def _verify_doi(args: argparse.Namespace, client: CrossrefClient) -> int:
+    lookup_doi = normalize_doi(args.doi)
+    fetched = client.fetch_work(lookup_doi)
+    provided = CitationInput(
+        doi=args.doi,
+        title=args.title,
+        first_author=args.first_author,
+        year=args.year,
+    )
+    result = verify_doi_metadata(provided, fetched)
+    _emit(result.to_dict(), as_json=args.json)
+    return 0 if result.verdict == "PASS" else 2
+
+
+def _check_claim(
+    args: argparse.Namespace,
+    client: CrossrefClient,
+    fallback_clients: Sequence[AbstractSourceClient],
+) -> int:
+    lookup_doi = normalize_doi(args.doi)
+    selected_clients = _select_abstract_clients(fallback_clients, args.source)
+    if args.source in ("auto", "crossref"):
+        fetched = client.fetch_work(lookup_doi)
+        lookup_result = lookup_abstract(lookup_doi, fetched, selected_clients)
+    else:
+        lookup_result = lookup_selected_abstract(lookup_doi, selected_clients)
+    if lookup_result.error_code == "DOI_MISMATCH":
+        result = ClaimSupportResult(
+            status="UNVERIFIABLE",
+            verdict="WARN",
+            reason="Fetched DOI does not match the requested DOI.",
+            evidence="",
+            paper=lookup_result.record,
+            claim=args.claim,
+        )
+        _emit(_claim_payload(result, lookup_result), as_json=args.json)
+        return 2
+
+    result = check_claim_support(lookup_result.record, args.claim)
+    _emit(_claim_payload(result, lookup_result), as_json=args.json)
+    return 0 if result.verdict == "ACCEPT" else 2
+
+
+def _claim_payload(result: ClaimSupportResult, lookup_result) -> dict:
+    payload = result.to_dict()
+    payload["abstract_source"] = lookup_result.abstract_source
+    payload["source_attempts"] = [attempt.to_dict() for attempt in lookup_result.attempts]
+    payload["error_code"] = lookup_result.error_code or _claim_error_code(result)
+    return payload
+
+
+def _claim_error_code(result: ClaimSupportResult) -> str:
+    if result.verdict == "ACCEPT":
+        return "CLAIM_SUPPORTED"
+    if result.status == "UNVERIFIABLE":
+        return "NO_ABSTRACT"
+    if result.status == "PARTIAL":
+        if "does not explicitly support" in result.reason:
+            return "CLAIM_NOT_EXPLICIT"
+        return "CLAIM_AMBIGUOUS"
+    return "CLAIM_NOT_EXPLICIT"
+
+
+def _default_abstract_clients() -> list[AbstractSourceClient]:
+    return [SemanticScholarClient(), PubMedClient()]
+
+
+def _select_abstract_clients(
+    fallback_clients: Sequence[AbstractSourceClient],
+    source: str,
+) -> Sequence[AbstractSourceClient]:
+    if source in ("auto", "crossref"):
+        return [] if source == "crossref" else fallback_clients
+    source_name = source.replace("-", "_")
+    return [client for client in fallback_clients if client.source_name == source_name]
+
+
+def _emit(payload: dict, *, as_json: bool) -> None:
+    if as_json:
+        print(json.dumps(payload, indent=2, sort_keys=True))
+        return
+    if "error" in payload:
+        print(f"ERROR: {payload['error']}")
+        return
+    for key, value in payload.items():
+        print(f"{key}: {value}")
+
+
+if __name__ == "__main__":
+    sys.exit(main())

ref_verify/crossref.py

@@ -0,0 +1,89 @@
+from __future__ import annotations
+
+import html
+import json
+import re
+from typing import Any
+from urllib.parse import quote
+from urllib.request import Request, urlopen
+
+from ref_verify import __version__
+from ref_verify.doi_check import normalize_doi
+from ref_verify.models import PaperRecord
+
+
+class CrossrefClient:
+    def __init__(self, timeout: float = 20.0) -> None:
+        self.timeout = timeout
+
+    def fetch_work(self, doi: str) -> PaperRecord:
+        encoded_doi = quote(normalize_doi(doi), safe="")
+        request = Request(
+            f"https://api.crossref.org/works/{encoded_doi}",
+            headers={
+                "User-Agent": (
+                    f"ref-verify/{__version__} "
+                    "(+https://github.com/Moonweave-Research/ref-verify)"
+                )
+            },
+        )
+        with urlopen(request, timeout=self.timeout) as response:
+            payload = json.loads(response.read().decode("utf-8"))
+        return parse_crossref_work(payload["message"])
+
+
+def parse_crossref_work(message: dict[str, Any]) -> PaperRecord:
+    doi = str(message.get("DOI") or "")
+    title = _first_string(message.get("title")) or "[title missing]"
+    authors = [
+        author_name
+        for author in message.get("author", [])
+        if (author_name := _crossref_author_name(author))
+    ]
+    year = _published_year(message)
+    journal = _first_string(message.get("container-title"))
+    abstract = _clean_abstract(message.get("abstract"))
+    url = message.get("URL")
+
+    return PaperRecord(
+        doi=doi,
+        title=title,
+        authors=authors,
+        year=year,
+        abstract=abstract,
+        source="CrossRef",
+        journal=journal,
+        url=str(url) if url else None,
+    )
+
+
+def _first_string(value: Any) -> str | None:
+    if isinstance(value, list) and value:
+        return str(value[0]).strip()
+    if isinstance(value, str) and value.strip():
+        return value.strip()
+    return None
+
+
+def _crossref_author_name(author: Any) -> str:
+    if not isinstance(author, dict):
+        return ""
+    family = str(author.get("family") or "").strip()
+    if family:
+        return family
+    return str(author.get("name") or "").strip()
+
+
+def _published_year(message: dict[str, Any]) -> int | None:
+    for key in ("published-print", "published-online", "published", "issued"):
+        date_parts = message.get(key, {}).get("date-parts")
+        if date_parts and date_parts[0]:
+            return int(date_parts[0][0])
+    return None
+
+
+def _clean_abstract(value: Any) -> str | None:
+    if not isinstance(value, str) or not value.strip():
+        return None
+    without_tags = re.sub(r"<[^>]+>", " ", value)
+    return re.sub(r"\s+", " ", html.unescape(without_tags)).strip()

ref_verify/doi_check.py

@@ -0,0 +1,191 @@
+from __future__ import annotations
+
+import re
+import unicodedata
+from urllib.parse import unquote
+
+from ref_verify.models import CitationInput, MetadataCheckResult, PaperRecord
+
+_GREEK_LETTER_NAMES = {
+    "\u03b1": "alpha",
+    "\u03b2": "beta",
+    "\u03b3": "gamma",
+    "\u03b4": "delta",
+    "\u03b5": "epsilon",
+    "\u03b6": "zeta",
+    "\u03b7": "eta",
+    "\u03b8": "theta",
+    "\u03b9": "iota",
+    "\u03ba": "kappa",
+    "\u03bb": "lambda",
+    "\u03bc": "mu",
+    "\u03bd": "nu",
+    "\u03be": "xi",
+    "\u03bf": "omicron",
+    "\u03c0": "pi",
+    "\u03c1": "rho",
+    "\u03c2": "sigma",
+    "\u03c3": "sigma",
+    "\u03c4": "tau",
+    "\u03c5": "upsilon",
+    "\u03c6": "phi",
+    "\u03c7": "chi",
+    "\u03c8": "psi",
+    "\u03c9": "omega",
+}
+
+_GROUP_AUTHOR_TERMS = {
+    "association",
+    "collaboration",
+    "committee",
+    "consortium",
+    "group",
+    "network",
+    "organisation",
+    "organization",
+    "society",
+    "team",
+    "working",
+}
+
+
+def verify_doi_metadata(
+    provided: CitationInput,
+    fetched: PaperRecord,
+) -> MetadataCheckResult:
+    mismatches: list[str] = []
+
+    if provided.doi and not doi_matches(provided.doi, fetched.doi):
+        mismatches.append("doi")
+
+    if not _has_comparison_metadata(provided):
+        mismatches.append("metadata")
+
+    if provided.title and not _titles_match(provided.title, fetched.title):
+        mismatches.append("title")
+
+    if provided.first_author and not _author_matches(
+        provided.first_author,
+        fetched.authors[0] if fetched.authors else None,
+    ):
+        mismatches.append("first_author")
+
+    if provided.year is not None and (
+        fetched.year is None or provided.year != fetched.year
+    ):
+        mismatches.append("year")
+
+    if not mismatches:
+        verdict = "PASS"
+        reason = "Provided citation metadata matches the fetched CrossRef record."
+    elif any(field in mismatches for field in ("doi", "title", "first_author")):
+        verdict = "REJECT"
+        reason = "DOI resolves to a materially different paper than provided."
+    elif "metadata" in mismatches:
+        verdict = "WARN"
+        reason = "Insufficient citation metadata was provided to verify the fetched CrossRef record."
+    else:
+        verdict = "WARN"
+        reason = "DOI resolves, but minor metadata differs from the provided citation."
+
+    return MetadataCheckResult(
+        verdict=verdict,
+        mismatches=mismatches,
+        reason=reason,
+        provided=provided,
+        fetched=fetched,
+    )
+
+
+def _has_comparison_metadata(provided: CitationInput) -> bool:
+    return bool(provided.title and provided.first_author)
+
+
+def doi_matches(provided: str, fetched: str) -> bool:
+    return normalize_doi(provided) == normalize_doi(fetched)
+
+
+def normalize_doi(value: str) -> str:
+    normalized = value.strip().casefold()
+    normalized = re.sub(r"^(?:https?://)?(?:dx\.)?doi\.org/", "", normalized)
+    normalized = re.sub(r"^doi:\s*", "", normalized)
+    normalized = unquote(normalized)
+    return _strip_trailing_doi_punctuation(normalized)
+
+
+def _strip_trailing_doi_punctuation(value: str) -> str:
+    stripped = value.strip()
+    while stripped:
+        without_sentence_punctuation = stripped.rstrip(".,;:")
+        if without_sentence_punctuation != stripped:
+            stripped = without_sentence_punctuation.rstrip()
+            continue
+        if stripped.endswith(")") and stripped.count(")") > stripped.count("("):
+            stripped = stripped[:-1].rstrip()
+            continue
+        return stripped
+    return stripped
+
+
+def _titles_match(provided: str, fetched: str) -> bool:
+    if _numbers(provided) != _numbers(fetched):
+        return False
+
+    return _title_tokens(provided) == _title_tokens(fetched)
+
+
+def _author_matches(provided: str, fetched: str | None) -> bool:
+    if not fetched:
+        return False
+    provided_tokens = _author_tokens(provided)
+    fetched_tokens = _author_tokens(fetched)
+    if not provided_tokens or not fetched_tokens:
+        return False
+    if _looks_like_group_author(provided_tokens) or _looks_like_group_author(
+        fetched_tokens,
+    ):
+        return provided_tokens == fetched_tokens
+    return provided_tokens[-1] == fetched_tokens[-1]
+
+
+def _author_tokens(value: str) -> list[str]:
+    normalized = _strip_diacritics(value.casefold())
+    cleaned = re.sub(r"[^a-z -]", " ", normalized).strip()
+    return [part for part in re.split(r"\s+", cleaned) if part]
+
+
+def _looks_like_group_author(tokens: list[str]) -> bool:
+    return bool(set(tokens) & _GROUP_AUTHOR_TERMS)
+
+
+def _numbers(value: str) -> list[str]:
+    return [
+        number.replace(",", "")
+        for number in re.findall(r"\d+(?:,\d{3})*(?:\.\d+)?", value)
+    ]
+
+
+def _title_tokens(value: str) -> list[str]:
+    normalized = _transliterate_greek_letters(_strip_diacritics(value.casefold()))
+    return [_singularize(token) for token in re.findall(r"[^\W_]+", normalized)]
+
+
+def _singularize(token: str) -> str:
+    if token.endswith("s") and len(token) > 3:
+        return token[:-1]
+    return token
+
+
+def _strip_diacritics(value: str) -> str:
+    return "".join(
+        char
+        for char in unicodedata.normalize("NFKD", value)
+        if not unicodedata.combining(char)
+    )
+
+
+def _transliterate_greek_letters(value: str) -> str:
+    return "".join(
+        f" {_GREEK_LETTER_NAMES[char]} " if char in _GREEK_LETTER_NAMES else char
+        for char in value
+    )

ref_verify/models.py

@@ -0,0 +1,89 @@
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass
+from typing import Any
+
+
+@dataclass(frozen=True)
+class CitationInput:
+    doi: str
+    title: str | None = None
+    first_author: str | None = None
+    year: int | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+
+@dataclass(frozen=True)
+class PaperRecord:
+    doi: str
+    title: str
+    authors: list[str]
+    year: int | None
+    abstract: str | None
+    source: str
+    journal: str | None = None
+    url: str | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+
+@dataclass(frozen=True)
+class MetadataCheckResult:
+    verdict: str
+    mismatches: list[str]
+    reason: str
+    provided: CitationInput
+    fetched: PaperRecord
+
+    def to_dict(self) -> dict[str, Any]:
+        payload = asdict(self)
+        payload["provided"] = self.provided.to_dict()
+        payload["fetched"] = self.fetched.to_dict()
+        return payload
+
+
+@dataclass(frozen=True)
+class ClaimSupportResult:
+    status: str
+    verdict: str
+    reason: str
+    evidence: str
+    paper: PaperRecord
+    claim: str
+
+    def to_dict(self) -> dict[str, Any]:
+        payload = asdict(self)
+        payload["paper"] = self.paper.to_dict()
+        return payload
+
+
+@dataclass(frozen=True)
+class AbstractSourceAttempt:
+    source: str
+    status: str
+    reason: str
+    record_id: str | None = None
+    doi: str | None = None
+    elapsed_ms: int | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+
+@dataclass(frozen=True)
+class AbstractLookupResult:
+    record: PaperRecord
+    abstract_source: str | None
+    attempts: list[AbstractSourceAttempt]
+    error_code: str | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "record": self.record.to_dict(),
+            "abstract_source": self.abstract_source,
+            "source_attempts": [attempt.to_dict() for attempt in self.attempts],
+            "error_code": self.error_code,
+        }