ReviewerZero

<div align="center"> <h1>📝 ReviewerZero</h1> <p><strong>Catch your citation and numeric-claim errors before Reviewer 2 does.</strong></p>

</div>

---

📌 GitHub Repository About & Topics

About Description:

Automated LaTeX citation and numeric claim auditor for IEEE-style academic papers. Parses .tex and .bib, resolves sources via arXiv, Crossref, and Semantic Scholar, and cross-checks numerical claims against resolved full-text sources.

Topics / Tags: latex · bibtex · academic-writing · citation-checker · ieee · mcp · claim-verification · python · research-tools · nlp

---

[!IMPORTANT] Platform & Runtime Notice: Requires Python 3.11+. No API keys are required for arXiv, Crossref, or Semantic Scholar source resolution. Offline audit mode is supported via local PDF directories using --sources.

ReviewerZero is an automated LaTeX citation and numeric claim auditing system. It parses your .tex source and .bib bibliography, resolves every reference to its full text, and cross-checks numerical values, percentages, and physical units near each citation against what the cited paper actually reports — catching rounding errors, unit mismatches, and figure drift before submission.

# reviewerzero.toml project configuration example
tight_tolerance = 0.005  # 0.5% tolerance for Verified claims
loose_tolerance = 0.05   # 5.0% tolerance for Close Match claims
sources_dir = "./sources/"

<br />

📖 Table of Contents

• What is ReviewerZero?
• Key Features
• System Architecture
• Mathematical & Technical Formulation
• Setup & Installation
• Connecting to AI Clients
• How to Use
• Reference Tables
• Scope & Limitations
• File Structure
• Troubleshooting
• Contributing
• Deployment & Releases
• Security Policy & Code of Conduct
• License

---

💡 What is ReviewerZero?

Academic drafts accumulate numerical values across months of revision: metrics copied from earlier experiment runs, statistics remembered slightly off, rounding adjustments that were not updated in every sentence, or citations renumbered when sections were reorganized. Traditional spellcheckers and LaTeX linters do not inspect numerical consistency against cited literature.

Instead of manually re-reading every cited paper to verify numbers at 11pm before a conference deadline, ReviewerZero automates citation verification end-to-end:

• LaTeX-Aware Sentence Extraction: Isolates every \cite/\citep/\citet call and extracts the surrounding sentence and exact file.tex:line location.
• Source Text Resolution: Fetches full-text papers automatically from arXiv, Crossref, and Semantic Scholar with persistent local caching for offline re-runs.
• Unit-Normalized Matching: Converts physical units across frequencies, durations, power scales, and distances before comparing relative numerical tolerances.

---

✨ Key Features

• 📄 LaTeX-Aware Parsing: Parses LaTeX source using pylatexenc, extracting citation keys and exact line contexts without false-positive matching on LaTeX control sequences.
• 🔗 Automatic Source Resolution: Resolves .bib entries via arXiv, Crossref, and Semantic Scholar APIs without API keys, backed by a persistent .reviewerzero_cache disk cache.
• 🔢 Unit-Aware Numeric Matching: Normalizes numbers across unit families (dB, %, Hz–GHz, s–μs, W–dBm, m–km) to SI base units before checking relative tolerance drift.
• 📐 IEEE Convention Linting: Checks first-appearance citation order, flags duplicate or unused .bib entries, and detects missing DOI/URL fields.
• 📋 Human-Readable Audit Reports: Outputs Markdown, standalone HTML, or console reports detailing file:line locations, claim text, citations, verdicts, and source excerpts.
• 🧩 MCP Tool Mode: Exposes a standard MCP audit_paper tool via reviewerzero-mcp for integration into AI agent workflows.

---

⚙️ System Architecture

The pipeline processes LaTeX and BibTeX inputs through five sequential stages:

graph TD
    Tex["paper.tex + refs.bib"] --> Parse

    subgraph Parse["1. Parse"]
        Cites["Extract \\cite calls + surrounding sentence"] --> Nums["Extract numeric/unit tokens"]
    end

    Nums --> Resolve

    subgraph Resolve["2. Resolve"]
        Cache{"In local cache?"}
        Cache -->|No| API["arXiv / Crossref / Semantic Scholar"]
        Cache -->|Yes| Cached["Cached source text"]
        API --> Cached
    end

    Cached --> Extract["3. Extract source text (pdfplumber / PyMuPDF)"]
    Extract --> Check

    subgraph Check["4. Cross-Check"]
        Match["Unit-normalized tolerance matching"] --> Verdict{Verdict}
    end

    Verdict --> Report["5. Markdown/HTML Audit Report"]

    classDef default fill:#0f172a,stroke:#3b82f6,stroke-width:2px,color:#fff;
    classDef process fill:#1e1b4b,stroke:#a855f7,stroke-width:2px,color:#fff;
    class Parse,Resolve,Check process;

[!NOTE] Triage Design Decision: ReviewerZero acts strictly as a verification and triage assistant. It intentionally generates audit reports rather than modifying .tex source files automatically.

---

📐 Mathematical & Technical Formulation

For a claimed numeric value $v_{\text{claim}}$ extracted near a citation, and the set of unit-compatible candidate numeric tokens ${v_1, v_2, \dots, v_n}$ extracted from the resolved source text (after normalizing all values to SI base units):

$$\delta = \min_{i} \frac{|v_{\text{claim}} - v_i|}{\max(|v_{\text{claim}}|, \epsilon)}$$

Where:

• $v_{\text{claim}}$ — Claimed numerical value extracted from the LaTeX sentence context.
• $v_i$ — Candidate numerical value extracted from the resolved source text.
• $\epsilon$ — Epsilon denominator threshold ($10^{-9}$) to prevent division by zero.
• $\delta$ — Minimum relative difference across unit-compatible candidates.

Verdict Classification Schema

ReviewerZero classifies each claim verdict based on project tolerances:

Verdict	Condition	Meaning
✅ Verified	$\delta \le \tau_{\text{tight}}$ (default $0.5%$)	Numerical value matches source within rounding tolerance
⚠️ Close Match	$\tau_{\text{tight}} < \delta \le \tau_{\text{loose}}$ (default $5.0%$)	Value drifted slightly — requires manual author review
❌ Not Found	$\delta > \tau_{\text{loose}}$ for all candidates, or no unit candidate found	No matching numerical figure located in resolved source text
❓ Source Unavailable	Source paper could not be fetched or extracted	Flagged for manual verification (not treated as code error)

Both thresholds $\tau_{\text{tight}}$ and $\tau_{\text{loose}}$ are configurable via reviewerzero.toml or CLI flags.

---

🚀 Setup & Installation

Option A: Installation via PyPI / Pip

pip install reviewerzero

Option B: Installation from Source

git clone https://github.com/IamOumarIbrahim/ReviewerZero.git
cd ReviewerZero
pip install -e .

🔍 Verification Command:

reviewerzero --version

Expected Output: ReviewerZero 1.0.0

---

🔌 Connecting to AI Clients

ReviewerZero includes a Model Context Protocol (MCP) server entrypoint (reviewerzero-mcp).

1. Open your client configuration file (e.g. claude_desktop_config.json):
   • Claude Desktop: %APPDATA%\Claude\claude_desktop_config.json (Windows) or ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)
2. Add the MCP server entry:

{
  "mcpServers": {
    "reviewerzero": {
      "command": "reviewerzero-mcp"
    }
  }
}

3. Restart your AI client. The audit_paper(tex_path, bib_path) tool will load into the active tools registry.

---

🖥️ How to Use

1. Run an audit on your paper against its .bib bibliography:

reviewerzero audit paper.tex --bib refs.bib

2. Audit using a local PDF directory for offline mode:

reviewerzero audit paper.tex --bib refs.bib --sources ./sources/

3. Override drift tolerances and export an HTML report:

reviewerzero audit paper.tex --bib refs.bib --loose-tolerance 0.02 --format html -o audit_report.html

---

📊 Reference Tables

CLI Flag Reference

Flag	Type	Description	Default
tex_file	Path	Path to primary .tex document	Required
--bib	Path	Path to BibTeX .bib reference file	Required
--sources	Path	Path to directory containing local source PDFs/txts	None
--tight-tolerance	Float	Threshold for Verified status ($\tau_{\text{tight}}$)	0.005 (0.5%)
--loose-tolerance	Float	Threshold for Close Match status ($\tau_{\text{loose}}$)	0.05 (5.0%)
--format	Enum	Output format (console, markdown, html)	console
-o, --output	Path	File path to write audit report	None (stdout)

Configuration Schema (reviewerzero.toml)

Key	Type	Description	Default
tight_tolerance	Float	Tight matching tolerance factor	0.005
loose_tolerance	Float	Loose matching tolerance factor	0.05
sources_dir	String	Directory path for local source documents	""

---

🔬 Scope & Limitations

• Numeric/Quote Level, Not Semantic: ReviewerZero verifies whether stated numbers and units match cited literature; it does not evaluate conceptual paper suitability.
• Paywalled Literature: If a publisher paywall blocks full-text retrieval and no local PDF is supplied via --sources, the claim is classified as Source Unavailable.
• Triage Aid: The tool does not auto-modify .tex files, preserving full author control over manuscript edits.

---

📁 File Structure

ReviewerZero/
├── reviewerzero/
│   ├── __init__.py        - Package version and metadata
│   ├── parse_tex.py       - LaTeX/BibTeX parsing (pylatexenc, bibtexparser)
│   ├── resolve.py          - arXiv/Crossref/Semantic Scholar resolution + cache
│   ├── extract.py           - PDF text extraction (pdfplumber, PyMuPDF)
│   ├── match.py               - Unit-aware tolerance matching engine
│   ├── lint.py                 - IEEE citation-order and bib-hygiene checks
│   ├── report.py                - Markdown/HTML report generation
│   ├── mcp_server.py             - Model Context Protocol tool wrapper
│   └── cli.py                  - Main CLI argument parser & entrypoint
├── tests/
│   ├── test_claim_formula.py    - Formula re-derivation & unit conversion unit tests
│   ├── test_full_pipeline.py    - End-to-end parsing & report tests
│   └── test_troubleshooting.py - Troubleshooting scenario tests
├── .github/
│   └── workflows/
│       └── ci.yml               - Automated CI build and test workflow
├── pyproject.toml               - Package build configuration
├── LICENSE                      - MIT License
├── REQUIREMENTS.md              - Verifiable claims checklist
└── VERIFICATION.md              - Proof artifact & verification evidence

---

🩹 Troubleshooting

Issue	Root Cause	Resolution
Every claim shows "Source Unavailable"	No internet access and no --sources folder provided	Provide local PDFs via --sources ./sources/
Citation not found in .bib	Key mismatch between .tex and .bib	Confirm \cite{key} matches .bib entry key
False "Not Found" on a correct claim	Source uses a synonymous unit (e.g. dBm vs mW) not in table	Extend unit normalization mapping in match.py

---

🧩 Contributing

Contributions are welcome! Please read our CONTRIBUTING.md guide for guidelines on setting up a development environment, submitting bug reports, extending unit conversion tables in match.py, and creating pull requests.

---

🚀 Deployment & Releases

• CI/CD Pipeline: GitHub Actions automates testing across Python versions on every push and pull request (.github/workflows/ci.yml).
• GitHub Release Command: Releases are published with git tags and GitHub Releases:

  gh release create v1.0.0 --title "v1.0.0 - Initial Production Release" --notes "First production release of ReviewerZero."
  

---

🔒 Security Policy & Code of Conduct

• Security Policy: Read our SECURITY.md for vulnerability disclosure procedures.
• Code of Conduct: ReviewerZero adheres to the Contributor Covenant Code of Conduct. Read CODE_OF_CONDUCT.md.

---

📄 License

MIT © 2026 Oumar Ibrahim

🙏 Powered By

pylatexenc · PyMuPDF · pdfplumber · bibtexparser

<div align="center">

If ReviewerZero caught something before your advisor did, a ⭐ helps other researchers find it.

</div>