claimcite 0.1.0__tar.gz

claimcite-0.1.0/.github/ISSUE_TEMPLATE/false-result.yml

@@ -0,0 +1,22 @@
+name: Wrong result · 结果不对
+description: claimcite flagged a correct citation, or missed a wrong one · 正确的引用被报错，或错误的引用没被发现
+labels: [accuracy]
+body:
+  - type: textarea
+    attributes:
+      label: Citation text · 引用原文
+      description: Paste the exact line from your document · 粘贴文档里的原始那一行
+      render: markdown
+    validations:
+      required: true
+  - type: textarea
+    attributes:
+      label: What claimcite said · claimcite 的输出
+      render: text
+    validations:
+      required: true
+  - type: textarea
+    attributes:
+      label: What it should have said, and why · 应该是什么结果，为什么
+    validations:
+      required: true

claimcite-0.1.0/.github/ISSUE_TEMPLATE/new-source.yml

@@ -0,0 +1,16 @@
+name: New source or format · 新数据源或新格式
+description: Propose a registry (OpenAlex, CNKI…) or a citation format (footnotes, BibTeX…) · 提议新的数据源或引用格式
+labels: [enhancement]
+body:
+  - type: input
+    attributes:
+      label: Source or format · 数据源或格式
+    validations:
+      required: true
+  - type: textarea
+    attributes:
+      label: Example citations · 引用示例
+      description: Real examples help most · 真实例子最有用
+  - type: textarea
+    attributes:
+      label: API / docs · 接口文档

claimcite-0.1.0/.github/pull_request_template.md

@@ -0,0 +1,8 @@
+## What and why · 改了什么，为什么
+
+## Tests · 测试
+- [ ] `uv run pytest` and `uv run ruff check src tests` pass
+- [ ] New network responses are recorded in `tests/fixtures/` · 新的网络响应已录进 fixtures
+
+## AI assistance · AI 辅助
+<!-- Did you use AI tools? Say which, and confirm you read and ran the result. · 是否用了 AI 工具？说明是哪个，并确认你读过、跑过。 -->

claimcite-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,28 @@
+name: CI
+on:
+  push:
+    branches: [main]
+  pull_request:
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python: ["3.10", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: ${{ matrix.python }}
+      - run: uv sync
+      - run: uv run ruff check src tests
+      - run: uv run pytest -q
+  action:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ./
+        with:
+          files: examples/*.md
+          fail-on: never
+          web: "false"

claimcite-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,51 @@
+# Push a tag such as v0.1.0 to publish. The version in src/claimcite/__init__.py must match the tag.
+# PyPI side (once): add a trusted publisher for this repo, workflow release.yml, environment "pypi".
+name: Release
+on:
+  push:
+    tags: ["v*"]
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: "3.12"
+      - run: uv sync
+      - run: uv run pytest -q
+      - name: Tag matches the package version
+        run: test "v$(uv run python -c 'import claimcite; print(claimcite.__version__)')" = "$GITHUB_REF_NAME"
+      - run: uv build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+  pypi:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1
+  github-release:
+    needs: pypi
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Release notes from CHANGELOG.md
+        run: awk -v v="${GITHUB_REF_NAME#v}" '/^## /{if (p) exit; if (index($0, "## " v)) {p=1; next}} p' CHANGELOG.md > notes.md
+      - run: gh release create "$GITHUB_REF_NAME" dist/* --title "claimcite $GITHUB_REF_NAME" --notes-file notes.md
+        env:
+          GH_TOKEN: ${{ github.token }}

claimcite-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+.venv/
+__pycache__/
+*.pyc
+.pytest_cache/
+.ruff_cache/
+dist/
+.DS_Store

claimcite-0.1.0/.pre-commit-hooks.yaml

@@ -0,0 +1,7 @@
+- id: claimcite
+  name: claimcite
+  description: Check that the citations in Markdown files are real and match what the text says.
+  entry: claimcite check
+  language: python
+  types: [markdown]
+  require_serial: true

claimcite-0.1.0/AGENTS.md

@@ -0,0 +1,109 @@
+# Instructions for AI agents · AI 代理须知
+
+[English](#english) · [中文](#中文)
+
+These rules apply to any AI coding agent working on claimcite. Human contributors: see [CONTRIBUTING.md](CONTRIBUTING.md), which these rules extend.
+
+## English
+
+### Think from first principles
+
+Start from what is true, not from habit or what other projects do.
+
+- **Start from the goal.** claimcite exists so a reader can trust that each citation is real, points to the paper the text names, and contains the quoted words. Judge every change by whether it makes that verdict more correct, or easier to get.
+- **Get facts by running things.** Read the code, run it, and look at what the real service returns before you decide. Do not guess a field's meaning from its name. For example, Crossref's `update-to` sits on the retraction notice, not on the retracted paper. Only the real record shows that.
+- **Question the starting point.** Issues, labels, earlier reviews and this file can be wrong or out of date. Check that the problem is real and still unsolved before you fix it.
+- **Build the simplest fix that the facts require.** Do not add layers, options or dependencies the problem does not need.
+- **Show your reasoning.** In the PR, say which facts you relied on (a recorded response, a failing test, a measurement) and how they lead to the change.
+
+### Check before you commit
+
+```bash
+uv sync
+uv run pytest
+uv run ruff check src tests
+```
+
+Both must pass. Tests run offline in well under a second.
+
+### Where things live
+
+| File | Job |
+|---|---|
+| `src/claimcite/extract.py` | Find citations (DOI, PMID, URL) and the title, year and quotes written next to them |
+| `src/claimcite/sources.py` | Talk to doi.org, PubMed and Crossref; parse their responses into `Record` |
+| `src/claimcite/check.py` | Compare what the text says with the `Record`; decide ok / warning / error / unchecked |
+| `src/claimcite/report.py` | Markdown (English and Chinese) and JSON output |
+| `src/claimcite/net.py` | HTTP with retries and per-host rate limits |
+| `src/claimcite/cache.py` | On-disk cache of successful responses |
+| `src/claimcite/web.py` | Fetch web pages (respecting robots.txt) and look for quoted text |
+| `tests/fixtures/` | Real responses recorded from the services |
+
+### Rules
+
+1. **Bug fixes start with a failing test.** Write the test, watch it fail, then fix.
+2. **Fixtures are recorded, not invented.** Save real responses from the service, including "not found". In `tests/conftest.py`, route only the exact identifiers a test uses. A broad pattern such as a whole DOI prefix makes unrelated tests pass by accident.
+3. **Test the path you changed.** If a paper is found in PubMed first, a test through `check_reference` never reaches the Crossref parser. Test the parser directly as well.
+4. **Assertions must be able to fail.** `assert a or b` that is true in the broken case proves nothing.
+5. **False alarms are worse than misses.** Report `error` only when the registry answer is definite. If you are unsure, report `warning`. If the lookup itself failed, report `unchecked` and fill in `Finding.error`. Never report "does not exist" because a request failed.
+6. **No secrets on disk or in history.** API keys, tokens and email addresses must not appear in the cache, logs, fixtures, test URLs or commits. The cache key strips `api_key`. Keep it that way for any new credential.
+7. **Optional parts must not crash the run.** If the cache, or a single source, cannot be used, print one line to stderr and continue.
+8. **Be polite to free services.** Batch requests, go through `net.http_get` for its rate limiting, and send the claimcite User-Agent. Do not put anyone's contact details in requests.
+9. **Standard library only at runtime**, Python 3.10+. Discuss a new runtime dependency in an issue first. Dev tools go in the `dev` group.
+10. **Both languages.** Every user-facing message in `report.py` needs English and Chinese. README changes go into both `README.md` and `README.zh-CN.md`.
+11. **No traces of your own environment.** Do not leave comments, workarounds or paths that only make sense on the machine you ran on.
+12. **One issue per pull request.** Comment on the issue before you start. Say in the PR that it is AI-assisted.
+13. **Commit identity.** Do not commit with a personal email address that should stay private. Use a GitHub noreply address.
+14. **Run a new check on a real document before calling it done.** Read every warning it gives and decide whether the document or the tool is wrong. Offline tests passed for the first web check, but a run on a real 34-chapter guide found 7 false warnings out of 15 in one chapter (curly vs straight quotes, extra spaces), plus a false warning on every PDF with a quote. Note the run time, too.
+
+## 中文
+
+### 第一性原理
+
+从事实出发推导，不照搬习惯，也不照搬别的项目的做法。
+
+- **先问目标。** claimcite 的目标是让读者能相信每条引用：论文真实存在，就是文中说的那篇，引号里的话确实出自它。每个改动都看它是否让这个判断更准确，或更容易得到。
+- **事实靠运行得到。** 动手前先读代码、跑代码，看真实服务返回什么。不要凭字段名猜意思。比如 Crossref 的 `update-to` 在撤稿通知上，不在被撤的论文上，只有看真实记录才知道。
+- **质疑出发点。** issue、标签、之前的 review，包括这份文件，都可能是错的或过时的。修之前先确认问题真实存在、还没人解决。
+- **按事实需要做最简单的方案。** 问题不需要的抽象层、选项和依赖都不要加。
+- **说清推理。** 在 PR 里写明你依据的事实（录下来的响应、失败的测试、实测数据），以及它们怎么推出这个改动。
+
+### 提交前检查
+
+```bash
+uv sync
+uv run pytest
+uv run ruff check src tests
+```
+
+两项都必须通过。测试不联网，一秒内跑完。
+
+### 代码分工
+
+| 文件 | 负责 |
+|---|---|
+| `src/claimcite/extract.py` | 找出引用（DOI、PMID、网址），以及旁边写的标题、年份和引文 |
+| `src/claimcite/sources.py` | 访问 doi.org、PubMed、Crossref，把返回结果解析成 `Record` |
+| `src/claimcite/check.py` | 比对文中写的和 `Record`，判定通过、警告、错误或未核查 |
+| `src/claimcite/report.py` | Markdown（中英文）和 JSON 输出 |
+| `src/claimcite/net.py` | 带重试和按站点限速的网络请求 |
+| `src/claimcite/cache.py` | 把查询成功的结果缓存到磁盘 |
+| `src/claimcite/web.py` | 抓取网页（遵守 robots.txt），查找引文 |
+| `tests/fixtures/` | 从真实服务录下来的响应 |
+
+### 规则
+
+1. **修 bug 先写测试。** 先写测试，确认它失败，再修。
+2. **测试数据要录，不要编。** 保存服务的真实响应，包括"查不到"的情况。在 `tests/conftest.py` 里只为测试用到的具体编号配路由。范围太宽的规则（比如整个 DOI 前缀）会让无关的测试碰巧通过。
+3. **测到你改的那条路径。** 如果论文先在 PubMed 查到，经过 `check_reference` 的测试就走不到 Crossref 的解析代码，要对解析函数单独写测试。
+4. **断言必须有可能失败。** 像 `assert a or b` 这样在代码出错时也成立的断言，什么也证明不了。
+5. **误报比漏报更糟。** 只有数据源给出确定答案时才报"错误"。不确定就报"警告"。查询本身失败时报"未核查"，并填写 `Finding.error`。不能因为请求失败就报"编号不存在"。
+6. **密钥不落盘，也不进历史。** API key、token、邮箱不能出现在缓存、日志、测试数据、测试网址或提交里。缓存键会去掉 `api_key`，以后新增任何凭据也要这样处理。
+7. **可选部分不能让整个程序崩溃。** 缓存或某个数据源用不了时，往 stderr 打一行提示，然后继续。
+8. **善待免费服务。** 批量请求，通过 `net.http_get` 发请求以遵守限速，并带上 claimcite 的 User-Agent。请求里不要放任何人的联系方式。
+9. **运行时只用标准库**，Python 3.10 及以上。要加运行时依赖，先开 issue 讨论。开发工具放进 `dev` 组。
+10. **中英双语。** `report.py` 里每条面向用户的提示都要有中文和英文。改 README 要同时改 `README.md` 和 `README.zh-CN.md`。
+11. **不留下你自己运行环境的痕迹。** 只在你那台机器上才说得通的注释、绕路写法和路径，都不要提交。
+12. **一个 PR 只做一个 issue。** 开工前先在 issue 下留言。在 PR 里说明是 AI 辅助完成的。
+13. **提交身份。** 不要用需要保密的个人邮箱提交，用 GitHub 的 noreply 邮箱。
+14. **新的检查先在真实文档上跑一遍再算完成。** 逐条看它报的警告，判断是文档错了还是工具错了。网页链接检查第一版的离线测试全部通过，但在一本 34 章的真实指南上一跑，一章的 15 条警告里有 7 条是误报（直引号和弯引号、多出的空格），带引文的 PDF 也每条都误报。顺便记下运行时间。

claimcite-0.1.0/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+## 0.1.0 (unreleased)
+
+First release on PyPI: `pipx install claimcite`.
+
+- Check that each DOI and PMID exists (doi.org handle API for every registrar, PubMed).
+- Compare the title and year written in the text with the registry (PubMed, then Crossref).
+- Look for quoted text (`"…"`, `“…”`, `「…」`) in the abstract.
+- Show the study type PubMed records: meta-analysis, RCT, observational, animal study…
+- Web links: check that the page is alive and contains the quoted text, respecting `robots.txt`.
+- Numbered citations: a quote followed by `[1]`, `[^1]`, `[1, 2]` or `[1-3]` is checked against that
+  entry in the reference list.
+- Check several files in one run; GitHub Action and pre-commit hook.
+- Markdown report in English or Chinese, JSON for scripts, exit code 1 on errors for CI.
+- 30-day on-disk cache of registry answers.

claimcite-0.1.0/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

claimcite-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,41 @@
+# Contributing · 参与贡献
+
+[English](#english) · [中文](#中文)
+
+## English
+
+1. **Pick something.** Roadmap items in the README and issues labelled `good first issue` are ready to start.
+   Comment on the issue so two people don't do the same work.
+2. **Set up.**
+   ```bash
+   git clone https://github.com/wasabihu/claimcite && cd claimcite
+   uv sync
+   uv run pytest && uv run ruff check src tests
+   ```
+3. **Tests run offline.** Every network response used in tests is a file in `tests/fixtures/`, recorded from
+   the real service. When you add a registry, record real responses (including "not found") and route them in
+   `tests/conftest.py`.
+4. **Bug fixes start with a failing test** that reproduces the bug, then the fix.
+5. **Keep false alarms rare.** A checker that cries wolf gets ignored. If a check is uncertain, report a
+   warning or "not checked" rather than an error.
+6. **Be polite to free services.** Batch requests, respect rate limits, send the claimcite User-Agent.
+
+**AI-assisted contributions are welcome.** Say so in the pull request, and make sure you have read and run
+what you submit. You are responsible for it, not the tool.
+AI agents: read [AGENTS.md](AGENTS.md) first.
+
+## 中文
+
+1. **选一项来做。** README 里的路线图和带 `good first issue` 标签的 issue 都可以直接开始做。先在 issue 下留言说你在做，免得两个人做重复了。
+2. **搭环境。**
+   ```bash
+   git clone https://github.com/wasabihu/claimcite && cd claimcite
+   uv sync
+   uv run pytest && uv run ruff check src tests
+   ```
+3. **测试不联网。** 测试用到的每个网络响应都是 `tests/fixtures/` 里的文件，录自真实服务。新增数据源时，把真实响应（包括"查不到"的情况）录下来，并在 `tests/conftest.py` 里配好路由。
+4. **修 bug 先写测试。** 先写一个能复现 bug、会失败的测试，再修。
+5. **少误报。** 一个老是误报的检查工具，最后没人会理会。不确定的情况报"警告"或"未核查"，不要报"错误"。
+6. **善待免费服务。** 尽量批量请求，遵守访问频率限制，请求时带上 claimcite 的 User-Agent。
+
+**欢迎 AI 辅助完成的贡献。** 在 PR 里说明，并确保提交的内容你自己读过、跑过。对内容负责的是你，不是工具。AI 代理请先读 [AGENTS.md](AGENTS.md)。

claimcite-0.1.0/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.

claimcite-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,132 @@
+# 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