AIBit-Discover Open Source Projects AIBit-Discover Open Source Projects

doc7: Turn Any Document into AI-Ready Markdown with Visual Understanding

doc7 converts PDFs, Office files, scans, and diagrams into AI-ready Markdown using your own multimodal model, eliminating OCR stacks and per-page fees.

doc7: Turn Any Document into AI-Ready Markdown with Visual Understanding

If you've ever tried to feed a PDF or a scanned document into an AI pipeline, you know the pain. Traditional extraction tools rely on OCR and layout parsers that often mangle tables, drop formulas, and completely miss the meaning of diagrams. doc7 takes a different approach: instead of trying to parse the document character by character, it renders each page as an image and lets a vision-language model (VLM) read the whole page, understanding the layout, relationships, and context. The result is clean, searchable Markdown that your AI can actually reason over.

Why Visual Understanding Beats Traditional Extraction

Most document-to-Markdown tools fall into one of three categories:

  • Format and text extraction (like MarkItDown's default path): These use file-specific parsers to pull out text and basic structure. They work fine for simple text files but fail on complex layouts, scanned pages, or anything with visual meaning.
  • Vision-model OCR wrappers (like Zerox): These convert pages to images and send them to a vision API, but they're often tied to a specific provider and require extra dependencies like GraphicsMagick.
  • Dedicated document AI stacks (like MinerU or Docling): These run a pipeline of OCR, layout, table, and formula models. They're powerful but heavy—you need to manage multiple model weights and infrastructure.

doc7 skips all that. It renders each page to an image and sends it to any OpenAI-compatible multimodal model you choose. The model sees the whole page—text, tables, charts, diagrams, even the spatial relationships between elements—and outputs Markdown directly. This means no OCR stack, no per-page fees, and no lock-in to a document-processing service.

Quick Start: From Zero to Markdown in Minutes

Getting started is surprisingly simple. Install doc7 with a one-liner, point it at a local vision model (like one running in LM Studio or Ollama), and convert your first document:

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

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

# Convert a document
doc7 report.pdf

The first run automatically discovers local model endpoints (LM Studio and Ollama), lets you pick a model if multiple are available, and verifies image understanding before saving your choice. No API key needed for local endpoints.

Real-World Benchmark: doc7 vs. MarkItDown vs. Docling

The project includes an open benchmark that shows exactly why visual understanding matters. They took two raster-only PDFs (no text layer) and checked 15 machine-verifiable visual facts. Using the same qwen3.5-9b model through the same local endpoint, doc7 recovered 15/15 facts, while MarkItDown with its OCR plugin got 9/15, and Docling's standard pipeline only managed 3/15.

Here's the breakdown:

System Attention paper Visual report Combined Raw Markdown
doc7 + qwen3.5-9b 7/7 8/8 15/15 5,293 bytes
MarkItDown 0.1.6 + OCR 0.1.0 + qwen3.5-9b 3/7 6/8 9/15 13,142 bytes
Docling 2.113.0 standard 1/7 2/8 3/15 2,571,445 bytes
MarkItDown 0.1.6 default N/A N/A N/A 0 bytes

MarkItDown's default path returned an empty file for both raster-only inputs, which is why it's marked N/A. Docling's raw Markdown is huge because it embeds page images as Base64—that's not a quality score, just a diagnostic.

The benchmark is fully reproducible: every raw output, SHA-256 digest, scoring rule, and machine-readable result is committed to the repo. You can run it yourself and verify the results.

One Pipeline for Every Format

One of doc7's strengths is its format coverage. Whether you're dealing with PDFs, Office documents, scans, screenshots, charts, formulas, or diagrams, they all go through the same visual-understanding pipeline. The output is a single Markdown document that preserves:

  • Headings, paragraphs, lists, quotes, and code → native Markdown structure
  • Tables and spreadsheets → Markdown or HTML tables with values and units
  • Mathematical notation → inline or display LaTeX
  • Charts → labels, values, trends, and conclusions as searchable text
  • Diagrams and workflows → nodes, ordering, grouping, and relationships
  • Screenshots and application states → visible status, errors, controls, and actions
  • Email messages → headers, HTML or text bodies, inline images, and attachment inventory
  • Jupyter notebooks → Markdown cells, source code, execution counts, text output, tracebacks, and visual output

Supported input formats include PDF, DOCX, PPTX, XLSX, EPUB, EML, MHTML, MSG, IPYNB, images (PNG, JPEG, GIF, WebP, BMP, TIFF, SVG), and even native text/data formats like Markdown, CSV, JSON, XML, and YAML. Office and OpenDocument files require LibreOffice; PDF rendering uses MuPDF when available; HTML, SVG, EPUB, and email formats require Chrome, Chromium, or Edge.

Built Around the CLI

The command-line interface is the heart of doc7. It provides everything from simple conversion to advanced features like page selection, resume, and batch processing.

Page Selection and Resume

Long documents can be processed in chunks, and failed pages can be retried without starting over:

# Process only pages 5 and 7
doc7 read report.pdf -o report-pages-5-7 --pages 5,7

# Resume a previous run, retrying failed pages
doc7 read report.pdf -o report-doc7 --resume

The manifest records source page counts and page selection, and successful pages remain byte-for-byte unchanged. If no failed pages remain, --resume validates the artifacts and rebuilds the merged Markdown without calling the model.

Piping and Stdin

You can pipe the merged Markdown directly into another tool:

doc7 read report.pdf --stdout > report.md

# Or read from stdin
cat report.pdf | doc7 read - --stdin-name report.pdf --stdout > report.md

Remote Documents and Directories

# Read a directory recursively
doc7 read ./documents -o ./knowledge

# Read a remote document
doc7 read https://example.com/report.pdf -o ./report-doc7

Run As a Service

For integration into larger systems, doc7 can run as an asynchronous HTTP service:

doc7 serve --addr 127.0.0.1:8787 --data-dir ./doc7-server

Submit a document or ZIP archive:

curl -F [email protected] http://127.0.0.1:8787/v1/jobs

The response includes a job ID. Poll the status URL, then download the merged Markdown or the complete artifact ZIP:

curl http://127.0.0.1:8787/v1/jobs/<job-id>
curl -o report.md http://127.0.0.1:8787/v1/jobs/<job-id>/markdown
curl -o report-artifacts.zip http://127.0.0.1:8787/v1/jobs/<job-id>/artifacts

You can even resume failed pages in a job:

curl -X POST -H 'Content-Type: application/json' -d '{}' http://127.0.0.1:8787/v1/jobs/<job-id>/resume

Security is built in: the service defaults to localhost, requires a bearer token for non-local bind addresses, limits upload size, and isolates each job directory.

Use From AI Tools: MCP Server

doc7 includes an MCP server with a typed convert_to_markdown tool. Configure your MCP client to launch the binary over stdio:

{
  "mcpServers": {
    "doc7": {
      "command": "/absolute/path/to/doc7",
      "args": ["mcp"],
      "env": {
        "DOC7_BASE_URL": "http://127.0.0.1:1234/v1",
        "DOC7_MODEL": "qwen3.5-0.8b",
        "DOC7_CREDENTIAL_STORE": "env"
      }
    }
  }
}

The tool accepts a local path, directory, HTTP(S) URL, or ZIP archive and returns Markdown plus structured conversion metadata.

Embed In Go

The public Go package exposes the same conversion engine. Here's a minimal example:

package main

import (
    "context"
    "log"

    "github.com/magicrew/doc7"
)

func main() {
    options := doc7.DefaultReadOptions()
    options.OutputDir = "report-doc7"
    options.BaseURL = "http://127.0.0.1:1234/v1"
    options.Model = "qwen3.5-4b"
    result, err := doc7.Read(context.Background(), "report.pdf", options)
    if err != nil {
        log.Fatal(err)
    }
    if result.Document != nil {
        log.Println(result.Document.MergedMarkdown)
    }
}

You can also use Convert and ConvertBatch for explicit single-document or directory-only APIs.

Cost and Privacy: Your Model, Your Infrastructure

doc7 doesn't sell document credits or charge per page. You bring your own multimodal model—local or private—and process as many documents as your hardware can handle. The marginal cost of another document is just the electricity and operating time.

This is a fundamentally different cost structure from cloud document APIs:

Option Typical billing unit Cost as document volume grows Document location
doc7 + local quantized VLM No doc7 per-page fee Mostly existing hardware, electricity, and operations Local or private infrastructure
AWS Textract Pages, priced by API and analysis feature Usage grows with pages and features Cloud API
Google Document AI Pages, usually priced per processor and volume tier Usage grows with pages and processor type Cloud API
Azure Document Intelligence Pages, model, and pricing tier Usage grows with pages and selected capability Cloud API
Alibaba Cloud OCR Pay-as-you-go calls or prepaid packages Continued processing consumes calls or quota Cloud API
Tencent Cloud OCR API calls through prepaid or postpaid billing Continued processing consumes calls or quota Cloud API
Baidu AI Cloud OCR API calls, free quota, and paid usage Continued processing consumes calls or quota Cloud API

Cloud APIs are still useful when you want managed capacity and don't want to operate a model. But if you want to eliminate a recurring document-parser bill and keep your documents private, doc7 is the way to go.

Advanced Features

Text Grounding

For PDFs and Office files with an embedded text layer, you can enable an optional exact-value check:

doc7 read report.pdf --text-grounding

This doesn't replace the visual result with extracted text. Instead, it checks exact numbers, codes, and identifiers from the embedded text layer and asks the visual model to confirm candidate corrections. It's off by default and may make additional model requests.

Context Fallbacks

If the model's context window is too small for a page, doc7 automatically retries with a lower-resolution image. You can configure this with --context-fallbacks and --min-image-dimension. If all fallbacks are exhausted, the page is marked as failed rather than writing truncated Markdown.

Custom Prompts

You can use a domain-specific conversion prompt without modifying doc7:

doc7 read ./reports --prompt-file ./prompt.md

Docker

The Docker image includes LibreOffice, MuPDF, Chromium, and CJK fonts. It runs the HTTP service as a non-root user and persists configuration and jobs in named volumes:

export DOC7_MODEL=qwen3.5-0.8b
export DOC7_SERVER_TOKEN=replace-me
docker compose pull
docker compose up --no-build

The published image is ghcr.io/magicrew/doc7:latest and supports both linux/amd64 and linux/arm64.

Security Considerations

doc7 runs local renderers like LibreOffice and Chrome with the current user's permissions. Treat untrusted Office files, HTML, SVG, EML, MSG, IPYNB, and archives as active input—use an isolated account or container for untrusted workloads. Email and notebook HTML is sanitized, remote resources are removed, and embedded BMP/TIFF images are normalized before rendering. API keys are sent as bearer credentials to the configured endpoint, so verify the endpoint before processing sensitive files.

Conclusion

doc7 is a refreshing take on document conversion. By leveraging visual understanding, it handles complex documents that traditional parsers struggle with, and it does so with a simple, unified pipeline. Whether you're building a RAG system, an agent knowledge base, or just need to make your documents searchable, doc7 is worth a serious look. The open benchmark and reproducible results give you confidence in its capabilities, and the MIT license means you can integrate it freely.

Try it out on your own documents and see the difference visual understanding makes.

Source

magicrew/doc7: Turn documents into AI-ready Markdown with visual understanding