Metadata-Version: 2.4
Name: citegate
Version: 0.2.1
Summary: Citation integrity as a CI gate: verify BibTeX references against Crossref and OpenAlex, catch fabricated citations, and get alerted when a paper you cite is retracted.
Author-email: Yang Song <songyang0714@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/chrisyangsong/citegate
Project-URL: Issues, https://github.com/chrisyangsong/citegate/issues
Keywords: bibtex,citations,references,hallucination,retraction,crossref,openalex,ci,research-integrity
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Text Processing :: Markup :: LaTeX
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.28
Requires-Dist: bibtexparser<2,>=1.4
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Dynamic: license-file

# citegate

[![PyPI](https://img.shields.io/pypi/v/citegate)](https://pypi.org/project/citegate/)
[![CI](https://github.com/chrisyangsong/citegate/actions/workflows/ci.yml/badge.svg)](https://github.com/chrisyangsong/citegate/actions/workflows/ci.yml)
[![Python](https://img.shields.io/pypi/pyversions/citegate)](https://pypi.org/project/citegate/)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

**Citation integrity as a CI gate.** citegate verifies every entry in your BibTeX files against [Crossref](https://www.crossref.org/) and [OpenAlex](https://openalex.org/), then fails your build when a reference is fabricated, wrong, or retracted.

LLM writing assistants fabricate plausible-looking references, and even careful humans cite papers that later get retracted. Existing checkers are interactive tools you have to remember to run. citegate is the piece that belongs in your repository instead: a GitHub Action, a pre-commit hook, and a weekly monitor that opens an issue the day a paper you cite is retracted.

```
  OK         he2016deep
  NOT FOUND  fabricated2023  (best title similarity 0.42)
             - no record with a similar title in Crossref or OpenAlex — possibly a fabricated reference
  RETRACTED  wakefield1998retracted
             - OpenAlex marks this work as retracted
             - Crossref/Retraction Watch records: retraction

citegate: checked 3 entries — 1 verified, 1 retracted, 1 not-found
```

## What it checks

| Verdict | Meaning |
|---|---|
| `verified` | The entry matches a real indexed work (title, year, authors agree). |
| `not-found` | No similar record exists in Crossref or OpenAlex. Likely fabricated. |
| `retracted` | The cited work is retracted or withdrawn, per OpenAlex and the [Retraction Watch data in Crossref](https://www.crossref.org/blog/news-crossref-and-retraction-watch/). |
| `mismatch` | A real work exists, but the year, title, or authors in your entry disagree with the index. |
| `unverifiable` | Websites, standards, and other entries without a DOI that scholarly indexes do not cover. Never fails the build. |
| `error` | A source API was unreachable. |

Entries with a DOI are resolved directly and their metadata compared field by field. Entries without a DOI are matched by fuzzy bibliographic search across both indexes; strong matches also get a `suggestion` with the DOI you should add.

## Quick start

```bash
pip install citegate            # or: pipx install citegate
citegate paper/references.bib --mailto you@example.edu
```

`--mailto` is optional but recommended: it identifies you to the APIs and places you in Crossref's polite pool. The exit code is non-zero when any `not-found` or `retracted` entry appears (configurable with `--fail-on not-found,retracted,mismatch`), so the same command works locally and in CI. Add `--json report.json` for machine-readable output, `--cache` to skip unchanged entries on repeated runs, and `--workers N` to tune lookup concurrency (default 4).

## GitHub Action

```yaml
name: References
on: [push, pull_request]
jobs:
  citegate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: chrisyangsong/citegate@main
        with:
          files: '**/*.bib'
          mailto: 'you@example.edu'
```

Failures show up as inline annotations and a job-summary table listing exactly which entries are suspect and why.

## Retraction monitoring

A bibliography that verified cleanly last month can go bad without you touching it: about [one in 500 published papers is eventually retracted](https://www.crossref.org/blog/news-crossref-and-retraction-watch/), and citing one in a submission is an avoidable reviewer complaint. Copy [`examples/retraction-monitor.yml`](examples/retraction-monitor.yml) into `.github/workflows/` and citegate re-verifies your references every Monday, opening an issue in your repository when a cited paper is retracted or stops resolving.

## pre-commit hook

```yaml
# .pre-commit-config.yaml
repos:
  - repo: https://github.com/chrisyangsong/citegate
    rev: v0.2.0
    hooks:
      - id: citegate
```

## Relation to other tools

Several good interactive checkers exist, including [refchecker](https://github.com/markrussinovich/refchecker) and [hallucinator](https://github.com/gianlucasb/hallucinator) for auditing a finished paper or PDF, and browser tools like [BibTeX Verifier](https://merfanian.github.io/Bibtex-Verifier/). citegate covers the other half of the problem: it lives in the repository with your `.bib` files, runs automatically on every push, and keeps watching after you stop looking. If you want a one-off deep audit of a PDF, use those tools; if you want your references checked continuously, use citegate.

## Design notes

- Sources: Crossref (REST API, polite pool) and OpenAlex. Retraction status is the union of OpenAlex's `is_retracted` flag and Crossref update records, which include the Retraction Watch database.
- Matching is deliberately conservative: `@misc` and other non-indexed entry types without DOIs are skipped rather than flagged, and a one-year slack is allowed on years (print vs online dates). False alarms are the fastest way to get a checker removed from CI.
- No LLMs are involved in verification; every verdict is traceable to an index record.

## Roadmap

- DOCX/PDF reference-list extraction (currently BibTeX only)
- arXiv and DBLP as additional sources
- An `--only retractions` fast mode for high-frequency monitoring

Issues and pull requests are welcome.

## License

MIT © 2026 Yang Song. Not affiliated with Crossref, OpenAlex, or Retraction Watch; please respect their API terms.
