DocmaxV3 3.0.0a7__py3-none-any.whl

docmax/__init__.py

@@ -0,0 +1,23 @@
+"""DocMax — terminal-native document toolkit.
+
+Importing this package must stay cheap. It pulls in no heavy dependency, no
+tool implementation, and no UI framework; ``tests/hygiene/test_no_heavy_imports.py``
+asserts as much by checking ``sys.modules`` after a bare import.
+
+That matters because non-negotiable #3 says the base install stays light: the
+TUI shell and cloud client are all a user gets until they first invoke a local
+engine that genuinely needs more.
+"""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+
+from docmax.core.branding import DIST_NAME
+
+try:
+    __version__ = version(DIST_NAME)
+except PackageNotFoundError:  # running from a source tree without an install
+    __version__ = "0.0.0.dev0"
+
+__all__ = ["__version__"]

docmax/cli/__init__.py

@@ -0,0 +1,8 @@
+"""Command-line interface.
+
+The only layer permitted to write to stdout, and the only layer permitted to
+terminate the process. Library code raises typed errors; this layer decides how
+to render them and what exit code to use.
+"""
+
+from __future__ import annotations

docmax/cli/main.py

@@ -0,0 +1,99 @@
+"""CLI entry point.
+
+This is the boundary where typed errors become exit codes. Library code raises;
+only this layer calls ``typer.Exit``. ``tests/hygiene/test_no_sys_exit.py``
+enforces the asymmetry by scanning ``core``, ``tools``, and ``cloud_client`` for
+any process-terminating call.
+"""
+
+from __future__ import annotations
+
+import shutil
+from typing import Annotated
+
+import typer
+
+from docmax import __version__
+from docmax.cli.render import console, out
+from docmax.core.branding import APP_NAME, CLI_NAME, HOMEPAGE
+
+app = typer.Typer(
+    name=CLI_NAME,
+    help=f"{APP_NAME} — terminal-native document toolkit. Local-first, no server required.",
+    epilog=f"Docs: {HOMEPAGE}",
+    add_completion=True,
+    rich_markup_mode="rich",
+    no_args_is_help=True,
+)
+
+#: External binaries a local engine may need, with the tools that depend on them.
+#: ``docmax setup`` (M3) installs these; ``doctor`` only reports.
+EXTERNAL_BINARIES: dict[str, tuple[str, ...]] = {
+    "tesseract": ("ocr",),
+    "gs": ("compress", "pdfa"),
+    "pdftoppm": ("ocr", "to-images"),
+    "pandoc": ("convert",),
+}
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        out.print(f"{APP_NAME} {__version__}")
+        raise typer.Exit
+
+
+@app.callback()
+def main(
+    _version: Annotated[
+        bool,
+        typer.Option(
+            "--version",
+            "-V",
+            callback=_version_callback,
+            is_eager=True,
+            help="Show version and exit.",
+        ),
+    ] = False,
+) -> None:
+    """Root callback. Global options live here."""
+
+
+@app.command()
+def doctor() -> None:
+    """Report the status of external tools the local engines depend on.
+
+    Reports only — never mutates. ``docmax setup`` (M3) does the installing, and
+    unlike v2's version it will be idempotent, support --dry-run, and verify
+    afterwards rather than assuming success.
+    """
+    from rich.table import Table
+
+    table = Table(title="External tool status", title_justify="left")
+    table.add_column("Tool")
+    table.add_column("Status")
+    table.add_column("Path")
+    table.add_column("Needed by")
+
+    missing: list[str] = []
+    for binary, used_by in EXTERNAL_BINARIES.items():
+        path = shutil.which(binary)
+        if path:
+            table.add_row(binary, "[green]found[/green]", path, ", ".join(used_by))
+        else:
+            missing.append(binary)
+            table.add_row(binary, "[yellow]missing[/yellow]", "—", ", ".join(used_by))
+
+    out.print(table)
+
+    if missing:
+        console.print(
+            f"\n[yellow]{len(missing)} tool(s) missing.[/yellow] "
+            "Affected operations can still run via the Cloud Engine, "
+            f"or install locally with [bold]{CLI_NAME} setup[/bold] (coming in M3)."
+        )
+    else:
+        console.print("\n[green]All external tools available.[/green]")
+
+
+if __name__ == "__main__":  # pragma: no cover
+    app()

docmax/cli/render.py

@@ -0,0 +1,58 @@
+"""Terminal rendering. The only module that owns a ``rich.Console``.
+
+v2 instantiated five separate ``Console`` objects across as many modules and
+wrote to all of them from worker threads while a ``Progress`` live region was
+active. The result was interleaved output and intermittent ``LiveError``
+crashes. There is one console here, and from M9 onward worker threads will push
+events onto a queue drained by a single render thread rather than printing
+directly.
+
+``core`` never imports this module, or ``rich`` at all — progress crosses that
+boundary as the ``ProgressSink`` protocol.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import TYPE_CHECKING
+
+from rich.console import Console
+from rich.panel import Panel
+from rich.text import Text
+
+if TYPE_CHECKING:
+    from docmax.core.errors import DocMaxError
+
+#: stderr, so that ``docmax get-info x.pdf --json | jq`` stays clean.
+console = Console(stderr=True)
+
+#: stdout, for actual command results.
+out = Console()
+
+
+def render_error(exc: DocMaxError, *, as_json: bool = False) -> None:
+    """Print a typed error as an actionable message — never a traceback.
+
+    Every anticipated failure carries a remedy naming the next step. If a user
+    sees a traceback, that is a bug in its own right: it means something escaped
+    the typed hierarchy.
+    """
+    if as_json:
+        out.print_json(json.dumps({"ok": False, "error": exc.to_dict()}))
+        return
+
+    body = Text()
+    body.append(exc.message)
+    if exc.remedy:
+        body.append("\n\n")
+        body.append("→ ", style="bold cyan")
+        body.append(exc.remedy)
+
+    console.print(
+        Panel(
+            body,
+            title=f"[bold red]{exc.code.value}[/bold red]",
+            border_style="red",
+            padding=(0, 1),
+        )
+    )

docmax/cloud_client/__init__.py

@@ -0,0 +1,35 @@
+"""Thin HTTP client for the Cloud Engine.
+
+Fully open source and fully optional. The endpoint is configurable, so this
+client talks to the hosted service by default and to a self-hosted deployment
+if you point it elsewhere.
+
+Cloud exists for one reason: to let someone use a tool without installing its
+heavy local dependencies. It is never a default and never silent — see the
+consent rules in ``core/router.py`` and the wire contract in ``docs/cloud-api.md``.
+
+The layout mirrors that contract:
+
+    config.py   which endpoint, which key, and the TLS rule
+    models.py   the wire types, parsed defensively
+    errors.py   error envelope -> typed exception, the inverse of server/errors.py
+    client.py   requests, retries, idempotency, polling
+"""
+
+from __future__ import annotations
+
+from docmax.cloud_client.client import CloudClient, idempotency_key, user_agent
+from docmax.cloud_client.config import CloudConfig
+from docmax.cloud_client.models import Capabilities, CloudJob, CloudOutput, JobStatus, UploadTicket
+
+__all__ = [
+    "Capabilities",
+    "CloudClient",
+    "CloudConfig",
+    "CloudJob",
+    "CloudOutput",
+    "JobStatus",
+    "UploadTicket",
+    "idempotency_key",
+    "user_agent",
+]

docmax/cloud_client/client.py

@@ -0,0 +1,343 @@
+"""The HTTP client for the Cloud Engine.
+
+Deliberately thin. It knows the wire contract in ``docs/cloud-api.md`` and
+nothing else: it does not decide whether cloud should be used (the router does,
+after checking consent), it does not know what a tool is beyond its name, and it
+does not write files — :meth:`CloudClient.fetch_output` hands back bytes for the
+caller to put through ``core/atomic.py``, because there is exactly one module in
+this project permitted to touch a destination path.
+
+Three behaviours are contract requirements rather than implementation choices:
+
+* **Idempotency.** The key is derived from the input digest and the parameters,
+  so a retry after a dropped connection returns the original result instead of
+  re-running the job and billing it twice.
+* **Server-controlled polling.** The client sleeps for ``poll_after_ms`` rather
+  than choosing an interval, so a busy endpoint can slow its callers down.
+* **Retries only when retrying can help.** ``retryable`` decides. Re-sending a
+  bad API key or an exhausted quota just wastes the user's time.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import secrets
+import sys
+import time
+from typing import TYPE_CHECKING, Any
+
+import httpx
+
+from docmax import __version__
+from docmax.cloud_client.config import CloudConfig
+from docmax.cloud_client.errors import raise_for_error
+from docmax.cloud_client.models import (
+    Capabilities,
+    CloudJob,
+    JobStatus,
+    UploadTicket,
+    as_mapping,
+)
+from docmax.core.branding import CLI_NAME
+from docmax.core.errors import (
+    CloudAuthError,
+    CloudEngineUnavailableError,
+    CloudProtocolError,
+    CloudTimeoutError,
+    DocMaxError,
+    InternalError,
+)
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
+    from docmax.core.models import DocumentRef
+
+IDEMPOTENCY_HEADER = "Idempotency-Key"
+
+#: How long to keep waiting for one job before giving up on it entirely.
+DEFAULT_JOB_TIMEOUT = 900.0
+
+_CHUNK = 1 << 20
+
+
+def user_agent() -> str:
+    """Identify the client, its Python, and its platform — nothing else."""
+    python = f"{sys.version_info.major}.{sys.version_info.minor}"
+    return f"{CLI_NAME}/{__version__} (python/{python}; {sys.platform})"
+
+
+class CloudClient:
+    """One configured endpoint, one connection pool.
+
+    Constructing this opens no socket and makes no request, so the router can
+    build one to ask a cheap question and throw it away.
+    """
+
+    def __init__(
+        self,
+        config: CloudConfig | None = None,
+        *,
+        http: httpx.Client | None = None,
+    ) -> None:
+        self.config = config or CloudConfig.from_env()
+        #: Injectable so the test suite can drive the whole client through a
+        #: mock transport, which is how the contract is verified without a
+        #: server existing.
+        self._http_client = http
+        self._capabilities: Capabilities | None = None
+
+    # -- lifecycle ---------------------------------------------------------
+
+    def _http(self) -> httpx.Client:
+        if self._http_client is None:
+            if not self.config.is_configured:
+                raise CloudAuthError("No API key is configured for the cloud endpoint.")
+            self._http_client = httpx.Client(
+                base_url=self.config.endpoint,
+                headers={
+                    "Authorization": f"Bearer {self.config.api_key}",
+                    "User-Agent": user_agent(),
+                    "Accept": "application/json",
+                },
+                timeout=httpx.Timeout(
+                    self.config.read_timeout,
+                    connect=self.config.connect_timeout,
+                ),
+            )
+        return self._http_client
+
+    def close(self) -> None:
+        if self._http_client is not None:
+            self._http_client.close()
+            self._http_client = None
+
+    def __enter__(self) -> CloudClient:
+        return self
+
+    def __exit__(self, *exc_info: object) -> None:
+        self.close()
+
+    # -- discovery ---------------------------------------------------------
+
+    def capabilities(self, *, refresh: bool = False) -> Capabilities:
+        """What this endpoint offers. Fetched once, then cached.
+
+        A self-hosted server implementing three of the five cloud tools is a
+        supported deployment, so "this endpoint cannot do that" is answered
+        before a document is uploaded rather than by a failed job.
+        """
+        if self._capabilities is None or refresh:
+            payload = self._request("GET", "/v1/capabilities")
+            self._capabilities = Capabilities.from_payload(payload)
+        return self._capabilities
+
+    # -- running a tool ----------------------------------------------------
+
+    def run(
+        self,
+        tool: str,
+        doc: DocumentRef,
+        params: Mapping[str, Any] | None = None,
+        *,
+        timeout: float = DEFAULT_JOB_TIMEOUT,
+    ) -> CloudJob:
+        """Submit ``doc`` and block until the job reaches a terminal state."""
+        return self.wait(self.submit(tool, doc, params), timeout=timeout)
+
+    def submit(
+        self,
+        tool: str,
+        doc: DocumentRef,
+        params: Mapping[str, Any] | None = None,
+    ) -> CloudJob:
+        """Send the work, taking whichever path the payload size calls for."""
+        resolved = dict(params or {})
+        if doc.size_bytes <= self._sync_limit():
+            return self._submit_sync(tool, doc, resolved)
+        return self._submit_large(tool, doc, resolved)
+
+    def poll(self, job_id: str) -> CloudJob:
+        """Ask after one job. Raises if the server reports it failed."""
+        body = self._request("GET", f"/v1/jobs/{job_id}")
+        if body.get("status") == JobStatus.FAILED.value:
+            raise_for_error(500, body)
+        return CloudJob.from_payload(body)
+
+    def wait(self, job: CloudJob, *, timeout: float = DEFAULT_JOB_TIMEOUT) -> CloudJob:
+        """Poll at the server's requested interval until the job settles."""
+        deadline = time.monotonic() + timeout
+        current = job
+        while not current.is_terminal:
+            if time.monotonic() >= deadline:
+                raise CloudTimeoutError(
+                    f"The job did not finish within {timeout:.0f}s.",
+                    remedy="Try again, or run locally with --engine local.",
+                    context={"job_id": current.job_id},
+                )
+            time.sleep(current.poll_after_ms / 1000)
+            current = self.poll(current.job_id)
+        return current
+
+    def fetch_output(self, job: CloudJob) -> bytes:
+        """Download a finished job's document.
+
+        Returns bytes rather than writing them. The caller hands these to
+        ``core/atomic.py``, which is the only module allowed to touch a
+        destination path — so a cloud result is delivered under exactly the same
+        crash-safety guarantee as a local one.
+        """
+        if job.output is None:
+            raise CloudProtocolError(
+                "The job reported success but carried no output.",
+                context={"job_id": job.job_id},
+            )
+        return self._storage("GET", job.output.url).content
+
+    # -- the two submission paths ------------------------------------------
+
+    def _submit_sync(self, tool: str, doc: DocumentRef, params: dict[str, Any]) -> CloudJob:
+        """Small payloads: one multipart request, answered when the work is done."""
+        body = self._request(
+            "POST",
+            f"/v1/tools/{tool}",
+            files={"file": (doc.path.name, doc.path.read_bytes(), "application/octet-stream")},
+            data={"params": json.dumps(params, sort_keys=True)},
+            headers={IDEMPOTENCY_HEADER: idempotency_key(doc, params)},
+        )
+        return CloudJob.from_payload(body)
+
+    def _submit_large(self, tool: str, doc: DocumentRef, params: dict[str, Any]) -> CloudJob:
+        """Large payloads: presigned upload, then a job to poll."""
+        ticket = UploadTicket.from_payload(
+            self._request(
+                "POST",
+                "/v1/uploads",
+                json={"filename": doc.path.name, "size_bytes": doc.size_bytes},
+            )
+        )
+        self._upload(ticket, doc)
+        body = self._request(
+            "POST",
+            f"/v1/tools/{tool}",
+            json={"file_id": ticket.file_id, "params": params},
+            headers={IDEMPOTENCY_HEADER: idempotency_key(doc, params)},
+        )
+        return CloudJob.from_payload(body)
+
+    def _upload(self, ticket: UploadTicket, doc: DocumentRef) -> None:
+        """PUT the bytes straight to storage, never through the API."""
+        self._storage("PUT", ticket.upload_url, content=doc.path.read_bytes())
+
+    def _storage(self, method: str, url: str, *, content: bytes | None = None) -> httpx.Response:
+        """Transfer bytes to or from the storage host, through a bare client.
+
+        Deliberately not the authenticated one: a presigned URL points at
+        storage, not at the API, and our bearer token has no business being
+        sent there.
+        """
+        with httpx.Client(timeout=self._timeout()) as storage:
+            try:
+                response = storage.request(method, url, content=content)
+            except httpx.TimeoutException as exc:
+                raise CloudTimeoutError(
+                    f"The transfer to storage timed out: {exc}",
+                    context={"url": url},
+                ) from exc
+            except httpx.TransportError as exc:
+                raise CloudEngineUnavailableError(
+                    f"The transfer to storage failed: {exc}",
+                    context={"url": url},
+                ) from exc
+
+        if response.status_code >= 400:
+            raise_for_error(response.status_code, None)
+        return response
+
+    def _sync_limit(self) -> int:
+        """The server's own threshold when we know it, ours otherwise.
+
+        Never fetches capabilities just to answer this: a size check must not
+        cost a round trip.
+        """
+        if self._capabilities is not None:
+            return self._capabilities.max_sync_bytes
+        return self.config.max_sync_bytes
+
+    # -- transport ---------------------------------------------------------
+
+    def _timeout(self) -> httpx.Timeout:
+        return httpx.Timeout(self.config.read_timeout, connect=self.config.connect_timeout)
+
+    def _request(self, method: str, url: str, **kwargs: Any) -> Mapping[str, Any]:
+        """One request, retried while retrying can plausibly help."""
+        attempts = self.config.max_retries + 1
+        for attempt in range(1, attempts + 1):
+            try:
+                return as_mapping(_decode(self._raw(method, url, **kwargs)))
+            except DocMaxError as exc:
+                if not exc.retryable or attempt == attempts:
+                    raise
+                time.sleep(_backoff(attempt))
+        raise InternalError("The retry loop finished without a result or an error.")
+
+    def _raw(self, method: str, url: str, **kwargs: Any) -> httpx.Response:
+        """Send one request and turn transport and status failures into typed errors."""
+        try:
+            response = self._http().request(method, url, **kwargs)
+        except httpx.TimeoutException as exc:
+            raise CloudTimeoutError(
+                f"The cloud endpoint did not respond within {self.config.read_timeout:.0f}s.",
+                context={"url": url},
+            ) from exc
+        except httpx.TransportError as exc:
+            raise CloudEngineUnavailableError(
+                f"Could not reach the cloud endpoint: {exc}",
+                remedy="Check your connection, or run locally with --engine local.",
+                context={"url": url},
+            ) from exc
+
+        if response.status_code >= 400:
+            raise_for_error(response.status_code, _decode(response, strict=False))
+        return response
+
+
+def idempotency_key(doc: DocumentRef, params: Mapping[str, Any]) -> str:
+    """Digest the input and the parameters, so a retry cannot run the job twice.
+
+    Same document plus same parameters means same key means the server returns
+    the original result. Anything that would change the output — a different
+    page range, a different language — changes the key.
+    """
+    digest = hashlib.sha256()
+    with doc.path.open("rb") as handle:
+        while chunk := handle.read(_CHUNK):
+            digest.update(chunk)
+    digest.update(json.dumps(params, sort_keys=True, separators=(",", ":")).encode())
+    return f"sha256:{digest.hexdigest()}"
+
+
+def _decode(response: httpx.Response, *, strict: bool = True) -> object:
+    """Decode a JSON body, or say so in the contract's own terms."""
+    try:
+        return response.json()
+    except ValueError as exc:
+        if not strict:
+            return None
+        raise CloudProtocolError(
+            "The cloud endpoint returned a body that is not JSON.",
+            remedy="Check that the configured endpoint speaks this API version.",
+            context={"content_type": response.headers.get("content-type", "")},
+        ) from exc
+
+
+def _backoff(attempt: int) -> float:
+    """Exponential, with jitter so concurrent clients do not resynchronise."""
+    base = min(2.0 ** (attempt - 1), 30.0)
+    # secrets, not random: not for secrecy, but because ruff's bandit rules
+    # (correctly) flag the stdlib PRNG and this is the cheaper answer.
+    return base + secrets.randbelow(1000) / 1000
+
+
+__all__ = ["DEFAULT_JOB_TIMEOUT", "CloudClient", "idempotency_key", "user_agent"]

docmax/cloud_client/config.py

@@ -0,0 +1,84 @@
+"""Where the Cloud Engine lives and how we authenticate to it.
+
+The endpoint is configuration, not a constant, because a self-hosted deployment
+is a first-class case: point this elsewhere and everything above it is
+identical. That is also why the TLS rule is enforced here rather than assumed —
+a user-supplied endpoint is the one place a document could be sent over
+plaintext by accident.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+from urllib.parse import urlsplit
+
+from docmax.core.branding import DEFAULT_CLOUD_ENDPOINT, ENV_PREFIX
+from docmax.core.errors import InvalidParameterError
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
+ENDPOINT_ENV = f"{ENV_PREFIX}CLOUD_ENDPOINT"
+API_KEY_ENV = f"{ENV_PREFIX}API_KEY"
+
+#: Plaintext is allowed only against these, so self-hosted development works
+#: without a certificate while a real endpoint still cannot be misconfigured
+#: into shipping documents in the clear.
+LOCAL_HOSTS = frozenset({"localhost", "127.0.0.1", "::1"})
+
+#: The contract's threshold between the synchronous path and presigned upload.
+#: Overridden by whatever ``GET /v1/capabilities`` reports, since the server is
+#: the authority on its own limits.
+DEFAULT_MAX_SYNC_BYTES = 10 * 1024 * 1024
+
+
+@dataclass(frozen=True, slots=True)
+class CloudConfig:
+    """Everything the client needs to talk to an endpoint."""
+
+    endpoint: str = DEFAULT_CLOUD_ENDPOINT
+    api_key: str | None = None
+    connect_timeout: float = 10.0
+    #: Generous, because OCR of a long document legitimately takes minutes.
+    #: A timeout is still mandatory: v2 had none anywhere and hung indefinitely.
+    read_timeout: float = 120.0
+    max_retries: int = 3
+    max_sync_bytes: int = DEFAULT_MAX_SYNC_BYTES
+
+    def __post_init__(self) -> None:
+        split = urlsplit(self.endpoint)
+        if split.scheme not in {"http", "https"} or not split.hostname:
+            raise InvalidParameterError(
+                f"The cloud endpoint is not a valid URL: {self.endpoint!r}",
+                remedy="Set a full URL, e.g. https://example.invalid",
+                context={"endpoint": self.endpoint},
+            )
+        if split.scheme == "http" and split.hostname not in LOCAL_HOSTS:
+            raise InvalidParameterError(
+                f"Refusing a plaintext endpoint: {self.endpoint!r}",
+                remedy="Use https://. Plaintext is permitted only for a local endpoint.",
+                context={"endpoint": self.endpoint},
+            )
+
+    @classmethod
+    def from_env(cls, env: Mapping[str, str] | None = None) -> CloudConfig:
+        """Read the endpoint and key from the environment.
+
+        The config file is the other source and takes lower precedence; that
+        merge belongs to ``core/config.py`` in M1, which will construct this.
+        """
+        source = os.environ if env is None else env
+        return cls(
+            endpoint=source.get(ENDPOINT_ENV, DEFAULT_CLOUD_ENDPOINT),
+            api_key=source.get(API_KEY_ENV) or None,
+        )
+
+    @property
+    def is_configured(self) -> bool:
+        """An API key is required from day one — anonymous access is not offered."""
+        return bool(self.api_key)
+
+
+__all__ = ["API_KEY_ENV", "ENDPOINT_ENV", "CloudConfig"]