DocmaxV3 3.0.0a7__tar.gz

docmaxv3-3.0.0a7/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Punith Naidu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

docmaxv3-3.0.0a7/PKG-INFO

@@ -0,0 +1,196 @@
+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.

docmaxv3-3.0.0a7/README.md

@@ -0,0 +1,132 @@
+# 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.

docmaxv3-3.0.0a7/pyproject.toml

@@ -0,0 +1,240 @@
+[build-system]
+requires = ["setuptools>=77", "wheel"]
+build-backend = "setuptools.build_meta"
+
+# ============================================================================
+# NOTE: product identity also lives in src/docmax/core/branding.py.
+# tests/hygiene/test_branding.py asserts the two stay in sync and that brand
+# literals do not leak into other modules.
+# ============================================================================
+
+[project]
+name = "DocmaxV3"
+version = "3.0.0a7"
+description = "Terminal-native document toolkit. Local-first, dual-engine, no server required."
+readme = "README.md"
+requires-python = ">=3.11"
+authors = [{ name = "Punith Naidu" }]
+maintainers = [{ name = "Punith Naidu", email = "punithmedaramitta@gmail.com" }]
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = ["pdf", "ocr", "document", "cli", "tui", "terminal", "conversion", "batch"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: End Users/Desktop",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Office/Business",
+    "Topic :: Utilities",
+    "Typing :: Typed",
+]
+
+# Base install stays light — non-negotiable #3.
+# Everything here is pure Python and installs in seconds on every platform.
+# Heavy deps (OpenCV, Tesseract bindings, ML models) live in extras and are
+# imported lazily, never at module scope. See tests/hygiene/test_no_heavy_imports.py
+dependencies = [
+    "typer>=0.12.0",
+    "rich>=13.7.0",
+    "pypdf>=4.2.0",
+    "platformdirs>=4.2.0",
+    "httpx>=0.27.0",
+]
+
+[project.optional-dependencies]
+# Each extra maps to the local engine of a specific tool group.
+# `docmax setup` installs the external *binaries*; these are the Python bindings.
+ocr = [
+    "pytesseract>=0.3.10",
+    "pdf2image>=1.17.0",
+    "opencv-python-headless>=4.9.0",
+    "numpy>=1.26.0",
+]
+tables = [
+    "pdfplumber>=0.11.0",
+    "pandas>=2.2.0",
+    "openpyxl>=3.1.0",
+]
+images = [
+    "Pillow>=10.3.0",
+    "img2pdf>=0.5.0",
+]
+tui = [
+    "textual>=0.60.0",
+]
+# Dependencies for the reference API server — the half a self-hoster deploys.
+# Not in `all`: installing DocMax should never install a web framework by
+# accident. Note this extra installs what the server *needs*, not the server
+# itself: its code is excluded from the wheel (see packages.find below) and is
+# run from a checkout.
+server = [
+    "DocmaxV3[all]",
+    "fastapi>=0.111.0",
+    "uvicorn[standard]>=0.30.0",
+    "python-multipart>=0.0.9",
+]
+# v2 shipped a `full` extra that silently omitted opencv, which broke the entire
+# OCR path for anyone who installed it. Self-referencing extras make that class
+# of mistake impossible — there is only one list.
+#
+# Must match [project].name exactly: "docmax" is already taken on PyPI by the
+# v2 package under this same author, so "docmax[...]" here would silently
+# resolve to that external package instead of self-referencing, shadowing the
+# local editable install with v2's incompatible module layout.
+all = [
+    "DocmaxV3[ocr,tables,images,tui]",
+]
+dev = [
+    "pytest>=8.2.0",
+    "pytest-cov>=5.0.0",
+    "pytest-timeout>=2.3.0",
+    "hypothesis>=6.100.0",
+    "respx>=0.21.0",
+    "ruff>=0.5.0",
+    "mypy>=1.10.0",
+    "import-linter>=2.0",
+    "pre-commit>=3.7.0",
+]
+
+[project.scripts]
+docmax = "docmax.cli.main:app"
+
+[project.urls]
+Homepage = "https://github.com/megabyte44/docmax"
+Repository = "https://github.com/megabyte44/docmax"
+Issues = "https://github.com/megabyte44/docmax/issues"
+Changelog = "https://github.com/megabyte44/docmax/blob/main/CHANGELOG.md"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+# The server is the half a self-hoster deploys from a checkout, inside an image
+# that also carries Ghostscript, Tesseract, and Pandoc — none of which pip can
+# install. So it has no reason to be in the wheel, and one reason not to be:
+# every byte here lands in the site-packages of someone who only wanted to merge
+# two PDFs. tests/hygiene/test_wheel_excludes_server.py holds the line.
+exclude = ["docmax.server*"]
+
+[tool.setuptools.package-data]
+docmax = ["py.typed"]
+
+# ============================================================================
+# Ruff
+# ============================================================================
+[tool.ruff]
+target-version = "py311"
+line-length = 100
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = [
+    "E", "W",    # pycodestyle
+    "F",         # pyflakes
+    "I",         # isort
+    "N",         # pep8-naming
+    "UP",        # pyupgrade
+    "B",         # bugbear
+    "A",         # builtin shadowing
+    "C4",        # comprehensions
+    "PT",        # pytest style
+    "SIM",       # simplify
+    "RET",       # return consistency
+    "PTH",       # use pathlib, not os.path
+    "S",         # bandit — this project shells out; we want these loud
+    "T20",       # no stray print() in library code
+    "RUF",
+]
+ignore = [
+    "E501",    # line length is handled by the formatter
+    "S101",    # assert is fine in tests
+    "RUF012",  # ClassVar annotations on mutable defaults — noisy for our error classes
+]
+
+[tool.ruff.lint.per-file-ignores]
+# Tests may assert, use fixtures loosely, and print.
+"tests/**" = ["S", "T20", "ARG", "PLR2004"]
+# The CLI layer is the one place that legitimately writes to stdout.
+"src/docmax/cli/**" = ["T20"]
+# FastAPI's dependency-injection idiom is a call in an argument default, which
+# B008 exists to catch. It is correct everywhere else.
+"src/docmax/server/**" = ["B008"]
+
+[tool.ruff.lint.isort]
+known-first-party = ["docmax"]
+
+# ============================================================================
+# Mypy — strict. There is no legacy code to grandfather in.
+# ============================================================================
+[tool.mypy]
+python_version = "3.11"
+strict = true
+warn_unreachable = true
+warn_no_return = true
+show_error_codes = true
+pretty = true
+files = ["src", "tests"]
+
+# Third-party packages without type stubs. Kept as a short, explicit list so
+# that adding one is a visible decision rather than a blanket ignore.
+[[tool.mypy.overrides]]
+module = [
+    "pytesseract.*",
+    "pdf2image.*",
+    "cv2.*",
+    "img2pdf.*",
+    "pdfplumber.*",
+    "rembg.*",
+]
+ignore_missing_imports = true
+
+# The server extra is not part of `dev`: the lint job type-checks the terminal
+# tool, and a self-hosted API server should not be able to slow that down or
+# break it. These two overrides are what that costs.
+[[tool.mypy.overrides]]
+module = [
+    "fastapi.*",
+    "starlette.*",
+    "uvicorn.*",
+]
+ignore_missing_imports = true
+
+[[tool.mypy.overrides]]
+module = ["docmax.server.*"]
+# FastAPI's route decorators are untyped when the framework itself is absent.
+disallow_untyped_decorators = false
+
+# ============================================================================
+# Pytest
+# ============================================================================
+[tool.pytest.ini_options]
+minversion = "8.0"
+testpaths = ["tests"]
+addopts = [
+    "--strict-markers",
+    "--strict-config",
+    "-ra",
+]
+# No test may hang. Property tests feed malformed bytes to parsers; a hang is a
+# failure mode we explicitly assert against.
+timeout = 120
+markers = [
+    "needs_binary(name): requires an external binary (gs, tesseract, pandoc, pdftoppm). Skipped when absent locally, REQUIRED in CI.",
+    "golden: golden-file test against the generated fixture corpus.",
+    "property: hypothesis-based fuzz test.",
+    "slow: excluded from the default run via -m 'not slow'.",
+]
+
+[tool.coverage.run]
+source = ["docmax"]
+branch = true
+
+[tool.coverage.report]
+exclude_lines = [
+    "pragma: no cover",
+    "if TYPE_CHECKING:",
+    "raise NotImplementedError",
+    "@overload",
+]

docmaxv3-3.0.0a7/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+