Skip to content

Transforms complex documents like PDFs and Office docs into LLM-ready markdown/JSON for your Agentic workflows.

6.9 KB
Raw Blame
"""mineru read — read doclib content by locator."""

from __future__ import annotations

import shutil
from dataclasses import dataclass
from pathlib import Path
from typing import Literal

import typer

from ...doclib.client import DoclibClient
from ...doclib.types import ContentNextRequest, DocContentResponse, ImageFormat
from ...errors import MineruError
from ...utils.i18n import t
from ..contracts import CliContext, CliResult
from ..runtime import cli_ok, run_cli
from .parse import _append_next_marker, _ensure_output_parent, _output_info


@dataclass(frozen=True)
class ReadTextOutput:
    text: str


def read_cmd(
    locator: str = typer.Argument(
        ...,
        help=t("Document library locator; page selection supports numbers, rN, ranges, comma-separated pages and all"),
    ),
    after: str | None = typer.Option(None, "--after", help=t("Continue reading after a content cursor from earlier output")),
    context: int = typer.Option(0, "--context", help=t("Read N pages/blocks before and after the locator")),
    limit: int = typer.Option(30000, "--limit", help=t("Soft character limit for printed content")),
    format: Literal["markdown", "image"] = typer.Option("markdown", "-f", "--format", help=t("Output format: markdown, image")),
    output: str = typer.Option(
        None, "-o", "--output", help=t("Image output path; creates parent directories; Markdown only accepts '-'")
    ),
    no_marker: bool = typer.Option(False, "--no-marker", help=t("Omit continuation marker from output")),
    json_mode: bool = typer.Option(False, "--json", help=t("JSON output")),
) -> None:
    """按单点或页范围定位读取内容,并支持范围内续读。"""
    ctx = CliContext(json_mode=json_mode)
    run_cli(
        ctx,
        lambda: _read(
            locator,
            after=after,
            context=context,
            limit=limit,
            format=format,
            output=output,
            no_marker=no_marker,
            json_mode=json_mode,
        ),
    )


def _read(
    locator: str,
    *,
    context: int,
    limit: int,
    format: Literal["markdown", "image"],
    output: str | None,
    no_marker: bool,
    json_mode: bool,
    after: str | None = None,
) -> DocContentResponse | dict[str, object] | CliResult[ReadTextOutput] | CliResult[None]:
    """调用内容服务;只有显式续读时才传入 after,保持普通调用参数兼容。"""
    _validate_read_output(format, output)
    image_format = _image_format_for_output(format=format, output=output) if format == "image" else "jpeg"
    client = DoclibClient(timeout=60)
    if format == "image":
        content = client.read_content(
            locator,
            context=context,
            limit=limit,
            format=format,
            image_format=image_format,
            no_marker=no_marker,
            **({"after": after} if after is not None else {}),
        )
    else:
        content = client.read_content(
            locator,
            context=context,
            limit=limit,
            format=format,
            no_marker=no_marker,
            **({"after": after} if after is not None else {}),
        )
    return _prepare_read_output(content, json_mode=json_mode, output=output, no_marker=no_marker)


def _prepare_read_output(
    content: DocContentResponse,
    *,
    json_mode: bool,
    output: str | None,
    no_marker: bool,
) -> DocContentResponse | dict[str, object] | CliResult[ReadTextOutput] | CliResult[None]:
    """只将图片素材写入路径;文本保持渐进阅读和原有 JSON 响应。"""
    _validate_read_output(content.format, output)
    output_path = _ensure_output_parent(output) if content.format == "image" else None
    if json_mode and output_path and output_path != "-":
        payload: dict[str, object] = content.model_dump(mode="json")
        if content.asset is None:
            raise MineruError("asset_not_available", t("No image asset returned."), "format")
        shutil.copyfile(content.asset.path, output_path)
        payload["content"] = None
        payload["output"] = _output_info(output_path)
        return payload

    if json_mode:
        return content

    if content.format == "image":
        if content.asset is None:
            raise MineruError("asset_not_available", t("No image asset returned."), "format")
        asset_path = content.asset.path
        if output_path and output_path != "-":
            shutil.copyfile(asset_path, output_path)
            return cli_ok(ReadTextOutput(t("Written to {path}", path=output_path)), render=_render_read_text)
        return cli_ok(ReadTextOutput(asset_path), render=_render_read_text)

    if not content.content and content.content_ranges:
        message = t("No renderable content in requested pages.")
        if content.next_request and not no_marker:
            marker = _read_next_marker(content.next_request)
            if marker:
                return cli_ok(ReadTextOutput(_append_next_marker(message, marker)), render=_render_read_text)
        return cli_ok(None, notices=[message])

    if content.next_request and not no_marker:
        marker = _read_next_marker(content.next_request)
        if marker:
            return cli_ok(ReadTextOutput(_append_next_marker(content.content, marker)), render=_render_read_text)

    return cli_ok(ReadTextOutput(content.content), render=_render_read_text)


def _validate_read_output(format: str, output: str | None) -> None:
    """在连接服务或创建目录前拒绝文本落盘,保留 stdout 的显式等价写法。"""
    if format == "markdown" and output not in {None, "-"}:
        raise MineruError(
            "invalid_request",
            t("Markdown read does not write files. Use stdout redirection or the SDK to save text."),
            "output",
        )


def _render_read_text(data: ReadTextOutput) -> str:
    return data.text


def _image_format_for_output(*, format: Literal["markdown", "image"], output: str | None) -> ImageFormat:
    if format != "image" or output is None:
        return "jpeg"
    if output == "-":
        raise MineruError(
            "image_output_extension_unsupported",
            t("Image output requires a file path ending with .png, .jpg, .jpeg, or .webp; stdout is not supported."),
            "output",
        )
    suffix = Path(output).suffix.lower()
    if suffix == ".png":
        return "png"
    if suffix in {".jpg", ".jpeg"}:
        return "jpeg"
    if suffix == ".webp":
        return "webp"
    raise MineruError(
        "image_output_extension_unsupported",
        t("Image output path must end with .png, .jpg, .jpeg, or .webp."),
        "output",
    )


def _read_next_marker(next_request: ContentNextRequest) -> str | None:
    """把范围定位和绝对游标一起写入可直接执行的续读命令。"""
    if not next_request.locator:
        return None
    after_option = f" --after {next_request.after}" if next_request.after else ""
    return f"<!-- Next: mineru read {next_request.locator}{after_option} -->"