ru-corpus-kit 0.1.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.
Files changed (34) hide show
  1. ru_corpus_kit-0.1.0/PKG-INFO +218 -0
  2. ru_corpus_kit-0.1.0/README.md +182 -0
  3. ru_corpus_kit-0.1.0/pyproject.toml +52 -0
  4. ru_corpus_kit-0.1.0/setup.cfg +4 -0
  5. ru_corpus_kit-0.1.0/src/ru_corpus_kit/__init__.py +3 -0
  6. ru_corpus_kit-0.1.0/src/ru_corpus_kit/answer.py +157 -0
  7. ru_corpus_kit-0.1.0/src/ru_corpus_kit/bm25.py +277 -0
  8. ru_corpus_kit-0.1.0/src/ru_corpus_kit/cli.py +147 -0
  9. ru_corpus_kit-0.1.0/src/ru_corpus_kit/config.py +156 -0
  10. ru_corpus_kit-0.1.0/src/ru_corpus_kit/extract.py +349 -0
  11. ru_corpus_kit-0.1.0/src/ru_corpus_kit/indexer.py +341 -0
  12. ru_corpus_kit-0.1.0/src/ru_corpus_kit/kit.py +68 -0
  13. ru_corpus_kit-0.1.0/src/ru_corpus_kit/meta.py +148 -0
  14. ru_corpus_kit-0.1.0/src/ru_corpus_kit/norm.py +139 -0
  15. ru_corpus_kit-0.1.0/src/ru_corpus_kit/ocrfix.py +114 -0
  16. ru_corpus_kit-0.1.0/src/ru_corpus_kit/pdftables.py +44 -0
  17. ru_corpus_kit-0.1.0/src/ru_corpus_kit/profile.py +81 -0
  18. ru_corpus_kit-0.1.0/src/ru_corpus_kit/profiles/tso_disclosure/ocr_words.txt +82 -0
  19. ru_corpus_kit-0.1.0/src/ru_corpus_kit/profiles/tso_disclosure/profile.toml +56 -0
  20. ru_corpus_kit-0.1.0/src/ru_corpus_kit/profiles/tso_disclosure/synonyms.toml +29 -0
  21. ru_corpus_kit-0.1.0/src/ru_corpus_kit/registry.py +108 -0
  22. ru_corpus_kit-0.1.0/src/ru_corpus_kit/status.py +96 -0
  23. ru_corpus_kit-0.1.0/src/ru_corpus_kit/store.py +60 -0
  24. ru_corpus_kit-0.1.0/src/ru_corpus_kit/tables.py +282 -0
  25. ru_corpus_kit-0.1.0/src/ru_corpus_kit/tools.py +381 -0
  26. ru_corpus_kit-0.1.0/src/ru_corpus_kit/wide.py +451 -0
  27. ru_corpus_kit-0.1.0/src/ru_corpus_kit.egg-info/PKG-INFO +218 -0
  28. ru_corpus_kit-0.1.0/src/ru_corpus_kit.egg-info/SOURCES.txt +32 -0
  29. ru_corpus_kit-0.1.0/src/ru_corpus_kit.egg-info/dependency_links.txt +1 -0
  30. ru_corpus_kit-0.1.0/src/ru_corpus_kit.egg-info/entry_points.txt +2 -0
  31. ru_corpus_kit-0.1.0/src/ru_corpus_kit.egg-info/requires.txt +28 -0
  32. ru_corpus_kit-0.1.0/src/ru_corpus_kit.egg-info/top_level.txt +1 -0
  33. ru_corpus_kit-0.1.0/tests/test_kit.py +412 -0
  34. ru_corpus_kit-0.1.0/tests/test_units.py +88 -0
@@ -0,0 +1,218 @@
1
+ Metadata-Version: 2.4
2
+ Name: ru-corpus-kit
3
+ Version: 0.1.0
4
+ Summary: Русский поиск и проверяемая аналитика по корпусу документов: индексация, поиск BM25 по леммам, таблицы, числа
5
+ Author: ru-corpus contributors
6
+ License: Apache-2.0
7
+ Project-URL: Homepage, https://github.com/ru-data-analysis/ru-corpus
8
+ Project-URL: Issues, https://github.com/ru-data-analysis/ru-corpus/issues
9
+ Keywords: russian,search,bm25,corpus,ocr,tables
10
+ Classifier: License :: OSI Approved :: Apache Software License
11
+ Classifier: Programming Language :: Python :: 3
12
+ Classifier: Natural Language :: Russian
13
+ Requires-Python: >=3.10
14
+ Description-Content-Type: text/markdown
15
+ Requires-Dist: pymorphy3>=1.2
16
+ Requires-Dist: openpyxl>=3.1
17
+ Requires-Dist: tomli>=2.0; python_version < "3.11"
18
+ Provides-Extra: ocr
19
+ Requires-Dist: pillow>=10; extra == "ocr"
20
+ Requires-Dist: pypdfium2>=4; extra == "ocr"
21
+ Provides-Extra: tables
22
+ Requires-Dist: pdfplumber>=0.11; extra == "tables"
23
+ Requires-Dist: pypdfium2>=4.18; extra == "tables"
24
+ Provides-Extra: rerank
25
+ Requires-Dist: sentence-transformers>=3; extra == "rerank"
26
+ Provides-Extra: office
27
+ Requires-Dist: xlrd>=2.0; extra == "office"
28
+ Requires-Dist: python-pptx>=1.0; extra == "office"
29
+ Provides-Extra: test
30
+ Requires-Dist: pytest>=8; extra == "test"
31
+ Requires-Dist: reportlab>=4; extra == "test"
32
+ Requires-Dist: python-docx>=1.1; extra == "test"
33
+ Requires-Dist: pillow>=10; extra == "test"
34
+ Requires-Dist: pdfplumber>=0.11; extra == "test"
35
+ Requires-Dist: pypdfium2>=4.18; extra == "test"
36
+
37
+ # ru-corpus-kit
38
+
39
+ > Обзор проекта, быстрый старт и лицензии — в корневом [README](../../README.md) ([English](../../README.en.md), [中文](../../README.zh.md)).
40
+
41
+ Ядро инструментов русского корпуса документов: индексация (PDF, сканы, DOCX, XLSX…), поиск BM25 по леммам,
42
+ таблицы с графами и годами, точные числа, агрегаты. Консольная команда — `ru-corpus`. Каждый ответ —
43
+ JSON с документом, страницей и якорем, либо честное «в корпусе нет».
44
+
45
+ Ядро не привязано к отрасли: отраслевое (классы таблиц, уровни, энергетические единицы, словарь
46
+ сокращений) подключается профилем (`[profile]` в `corpus.toml`); в комплекте профиль `tso_disclosure`.
47
+
48
+ ## Установка
49
+
50
+ Нужен Python 3.10+.
51
+
52
+ ```bash
53
+ pip install -e packages/ru-corpus-kit # ядро: pymorphy3, openpyxl
54
+ pip install -e "packages/ru-corpus-kit[tables]" # + таблицы PDF с сеткой и широкие таблицы (pdfplumber, pypdfium2)
55
+ pip install -e "packages/ru-corpus-kit[ocr]" # + OCR сканов (Pillow, pypdfium2); в системе нужен tesseract с языком rus
56
+ pip install -e "packages/ru-corpus-kit[rerank]" # + кросс-энкодер (sentence-transformers) для --rerank
57
+ pip install -e "packages/ru-corpus-kit[office]" # + .xls и .pptx без LibreOffice (xlrd, python-pptx)
58
+ ```
59
+
60
+ Лицензии: все зависимости, включая extras, пермиссивные — MIT, BSD, Apache-2.0 (см. [THIRD_PARTY_LICENSES.md](../../THIRD_PARTY_LICENSES.md)).
61
+
62
+ Системные программы: `pdftotext` из poppler (если его нет, текст PDF берёт pdfplumber), `tesseract` для сканов
63
+ (`brew install poppler tesseract tesseract-lang` / `apt install poppler-utils tesseract-ocr tesseract-ocr-rus`).
64
+
65
+ ## Быстрый старт
66
+
67
+ ```bash
68
+ cd мой-проект
69
+ ru-corpus init --root ./документы --prefix "корпус/" # создаёт corpus.toml
70
+ ru-corpus index # реестр -> текст -> OCR -> леммы -> таблицы -> bm25
71
+ ru-corpus status # что в индексе и что устарело
72
+ ```
73
+
74
+ `ru-corpus index` инкрементален: у каждого документа есть sha256; неизменённые файлы не пересчитываются,
75
+ изменённые проходят все стадии заново, удалённые убираются из индекса, копии с тем же sha256 не дублируются.
76
+ Прерванный запуск продолжается с того места, где остановился. Ключи: `--no-ocr` (пропустить сканы),
77
+ `--force` (пересобрать всё), `--stages text,lemma` (только указанные стадии).
78
+
79
+ ## Команды
80
+
81
+ Все команды печатают один JSON-объект. Конфиг берётся из `--config`, переменной `RU_CORPUS_CONFIG`
82
+ или ближайшего `corpus.toml` выше по папкам.
83
+
84
+ ```bash
85
+ ru-corpus search "выручка от передачи электроэнергии" --n 5 # доказательства: file, page, section, snippet
86
+ ru-corpus search "1 234 567,89" # запрос-число: поиск по всем страницам, пробелы разрядов не мешают
87
+ ru-corpus page d0001 1 # точный текст страницы + sha256 + origin
88
+ ru-corpus number d0001 1 "1 234 567,89" # стоит ли число дословно на странице
89
+ ru-corpus table --q "Потери электроэнергии" --year 2024 # ячейки таблиц: значение, единица, год, якорь «стр., таблица, строка, графа»
90
+ ru-corpus table --q "Ставка на содержание" --level СН2 --doc d0001 --page 3 # уровни — из профиля
91
+ ru-corpus aggregate d0003 --column "Мощность" --page "Реестр" # сумма/число/среднее/мин/макс; «Итого» сверяется, а не суммируется
92
+ ru-corpus aggregate d0003 --column "Стоимость" --column2 "Мощность" # отношение сумм
93
+ ru-corpus aggregate d0003 --column "Мощность" --where "Наименование~Подстанция"
94
+ ru-corpus doc d0001 # карточка: год и реквизиты акта из текста шапки
95
+ ru-corpus doc --find "отчёт 2024" # поиск документа по названию
96
+ ru-corpus calc "1 234,5 + 0,25 - 10" --digits 2 # точная десятичная арифметика
97
+ ```
98
+
99
+ Пример ответа `search` (демо-данные):
100
+
101
+ ```json
102
+ {"ok": true, "q": "выручка от передачи электроэнергии", "verdict": "есть доказательства",
103
+ "evidence": [{"doc": "d0001", "file": "корпус/reports/otchet_2024.pdf", "page": "1", "section": "основной текст",
104
+ "sources": ["bm25", "fts"], "snippet": "…Выручка от передачи электроэнергии составила 1 234 567,89 тыс. руб.…"}],
105
+ "facts": [], "scope": "all", "note": "поиск по всему индексу"}
106
+ ```
107
+
108
+ Ловушка (вопрос, ответа на который нет в корпусе) возвращает `"verdict": "в корпусе нет"` с пустыми
109
+ `evidence` и сигналами отказа (`signals`): ответ без доказательства не выдаётся.
110
+
111
+ ### Как устроен поиск
112
+
113
+ Две ветки: FTS5 по леммам страниц и BM25 по фрагментам (окно 96 токенов, перекрытие 16). Запрос — OR по
114
+ леммам с префиксом и синонимами из словаря. Ветки сливаются взвешиванием RRF по документам. Ответ «в корпусе
115
+ нет», когда обе ветки ниже порогов (`fts_coverage`, `bm25_best_doc`, `bm25_miss` в `[search]`).
116
+ `--rerank` (extras `[rerank]`) переупорядочивает фрагменты кросс-энкодером.
117
+
118
+ ## corpus.toml
119
+
120
+ ```toml
121
+ [corpus]
122
+ root = "документы" # каталог с документами; относительные пути — от папки с corpus.toml
123
+ source_prefix = "корпус/" # префикс ссылок в выводе: file и origin = префикс + относительный путь
124
+
125
+ [index]
126
+ dir = ".ru-corpus" # kb.sqlite, bm25.sqlite, registry.csv
127
+ registry = [] # готовые реестры CSV (id, rel_path, title, section, type, year, ext, sha256)
128
+ archive_registry = [] # реестры документов из архивов (в карточке from_archive = true)
129
+ # kb = "..."; bm25 = "..." # пути к уже построенным базам
130
+ extensions = [".pdf", ".docx", ".xlsx", ".xlsm", ".xls", ".pptx", ".doc", ".txt", ".md", ".csv", ".json"]
131
+ exclude = ["**/.git/**", "**/node_modules/**"]
132
+ max_size_mb = 0 # 0 — без ограничения
133
+ ocr = true # сканы; нужен tesseract и extras [ocr]
134
+ ocr_dpi = 300
135
+ ocr_psm = 4
136
+ ocr_workers = 4
137
+ ocr_langs = "rus+eng"
138
+ tables = true # таблицы PDF с сеткой (extras [tables])
139
+ wide_tables = true # широкие альбомные таблицы по координатам (extras [tables])
140
+ bm25_window = 96
141
+ bm25_overlap = 16
142
+
143
+ [search]
144
+ synonyms = "" # TOML-файл со словарём сокращений; пусто — словарь профиля
145
+ fts_coverage = 0.75
146
+ bm25_best_doc = 0.6
147
+ bm25_miss = 0.2
148
+ derived_sections = [] # разделы (первая папка) производного слоя: в выдаче ниже первичных
149
+ rerank = false
150
+
151
+ [profile]
152
+ name = "" # tso_disclosure | путь к каталогу профиля | пусто — только ядро
153
+ ```
154
+
155
+ Словарь синонимов — TOML: сокращение (строчными) и фразы, на которые оно раскрывается:
156
+
157
+ ```toml
158
+ [synonyms]
159
+ "тп" = ["технологическое присоединение", "трансформаторная подстанция"]
160
+ ```
161
+
162
+ ## Профили
163
+
164
+ Профиль — каталог с `profile.toml` (и файлами рядом). В нём то, чего нет в ядре: словарь сокращений
165
+ (`synonyms`), слова для правки OCR (`ocr_words`), шаблон номера акта (`act_no`), уровни в заголовках таблиц
166
+ (`[[levels]]`; «Всего» — в ядре), энергетические единицы измерения (`extra_units`), классы документов
167
+ (`[[classes]]`: год таких таблиц берётся из названия документа). Встроенный профиль
168
+ `tso_disclosure` — раскрытие информации сетевой организацией: баланс электроэнергии и мощности, потери,
169
+ структура затрат по форме 1831-э, предложение о ценах; уровни ВН/СН1/СН2/НН; единицы МВт, МВА, кВт·ч.
170
+ Свой профиль: `[profile] name = "путь/к/каталогу"`.
171
+
172
+ ## Открыть уже построенный индекс без переиндексации
173
+
174
+ Схема `kb.sqlite` и `bm25.sqlite` совпадает со схемой прототипа, на котором ядро выросло, поэтому такой
175
+ индекс открывается через `corpus.toml`:
176
+
177
+ ```toml
178
+ [corpus]
179
+ root = "/путь/к/корпусу"
180
+ source_prefix = "корпус/"
181
+ [index]
182
+ kb = "/путь/к/kb.sqlite"
183
+ bm25 = "/путь/к/bm25.sqlite"
184
+ registry = ["/путь/к/реестру.csv"]
185
+ ```
186
+
187
+ Индекс, построенный не `ru-corpus index` (нет таблицы `kit_meta`), открывается только на чтение;
188
+ `ru-corpus index` на нём откажет, чтобы не испортить его.
189
+
190
+ ## Что в индексе
191
+
192
+ - `docs`, `pages` (страница = страница PDF, лист XLSX, слайд PPTX; таблицы PDF — «N/тK» в `table_raw`);
193
+ - `pages_lemma` + FTS5 по леммам; разделы («Приложение № 3», «Таблица 2») протягиваются на следующие страницы;
194
+ - `docs_meta_text` — год периода, дата и номер акта из текста шапки, а не из имени файла;
195
+ - `table_cells` — ячейки таблиц: `label`, `year`, `level`, `half`, `unit`, `header` (путь графы), `value`, `raw`;
196
+ `method = 'bbox'` — широкие таблицы, восстановленные по координатам;
197
+ - `bm25.sqlite` — фрагменты и FTS5.
198
+
199
+ ## Ограничения
200
+
201
+ - Скан читается tesseract: цифры после OCR проверяйте командой `page` (поле `ocr`) и по оригиналу.
202
+ - В таблицах с графой, объединённой по вертикали («Итого» над строкой лет), графа наследует год соседней
203
+ (приём протяжки шапки): год такой графы смотрите по якорю, а не по полю `year`.
204
+ - Запрос из одних аббревиатур, которых нет в тексте, даст «в корпусе нет»: синонимы расширяют запрос,
205
+ но порог покрытия считается по словам самого вопроса.
206
+ - `.doc` читается через LibreOffice (если установлен), `.xls` — через xlrd или LibreOffice.
207
+
208
+ ## Тесты
209
+
210
+ ```bash
211
+ pip install -e "packages/ru-corpus-kit[tables,ocr,test]"
212
+ pytest packages/ru-corpus-kit/tests
213
+ ```
214
+
215
+ Корпус для тестов генерируется в фикстуре: вымышленная организация «АО «Демо-Сеть»», вымышленные числа
216
+ (PDF — reportlab со шрифтом DejaVu Sans из `tests/fonts/`, XLSX — openpyxl, DOCX — python-docx, скан — картинка с текстом, нарисованная Pillow). Тест OCR пропускается без tesseract.
217
+
218
+ Лицензия — Apache-2.0.
@@ -0,0 +1,182 @@
1
+ # ru-corpus-kit
2
+
3
+ > Обзор проекта, быстрый старт и лицензии — в корневом [README](../../README.md) ([English](../../README.en.md), [中文](../../README.zh.md)).
4
+
5
+ Ядро инструментов русского корпуса документов: индексация (PDF, сканы, DOCX, XLSX…), поиск BM25 по леммам,
6
+ таблицы с графами и годами, точные числа, агрегаты. Консольная команда — `ru-corpus`. Каждый ответ —
7
+ JSON с документом, страницей и якорем, либо честное «в корпусе нет».
8
+
9
+ Ядро не привязано к отрасли: отраслевое (классы таблиц, уровни, энергетические единицы, словарь
10
+ сокращений) подключается профилем (`[profile]` в `corpus.toml`); в комплекте профиль `tso_disclosure`.
11
+
12
+ ## Установка
13
+
14
+ Нужен Python 3.10+.
15
+
16
+ ```bash
17
+ pip install -e packages/ru-corpus-kit # ядро: pymorphy3, openpyxl
18
+ pip install -e "packages/ru-corpus-kit[tables]" # + таблицы PDF с сеткой и широкие таблицы (pdfplumber, pypdfium2)
19
+ pip install -e "packages/ru-corpus-kit[ocr]" # + OCR сканов (Pillow, pypdfium2); в системе нужен tesseract с языком rus
20
+ pip install -e "packages/ru-corpus-kit[rerank]" # + кросс-энкодер (sentence-transformers) для --rerank
21
+ pip install -e "packages/ru-corpus-kit[office]" # + .xls и .pptx без LibreOffice (xlrd, python-pptx)
22
+ ```
23
+
24
+ Лицензии: все зависимости, включая extras, пермиссивные — MIT, BSD, Apache-2.0 (см. [THIRD_PARTY_LICENSES.md](../../THIRD_PARTY_LICENSES.md)).
25
+
26
+ Системные программы: `pdftotext` из poppler (если его нет, текст PDF берёт pdfplumber), `tesseract` для сканов
27
+ (`brew install poppler tesseract tesseract-lang` / `apt install poppler-utils tesseract-ocr tesseract-ocr-rus`).
28
+
29
+ ## Быстрый старт
30
+
31
+ ```bash
32
+ cd мой-проект
33
+ ru-corpus init --root ./документы --prefix "корпус/" # создаёт corpus.toml
34
+ ru-corpus index # реестр -> текст -> OCR -> леммы -> таблицы -> bm25
35
+ ru-corpus status # что в индексе и что устарело
36
+ ```
37
+
38
+ `ru-corpus index` инкрементален: у каждого документа есть sha256; неизменённые файлы не пересчитываются,
39
+ изменённые проходят все стадии заново, удалённые убираются из индекса, копии с тем же sha256 не дублируются.
40
+ Прерванный запуск продолжается с того места, где остановился. Ключи: `--no-ocr` (пропустить сканы),
41
+ `--force` (пересобрать всё), `--stages text,lemma` (только указанные стадии).
42
+
43
+ ## Команды
44
+
45
+ Все команды печатают один JSON-объект. Конфиг берётся из `--config`, переменной `RU_CORPUS_CONFIG`
46
+ или ближайшего `corpus.toml` выше по папкам.
47
+
48
+ ```bash
49
+ ru-corpus search "выручка от передачи электроэнергии" --n 5 # доказательства: file, page, section, snippet
50
+ ru-corpus search "1 234 567,89" # запрос-число: поиск по всем страницам, пробелы разрядов не мешают
51
+ ru-corpus page d0001 1 # точный текст страницы + sha256 + origin
52
+ ru-corpus number d0001 1 "1 234 567,89" # стоит ли число дословно на странице
53
+ ru-corpus table --q "Потери электроэнергии" --year 2024 # ячейки таблиц: значение, единица, год, якорь «стр., таблица, строка, графа»
54
+ ru-corpus table --q "Ставка на содержание" --level СН2 --doc d0001 --page 3 # уровни — из профиля
55
+ ru-corpus aggregate d0003 --column "Мощность" --page "Реестр" # сумма/число/среднее/мин/макс; «Итого» сверяется, а не суммируется
56
+ ru-corpus aggregate d0003 --column "Стоимость" --column2 "Мощность" # отношение сумм
57
+ ru-corpus aggregate d0003 --column "Мощность" --where "Наименование~Подстанция"
58
+ ru-corpus doc d0001 # карточка: год и реквизиты акта из текста шапки
59
+ ru-corpus doc --find "отчёт 2024" # поиск документа по названию
60
+ ru-corpus calc "1 234,5 + 0,25 - 10" --digits 2 # точная десятичная арифметика
61
+ ```
62
+
63
+ Пример ответа `search` (демо-данные):
64
+
65
+ ```json
66
+ {"ok": true, "q": "выручка от передачи электроэнергии", "verdict": "есть доказательства",
67
+ "evidence": [{"doc": "d0001", "file": "корпус/reports/otchet_2024.pdf", "page": "1", "section": "основной текст",
68
+ "sources": ["bm25", "fts"], "snippet": "…Выручка от передачи электроэнергии составила 1 234 567,89 тыс. руб.…"}],
69
+ "facts": [], "scope": "all", "note": "поиск по всему индексу"}
70
+ ```
71
+
72
+ Ловушка (вопрос, ответа на который нет в корпусе) возвращает `"verdict": "в корпусе нет"` с пустыми
73
+ `evidence` и сигналами отказа (`signals`): ответ без доказательства не выдаётся.
74
+
75
+ ### Как устроен поиск
76
+
77
+ Две ветки: FTS5 по леммам страниц и BM25 по фрагментам (окно 96 токенов, перекрытие 16). Запрос — OR по
78
+ леммам с префиксом и синонимами из словаря. Ветки сливаются взвешиванием RRF по документам. Ответ «в корпусе
79
+ нет», когда обе ветки ниже порогов (`fts_coverage`, `bm25_best_doc`, `bm25_miss` в `[search]`).
80
+ `--rerank` (extras `[rerank]`) переупорядочивает фрагменты кросс-энкодером.
81
+
82
+ ## corpus.toml
83
+
84
+ ```toml
85
+ [corpus]
86
+ root = "документы" # каталог с документами; относительные пути — от папки с corpus.toml
87
+ source_prefix = "корпус/" # префикс ссылок в выводе: file и origin = префикс + относительный путь
88
+
89
+ [index]
90
+ dir = ".ru-corpus" # kb.sqlite, bm25.sqlite, registry.csv
91
+ registry = [] # готовые реестры CSV (id, rel_path, title, section, type, year, ext, sha256)
92
+ archive_registry = [] # реестры документов из архивов (в карточке from_archive = true)
93
+ # kb = "..."; bm25 = "..." # пути к уже построенным базам
94
+ extensions = [".pdf", ".docx", ".xlsx", ".xlsm", ".xls", ".pptx", ".doc", ".txt", ".md", ".csv", ".json"]
95
+ exclude = ["**/.git/**", "**/node_modules/**"]
96
+ max_size_mb = 0 # 0 — без ограничения
97
+ ocr = true # сканы; нужен tesseract и extras [ocr]
98
+ ocr_dpi = 300
99
+ ocr_psm = 4
100
+ ocr_workers = 4
101
+ ocr_langs = "rus+eng"
102
+ tables = true # таблицы PDF с сеткой (extras [tables])
103
+ wide_tables = true # широкие альбомные таблицы по координатам (extras [tables])
104
+ bm25_window = 96
105
+ bm25_overlap = 16
106
+
107
+ [search]
108
+ synonyms = "" # TOML-файл со словарём сокращений; пусто — словарь профиля
109
+ fts_coverage = 0.75
110
+ bm25_best_doc = 0.6
111
+ bm25_miss = 0.2
112
+ derived_sections = [] # разделы (первая папка) производного слоя: в выдаче ниже первичных
113
+ rerank = false
114
+
115
+ [profile]
116
+ name = "" # tso_disclosure | путь к каталогу профиля | пусто — только ядро
117
+ ```
118
+
119
+ Словарь синонимов — TOML: сокращение (строчными) и фразы, на которые оно раскрывается:
120
+
121
+ ```toml
122
+ [synonyms]
123
+ "тп" = ["технологическое присоединение", "трансформаторная подстанция"]
124
+ ```
125
+
126
+ ## Профили
127
+
128
+ Профиль — каталог с `profile.toml` (и файлами рядом). В нём то, чего нет в ядре: словарь сокращений
129
+ (`synonyms`), слова для правки OCR (`ocr_words`), шаблон номера акта (`act_no`), уровни в заголовках таблиц
130
+ (`[[levels]]`; «Всего» — в ядре), энергетические единицы измерения (`extra_units`), классы документов
131
+ (`[[classes]]`: год таких таблиц берётся из названия документа). Встроенный профиль
132
+ `tso_disclosure` — раскрытие информации сетевой организацией: баланс электроэнергии и мощности, потери,
133
+ структура затрат по форме 1831-э, предложение о ценах; уровни ВН/СН1/СН2/НН; единицы МВт, МВА, кВт·ч.
134
+ Свой профиль: `[profile] name = "путь/к/каталогу"`.
135
+
136
+ ## Открыть уже построенный индекс без переиндексации
137
+
138
+ Схема `kb.sqlite` и `bm25.sqlite` совпадает со схемой прототипа, на котором ядро выросло, поэтому такой
139
+ индекс открывается через `corpus.toml`:
140
+
141
+ ```toml
142
+ [corpus]
143
+ root = "/путь/к/корпусу"
144
+ source_prefix = "корпус/"
145
+ [index]
146
+ kb = "/путь/к/kb.sqlite"
147
+ bm25 = "/путь/к/bm25.sqlite"
148
+ registry = ["/путь/к/реестру.csv"]
149
+ ```
150
+
151
+ Индекс, построенный не `ru-corpus index` (нет таблицы `kit_meta`), открывается только на чтение;
152
+ `ru-corpus index` на нём откажет, чтобы не испортить его.
153
+
154
+ ## Что в индексе
155
+
156
+ - `docs`, `pages` (страница = страница PDF, лист XLSX, слайд PPTX; таблицы PDF — «N/тK» в `table_raw`);
157
+ - `pages_lemma` + FTS5 по леммам; разделы («Приложение № 3», «Таблица 2») протягиваются на следующие страницы;
158
+ - `docs_meta_text` — год периода, дата и номер акта из текста шапки, а не из имени файла;
159
+ - `table_cells` — ячейки таблиц: `label`, `year`, `level`, `half`, `unit`, `header` (путь графы), `value`, `raw`;
160
+ `method = 'bbox'` — широкие таблицы, восстановленные по координатам;
161
+ - `bm25.sqlite` — фрагменты и FTS5.
162
+
163
+ ## Ограничения
164
+
165
+ - Скан читается tesseract: цифры после OCR проверяйте командой `page` (поле `ocr`) и по оригиналу.
166
+ - В таблицах с графой, объединённой по вертикали («Итого» над строкой лет), графа наследует год соседней
167
+ (приём протяжки шапки): год такой графы смотрите по якорю, а не по полю `year`.
168
+ - Запрос из одних аббревиатур, которых нет в тексте, даст «в корпусе нет»: синонимы расширяют запрос,
169
+ но порог покрытия считается по словам самого вопроса.
170
+ - `.doc` читается через LibreOffice (если установлен), `.xls` — через xlrd или LibreOffice.
171
+
172
+ ## Тесты
173
+
174
+ ```bash
175
+ pip install -e "packages/ru-corpus-kit[tables,ocr,test]"
176
+ pytest packages/ru-corpus-kit/tests
177
+ ```
178
+
179
+ Корпус для тестов генерируется в фикстуре: вымышленная организация «АО «Демо-Сеть»», вымышленные числа
180
+ (PDF — reportlab со шрифтом DejaVu Sans из `tests/fonts/`, XLSX — openpyxl, DOCX — python-docx, скан — картинка с текстом, нарисованная Pillow). Тест OCR пропускается без tesseract.
181
+
182
+ Лицензия — Apache-2.0.
@@ -0,0 +1,52 @@
1
+ [build-system]
2
+ requires = ["setuptools>=64"]
3
+ build-backend = "setuptools.build_meta"
4
+
5
+ [project]
6
+ name = "ru-corpus-kit"
7
+ version = "0.1.0"
8
+ description = "Русский поиск и проверяемая аналитика по корпусу документов: индексация, поиск BM25 по леммам, таблицы, числа"
9
+ readme = "README.md"
10
+ requires-python = ">=3.10"
11
+ license = { text = "Apache-2.0" }
12
+ authors = [{ name = "ru-corpus contributors" }]
13
+ keywords = ["russian", "search", "bm25", "corpus", "ocr", "tables"]
14
+ classifiers = [
15
+ "License :: OSI Approved :: Apache Software License",
16
+ "Programming Language :: Python :: 3",
17
+ "Natural Language :: Russian",
18
+ ]
19
+ dependencies = [
20
+ "pymorphy3>=1.2",
21
+ "openpyxl>=3.1",
22
+ "tomli>=2.0; python_version < '3.11'",
23
+ ]
24
+
25
+ [project.optional-dependencies]
26
+ # OCR сканов: tesseract (rus) должен стоять в системе; здесь только Python-часть.
27
+ # Растеризация страниц — pdftoppm (poppler), а без него pypdfium2 (Apache-2.0 / BSD-3-Clause)
28
+ ocr = ["pillow>=10", "pypdfium2>=4"]
29
+ # таблицы PDF: сетки и широкие таблицы по координатам (pdfplumber, MIT; текст и координаты слов — pypdfium2)
30
+ tables = ["pdfplumber>=0.11", "pypdfium2>=4.18"]
31
+ # повторное ранжирование кросс-энкодером
32
+ rerank = ["sentence-transformers>=3"]
33
+ # .xls и .pptx без LibreOffice
34
+ office = ["xlrd>=2.0", "python-pptx>=1.0"]
35
+ test = ["pytest>=8", "reportlab>=4", "python-docx>=1.1", "pillow>=10", "pdfplumber>=0.11", "pypdfium2>=4.18"]
36
+
37
+ [project.scripts]
38
+ ru-corpus = "ru_corpus_kit.cli:main"
39
+
40
+ [tool.setuptools.packages.find]
41
+ where = ["src"]
42
+
43
+ [tool.setuptools.package-data]
44
+ ru_corpus_kit = ["profiles/*/*"]
45
+
46
+ [tool.pytest.ini_options]
47
+ testpaths = ["tests"]
48
+ addopts = "-q"
49
+
50
+ [project.urls]
51
+ Homepage = "https://github.com/ru-data-analysis/ru-corpus"
52
+ Issues = "https://github.com/ru-data-analysis/ru-corpus/issues"
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
@@ -0,0 +1,3 @@
1
+ """ru-corpus-kit: ядро инструментов русского корпуса документов."""
2
+
3
+ __version__ = "0.1.0"
@@ -0,0 +1,157 @@
1
+ # -*- coding: utf-8 -*-
2
+ """Пакет доказательств для ответа: гибрид двух веток поиска + ячейки таблиц.
3
+
4
+ Ответ не пишется без доказательства. Каждое доказательство — файл источника (с префиксом из
5
+ corpus.toml), страница, раздел («Приложение № 1», «Таблица 1», лист), ветки поиска и фрагмент.
6
+ Ветки:
7
+ fts — FTS5 по леммам страниц (pages_lemma_fts), OR по словам с синонимами и префиксом;
8
+ bm25 — BM25 по фрагментам (bm25.sqlite).
9
+ Слияние — RRF по документам. Если обе ветки отказали (FTS: покрытие лемм < порога; BM25: лучший
10
+ документ ниже порога или доля отсутствующих слов >= порога) — ответ «в корпусе нет».
11
+ Точная цифра из таблицы — отдельной строкой из table_cells с якорем «стр. N, таблица K, строка r, графа …».
12
+ """
13
+ from __future__ import annotations
14
+
15
+ import re
16
+ import sqlite3
17
+
18
+ from . import norm
19
+
20
+ RRF_K = 60
21
+
22
+
23
+ def fts_run(db, q, synonyms, limit=200):
24
+ """-> (doc_rank, page_hits[(doc, page)], coverage). Режим «леммы + синонимы»."""
25
+ match = norm.fts_query(q, expand=True, operator="or", synonyms=synonyms)
26
+ if not match:
27
+ return [], [], 0.0
28
+ try:
29
+ hits = db.execute("SELECT f.doc_id, f.page FROM pages_lemma_fts f WHERE pages_lemma_fts MATCH ? "
30
+ "ORDER BY bm25(pages_lemma_fts) LIMIT ?", (match, limit)).fetchall()
31
+ except sqlite3.OperationalError:
32
+ hits = []
33
+ docs = list(dict.fromkeys(d for d, _p in hits))
34
+ return docs, hits, fts_coverage(db, q, hits[:10])
35
+
36
+
37
+ def fts_coverage(db, q, hits):
38
+ """Доля лемм запроса, найденных на лучшей из первых страниц (0..1)."""
39
+ lem = [norm.lemma(t) for t in norm.tokens(q)]
40
+ lem = [x for x in dict.fromkeys(lem) if x]
41
+ if not lem or not hits:
42
+ return 0.0
43
+ best = 0.0
44
+ for d, p in hits:
45
+ row = db.execute("SELECT text_lemma FROM pages_lemma WHERE doc_id=? AND page=?", (d, p)).fetchone()
46
+ if not row:
47
+ continue
48
+ words = set(row[0].split())
49
+ got = sum(1 for x in lem if x in words or any(w.startswith(x) for w in words
50
+ if len(x) >= 4 and w[:2] == x[:2]))
51
+ best = max(best, got / len(lem))
52
+ return best
53
+
54
+
55
+ def norm_hit_page(p):
56
+ """'12/т1' -> ('12', 'таблица 1'); [5, 5] -> ('5', None), [5, 7] -> ('5–7', None)."""
57
+ if isinstance(p, (list, tuple)):
58
+ if not p:
59
+ return ("?", None)
60
+ a, b = (list(p) + [p[0]])[:2]
61
+ return (str(a) if a == b else f"{a}–{b}", None)
62
+ m = re.match(r"^(\d+)/т(\d+)$", str(p))
63
+ return (m.group(1), f"таблица {m.group(2)}") if m else (str(p), None)
64
+
65
+
66
+ def fuse(fts_res, bm_res, k=RRF_K):
67
+ """RRF по документам + единый список доказательств без дублей (документ + страница)."""
68
+ score = {}
69
+ for docs in (fts_res[0], bm_res[0]):
70
+ for i, d in enumerate(docs[:20]):
71
+ score[d] = score.get(d, 0.0) + 1.0 / (k + i + 1)
72
+ docs = sorted(score, key=lambda d: -score[d])
73
+ ev, seen = [], {}
74
+ for src, hits in (("fts", fts_res[1][:10]), ("bm25", bm_res[1][:10])):
75
+ for d, p in hits:
76
+ pg, extra = norm_hit_page(p)
77
+ key = (d, pg.split("–")[0])
78
+ if key in seen:
79
+ seen[key]["sources"].add(src)
80
+ continue
81
+ e = {"doc": d, "page": pg, "extra": extra, "sources": {src}, "raw_page": p}
82
+ seen[key] = e
83
+ ev.append(e)
84
+ rank = {d: i for i, d in enumerate(docs)}
85
+ ev.sort(key=lambda e: rank.get(e["doc"], 999))
86
+ return docs, ev
87
+
88
+
89
+ def section_of(db, doc, page):
90
+ r = db.execute("SELECT section FROM pages_lemma WHERE doc_id=? AND page=?", (doc, str(page))).fetchone()
91
+ return (r[0] if r and r[0] else None)
92
+
93
+
94
+ def snippet(db, doc, page, q, width=160):
95
+ r = db.execute("SELECT text FROM pages WHERE doc_id=? AND page=?", (doc, str(page))).fetchone()
96
+ if not r:
97
+ return ""
98
+ t = re.sub(r"\s+", " ", r[0])
99
+ lem = {norm.lemma(w) for w in norm.tokens(q)}
100
+ for m in norm.TOKEN_RE.finditer(t):
101
+ if norm.lemma(m.group(0)) in lem:
102
+ return "…" + t[max(0, m.start() - width // 2): m.end() + width // 2] + "…"
103
+ return t[:width] + "…"
104
+
105
+
106
+ def table_facts(db, q, docs, dims, limit=3):
107
+ """Ячейки таблиц: год и уровень из вопроса, подпись — по словам вопроса."""
108
+ if not docs or not db.execute("SELECT name FROM sqlite_master WHERE name='table_cells'").fetchone():
109
+ return []
110
+ y = re.search(r"\b(20[0-4]\d)\b", q)
111
+ lv = next((n for n, rx in dims.level_patterns if n != "Всего" and re.search(rx, q)), None)
112
+ hf = "II" if re.search(r"втор\w* полугоди|II полугоди", q, re.I) else \
113
+ ("I" if re.search(r"перв\w* полугоди|\bI полугоди", q, re.I) else None)
114
+ words = [w for w in norm.tokens(q) if len(w) > 4 and not w.isdigit()][:4]
115
+ if not words or not (y or lv):
116
+ return []
117
+ sql = ("SELECT doc_id, page, tab, row, header, label, year, level, half, unit, raw FROM table_cells "
118
+ "WHERE doc_id IN (%s)" % ",".join("?" * len(docs)))
119
+ args = list(docs)
120
+ for w in words:
121
+ sql += " AND lower(label) LIKE ?"
122
+ args.append("%" + w[:max(4, len(w) - 2)] + "%")
123
+ for col, v in (("year", int(y.group(1)) if y else None), ("level", lv), ("half", hf)):
124
+ if v is not None:
125
+ sql += f" AND {col}=?"
126
+ args.append(v)
127
+ return db.execute(sql + " LIMIT ?", args + [limit]).fetchall()
128
+
129
+
130
+ def answer(kit, q, n=5, primary_first=True, rerank=None):
131
+ """Доказательства по вопросу или «в корпусе нет»."""
132
+ cfg, db = kit.cfg, kit.db
133
+ fd, fh, cov = fts_run(db, q, cfg.synonyms)
134
+ rr = cfg.rerank if rerank is None else rerank
135
+ kd, kh, (b, miss), _v, _nh = kit.bm.branch(q, rerank=rr)
136
+ docs, ev = fuse((fd, fh), (kd, kh))
137
+ f_ab = (not fd) or cov < cfg.fts_coverage
138
+ k_ab = (not kd) or b is None or b < cfg.bm25_best_doc or miss >= cfg.bm25_miss
139
+ if f_ab and k_ab:
140
+ return {"q": q, "verdict": "в корпусе нет", "evidence": [], "facts": [],
141
+ "signals": {"fts_coverage": round(cov, 2), "bm25_best_doc": b, "bm25_missing": round(miss, 2)}}
142
+ reg = kit.registry()
143
+ if primary_first and cfg.derived_sections:
144
+ # первичные документы — выше производного слоя (отчёты, своды): ссылка идёт на первичный файл
145
+ ev = sorted(ev, key=lambda e: reg.get(e["doc"], {}).get("section") in cfg.derived_sections)
146
+ out = []
147
+ for e in ev[:n]:
148
+ pg = e["page"].split("–")[0]
149
+ raw = e["raw_page"] if not isinstance(e["raw_page"], list) else pg
150
+ sec = section_of(db, e["doc"], raw)
151
+ sec = sec or e["extra"] or ("лист «%s»" % pg if not pg.isdigit() else "основной текст")
152
+ out.append({"doc": e["doc"], "file": kit.file_of(e["doc"]), "page": e["page"], "section": sec,
153
+ "sources": sorted(e["sources"]), "snippet": snippet(db, e["doc"], raw, q)})
154
+ facts = [{"doc": f[0], "file": kit.file_of(f[0]),
155
+ "anchor": f"стр. {f[1]}, таблица {f[2]}, строка {f[3]}, графа «{f[4]}»",
156
+ "label": f[5], "value": f[10], "unit": f[9]} for f in table_facts(db, q, docs[:5], kit.dims)]
157
+ return {"q": q, "verdict": "есть доказательства", "evidence": out, "facts": facts}