ReviewerZero
README.md
<div align="center">
<h1>📝 ReviewerZero</h1>
<p><strong>Catch your citation and numeric-claim errors before Reviewer 2 does.</strong></p>
[](https://www.python.org/)
[](https://pypi.org/)
[](https://www.latex-project.org/)
[](https://opensource.org/licenses/MIT)
[](https://modelcontextprotocol.io/)
[](https://github.com/IamOumarIbrahim/ReviewerZero/actions/workflows/ci.yml)
</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.
```toml
# 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?](#-what-is-reviewerzero)
- [Key Features](#-key-features)
- [System Architecture](#-system-architecture)
- [Mathematical & Technical Formulation](#-mathematical--technical-formulation)
- [Setup & Installation](#-setup--installation)
- [Connecting to AI Clients](#-connecting-to-ai-clients)
- [How to Use](#-how-to-use)
- [Reference Tables](#-reference-tables)
- [Scope & Limitations](#-scope--limitations)
- [File Structure](#-file-structure)
- [Troubleshooting](#-troubleshooting)
- [Contributing](#-contributing)
- [Deployment & Releases](#-deployment--releases)
- [Security Policy & Code of Conduct](#-security-policy--code-of-conduct)
- [License](#-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:
```mermaid
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
```bash
pip install reviewerzero
```
### Option B: Installation from Source
```bash
git clone https://github.com/IamOumarIbrahim/ReviewerZero.git
cd ReviewerZero
pip install -e .
```
🔍 **Verification Command**:
```bash
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:
```json
{
"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:
```bash
reviewerzero audit paper.tex --bib refs.bib
```
2. Audit using a local PDF directory for offline mode:
```bash
reviewerzero audit paper.tex --bib refs.bib --sources ./sources/
```
3. Override drift tolerances and export an HTML report:
```bash
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](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:
```bash
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](SECURITY.md) for vulnerability disclosure procedures.
- **Code of Conduct**: ReviewerZero adheres to the Contributor Covenant Code of Conduct. Read [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md).
---
## 📄 License
MIT © 2026 [Oumar Ibrahim](https://github.com/IamOumarIbrahim)
## 🙏 Powered By
[pylatexenc](https://github.com/phfaist/pylatexenc) · [PyMuPDF](https://github.com/pymupdf/PyMuPDF) · [pdfplumber](https://github.com/jsvine/pdfplumber) · [bibtexparser](https://github.com/sciunt/bibtexparser)
<div align="center">
If ReviewerZero caught something before your advisor did, a ⭐ helps other researchers find it.
</div>
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessSyncing