docvortex 0.2.1__py3-none-any.whl

docvortex/document/pdf/visual_geometry.py

@@ -0,0 +1,201 @@
+"""PDF 页面坐标、方向和裁图使用的无状态几何原语。"""
+
+from __future__ import annotations
+
+import base64
+from typing import Any
+
+import cv2
+import numpy as np
+from loguru import logger
+
+from ...schema import BBox
+from ...foundation.geometry import normalize_to_int_bbox
+
+
+def _normalize_page_size(page_image: Any) -> tuple[int, int]:
+    """从PIL或numpy图像中读取页面宽高，供归一化bbox还原为像素bbox。"""
+    if hasattr(page_image, "size"):
+        return page_image.size
+
+    height, width = page_image.shape[:2]
+    return width, height
+
+
+def _bbox_to_pixel_bbox(bbox: BBox | None, page_size: tuple[int, int]) -> BBox | None:
+    """将归一化或像素bbox统一成像素bbox，异常bbox返回None。"""
+    if bbox is None or len(bbox) != 4:
+        return None
+
+    try:
+        x0, y0, x1, y1 = [float(v) for v in bbox]
+    except (TypeError, ValueError):
+        return None
+
+    width, height = page_size
+    if all(0.0 <= value <= 1.0 for value in [x0, y0, x1, y1]):
+        x0, y0, x1, y1 = x0 * width, y0 * height, x1 * width, y1 * height
+
+    left, right = sorted([x0, x1])
+    top, bottom = sorted([y0, y1])
+    if right <= left or bottom <= top:
+        return None
+    return (left, top, right, bottom)
+
+
+def _normalize_layout_bbox_to_unit(bbox: BBox | None, page_size: tuple[int, int]) -> list[float] | None:
+    """将 layout 像素 bbox 归一化为 VLM ContentBlock 需要的 0-1 坐标。"""
+    pixel_bbox = _bbox_to_pixel_bbox(bbox, page_size)
+    if pixel_bbox is None:
+        return None
+
+    page_width, page_height = page_size
+    if page_width <= 0 or page_height <= 0:
+        return None
+
+    x0, y0, x1, y1 = pixel_bbox
+    unit_bbox = [
+        round(max(0.0, min(1.0, float(x0) / page_width)), 3),
+        round(max(0.0, min(1.0, float(y0) / page_height)), 3),
+        round(max(0.0, min(1.0, float(x1) / page_width)), 3),
+        round(max(0.0, min(1.0, float(y1) / page_height)), 3),
+    ]
+    if unit_bbox[2] <= unit_bbox[0] or unit_bbox[3] <= unit_bbox[1]:
+        return None
+    return unit_bbox
+
+
+def _medium_bbox_to_quad(bbox: list[float] | tuple[float, ...]) -> np.ndarray:
+    """将普通 bbox 转为表格模型 OCR token 使用的四点框。"""
+    x0, y0, x1, y1 = [float(v) for v in bbox]
+    return np.asarray([[x0, y0], [x1, y0], [x1, y1], [x0, y1]], dtype=np.float32)
+
+
+def _normalize_medium_content(value: Any) -> str:
+    """将 medium 本地模型输出的文本字段规范成 Hybrid block 可消费的字符串。"""
+    if isinstance(value, list):
+        return "\n".join(str(item) for item in value if str(item).strip())
+    if isinstance(value, str):
+        return value.strip()
+    return ""
+
+
+def _table_bbox_center(bbox: BBox) -> tuple[float, float]:
+    """计算 bbox 中心点，用于判断图片或公式应归属哪个表格。"""
+    return (float(bbox[0]) + float(bbox[2])) / 2.0, (float(bbox[1]) + float(bbox[3])) / 2.0
+
+
+def _normalize_visual_block_angle(angle: Any) -> int:
+    """规范视觉块角度为 0/90/180/270，无法识别的角度按 0 处理。"""
+    try:
+        normalized_angle = int(float(angle or 0)) % 360
+    except (TypeError, ValueError):
+        logger.warning(f"Unsupported visual block angle: {angle}, using 0")
+        return 0
+    if normalized_angle not in {0, 90, 180, 270}:
+        logger.warning(f"Unsupported visual block angle: {angle}, using 0")
+        return 0
+    return normalized_angle
+
+
+def _rotate_visual_block_image_to_upright(image: np.ndarray, angle: int) -> np.ndarray:
+    """按 layout 视觉块角度把裁图旋转至正向，角度语义与方向分类模型保持一致。"""
+    if angle == 270:
+        return cv2.rotate(image, cv2.ROTATE_90_CLOCKWISE)
+    if angle == 90:
+        return cv2.rotate(image, cv2.ROTATE_90_COUNTERCLOCKWISE)
+    if angle == 180:
+        return cv2.rotate(image, cv2.ROTATE_180)
+    return image
+
+
+def _rotate_medium_table_bbox(
+    bbox: BBox,
+    image_width: float,
+    image_height: float,
+    angle: int,
+) -> BBox:
+    """把原表格裁图中的 bbox 同步转换到旋转后裁图坐标系。"""
+    x0, y0, x1, y1 = [float(value) for value in bbox]
+    if angle == 270:
+        # 顺时针旋转 90 度后，新 x 轴来自原 y 轴的反方向。
+        return (image_height - y1, x0, image_height - y0, x1)
+    if angle == 90:
+        # 逆时针旋转 90 度后，新 y 轴来自原 x 轴的反方向。
+        return (y0, image_width - x1, y1, image_width - x0)
+    if angle == 180:
+        return (image_width - x1, image_height - y1, image_width - x0, image_height - y0)
+    return (x0, y0, x1, y1)
+
+
+def _get_medium_table_virtual_image_bbox(
+    bbox: BBox,
+    image_size: tuple[int, int],
+    box_size: float = 10.0,
+) -> BBox:
+    """在图片中心生成小 OCR token 框，避免图片大框干扰单元格匹配。"""
+    image_width, image_height = image_size
+    center_x, center_y = _table_bbox_center(bbox)
+    half_size = box_size / 2.0
+    return (
+        max(0.0, center_x - half_size),
+        max(0.0, center_y - half_size),
+        min(float(image_width), center_x + half_size),
+        min(float(image_height), center_y + half_size),
+    )
+
+
+def _encode_page_crop_as_jpeg_data_uri(
+    np_image: np.ndarray,
+    page_bbox: BBox,
+    angle: int,
+) -> str:
+    """从页面原图按像素框裁剪，按视觉块方向回正后编码为 JPEG data URI。"""
+    image_h, image_w = np_image.shape[:2]
+    image_bbox = normalize_to_int_bbox(page_bbox, image_size=(image_h, image_w))
+    if image_bbox is None:
+        return ""
+    x0, y0, x1, y1 = image_bbox
+    crop_rgb = np_image[y0:y1, x0:x1].copy()
+    if crop_rgb.size == 0:
+        return ""
+
+    crop_rgb = _rotate_visual_block_image_to_upright(crop_rgb, angle)
+    crop_bgr = cv2.cvtColor(crop_rgb, cv2.COLOR_RGB2BGR)
+    success, encoded = cv2.imencode(".jpg", crop_bgr)
+    if not success:
+        return ""
+    return f"data:image/jpeg;base64,{base64.b64encode(encoded.tobytes()).decode('ascii')}"
+
+
+def _sidecar_bbox_to_page_bbox(
+    bbox: BBox | None,
+    page_size: tuple[float, float],
+    render_scale: float,
+) -> BBox | None:
+    """将公式或 OCR sidecar bbox 转为 PDF point 坐标，供原生字符匹配和组行。"""
+    if bbox is None or len(bbox) != 4 or render_scale <= 0:
+        return None
+    try:
+        x0, y0, x1, y1 = [float(value) for value in bbox]
+    except (TypeError, ValueError):
+        return None
+
+    page_width, page_height = page_size
+    if page_width <= 0 or page_height <= 0:
+        return None
+    if all(0.0 <= value <= 1.0 for value in [x0, y0, x1, y1]):
+        x0, y0, x1, y1 = x0 * page_width, y0 * page_height, x1 * page_width, y1 * page_height
+    else:
+        x0, y0, x1, y1 = (
+            x0 / render_scale,
+            y0 / render_scale,
+            x1 / render_scale,
+            y1 / render_scale,
+        )
+
+    left, right = sorted([max(0.0, min(page_width, x0)), max(0.0, min(page_width, x1))])
+    top, bottom = sorted([max(0.0, min(page_height, y0)), max(0.0, min(page_height, y1))])
+    if right <= left or bottom <= top:
+        return None
+    return (left, top, right, bottom)

docvortex/document/pdf/visuals.py

@@ -0,0 +1,343 @@
+"""视觉块容器补全、方向归一化与页面裁图。"""
+
+from __future__ import annotations
+
+import math
+from typing import TYPE_CHECKING, Any
+
+import numpy as np
+from loguru import logger
+
+from ...schema import BBox, BlockType
+from ...foundation.geometry import calculate_overlap_area_2_minbox_area_ratio, calculate_overlap_area_in_bbox1_area_ratio
+
+from .constants import (
+    IMAGE_BLOCK_CONTAINMENT_THRESHOLD,
+    IMAGE_BLOCK_LAYOUT_COVERAGE_THRESHOLD,
+    IMAGE_BLOCK_LAYOUT_MIN_VISUAL_COUNT,
+    LOCAL_LAYOUT_IMAGE_BLOCK_AREA_TYPES,
+    LOCAL_LAYOUT_IMAGE_BLOCK_BODY_TYPES,
+    MODEL_JSON_VISUAL_BLOCK_TYPES,
+)
+from .visual_geometry import (
+    _bbox_to_pixel_bbox,
+    _encode_page_crop_as_jpeg_data_uri,
+    _normalize_page_size,
+    _normalize_visual_block_angle,
+)
+
+if TYPE_CHECKING:
+    from .document import PDFDocument
+
+
+def _normalize_model_bbox_for_containment(raw_bbox: Any) -> BBox | None:
+    """校验模型 block 的四点框，返回可用于面积包含判断的浮点坐标。"""
+    try:
+        if raw_bbox is None or len(raw_bbox) != 4:
+            return None
+        bbox = tuple(float(value) for value in raw_bbox)
+    except (TypeError, ValueError):
+        return None
+
+    if not all(math.isfinite(value) for value in bbox):
+        return None
+    if bbox[2] <= bbox[0] or bbox[3] <= bbox[1]:
+        return None
+    return bbox
+
+
+def _collapse_image_blocks(
+    page_model_list: list[dict[str, Any]],
+    containment_threshold: float = IMAGE_BLOCK_CONTAINMENT_THRESHOLD,
+) -> None:
+    """将 image_block 折叠为单个图片，并删除面积上被其包裹的非容器子块。"""
+    image_blocks = [block for block in page_model_list if block.get("type") == "image_block"]
+    if not image_blocks:
+        return
+
+    image_block_ids = {id(block) for block in image_blocks}
+    image_block_bboxes = [
+        bbox for block in image_blocks if (bbox := _normalize_model_bbox_for_containment(block.get("bbox"))) is not None
+    ]
+
+    retained_blocks: list[dict[str, Any]] = []
+    for block in page_model_list:
+        if id(block) in image_block_ids:
+            block["type"] = BlockType.IMAGE
+            retained_blocks.append(block)
+            continue
+
+        block_bbox = _normalize_model_bbox_for_containment(block.get("bbox"))
+        is_contained = block_bbox is not None and any(
+            calculate_overlap_area_in_bbox1_area_ratio(block_bbox, image_block_bbox) >= containment_threshold
+            for image_block_bbox in image_block_bboxes
+        )
+        if not is_contained:
+            retained_blocks.append(block)
+
+    page_model_list[:] = retained_blocks
+
+
+def _supplement_missing_image_block_containers(
+    model_list: list[list[dict[str, Any]]],
+    layout_blocks_list: list[list[dict[str, Any]]],
+    containment_threshold: float = IMAGE_BLOCK_CONTAINMENT_THRESHOLD,
+    coverage_threshold: float = IMAGE_BLOCK_LAYOUT_COVERAGE_THRESHOLD,
+    min_visual_count: int = IMAGE_BLOCK_LAYOUT_MIN_VISUAL_COUNT,
+) -> None:
+    """用本地 layout 整图框为 xhigh 结果补充缺失的 image_block 容器。"""
+    if len(model_list) != len(layout_blocks_list):
+        raise ValueError(
+            "Hybrid image-block fallback page count mismatch: "
+            f"model_list={len(model_list)}, layout_blocks={len(layout_blocks_list)}"
+        )
+
+    for page_model_list, page_layout_blocks in zip(model_list, layout_blocks_list):
+        existing_image_block_bboxes = [
+            bbox
+            for block in page_model_list
+            if block.get("type") == "image_block"
+            if (bbox := _normalize_model_bbox_for_containment(block.get("bbox"))) is not None
+        ]
+
+        existing_claimed_block_ids: set[int] = set()
+        if existing_image_block_bboxes:
+            for block in page_model_list:
+                if block.get("type") == "image_block":
+                    continue
+                block_bbox = _normalize_model_bbox_for_containment(block.get("bbox"))
+                if block_bbox is not None and any(
+                    calculate_overlap_area_in_bbox1_area_ratio(block_bbox, image_block_bbox) >= containment_threshold
+                    for image_block_bbox in existing_image_block_bboxes
+                ):
+                    existing_claimed_block_ids.add(id(block))
+
+        candidates: list[tuple[int, float, int, int, dict[str, Any], set[int]]] = []
+        for layout_order, layout_block in enumerate(page_layout_blocks):
+            if layout_block.get("type") != BlockType.IMAGE or layout_block.get("sub_type") == "seal":
+                continue
+
+            layout_bbox = _normalize_model_bbox_for_containment(layout_block.get("bbox"))
+            if layout_bbox is None:
+                continue
+            if any(
+                calculate_overlap_area_2_minbox_area_ratio(layout_bbox, image_block_bbox) >= containment_threshold
+                for image_block_bbox in existing_image_block_bboxes
+            ):
+                continue
+
+            contained_blocks: list[tuple[int, dict[str, Any], BBox]] = []
+            for block_index, block in enumerate(page_model_list):
+                if block.get("type") == "image_block" or id(block) in existing_claimed_block_ids:
+                    continue
+                block_bbox = _normalize_model_bbox_for_containment(block.get("bbox"))
+                if block_bbox is None:
+                    continue
+                if calculate_overlap_area_in_bbox1_area_ratio(block_bbox, layout_bbox) >= containment_threshold:
+                    contained_blocks.append((block_index, block, block_bbox))
+
+            contained_visuals = [
+                (block_index, block)
+                for block_index, block, _ in contained_blocks
+                if block.get("type") in LOCAL_LAYOUT_IMAGE_BLOCK_BODY_TYPES
+            ]
+            if len(contained_visuals) < min_visual_count:
+                continue
+
+            layout_area = (layout_bbox[2] - layout_bbox[0]) * (layout_bbox[3] - layout_bbox[1])
+            contained_area = sum(
+                (block_bbox[2] - block_bbox[0]) * (block_bbox[3] - block_bbox[1])
+                for _, block, block_bbox in contained_blocks
+                if block.get("type") in LOCAL_LAYOUT_IMAGE_BLOCK_AREA_TYPES
+            )
+            coverage_ratio = contained_area / layout_area
+            if coverage_ratio < coverage_threshold and not math.isclose(
+                coverage_ratio,
+                coverage_threshold,
+                rel_tol=0.0,
+                abs_tol=1e-12,
+            ):
+                continue
+
+            contained_block_ids = {id(block) for _, block, _ in contained_blocks}
+            first_block_index = min(block_index for block_index, _, _ in contained_blocks)
+            candidates.append(
+                (
+                    -len(contained_visuals),
+                    layout_area,
+                    layout_order,
+                    first_block_index,
+                    layout_block,
+                    contained_block_ids,
+                )
+            )
+
+        claimed_block_ids: set[int] = set()
+        selected_containers: list[tuple[int, dict[str, Any]]] = []
+        for _, _, _, first_block_index, layout_block, block_ids in sorted(candidates):
+            if claimed_block_ids.intersection(block_ids):
+                continue
+            claimed_block_ids.update(block_ids)
+            selected_containers.append(
+                (
+                    first_block_index,
+                    {
+                        "type": "image_block",
+                        "bbox": list(layout_block["bbox"]),
+                        "angle": layout_block.get("angle", 0),
+                        "content": None,
+                    },
+                )
+            )
+
+        for insert_index, image_block in sorted(selected_containers, reverse=True):
+            page_model_list.insert(insert_index, image_block)
+
+
+def _attach_visual_block_images(
+    model_list: list[list[dict[str, Any]]],
+    images_list: list[dict[str, Any]],
+    page_start_index: int = 0,
+) -> None:
+    """在窗口页图释放前，为最终 model_list 视觉块写入回正后的页面裁图。"""
+    if len(model_list) != len(images_list):
+        raise ValueError(f"Hybrid visual crop page count mismatch: model_list={len(model_list)}, images={len(images_list)}")
+
+    for page_offset, (page_model_list, image_dict) in enumerate(zip(model_list, images_list)):
+        _attach_prepared_visual_block_images(
+            [_prepare_page_visual_blocks(page_model_list)], [image_dict], page_start_index + page_offset
+        )
+
+
+def _prepare_page_visual_blocks(page_model_list: list[dict[str, Any]]) -> list[tuple[int, dict[str, Any]]]:
+    """先折叠视觉容器，再记录原始块索引，供按需页图任务复用。"""
+    _collapse_image_blocks(page_model_list)
+    return [(index, block) for index, block in enumerate(page_model_list) if block.get("type") in MODEL_JSON_VISUAL_BLOCK_TYPES]
+
+
+def _visual_page_ranges(
+    prepared_pages: list[list[tuple[int, dict[str, Any]]]],
+    image_bytes_by_page: dict[int, int] | None = None,
+    *,
+    window_size: int = 64,
+) -> list[tuple[int, int]]:
+    """在指定窗口和 32MiB 像素预算内合并需裁图页，不改变单页清晰度。"""
+    ranges: list[tuple[int, int]] = []
+    batch_bytes = 0
+    for page_index, blocks in enumerate(prepared_pages):
+        if not blocks:
+            continue
+        page_bytes = (image_bytes_by_page or {}).get(page_index, 0)
+        if (
+            ranges
+            and page_index == ranges[-1][1] + 1
+            and page_index // window_size == ranges[-1][0] // window_size
+            and batch_bytes + page_bytes <= 32 * 1024 * 1024
+        ):
+            ranges[-1] = (ranges[-1][0], page_index)
+            batch_bytes += page_bytes
+        else:
+            ranges.append((page_index, page_index))
+            batch_bytes = page_bytes
+    return ranges
+
+
+def attach_visual_block_images_from_pdf(
+    document: PDFDocument,
+    model_list: list[list[dict[str, Any]]],
+    *,
+    window_size: int = 64,
+    timeout: int | None = None,
+    threads: int | None = None,
+) -> None:
+    """按当前 PDF 全部物理页的视觉块需求原地补图；页图由本函数释放，文档仍归调用方。"""
+    from .images import load_images_from_pdf_bytes_range
+    from .raster import estimate_page_image_bytes
+
+    if isinstance(window_size, bool) or not isinstance(window_size, int) or window_size <= 0:
+        raise ValueError("window_size must be a positive integer")
+    if len(model_list) != document.page_count:
+        raise ValueError(f"PDF visual crop page count mismatch: model_list={len(model_list)}, document={document.page_count}")
+
+    prepared_visuals = [_prepare_page_visual_blocks(page) for page in model_list]
+    image_bytes = {
+        index: estimate_page_image_bytes(document.page_size(index)) for index, blocks in enumerate(prepared_visuals) if blocks
+    }
+    for start, end in _visual_page_ranges(prepared_visuals, image_bytes, window_size=window_size):
+        images = load_images_from_pdf_bytes_range(
+            document.bytes,
+            start_page_id=start,
+            end_page_id=end,
+            image_type="pil_img",
+            timeout=timeout,
+            threads=threads,
+        )
+        try:
+            _attach_prepared_visual_block_images(prepared_visuals[start : end + 1], images, page_start_index=start)
+        finally:
+            for item in images:
+                if item.get("img_pil") is not None:
+                    item["img_pil"].close()
+
+
+def _attach_prepared_visual_block_images(
+    prepared_pages: list[list[tuple[int, dict[str, Any]]]],
+    images_list: list[dict[str, Any]],
+    page_start_index: int = 0,
+) -> None:
+    """按所选 PDF 的物理页索引裁图，输入块已经整理且无需再次折叠。"""
+    if len(prepared_pages) != len(images_list):
+        raise ValueError(f"Hybrid visual crop page count mismatch: model_list={len(prepared_pages)}, images={len(images_list)}")
+    for page_offset, (visual_blocks, image_dict) in enumerate(zip(prepared_pages, images_list)):
+        if not visual_blocks:
+            continue
+
+        page_index = page_start_index + page_offset
+        page_pil_image = image_dict.get("img_pil")
+        if page_pil_image is None:
+            logger.warning(f"Skipping model visual block crops without page image: page={page_index}")
+            continue
+
+        converted_page_image = None
+        try:
+            if getattr(page_pil_image, "mode", None) == "RGB":
+                page_rgb_image = page_pil_image
+            else:
+                converted_page_image = page_pil_image.convert("RGB")
+                page_rgb_image = converted_page_image
+
+            page_size = _normalize_page_size(page_rgb_image)
+            np_image = np.asarray(page_rgb_image)
+            for block_idx, block in visual_blocks:
+                try:
+                    pixel_bbox = _bbox_to_pixel_bbox(block.get("bbox"), page_size)
+                    if pixel_bbox is None:
+                        raise ValueError("invalid bbox")
+                    angle = _normalize_visual_block_angle(block.get("angle", 0))
+                    image_base64 = _encode_page_crop_as_jpeg_data_uri(
+                        np_image,
+                        pixel_bbox,
+                        angle,
+                    )
+                    if not image_base64:
+                        raise ValueError("empty crop or JPEG encoding failure")
+                    block["image_base64"] = image_base64
+                except Exception as exc:
+                    logger.warning(
+                        "Skipping invalid model visual block crop: "
+                        f"page={page_index}, block={block_idx}, type={block.get('type')}, "
+                        f"bbox={block.get('bbox')}, error={exc}"
+                    )
+        finally:
+            if converted_page_image is not None:
+                converted_page_image.close()
+
+
+attach_visual_block_images = _attach_visual_block_images
+supplement_missing_image_block_containers = _supplement_missing_image_block_containers
+
+__all__ = [
+    "attach_visual_block_images",
+    "attach_visual_block_images_from_pdf",
+    "supplement_missing_image_block_containers",
+]

docvortex/document/source.py

@@ -0,0 +1,92 @@
+"""文件输入准备与有效页范围，不包含档位或 OCR 路由。"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TYPE_CHECKING, cast
+
+from docvortex.document.contracts import HtmlSourceContext
+from ..errors import InvalidRequestError
+from ..schema import FILE_SUFFIXES, FileSuffix
+
+if TYPE_CHECKING:
+    from .pdf.document import PDFDocument
+
+
+@dataclass(slots=True)
+class PreparedSource:
+    """保存输入字节、有效页面映射及底层文档的资源所有权。"""
+
+    data: bytes
+    file_suffix: FileSuffix
+    source_context: HtmlSourceContext | None = None
+    page_index_map: list[int] | None = None
+    broken_page_indices: tuple[int, ...] = ()
+    document: PDFDocument | None = None
+    owns_document: bool = False
+
+
+def prepare_source(
+    source: str | Path | bytes | PDFDocument,
+    *,
+    file_suffix: FileSuffix | None = None,
+    page_range: str = "",
+    source_context: HtmlSourceContext | None = None,
+) -> PreparedSource:
+    """准备原生解析输入，调用者持有的 PDFDocument 不由引擎关闭。"""
+    from .page_range import normalize_page_range_input, parse_page_range
+
+    document = None
+    path = Path(source) if isinstance(source, (str, Path)) else None
+    if path is not None:
+        data = path.read_bytes()
+    elif isinstance(source, bytes):
+        data = source
+    else:
+        from .pdf.document import PDFDocument
+
+        if not isinstance(source, PDFDocument):
+            raise TypeError("source must be a path, bytes, or PDFDocument")
+        document, data, file_suffix = source, source.bytes, "pdf"
+    if file_suffix:
+        suffix = file_suffix
+    else:
+        from .detection import guess_suffix_by_bytes
+
+        suffix = guess_suffix_by_bytes(data, str(path) if path else None)
+    if suffix not in FILE_SUFFIXES:
+        raise InvalidRequestError("file_type_unsupported", f"Unsupported native input format: {suffix}", "file_suffix")
+    page_range = normalize_page_range_input(page_range)
+    if suffix != "pdf" and page_range:
+        raise InvalidRequestError("page_range_invalid", "Page ranges are supported only for PDF input", "page_range")
+    if suffix == "html" and source_context is None and path is not None:
+        absolute = path.resolve()
+        source_context = HtmlSourceContext(source_uri=absolute.as_uri(), local_resource_root=absolute.parent)
+    prepared = PreparedSource(data, cast(FileSuffix, suffix), source_context=source_context, document=document)
+    if suffix == "pdf":
+        from .pdf.document import PDFDocument
+        from .pdf.pdfium import safe_rewrite_pdf_bytes_with_pdfium_result
+
+        if document is None:
+            document = PDFDocument(data)
+            prepared.document, prepared.owns_document = document, True
+        try:
+            indices = parse_page_range(page_range, document.page_count)
+            if indices != list(range(document.page_count)):
+                rewrite = safe_rewrite_pdf_bytes_with_pdfium_result(data, page_indices=indices)
+                prepared.data = rewrite.pdf_bytes or data
+                prepared.page_index_map = None if rewrite.used_original else rewrite.retained_page_indices
+                prepared.broken_page_indices = tuple(rewrite.broken_page_indices)
+                if prepared.owns_document:
+                    document.close()
+                prepared.document = PDFDocument(prepared.data)
+                prepared.owns_document = True
+        except Exception:
+            if prepared.owns_document and prepared.document is not None:
+                prepared.document.close()
+            raise
+    return prepared
+
+
+__all__ = ["PreparedSource", "prepare_source", "HtmlSourceContext"]

docvortex/errors.py

@@ -0,0 +1,21 @@
+"""独立文档引擎的可定位错误，不依赖宿主 HTTP 或任务状态。"""
+
+from __future__ import annotations
+
+
+class DocumentError(ValueError):
+    """携带稳定错误码的文档输入或处理错误。"""
+
+    def __init__(self, code: str, message: str, param: str | None = None) -> None:
+        """保存供命令行及上层应用映射的错误信息。"""
+        super().__init__(message)
+        self.code = code
+        self.message = message
+        self.param = param
+
+
+class InvalidRequestError(DocumentError):
+    """表示页范围或格式选项不符合文档输入契约。"""
+
+
+__all__ = ["DocumentError", "InvalidRequestError"]

docvortex/export/__init__.py

@@ -0,0 +1,3 @@
+"""DocVortex 模块边界。"""
+
+__all__ = []