mmar-chunker 1.0.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 AIRI
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,75 @@
1
+ Metadata-Version: 2.4
2
+ Name: mmar-chunker
3
+ Version: 1.0.0
4
+ Summary: Склейка блоков OCR в чанки: DP под целевой размер
5
+ Keywords:
6
+ Author: malovichko, kartashev, kopanichuk, tagin, bakulin
7
+ Author-email: malovichko <malovichko@airi.net>, kartashev <kartashev@airi.net>, kopanichuk <kopanichuk@airi.net>, tagin <tagin@airi.net>, bakulin <bakulin@airi.net>
8
+ License-Expression: MIT
9
+ License-File: LICENSE
10
+ Classifier: Development Status :: 4 - Beta
11
+ Classifier: Intended Audience :: Developers
12
+ Classifier: Programming Language :: Python
13
+ Classifier: Programming Language :: Python :: 3
14
+ Classifier: Programming Language :: Python :: 3 :: Only
15
+ Classifier: Programming Language :: Python :: 3.12
16
+ Classifier: Programming Language :: Python :: 3.13
17
+ Classifier: Programming Language :: Python :: 3.14
18
+ Classifier: Topic :: Documentation
19
+ Classifier: Topic :: Software Development
20
+ Classifier: Topic :: Utilities
21
+ Classifier: Typing :: Typed
22
+ Requires-Dist: loguru~=0.7.3
23
+ Requires-Dist: numpy~=2.0
24
+ Requires-Dist: pydantic~=2.12
25
+ Requires-Python: >=3.12
26
+ Description-Content-Type: text/markdown
27
+
28
+
29
+ # MMAR Chunker
30
+
31
+ Склеивает блоки OCR из `proc_json` в чанки произвольной длины (`--target-size`, по умолчанию 1000 символов).
32
+
33
+ Таблица никогда не режется: она целиком лежит в одном чанке, даже если длиннее коридора.
34
+
35
+ ## Запуск
36
+
37
+ ```bash
38
+ make deps
39
+ make run DATA=~/dvc_data/proc_json OUT=chunks_json
40
+ ```
41
+
42
+ Python 3.12. Параметры: `PYTHONPATH=src uv run python -m mmar_chunker -h`, значения по умолчанию — в
43
+ `src/mmar_chunker/config.py`. Цены разрезов меняются по имени: `ARGS='--cut-costs "sentence=0.1,word=2"'`.
44
+
45
+ ## Вход
46
+
47
+ Папка с `*.json`, по файлу на домен (`econ_full_chunks.json`, …). Каждый файл — список блоков:
48
+
49
+ ```json
50
+ {"text": "...", "document_id": "doc.pdf", "page_id": "2", "chunk_id": "10",
51
+ "bbox": {"x_left": 0.09, "y_bottom": 0.49, "x_right": 0.91, "y_top": 0.87}}
52
+ ```
53
+
54
+ ## Выход
55
+
56
+ В папке `OUT` по файлу на домен `chunk_<домен>_<версия>_<средняя длина>_<число чанков>.json`
57
+ (например `chunk_econ_1.0.0_957_2588.json`; версия чанкера — из `pyproject.toml`) и `report.json`
58
+ (версия, параметры и метрики длин по доменам). Чанк:
59
+
60
+ ```json
61
+ {"text": "...", "document_id": "doc.pdf", "page_id": 2, "chunk_id": 10,
62
+ "bbox": {"x_left": 0.09, "y_bottom": 0.49, "x_right": 0.91, "y_top": 0.89}}
63
+ ```
64
+
65
+ `chunk_id` — номер чанка в документе. Чанк всегда лежит на одной странице, `bbox` — общая
66
+ рамка всех его блоков. Для отладки `ARGS=--bboxes` дописывает в чанк список `bboxes` исходных
67
+ блоков; его требует `scripts/check_output.py`.
68
+ Форматы описаны моделями в `src/mmar_chunker/models.py` (`Block`, `Chunk`), отчёт — в `report.py`.
69
+
70
+ ## Проверка
71
+
72
+ ```bash
73
+ make pre # формат, линтер и тесты (pre-commit)
74
+ make test
75
+ ```
@@ -0,0 +1,48 @@
1
+
2
+ # MMAR Chunker
3
+
4
+ Склеивает блоки OCR из `proc_json` в чанки произвольной длины (`--target-size`, по умолчанию 1000 символов).
5
+
6
+ Таблица никогда не режется: она целиком лежит в одном чанке, даже если длиннее коридора.
7
+
8
+ ## Запуск
9
+
10
+ ```bash
11
+ make deps
12
+ make run DATA=~/dvc_data/proc_json OUT=chunks_json
13
+ ```
14
+
15
+ Python 3.12. Параметры: `PYTHONPATH=src uv run python -m mmar_chunker -h`, значения по умолчанию — в
16
+ `src/mmar_chunker/config.py`. Цены разрезов меняются по имени: `ARGS='--cut-costs "sentence=0.1,word=2"'`.
17
+
18
+ ## Вход
19
+
20
+ Папка с `*.json`, по файлу на домен (`econ_full_chunks.json`, …). Каждый файл — список блоков:
21
+
22
+ ```json
23
+ {"text": "...", "document_id": "doc.pdf", "page_id": "2", "chunk_id": "10",
24
+ "bbox": {"x_left": 0.09, "y_bottom": 0.49, "x_right": 0.91, "y_top": 0.87}}
25
+ ```
26
+
27
+ ## Выход
28
+
29
+ В папке `OUT` по файлу на домен `chunk_<домен>_<версия>_<средняя длина>_<число чанков>.json`
30
+ (например `chunk_econ_1.0.0_957_2588.json`; версия чанкера — из `pyproject.toml`) и `report.json`
31
+ (версия, параметры и метрики длин по доменам). Чанк:
32
+
33
+ ```json
34
+ {"text": "...", "document_id": "doc.pdf", "page_id": 2, "chunk_id": 10,
35
+ "bbox": {"x_left": 0.09, "y_bottom": 0.49, "x_right": 0.91, "y_top": 0.89}}
36
+ ```
37
+
38
+ `chunk_id` — номер чанка в документе. Чанк всегда лежит на одной странице, `bbox` — общая
39
+ рамка всех его блоков. Для отладки `ARGS=--bboxes` дописывает в чанк список `bboxes` исходных
40
+ блоков; его требует `scripts/check_output.py`.
41
+ Форматы описаны моделями в `src/mmar_chunker/models.py` (`Block`, `Chunk`), отчёт — в `report.py`.
42
+
43
+ ## Проверка
44
+
45
+ ```bash
46
+ make pre # формат, линтер и тесты (pre-commit)
47
+ make test
48
+ ```
@@ -0,0 +1,70 @@
1
+ [project]
2
+ name = "MMAR-Chunker"
3
+ # dynamic version is not supported yet on uv_build
4
+ version = "1.0.0"
5
+ description = "Склейка блоков OCR в чанки: DP под целевой размер"
6
+ authors = [
7
+ { name = "malovichko", email = "malovichko@airi.net" },
8
+ { name = "kartashev", email = "kartashev@airi.net" },
9
+ { name = "kopanichuk", email = "kopanichuk@airi.net" },
10
+ { name = "tagin", email = "tagin@airi.net" },
11
+ { name = "bakulin", email = "bakulin@airi.net" },
12
+ ]
13
+ license = "MIT"
14
+ license-files = ["LICENSE"]
15
+ readme = "README.md"
16
+ requires-python = ">=3.12"
17
+ keywords = []
18
+ classifiers = [
19
+ "Development Status :: 4 - Beta",
20
+ "Intended Audience :: Developers",
21
+ "Programming Language :: Python",
22
+ "Programming Language :: Python :: 3",
23
+ "Programming Language :: Python :: 3 :: Only",
24
+ "Programming Language :: Python :: 3.12",
25
+ "Programming Language :: Python :: 3.13",
26
+ "Programming Language :: Python :: 3.14",
27
+ "Topic :: Documentation",
28
+ "Topic :: Software Development",
29
+ "Topic :: Utilities",
30
+ "Typing :: Typed",
31
+ ]
32
+ dependencies = [
33
+ "loguru~=0.7.3",
34
+ "numpy~=2.0",
35
+ "pydantic~=2.12",
36
+ ]
37
+
38
+ [build-system]
39
+ requires = ["uv_build>=0.8.14,<0.9.0"]
40
+ build-backend = "uv_build"
41
+
42
+ [tool.uv.build-backend]
43
+ module-name = "mmar_chunker"
44
+ source-exclude = [".ruff_cache"]
45
+
46
+ [dependency-groups]
47
+ dev = [
48
+ "pre-commit>=4.7.0",
49
+ "ruff>=0.4",
50
+ "pytest>=8.2",
51
+ "pytest-asyncio>=1.0.0",
52
+ "ty>=0.0.1a1",
53
+ ]
54
+
55
+ [tool.uv]
56
+ default-groups = ["dev"]
57
+
58
+ [tool.ruff]
59
+ line-length = 120
60
+ target-version = "py312"
61
+
62
+ [tool.pytest.ini_options]
63
+ asyncio_mode = "auto"
64
+
65
+ [pytest]
66
+ python_files = [ "test_*.py" ]
67
+ testpaths = [ "tests" ]
68
+
69
+ # action:message_regex:warning_class:module_regex:line
70
+ filterwarnings = [ "error" ]
@@ -0,0 +1,34 @@
1
+ from importlib.metadata import version
2
+
3
+ __version__ = version("MMAR-Chunker")
4
+
5
+
6
+ from mmar_chunker import splitting
7
+ from mmar_chunker.chunker import Chunker
8
+ from mmar_chunker.config import ChunkerConfig, CutCosts
9
+ from mmar_chunker.models import (
10
+ BBox,
11
+ Block,
12
+ Chunk,
13
+ CutType,
14
+ SourceBlock,
15
+ load_blocks,
16
+ load_chunks,
17
+ save_chunks,
18
+ )
19
+
20
+ __all__ = [
21
+ "BBox",
22
+ "Block",
23
+ "Chunk",
24
+ "Chunker",
25
+ "ChunkerConfig",
26
+ "CutCosts",
27
+ "CutType",
28
+ "SourceBlock",
29
+ "__version__",
30
+ "load_blocks",
31
+ "load_chunks",
32
+ "save_chunks",
33
+ "splitting",
34
+ ]
@@ -0,0 +1,3 @@
1
+ from mmar_chunker.cli import main
2
+
3
+ main()
@@ -0,0 +1,83 @@
1
+ import itertools
2
+ from collections import defaultdict
3
+
4
+ from mmar_chunker.config import ChunkerConfig
5
+ from mmar_chunker.dp import dp_bounds
6
+ from mmar_chunker.models import BBox, Block, Chunk, SourceBlock
7
+ from mmar_chunker.splitting import Unit, to_units
8
+
9
+
10
+ def group_by_document(blocks: list[Block]) -> dict[str, list[Block]]:
11
+ """Блоки по документам, внутри документа — в порядке чтения."""
12
+ docs: dict[str, list[Block]] = defaultdict(list)
13
+ for block in blocks:
14
+ docs[block.document_id].append(block)
15
+ for doc_blocks in docs.values():
16
+ doc_blocks.sort(key=lambda b: (b.page_id, b.chunk_id))
17
+ return docs
18
+
19
+
20
+ class Chunker:
21
+ def __init__(self, config: ChunkerConfig | None = None):
22
+ self.cfg = config or ChunkerConfig()
23
+
24
+ def chunk_records(self, blocks: list[Block]) -> list[Chunk]:
25
+ chunks: list[Chunk] = []
26
+ for document_id, doc_blocks in group_by_document(blocks).items():
27
+ chunks.extend(self.chunk_document(document_id, doc_blocks))
28
+ return chunks
29
+
30
+ def chunk_document(self, document_id: str, blocks: list[Block]) -> list[Chunk]:
31
+ cfg = self.cfg
32
+ units = to_units(blocks, cfg.max_unit)
33
+ sizes = [len(u.text) for u in units]
34
+ pages = [u.block.page_id for u in units]
35
+ cuts = [u.cut for u in units]
36
+ joins = [0] + [
37
+ 0 if units[i].src == units[i - 1].src else len(cfg.separator)
38
+ for i in range(1, len(units))
39
+ ]
40
+ bounds = dp_bounds(sizes, pages, joins, cfg, cuts)
41
+ return [
42
+ self._make_chunk(document_id, k, units[a:b])
43
+ for k, (a, b) in enumerate(bounds)
44
+ ]
45
+
46
+ def _make_chunk(self, document_id: str, chunk_id: int, units: list[Unit]) -> Chunk:
47
+ text = units[0].text
48
+ for prev, unit in itertools.pairwise(units):
49
+ text += ("" if unit.src == prev.src else self.cfg.separator) + unit.text
50
+
51
+ sources: list[SourceBlock] = []
52
+ for i, unit in enumerate(units):
53
+ if i and unit.src == units[i - 1].src:
54
+ continue # следующий кусок того же блока
55
+ b = unit.block
56
+ sources.append(
57
+ SourceBlock(
58
+ page_id=b.page_id, chunk_id=b.chunk_id, **b.bbox.model_dump()
59
+ )
60
+ )
61
+
62
+ return Chunk(
63
+ text=text,
64
+ document_id=document_id,
65
+ page_id=units[0].block.page_id,
66
+ chunk_id=chunk_id,
67
+ bbox=union_bbox(sources),
68
+ bboxes=sources,
69
+ cut=units[-1].cut,
70
+ )
71
+
72
+
73
+ def union_bbox(sources: list[SourceBlock]) -> BBox:
74
+ """Общая рамка блоков чанка. Если склейка через страницу разрешена
75
+ (page_penalty < inf), рамка покрывает только первую страницу чанка."""
76
+ page = sources[0].page_id
77
+ same_page = [b for b in sources if b.page_id == page]
78
+ return BBox(
79
+ x_left=min(b.x_left for b in same_page),
80
+ y_bottom=min(b.y_bottom for b in same_page),
81
+ x_right=max(b.x_right for b in same_page),
82
+ y_top=max(b.y_top for b in same_page),
83
+ )
@@ -0,0 +1,120 @@
1
+ import argparse
2
+ from pathlib import Path
3
+
4
+ import numpy as np
5
+ from loguru import logger
6
+
7
+ from mmar_chunker import __version__
8
+ from mmar_chunker.chunker import Chunker
9
+ from mmar_chunker.config import ChunkerConfig, CutCosts
10
+ from mmar_chunker.models import load_blocks, save_chunks
11
+ from mmar_chunker.report import DomainStats, Report
12
+
13
+
14
+ def build_parser() -> argparse.ArgumentParser:
15
+ defaults = ChunkerConfig()
16
+ parser = argparse.ArgumentParser(
17
+ prog="MMAR Chunker",
18
+ description="Склейка блоков OCR в чанки с помощью DP",
19
+ )
20
+ parser.add_argument(
21
+ "--data", type=Path, required=True, help="папка с *.json блоков"
22
+ )
23
+ parser.add_argument("--out", type=Path, required=True, help="папка для результата")
24
+ parser.add_argument("--target-size", type=int, default=defaults.target_size)
25
+ parser.add_argument("--half-width", type=float, default=defaults.half_width)
26
+ parser.add_argument("--sigma", type=float, default=defaults.sigma)
27
+ parser.add_argument(
28
+ "--shape", choices=["normal", "gennorm"], default=defaults.shape
29
+ )
30
+ parser.add_argument("--gn-beta", type=float, default=defaults.gn_beta)
31
+ parser.add_argument("--page-penalty", type=float, default=defaults.page_penalty)
32
+ parser.add_argument("--max-size", type=int, default=defaults.max_size)
33
+ parser.add_argument("--max-unit", type=int, default=defaults.max_unit)
34
+ parser.add_argument(
35
+ "--cut-costs",
36
+ type=str,
37
+ default="",
38
+ help='стоимости разрезов, меняются только указанные: "sentence=0.05,word=2" '
39
+ f"(по умолчанию {defaults.cut_costs.model_dump()})",
40
+ )
41
+ parser.add_argument(
42
+ "--bboxes",
43
+ action="store_true",
44
+ help="записать в файл ещё и список рамок исходных блоков (для отладки и "
45
+ "scripts/check_output.py)",
46
+ )
47
+ return parser
48
+
49
+
50
+ def parse_cut_costs(text: str) -> CutCosts:
51
+ """ "sentence=0.05,word=2" поверх цен по умолчанию; неизвестное имя — ошибка."""
52
+ override = {}
53
+ for item in filter(None, (s.strip() for s in text.split(","))):
54
+ name, value = item.split("=")
55
+ override[name.strip()] = float(value)
56
+ return CutCosts(**{**CutCosts().model_dump(), **override})
57
+
58
+
59
+ def chunk_file_name(domain: str, st: DomainStats) -> str:
60
+ """Имя для DVC: chunk_<домен>_<версия чанкера>_<средняя длина>_<число чанков>.json."""
61
+ return f"chunk_{domain}_{__version__}_{round(st.mean)}_{st.chunks}.json"
62
+
63
+
64
+ def config_from_args(args: argparse.Namespace) -> ChunkerConfig:
65
+ return ChunkerConfig(
66
+ target_size=args.target_size,
67
+ half_width=args.half_width,
68
+ sigma=args.sigma,
69
+ shape=args.shape,
70
+ gn_beta=args.gn_beta,
71
+ page_penalty=args.page_penalty,
72
+ max_size=args.max_size,
73
+ max_unit=args.max_unit,
74
+ cut_costs=parse_cut_costs(args.cut_costs),
75
+ single_bbox=not args.bboxes,
76
+ )
77
+
78
+
79
+ def main(argv: list[str] | None = None) -> None:
80
+ args = build_parser().parse_args(argv)
81
+ cfg = config_from_args(args)
82
+ if np.isinf(cfg.page_penalty):
83
+ logger.info("page_penalty=inf: склейка через страницу запрещена")
84
+ chunker = Chunker(cfg)
85
+ args.out.mkdir(parents=True, exist_ok=True)
86
+
87
+ report = Report(version=__version__, config=cfg)
88
+ for path in sorted(args.data.glob("*.json")):
89
+ domain = path.name.split("_")[0]
90
+ blocks = load_blocks(path)
91
+ chunks = chunker.chunk_records(blocks)
92
+ st = report.domains[domain] = DomainStats.of(chunks, cfg)
93
+ save_chunks(
94
+ args.out / chunk_file_name(domain, st),
95
+ chunks,
96
+ with_bboxes=not cfg.single_bbox,
97
+ )
98
+ logger.info(
99
+ "{}: {} блоков -> {} чанков, среднее {} ± {} (CV {}%), |S-T|/T {}%, "
100
+ "вне коридора {}%, через страницу {}%, разрезы {}",
101
+ domain,
102
+ len(blocks),
103
+ st.chunks,
104
+ st.mean,
105
+ st.std,
106
+ st.cv_pct,
107
+ st.mean_abs_dev_pct,
108
+ st.outside_bounds_pct,
109
+ st.cross_page_pct,
110
+ {k.value: v for k, v in st.cuts_pct.items()},
111
+ )
112
+
113
+ (args.out / "report.json").write_text(
114
+ report.model_dump_json(indent=2), encoding="utf-8"
115
+ )
116
+ logger.info("Готово: {}", args.out)
117
+
118
+
119
+ if __name__ == "__main__":
120
+ main()
@@ -0,0 +1,70 @@
1
+ from typing import Literal
2
+
3
+ import numpy as np
4
+ from pydantic import BaseModel, ConfigDict, Field
5
+
6
+ from mmar_chunker.models import CutType
7
+
8
+
9
+ class _Strict(BaseModel):
10
+ """Лишние ключи запрещены: опечатка в имени параметра — ошибка, а не тихий дефолт."""
11
+
12
+ model_config = ConfigDict(extra="forbid")
13
+
14
+
15
+ class CutCosts(_Strict):
16
+ """Цена разреза по типу точки, в единицах штрафа за размер ((S-T)/σ)²/2.
17
+
18
+ Граница блока бесплатна. Внутри таблицы точек разреза нет: таблица не режется.
19
+ """
20
+
21
+ sentence: float = 0.05
22
+ clause: float = 0.3
23
+ word: float = 1.0
24
+ char: float = 5.0
25
+
26
+ def of(self, cut: CutType) -> float:
27
+ return 0.0 if cut is CutType.BLOCK else getattr(self, cut.value)
28
+
29
+ def scaled(self, factor: float) -> "CutCosts":
30
+ return CutCosts(**{k: v * factor for k, v in self.model_dump().items()})
31
+
32
+
33
+ class ChunkerConfig(_Strict):
34
+ # page_penalty=inf пишется в report.json строкой "Infinity" и читается обратно
35
+ model_config = ConfigDict(extra="forbid", ser_json_inf_nan="strings")
36
+
37
+ target_size: int = Field(1000, description="Целевой размер чанка, символы (T)")
38
+ half_width: float = Field(
39
+ 0.4,
40
+ description="Полуширина коридора в долях T: допустимые чанки [T(1-h), T(1+h)]",
41
+ )
42
+ barrier: float = Field(
43
+ 30.0,
44
+ description="Штраф за выход за коридор, когда уложиться в него невозможно",
45
+ )
46
+ cut_costs: CutCosts = Field(default_factory=CutCosts)
47
+ max_unit: int = Field(
48
+ 300, description="Предложение длиннее делится по клаузам, клауза — по словам"
49
+ )
50
+ sigma: float = Field(250.0, description="Ширина колокола для shape=normal, символы")
51
+ shape: Literal["normal", "gennorm"] = "normal"
52
+ gn_beta: float = Field(
53
+ 2.0,
54
+ description="Показатель для shape=gennorm: штраф |S-T|^β/σ^β/2; "
55
+ "β=2 совпадает с normal, β→∞ — жёсткая стенка на ±σ",
56
+ )
57
+ page_penalty: float = Field(
58
+ np.inf,
59
+ description="Штраф за каждую границу страницы внутри чанка; inf = чанк всегда "
60
+ "на одной странице (тогда общая рамка bbox покрывает его целиком)",
61
+ )
62
+ max_size: int = Field(
63
+ 2000, description="Чанк из нескольких кусков не длиннее этого"
64
+ )
65
+ separator: str = Field("\n", description="Разделитель между текстами блоков")
66
+ single_bbox: bool = Field(
67
+ True,
68
+ description="В файл пишется только общая рамка bbox; False — ещё и список bboxes "
69
+ "исходных блоков (для отладки и проверок, потом уберём)",
70
+ )
@@ -0,0 +1,87 @@
1
+ from collections.abc import Sequence
2
+
3
+ import numpy as np
4
+
5
+ from mmar_chunker.config import ChunkerConfig
6
+ from mmar_chunker.models import CutType
7
+
8
+ Bounds = list[tuple[int, int]] # полуинтервалы индексов юнитов [start, end)
9
+
10
+
11
+ def bounds_of(cfg: ChunkerConfig) -> tuple[float, float]:
12
+ return cfg.target_size * (1 - cfg.half_width), cfg.target_size * (
13
+ 1 + cfg.half_width
14
+ )
15
+
16
+
17
+ def chunk_cost(size: int, cfg: ChunkerConfig) -> float:
18
+ """Штраф за размер: внутри коридора тянем к T, снаружи барьер.
19
+
20
+ Коридор в DP — жёсткое окно; барьер срабатывает только когда окно невыполнимо
21
+ (документ короче нижней границы, слово длиннее верхней).
22
+ """
23
+ lo, hi = bounds_of(cfg)
24
+ if size < lo or size > hi:
25
+ dist = lo - size if size < lo else size - hi
26
+ return cfg.barrier * (1 + dist / cfg.target_size)
27
+ if cfg.shape == "gennorm":
28
+ return (abs(size - cfg.target_size) / cfg.sigma) ** cfg.gn_beta / 2
29
+ return ((size - cfg.target_size) / cfg.sigma) ** 2 / 2
30
+
31
+
32
+ def dp_bounds(
33
+ sizes: Sequence[int],
34
+ pages: Sequence[int],
35
+ joins: Sequence[int],
36
+ cfg: ChunkerConfig,
37
+ cuts: Sequence[CutType] | None = None,
38
+ ) -> Bounds:
39
+ """Минимум суммы штрафов: размер + цена разреза + страницы.
40
+
41
+ joins[i] — длина склейки между юнитами i-1 и i. cuts[i] — тип правой границы
42
+ юнита i; чанк, заканчивающийся на юните i, платит cfg.cut_costs.of(cuts[i]).
43
+ Коридор [lo, hi] — жёсткое окно: позиции j, достижимые внутри окна, не
44
+ рассматривают варианты вне него; если таких нет, берётся лучший вне окна с барьером.
45
+ """
46
+ n = len(sizes)
47
+ lo, hi = bounds_of(cfg)
48
+ best = [np.inf] * (n + 1)
49
+ prev = [-1] * (n + 1)
50
+ best[0] = 0.0
51
+ forbid_pages = np.isinf(cfg.page_penalty)
52
+ cut_cost = [0.0] * n
53
+ if cuts is not None:
54
+ cut_cost = [cfg.cut_costs.of(c) for c in cuts]
55
+
56
+ for j in range(1, n + 1): # чанк = юниты i .. j-1
57
+ size, crossings = 0, 0
58
+ best_in, prev_in = np.inf, -1 # лучший вариант внутри окна
59
+ best_out, prev_out = np.inf, -1 # лучший вне окна (запасной)
60
+ for i in range(j - 1, -1, -1):
61
+ size += sizes[i] + (joins[i + 1] if i < j - 1 else 0)
62
+ if i < j - 1:
63
+ if pages[i] != pages[i + 1]:
64
+ crossings += 1
65
+ if forbid_pages:
66
+ break
67
+ if size > cfg.max_size:
68
+ break
69
+ cost = best[i] + chunk_cost(size, cfg) + cut_cost[j - 1]
70
+ if crossings:
71
+ cost += cfg.page_penalty * crossings
72
+ if lo <= size <= hi:
73
+ if cost < best_in:
74
+ best_in, prev_in = cost, i
75
+ elif cost < best_out:
76
+ best_out, prev_out = cost, i
77
+ if prev_in >= 0:
78
+ best[j], prev[j] = best_in, prev_in
79
+ else:
80
+ best[j], prev[j] = best_out, prev_out
81
+
82
+ bounds: Bounds = []
83
+ j = n
84
+ while j > 0:
85
+ bounds.append((prev[j], j))
86
+ j = prev[j]
87
+ return bounds[::-1]
@@ -0,0 +1,80 @@
1
+ """Данные чанкера: блоки OCR на входе, чанки на выходе, тип точки разреза."""
2
+
3
+ from enum import StrEnum
4
+ from pathlib import Path
5
+
6
+ from pydantic import BaseModel, ConfigDict, Field, TypeAdapter
7
+
8
+
9
+ class CutType(StrEnum):
10
+ """Тип точки разреза (правой границы куска текста), от дешёвых к дорогим."""
11
+
12
+ BLOCK = "block" # граница исходного блока OCR
13
+ SENTENCE = "sentence" # конец предложения
14
+ CLAUSE = "clause" # запятая, точка с запятой, двоеточие, тире
15
+ WORD = "word" # граница слова
16
+ CHAR = "char" # произвольный символ: только если слово длиннее max_unit
17
+
18
+
19
+ class BBox(BaseModel):
20
+ """Рамка на странице в долях её размера."""
21
+
22
+ model_config = ConfigDict(frozen=True)
23
+
24
+ x_left: float
25
+ y_bottom: float
26
+ x_right: float
27
+ y_top: float
28
+
29
+
30
+ class Block(BaseModel):
31
+ """Блок OCR из proc_json. Номера страниц и блоков в файле — строки, здесь — числа."""
32
+
33
+ model_config = ConfigDict(frozen=True)
34
+
35
+ text: str
36
+ document_id: str
37
+ page_id: int
38
+ chunk_id: int # номер блока на странице
39
+ bbox: BBox
40
+
41
+
42
+ class SourceBlock(BBox):
43
+ """Исходный блок внутри чанка: где он лежит и его рамка."""
44
+
45
+ page_id: int
46
+ chunk_id: int
47
+
48
+
49
+ class Chunk(BaseModel):
50
+ """Чанк для индекса. Чанк лежит на одной странице, рамка bbox покрывает его целиком.
51
+
52
+ bboxes — исходные блоки чанка: в памяти есть всегда (для проверок и статистики),
53
+ в файл пишутся только в режиме отладки (--bboxes).
54
+ """
55
+
56
+ text: str
57
+ document_id: str
58
+ page_id: int # страница начала чанка
59
+ chunk_id: int # номер чанка в документе: 0, 1, 2, …
60
+ bbox: BBox # общая рамка всех блоков чанка
61
+ bboxes: list[SourceBlock] | None = None # исходные блоки; в файле только с --bboxes
62
+ # чем кончается чанк: для статистики, в файл не пишется (у прочитанного из файла None)
63
+ cut: CutType | None = Field(None, exclude=True)
64
+
65
+
66
+ _BLOCKS = TypeAdapter(list[Block])
67
+ _CHUNKS = TypeAdapter(list[Chunk])
68
+
69
+
70
+ def load_blocks(path: Path) -> list[Block]:
71
+ return _BLOCKS.validate_json(path.read_bytes())
72
+
73
+
74
+ def load_chunks(path: Path) -> list[Chunk]:
75
+ return _CHUNKS.validate_json(path.read_bytes())
76
+
77
+
78
+ def save_chunks(path: Path, chunks: list[Chunk], *, with_bboxes: bool = False) -> None:
79
+ exclude = None if with_bboxes else {"__all__": {"bboxes"}}
80
+ path.write_bytes(_CHUNKS.dump_json(chunks, exclude=exclude, exclude_none=True))
@@ -0,0 +1,64 @@
1
+ """Статистика длин чанков по домену (report.json)."""
2
+
3
+ import statistics
4
+
5
+ from pydantic import BaseModel
6
+
7
+ from mmar_chunker.config import ChunkerConfig
8
+ from mmar_chunker.dp import bounds_of
9
+ from mmar_chunker.models import Chunk, CutType
10
+
11
+
12
+ class DomainStats(BaseModel):
13
+ chunks: int
14
+ mean: float
15
+ median: int
16
+ std: float
17
+ cv_pct: float # коэффициент вариации std / mean — главная цель
18
+ p5: int
19
+ p95: int
20
+ min: int
21
+ max: int
22
+ mean_abs_dev_pct: float # среднее |S - T| / T = W1 до пика «все чанки ровно T»
23
+ within_10_pct: float
24
+ within_20_pct: float
25
+ outside_bounds_pct: float # доля чанков вне коридора [T(1-h), T(1+h)]
26
+ cross_page_pct: float # доля чанков, склеенных через границу страницы
27
+ cuts_pct: dict[CutType, float] # чем кончаются чанки
28
+
29
+ @classmethod
30
+ def of(cls, chunks: list[Chunk], cfg: ChunkerConfig) -> "DomainStats":
31
+ sizes = sorted(len(c.text) for c in chunks)
32
+ n, t = len(sizes), cfg.target_size
33
+ lo, hi = bounds_of(cfg)
34
+ mean = statistics.fmean(sizes)
35
+ std = statistics.pstdev(sizes)
36
+ cross = sum(len({b.page_id for b in c.bboxes or []}) > 1 for c in chunks)
37
+ cuts = [c.cut for c in chunks if c.cut is not None]
38
+
39
+ def pct(k: int) -> float:
40
+ return round(100 * k / n, 1)
41
+
42
+ return cls(
43
+ chunks=n,
44
+ mean=round(mean, 1),
45
+ median=int(statistics.median(sizes)),
46
+ std=round(std, 1),
47
+ cv_pct=round(100 * std / mean, 1),
48
+ p5=sizes[int(0.05 * (n - 1))],
49
+ p95=sizes[int(0.95 * (n - 1))],
50
+ min=sizes[0],
51
+ max=sizes[-1],
52
+ mean_abs_dev_pct=round(100 * sum(abs(s - t) for s in sizes) / n / t, 1),
53
+ within_10_pct=pct(sum(abs(s - t) <= 0.1 * t for s in sizes)),
54
+ within_20_pct=pct(sum(abs(s - t) <= 0.2 * t for s in sizes)),
55
+ outside_bounds_pct=round(100 * sum(s < lo or s > hi for s in sizes) / n, 2),
56
+ cross_page_pct=pct(cross),
57
+ cuts_pct={k: pct(cuts.count(k)) for k in CutType if k in cuts},
58
+ )
59
+
60
+
61
+ class Report(BaseModel):
62
+ version: str # версия чанкера
63
+ config: ChunkerConfig
64
+ domains: dict[str, DomainStats] = {}
@@ -0,0 +1,95 @@
1
+ """Разметка текста блоков на куски (юниты) с типом точки разреза после каждого."""
2
+
3
+ import re
4
+
5
+ from pydantic import BaseModel, ConfigDict
6
+
7
+ from mmar_chunker.models import Block, CutType
8
+
9
+ # Числовой токен таблицы: -0,523 (0,612) 4,40*** .0955642 12% и одиночные + - *
10
+ NUMERIC = re.compile(r"[(\[]?[-+–−]?\.?\d[\d.,]*%?\**[)\]]?|[-+–−*]+")
11
+ TABLE_MIN_TOKENS = 15 # короткий блок резать почти не приходится, детектор ему не нужен
12
+ TABLE_NUMERIC_SHARE = 0.30
13
+
14
+ SENTENCE = re.compile(r"(?<=[.!?…]\s)(?=[«\"(A-ZА-ЯЁ0-9])|(?<=\n)")
15
+ CLAUSE = re.compile(r"(?<=[,;:]\s)|(?<=\s[—–-]\s)")
16
+ WORD = re.compile(r"(?<=\s)(?=\S)")
17
+
18
+
19
+ class Unit(BaseModel):
20
+ """Неделимый кусок текста блока; чанк — отрезок подряд идущих юнитов."""
21
+
22
+ model_config = ConfigDict(frozen=True)
23
+
24
+ text: str
25
+ src: int # номер исходного блока в документе
26
+ block: Block
27
+ cut: CutType # тип точки разреза после юнита
28
+
29
+
30
+ def _split(text: str, pattern: re.Pattern[str]) -> list[str]:
31
+ return [p for p in pattern.split(text) if p]
32
+
33
+
34
+ def mark_cuts(text: str, max_unit: int) -> list[tuple[str, CutType]]:
35
+ """Режет текст блока на юниты по иерархии, помечая тип правой границы каждого.
36
+
37
+ Предложения всегда отдельные юниты. Предложение длиннее max_unit делится по
38
+ клаузам, клауза длиннее max_unit по словам, слово длиннее max_unit по символам.
39
+ Конкатенация текстов юнитов равна исходному тексту.
40
+ """
41
+ out: list[tuple[str, CutType]] = []
42
+ sentences = _split(text, SENTENCE)
43
+ for si, sent in enumerate(sentences):
44
+ last_s = si == len(sentences) - 1
45
+ if len(sent) <= max_unit:
46
+ out.append((sent, CutType.BLOCK if last_s else CutType.SENTENCE))
47
+ continue
48
+ clauses = _split(sent, CLAUSE)
49
+ for ci, clause in enumerate(clauses):
50
+ last_c = ci == len(clauses) - 1
51
+ end_s = CutType.BLOCK if last_s else CutType.SENTENCE
52
+ end_c = end_s if last_c else CutType.CLAUSE
53
+ if len(clause) <= max_unit:
54
+ out.append((clause, end_c))
55
+ continue
56
+ words = _split(clause, WORD)
57
+ for wi, word in enumerate(words):
58
+ last_w = wi == len(words) - 1
59
+ end_w = end_c if last_w else CutType.WORD
60
+ if len(word) <= max_unit:
61
+ out.append((word, end_w))
62
+ continue
63
+ pieces = [word[k : k + max_unit] for k in range(0, len(word), max_unit)]
64
+ for pi, piece in enumerate(pieces):
65
+ out.append(
66
+ (piece, end_w if pi == len(pieces) - 1 else CutType.CHAR)
67
+ )
68
+ return out
69
+
70
+
71
+ def numeric_share(text: str) -> float:
72
+ """Доля числовых токенов; 0 для блоков короче TABLE_MIN_TOKENS токенов."""
73
+ tokens = text.split()
74
+ if len(tokens) < TABLE_MIN_TOKENS:
75
+ return 0.0
76
+ return sum(bool(NUMERIC.fullmatch(t)) for t in tokens) / len(tokens)
77
+
78
+
79
+ def is_table(text: str) -> bool:
80
+ """Таблица после OCR: плоская строка, где числа составляют заметную долю токенов."""
81
+ return numeric_share(text) >= TABLE_NUMERIC_SHARE
82
+
83
+
84
+ def to_units(blocks: list[Block], max_unit: int) -> list[Unit]:
85
+ units: list[Unit] = []
86
+ for k, block in enumerate(blocks):
87
+ if is_table(block.text):
88
+ # таблица — один неделимый кусок: внутри неё нет точек разреза, и она всегда
89
+ # целиком в одном чанке, даже если длиннее коридора
90
+ parts = [(block.text, CutType.BLOCK)]
91
+ else:
92
+ parts = mark_cuts(block.text, max_unit)
93
+ for part, cut in parts:
94
+ units.append(Unit(text=part, src=k, block=block, cut=cut))
95
+ return units