{
  "markdown": "\n\n<div align=\"center\">\n  <p align=\"center\">\n    <img src=\"https://raw.githubusercontent.com/HzaCode/onecite/main/logo_.jpg\" alt=\"OneCite Logo\" width=\"160\" />\n  </p>\n\n  <h1>OneCite</h1>\n  <h3>Auditable citation normalization for research workflows</h3>\n</div>\n\n<div align=\"center\">\n\n[![Downloads](https://img.shields.io/pepy/dt/onecite?style=flat-square&label=Downloads)](https://pepy.tech/project/onecite)\n[![Awesome CLI Apps](https://img.shields.io/badge/🏆%20Featured-Awesome%20CLI%20Apps%20-FF6B35?style=flat-square)](https://github.com/agarrharr/awesome-cli-apps?tab=readme-ov-file#academia)\n\n[![Tests](https://img.shields.io/github/actions/workflow/status/HzaCode/OneCite/tests.yml?style=flat-square&logo=github)](https://github.com/HzaCode/OneCite/actions)\n[![codecov](https://img.shields.io/codecov/c/github/HzaCode/OneCite?style=flat-square&logo=codecov)](https://codecov.io/gh/HzaCode/OneCite)\n[![PyPI](https://img.shields.io/pypi/v/onecite?style=flat-square&logo=pypi&color=blue)](https://pypi.org/project/onecite/)\n[![Python](https://img.shields.io/badge/3.10+-blue?style=flat-square&logo=python)](https://www.python.org)\n[![MIT](https://img.shields.io/badge/MIT-green?style=flat-square)](LICENSE)\n[![Docs](https://img.shields.io/badge/Docs-Pages-blue?style=flat-square&logo=github)](https://hezhiang.com/OneCite/)\n[![Awesome LaTeX](https://img.shields.io/badge/Awesome-LaTeX-008B8B?style=flat-square&logo=awesome-lists&logoColor=white&labelColor=493267)](https://github.com/egeerardyn/awesome-LaTeX?tab=readme-ov-file#bibliography-tools)\n\n\n</div>\n\n<p align=\"center\">\n  <a href=\"#-features\">Features</a> •\n  <a href=\"#-quick-start\">Quick Start</a> •\n  <a href=\"#privacy-and-external-services\">Privacy &amp; External Services</a> •\n  <a href=\"#-advanced-usage\">📖 Advanced Usage</a> •\n  <a href=\"#-roadmap\">🗺️ Roadmap</a> •\n  <a href=\"#-contributing\">🤝 Contributing</a>\n</p>\n\n---\n\n<p align=\"center\">\n  OneCite is a command-line and Python toolkit that turns messy, mixed-format references — DOIs, PMIDs, arXiv IDs, ISBNs, URLs, and BibTeX fragments — into <strong>auditable</strong> 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 <code>process</code>.\n</p>\n\n---\n\n\nAI-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.\n\nOneCite 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.\n\n\n\n\n\n---\n\n## Features\n\n| Feature                 | Description                                                                                             |\n| ----------------------- | ------------------------------------------------------------------------------------------------------- |\n| **Candidate Suggestions**   | Search incomplete plain-text references with `onecite suggest` without promoting them to resolved bibliography output. |\n| **Multiple Formats**        | Input `.txt`/`.bib` → Output **BibTeX** or **CSL-JSON**.                                             |\n| **4-stage Pipeline**        | A 4-stage process (parse → identify → enrich → format) with explicit unresolved entries.             |\n| **Field Completion**        | Fill available fields returned by metadata sources, such as journal, volume, pages, authors, and abstract. |\n| 🎓 **7+ Citation Types**    | Handles journal articles, conference papers, books, software, datasets, theses, and preprints.        |\n| **Input-Routed Lookup**     | Uses source-specific routes for Crossref, arXiv, PubMed, Semantic Scholar, Google Books, and others. Not every source is queried for every input. |\n| **Many Identifier Types**   | Resolves DOI, PMID, arXiv ID, ISBN, GitHub URL, Zenodo DOI, and DataCite DOI inputs.                 |\n| **Custom Templates**        | YAML-based presets that provide a fallback BibTeX entry type when auto-detection is inconclusive.    |\n\n\n## 🌐 Data Sources\n\n<div align=\"center\">\n\n[![CrossRef](https://img.shields.io/badge/CrossRef-B31B1B?style=for-the-badge&logo=crossref&logoColor=white)](https://www.crossref.org/)\n[![Semantic Scholar](https://img.shields.io/badge/Semantic-1857B6?style=for-the-badge&logo=semanticscholar&logoColor=white)](https://www.semanticscholar.org/)\n[![PubMed](https://img.shields.io/badge/PubMed-326599?style=for-the-badge&logo=pubmed&logoColor=white)](https://pubmed.ncbi.nlm.nih.gov/)\n[![arXiv](https://img.shields.io/badge/𝒳_arXiv-B31B1B?style=for-the-badge)](https://arxiv.org/)\n[![DataCite](https://img.shields.io/badge/DataCite-00B4A0?style=for-the-badge&logo=datacite&logoColor=white)](https://datacite.org/)\n[![Zenodo](https://img.shields.io/badge/Zenodo-0A0E4A?style=for-the-badge&logo=zenodo&logoColor=white)](https://zenodo.org/)\n[![Google Books](https://img.shields.io/badge/Google-4285F4?style=for-the-badge&logo=google&logoColor=white)](https://books.google.com/)\n</div>\n\n### Privacy and external services\n\nNormal `process` and `suggest` runs can make input-dependent outbound requests.\nFor example, DOI resolution sends the DOI to Crossref (and sometimes a\nfallback registry); `suggest` sends citation queries to Crossref, Semantic\nScholar, and arXiv; arbitrary URL input is fetched from the supplied host; and\nthesis queries can be sent to OpenAIRE and BASE. Google Scholar is an optional,\nscraping-based `suggest` fallback that is off by default and may be blocked or\nchallenged by a CAPTCHA.\n\nOneCite does not provide a privacy-compliance guarantee or a persistent cache\nof ordinary live responses. Providers, proxies, output files, and logs may\nretain data. Review and redact confidential input before use. See\n[Privacy and external services](docs/external_services.rst) for the exact\n`process`/`suggest` routes, transmitted fields, source-health limits, and the\noffline benchmark/doctor boundary.\n\n\n## Quick Start\n\nInstall and try OneCite in a few steps.\n\n### 1. Installation\n\nThe current public PyPI release is `0.1.1`. This working tree documents the\nunreleased `0.2.0` candidate, so install from the checkout when verifying\ncandidate-only behavior:\n\n```bash\n# Current stable public release\npip install onecite\n\n# Unreleased 0.2.0 candidate, from the repository checkout\npython -m pip install -e .\n```\n\n### 2. Create an Input File\nCreate a file named `references.txt` with your mixed-format references:\n```text\n# references.txt\n# Add blank lines between entries to avoid misidentification\n\n10.1038/nature14539\n\narXiv:1706.03762\n\nISBN:9780262035613\n\nhttps://github.com/tensorflow/tensorflow\n\n10.5281/zenodo.3233118\n\narXiv:2103.00020\n\nSmith, J. (2020). Neural Architecture Search. PhD Thesis. Stanford University.\n```\n\n### 3. Run OneCite\nExecute the command to process your file and generate a clean `.bib` output.\n```bash\nonecite process references.txt -o results.bib --quiet\n```\n\n### 4. View Output\nYour `results.bib` file now contains entries of different types.\n\n<details>\n<summary><strong>View Complete Output (results.bib)</strong></summary>\n\n```bibtex\n@article{LeCun2015Deep,\n  doi = \"10.1038/nature14539\",\n  title = \"Deep learning\",\n  author = \"LeCun, Yann and Bengio, Yoshua and Hinton, Geoffrey\",\n  journal = \"Nature\",\n  year = 2015,\n  volume = 521,\n  number = 7553,\n  pages = \"436-444\",\n  publisher = \"Springer Science and Business Media LLC\",\n  url = \"https://doi.org/10.1038/nature14539\",\n  type = \"journal-article\",\n  abstract = \"Deep learning allows computational models that are composed of multiple processing layers to learn representations of data with multiple levels of abstraction...\",\n}\n@inproceedings{Vaswani2017Attention,\n  arxiv = \"1706.03762\",\n  title = \"Attention Is All You Need\",\n  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\",\n  year = 2017,\n  booktitle = \"Advances in Neural Information Processing Systems (NeurIPS)\",\n  url = \"https://arxiv.org/abs/1706.03762\",\n}\n# ... and 5 more entries ...\n```\n\n</details>\n\n## 📖 Advanced Usage\n\n<details>\n<summary><strong>Direct String and Stdin Input</strong></summary>\n\n```bash\nonecite process \"10.1038/nature14539\"\nonecite suggest \"Attention is all you need, Vaswani et al., NIPS 2017\"\necho \"10.1038/nature14539\" | onecite process -\n```\n</details>\n\n<details>\n<summary><strong>🐍 Use as a Python Library</strong></summary>\n\nUse OneCite directly in your Python scripts.\n\n```python\nfrom onecite import process_references\n\nresult = process_references(\n    input_content=\"10.1038/nature14539\",\n    input_type=\"txt\",\n    template_name=\"journal_article_full\",\n    output_format=\"bibtex\",\n)\n\nprint('\\n\\n'.join(result['results']))\n```\n</details>\n\n<details>\n<summary><strong>💻 CLI Commands & Options</strong></summary>\n\nOneCite provides a command-line interface with the following commands and options:\n\n### `onecite process`\n\nThe main command for processing references through the OneCite pipeline.\n\n**Usage:**\n```bash\nonecite process <input_file> [OPTIONS]\n```\n\n**Arguments:**\n- `input_file` - Input file path, `-` for stdin, or a strong identifier/reference string\n\n**Options:**\n| Option | Short | Description | Default |\n|--------|-------|-------------|---------|\n| `--input-type` | | Input format: `txt` or `bib` | `txt` |\n| `--template` | | Fallback BibTeX entry-type preset when auto-detection is inconclusive | `journal_article_full` |\n| `--output-format` | | Output format: `bibtex` or `csl-json` for downstream tools that consume CSL-JSON | `bibtex` |\n| `--output` | `-o` | Output file path (default: stdout) | - |\n| `--quiet` | `-q` | Suppress verbose logging output | `False` |\n| `--json` | | Print a stable JSON envelope instead of BibTeX text | `False` |\n| `--ndjson` | | Print newline-delimited JSON events for streaming automation workflows | `False` |\n| `--fail-on-unresolved` | | Return exit code `2` when any entry cannot be resolved | `False` |\n\n**Examples:**\n```bash\n# Process a text file\nonecite process references.txt -o results.bib\n\n# Process a BibTeX file with auto-detection\nonecite process references.bib\n\n# Use stdin\necho \"10.1038/nature14539\" | onecite process -\n\n# Process a direct string (DOI)\nonecite process \"10.1038/nature14539\"\n\n# Process with custom template\nonecite process references.txt --template conference_paper\n\n# Quiet mode for scripts\nonecite process references.txt -o results.bib --quiet\n\n# Automation-friendly JSON with unresolved-entry exit-code handling\nonecite process references.txt --json --fail-on-unresolved\n\n# Streaming NDJSON for automation\nonecite process references.txt --ndjson\n\n# CSL-JSON item output (a development fixture verifies Pandoc 3.10 consumption)\nonecite process references.txt --output-format csl-json -o references.json\n```\n\nThe development evidence verifies Pandoc 3.10 consumption of representative\nemitted items. Quarto, standalone citeproc, and reference-manager import\nworkflows are not separately validated in this release.\n\n**Report fields.** Beyond `results` and `failed_entries`, the processing\nreport carries two audit signals:\n\n- `warnings` — non-blocking review warnings on *resolved* entries. Most\n  importantly `text_metadata_mismatch`: the input text around a resolved DOI\n  appears to describe a **different** work (the classic hallucinated\n  title+DOI pairing). The DOI remains the resolved identifier and the entry resolves,\n  but it is flagged for review instead of silently emitted as clean output.\n- `duplicates` — the same work appeared more than once in the batch (bare\n  DOI, PMID, formatted citation). It is emitted once; repeats are reported\n  with the emitted entry's cite key.\n\nFailed entries carry the original input excerpt (`raw_text`) and a `reason`\ncode — `doi_not_found` (no registry record was returned after the implemented\nfallback), `no_strong_identifier` (ambiguous text; use `onecite suggest`),\n`source_error` (a source/identity failure surfaced on that route), and more.\nThese codes make important cases distinguishable, but they are not a complete\nprovider trace: some PMID, ISBN, and DataCite request errors currently collapse\ninto the same unresolved reason as a lookup miss.\n\n### `onecite suggest`\n\nSearch for candidate matches without producing BibTeX or returning a\nvalidation `passed` status.\n\n```bash\nonecite suggest \"Attention is all you need, Vaswani et al., NIPS 2017\" --json\n```\n\n**Candidates are for review, not source-resolved citations.** Each suggestion\ndiscloses the health of the consulted scholarly indexes in a `sources`\nlist. If a source was rate-limited or errored, the suggestion status becomes\n`candidates_found_incomplete` / `no_candidates_incomplete` — the correct\nmatch may be missing from the list entirely, and the candidate list must\nnot be treated as exhaustive. Candidates whose year contradicts the year\ncited in the query are penalized and flagged with `year_conflict`. To turn\na reviewed candidate into source-resolved BibTeX, resolve its DOI through\n`onecite process \"<doi>\"`.\n\n**Optional Google Scholar fallback.** `suggest` accepts `--google-scholar`\n(requires the optional `scholarly` package: `pip install onecite[scholar]`).\nIt is consulted only as a best-effort fallback when CrossRef and Semantic\nScholar return nothing. Because it scrapes a service with no public API, it\nis **off by default, may be rate-limited or blocked by a CAPTCHA, and is not\nguaranteed to be reproducible** — it is exposed only on `suggest` (candidates\nfor human review), never on `process`.\n\n```bash\npip install onecite[scholar]\nonecite suggest \"some obscure title\" --google-scholar\n```\n\n### `onecite --version`\n\nDisplay the installed OneCite version.\n\n**Usage:**\n```bash\nonecite --version\n```\n\n### `onecite version`\n\nAlternative command to display version information.\n\n**Usage:**\n```bash\nonecite version\n```\n\n### `onecite templates`\n\nList the bundled fallback BibTeX templates and the fields they request.\n\n**Usage:**\n```bash\nonecite templates\nonecite templates --json\n```\n\n### `onecite benchmark`\n\nRun a small deterministic regression suite for covered DOI lookup, arXiv\nlookup, PMID/PubMed lookup, GitHub software URLs, Zenodo/DataCite dataset\nDOIs, and mixed valid/invalid batches. The command is designed for CI and\nautomation workflows that need a machine-readable pass/fail check; it is not\na comprehensive citation-accuracy benchmark.\n\n**Usage:**\n```bash\nonecite benchmark [OPTIONS]\n```\n\n**Options:**\n| Option | Description | Default |\n|--------|-------------|---------|\n| `--cases` | Path to a custom benchmark suite JSON file | bundled golden cases |\n| `--min-success-rate` | Minimum covered-case pass rate required for exit code `0` | `1.0` |\n| `--json` | Print the benchmark report as JSON | `False` |\n| `--live` | Use live external APIs instead of bundled offline fixtures | `False` |\n| `--anti-hallucination` | Run the labelled non-fabrication evaluation instead of the golden cases | `False` |\n\n**Examples:**\n```bash\nonecite benchmark\nonecite benchmark --json\nonecite benchmark --live --json\nonecite benchmark --cases my_cases.json --min-success-rate 1.0 --json\nonecite benchmark --anti-hallucination\nonecite benchmark --anti-hallucination --json\n```\n\nThe repository baseline record is stored at `benchmarks/leaderboard.json`, with\nreproduction instructions in `benchmarks/README.md`.\n\n#### Anti-hallucination evaluation\n\n`onecite benchmark --anti-hallucination` runs a labelled, fully-offline\nevaluation of OneCite's core safety property. It resolves real strong\nidentifiers (class **A**) into source-resolved BibTeX, leaves ambiguous\nplain-text references (class **B**) and fabricated, non-existent DOIs (class\n**C** — the kind a language model may hallucinate) **unresolved** rather than\nemitting a wrong citation, and flags mismatched pairings (class **D** — a real\nDOI attached to a *different* paper's title, the most common hallucinated-citation\nshape) with a `text_metadata_mismatch` warning instead of silently emitting them\nas clean source-resolved output. It reports three metrics:\n\n- **resolution rate** — fraction of class-A inputs correctly resolved;\n- **non-fabrication rate** — fraction of class-B/C inputs correctly left\n  *unresolved* (not fabricated). `100%` means OneCite invented no citations;\n- **mismatch detection rate** — fraction of class-D inputs resolved *with*\n  the mismatch warning attached.\n\nA pipeline crash is recorded as `error` and never counts as correct for any\nmetric — a clean rejection and a broken pipeline are different outcomes.\n\nThe dataset lives at `src/onecite/benchmarks/anti_hallucination_cases.json`, and the\nevaluation is also available from Python via\n`onecite.run_anti_hallucination_eval()`.\n\n### `onecite doctor`\n\nCheck the local installation health for automation and CI. The doctor\ncommand checks package importability, bundled templates, packaged benchmark\nresources, the repository-contained OneCite Skill, and the offline benchmark\nregression check.\n\n**Usage:**\n```bash\nonecite doctor\nonecite doctor --json\n```\n\nThe JSON output is a stable envelope with `schema_version`, `tool`,\n`command`, `status`, `environment`, `summary`, and `checks` fields.\n\n### OneCite Skill for Automated Workflows\n\nThe repository includes a local skill package at `skills/onecite/SKILL.md`.\nIt gives automation and contributor workflows a repeatable procedure for\nreference cleanup, benchmark and doctor checks, and explicit\nreporting of unresolved entries.\nThe skill is repository-contained and does not install itself into any local\ntool memory.\n\n### Input Type Auto-Detection\n\nWhen `--input-type` is not specified, OneCite automatically detects the input type:\n- Files ending with `.bib` are treated as BibTeX format\n- All other files and strings are treated as plain text\n\n### Available Templates\n\nOneCite supports several template presets for different entry types:\n- `journal_article_full` - Full journal article entry (default)\n- `conference_paper` - Conference proceedings paper\n- `book` - Book entry\n- `thesis` - Thesis/dissertation entry\n- `dataset` - Dataset entry\n- `software` - Software/code entry\n\n### Exit Codes\n\n- `0` - Success\n- `1` - Error occurred (invalid input, processing failure, etc.)\n- `2` - One or more entries were unresolved when `--fail-on-unresolved` was used\n\nFor `onecite benchmark` and `onecite doctor`, exit code `0` means the\nconfigured checks passed and exit code `1` means at least one check failed.\n\n</details>\n\n## 🗺️ Roadmap\n\n- [x] **OneCite Skill** — Repository-contained operating guide for local citation-cleanup workflows\n- [x] **Benchmarking** — Small deterministic regression suite, configurable pass-rate gate, and baseline record\n- [x] **Enhanced CLI** — Automation-friendly JSON, NDJSON, summaries, and exit codes for reference processing\n- [x] **Anti-hallucination evaluation** — Labelled offline eval of the non-fabrication property (resolution, non-fabrication, and mismatch detection rates), gated in CI\n- [x] **Audit-grade reports** — Text/DOI mismatch warnings, failure reason codes with original input, DOI-level deduplication, and suggest source-health disclosure\n- [x] **CSL-JSON output** — `--output-format csl-json` emits CSL-JSON items for downstream tools that consume the format; a development fixture verifies Pandoc 3.10 consumption, while Quarto, standalone citeproc, and reference-manager imports are not separately validated\n- [x] **Expanded suggest sources** — Direct arXiv candidate search covers the CS venues that CrossRef does not index\n- [ ] **Concurrent batch resolution** — Parallel source lookups for large reference lists (currently sequential; latency depends on the selected routes and external services)\n- [ ] **Larger anti-hallucination dataset** — More labelled cases per class and a published live-mode baseline\n\n## 🤝 Contributing\n\nContributions are always welcome! Please see [**CONTRIBUTING.md**](CONTRIBUTING.md) for development guidelines and instructions on how to submit a pull request.\n\n## 📄 License\n\nThis project is licensed under the **MIT License**. See the [**LICENSE**](LICENSE) file for details.\n\n<div align=\"center\">\n\n**OneCite**\n\n<p>\n  <a href=\"https://github.com/HzaCode/OneCite\">Star on GitHub</a> •\n  <a href=\"https://hezhiang.com/OneCite/\">Documentation</a> •\n  <a href=\"https://github.com/HzaCode/OneCite/issues\">🐛 Report an Issue</a> •\n  <a href=\"https://github.com/HzaCode/OneCite/discussions\">Discussions</a>\n</p>\n\n</div>\n",
  "bytes": 21770,
  "sha": "362b3fd6932005fbef535bf1bc25ce080b353e0a107810ee415557028ada60ba",
  "repo_slug": "hzacode/onecite",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_hzacode_onecite_b1384876/readme"
}