Metadata-Version: 2.4
Name: pdf2wiki
Version: 0.1.2
Summary: Convert technical books (native-text PDFs) into clean, chapter-split, LLM-ready Markdown using a dual-pass MinerU pipeline plus fidelity-preserving post-processing.
Project-URL: Homepage, https://github.com/Sevthered/pdf2wiki
Project-URL: Repository, https://github.com/Sevthered/pdf2wiki
Project-URL: Documentation, https://github.com/Sevthered/pdf2wiki/tree/main/docs
Project-URL: Issues, https://github.com/Sevthered/pdf2wiki/issues
Project-URL: Changelog, https://github.com/Sevthered/pdf2wiki/blob/main/CHANGELOG.md
Author: Sevthered
License-Expression: AGPL-3.0-or-later
License-File: LICENSE
Keywords: book,conversion,knowledge-base,markdown,mineru,obsidian,pdf
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Text Processing :: Markup :: Markdown
Requires-Python: >=3.11
Requires-Dist: pymupdf>=1.24
Description-Content-Type: text/markdown

# pdf2wiki

[![PyPI](https://img.shields.io/pypi/v/pdf2wiki)](https://pypi.org/project/pdf2wiki/)
[![Python](https://img.shields.io/pypi/pyversions/pdf2wiki)](https://pypi.org/project/pdf2wiki/)
[![License: AGPL-3.0](https://img.shields.io/pypi/l/pdf2wiki)](LICENSE)

Convert heavily technical books (native-text PDFs) into clean, chapter-split, **LLM-ready Markdown** —
code byte-perfect, tables intact, diagrams transcribed to Mermaid — suitable for an Obsidian vault or
any Markdown-native knowledge base.

Built on [MinerU](https://github.com/opendatalab/MinerU) with a **dual-pass strategy**: a pipeline pass
(`-m txt`) takes byte-perfect code and text from the PDF's embedded text layer, a hybrid/VLM pass
(`--effort high`) reconstructs table grids and transcribes diagrams to Mermaid, and a base-driven merge
grafts the good parts together — token-verifying code so a hallucinating VLM never corrupts a listing.
A six-step post-processing chain then cleans and splits the result into per-chapter files.

Why two backends instead of one: [why a dual-backend pipeline](docs/explanation/why-dual-backend.md).

## Requirements

- Linux (native or WSL2) with an NVIDIA GPU, **≥ 8 GB VRAM**, CUDA driver installed
- Python ≥ 3.11
- [MinerU](https://github.com/opendatalab/MinerU) ≥ 3.4 on `PATH`
- A C compiler for vLLM's Triton JIT: `sudo apt install build-essential python3-dev`

Only the conversion needs the GPU — `phase5`, `qa`, and `scan` run anywhere Python runs.

## Install

```bash
uv tool install pdf2wiki        # or: pip install pdf2wiki
```

Full steps: [install pdf2wiki](docs/how-to/install.md).

## Quickstart

```bash
# 1. convert one book  ->  out/my-book/my-book.md + images/ + blocks.json
pdf2wiki convert book.pdf --name my-book

# 2. preview the cleanup + chapter split (dry-run)
pdf2wiki phase5 out/my-book/my-book.md --book my-book

# 3. apply it  ->  out/my-book/chapters/00-front-matter.md, 01-….md, …
pdf2wiki phase5 out/my-book/my-book.md --book my-book --source-name book.pdf --apply
```

New here? Follow the guided [tutorial: convert your first book](docs/tutorials/convert-your-first-book.md).

## Documentation

Full docs live in [`docs/`](docs/), organized by intent ([Diátaxis](https://diataxis.fr/)):

- **Tutorials** — [convert your first book](docs/tutorials/convert-your-first-book.md)
- **How-to** — [convert](docs/how-to/convert-a-book.md) · [post-process & split](docs/how-to/post-process-and-split.md) · [batch](docs/how-to/run-a-batch.md) · [QA](docs/how-to/qa-a-conversion.md) · [remote GPU](docs/how-to/set-up-remote-gpu.md) · [troubleshoot](docs/how-to/troubleshoot.md)
- **Reference** — [CLI](docs/reference/cli.md) · [configuration](docs/reference/configuration.md) · [pipeline stages](docs/reference/pipeline-stages.md) · [phase 5 steps](docs/reference/phase5-steps.md) · [output layout](docs/reference/output-layout.md)
- **Explanation** — [why dual-backend](docs/explanation/why-dual-backend.md) · [how the merge works](docs/explanation/how-the-merge-works.md) · [design principles](docs/explanation/design-principles.md)
- **Architecture** — [overview with C4 diagrams](docs/architecture/architecture.md)

## Status

**Alpha.** All stages are functional; the converter was ported from a production deployment validated
on several full technical books, and the coverage gate hard-stops rather than silently dropping
content. Remote mode is **experimental** — no full public end-to-end run yet; prefer local mode.

## License

AGPL-3.0-or-later. This tool drives the MinerU CLI (AGPL-3.0) as an external process.
