Metadata-Version: 2.4
Name: scan-reader
Version: 1.0.0
Summary: AI legal document recognition, Zero-Trust verification, and 1C/Excel registry orchestration
Author: ScanReader Contributors
License-Expression: MIT
Project-URL: Homepage, https://github.com/Riper21/ScanReader
Project-URL: Repository, https://github.com/Riper21/ScanReader
Project-URL: Changelog, https://github.com/Riper21/ScanReader/blob/main/CHANGELOG.md
Project-URL: Issues, https://github.com/Riper21/ScanReader/issues
Keywords: vlm,ocr,document-analysis,legal-tech,zero-trust,fssp,court-orders,1c,excel-registry,mcp
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Legal Industry
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Office/Business :: Financial :: Accounting
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: LICENSE_RU.md
Requires-Dist: pydantic<3.0,>=2.6
Requires-Dist: openai>=1.30
Requires-Dist: Pillow>=10.0
Requires-Dist: pymupdf>=1.24.3
Requires-Dist: python-docx>=1.1.0
Requires-Dist: docx2txt>=0.8
Requires-Dist: openpyxl>=3.1
Requires-Dist: python-dotenv>=1.0
Provides-Extra: ocr
Requires-Dist: rapidocr-onnxruntime>=1.3; extra == "ocr"
Provides-Extra: ocr-full
Requires-Dist: paddleocr>=2.7; extra == "ocr-full"
Requires-Dist: paddlepaddle>=2.5; extra == "ocr-full"
Provides-Extra: dev
Requires-Dist: build>=1.0; extra == "dev"
Requires-Dist: mypy>=1.13; extra == "dev"
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
Requires-Dist: ruff>=0.9; extra == "dev"
Dynamic: license-file

[English](README_EN.md) | [Русский](README.md)

# ScanReader (AI-Система распознавания документов)

[![CI](https://github.com/Riper21/ScanReader/actions/workflows/ci.yml/badge.svg)](https://github.com/Riper21/ScanReader/actions)
[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Code style: ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
[![Checked with mypy](https://www.mypy-lang.org/static/mypy_badge.svg)](https://mypy-lang.org/)

**ScanReader** — это промышленная платформа на Python 3.9+ для мультимодального распознавания юридических документов, Fast-Path классификации, Zero-Trust аудита финансовых и регистрационных реквизитов, а также автоматизированной выгрузки в 1С:Предприятие и многостраничные Excel-реестры.

Платформа спроектирована для работы в закрытом корпоративном контуре с локальными VLM (Qwen2.5-VL через Ollama/vLLM) и внешними эндпоинтами OpenAI/DeepSeek с гарантией детерминированной проверки достоверности данных.

---

## Ключевые возможности и гарантии

- **Fast-Path роутер:** трёхступенчатый каскад — правила по пути и имени файла, затем текстовые маркеры, и только если оба не сработали — двухзонный Chain-of-Thought проход VLM. Если правило сматчилось, модель **не вызывается**, что делает обычные пакеты детерминированными и дешёвыми.
- **Zero-Trust Verification Engine:** детерминированный аудит извлечённых данных, управляемый для каждого типа документа декларацией `verification.json`:
  - Алгоритмический расчёт контрольных разрядов РФ: ИНН (10 и 12 знаков), СНИЛС, ОГРН/ОГРНИП, БИК и 20-значные счета (ключ 565-П ЦБ РФ).
  - Сверка составных сумм. **Сверкой считается только сравнение двух и более чисел**; единственное число фиксируется как непроверенное, а не как проверенное.
  - Законодательные ограничения: 50 % стандартно, до 70 % при наличии основания по алиментам (ст. 99 229-ФЗ) и 20 % от общего месячного заработка (ст. 138 ТК РФ). Компенсация вреда здоровью лимиту 50 % **не подлежит** (ФЗ № 314-ФЗ), и отдельного процентного потолка для неё нет — аудитор не утверждает обратного.
  - Контроль юридической хронологии процессуальных актов.
- **Cross-Modal Антигаллюцинационный шлюз:** сопоставляет извлечённые реквизиты, суммы и наименования сторон с эталонным каналом и фиксирует его происхождение (`gate_source`, `gate_independent`). С `pip install "scan-reader[ocr]"` эталоном служит **независимый** проход OCR; без него транскрипцию даёт та же модель, что и извлечение, и это прямо помечается как **не** независимая проверка.
- **Честные статусы верификации:** `zero_trust_verified` означает «все применимые проверки пройдены». Это не утверждение о стопроцентной правильности, и документация явно обозначает эту границу (см. [ARCHITECTURE_RU.md](ARCHITECTURE_RU.md)).
- **JSON-RPC Stdio-сервер:** встроенный приватный JSON-RPC 2.0 сервер с 5 инструментами для доверенных интеграций внутри корпоративного контура; доступ к файлам ограничен `SCANREADER_ALLOWED_DIRS`. Это не официальный протокол MCP.
- **Отказоустойчивый атомарный ввод-вывод:** запись файлов через временные буферы с `fsync` и атомарной заменой (защита от повреждения при сбоях питания); реестры дополняются, а не усекаются.
- **Канонический двухфайловый формат JSON (Full & Flat):** сохранение полной иерархической модели `{stem}_Full.json` (аудит, Guardrails, оговорки измерения) и одноуровневого файла `{stem}_Flat.json` для прямой загрузки в 1С без вложенных структур.
- **Обратная совместимость CLI:** поддержка существующих скриптов импорта в 1С и батников операторов с детерминированными кодами возврата.

### Коды возврата

| Код | Значение |
| :--- | :--- |
| `0` | Обработано, блокирующих замечаний верификации нет |
| `1` | Ошибка обработки или входной файл не найден |
| `2` | Ошибка аргументов CLI |
| `3` | Обнаружено расхождение либо кросс-модальный гейт не выполнился — **требуется ручная проверка** |
| `4` | Суммы восстановлены эвристическим regex-сканером, а не прочитаны моделью |

---

## Поддерживаемые типы документов (Universal Enterprise Matrix)

ScanReader построен на расширяемой архитектуре плагинов (`TypeRegistry`), поддерживающей 9 ключевых категорий делопроизводства РФ «из коробки»:

| Категория | Плагин (`ID`) | Ключевые сущности & Проверки Zero-Trust | Форматы выгрузки |
| :--- | :--- | :--- | :--- |
| **Договоры** | `commercial_contracts` | Стороны, ИНН/КПП, ОГРН, уставные полномочия подписантов, предмет, общая сумма, ставка НДС, сроки действия. | 1С, Excel, Full JSON |
| **УПД и накладные** | `invoices_upd` | Статус 1/2, продавец/покупатель, ИНН 10/12, табличные товарные строки, ставки НДС 20%/10%/0%, суммы без НДС и с НДС. | 1С:УТ/ERP, Excel, Full JSON |
| **Акты сдачи-приемки** | `acceptance_certificates` | Заказчик, исполнитель, договор-основание, период, перечень услуг/работ, общая стоимость, отметка об отсутствии претензий. | 1С:Бухгалтерия, Excel, Full JSON |
| **Доверенности** | `powers_of_attorney` | Доверитель, представитель (паспортные данные, СНИЛС), объем полномочий, право передоверия, нотариальное удостоверение, срок. | 1С:ЗУП/ERP, Excel, Full JSON |
| **Досудебные претензии** | `legal_claims` | Кредитор, должник, договор-основание, основной долг, неустойка/пени, расчет ст. 395 ГК РФ, дедлайн для добровольного ответа. | Юр. системы, Excel, Full JSON |
| **Кадровые приказы** | `hr_orders` | Унифицированные формы Т-1, Т-5, Т-6, Т-8, табельный номер, подразделение, оклад/ставка, даты приема/увольнения, трудовой договор. | 1С:ЗУП, Excel, Full JSON |
| **Приказы ИП** | `enforcement_orders` | Постановления и заявления о возбуждении ИП, отделы РОСП/УФССП, реквизиты взыскателя и должника. | 1С, Excel, Full JSON |
| **Исполнительные листы** | `executive_documents` | Серии ФС/ВС, решения судов РФ, суммы присужденного взыскания, реквизиты арбитражных судов. | 1С, Excel, Full JSON |
| **Взыскание на зарплату** | `salary_deductions` | Постановления ФССП по доходам должника, ст. 99 229-ФЗ, ограничение удержаний 50%/70%, банковские реквизиты. | 1С:ЗУП, Excel, Full JSON |

---

## Установка

### Установка из PyPI (рекомендуется)
```bash
pip install scan-reader
```

### Установка из исходников
```bash
git clone https://github.com/Riper21/ScanReader.git
cd ScanReader
pip install .
```

### Editable-установка (разработка)

Если вы работаете с исходниками, ставьте пакет **editable из этого репозитория**, чтобы команды `scan-reader` / `scanreader` и JSON-RPC-сервер исполняли именно эту копию проекта, а не другую версию на машине:

```bash
py -3 -m pip uninstall scan-reader -y   # сначала уберите старые editable-установки
py -3 -m pip install -e .
py -3 -c "import scan_reader; print(scan_reader.__file__)"   # должен указывать в этот репозиторий
scan-reader --version
```

Устаревшая editable-установка, указывающая в другую папку, — самая частая причина жалоб «CLI запускает старый код»; после переустановки всегда проверяйте `scan_reader.__file__`.

### OCR (рекомендуется для сканов)

Без OCR-движка кросс-модальный гейт для **сканов** опирается на транскрипцию той же
модели, что и извлечение. Это **не** независимая проверка: ошибки распознавания
неотличимы от ошибок извлечения, и отчёт это помечает
(`gate_source=vlm_transcription`, предупреждение `GATE_REFERENCE_FROM_VLM`).

```bash
# CPU, ~15 МБ, тот же движок, что и в PaddleOCR
pip install "scan-reader[ocr]"

# PaddleOCR с поддержкой GPU и широким языковым покрытием
pip install "scan-reader[ocr-full]"
```

После установки `scan-reader doctor` покажет активный бэкенд.

### Установка инструментов разработки и тестирования
```bash
pip install ".[dev]"
```

---

## Использование в командной строке (CLI)

Консольный интерфейс `scan-reader` поддерживает модульные подкоманды и машиночитаемый флаг `--json`:

```bash
# 1. Обработка документа: возврат пути к плоскому JSON для 1С (режим по умолчанию)
scan-reader run "C:\Scans\order.pdf" --format flat

# 2. Обработка с возвратом полного иерархического JSON
scan-reader run "C:\Scans\order.pdf" --format full

# 3. Обработка с возвратом путей к обоим файлам (Full и Flat)
scan-reader run "C:\Scans\order.pdf" --format both

# 4. Полная обработка со структурированным выводом JSON и Zero-Trust отчетом
scan-reader run "C:\Scans\order.pdf" --json

# 5. Быстрая Fast-Path классификация документа по шапке
scan-reader classify "C:\Scans\order.pdf" --json

# 6. Независимый Zero-Trust аудит ранее извлеченного JSON-файла
scan-reader verify "output\order_salary_deductions_Full.json" --json

# 7. Сборка сводных реестров 1С и многостраничного Excel
scan-reader export "output" --format both

# 8. Самодиагностика платформы (VLM-модель, TTFT, токены, GPU, окружение)
scan-reader doctor

# 9. Запуск приватного JSON-RPC сервера (5 инструментов) по Stdio
scan-reader mcp
```

### Коды возврата (Exit Codes)
- `0`: Обработано, блокирующих замечаний верификации нет.
- `1`: Ошибка обработки или входной файл не найден.
- `2`: Ошибка синтаксиса аргументов командной строки.
- `3`: Обнаружены расхождения либо кросс-модальный гейт не выполнился — требуется ручная проверка.
- `4`: Суммы восстановлены эвристическим regex-сканером, а не прочитаны моделью.

---

## Использование через Python API

```python
from scan_reader import LegalDocPlatformFacade
from scan_reader.verifier import ZeroTrustAuditor, VerificationStatus

# Инициализация фасада платформы
facade = LegalDocPlatformFacade()

# Обработка документа через сквозной конвейер
result = facade.process_single_document("scan.pdf")
print("Тип документа:", result["doc_type"])
print("Оценка качества:", result["quality_score_percent"])

# Запуск независимого Zero-Trust аудита
report = ZeroTrustAuditor.audit_document(
    data=result["data"],
    doc_type=result["doc_type"],
    raw_ocr_text=result.get("raw_text")
)

if report.status == VerificationStatus.ZERO_TRUST_VERIFIED:
    # Формулировка «на 100%» была бы ложью: статус означает, что прошли
    # применимые детерминированные проверки, то есть утверждение о проверках,
    # а не о правильности документа.
    print("Все применимые проверки Zero-Trust пройдены")
    print("  контрольных сумм пройдено:", report.details.get("checksums_verified_ok"))
    print("  сверка сумм выполнена :", report.details.get("math_verified_ok"))
    print("  источник эталона      :", report.details.get("gate_source"))
elif report.status == VerificationStatus.PARTIALLY_VERIFIED:
    print("Проверки выполнены частично — нужен выборочный контроль")
elif report.status == VerificationStatus.GATE_NOT_EXECUTED:
    print("Кросс-модальный гейт не выполнился: реквизиты не подтверждены")
elif report.status == VerificationStatus.DISCREPANCY_DETECTED:
    print("Обнаружены расхождения:")
    for issue in report.issues:
        print(f"  • [{issue.code}] {issue.message}")
```

---

## JSON-RPC интеграция (Stdio)

ScanReader предоставляет **приватный строчно-ориентированный JSON-RPC 2.0 сервер** с 5 инструментами
(запуск: `scan-reader mcp`). Протокол приватный: он **не совместим** с официальным MCP SDK
(нет Content-Length framing и handshake `initialize`) и предназначен для доверенных интеграций
внутри корпоративного контура. Доступ к файлам ограничен корнями из `SCANREADER_ALLOWED_DIRS`.

1. `scan_document`: полный цикл распознавания и Zero-Trust аудита.
2. `classify_document`: экспресс-роутинг документа по первой странице.
3. `verify_legal_data`: алгоритмический аудит реквизитов, сумм и дат.
4. `run_benchmark`: запуск эталонного тестирования против Ground Truth.
5. `export_results`: консолидация данных в реестры Excel и 1C.

### Пример запроса (один JSON-объект на строку)
```json
{"jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {}}
{"jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": {"name": "classify_document", "arguments": {"file_path": "incoming/order.pdf"}}}
```

---

## Архитектура и таксономия статусов

Подробные диаграммы компонентов, жизненный цикл обработки и семантика статусов представлены в документе [ARCHITECTURE_RU.md](ARCHITECTURE_RU.md) ([English](ARCHITECTURE.md)).

---

## Поддержка

- 🐛 **Баги и предложения:** [GitHub Issues](https://github.com/Riper21/ScanReader/issues)
- 💬 **Быстрые вопросы и помощь с интеграцией:** Telegram — [@riper21](https://t.me/riper21)

---

## Лицензия

Лицензия MIT. Подробнее см. в [LICENSE_RU.md](LICENSE_RU.md).
