magicrew/doc7: turning PDFs and scans into AI-ready Markdown with a local vision model

The problem doc7 targets: pages that text extraction cannot read

Most document-to-Markdown tools start from the characters embedded in the file. That works for born-digital text and fails for everything else. A scanned page has no text layer. A chart has no text layer. A displayed equation, a diagram whose meaning lives in its arrows, a screenshot of a UI state: none of these survive a character-extraction pass, and an OCR pass recovers glyphs without recovering relationships.

doc7 takes the opposite starting point. The README describes it as reading "the whole page instead of stopping at character extraction," and the repository's own example is a raster-only page from Attention Is All You Need with no text layer, from which doc7 reports recovering the paper identity, Figure 2, a displayed equation, a technical footnote, and the ordered relationships inside two attention diagrams.

The intended user is someone building a knowledge base, a retrieval index, or a quoting workflow on top of documents that are partly or wholly image-based. The README frames the output as Markdown that an AI "can search, quote, and reason over," which is a different goal from producing a human-readable facsimile. It is not aimed at high-volume text-native PDFs where a simple extractor would be faster and cheaper.

One visual pipeline instead of a format-by-format OCR stack

The architecture claim in the README is that "different containers enter the same page-understanding pipeline." PDFs, Office files, scans, screenshots, charts, formulas and diagrams are all normalized into page images, and those images go to a multimodal model. Text, tables, formulas, charts, diagram relationships, image meaning and visible UI state come out as a single Markdown document. Multi-page inputs are processed as ordered pages and then "rebuilt into one document."

That design has a clear consequence. There is no required OCR stack and no per-page document-parser fee from doc7 itself, because the parsing work is delegated to whichever OpenAI-compatible multimodal endpoint you supply. The model is not a fallback for hard pages; it is the parser. The repository ships a benchmark directory comparing runs where MarkItDown OCR and doc7 used the same qwen3.5-9b model through the same local endpoint, and Docling used its standard local pipeline. In that run doc7 recovered 15/15 checked visual facts, MarkItDown with its OCR plugin 9/15, and Docling's standard pipeline 3/15. Those are the project's own numbers on two raster-only PDFs and fifteen machine-checkable facts, so treat them as a directional signal about pipeline design rather than a general accuracy rating.

The Go module list is consistent with a self-contained binary: Cobra for the CLI, goldmark for Markdown handling, the official MCP Go SDK, and image decoding libraries. The Dockerfile installs libreoffice, mupdf-tools, chromium and CJK fonts, which tells you where the non-PDF format handling and the rendering actually happen in the container image.

Installing doc7 and converting your first document

The README gives two install paths. The script installer is described as the recommended macOS path: it downloads a checksum-verified release and installs under your user directory, so no administrator account is needed.

curl -fsSL https://raw.githubusercontent.com/magicrew/doc7/main/scripts/install.sh | bash

On Windows the equivalent is a PowerShell one-liner:

irm https://raw.githubusercontent.com/magicrew/doc7/main/scripts/install.ps1 | iex

If you take the archive route instead and macOS attaches a quarantine attribute to the downloaded binary, the README says to run this after extracting, from Terminal:

xattr -dr com.apple.quarantine <extracted-directory>

The README is explicit that this removes the local download quarantine and is not Apple signing or notarization. Official Developer ID signing and notarization are described as planned for a future signed release channel, so a browser-downloaded binary will still trip Gatekeeper warnings.

Before converting anything, start LM Studio or Ollama and load a local vision model. Then conversion is a single command:

doc7 report.pdf
doc7 screenshot.png

The README states that the first run detects the system language, finds running local model servers, reads their real model IDs, lets you choose when several are available, verifies image understanding, and saves the choice on this machine. LM Studio and Ollama endpoints without authentication need no API key. For a remote endpoint you configure it with `doc7 setup`. The same binary also exposes an interactive chat agent, batch processing, model checks, MCP and an asynchronous HTTP service, but `doc7 <file>` is described as the stable direct conversion entrypoint.

Chat and the restricted filesystem tool set

`doc7 chat` runs a small agent on the configured local model. Ordinary messages go straight to the model and need no document:

doc7 chat "Hello, introduce yourself"
doc7 chat

When you explicitly supply a file, directory or URL and ask doc7 to process it, the model can call a restricted `convert_document` tool:

doc7 chat "Turn report.pdf into knowledge-base Markdown"

The README is clear that there is no keyword or language-specific intent parser; the model decides whether to use tools through OpenAI-compatible Tool Calling. For a vague filename, chat can use a structured read-only filesystem tool set (`pwd`, `ls`, `find`, `file`, `stat`, `wc`, `realpath`) inside authorized directories and then ask you to pick a candidate before converting. It never receives an arbitrary shell string: no pipes, redirects, scripts, writes, network commands or process controls. `head` and `tail` are separate preview tools because they expose limited text content to the model, and chat asks for confirmation before using them.

The session starts with the working directory plus existing Desktop, Documents and Downloads directories; anything else needs an explicit path typed into the local terminal. Models without Tool Calling can still chat, but the README points you back to `doc7 <file>` for conversion. This is a deliberately narrow agent, and the narrowness is the point: the blast radius of a confused model is a read of a file you authorized.

Where doc7 is the wrong tool

The model is the parser, so output quality is bounded by the model. A small or weak vision model will produce confident, wrong Markdown, and nothing in the pipeline described in the README cross-checks the model's reading against the page. The benchmark numbers are the project's own, on two raster-only PDFs and fifteen machine-checkable facts; they do not tell you how the pipeline behaves on a 400-page text-native contract where a plain extractor would be both faster and more faithful.

Cost and latency follow the same logic. Every page is a vision model call. There is no per-page parser fee from doc7, but there is whatever your endpoint charges, plus the time to render and infer. For a corpus of text-native PDFs, routing through a vision model is strictly more expensive than extracting the text layer.

Reproducibility is the other boundary. A vision model can phrase the same table differently on two runs. If your downstream system needs byte-stable output for diffing or audit, a model-driven parser is a poor fit.

Finally, the README does not document rollback, version pinning for models, or how the saved per-machine model choice is invalidated when you switch endpoints. The installer is checksum-verified, but there is no signed release channel yet, and the macOS quarantine removal is a manual step the README itself describes as not notarization.

How doc7 differs from MarkItDown and Docling

The comparison that matters is not feature lists but where the intelligence sits. MarkItDown is a text-extraction tool: it reads what is already encoded in the file, and its OCR plugin adds glyph recognition for pages without a text layer. In the project's benchmark run, MarkItDown with its OCR plugin scored 9/15 on the checked visual facts using the same qwen3.5-9b model and the same local endpoint as doc7. The gap is not the model. It is that OCR recovers characters, while the checked facts in that benchmark include diagram relationships and a displayed equation.

Docling's standard local pipeline scored 3/15 in the same run, using its own pipeline rather than the shared endpoint. Docling is a document-conversion framework with its own layout and table models; it is built to run without an external vision endpoint, which is a real advantage if you cannot run one. The trade-off is that its standard pipeline is tuned for structure recovery on conventional documents, not for reading the meaning of a chart or a UI screenshot.

doc7 sits between them in a specific way: it has no built-in parsing models at all, so it is only as good as the endpoint you give it, and in exchange it can be pointed at a private deployment and handles image-only pages through the same code path as ordinary ones.

Licence, container deployment and upgrade cost

doc7 is MIT licensed, which permits commercial use, modification and redistribution provided the copyright notice and permission notice are retained. The Dockerfile labels the image with `org.opencontainers.image.licenses="MIT"`. That is a statement about the project's own code, not about the models you connect to it: your endpoint's licence, and the licence of any document you feed through it, are separate questions. This is not legal advice; check the terms of your model provider and your source documents.

The container path is documented in `docker-compose.yml`. It requires two environment variables to start, `DOC7_MODEL` and `DOC7_SERVER_TOKEN`, and defaults `DOC7_BASE_URL` to `http://host.docker.internal:1234/v1`, which is the standard LM Studio port. The service listens on port 8787 inside the container and is mapped from `${DOC7_PORT:-8787}`. The compose file sets `DOC7_CREDENTIAL_STORE: env`, `DOC7_TIMEOUT_SECONDS: 600`, `no-new-privileges:true`, and a 40 second stop grace period, with named volumes for `/config` and `/data`.

Upgrade cost is mostly the image. The runtime stage installs ca-certificates, chromium, curl, fonts-noto-cjk, libreoffice and mupdf-tools on debian:bookworm-slim, so pulling a new image is a substantial download rather than a small binary swap. The CLI path is lighter: the install script fetches a checksum-verified release, and the repository's most recent release listed is v0.1.2, pushed on 2026-08-07, with a Windows portable build published the same day. The README does not document a downgrade path or a changelog policy, so pinning a specific release tag is the only version control the repository currently supports.

Editorial conclusion

Adopt doc7 if you already run a local or private OpenAI-compatible vision model and want page-level visual understanding rather than a text layer, and if you accept that output quality tracks the model you point it at. Skip it if you need deterministic, reproducible extraction with no model in the loop, or if you cannot run a multimodal endpoint at all. Before committing, verify two things: that your chosen model passes the image-understanding probe during setup, and that your pages survive the rasterization step, since the pipeline is designed around rendered pages rather than embedded text.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. magicrew/doc7 on GitHub
4. README
5. Releases