Onecite

OneCite Auditable citation normalization for research workflows

Features • Quick Start • Privacy & External Services • 📖 Advanced Usage • 🗺️ Roadmap • 🤝 Contributing

---

OneCite is a command-line and Python toolkit that turns messy, mixed-format references — DOIs, PMIDs, arXiv IDs, ISBNs, URLs, and BibTeX fragments — into auditable BibTeX or CSL-JSON records. Strong identifiers follow documented metadata-service routes; ordinary ambiguous plain-text references are returned as candidates for review and are not auto-promoted by process .

---

AI-assisted writing, automated literature pipelines, and copy-paste research habits produce ever more reference objects in ever more formats — and ever more chances for wrong, fabricated, or mismatched bibliographic data. Reference *managers* (Zotero), *parsers* (AnyStyle, GROBID), *format converters* (Citation.js), and *identifier-to-BibTeX* helpers (doi2bib, Manubot) each solve one slice of the problem. OneCite targets the under-served step before references enter a manuscript, systematic review, or manager: an auditable normalization layer that routes strong identifiers (DOI, PMID, arXiv, ISBN, URL, data/software DOIs) to the applicable metadata services, completes available metadata, reports unresolved entries, and produces BibTeX or CSL-JSON.

OneCite is not another reference manager, and process does not auto-accept fuzzy title matches. Strong identifiers are resolved through documented source routes; explicitly labelled thesis/dissertation citations have a separate OpenAIRE/BASE route and can fall back to fields parsed from the input. Ordinary ambiguous text is returned as ranked candidates through onecite suggest for human review rather than silently emitted as source-resolved output. That process/suggest separation, together with machine-readable JSON/NDJSON, exit codes, and deterministic offline checks, makes OneCite a scriptable building block for agents, batch jobs, and reproducible reviews rather than a GUI library. Source resolution does not establish that a work is authentic, unretracted, or correctly described by upstream metadata.

---

Features

🌐 Data Sources

Privacy and external services

Normal process and suggest runs can make input-dependent outbound requests. For example, DOI resolution sends the DOI to Crossref (and sometimes a fallback registry); suggest sends citation queries to Crossref, Semantic Scholar, and arXiv; arbitrary URL input is fetched from the supplied host; and thesis queries can be sent to OpenAIRE and BASE. Google Scholar is an optional, scraping-based suggest fallback that is off by default and may be blocked or challenged by a CAPTCHA.

OneCite does not provide a privacy-compliance guarantee or a persistent cache of ordinary live responses. Providers, proxies, output files, and logs may retain data. Review and redact confidential input before use. See Privacy and external services for the exact process/suggest routes, transmitted fields, source-health limits, and the offline benchmark/doctor boundary.

Quick Start

Install and try OneCite in a few steps.

1. Installation

The current public PyPI release is 0.1.1. This working tree documents the unreleased 0.2.0 candidate, so install from the checkout when verifying candidate-only behavior:

# Current stable public release

pip install onecite

Unreleased 0.2.0 candidate, from the repository checkout

python -m pip install -e .

2. Create an Input File

Create a file named references.txt with your mixed-format references:

# references.txt

Add blank lines between entries to avoid misidentification

10.1038/nature14539

arXiv:1706.03762

ISBN:9780262035613

https://github.com/tensorflow/tensorflow

10.5281/zenodo.3233118

arXiv:2103.00020

Smith, J. (2020). Neural Architecture Search. PhD Thesis. Stanford University.

3. Run OneCite

Execute the command to process your file and generate a clean .bib output.

onecite process references.txt -o results.bib --quiet

4. View Output

Your results.bib file now contains entries of different types.

View Complete Output (results.bib)

@article{LeCun2015Deep,

doi = "10.1038/nature14539", title = "Deep learning", author = "LeCun, Yann and Bengio, Yoshua and Hinton, Geoffrey", journal = "Nature", year = 2015, volume = 521, number = 7553, pages = "436-444", publisher = "Springer Science and Business Media LLC", url = "https://doi.org/10.1038/nature14539", type = "journal-article", abstract = "Deep learning allows computational models that are composed of multiple processing layers to learn representations of data with multiple levels of abstraction...", } @inproceedings{Vaswani2017Attention, arxiv = "1706.03762", title = "Attention Is All You Need", author = "Vaswani, Ashish and Shazeer, Noam and Parmar, Niki and Uszkoreit, Jakob and Jones, Llion and Gomez, Aidan N. and Kaiser, Lukasz and Polosukhin, Illia", year = 2017, booktitle = "Advances in Neural Information Processing Systems (NeurIPS)", url = "https://arxiv.org/abs/1706.03762", }

... and 5 more entries ...

📖 Advanced Usage

Direct String and Stdin Input

onecite process "10.1038/nature14539"

onecite suggest "Attention is all you need, Vaswani et al., NIPS 2017" echo "10.1038/nature14539" | onecite process -

</details>

🐍 Use as a Python Library

Use OneCite directly in your Python scripts.

from onecite import process_references

result = process_references( input_content="10.1038/nature14539", input_type="txt", template_name="journal_article_full", output_format="bibtex", )

print('\n\n'.join(result['results']))

</details>

💻 CLI Commands & Options

OneCite provides a command-line interface with the following commands and options:

onecite process

The main command for processing references through the OneCite pipeline.

Usage:

onecite process <input_file> [OPTIONS]

Arguments:

• input_file - Input file path, - for stdin, or a strong identifier/reference string

Options:

Examples:

# Process a text file

onecite process references.txt -o results.bib

Process a BibTeX file with auto-detection

onecite process references.bib

Use stdin

echo "10.1038/nature14539" | onecite process -

Process a direct string (DOI)

onecite process "10.1038/nature14539"

Process with custom template

onecite process references.txt --template conference_paper

Quiet mode for scripts

onecite process references.txt -o results.bib --quiet

Automation-friendly JSON with unresolved-entry exit-code handling

onecite process references.txt --json --fail-on-unresolved

Streaming NDJSON for automation

onecite process references.txt --ndjson

CSL-JSO