bibcheck-verify 0.1.1__tar.gz

bibcheck_verify-0.1.1/.env.example

@@ -0,0 +1,8 @@
+# Copy this file to .env and fill only the provider you intend to use.
+BIBCHECK_VERIFY_LLM_PROVIDER=openai
+BIBCHECK_VERIFY_LLM_MODEL=gpt-4o-mini
+
+# Never commit the real key. Keep .env local.
+OPENAI_API_KEY=
+ANTHROPIC_API_KEY=
+GEMINI_API_KEY=

bibcheck_verify-0.1.1/.github/skills/bibcheck/README.md

@@ -0,0 +1,27 @@
+# Skill `bibcheck-verify`
+
+This directory contains the integration for Hermes Agent, Claude Code, or compatible agents. The skill instructs the agent to extract metadata using the session model and invoke the Python `bibcheck` command.
+
+## Installation
+
+The skill and the Python package are separate components.
+
+1. Install the `bibcheck-verify` package. It provides the `bibcheck-verify` command:
+
+   ```powershell
+   uv tool install bibcheck-verify
+   ```
+
+   Before publishing to PyPI, use `uv tool install <repository-path>`.
+
+2. Copy the entire `bibcheck-verify` directory to the skills directory expected by your Hermes or Claude Code installation. The copied directory must contain `SKILL.md`.
+
+3. Ask the agent to verify a PDF, Markdown, text, or BibTeX file.
+
+Do not copy this directory expecting it to also contain the executable: the `bibcheck-verify` command must already be installed and available in the agent's PATH.
+
+## API key
+
+The skill mode does not require an API key for an LLM provider. The session model extracts the metadata; `bibcheck-verify` queries Crossref and OpenAlex.
+
+API keys are required only when directly using the standalone command's LLM fallback with `--llm-provider`.

bibcheck_verify-0.1.1/.github/skills/bibcheck/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: bibcheck-verify
+description: Use when verifying a bibliography from PDF, Markdown, text, or BibTeX, especially when references lack DOI or reliable metadata. Extract metadata with the current session model, then run the installed bibcheck-verify command with Crossref and OpenAlex.
+---
+
+# Verify bibliography with bibcheck-verify
+
+Use the current session model to extract citation metadata, then use the installed `bibcheck-verify` command to verify those metadata against Crossref and OpenAlex.
+
+The model extraction is a hypothesis. Crossref, OpenAlex and the local fuzzy match provide the verification evidence.
+
+## Prerequisite
+
+The user must have the `bibcheck-verify` command installed and available to the agent:
+
+```powershell
+uv tool install bibcheck-verify
+```
+
+Before the package is published, the user can install it from a local clone of the repository with `uv tool install <repository-directory>`.
+
+The skill itself does not contain the Python verifier. Do not use `uv run --project` with a path relative to this skill and do not assume that the repository is available after the skill has been copied to the agent's skills directory.
+
+## Workflow
+
+1. Ask for or identify the original bibliography file. It may be PDF, Markdown, text, or BibTeX.
+2. Read the file and preserve citation order. The first citation has ID `"0"`.
+3. For every citation, extract only metadata supported by the text:
+   - `title`: string or `""`;
+   - `authors`: array of strings;
+   - `year`: integer or `null`;
+   - `doi`: normalized DOI string or `null`;
+   - `venue`: string or `""`;
+   - `queries`: one or more useful search strings based only on extracted metadata.
+4. Never invent authors, titles, years, venues or DOI values. Use empty values when a field is not supported by the citation.
+5. Write a temporary JSON file outside the repository when possible:
+
+```json
+{
+  "items": [
+    {
+      "reference_id": "0",
+      "title": "A Paper",
+      "authors": ["Jane Doe"],
+      "year": 2020,
+      "doi": null,
+      "venue": "Journal",
+      "queries": ["A Paper Jane Doe 2020"]
+    }
+  ]
+}
+```
+
+There must be exactly one item per input citation, with sequential zero-based IDs.
+6. Run the verifier against the original bibliography. Pass the metadata JSON only via `--metadata-file`:
+
+```powershell
+bibcheck-verify verify "C:\Temp\references.txt" --metadata-file "C:\Temp\bibcheck_metadata.json"
+```
+
+Never use the metadata JSON as the positional input file. The verifier parses the original file to determine the number and order of references.
+7. Read `summary.md` and, when needed, `graph.json` from the output directory. Report low-confidence and `suspected_hallucination` entries for manual review.
+
+Use the user's requested options when provided. Do not pass `--llm-provider` in this workflow: the current session model already performed extraction.
+
+## Important boundary
+
+Never request, print, store, or add an API key to the metadata file or this skill.

bibcheck_verify-0.1.1/.github/skills/bibcheck-verify/README.md

@@ -0,0 +1,27 @@
+# Skill `bibcheck-verify`
+
+This directory contains the integration for Hermes Agent, Claude Code, or compatible agents. The skill instructs the agent to extract metadata using the session model and invoke the Python `bibcheck-verify` command.
+
+## Installation
+
+The skill and the Python package are separate components.
+
+1. Install the `bibcheck-verify` package. It provides the `bibcheck-verify` command:
+
+   ```powershell
+   uv tool install bibcheck-verify
+   ```
+
+   Before publishing to PyPI, use `uv tool install <repository-path>`.
+
+2. Copy the entire `bibcheck-verify` directory to the skills directory expected by your Hermes or Claude Code installation. The copied directory must contain `SKILL.md`.
+
+3. Ask the agent to verify a PDF, Markdown, text, or BibTeX file.
+
+Do not copy this directory expecting it to also contain the executable: the `bibcheck-verify` command must already be installed and available in the agent's PATH.
+
+## API key
+
+The skill mode does not require an API key for an LLM provider. The session model extracts the metadata; `bibcheck-verify` queries Crossref and OpenAlex.
+
+API keys are required only when directly using the standalone command's LLM fallback with `--llm-provider`.

bibcheck_verify-0.1.1/.github/skills/bibcheck-verify/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: bibcheck-verify
+description: Use when verifying a bibliography from PDF, Markdown, text, or BibTeX, especially when references lack DOI or reliable metadata. Extract metadata with the current session model, then run the installed bibcheck-verify command with Crossref and OpenAlex.
+---
+
+# Verify bibliography with bibcheck-verify
+
+Use the current session model to extract citation metadata, then use the installed `bibcheck-verify` command to verify those metadata against Crossref and OpenAlex.
+
+The model extraction is a hypothesis. Crossref, OpenAlex and the local fuzzy match provide the verification evidence.
+
+## Prerequisite
+
+The user must have the `bibcheck-verify` command installed and available to the agent:
+
+```powershell
+uv tool install bibcheck-verify
+```
+
+Before the package is published, the user can install it from a local clone of the repository with `uv tool install <repository-directory>`.
+
+The skill itself does not contain the Python verifier. Do not use `uv run --project` with a path relative to this skill and do not assume that the repository is available after the skill has been copied to the agent's skills directory.
+
+## Workflow
+
+1. Ask for or identify the original bibliography file. It may be PDF, Markdown, text, or BibTeX.
+2. Read the file and preserve citation order. The first citation has ID `"0"`.
+3. For every citation, extract only metadata supported by the text:
+   - `title`: string or `""`;
+   - `authors`: array of strings;
+   - `year`: integer or `null`;
+   - `doi`: normalized DOI string or `null`;
+   - `venue`: string or `""`;
+   - `queries`: one or more useful search strings based only on extracted metadata.
+4. Never invent authors, titles, years, venues or DOI values. Use empty values when a field is not supported by the citation.
+5. Write a temporary JSON file outside the repository when possible:
+
+```json
+{
+  "items": [
+    {
+      "reference_id": "0",
+      "title": "A Paper",
+      "authors": ["Jane Doe"],
+      "year": 2020,
+      "doi": null,
+      "venue": "Journal",
+      "queries": ["A Paper Jane Doe 2020"]
+    }
+  ]
+}
+```
+
+There must be exactly one item per input citation, with sequential zero-based IDs.
+6. Run the verifier against the original bibliography. Pass the metadata JSON only via `--metadata-file`:
+
+```powershell
+bibcheck-verify verify "C:\Temp\references.txt" --metadata-file "C:\Temp\bibcheck-verify_metadata.json"
+```
+
+Never use the metadata JSON as the positional input file. The verifier parses the original file to determine the number and order of references.
+7. Read `summary.md` and, when needed, `graph.json` from the output directory. Report low-confidence and `suspected_hallucination` entries for manual review.
+
+Use the user's requested options when provided. Do not pass `--llm-provider` in this workflow: the current session model already performed extraction.
+
+## Important boundary
+
+Never request, print, store, or add an API key to the metadata file or this skill.

bibcheck_verify-0.1.1/.github/workflows/publish.yaml

@@ -0,0 +1,24 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - run: python -m pip install build
+      - run: python -m build
+
+      - uses: pypa/gh-action-pypi-publish@release/v1

bibcheck_verify-0.1.1/.gitignore

@@ -0,0 +1,38 @@
+.env
+.env.*
+!.env.example
+.venv/
+
+# Python environments and caches
+__pycache__/
+**/.venv/
+.pytest_cache/
+**/__pycache__/
+*.py[cod]
+.pytest_cache/
+**/.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# Build artifacts
+build/
+dist/
+*.egg-info/
+**/*.egg-info/
+
+# Generated verifier data
+bibcheck-verify-results/
+**/bibcheck-verify-results/
+bibcheck-verify-results*/
+**/bibcheck-verify-results*/
+bibcheck-results/
+**/bibcheck-results/
+bibcheck-results*/
+**/bibcheck-results*/
+
+# Editor and OS files
+.DS_Store
+Thumbs.db
+.vscode/settings.json

bibcheck_verify-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

bibcheck_verify-0.1.1/PKG-INFO

@@ -0,0 +1,227 @@
+Metadata-Version: 2.5
+Name: bibcheck-verify
+Version: 0.1.1
+Summary: Deterministic bibliography verification for scientific papers
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: bibtexparser<2,>=1.4
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: pymupdf<2,>=1.24
+Requires-Dist: python-dotenv<2,>=1.0
+Requires-Dist: rapidfuzz<4,>=3.9
+Requires-Dist: typer<1,>=0.12
+Provides-Extra: test
+Requires-Dist: pytest<9,>=8; extra == 'test'
+Description-Content-Type: text/markdown
+
+# bibcheck-verify
+
+`bibcheck-verify` is a tool for an initial reproducible check of scientific bibliographies. It compares each reference with metadata indexed by Crossref and OpenAlex and produces a report that helps identify strong matches, possible matches, and references that require manual review.
+
+It does not determine on its own that a citation is fabricated. A reference may be correct but not indexed, or it may be written too incompletely to be recognized. The results are therefore a triage tool, not definitive proof.
+
+## Why it exists
+
+Real bibliographies often come from PDFs, copied text, or documents with missing DOIs and metadata. Checking them one entry at a time is slow; relying on a language model for the judgment, on the other hand, can introduce fabricated details.
+
+`bibcheck-verify` separates these two problems: extracting incomplete metadata can be assisted by a model, while the existence and matching of a work are evaluated by querying external bibliographic sources and comparing the results. This makes both interactive verification with an agent and repeated processing of many bibliographies through scripts, caching, and request limits possible.
+
+### Why this matters
+
+The scale of the problem is illustrated by a 2026 audit published in [The Lancet](https://www.thelancet.com/journals/lancet/article/PIIS0140-6736(26)00603-3/fulltext). The audit examined 2,471,758 biomedical papers published between January 1, 2023, and February 18, 2026, containing 125,615,773 structured references. Of these references, 97.1 million (77%) carried a PMID and were checked against bibliographic records; references to websites, books, and other grey literature were mostly excluded.
+
+The authors identified 4,046 fabricated references across 2,810 papers. The reported rate increased from approximately one paper in 2,828 in 2023 to one in 458 in 2025, and one in 277 during the first seven weeks of 2026. The fabrication rate rose from about 4 per 10,000 papers in 2023 to 51.3 per 10,000 papers in the fourth quarter of 2025, reaching 56.9 per 10,000 papers in early 2026.
+
+Their system compared claimed reference metadata with records from PubMed and Crossref, then used automated filters, an LLM review step, and additional checks against OpenAlex and Google Scholar. In a masked validation of 500 entries, the system had a reported precision of 91% (Fleiss’ κ = 0.71); the authors explicitly note that this estimates precision, not recall. The study also distinguishes fabricated references from reference errors, such as abbreviated titles that still correspond to a real publication.
+
+This is the problem `bibcheck-verify` is intended to make easier to investigate at a smaller and inspectable scale: verify references against external records, preserve the queries and evidence, and send uncertain cases to human review. Its results should not be interpreted as a replication of the Lancet audit or as definitive proof that an unmatched reference is fabricated.
+
+## Two ways to use the project
+
+The repository contains two related but distinct components:
+
+1. **The standalone Python package**: the `bibcheck-verify` program can be used from a terminal, script, or pipeline to check many bibliographies. It can also use an LLM provider through an API key as a fallback for extracting missing metadata.
+2. **The `bibcheck-verify` skill**: instructions for Hermes Agent, Claude Code, or compatible agents. The agent uses the session model to extract metadata, without a separate LLM API key, and then delegates verification to the Python `bibcheck-verify` command.
+
+The skill does not contain a copy of the program. To use it, first install the Python package and then copy the `.github/skills/bibcheck-verify/` directory to the agent’s local skills directory.
+
+## Package installation
+
+Requirements:
+
+- Python 3.11 o successivo;
+- [`uv`](https://docs.astral.sh/uv/).
+
+### From the repository
+
+This is the useful mode during development or before publishing to PyPI:
+
+```powershell
+uv tool install .
+```
+
+To update the installation after a local change:
+
+```powershell
+uv tool install --force .
+```
+
+Alternatively, to use the project without installing it globally:
+
+```powershell
+uv run bibcheck-verify verify references.bib
+```
+
+### From PyPI
+
+Once the package is published, installation will not require downloading the repository:
+
+```powershell
+uv tool install bibcheck-verify
+```
+
+For a single temporary run:
+
+```powershell
+uvx bibcheck-verify verify references.bib
+```
+
+PyPI distributes the code and dependencies. It does not automatically receive the user’s bibliographies, reports, or API keys.
+
+## Standalone usage
+
+The command accepts BibTeX, PDF, Markdown, and plain text:
+
+```powershell
+bibcheck-verify verify references.bib
+bibcheck-verify verify article.pdf
+bibcheck-verify verify references.md --output-dir risultati
+```
+
+The format is recognized from the extension:
+
+- `.bib`: title, authors, year, DOI, journal, or proceedings are extracted;
+- `.pdf`: text is extracted with PyMuPDF;
+- other extensions: the file is treated as text or Markdown.
+
+For text and Markdown, the parser looks for a `References`, `Bibliography`, or `Bibliografia` section. If it does not find one, it tries to interpret the entire file as a bibliography. PDF parsing is best effort; whenever possible, a BibTeX file produces more predictable results.
+
+To see all options:
+
+```powershell
+bibcheck-verify --help
+bibcheck-verify verify --help
+```
+
+Example with the main options:
+
+```powershell
+bibcheck-verify verify references.bib `
+  --depth 1 `
+  --sources openalex,crossref `
+  --confidence-threshold 0.85 `
+  --max-requests 2000 `
+  --output-dir risultati `
+  --mailto nome@example.org
+```
+
+`--depth 0` checks only the provided references. With higher values, it can follow works cited by the verified publications and build a larger graph.
+
+## Usage with a skill
+
+The skill is located in [.github/skills/bibcheck-verify](.github/skills/bibcheck-verify). To install it:
+
+1. install the `bibcheck-verify` command, from the repository with `uv tool install .` or from PyPI with `uv tool install bibcheck-verify` once it is available;
+2. copy the entire `.github/skills/bibcheck-verify/` directory to the skills directory supported by your Hermes Agent or Claude Code installation;
+3. ask the agent to verify a PDF, Markdown, text, or BibTeX file.
+
+The session model reads the bibliography and creates a temporary file with the title, authors, year, DOI, journal, and search query. The `bibcheck-verify` command reads the original file, applies that metadata, and queries Crossref and OpenAlex. The model proposes metadata; it does not decide whether a publication exists.
+
+This mode does not require `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, or `GEMINI_API_KEY`. It does require network access to the bibliographic sources, and the `bibcheck-verify` command must be available in the agent’s PATH.
+
+## API keys and LLM fallback
+
+Standalone usage can ask the program to extract incomplete metadata through an LLM provider. This is an optional fallback and does not replace verification against Crossref/OpenAlex.
+
+```powershell
+$env:OPENAI_API_KEY = "..."
+bibcheck-verify verify references.md --llm-provider openai
+```
+
+The `openai`, `anthropic`, and `gemini` providers are supported. Keys must remain in environment variables or a local `.env` file, never in the repository, reports, or metadata JSON file.
+
+## Results
+
+The output directory `bibcheck-verify-results` contains:
+
+- `summary.md`: readable report for manual review;
+- `graph.json`: complete details, queries, sources, nodes, edges, and confidence;
+- `cache.sqlite3`: local resolution cache.
+
+The main statuses are:
+
+- `verified`: verified match, including through an exact DOI;
+- `verified_fuzzy`: match accepted by fuzzy comparison;
+- `low_confidence`: possible match that is not sufficiently strong;
+- `suspected_hallucination`: no match found in the consulted sources.
+
+`suspected_hallucination` is a triage label, not proof that the reference is fabricated. All uncertain cases require human review.
+
+## Project structure
+
+```text
+bibcheck-verify/
+├── src/bibcheck/                 # Internal Python module for the bibcheck-verify command
+│   ├── cli.py                    # `bibcheck-verify` commands and options
+│   ├── ingest/                   # BibTeX, PDF, and text parsers
+│   ├── resolve/                  # Crossref, OpenAlex, fuzzy matching, and optional LLM
+│   ├── graph/                    # citation graph cache and traversal
+│   └── report/                   # Markdown and JSON output
+├── tests/                        # automated package tests
+├── .github/skills/bibcheck-verify/ # skill for compatible agents
+│   ├── SKILL.md                  # agent operating instructions
+│   └── README.md                 # manual skill installation
+├── pyproject.toml                # metadata, dependencies, and console command
+├── uv.lock                       # locked dependency versions
+├── .env.example                  # local LLM configuration example
+└── README.md                     # this guide
+```
+
+The `bibcheck-verify-results*` directories are results from local runs and are not part of the distributed package.
+
+## Development and testing
+
+To prepare the repository environment:
+
+```powershell
+uv sync --extra test
+uv run python -m pytest
+```
+
+The distributable package is built with:
+
+```powershell
+uv build
+```
+
+Artifacts are created in `dist/`. Before publishing to PyPI, it is advisable to check the wheel contents and test it in a clean environment or on TestPyPI.
+
+## Publishing to PyPI
+
+Publishing is optional and is not required to use the project locally. In summary:
+
+1. create an account on PyPI and, preferably, a project-scoped token;
+2. run `uv build`;
+3. check the artifacts in `dist/`;
+4. upload to TestPyPI first;
+5. upload to PyPI using the token, without saving it in versioned files.
+
+The `bibcheck-verify` distribution name must be available on PyPI. The installed package provides the `bibcheck-verify` command. The actual upload requires the owner’s credentials and is not performed by this repository.
+
+## Limitations
+
+- verification requires network access;
+- Crossref and OpenAlex may have incomplete or differing data;
+- the request limit may produce a partial result;
+- the cache may reuse previous resolutions;
+- no result replaces review of the original bibliography.