citeparse
citeparse turns reference strings into structured records. It reads one reference per line and writes CSL-JSON or BibTeX. A small local model does the work, so nothing leaves your machine unless you ask it to check a record against Crossref.
Try it in your browser: huggingface.co/spaces/hedwigai/citeparse. The model runs on the page, so nothing you paste is uploaded.
pip install citeparse
citeparse refs.txt # CSL-JSON, one record per line
citeparse refs.txt --bibtex # BibTeX
citeparse check refs.txt # flag references that point to no real work
from citeparse import Parser
p = Parser() # hedwigai/citeparse-32m; pass "hedwigai/citeparse-150m" for the larger model
p.parse('K. He, X. Zhang, S. Ren, and J. Sun, "Deep residual learning for image recognition," '
'in Proc. CVPR, 2016, pp. 770-778. doi:10.1109/CVPR.2016.90')
# {'author': [{'family': 'He', 'given': 'K.'}, ...], 'title': 'Deep residual learning for image recognition',
# 'container-title': 'CVPR', 'issued': {'date-parts': [[2016]]}, 'page': '770-778', 'DOI': '10.1109/CVPR.2016.90'}
Checking a reference list
citeparse check looks for citations that point to no real work, such as references invented by a language model. Each reference is parsed on your machine. Its DOI is then looked up on Crossref and DataCite; a reference without one is searched on Crossref, and on OpenAlex when there is budget. A match needs the title, a surname and the year to agree.
$ citeparse check refs.txt
1 ok K. He, X. Zhang, S. Ren, and J. Sun, "Deep residual learning for image recognition," in Pr
2 NOT FOUND Smith, J. A., & Patel, R. (2021). Recursive attention gating for low-resource legal summar
no published work with a close title; check it by hand
3 MISMATCH Hinton, G. (2015). Deep residual learning for image recognition. Nature, 521, 436-444. htt
the DOI's record has a different author: "Deep Residual Learning for Image Recognition"
4 BAD DOI Lee, M., & Gomez, T. (2020). Neural citation graphs for clinical trial retrieval. Bioinfor
DOI 10.1093/bioinformatics/btz99999 is not registered
How well does it work? We ran it on 100 real references from the benchmark below, with their DOIs removed so that each had to be found by search, and on 83 fakes made by putting one reference's title on another's authors and year. Crossref was the only index (no OpenAlex key).
| Matched (ok) | Check by hand (not found) | Accused (mismatch or bad DOI) | |
|---|---|---|---|
| 100 real references | 89 | 11 | 0 |
| 83 fakes | 3 | 80 | 0 |
No real reference was accused. The 11 left to check by hand are mostly old physics references with no title, an Italian law chapter, a Russian book and one reference whose title is miswritten. The script is train/eval_check.py.
The command exits with status 1 when a reference is a mismatch or has an unregistered DOI, so it can run in CI over a paper's bibliography. "Not found" is a prompt to look by hand, not proof of a fake: theses, reports and old books are often missing from every index. Pass --mailto you@example.org so Crossref can reach you, and set OPENALEX_API_KEY for OpenAlex, whose free budget without a key is small and shared by your network.
Use it from an agent (MCP)
pip install "citeparse[mcp]"
claude mcp add citeparse -- citeparse-mcp
The server offers two tools, parse_references (CSL-JSON or BibTeX) and check_references. Then ask your agent to "check the references in paper.tex".
How good is it?
We scored it on 700 real references taken from Crossref. Each one cites a DOI, so the cited work's own Crossref record is the answer key. None of these DOIs were in our training data. We gave GROBID the same DOI rule that citeparse uses, so the DOI column is equal and the rest of the gap comes from the models.
| Parser | Fields right | References fully right | Title | Container | Volume | Issue | First page | DOI |
|---|---|---|---|---|---|---|---|---|
| GROBID 0.8.1 (CRF) | 0.911 | 71.1% | 0.882 | 0.805 | 0.908 | 0.803 | 0.953 | 0.994 |
| citeparse-32m | 0.939 | 80.3% | 0.921 | 0.858 | 0.956 | 0.841 | 0.968 | 0.988 |
| citeparse-150m | 0.952 | 83.4% | 0.934 | 0.878 | 0.966 | 0.861 | 0.982 | 0.994 |
GROBID still wins on its own held-out citations (0.943 against 0.900 for citeparse-150m and 0.882 for citeparse-32m, all on GROBID's own scorer). Those citations come from the same sources as GROBID's training data. We report both results.
"Fields right" is the share of the 3,138 fields in the set that come out exactly right. A journal also counts as right when it matches its short title.
Speed on CPU (8 threads): citeparse-32m parses about 118 references a second, and citeparse-150m about 20.
Fields
AUTHOR, EDITOR, TITLE, CONTAINER, DATE, VOLUME, ISSUE, PAGES, PUBLISHER, LOCATION, EDITION, DOI, URL, ISBN, IDENTIFIER, NOTE. Names are split into family and given parts. DOIs are read with a regular expression, because a DOI has a fixed shape; the model's DOI span is used only when the text has no well-formed DOI.
Models and data
- hedwigai/citeparse-32m: the default, from
jhu-clsp/ettin-encoder-32m. - hedwigai/citeparse-150m: from
jhu-clsp/ettin-encoder-150m. - hedwigai/citeparse-wild-700: the benchmark above.
The models were trained on GROBID's citation corpus (Apache-2.0), with its evaluation files and any reference that also appears in them removed, and on Crossref records (CC0) written out in 11 citation styles. The code to rebuild the data, train and benchmark is in train/.
License
Apache-2.0 for the code and the models.
Metadata
Release files for citeparse 0.2.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| citeparse-0.2.0.tar.gz | 30.6 kB | Without provenance | Details for citeparse-0.2.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| citeparse-0.2.0-py3-none-any.whl | Python 3 | none | any | Details for citeparse-0.2.0-py3-none-any.whl |
Total release size: 49.9 kB
Release files / citeparse-0.2.0.tar.gz
| Download URL | citeparse-0.2.0.tar.gz |
|---|---|
| Size | 30.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
d6eb78bbb6a7d520b9077445765098e0861f752b15dbab8868ac4e37e3a7f87d
|
|
BLAKE2b-256 checksum How to use checksums |
bbaa9e6139df708142998fe391e449c0c99664919bd16df408fa64303fab6285
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.9
|
Release files / citeparse-0.2.0-py3-none-any.whl
| Download URL | citeparse-0.2.0-py3-none-any.whl |
|---|---|
| Size | 19.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
ce43b4f50fd429f326122389cc352214736be2172bfe0c9e9a6c5fe2a4a98ac1
|
|
BLAKE2b-256 checksum How to use checksums |
9b0476eafa6e0f1600219b1e93a2bc859909e86e22ed4db2b62ebdedeb270f18
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.9
|
Security for citeparse 0.2.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.