Metadata-Version: 2.4
Name: docdistill
Version: 0.1.0
Summary: Document → text via VLM. Independent Python MCP server (Office→PDF + PDF→Markdown/LaTeX/JSON).
Project-URL: Homepage, https://github.com/Joe-zhouman/docdistill
Project-URL: Repository, https://github.com/Joe-zhouman/docdistill
Project-URL: Changelog, https://github.com/Joe-zhouman/docdistill/blob/main/CHANGELOG.md
License-Expression: MIT
License-File: LICENSE
Requires-Python: >=3.10
Requires-Dist: click>=8.1
Requires-Dist: fastmcp>=3.3
Requires-Dist: httpx>=0.27
Requires-Dist: mineru-open-sdk>=0.2
Requires-Dist: pypdf>=4.0
Requires-Dist: pypdfium2>=4.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Description-Content-Type: text/markdown

# docdistill

Document → text via VLM. An independent Python MCP server with two tools:
`document_to_pdf` (Office→PDF via real renderers) and `analyze_doc` (PDF→Markdown/LaTeX/JSON
via MinerU's VLM). Local file paths only, no CDN, images localized.

> Predecessor: seed-viz's `analyze_doc` (Node), now independent and pure-Python.

## Install

In your MCP client (`.mcp.json`):

```json
{
  "mcpServers": {
    "docdistill": {
      "command": "uvx",
      "args": ["docdistill"],
      "env": { "BACKEND": "mineru-official", "AUTH": "<your-mineru-token>" }
    }
  }
}
```

Get a free MinerU token (1000/day): https://mineru.net/apiManage/token

## Backends

| `BACKEND` | What it hits | `AUTH` | `ENDPOINT` |
|---|---|---|---|
| `mineru-official` (default) | mineru.net cloud | required (MinerU token) | optional (default mineru.net) |
| `mineru-tasks-v3.2` | your self-hosted mineru-api | none | required (e.g. http://127.0.0.1:5580) |

`mineru-tasks-v3.2` is for users who self-host MinerU (e.g. an intranet-shared deployment:
one install serves a whole campus LAN). No rate limits, no auth, data stays local.

## Platform support (v1)

- **PDF extraction** (`analyze_doc`): all platforms (hosted backend, any networked machine).
- **Office→PDF** (`document_to_pdf`): **Linux (LibreOffice) + Windows (Word/PowerPoint COM)** only.
  macOS users get an honest error for Office files — export to PDF manually, then `analyze_doc`.

## CLI

```bash
docdistill document-to-pdf paper.docx        # → paper.pdf, hint to use analyze_doc
docdistill analyze-doc paper.pdf              # → .docdistill/paper.md + .docdistill/images-<hash>/
docdistill analyze-doc thesis.pdf --output-format latex
docdistill analyze-doc doc.pdf --backend mineru-tasks-v3.2 --endpoint http://127.0.0.1:5580
```

Output lands in `.docdistill/` next to the source. The images directory uses a
short hash name (`images-<hash>`) rather than the source filename, so image
references render correctly even when the source PDF has spaces/non-ASCII in
its name. PDFs >180 pages auto-paginate.

## Known behavior: VLM splits multi-subfigure figures

The VLM extracts purely from visual content and does **semantic segmentation**,
not pixel-chopping. On a large figure with several subfigures (e.g. a paper's
"Fig. 4 (a)–(e)"), it tends to split it into one image block per visually
bounded subfigure. Conversely, a region that *looks* like a table (clear grid
lines) is extracted as a Markdown table rather than an image — which is usually
what you want.

This is the VLM's own behavior, not a docdistill bug, and there is no API
switch to disable it. Switching to the non-VLM `pipeline` model avoids the
split but noticeably degrades text quality, so docdistill uses VLM. If you need
the original single-image figure, refer to the source PDF.

## Status

0.1.0 beta. Interface may change before 1.0.
