claimcite 0.1.0__py3-none-any.whl

claimcite/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

claimcite/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from .cli import main
+
+sys.exit(main())

claimcite/cache.py

@@ -0,0 +1,118 @@
+"""On-disk cache for registry responses. Standard library only.
+
+Wraps the ``http_get(url) -> str`` callable: successful responses are stored by
+URL (which encodes registry + identifier), so a second run after a one-line edit
+does not repeat every request. Lookup failures are never written.
+
+The cache is best-effort: if the directory or database cannot be used (read-only
+home, full disk, locked file), requests go straight to the network.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import sqlite3
+import sys
+import time
+import zlib
+from collections.abc import Callable
+from pathlib import Path
+
+DB_NAME = "cache.sqlite3"
+DEFAULT_TTL_DAYS = 30
+# Credentials must not be written to disk, and changing them must not empty the cache.
+_SECRET_PARAM = re.compile(r"[?&]api_key=[^&]*")
+
+
+def cache_key(url: str) -> str:
+    return _SECRET_PARAM.sub("", url)
+
+
+def default_cache_dir() -> Path:
+    """Honour XDG_CACHE_HOME; fall back to ~/.cache/claimcite/v1."""
+    base = os.environ.get("XDG_CACHE_HOME")
+    return (Path(base) if base else Path.home() / ".cache") / "claimcite" / "v1"
+
+
+class CachedHttp:
+    """A thread-safe, file-backed wrapper around an HTTP callable."""
+
+    def __init__(
+        self,
+        http: Callable[[str], str],
+        cache_dir: Path | None = None,
+        ttl_days: float = DEFAULT_TTL_DAYS,
+    ):
+        self.http = http
+        self.cache_dir = cache_dir if cache_dir is not None else default_cache_dir()
+        self.ttl = ttl_days * 86400
+        self.enabled = True
+        try:
+            self._init_db()
+        except (OSError, sqlite3.Error) as e:
+            self._disable(e)
+
+    def _disable(self, error: Exception) -> None:
+        if self.enabled:
+            print(f"claimcite: cache disabled ({error})", file=sys.stderr)
+        self.enabled = False
+
+    @property
+    def db_path(self) -> Path:
+        return self.cache_dir / DB_NAME
+
+    def _connect(self) -> sqlite3.Connection:
+        return sqlite3.connect(self.db_path, timeout=5.0)
+
+    def _init_db(self) -> None:
+        self.cache_dir.mkdir(parents=True, exist_ok=True)
+        db = self._connect()
+        try:
+            db.execute(
+                "CREATE TABLE IF NOT EXISTS responses ("
+                "url TEXT PRIMARY KEY, body BLOB NOT NULL, fetched_at REAL NOT NULL)"
+            )
+            db.commit()
+        finally:
+            db.close()
+
+    def __call__(self, url: str) -> str:
+        if not self.enabled:
+            return self.http(url)
+        key = cache_key(url)
+        try:
+            db = self._connect()
+            try:
+                row = db.execute("SELECT body, fetched_at FROM responses WHERE url = ?", (key,)).fetchone()
+            finally:
+                db.close()
+        except sqlite3.Error as e:
+            self._disable(e)
+            return self.http(url)
+        if row is not None and time.time() - row[1] <= self.ttl:
+            body = row[0]
+            # Bodies are stored compressed; plain text rows are from before that change.
+            if not isinstance(body, bytes):
+                return body
+            try:
+                return zlib.decompress(body).decode("utf-8")
+            except (zlib.error, UnicodeDecodeError):
+                pass  # damaged row: fetch again and overwrite it
+
+        # Exceptions propagate untouched: a failed lookup is never cached.
+        body = self.http(url)
+
+        try:
+            db = self._connect()
+            try:
+                db.execute(
+                    "INSERT OR REPLACE INTO responses (url, body, fetched_at) VALUES (?, ?, ?)",
+                    (key, zlib.compress(body.encode("utf-8")), time.time()),
+                )
+                db.commit()
+            finally:
+                db.close()
+        except sqlite3.Error as e:
+            self._disable(e)
+        return body

claimcite/check.py

@@ -0,0 +1,82 @@
+"""Compare what the document says about each citation with what the registry says."""
+
+from __future__ import annotations
+
+from concurrent.futures import ThreadPoolExecutor
+from difflib import SequenceMatcher
+
+from .evidence import UNKNOWN, evidence_level
+from .extract import extract_references
+from .models import Finding, Reference
+from .sources import Lookup, LookupFailed
+from .text import CJK as _CJK
+from .text import quote_found
+from .text import words as _words
+from .web import check_page
+
+
+def compare_titles(stated: str | None, actual: str | None) -> str:
+    if not stated:
+        return "not_stated"
+    if not actual:
+        return "unknown"
+    if _CJK.search(stated) and not _CJK.search(actual):
+        return "not_comparable"
+    a, b = _words(stated), _words(actual)
+    ratio = SequenceMatcher(None, a, b).ratio()
+    if ratio >= 0.9 or (len(a) > 20 and (a in b or b in a)):
+        return "match"
+    if ratio >= 0.6:
+        return "partial"
+    return "mismatch"
+
+
+def check_reference(ref: Reference, lookup: Lookup, web: bool = True) -> Finding:
+    if ref.kind == "url" and not web:
+        return Finding(ref, status="unchecked")
+    if ref.kind == "url":
+        result = check_page(ref, lookup.http)
+        status = {"alive": "ok", "dead": "warning", "blocked": "unchecked", "failed": "unchecked"}[
+            result.state
+        ]
+        if result.state == "alive" and any(ok is False for _, ok in result.quotes):
+            status = "warning"
+        return Finding(ref, status=status, web=result)
+
+    try:
+        record = lookup.doi(ref.id) if ref.kind == "doi" else lookup.pmid(ref.id)
+    except LookupFailed as e:
+        return Finding(ref, status="unchecked", error=str(e))
+    if record is None:
+        return Finding(ref, status="error", exists=False)
+
+    f = Finding(ref, status="ok", exists=True, record=record)
+    f.title_match = compare_titles(ref.title, record.title)
+    years = record.years or ([record.year] if record.year else [])
+    if ref.year and years:
+        # Papers have online, print and issue years; any of them, give or take one, is fine.
+        f.year_match = any(abs(ref.year - y) <= 1 for y in years)
+    text = " ".join(filter(None, [record.title, record.abstract]))
+    f.quotes = [(q, quote_found(q, record.abstract and text)) for q in ref.quotes]
+    f.evidence = (
+        evidence_level(record.pub_types, record.humans, record.animals)
+        if record.source == "pubmed"
+        else UNKNOWN
+    )
+
+    if f.title_match == "mismatch":
+        f.status = "error"
+    elif f.title_match == "partial" or f.year_match is False or any(ok is False for _, ok in f.quotes):
+        f.status = "warning"
+    return f
+
+
+def check_text(text: str, lookup: Lookup | None = None, web: bool = True) -> list[Finding]:
+    lookup = lookup or Lookup()
+    refs = extract_references(text)
+    lookup.prefetch(
+        dois=[r.id for r in refs if r.kind == "doi"], pmids=[r.id for r in refs if r.kind == "pmid"]
+    )
+    # Registry lookups are already batched above; this mainly runs web-page fetches side by side.
+    with ThreadPoolExecutor(max_workers=lookup.workers) as pool:
+        return list(pool.map(lambda ref: check_reference(ref, lookup, web), refs))

claimcite/cli.py

@@ -0,0 +1,63 @@
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from . import __version__
+from .cache import CachedHttp, default_cache_dir
+from .check import check_text
+from .net import http_get
+from .report import to_json, to_markdown
+from .sources import Lookup
+
+FAIL_ON = {"error": {"error"}, "warning": {"error", "warning"}, "never": set()}
+
+
+def make_lookup(no_cache: bool = False) -> Lookup:
+    http = http_get if no_cache else CachedHttp(http_get, default_cache_dir())
+    return Lookup(http=http)
+
+
+def main(argv: list[str] | None = None) -> int:
+    p = argparse.ArgumentParser(prog="claimcite", description="Check the citations in a document.")
+    p.add_argument("--version", action="version", version=f"claimcite {__version__}")
+    sub = p.add_subparsers(dest="command", required=True)
+    c = sub.add_parser("check", help="check Markdown or text files ('-' reads stdin)")
+    c.add_argument("paths", nargs="+", metavar="path")
+    c.add_argument("--format", choices=["md", "json"], default="md")
+    c.add_argument("--lang", choices=["en", "zh"], default="en")
+    c.add_argument(
+        "--fail-on",
+        choices=list(FAIL_ON),
+        default="error",
+        help="exit with 1 when any finding has this status (default: error)",
+    )
+    c.add_argument("--no-cache", action="store_true", help="bypass the on-disk lookup cache for this run")
+    c.add_argument("--no-web", action="store_true", help="do not fetch web pages; check DOIs and PMIDs only")
+    args = p.parse_args(argv)
+
+    lookup = make_lookup(no_cache=args.no_cache)
+    several = len(args.paths) > 1
+    failed, reports = False, []
+    for path in args.paths:
+        text = sys.stdin.read() if path == "-" else Path(path).read_text(encoding="utf-8")
+        findings = check_text(text, lookup, web=not args.no_web)
+        failed |= any(f.status in FAIL_ON[args.fail_on] for f in findings)
+        if args.format == "json":
+            reports.append({"path": path, **json.loads(to_json(findings))})
+        else:
+            print(f"## {path}\n" if several else "", to_markdown(findings, args.lang), sep="")
+    if args.format == "json":
+        if several:
+            total = {k: sum(r["summary"][k] for r in reports) for k in reports[0]["summary"]}
+            print(json.dumps({"summary": total, "files": reports}, ensure_ascii=False, indent=2))
+        else:
+            reports[0].pop("path")
+            print(json.dumps(reports[0], ensure_ascii=False, indent=2))
+    return 1 if failed else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

claimcite/evidence.py

@@ -0,0 +1,47 @@
+"""Study design from PubMed publication types. A rough guide, not a quality appraisal."""
+
+from __future__ import annotations
+
+from .models import Evidence
+
+META = Evidence("meta_analysis", 1, "Systematic review / meta-analysis", "系统综述 / 荟萃分析")
+GUIDELINE = Evidence("guideline", 1, "Clinical guideline", "临床指南")
+RCT = Evidence("rct", 2, "Randomized controlled trial", "随机对照试验")
+TRIAL = Evidence("clinical_trial", 3, "Clinical trial (not randomized)", "临床试验（非随机）")
+OBSERVATIONAL = Evidence("observational", 4, "Observational study", "观察性研究")
+CASE = Evidence("case_report", 5, "Case report", "病例报告")
+REVIEW = Evidence("narrative_review", 5, "Narrative review", "叙述性综述")
+OPINION = Evidence("opinion", 6, "Editorial / comment / letter", "社论 / 评论 / 通信")
+ANIMAL = Evidence("animal", 6, "Animal study", "动物研究")
+UNKNOWN = Evidence("unknown", 9, "Not classified", "未分类")
+
+_BY_TYPE = [
+    (META, {"Meta-Analysis", "Systematic Review"}),
+    (GUIDELINE, {"Practice Guideline", "Guideline", "Consensus Development Conference"}),
+    (RCT, {"Randomized Controlled Trial", "Pragmatic Clinical Trial", "Equivalence Trial"}),
+    (
+        TRIAL,
+        {
+            "Clinical Trial",
+            "Controlled Clinical Trial",
+            "Clinical Trial, Phase I",
+            "Clinical Trial, Phase II",
+            "Clinical Trial, Phase III",
+            "Clinical Trial, Phase IV",
+        },
+    ),
+    (OBSERVATIONAL, {"Observational Study", "Twin Study"}),
+    (CASE, {"Case Reports"}),
+    (REVIEW, {"Review"}),
+    (OPINION, {"Editorial", "Comment", "Letter"}),
+]
+
+
+def evidence_level(pub_types: list[str], humans: bool, animals: bool) -> Evidence:
+    types = set(pub_types)
+    if animals and not humans:
+        return ANIMAL
+    for evidence, names in _BY_TYPE:
+        if types & names:
+            return evidence
+    return UNKNOWN

claimcite/extract.py

@@ -0,0 +1,150 @@
+"""Find citations in plain text / Markdown and the metadata the author wrote next to them.
+
+Supported citation forms:
+  - DOI: https://doi.org/10.x/y, doi:10.x/y, or a bare 10.x/y
+  - PMID: "PMID: 123" or https://pubmed.ncbi.nlm.nih.gov/123
+  - any other http(s) link (fetched and checked for availability and quoted text)
+
+The text between two citations on the same line is treated as the description of the
+second one, e.g. ``Author (2020). Title. Journal：「quoted words」. <https://doi.org/...>``
+
+Numbered citations work too: a quote in the body followed by ``[1]``, ``[^note]``, ``[1, 2]`` or ``[1-3]``
+is checked against the reference-list entry with that label (``[1] …``, ``1. …`` or ``[^note]: …``).
+"""
+
+from __future__ import annotations
+
+import re
+
+from .models import Reference
+
+_ASCII_TOKEN = r"[^\s<>\"'\u0080-\uffff]+"
+# No re.I here: case-folding would make the non-ASCII exclusion also drop "s" and "k" (ſ, K).
+DOI_RE = re.compile(r"(?i:https?://(?:dx\.)?doi\.org/|\bdoi:\s*)?\b(10\.\d{4,9}/" + _ASCII_TOKEN + ")")
+PMID_RE = re.compile(
+    r"\bPMID:?\s*(\d{1,9})\b|https?://pubmed\.ncbi\.nlm\.nih\.gov/(\d{1,9})/?", re.IGNORECASE
+)
+URL_RE = re.compile(r"https?://" + _ASCII_TOKEN)
+
+YEAR_RE = re.compile(r"\((\d{4})(?:-\d{1,2}(?:-\d{1,2})?)?[a-z]?\)")
+TITLE_RE = re.compile(r"\(\d{4}[^)]*\)\.\s*(.+?)(?:\.\s|\.?\s*$|[：:]\s*[「“\"])")
+# "Journal of X, 41(2), 181-202": the author gave the journal, not the title.
+JOURNAL_ONLY = re.compile(r"^[^.?!]{3,150},\s*\d+\s*(?:\(\d+\))?\s*(?:,\s*[eE]?\d+(?:[-–]\d+)?)?$")
+# "Is it true? Psychological Science, 26": title ends at the question mark.
+TITLE_THEN_JOURNAL = re.compile(r"^(.+?[?!])\s+[A-Z][^?!]*,\s*\d+.*$")
+QUOTE_RES = [re.compile(r"「(.+?)」"), re.compile(r"“(.+?)”"), re.compile(r"\"([^\"]{4,}?)\"")]
+LEADING_NOISE = re.compile(
+    r"^(?:\s|[；;,，、]|（[^）]*）|\([^)]*\)(?=\s*[；;])|[-*]\s*|来源[：:]|Sources?:)+", re.IGNORECASE
+)
+
+# A reference-list entry: "[1] …", "[^note]: …", "1. …" or "1) …" at the start of a line.
+DEF_RE = re.compile(r"^\s*(?:\[(\^?[\w-]+)\]:?|(\d{1,3})[.)])\s+")
+# A marker in the body: [1], [^note], [1, 2], [1-3]. Not a Markdown link "[x](…)", "[x][y]" or "[x]:".
+MARK_RE = re.compile(r"\[(\^[\w-]+|\d{1,3}(?:\s*[-–,]\s*\d{1,3})*)\](?![(:\[])")
+FENCE_RE = re.compile(r"^\s*(```|~~~)")
+INLINE_CODE_RE = re.compile(r"`[^`]*`")
+SENTENCE_END = re.compile(r"[。！？!?]|\.(?=\s)")
+
+_TRAILING = ".,;:!?"
+
+
+def _clean_id(raw: str) -> str:
+    raw = raw.rstrip(_TRAILING)
+    while raw.endswith(")") and raw.count(")") > raw.count("("):
+        raw = raw[:-1].rstrip(_TRAILING)
+    return raw
+
+
+def _describe(segment: str) -> tuple[int | None, str | None, list[str], str]:
+    seg = LEADING_NOISE.sub("", segment).rstrip(" <[(")
+    year_m = YEAR_RE.search(seg)
+    title_m = TITLE_RE.search(seg)
+    title = title_m.group(1).strip().rstrip(".") if title_m else None
+    if title and JOURNAL_ONLY.match(title):
+        title = None
+    elif title and (m := TITLE_THEN_JOURNAL.match(title)):
+        title = m.group(1)
+    quotes = []
+    for rx in QUOTE_RES:
+        quotes += [q.strip() for q in rx.findall(seg)]
+    if title and any(title == q or q in title for q in quotes):
+        title = None
+    return (int(year_m.group(1)) if year_m else None), title or None, quotes, seg.strip()
+
+
+def extract_references(text: str) -> list[Reference]:
+    refs: list[Reference] = []
+    for lineno, line in enumerate(text.splitlines(), start=1):
+        hits: list[tuple[int, int, str, str]] = []  # start, end, kind, id
+        for m in DOI_RE.finditer(line):
+            hits.append((m.start(), m.end(), "doi", _clean_id(m.group(1)).lower()))
+        for m in PMID_RE.finditer(line):
+            if not any(s <= m.start() < e for s, e, *_ in hits):
+                hits.append((m.start(), m.end(), "pmid", m.group(1) or m.group(2)))
+        for m in URL_RE.finditer(line):
+            if not any(s <= m.start() < e or m.start() <= s < m.end() for s, e, *_ in hits):
+                hits.append((m.start(), m.end(), "url", _clean_id(m.group(0))))
+        hits.sort()
+        prev_end = 0
+        for start, end, kind, ident in hits:
+            year, title, quotes, ctx = _describe(line[prev_end:start])
+            refs.append(Reference(kind, ident, lineno, year, title, quotes, ctx))
+            prev_end = end
+    _attach_numbered_quotes(text, refs)
+    return refs
+
+
+def _labels(raw: str) -> list[str]:
+    """``1-3`` -> 1, 2, 3; ``1, 4`` -> 1, 4; ``^note`` -> ^note."""
+    if raw.startswith("^"):
+        return [raw]
+    out: list[str] = []
+    for part in re.split(r"\s*,\s*", raw):
+        m = re.fullmatch(r"(\d+)\s*[-–]\s*(\d+)", part)
+        if m and 0 < int(m[2]) - int(m[1]) < 50:
+            out += [str(i) for i in range(int(m[1]), int(m[2]) + 1)]
+        else:
+            out.append(part.strip())
+    return out
+
+
+def _quotes_before(line: str, start: int, end: int) -> list[str]:
+    """Quotes in the sentence that the marker at ``end`` closes, not earlier than ``start``."""
+    spans = sorted(
+        (m.start(), m.end(), m.group(1).strip()) for rx in QUOTE_RES for m in rx.finditer(line, start, end)
+    )
+    for m in SENTENCE_END.finditer(line, start, end):
+        inside = any(s <= m.start() < e for s, e, _ in spans)
+        if not inside and line[m.end() : end].strip():
+            start = m.end()  # a sentence ended before the marker; its quotes belong to something else
+    return [q for s, _, q in spans if s >= start]
+
+
+def _attach_numbered_quotes(text: str, refs: list[Reference]) -> None:
+    lines = text.splitlines()
+    by_label: dict[str, Reference] = {}
+    defs: set[int] = set()
+    for lineno, line in enumerate(lines, start=1):
+        m = DEF_RE.match(line)
+        first = next((r for r in refs if r.line == lineno), None)
+        if m and first:
+            by_label.setdefault(m.group(1) or m.group(2), first)
+            defs.add(lineno)
+    if not by_label:
+        return
+    fenced = False
+    for lineno, line in enumerate(lines, start=1):
+        if FENCE_RE.match(line):
+            fenced = not fenced
+            continue
+        if fenced or lineno in defs:
+            continue
+        line = INLINE_CODE_RE.sub(lambda m: " " * len(m.group(0)), line)  # `x[1]` is code, not a citation
+        prev = 0
+        for m in MARK_RE.finditer(line):
+            quotes = _quotes_before(line, prev, m.start())
+            prev = m.end()
+            for label in _labels(m.group(1)):
+                ref = by_label.get(label)
+                if ref:
+                    ref.quotes += [q for q in quotes if q not in ref.quotes]

claimcite/models.py

@@ -0,0 +1,64 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass
+class Reference:
+    """One citation as written in the document."""
+
+    kind: str  # "doi" | "pmid" | "url"
+    id: str  # normalised DOI (lower case), PMID digits, or the URL
+    line: int
+    year: int | None = None
+    title: str | None = None  # title as the author wrote it
+    quotes: list[str] = field(default_factory=list)  # text the author says comes from the source
+    context: str = ""  # the citation text this was parsed from
+
+
+@dataclass
+class Record:
+    """What a registry (PubMed, Crossref) says the identifier points to."""
+
+    source: str
+    title: str | None = None
+    year: int | None = None
+    years: list[int] = field(default_factory=list)  # every known publication year (online, print, issue)
+    doi: str | None = None
+    pmid: str | None = None
+    abstract: str | None = None
+    pub_types: list[str] = field(default_factory=list)
+    humans: bool = False
+    animals: bool = False
+
+
+@dataclass(frozen=True)
+class Evidence:
+    key: str
+    rank: int  # lower = stronger study design
+    label_en: str
+    label_zh: str
+
+
+@dataclass
+class WebResult:
+    """What a web-page lookup found (issue #1)."""
+
+    state: str  # "alive" | "dead" | "blocked" | "failed"
+    status_code: int | None = None
+    detail: str | None = None
+    quotes: list[tuple[str, bool | None]] = field(default_factory=list)
+
+
+@dataclass
+class Finding:
+    ref: Reference
+    status: str  # "ok" | "warning" | "error" | "unchecked"
+    exists: bool | None = None
+    record: Record | None = None
+    title_match: str = "not_stated"  # match | partial | mismatch | not_stated | not_comparable | unknown
+    year_match: bool | None = None
+    quotes: list[tuple[str, bool | None]] = field(default_factory=list)
+    evidence: Evidence | None = None
+    error: str | None = None  # set when a registry could not be reached
+    web: WebResult | None = None

claimcite/net.py

@@ -0,0 +1,61 @@
+"""The only place that touches the network. Swap `http_get` out in tests."""
+
+from __future__ import annotations
+
+import threading
+import time
+import urllib.error
+import urllib.request
+from urllib.parse import urlparse
+
+from . import __version__
+
+USER_AGENT = f"claimcite/{__version__} (+https://github.com/wasabihu/claimcite)"
+
+# NCBI allows 3 requests/second without an API key; be polite to everyone.
+_MIN_INTERVAL = {"eutils.ncbi.nlm.nih.gov": 0.4}
+_next_slot: dict[str, float] = {}
+_lock = threading.Lock()
+# Web pages are fetched from many sites that did not sign up for this; one request a second each.
+WEB_INTERVAL = 1.0
+# Registry answers are small; anything bigger is a download we do not need in full.
+MAX_BYTES = 10 * 1024 * 1024
+
+
+def polite(host: str, interval: float = WEB_INTERVAL) -> None:
+    """Rate-limit a host that has no explicit limit yet."""
+    with _lock:
+        _MIN_INTERVAL.setdefault(host, interval)
+
+
+class NotFound(Exception):
+    """The server answered 404."""
+
+
+def http_get(url: str, timeout: float = 20.0, retries: int = 3) -> str:
+    host = urlparse(url).netloc
+    for attempt in range(retries + 1):
+        with _lock:  # reserve the next free slot for this host, safe across threads
+            now = time.monotonic()
+            slot = max(now, _next_slot.get(host, 0))
+            _next_slot[host] = slot + _MIN_INTERVAL.get(host, 0)
+        if slot > now:
+            time.sleep(slot - now)
+        req = urllib.request.Request(url, headers={"User-Agent": USER_AGENT})
+        try:
+            with urllib.request.urlopen(req, timeout=timeout) as resp:
+                return resp.read(MAX_BYTES).decode("utf-8", errors="replace")
+        except urllib.error.HTTPError as e:
+            if e.code == 404:
+                raise NotFound(url) from e
+            if e.code in (429, 500, 502, 503, 504) and attempt < retries:
+                retry_after = e.headers.get("Retry-After", "") if e.headers else ""
+                time.sleep(max(2**attempt, int(retry_after) if retry_after.isdigit() else 0))
+                continue
+            raise
+        except urllib.error.URLError:
+            if attempt < retries:
+                time.sleep(2**attempt)
+                continue
+            raise
+    raise RuntimeError("unreachable")

claimcite/report.py

@@ -0,0 +1,157 @@
+from __future__ import annotations
+
+import json
+from collections import Counter
+
+from .models import Finding
+
+STATUSES = ("ok", "warning", "error", "unchecked")
+
+LABELS = {
+    "en": {
+        "title": "Citation check",
+        "summary": "{ok} ok · {warning} warnings · {error} errors · {unchecked} not checked",
+        "ok": "OK",
+        "warning": "Warning",
+        "error": "Error",
+        "unchecked": "Not checked",
+        "line": "line",
+        "missing": "Identifier does not exist",
+        "title_mismatch": "Title does not match this identifier. Registry title: {t}",
+        "title_partial": "Title only partly matches. Registry title: {t}",
+        "year": "Year differs: document {a}, registry {b}",
+        "quote_missing": "Quoted text not found in the abstract (it may be in the full text): “{q}”",
+        "quote_unknown": "No abstract available to check the quote: “{q}”",
+        "web": "Web page: not verified yet",
+        "web_alive": "Web page is reachable",
+        "web_dead": "Web page could not be opened (HTTP {code})",
+        "web_blocked": "Skipped: robots.txt disallows automated fetching",
+        "web_failed": "Web page lookup failed ({e}); not checked",
+        "web_quote_missing": "Quoted text not found on the page: “{q}”",
+        "web_quote_unknown": "Could not read the page text (e.g. a PDF); quoted text not checked: “{q}”",
+        "failed": "Lookup failed, try again later ({e})",
+        "evidence": "Study type (as tagged by PubMed)",
+        "disclaimer": "Automated check. It confirms that sources exist and match; it does not judge "
+        "whether a claim is true and is not medical advice.",
+    },
+    "zh": {
+        "title": "引用核查",
+        "summary": "通过 {ok} · 警告 {warning} · 错误 {error} · 未核查 {unchecked}",
+        "ok": "通过",
+        "warning": "警告",
+        "error": "错误",
+        "unchecked": "未核查",
+        "line": "第 {n} 行",
+        "missing": "编号不存在",
+        "title_mismatch": "标题与该编号对应的文献不符。登记的标题：{t}",
+        "title_partial": "标题只部分吻合。登记的标题：{t}",
+        "year": "年份不一致：文中 {a}，登记 {b}",
+        "quote_missing": "引文在摘要中没有找到（可能在全文里）：「{q}」",
+        "quote_unknown": "没有摘要，无法核对引文：「{q}」",
+        "web": "网页链接：暂不核查",
+        "web_alive": "网页可访问",
+        "web_dead": "网页打不开（HTTP {code}）",
+        "web_blocked": "已跳过：robots.txt 不允许自动抓取",
+        "web_failed": "网页查询失败（{e}），未核查",
+        "web_quote_missing": "页面正文中未找到引文：「{q}」",
+        "web_quote_unknown": "读不到页面文字（比如 PDF），引文未核对：「{q}」",
+        "failed": "查询失败，请稍后重试（{e}）",
+        "evidence": "研究类型（PubMed 标注）",
+        "disclaimer": "自动核查只确认出处存在且对得上，不判断说法本身是否正确，也不构成医疗建议。",
+    },
+}
+
+
+def summary(findings: list[Finding]) -> dict[str, int]:
+    c = Counter(f.status for f in findings)
+    return {s: c.get(s, 0) for s in STATUSES}
+
+
+def _problems(f: Finding, L: dict[str, str]) -> list[str]:
+    if f.ref.kind == "url":
+        w = f.web
+        if w is None:
+            return [L["web"]]
+        if w.state == "blocked":
+            return [L["web_blocked"]]
+        if w.state == "failed":
+            return [L["web_failed"].format(e=w.detail or "error")]
+        if w.state == "dead":
+            return [L["web_dead"].format(code=w.status_code or "?")]
+        out = [L["web_alive"]]
+        out += [L["web_quote_missing"].format(q=q) for q, ok in w.quotes if ok is False]
+        out += [L["web_quote_unknown"].format(q=q) for q, ok in w.quotes if ok is None]
+        return out
+    if f.error:
+        return [L["failed"].format(e=f.error)]
+    if f.exists is False:
+        return [L["missing"]]
+    out = []
+    title = f.record.title if f.record else None
+    if f.title_match == "mismatch":
+        out.append(L["title_mismatch"].format(t=title))
+    elif f.title_match == "partial":
+        out.append(L["title_partial"].format(t=title))
+    if f.year_match is False:
+        out.append(L["year"].format(a=f.ref.year, b=f.record.year))
+    for q, ok in f.quotes:
+        if ok is False:
+            out.append(L["quote_missing"].format(q=q))
+        elif ok is None:
+            out.append(L["quote_unknown"].format(q=q))
+    return out
+
+
+def to_markdown(findings: list[Finding], lang: str = "en") -> str:
+    L = LABELS[lang]
+    lines = [f"# {L['title']}", "", L["summary"].format(**summary(findings)), ""]
+    for f in findings:
+        where = L["line"].format(n=f.ref.line) if lang == "zh" else f"{L['line']} {f.ref.line}"
+        lines.append(f"- **{L[f.status]}** · {where} · `{f.ref.kind}:{f.ref.id}`")
+        if f.record and f.record.title:
+            lines.append(f"  - {f.record.title} ({f.record.year or '?'})")
+        if f.evidence and f.evidence.key != "unknown":
+            label = f.evidence.label_zh if lang == "zh" else f.evidence.label_en
+            lines.append(f"  - {L['evidence']}{'：' if lang == 'zh' else ': '}{label}")
+        lines += [f"  - {p}" for p in _problems(f, L)]
+    lines += ["", f"_{L['disclaimer']}_", ""]
+    return "\n".join(lines)
+
+
+def to_json(findings: list[Finding]) -> str:
+    def one(f: Finding) -> dict:
+        r = f.record
+        return {
+            "kind": f.ref.kind,
+            "id": f.ref.id,
+            "line": f.ref.line,
+            "status": f.status,
+            "exists": f.exists,
+            "stated": {"title": f.ref.title, "year": f.ref.year, "quotes": f.ref.quotes},
+            "registry": None
+            if r is None
+            else {
+                "source": r.source,
+                "title": r.title,
+                "year": r.year,
+                "doi": r.doi,
+                "pmid": r.pmid,
+                "publication_types": r.pub_types,
+            },
+            "title_match": f.title_match,
+            "year_match": f.year_match,
+            "quotes": [{"text": q, "found_in_abstract": ok} for q, ok in f.quotes],
+            "evidence": f.evidence.key if f.evidence else None,
+            "error": f.error,
+            "web": None
+            if f.web is None
+            else {
+                "state": f.web.state,
+                "status_code": f.web.status_code,
+                "quotes": [{"text": q, "found": ok} for q, ok in f.web.quotes],
+            },
+        }
+
+    return json.dumps(
+        {"summary": summary(findings), "findings": [one(f) for f in findings]}, ensure_ascii=False, indent=2
+    )

claimcite/sources.py

@@ -0,0 +1,209 @@
+"""Look identifiers up in public registries.
+
+- doi.org handle API: does the DOI exist at all (any registrar)?
+- PubMed E-utilities: title, year, abstract, publication types (biomedical papers)
+- Crossref: title and year for DOIs that are not in PubMed
+"""
+
+from __future__ import annotations
+
+import html
+import json
+import os
+import re
+import xml.etree.ElementTree as ET
+from collections.abc import Callable
+from concurrent.futures import ThreadPoolExecutor
+from urllib.parse import quote
+
+from .models import Record
+from .net import NotFound, http_get
+
+EUTILS = "https://eutils.ncbi.nlm.nih.gov/entrez/eutils"
+_TAG = re.compile(r"<[^>]+>")
+
+
+def _text(el: ET.Element | None) -> str | None:
+    if el is None:
+        return None
+    return re.sub(r"\s+", " ", "".join(el.itertext())).strip() or None
+
+
+def parse_pubmed(xml: str) -> dict[str, Record]:
+    out: dict[str, Record] = {}
+    for art in ET.fromstring(xml).iter("PubmedArticle"):
+        pmid = art.findtext("MedlineCitation/PMID")
+        if not pmid:
+            continue
+        year = art.findtext(".//Article/Journal/JournalIssue/PubDate/Year") or art.findtext(
+            ".//Article/ArticleDate/Year"
+        )
+        if not year:
+            medline = art.findtext(".//PubDate/MedlineDate") or ""
+            year = medline[:4] if medline[:4].isdigit() else None
+        years = []
+        for y in (year, art.findtext(".//Article/ArticleDate/Year")):
+            if y and int(y) not in years:
+                years.append(int(y))
+        doi = next(
+            (i.text for i in art.iterfind("PubmedData/ArticleIdList/ArticleId") if i.get("IdType") == "doi"),
+            None,
+        ) or next((e.text for e in art.iter("ELocationID") if e.get("EIdType") == "doi"), None)
+        abstract = " ".join(filter(None, (_text(a) for a in art.iter("AbstractText")))) or None
+        mesh = {d.text for d in art.iter("DescriptorName")}
+        out[pmid] = Record(
+            source="pubmed",
+            title=_text(art.find(".//Article/ArticleTitle")),
+            year=int(year) if year else None,
+            years=years,
+            doi=doi.lower() if doi else None,
+            pmid=pmid,
+            abstract=abstract,
+            pub_types=[p.text for p in art.iter("PublicationType") if p.text],
+            humans="Humans" in mesh,
+            animals="Animals" in mesh,
+        )
+    return out
+
+
+def clean_markup(s: str | None) -> str | None:
+    """Crossref titles and abstracts carry JATS/HTML markup, sometimes escaped twice."""
+    if not s:
+        return None
+    s = html.unescape(html.unescape(s))
+    s = re.sub(r"<xref\b[^>]*>.*?</xref>", "", s, flags=re.DOTALL)  # footnote markers
+    s = re.sub(r"\s*(<su[bp]\b)", r"\1", s)  # "D <sub>3</sub>" -> "D3"
+    s = re.sub(r"<(?:jats:)?(?:p|title|sec)\b[^>]*>", " ", s)  # block tags separate words
+    return re.sub(r"\s+", " ", _TAG.sub("", s)).strip() or None
+
+
+def parse_crossref(payload: str) -> Record:
+    msg = json.loads(payload)["message"]
+    years = []
+    for key in ("issued", "published-print", "published-online", "published"):
+        y = ((msg.get(key) or {}).get("date-parts") or [[None]])[0][0]
+        if y and y not in years:
+            years.append(y)
+    return Record(
+        source="crossref",
+        title=clean_markup((msg.get("title") or [None])[0]),
+        year=years[0] if years else None,
+        years=years,
+        doi=(msg.get("DOI") or "").lower() or None,
+        abstract=clean_markup(msg.get("abstract")),
+    )
+
+
+class LookupFailed(Exception):
+    """A registry could not be reached; the citation is neither confirmed nor refuted."""
+
+
+def _chunks(items: list[str], size: int):
+    for i in range(0, len(items), size):
+        yield items[i : i + size]
+
+
+def _safe(fn):
+    def run(arg):
+        try:
+            return fn(arg)
+        except Exception as e:  # noqa: BLE001 - one bad lookup must not sink the whole report
+            return LookupFailed(f"{type(e).__name__}: {e}")
+
+    return run
+
+
+class Lookup:
+    """Resolves DOIs and PMIDs to Records, with an in-memory cache.
+
+    Call `prefetch` with everything in a document first: it batches PubMed requests
+    (NCBI allows 3 requests/second) and runs the other registries in parallel.
+    """
+
+    def __init__(self, http: Callable[[str], str] = http_get, workers: int = 8):
+        self.http = http
+        self.workers = workers
+        self._cache: dict[tuple[str, str], Record | LookupFailed | None] = {}
+        key = os.environ.get("NCBI_API_KEY")
+        self._ncbi_key = f"&api_key={key}" if key else ""
+
+    def doi(self, doi: str) -> Record | None:
+        return self._get("doi", doi)
+
+    def pmid(self, pmid: str) -> Record | None:
+        return self._get("pmid", pmid)
+
+    def _get(self, kind: str, ident: str) -> Record | None:
+        if (kind, ident) not in self._cache:
+            self.prefetch(**{f"{kind}s": [ident]})
+        value = self._cache[(kind, ident)]
+        if isinstance(value, LookupFailed):
+            raise value
+        return value
+
+    def prefetch(self, dois: list[str] = (), pmids: list[str] = ()) -> None:
+        dois = [d for d in dict.fromkeys(dois) if ("doi", d) not in self._cache]
+        pmids = [p for p in dict.fromkeys(pmids) if ("pmid", p) not in self._cache]
+        if not dois and not pmids:
+            return
+
+        # 1. Does each DOI exist at all? doi.org knows every registrar.
+        with ThreadPoolExecutor(self.workers) as pool:
+            exists = dict(zip(dois, pool.map(_safe(self._doi_exists), dois)))
+        live = []
+        for d, e in exists.items():
+            if e is True:
+                live.append(d)
+            else:
+                self._cache[("doi", d)] = e if isinstance(e, LookupFailed) else None
+
+        # 2. PubMed, in batches: DOIs -> PMIDs, then one efetch for all PMIDs.
+        records: dict[str, Record] = {}
+        pubmed_error = None
+        try:
+            ids = list(pmids)
+            for chunk in _chunks(live, 40):
+                term = quote(" OR ".join(f"{d}[doi]" for d in chunk), safe="")
+                found = json.loads(
+                    self.http(
+                        f"{EUTILS}/esearch.fcgi?db=pubmed&term={term}&retmode=json&retmax=200{self._ncbi_key}"
+                    )
+                )
+                ids += found.get("esearchresult", {}).get("idlist", [])
+            for chunk in _chunks(list(dict.fromkeys(ids)), 150):
+                records.update(
+                    parse_pubmed(
+                        self.http(
+                            f"{EUTILS}/efetch.fcgi?db=pubmed&id={','.join(chunk)}&retmode=xml{self._ncbi_key}"
+                        )
+                    )
+                )
+        except Exception as e:  # noqa: BLE001
+            pubmed_error = LookupFailed(f"PubMed: {type(e).__name__}: {e}")
+
+        for p in pmids:
+            self._cache[("pmid", p)] = records.get(p) if pubmed_error is None else pubmed_error
+        by_doi = {r.doi: r for r in records.values() if r.doi}
+        rest = [d for d in live if d not in by_doi]
+        for d in live:
+            if d in by_doi:
+                self._cache[("doi", d)] = by_doi[d]
+
+        # 3. Everything else: Crossref, in parallel.
+        with ThreadPoolExecutor(self.workers) as pool:
+            for d, r in zip(rest, pool.map(_safe(self._crossref), rest)):
+                self._cache[("doi", d)] = r
+
+    def _doi_exists(self, doi: str) -> bool:
+        try:
+            handle = json.loads(self.http(f"https://doi.org/api/handles/{quote(doi, safe='/')}"))
+        except NotFound:
+            return False
+        return handle.get("responseCode") == 1
+
+    def _crossref(self, doi: str) -> Record:
+        try:
+            return parse_crossref(self.http(f"https://api.crossref.org/works/{quote(doi, safe='/')}"))
+        except NotFound:
+            # Registered (e.g. DataCite, CNKI) but no metadata we can read yet.
+            return Record(source="doi.org", doi=doi)

claimcite/text.py

@@ -0,0 +1,34 @@
+"""Shared text normalisation for both registry and web-page checks."""
+
+from __future__ import annotations
+
+import re
+import unicodedata
+
+CJK = re.compile(r"[\u3400-\u9fff]")
+ELLIPSIS = re.compile(r"\s*(?:…+|\.\.\.+)\s*")
+
+
+def norm(s: str) -> str:
+    s = unicodedata.normalize("NFKC", s).lower().replace("·", ".").replace("×", "x")
+    s = re.sub(r"[‐-―−]", "-", s)
+    return re.sub(r"\s+", " ", s).strip()
+
+
+def words(s: str) -> str:
+    return re.sub(r"[^\w]+", " ", norm(s)).strip()
+
+
+def letters(s: str) -> str:
+    """Only letters and digits: quotation-mark style, punctuation and spacing differ
+    between a page and a faithful quote of it (“ vs ", "26 个" vs "26个", "( NSAIDs )")."""
+    return re.sub(r"[\W_]+", "", norm(s))
+
+
+def quote_found(quote: str, haystack: str | None) -> bool | None:
+    """True/False when we could look, None when there was nothing to look in."""
+    if not haystack:
+        return None
+    hay = letters(haystack)
+    parts = [letters(part) for part in ELLIPSIS.split(quote)]
+    return all(part in hay for part in parts if part)

claimcite/web.py

@@ -0,0 +1,93 @@
+"""Check web-page citations: is the page alive, and does it contain the quoted text?
+
+Deliberately conservative: a dead link or a missing quote is a *warning*, never an
+error. Pages change, some sites block bots, and we must not cry wolf.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from html.parser import HTMLParser
+from typing import ClassVar
+from urllib.parse import urlparse, urlunparse
+from urllib.robotparser import RobotFileParser
+
+from .models import Reference, WebResult
+from .net import USER_AGENT, NotFound, polite
+from .text import quote_found
+
+
+class _TextExtractor(HTMLParser):
+    """Collect visible text, skipping script/style/noscript/template bodies."""
+
+    _SKIP: ClassVar[set[str]] = {"script", "style", "noscript", "template"}
+
+    def __init__(self) -> None:
+        super().__init__(convert_charrefs=True)
+        self.parts: list[str] = []
+        self._depth = 0
+
+    def handle_starttag(self, tag, attrs):
+        if tag.lower() in self._SKIP:
+            self._depth += 1
+
+    def handle_endtag(self, tag):
+        if tag.lower() in self._SKIP and self._depth:
+            self._depth -= 1
+
+    def handle_data(self, data):
+        if not self._depth:
+            self.parts.append(data)
+
+    def text(self) -> str:
+        return " ".join(" ".join(self.parts).split())
+
+
+def _robots_url(url: str) -> str:
+    p = urlparse(url)
+    return urlunparse((p.scheme, p.netloc, "/robots.txt", "", "", ""))
+
+
+def _robots_allows(url: str, http: Callable[[str], str]) -> bool:
+    """Only an explicit disallow blocks us; a missing robots.txt never does."""
+    try:
+        body = http(_robots_url(url))
+    except Exception:  # noqa: BLE001 - an unreachable robots.txt must not block the check
+        return True
+    parser = RobotFileParser()
+    try:
+        parser.parse(body.splitlines())
+    except Exception:  # noqa: BLE001 - malformed robots.txt is treated as absent
+        return True
+    return parser.can_fetch(USER_AGENT, url)
+
+
+def _is_binary(body: str) -> bool:
+    """PDFs and other downloads: we cannot read their text yet, so do not search them."""
+    head = body.lstrip("\ufeff \t\r\n")[:1024]
+    return head.startswith("%PDF-") or "\x00" in head
+
+
+def check_page(ref: Reference, http: Callable[[str], str]) -> WebResult:
+    unknown = [(q, None) for q in ref.quotes]
+    polite(urlparse(ref.id).netloc)
+    if not _robots_allows(ref.id, http):
+        return WebResult(state="blocked", quotes=unknown)
+    try:
+        body = http(ref.id)
+    except NotFound:
+        return WebResult(state="dead", status_code=404, quotes=unknown)
+    except Exception as e:  # noqa: BLE001 - one bad page must not sink the whole report
+        return WebResult(state="failed", detail=type(e).__name__, quotes=unknown)
+
+    if _is_binary(body):
+        return WebResult(state="alive", detail="binary", quotes=unknown)
+
+    parser = _TextExtractor()
+    try:
+        parser.feed(body)
+        page_text = parser.text()
+    except Exception:  # noqa: BLE001 - malformed HTML: fall back to the raw text
+        page_text = body
+    quotes = [(q, quote_found(q, page_text)) for q in ref.quotes]
+    return WebResult(state="alive", quotes=quotes)

claimcite-0.1.0.dist-info/METADATA

@@ -0,0 +1,155 @@
+Metadata-Version: 2.5
+Name: claimcite
+Version: 0.1.0
+Summary: Check that every citation in a document is real, matches what the text says it is, and supports the quoted words.
+Project-URL: Homepage, https://github.com/wasabihu/claimcite
+Project-URL: Issues, https://github.com/wasabihu/claimcite/issues
+Project-URL: Changelog, https://github.com/wasabihu/claimcite/blob/main/CHANGELOG.md
+License-Expression: MIT
+License-File: LICENSE
+Keywords: citation,crossref,doi,evidence-based,fact-checking,hallucination,pubmed
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
+Classifier: Topic :: Text Processing
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# claimcite
+
+**English** · [中文](README.zh-CN.md)
+
+Check that every citation in a document is real, points to the paper the text says it does, and actually contains the words quoted from it.
+
+AI-written articles, health advice and even papers increasingly cite sources that don't exist, or attach a real DOI to the wrong paper. Readers can't check dozens of references by hand. claimcite does it in one command.
+
+```console
+$ claimcite check examples/sample.md
+# Citation check
+
+1 ok · 2 warnings · 2 errors · 0 not checked
+
+- **Error** · line 7 · `doi:10.1016/s0140-6736(10)61388-8`
+  - Title does not match this identifier. Registry title: Worldwide burden of disease from
+    exposure to second-hand smoke: a retrospective analysis of data from 192 countries.
+  - Year differs: document 2021, registry 2011
+- **Error** · line 9 · `doi:10.1001/jama.2022.99999`
+  - Identifier does not exist
+- **Warning** · line 11 · `pmid:33237064`
+  - Study type (as tagged by PubMed): Systematic review / meta-analysis
+  - Quoted text not found in the abstract (it may be in the full text): “calcium and vitamin D
+    supplementation cured osteoporosis in all women”
+...
+```
+
+## What it checks today
+
+| Check | How |
+|---|---|
+| The DOI / PMID exists | doi.org handle API (every registrar), PubMed |
+| The title written in the text matches the identifier | PubMed, then Crossref; fuzzy match |
+| The year matches (±1 for online-first vs print) | same |
+| Text in quotes (`"…"`, `“…”`, `「…」`) appears in the abstract | PubMed / Crossref abstract |
+| Study type: meta-analysis, RCT, observational, animal… | PubMed publication types and MeSH |
+| A web link is alive and contains the quoted text | fetch the page (respecting `robots.txt`), strip HTML, normalise whitespace |
+
+It reads Markdown or plain text and understands the common
+`Author (Year). Title. Journal: "quote". https://doi.org/…` pattern, plus `doi:…`, bare DOIs,
+`PMID: …` and PubMed links. Numbered citations work too: a quote in the text followed by `[1]`, `[^1]`,
+`[1, 2]` or `[1-3]` is checked against the matching entry in the reference list (`[1] …`, `1. …` or
+`[^1]: …`). Code blocks and inline code are skipped. Other web links are fetched (respecting `robots.txt`) and checked for
+availability and for the quoted text. A dead link or a missing quote is a **warning**, never an error —
+pages change and some sites block bots. When a page cannot be read the link stays *not checked*.
+
+**What it does not do (yet):** decide whether a source *supports* a claim. That needs a language model and a
+labelled test set. See the roadmap. claimcite only confirms that sources exist and match what the text says
+about them. It is not medical advice.
+
+## Install and run
+
+Requires Python 3.10+. No API keys needed.
+
+```bash
+pipx install claimcite                   # or: uv tool install claimcite
+claimcite check article.md               # Markdown report
+claimcite check article.md --lang zh     # 中文报告
+claimcite check article.md --format json # for scripts and CI
+cat article.md | claimcite check -
+```
+
+The exit code is 1 when any citation has an error, so it works as a CI gate (`--fail-on warning|never` to tune).
+Set `NCBI_API_KEY` to raise PubMed's rate limit.
+
+### Lookup cache
+
+Successful registry responses are cached on disk for **30 days** (default `~/.cache/claimcite/v1/`,
+or `$XDG_CACHE_HOME/claimcite/v1/`), so re-running after a one-line edit does not repeat every
+request. Lookup failures are never cached. Use `--no-cache` to bypass the cache for one run.
+
+Web pages are fetched at most once a second per site, so the first run over a document with hundreds of
+links takes minutes. Use `--no-web` to check only DOIs and PMIDs. Quotes in PDFs are not checked yet.
+
+### In CI: GitHub Action
+
+```yaml
+# .github/workflows/citations.yml
+on: [push, pull_request]
+jobs:
+  claimcite:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: wasabihu/claimcite@v0.1.0
+        with:
+          files: "docs/**/*.md"  # default: every Markdown file
+          fail-on: error         # or: warning, never
+          web: "true"            # "false" checks DOIs and PMIDs only
+```
+
+The report also appears in the job summary. Runs on Linux and macOS runners.
+
+### Before each commit: pre-commit
+
+```yaml
+# .pre-commit-config.yaml
+repos:
+  - repo: https://github.com/wasabihu/claimcite
+    rev: v0.1.0
+    hooks:
+      - id: claimcite
+        # args: [--no-web]   # faster: skip ordinary web links
+```
+
+Every changed Markdown file is checked; the commit stops when a citation has an error. You can also pass
+several files on the command line: `claimcite check docs/*.md`.
+
+## Roadmap
+
+Each item is a self-contained piece of work. Pick one and open an issue to say you're on it.
+
+- [x] **Web links**: check that the page is alive and contains the quoted text
+- [ ] **More registries**: OpenAlex, Semantic Scholar, arXiv, CNKI/Wanfang metadata, DataCite
+- [ ] **Retractions**: flag retracted papers (Crossref / Retraction Watch data)
+- [ ] **Full text**: look for quotes in open-access full text (PubMed Central, Europe PMC), not only abstracts
+- [ ] **Support check**: does the source support the sentence? Pluggable LLM judge, local models first
+- [ ] **Benchmark**: a public, labelled set of real and fabricated citations to measure every check
+- [x] **Numbered citations**: `[1]`, `[1-3]` and footnotes `[^1]` linked to the reference list
+- [ ] **More input formats**: BibTeX, Word / PDF input
+- [x] **Integrations**: GitHub Action, pre-commit hook
+- [ ] Browser extension
+- [x] **Caching** between runs (30-day on-disk cache, `--no-cache` to bypass)
+- [ ] Faster batch lookups
+
+## Contributing
+
+Contributions of every size are welcome, including AI-assisted ones. See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+MIT

claimcite-0.1.0.dist-info/RECORD

@@ -0,0 +1,18 @@
+claimcite/__init__.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+claimcite/__main__.py,sha256=E6Gls0DNz8GQK2K-kOUIx8cYhgANW_CH54VKrfCfs14,52
+claimcite/cache.py,sha256=6wOECPIe4GOpRDHv8AuKqC_zjyr23j6u2RmwQ57xbps,3839
+claimcite/check.py,sha256=uu00GYFIYy38wkncchpl27ouW-OaM-M42RMl9a12HeI,3228
+claimcite/cli.py,sha256=WtJB_87PV4sVg89GLh9mIJXFmMEUOPXGIrHhonBFpS8,2578
+claimcite/evidence.py,sha256=242-N6DfVdET1cCRgc0WKn9zSmd8Rmn0s6ybhsoBI9Q,1943
+claimcite/extract.py,sha256=0cMuxGhddHppJ5Wly9PMn8R3YIgdIUsM9y13yreR-lQ,6618
+claimcite/models.py,sha256=uGQM_2YIanPkF4-vfzzztCBC8YRAT40j4DVmnVLY7wo,1950
+claimcite/net.py,sha256=8Kz2Y8BnCO1S278cQ3WUwdN2kZ7fuPv0zTdDHrauaW4,2281
+claimcite/report.py,sha256=JzjXZxmzDs_dH-fQXvp_5VVcovGdMb2immC5N8MzuyI,6759
+claimcite/sources.py,sha256=qVjQu9J5rN9Q78oi8rQJrluwvC1NZhP-MHdPQMsWTFo,7944
+claimcite/text.py,sha256=ljAuav1rASJ0McRlNUv19i1g1oNExoI4dkhfWeWxjXk,1086
+claimcite/web.py,sha256=72jndrWvQeHAEOrcE8hlWEoiA81LekINLL7CIGX92xs,3203
+claimcite-0.1.0.dist-info/METADATA,sha256=ccy3BiXc8l7IWJoD9eA8_pjgzV88ckoaLsYf6BTxy5Q,6925
+claimcite-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+claimcite-0.1.0.dist-info/entry_points.txt,sha256=UTZcBv29D6YtyLoY3LqUDXjej-Sww1bqRpQujANf_nA,49
+claimcite-0.1.0.dist-info/licenses/LICENSE,sha256=kNZjGIeNgVNpjFFuYCgx3v7FlDy6g_f4861-K_zpEF8,1079
+claimcite-0.1.0.dist-info/RECORD,,

claimcite-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

claimcite-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+claimcite = claimcite.cli:main

claimcite-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 claimcite contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.