Plagiarism Detector Pro README

🌟 Why Plagiarism Detector Pro?

Most open-source plagiarism checkers rely on basic string searching or single-word keyword matching, causing massive false-positive keyword collisions (e.g. flagging common nouns like "diamonds", "seaborn", or "price").

Plagiarism Detector Pro finds contiguous lexical overlap in the sources it can retrieve and adds statistical writing-pattern diagnostics. It does not reproduce the private corpora or scoring methods used by Blackboard SafeAssign or Turnitin.

┌──────────────────────────────────────────────────────────────────────────────────┐
│                             PLAGIARISM DETECTOR PRO                              │
├─────────────────────────┬──────────────────────────────┬─────────────────────────┤
│   🌐 Web Application    │    📦 Standalone CLI & NPM   │   🤖 Claude & Codex MCP │
│  • Interactive split-UI │  • 100% offline local engine │  • Native JSON-RPC MCP  │
│  • Batch ZIP gradebook  │  • Zero server dependency    │  • 1-click citation bot │
│  • PDF / Cert export    │  • Fast terminal feedback    │  • Real-time coach tool │
└─────────────────────────┴──────────────────────────────┴─────────────────────────┘

📦 NPM Package & Standalone CLI (100% Offline)

The CLI and NPM package operate completely offline and standalone with built-in embedded benchmark corpora. Zero Python or web server required!

1. Installation

# Global installation
npm install -g plagiarism-detector-pro

# Or run instantly with npx (no install needed)
npx plagiarism-detector-pro --help

2. CLI Command Suite

# 🔍 1. Scan a document for text similarity and AI-pattern signals
plag scan thesis_draft.md
plag scan essay.docx --verbose   # Shows side-by-side matching passages
plag scan paper.tex --json       # Outputs machine-readable JSON

# 🧑‍🎓 2. Student Writing & Integrity Coach
# Scans unsupported empirical claims, formal vocabulary boosts, and thesis strength
plag coach manuscript.docx

# 🔬 3. PhD Research & Conference Double-Blind Pre-Flight Auditor
# Audits anonymity compliance, isolates LaTeX math, and profiles section cadence
plag audit neurips_paper.pdf

# ✍️ 4. Smart Academic Paraphraser & Attribution Helper
# Generates 3 academic restructuring options (Active Inversion, Methodological, Conceptual)
plag paraphrase "Deep neural networks learn rich representations from massive text corpora." --source "Vaswani2017"

# 📚 5. Instant DOI, arXiv & Scientific Citation Generator
# Resolves DOIs/arXiv IDs into copy-ready BibTeX, APA 7th, MLA 9th, and IEEE
plag cite 10.1038/s41586-020-2649-2
plag cite 1706.03762

# 🔤 6. Reference List Alphabetizer & Clean Formatter
# Auto-sorts unorganized bibliographies by primary author, validates years & DOIs
plag alphabetize unorganized_references.txt

# 📑 7. Draft-to-Draft Revision Comparator
# Evaluates revision percentage, newly added sections, and retained text between drafts
plag diff draft_v1.txt draft_v2.txt

# 📦 8. Class Gradebook Batch Processor
# Ingests an entire folder of student assignments and prints an aggregated gradebook table
plag batch ./student_submissions/

# 📜 9. Advisory Pre-Submission Analysis Summary
# Generates an unsigned advisory summary with a SHA-256 analysis reference
plag certificate essay.md --name "Jane Doe" --title "Deep Learning Study"

# 🤖 10. Start Model Context Protocol (MCP) Server for Claude & Codex
plag mcp

# 🧹 11. Deterministic Writing Cleanup (offline, reviewable word swaps)
# Applies only the flagged predictable-vocabulary suggestions already shown by `plag scan` -- no rewriting, no network
plag cleanup essay.docx --apply --output essay.clean.txt

# ✅ 12. One Combined Pre-Submission Verdict
# Merges pattern-score, provenance-flag, and evidence-integrity signals into one clear/needs_review call + top 3 fixes
plag check essay.docx
plag check essay.docx --json   # Machine-readable, e.g. for CI or a script that gates on the verdict

🤖 Claude Desktop, Claude Code & Codex MCP Integration

Plagiarism Detector Pro implements the Model Context Protocol (MCP), allowing Claude Desktop, Claude Code, OpenAI Codex, Antigravity, and Cursor to inspect lexical overlap, check citation syntax, and restructure text.

Claude Desktop Setup

Add this configuration to your Claude Desktop config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "plagiarism-detector-pro": {
      "command": "npx",
      "args": ["-y", "plagiarism-detector-pro", "mcp"]
    }
  }
}

Claude Code CLI Setup

claude mcp add plagiarism-detector-pro npx -y plagiarism-detector-pro mcp

Available MCP Tools for AI Assistants:

🌐 Running as a Web Server

If you wish to host your own web platform instance with the interactive dashboard, PDF report generator, and class gradebook:

Option A: Docker Compose (Recommended)

# 1. Clone repository
git clone https://github.com/scalesynthai/Plagiarism-Detector-Pro.git
cd Plagiarism-Detector-Pro

# 2. Start container
docker compose up -d --build

Open http://localhost:5001 in your browser.

Option B: Local Python Setup

# 1. Create and activate virtual environment
python3 -m venv venv
source venv/bin/activate   # On Windows: venv\Scripts\activate

# 2. Install dependencies
pip install -r requirements.txt

# 3. Launch development server
python app.py

Environment Configuration

Export these variables before running Python. Docker Compose reads a local .env; direct Python execution does not load that file automatically.

FLASK_ENV=production
SECRET_KEY=your-secure-random-secret-key
ADMIN_PIN=replace-with-a-long-random-secret # Required for corpus uploads and deletions
PORT=5001
MAX_CONTENT_LENGTH=33554432 # 32 MB request limit; each document is limited to 8 MB

🎓 Key Features & Capabilities

1. 🛡️ Student "Private Draft Shield"

• Scans do not add submitted manuscripts to the local corpus. With web search enabled, search terms derived from the manuscript are sent to external providers. Set include_web to false for local-only checks. The private_draft flag does not disable web requests. This project does not provide access to proprietary Turnitin/SafeAssign databases or guarantee external submission outcomes.

2. 🧑‍🎓 Student Academic Writing & Integrity Coach

• 🔍 Unsupported Claim Finder: Detects empirical and statistical assertions ("studies show", "85% of", "research demonstrates") lacking a parenthetical citation, with a 1-click (Author, Year) citation placeholder.
• ✍️ Scholarly Tone Booster: Identifies conversational phrases ("a lot of", "basically", "big impact") and provides instant formal replacements (numerous, fundamentally, significant effect).
• 🎯 Thesis Statement & Abstract Evaluator: Evaluates scientific completeness (Hypothesis, Methodology, Significance) with a /100 score and actionable recommendations.

3. 🔬 PhD Research & Conference Pre-Flight Auditor

• 🔒 Double-Blind Anonymity Compliance: Detects self-identifying author references or unblinded repository links before conference submission (NeurIPS, ICML, ICLR, IEEE).
• 📐 Mathematical & LaTeX Isolation: Isolates LaTeX equations ($...$, \begin{equation}) and code cells from false similarity flags.

4. ↔️ Interactive Side-by-Side Split Diff Comparison

• Clicking any highlighted sentence opens a split-screen viewer comparing the student submission on the left with the verbatim original source on the right.

5. 🤖 Writing-Pattern Heuristic

• Scores nine explainable signal groups: vocabulary, sentence rhythm, hedging, structure, specificity, transitions, punctuation, register, and rhetorical scaffolding.
• Shows the exact phrases and sentence spans behind every non-zero category, plus sample-length reliability.
• Reports em-dash count and rate separately so punctuation feedback is actionable without treating one mark as proof of AI use.
• Adds an evidence-integrity profile for claim citation coverage, bibliography linkage, and available source quality.
• Flags literal AI-tool copy-paste artifacts (unfilled placeholders, leftover chatbot citation markup, AI-tool tracking links) separately from the style score, since those are checkable facts rather than inference.
• Offers a deterministic, opt-in cleanup: apply the exact word-swap suggestions already shown, reviewed one by one, fully offline. Not a rewrite engine and not built to change how any third-party detector scores the result — see Deterministic writing cleanup.
• Combines the pattern score, provenance flags, and evidence-integrity score into one clear / needs_review verdict with the top 3 fixes (plag check, or the check_summary field on /check) — no new detection, just one answer instead of three separate outputs to reconcile.
• See Explainable writing-pattern scoring and third-party notices.
• See the end-to-end AI Writing Style Review architecture and coverage matrix.

6. 📦 Whole-Class Batch Submissions Gradebook

• Upload a .zip archive or multiple files to scan all submissions concurrently and produce an aggregated Instructor Gradebook Table.

📡 REST API Reference

🧪 Testing & Quality Assurance

Plagiarism Detector Pro includes comprehensive test suites across both Python and Node.js:

# Run Node.js & CLI test suite (14 tests)
npm test

# Run Python & Web test suite (69 tests)
pytest tests/ -v
# Or: ./venv/bin/python -m unittest discover tests -v

# Run all test suites
make test

⚖️ Institutional Academic Advisory & Disclaimer

[!IMPORTANT] Advisory & Formative Purpose: Similarity metrics, uncalibrated writing-pattern scores, thesis-structure scores, and writing-coach diagnostics are intended for pre-submission review and academic coaching. They do not establish plagiarism, authorship, or AI use.

Official academic integrity determinations, final course grades, and institutional submission clearances are governed exclusively by your university's specific Honor Code, academic policies, course syllabus, and faculty review. No automated scoring tool constitutes a final institutional endorsement.

🤝 Contributing & Security

Contributions are warmly welcomed! Please read our Contributing Guide and Code of Conduct before submitting pull requests.

If you discover a security vulnerability, please consult our Security Policy or report it privately to security@subba.dev.

📄 License

This project is open-source software licensed under the MIT License.

Reliability and deployment notes

See HARDENING.md for verified fixes, supported limits, and remaining production work. Similarity and AI scores are heuristics, not proof of plagiarism or authorship. Certificates are advisory summaries of supplied scores and are not signed attestations.

Corpus uploads and deletions require X-Admin-PIN. Without a configured ADMIN_PIN, corpus mutations are disabled. Uploads reject empty or malformed documents and existing filenames; delete an existing source explicitly before replacing it. Configure both SECRET_KEY and ADMIN_PIN before starting Docker Compose.

Run python -m unittest discover tests -v and npm test before release. CI runs both language suites; automated deployment runs only after successful push CI.

Passage scoring and accuracy checks

The Python API and Node engine now use exact-word-spans-v1: four-word contiguous seeds (at least two non-function words) extend through identical neighboring words. Unique matched query words determine coverage; overlapping sources cannot inflate the overall score. Semantic paraphrases and very short fragments may be missed. A citation identifies attribution and does not automatically erase similarity.

exclude_quotes / Node excludeQuotes excludes only quoted word spans. exclude_bibliography / Node excludeBibliography excludes a standalone References/Bibliography section. Excluded words leave both numerator and denominator. Responses include the selected score, raw whole-document score, body-only score, bibliography and quotation scores, matched spans, and the eligible word count. Body-only means excluding the bibliography, not automatically removing the title page. Bibliography/quotation scores are within their own sections and do not sum to the overall score. Source percentages can overlap. Offsets reference normalized_text (Python Unicode code points; Node UTF-16 code units).

CLI JSON and human-readable scans accept --exclude-quotes and --exclude-bibliography. The browser provides both switches. Citation, thesis, and anonymity diagnostics are structural screening aids, not verification of sources, writing quality, or conference acceptance.

See benchmark documentation and machine-readable baseline. Run python benchmarks/run.py in the checkout to compare Python and Node against fixed labels without network requests.