@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 ...

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

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']))

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-JSON item output (a development fixture verifies Pandoc 3.10 consumption)
onecite process references.txt --output-format csl-json -o references.json

The development evidence verifies Pandoc 3.10 consumption of representative
emitted items. Quarto, standalone citeproc, and reference-manager import
workflows are not separately validated in this release.

Report fields. Beyond results and failed_entries, the processing
report carries two audit signals:

• warnings - non-blocking review warnings on resolved entries. Most
  importantly text_metadata_mismatch: the input text around a resolved DOI
  appears to describe a different work (the classic hallucinated
  title+DOI pairing). The DOI remains the resolved identifier and the entry resolves,
  but it is flagged for review instead of silently emitted as clean output.
• duplicates - the same work appeared more than once in the batch (bare
  DOI, PMID, formatted citation). It is emitted once; repeats are reported
  with the emitted entry's cite key.

Failed entries carry the original input excerpt (raw_text) and a reason
code - doi_not_found (no registry record was returned after the implemented
fallback), no_strong_identifier (ambiguous text; use onecite suggest),
source_error (a source/identity failure surfaced on that route), and more.
These codes make important cases distinguishable, but they are not a complete
provider trace: some PMID, ISBN, and DataCite request errors currently collapse
into the same unresolved reason as a lookup miss.

onecite suggest

Search for candidate matches without producing BibTeX or returning a
validation passed status.

onecite suggest "Attention is all you need, Vaswani et al., NIPS 2017" --json

Candidates are for review, not source-resolved citations. Each suggestion
discloses the health of the consulted scholarly indexes in a sources
list. If a source was rate-limited or errored, the suggestion status becomes
candidates_found_incomplete / no_candidates_incomplete - the correct
match may be missing from the list entirely, and the candidate list must
not be treated as exhaustive. Candidates whose year contradicts the year
cited in the query are penalized and flagged with year_conflict. To turn
a reviewed candidate into source-resolved BibTeX, resolve its DOI through
onecite process "<doi>".

Optional Google Scholar fallback. suggest accepts --google-scholar
(requires the optional scholarly package: pip install onecite[scholar]).
It is consulted only as a best-effort fallback when CrossRef and Semantic
Scholar return nothing. Because it scrapes a service with no public API, it
is off by default, may be rate-limited or blocked by a CAPTCHA, and is not
guaranteed to be reproducible - it is exposed only on suggest (candidates
for human review), never on process.

pip install onecite[scholar]
onecite suggest "some obscure title" --google-scholar

onecite --version

Display the installed OneCite version.

Usage:

onecite --version

onecite version

Alternative command to display version information.

Usage:

onecite version

onecite templates

List the bundled fallback BibTeX templates and the fields they request.

Usage:

onecite templates
onecite templates --json

onecite benchmark

Run a small deterministic regression suite for covered DOI lookup, arXiv
lookup, PMID/PubMed lookup, GitHub software URLs, Zenodo/DataCite dataset
DOIs, and mixed valid/invalid batches. The command is designed for CI and
automation workflows that need a machine-readable pass/fail check; it is not
a comprehensive citation-accuracy benchmark.

Usage:

onecite benchmark [OPTIONS]

Options:

Examples:

onecite benchmark
onecite benchmark --json
onecite benchmark --live --json
onecite benchmark --cases my_cases.json --min-success-rate 1.0 --json
onecite benchmark --anti-hallucination
onecite benchmark --anti-hallucination --json

The repository baseline record is stored at benchmarks/leaderboard.json, with
reproduction instructions in benchmarks/README.md.

Anti-hallucination evaluation

onecite benchmark --anti-hallucination runs a labelled, fully-offline
evaluation of OneCite's core safety property. It resolves real strong
identifiers (class A) into source-resolved BibTeX, leaves ambiguous
plain-text references (class B) and fabricated, non-existent DOIs (class
C - the kind a language model may hallucinate) unresolved rather than
emitting a wrong citation, and flags mismatched pairings (class D - a real
DOI attached to a different paper's title, the most common hallucinated-citation
shape) with a text_metadata_mismatch warning instead of silently emitting them
as clean source-resolved output. It reports three metrics:

• resolution rate - fraction of class-A inputs correctly resolved;
• non-fabrication rate - fraction of class-B/C inputs correctly left
  unresolved (not fabricated). 100% means OneCite invented no citations;
• mismatch detection rate - fraction of class-D inputs resolved with
  the mismatch warning attached.

A pipeline crash is recorded as error and never counts as correct for any
metric - a clean rejection and a broken pipeline are different outcomes.

The dataset lives at src/onecite/benchmarks/anti_hallucination_cases.json, and the
evaluation is also available from Python via
onecite.run_anti_hallucination_eval().

onecite doctor

Check the local installation health for automation and CI. The doctor
command checks package importability, bundled templates, packaged benchmark
resources, the repository-contained OneCite Skill, and the offline benchmark
regression check.

Usage:

onecite doctor
onecite doctor --json

The JSON output is a stable envelope with schema_version, tool,
command, status, environment, summary, and checks fields.

OneCite Skill for Automated Workflows

The repository includes a local skill package at skills/onecite/SKILL.md.
It gives automation and contributor workflows a repeatable procedure for
reference cleanup, benchmark and doctor checks, and explicit
reporting of unresolved entries.
The skill is repository-contained and does not install itself into any local
tool memory.

Input Type Auto-Detection

When --input-type is not specified, OneCite automatically detects the input type:

• Files ending with .bib are treated as BibTeX format
• All other files and strings are treated as plain text

Available Templates

OneCite supports several template presets for different entry types:

• journal_article_full - Full journal article entry (default)
• conference_paper - Conference proceedings paper
• book - Book entry
• thesis - Thesis/dissertation entry
• dataset - Dataset entry
• software - Software/code entry

Exit Codes

• 0 - Success
• 1 - Error occurred (invalid input, processing failure, etc.)
• 2 - One or more entries were unresolved when --fail-on-unresolved was used

For onecite benchmark and onecite doctor, exit code 0 means the
configured checks passed and exit code 1 means at least one check failed.