Metadata-Version: 2.4
Name: DocmaxV3
Version: 3.0.0a7
Summary: Terminal-native document toolkit. Local-first, dual-engine, no server required.
Author: Punith Naidu
Maintainer-email: Punith Naidu <punithmedaramitta@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/megabyte44/docmax
Project-URL: Repository, https://github.com/megabyte44/docmax
Project-URL: Issues, https://github.com/megabyte44/docmax/issues
Project-URL: Changelog, https://github.com/megabyte44/docmax/blob/main/CHANGELOG.md
Keywords: pdf,ocr,document,cli,tui,terminal,conversion,batch
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business
Classifier: Topic :: Utilities
Classifier: Typing :: Typed
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: typer>=0.12.0
Requires-Dist: rich>=13.7.0
Requires-Dist: pypdf>=4.2.0
Requires-Dist: platformdirs>=4.2.0
Requires-Dist: httpx>=0.27.0
Provides-Extra: ocr
Requires-Dist: pytesseract>=0.3.10; extra == "ocr"
Requires-Dist: pdf2image>=1.17.0; extra == "ocr"
Requires-Dist: opencv-python-headless>=4.9.0; extra == "ocr"
Requires-Dist: numpy>=1.26.0; extra == "ocr"
Provides-Extra: tables
Requires-Dist: pdfplumber>=0.11.0; extra == "tables"
Requires-Dist: pandas>=2.2.0; extra == "tables"
Requires-Dist: openpyxl>=3.1.0; extra == "tables"
Provides-Extra: images
Requires-Dist: Pillow>=10.3.0; extra == "images"
Requires-Dist: img2pdf>=0.5.0; extra == "images"
Provides-Extra: tui
Requires-Dist: textual>=0.60.0; extra == "tui"
Provides-Extra: server
Requires-Dist: DocmaxV3[all]; extra == "server"
Requires-Dist: fastapi>=0.111.0; extra == "server"
Requires-Dist: uvicorn[standard]>=0.30.0; extra == "server"
Requires-Dist: python-multipart>=0.0.9; extra == "server"
Provides-Extra: all
Requires-Dist: DocmaxV3[images,ocr,tables,tui]; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest>=8.2.0; extra == "dev"
Requires-Dist: pytest-cov>=5.0.0; extra == "dev"
Requires-Dist: pytest-timeout>=2.3.0; extra == "dev"
Requires-Dist: hypothesis>=6.100.0; extra == "dev"
Requires-Dist: respx>=0.21.0; extra == "dev"
Requires-Dist: ruff>=0.5.0; extra == "dev"
Requires-Dist: mypy>=1.10.0; extra == "dev"
Requires-Dist: import-linter>=2.0; extra == "dev"
Requires-Dist: pre-commit>=3.7.0; extra == "dev"
Dynamic: license-file

# DocMax

**A document toolkit that lives in your terminal.** Merge, split, OCR, compress,
convert, redact — locally, privately, with no server to run and no browser tab
to open.

```bash
pip install DocmaxV3
docmax merge a.pdf b.pdf -o combined.pdf
```

> **Status: early development (M0).** The architecture and safety mechanisms are
> in place; the tools are being rebuilt on top of them one at a time. For a
> working tool today, use [`docmax` 2.x](https://pypi.org/project/docmax/).
> See [the roadmap](#roadmap) for what lands when.

---

## Why another PDF tool

The good self-hosted options — Stirling PDF and friends — are excellent, and
they all assume a browser. That means Docker, a running server, a port, and no
sensible way to use them over SSH or from a script.

DocMax assumes a terminal instead.

|  | DocMax | Self-hosted web tools |
|---|---|---|
| Install | `pip install DocmaxV3` | Docker + a container |
| Interface | CLI and TUI | browser |
| Over SSH | works | needs port forwarding |
| Scripting | argv | HTTP against a running server |
| Your documents | stay on your machine | stay on your machine |

## Two engines, one interface

Every operation can run two ways, and the choice is yours per tool:

- **Local** — offline and private. Needs the relevant dependencies installed.
- **Cloud** — no local install at all. For the handful of tools whose
  dependencies are genuinely painful.

```bash
docmax ocr scan.pdf                     # picks whichever is available
docmax ocr scan.pdf --engine local      # force local
docmax ocr scan.pdf --engine cloud      # skip installing Tesseract
```

Cloud exists for exactly one reason — to let you use a tool without installing
its heavy dependencies. Only five tools have it (`ocr`, `compress`, `convert`,
`pdfa`, `remove-bg`), because for a pure-Python operation like `merge`,
uploading your document would be slower, less private, and pointless.

**Nothing is ever uploaded without asking.** Consent is per-tool and remembered;
`offline = true` in your config disables cloud entirely regardless of flags; and
every upload tells you what it is sending before it sends it. The cloud endpoint
is configurable, so you can point DocMax at your own server instead.

## Your files are safe

This is the part most tools get wrong, so it is worth being specific.

- **Atomic writes.** Output goes to a temp file, gets validated, and is only then
  swapped into place. A crash or Ctrl-C mid-operation leaves your destination
  either untouched or absent — never half-written.
- **Your input is never the output.** `docmax merge a.pdf b.pdf -o a.pdf` is
  refused, not silently obeyed.
- **Nothing is overwritten by accident.** Existing files need `--force`.
- **No tracebacks.** Every anticipated failure gives you a plain message and the
  next step to take.

These are enforced by tests that run on every commit across Linux, macOS, and
Windows — not by good intentions. See
[architecture.md](docs/architecture.md#the-structural-guarantees).

## Install

```bash
pip install DocmaxV3              # the shell and the cloud client
pip install "DocmaxV3[ocr]"       # local OCR
pip install "DocmaxV3[all]"       # everything
```

The base install is deliberately small. Heavy dependencies arrive only when you
first ask for a local engine that needs them.

Some local engines also need external programs (Ghostscript, Tesseract, Pandoc,
Poppler):

```bash
docmax doctor                     # what's installed, what's missing, what needs it
```

## Roadmap

| | | |
|---|---|---|
| **M0** | Foundation — architecture, CI, safety mechanisms | ✅ done |
| **M1** | Core engine + `merge` as the reference implementation | in progress |
| **M2** | `split`, `rotate`, `reorder`, `pages`, `metadata`, `sanitize`, `get-info` | |
| **M3** | `compress` + a real `setup` / `doctor` | |
| **M4** | `watermark`, `stamp`, `protect`, `unlock`, `permissions` | |
| **M5** | `convert`, `to-images`, `from-images` | |
| **M6** | Cloud engines, `--json` everywhere, published benchmarks | |
| **M7** | Textual TUI + visual pickers for crop and reorder | |
| **M8** | OCR, done properly | |
| **M9** | Pipelines, resumable batch, folder watch | |
| **M10** | Local MCP server — drive DocMax from an AI agent, nothing leaves your machine | |

Benchmarks will be published in `benchmarks/` with real hardware and
methodology. No numbers appear in this README until they are measured.

## Contributing

```bash
git clone https://github.com/megabyte44/docmax
cd docmax
python -m venv .venv && .venv/bin/pip install -e ".[dev]"
pre-commit install

pytest && ruff check . && mypy && lint-imports
```

Start with [docs/architecture.md](docs/architecture.md) and the
[ADRs](docs/adr/) — they explain the constraints, most of which exist for a
specific reason.

## Licence

MIT. Every document operation is free and always will be — see
[ADR 0004](docs/adr/0004-open-core-boundary.md) for where the open-core line
sits and why.
