Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 6 additions & 1 deletion docs/JSON_PROTOCOL.md
Original file line number Diff line number Diff line change
Expand Up @@ -69,7 +69,12 @@ wrapper JSON need not equal the underlying Middle JSON byte for byte.
DocVortex retains its AssetStore and explicit sidecar export behavior.

Structured Content keeps its own content projection, shares metadata/extensions,
and carries no Model/Middle schema identity. Content List V1/V2 remain MinerU outputs.
and carries no Model/Middle schema identity. By default, its per-page blocks retain
continued-table markers without merging content. Set `merge_continued_tables=True`
in `StructuredContentRenderOptions`, or pass it to `render_structured_content()`, to
merge marked table continuations through the shared table renderer. This option does
not merge continued text or lists, keeps empty source pages, and does not mutate the
input MiddleJson. Content List V1/V2 remain MinerU outputs.
Bundle manifests now use `docvortex.bundle` version `2.0`, with current document
JSON and the existing asset paths, sizes and hashes. Old bundles are rejected.

Expand Down
21 changes: 19 additions & 2 deletions src/docvortex/render/_internal/structured_content/renderer.py
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,7 @@
)
from ..markdown.assets import normalize_image_source, resolve_image_source
from ..markdown.escaping import escape_standalone_marker_rule, escape_text_block_markdown_prefix
from ..common.planner import PlannedBlock, _merge_continued_table_blocks
from ..markdown.inline import render_inline_content
from ....schema import (
BlockType,
Expand Down Expand Up @@ -61,30 +62,46 @@ def render_structured_content(
*,
asset_base_url: str = "",
latex_delimiters: LatexDelimitersConfig | None = None,
merge_continued_tables: bool = False,
) -> dict[str, Any]:
"""把严格 MiddleJson 无副作用地渲染为树形 Markdown structured_content。"""
if not isinstance(middle_json, MiddleJson):
raise TypeError("render_structured_content expects a MiddleJson instance")
if not isinstance(merge_continued_tables, bool):
raise TypeError("merge_continued_tables must be a bool")

delimiters = latex_delimiters or LatexDelimitersConfig()
document_fields = middle_json.model_dump(
mode="json",
exclude={"pages", "schema_id", "schema_version"},
exclude_defaults=True,
)
render_middle = middle_json
render_blocks_by_source_id: dict[int, PageBlock] = {}
removed_block_ids: set[int] = set()
if merge_continued_tables:
render_middle = middle_json.model_copy(deep=True)
planned_blocks = [
PlannedBlock(page_idx=page.page_idx, block=block) for page in render_middle.pages for block in page.blocks
]
planned_blocks_by_source_id = {id(planned.block): planned for planned in planned_blocks}
_merge_continued_table_blocks(planned_blocks)
render_blocks_by_source_id = {source_id: planned.block for source_id, planned in planned_blocks_by_source_id.items()}
removed_block_ids = {id(planned.block) for planned in planned_blocks if planned.removed}
pages = [
{
"page_idx": page.page_idx,
"blocks": [
_render_content_block(
block,
render_blocks_by_source_id.get(id(block), block),
delimiters=delimiters,
asset_base_url=asset_base_url,
)
for block in page.blocks
if id(block) not in removed_block_ids
],
}
for page in middle_json.pages
for page in render_middle.pages
]
return {"pages": pages, **document_fields}

Expand Down
1 change: 1 addition & 0 deletions src/docvortex/render/api.py
Original file line number Diff line number Diff line change
Expand Up @@ -193,6 +193,7 @@ def render(
middle_json,
latex_delimiters=resolved_options.latex_delimiters,
asset_base_url=resolved_options.asset_base_url,
merge_continued_tables=resolved_options.merge_continued_tables,
)

raise ValueError(f"Unsupported RenderFormat: {output_format}")
Expand Down
5 changes: 4 additions & 1 deletion src/docvortex/render/contracts.py
Original file line number Diff line number Diff line change
Expand Up @@ -184,10 +184,13 @@ class StructuredContentRenderOptions:
latex_delimiters: LatexDelimitersConfig | None = None

asset_base_url: str = ""
merge_continued_tables: bool = False

def __post_init__(self) -> None:
"""在构造时校验图片资源根地址。"""
"""在构造时校验图片资源根地址与续表合并开关。"""
_validate_asset_base_url(self.asset_base_url)
if not isinstance(self.merge_continued_tables, bool):
raise TypeError("merge_continued_tables must be a bool")


RenderOptions: TypeAlias = (
Expand Down
8 changes: 7 additions & 1 deletion src/docvortex/render/structured_content.py
Original file line number Diff line number Diff line change
Expand Up @@ -13,11 +13,17 @@ def render_structured_content(
*,
asset_base_url: str = "",
latex_delimiters: LatexDelimitersConfig | None = None,
merge_continued_tables: bool = False,
) -> dict[str, Any]:
"""惰性加载 Structured Content 实现并渲染严格 MiddleJson。"""
from ._internal.structured_content.renderer import render_structured_content as _render_structured_content

return _render_structured_content(middle_json, asset_base_url=asset_base_url, latex_delimiters=latex_delimiters)
return _render_structured_content(
middle_json,
asset_base_url=asset_base_url,
latex_delimiters=latex_delimiters,
merge_continued_tables=merge_continued_tables,
)


__all__ = ["render_structured_content"]
21 changes: 21 additions & 0 deletions tests/unittest/test_render_api.py
Original file line number Diff line number Diff line change
Expand Up @@ -173,6 +173,25 @@ def test_unified_render_rejects_legacy_format_and_mismatched_options() -> None:
render(middle, RenderFormat.PDF, options=DocxRenderOptions())


def test_structured_content_options_forward_table_merge(monkeypatch: pytest.MonkeyPatch) -> None:
"""验证统一入口传递续表合并开关。"""
received = {}

def render_stub(middle_json, **kwargs):
received.update(kwargs)
return {}

monkeypatch.setattr("docvortex.render.api.render_structured_content", render_stub)
result = render(
_middle(_page(0)),
RenderFormat.STRUCTURED_CONTENT,
options=StructuredContentRenderOptions(merge_continued_tables=True),
)

assert result == {}
assert received["merge_continued_tables"] is True


def test_public_options_validate_fields() -> None:
"""验证 Options 构造期的严格字段类型检查。"""
with pytest.raises(TypeError, match="RenderMode"):
Expand All @@ -191,6 +210,8 @@ def test_public_options_validate_fields() -> None:
options_type(mode=RenderMode.DEFAULT)
with pytest.raises(TypeError, match="asset_base_url"):
StructuredContentRenderOptions(asset_base_url=1)
with pytest.raises(TypeError, match="merge_continued_tables"):
StructuredContentRenderOptions(merge_continued_tables=1)
with pytest.raises(TypeError, match="standalone"):
HtmlRenderOptions(standalone=1)
with pytest.raises(TypeError, match="document_title"):
Expand Down
60 changes: 60 additions & 0 deletions tests/unittest/test_structured_content_render.py
Original file line number Diff line number Diff line change
Expand Up @@ -364,6 +364,66 @@ def test_structured_content_keeps_table_image_source_and_cross_page_metadata() -
assert image_only_output["image_source"] == "images/image-only-table.png"


def test_structured_content_option_merges_only_continued_tables() -> None:
"""验证可选续表合并不改变续段行为,也不污染输入文档。"""
bbox = [0.1, 0.1, 0.9, 0.9]
first = TableBlock.model_validate(
{
"type": "table",
"index": 0,
"bbox": bbox,
"content": [
{"type": "table_caption", "index": 0, "content": _inline("Table 1")},
{
"type": "table_body",
"index": 0,
"bbox": bbox,
"content": "<table><tr><th>A</th></tr><tr><td>1</td></tr></table>",
},
{"type": "table_footnote", "index": 2, "content": _inline("old note")},
],
}
)
second = TableBlock.model_validate(
{
"type": "table",
"index": 0,
"bbox": bbox,
"continues_prev": True,
"content": [
{"type": "table_caption", "index": 0, "content": _inline("Table 1 (continued)")},
{
"type": "table_body",
"index": 0,
"bbox": bbox,
"content": "<table><tr><th>A</th></tr><tr><td>2</td></tr></table>",
},
{"type": "table_footnote", "index": 2, "content": _inline("new note")},
],
}
)
middle = _middle(
_page(0, first, TextBlock(type="text", index=3, content=_inline("first-"))),
_page(
1,
second,
TextBlock(type="text", index=3, content=_inline("continued"), continues_prev=True),
),
)
original = deepcopy(middle)

result = render_structured_content(middle, merge_continued_tables=True)

assert [block["type"] for block in result["pages"][0]["blocks"]] == ["table", "text"]
assert result["pages"][0]["blocks"][0]["content"] == "| A |\n| --- |\n| 1 |\n| 2 |"
assert result["pages"][0]["blocks"][0]["captions"] == [{"content": "Table 1"}]
assert result["pages"][0]["blocks"][0]["footnotes"] == [{"content": "new note"}]
assert result["pages"][0]["blocks"][1]["content"] == "first-"
assert result["pages"][1]["blocks"] == [{"type": "text", "content": "continued", "continues_prev": True}]
_assert_output_field_contract(result)
assert middle == original


def test_structured_content_keeps_chart_content_separate_from_base64_source(
monkeypatch: pytest.MonkeyPatch,
) -> None:
Expand Down