-
✓
Управление через Spec-Driven Development (SDD): Любое функциональное изменение начинается с формальных спецификаций (
specs/<capability>/spec.md) с трассируемыми требованиями (REQ-*), валидируемыми автоматическими регрессионными тестами. -
✓
Однонаправленная слоистая архитектура: Полное соответствие правилам
docs/architecture.md. CLI-раннер изолирован от ядра распознавания, адаптеры моделей абстрагированы, внешние ресурсы инжектируются извне. -
✓
Отказоустойчивый каскад моделей: Гибридная поддержка моделей OpenRouter: первичные бесплатные квоты (
:free) с автоматическим переключением на гарантированные платные шлюзы при насыщении лимитов или 429 ошибках. -
✓
Изоляция контекста и управление памятью: Каждая страница обрабатывается в отдельной turn-сессии без накопления контекста диалога. Рендеринг и сохранение чанками по 20 страниц предотвращают утечки оперативной памяти.
-
✓
Гарантия целостности при прерывании (SIGINT): Перехватчик сигнала прерывания атомарно удаляет неполные выходные файлы текущей страницы с кодом возврата 130, сохраняя 100% корректность ранее обработанных листов.
-
!
V-01: Отсутствие авторизации (Локальный запуск): Текущий CLI рассчитан на доверенную рабочую станцию с чтением ключей из
.env. При миграции на веб-сервер критически необходима интеграция Google OAuth 2.0 + TOTP 2FA. -
!
V-02: Ручной перезапуск при остановке на чертежах: При обнаружении нетекстовых графиков конвейер завершается с кодом 3. В веб-версии требуется интерактивное окно разрешения (пропуск, разметка, вырезание).
-
!
V-03: Лимиты OpenRouter на бесплатных тарифах: Высокая частота запросов на
nvidia/nemotron-3.5-super-vl:freeприводит к задержкам шлюза. Необходим пул запасных ключей и экспоненциальный бэкофф. -
!
V-04: Объем временного дискового пространства: Рендеринг сотен страниц в 150 DPI создает гигабайты временных изображений. Решение: стриминг в Google Drive и автоматическая ротация кэша.
| Правило | Формулировка инварианта | Механизм соблюдения в коде | Статус проверки |
|---|---|---|---|
C-01 |
Изоляция секретов | Ключи API загружаются через переменные окружения, запрещены в коде и репозитории | Соблюдено |
C-02 |
Трассируемость SDD | Каждое требование связано с приемочным тестом в tests/test_*.py |
Соблюдено |
C-03 |
Дословность текста | Запрет на галлюцинации, исправление опечаток оригинала и перевод кириллицы | Соблюдено |
C-04 |
Отказ от инструментов | OCR-сессия выполняется в изолированном контексте turn без внешних тулов | Соблюдено |
C-05 |
Защита чертежей | Аварийная остановка с кодом 3 при наличии схем/графиков для защиты от искажений | Соблюдено |
C-06 |
Атомарность очистки | Удаление незавершенных файлов при прерывании SIGINT (Ctrl+C) | Соблюдено |
Система следует строгому однонаправленному многослойному паттерну в соответствии с docs/architecture.md.
Внешние ресурсы (файловая система, LLM-модели, сетевой стек) изолированы и инжектируются извне. Ядро обработки полностью отвязано от интерфейсов входа.
Скрипт src/run_volumes.sh управляет пакетным последовательным выполнением томов с остановкой при первой ошибке (fail-fast).
Модуль src/pdf_image_ocr.py объединяет рендеринг через PyMuPDF, распознавание страниц, валидацию и парсинг артефактов.
Адаптер OpenRouterClient обеспечивает отказоустойчивый роутинг запросов с автоматическим переключением на резервные платные шлюзы.
Пошаговый цикл обработки каждой отдельной страницы дела через конвейер распознавания: рендеринг, детекция ошибок, повторные попытки, ветвление артефактов и атомарный откат.
Исходный PDF конвертируется по 20 листов в PNG и JPEG с разрешением 150 DPI. Чанкование предотвращает переполнение памяти процесса.
Паттерны фраз-отказов («I cannot read», «As an AI») или английский комментарий триггерят повторный запрос (до 3 раз) с автоматическим переключением шлюза.
Текст направляется в .txt, таблицы преобразуются в полноценный .xlsx с сохранением чисел, а фотографии вырезаются в отдельные JPG.
Каждая возможность системы представляет собой автономный модуль поведения с формальными критериями приемки WHEN / THEN и автоматизированным набором тестов pytest.
| Возможность | Файл спецификации | Ключевые требования (REQ) | Файл теста | Статус |
|---|---|---|---|---|
| text-ocr | specs/text-ocr/spec.md |
• R-text-ocr-01: Изолированная turn-сессия на страницу, без тулов, среднее усилие
• R-text-ocr-02: Дословная кириллическая транскрипция без перевода на английский
|
tests/test_text_ocr.py |
Реализовано |
| table-export | specs/table-export/spec.md |
• R-table-export-01: Табличные страницы не останавливают конвейер
• R-table-export-02: Создание файла
vol<V>_<P>.xlsx на каждую страницу с таблицей• R-table-export-03: Числовое форматирование ячеек; указатель таблицы в
.txt |
tests/test_table_export.py |
Реализовано |
| photo-handling | specs/photo-handling/spec.md |
• R-photo-handling-01: Фототаблицы не останавливают общий цикл
• R-photo-handling-02: Нарезка снимков в
page<P>_<N>.jpg по координатам• R-photo-handling-03: Транскрипция печатного текста и описание фото на русском языке
|
tests/test_photo_pages.py |
Реализовано |
| non-text-handling | specs/non-text-handling/spec.md |
• R-non-text-handling-01: Остановка с кодом 3 на чертежах, схемах и графиках
• R-non-text-handling-02: Штампы, печати и рукописные заметки транскрибируются как есть
|
tests/test_non_text_stop.py |
Реализовано |
| page-rendering | specs/page-rendering/spec.md |
• R-page-rendering-01: Рендеринг каждой страницы в PNG и JPEG с 150 DPI
• R-page-rendering-02: Группировка страниц по подкаталогам (макс. 20 на папку)
|
tests/test_text_ocr.py |
Реализовано |
| answer-retry | specs/answer-retry/spec.md |
• R-answer-retry-01: Детекция фраз-отказов, английских реплик и сбоев JSON
• R-answer-retry-02: До 3 попыток повторного запроса перед генерацией ошибки
|
tests/test_text_ocr.py |
Реализовано |
| interrupt-cleanup | specs/interrupt-cleanup/spec.md |
• R-interrupt-cleanup-01: SIGINT удаляет неполные выходные файлы с кодом 130
• R-interrupt-cleanup-02: Ранее завершенные страницы сохраняются без повреждений
|
tests/test_interrupt_cleanup.py |
Реализовано |
| volume-runner | specs/volume-runner/spec.md |
• R-volume-runner-01: Последовательная обработка диапазона FROM..TO
• R-volume-runner-02: Аварийная остановка при первой же ошибке (код 1 или 3)
• R-volume-runner-03: Проброс параметров CLI (
--resume, --engine) |
tests/test_volume_runner.py |
Реализовано |
| run-logging | specs/run-logging/spec.md |
• R-run-logging-01: Создание файла лога с меткой времени в каталоге
logs/• R-run-logging-02: Уровень INFO в консоль терминала, подробный DEBUG в файл
|
tests/test_text_ocr.py |
Реализовано |
Система предоставляет гибридную поддержку мультимодельных бэкендов. По умолчанию запросы идут в OpenRouter с нулевой стоимостью на бесплатных тарифах и автоматическим каскадным переключением на гарантированные платные шлюзы при лимитах частоты или 429 ответах.
| Идентификатор | Флаг CLI | Основной уровень (Бесплатный) | Резервный уровень (Платный) | Протокол и авторизация |
|---|---|---|---|---|
| nemotron По умолчанию | --engine nemotron |
nvidia/nemotron-3.5-super-vl:free |
nvidia/nemotron-3.5-super-vl (Платный) |
OpenRouter HTTP API via httpx (Bearer-токен) |
| gemma Альтернатива | --engine gemma |
google/gemma-3-27b-it:free |
google/gemma-3-27b-it (Платный) |
OpenRouter HTTP API via httpx (Bearer-токен) |
| claude Макс. точность | --engine claude |
claude-3-5-sonnet-20241022 |
Резерв недоступен (Прямой вызов) | Прямой SDK Anthropic (ANTHROPIC_API_KEY) |
- • Шаг 1: Отправка страницы на бесплатный шлюз (
:free). - • Шаг 2: При получении HTTP 429, 502, 503 или таймаута — немедленный повтор на платном шлюзе без
:free. - • Шаг 3: При сохранении ошибки — экспоненциальный бэкофф с задержкой до 3 попыток.
- • Шаг 4: При отказе модели или некириллическом выводе — перегенерация промпта.
- • Детекция английских реплик: Проверка отсутствия галлюцинаций («Here is the text...»).
- • Валидация JSON: Строгий парсинг блоков
<tables>и<photos>. - • Контроль символов: Защита от перевода кириллицы на латиницу.
- • Координатная сетка: Нормализация рамок фото (ymin, xmin, ymax, xmax в масштабе 0–1000).
Физическая организация компонентов репозитория с разделением версионируемого исходного кода, спецификаций и генерируемых артефактов.
Страницы дел группируются в подпапки по 20 листов. Используйте интерактивный калькулятор для мгновенной конвертации между абсолютными страницами PDF и именами файлов в конвейере.
→ Прямой расчет: Страница PDF → Имена файлов
003_012
017.png / 017.jpg
003_012_017.txt
vol003_237.xlsx
vol003_page237
← Обратный расчет: Имя файла → Страница PDF
Стратегия эволюции от локального CLI-инструмента к серверному многопользовательскому веб-приложению с авторизацией Google OAuth, двухфакторной аутентификацией TOTP и облачной синхронизацией Google Drive.
-
1.
Аутентификация и белый список: Вход через Google OAuth 2.0 в связке с обязательным TOTP (Google Authenticator) и валидацией по разрешенному списку корпоративных email.
-
2.
Облачное хранилище через Google Drive: Подключение общих дисков для исходных PDF и зеркалирования архивов распознавания, снимающее ограничения локального хранилища.
-
3.
Интерактивное разрешение нетекстовых схем: Веб-интерфейс оператора для обработки остановок на чертежах: предпросмотр, пропуск, аннотирование или ручная нарезка.
-
4.
Асинхронная очередь задач: Фоновые воркеры (FastAPI / Celery / Redis) для последовательного выполнения ресурсоемких пайплайнов без блокировки HTTP-сервера.
| ID | Новая возможность | Ключевой фокус разработки |
|---|---|---|
010 |
OpenRouter OCR Backend | Формализация HTTP-клиента OpenRouter и логики каскадного переключения |
011 |
Drive Cloud Storage | Интеграция с API Google Drive для потоковой загрузки PDF и выгрузки результатов |
012 |
Authentication Subsystem | Google OAuth 2.0 + выпуск и валидация QR-кодов TOTP 2FA |
013 |
Web UI & Job Runner | Интерактивная панель мониторинга, запуск томов, обработка чертежей |