ScholarOCR

A reusable academic-document OCR and intelligence engine for AI agents. You extract a document once into a structured, source-traceable representation, then retrieve, verify and export it in any format without running OCR again. The main agent integration is an Antigravity CLI plugin: install it, sign in with your own Google account, and Antigravity's model reads the pages. Other agents connect through the same MCP server or the CLI, and a Claude Code skill teaches Claude how to use it.

No API key is needed. By default the model doing the reading is the one in your own chat client (Antigravity, Claude Code, Claude Desktop, and ChatGPT through the hosted app): the server does every deterministic step and hands that model one page image at a time (host mode). A Gemini or OpenRouter key is optional and switches to ScholarOCR's dedicated server-side OCR pipeline.

Antigravity CLI (plugin) · Claude Code · ChatGPT (hosted) · other MCP clients · scripts
        │ MCP (stdio/HTTP)          │ CLI          │ Python
        └────────────► ScholarOCR service ◄────────┘
     ingestion → routing → text layer (no model)
                         → visual pages: render, crop, deskew →  host mode: your client's model
                                                                    (get_page_image → submit_page_content)
                                                                 key mode: Gemini / OpenRouter
     → validation → IR checkpoints → verification → exports (JSON, Markdown, searchable PDF, DOCX, LaTeX, CSV/XLSX)

What it does

• Per-page hybrid extraction. Reliable PDF text layers are extracted deterministically with no model call. Scans, photos, math-font pages and image-heavy pages need vision. Screenshots and photos are cropped to the document region (app/screen chrome removed), skew and rotation are corrected and dark-mode notes are handled before any model sees the page. Blank pages are skipped. Duplicate pages are flagged, never dropped.

• Two ways to read the visual pages.

  • Host mode (default): the MCP client's model gets one page image with the rules and the exact JSON shape, transcribes it, and submits it. The server validates the submission strictly (every problem reported with its path and a fix) and stores it like any other extraction.

  • Key mode: Gemini or OpenRouter with a profile per page type (general, math, handwriting), structured output, and a targeted review of flagged elements by a second model.

• Academic structure.

  • LaTeX for equations and mhchem for chemistry.

  • Tables with spans; figures and diagrams with crops, labels and descriptions.

  • Questions, sub-questions and marks.

  • Headings, captions, footnotes and bibliography entries.

• Traceability. Every element has page, source file, bounding box and a source crop. get_source_region returns the original pixels.

• Honest uncertainty. Labels are ordinal (low/medium/high/unresolved). Unreadable regions are marked, never guessed. LaTeX, tables and legibility are checked deterministically.

• Operations.

  • Page-level checkpoints and a content-hash cache.

  • Background jobs with cancel, resume and crash recovery.

  • Retries, rate limiting and usage tracking (key mode).

  • Path allow-listing and retention.

Quality trade-off. Host mode is a single pass by a general chat model, at whatever resolution the client passes to it, and its optional review pass is the same model looking at a crop again. Key mode uses a dedicated OCR prompt, the PDF text layer as a hint and an independent review model. Validation, uncertainty rules, traceability and verification are the same in both. Accuracy on real scans has not been measured for either mode yet.

Related MCP server: DocImprint Document Intelligence

Status

Tests: pytest --ignore=tests/live, see docs/QUALITY_ASSURANCE.md for the current count.

Quick start: Antigravity CLI (no key)

uv tool install "git+https://github.com/adiroy911/scholarocr"     # the server: scholarocr-mcp on PATH
agy plugin install https://github.com/adiroy911/scholarocr         # the plugin

Antigravity starts the server in the plugin folder, so list the folders it may read in %LOCALAPPDATA%\ScholarOCR\scholarocr.env (~/.local/share/scholarocr/scholarocr.env on macOS/Linux):

SCHOLAROCR_ALLOWED_DIRS=C:\Users\you\Documents;D:\Study

Start agy and ask it to read a document ("extract the scanned exam in D:\Study\chem and list anything unreadable"). Keys are optional. Details, headless runs and the verified result: docs/ANTIGRAVITY_PLUGIN.md.

Quick start: CLI and Python

git clone https://github.com/adiroy911/scholarocr && cd scholarocr
python -m venv .venv && . .venv/bin/activate     # Windows: .\.venv\Scripts\Activate.ps1
pip install -e ".[dev]"
scholarocr process path/to/paper.pdf --type exam-paper   # text-layer PDFs work without any key
scholarocr content <document_id>
scholarocr export <document_id> --format searchable-pdf

The CLI has no model of its own: for scans it needs a key (cp .env.example .env, set GEMINI_API_KEY or OPENROUTER_API_KEY), otherwise it stops with exit code 6 and lists the pages awaiting transcription. Through MCP, your client's model transcribes them instead.

Connect Claude Code (no key needed):

python scripts/install_skill.py      # copies claude-skill/scholarocr to ~/.claude/skills
claude mcp add --scope user scholarocr -e SCHOLAROCR_ALLOWED_DIRS="<folders>" -- "<venv>/bin/scholarocr-mcp"
# optional key mode: add -e GEMINI_API_KEY="<key>"

Examples: examples/01_python_api.py, examples/02_cli_workflow.sh, examples/03_mcp_client.py, and the config snippet examples/claude_code.mcp.json.

Documentation

Repository layout

The repository root is also the Antigravity plugin root: .antigravity-plugin/plugin.json, mcp_config.json, rules/, skills/ and assets/ are the plugin. src/scholarocr/ is the Python package and claude-skill/scholarocr/ is the Claude Code skill. Changes are listed in CHANGELOG.md.

Licence

MIT, see LICENSE. The DejaVu test fonts in tests/fixtures/fonts/ keep their own licence (LICENSE_DEJAVU).