Прототип модуля для автоматической классификации и структурированного извлечения данных из инженерных/технических PDF-документов (чертежи, фотографии, текст, формы).

Использует мультимодальные LLM (Vision) через LiteLLM + Pydantic-схемы для валидации.

---

Быстрый старт

1. Требования

• Python 3.11+
• API-ключи для LLM-провайдеров (см. ниже)

2. Установка

git clone <repo_url>
cd <repo>
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install -r requirements.txt

3. Настройка API-ключей

Создайте файл .env в корне проекта:

OPENAI_API_KEY=sk-...
GEMINI_API_KEY=...

Проект использует LiteLLM — формат имени модели: provider/model_name.
Модели по умолчанию: cometapi/gpt-5-nano (классификация), cometapi/gemini-3-flash (экстракция).

4. Запуск

# Одна страница
python main.py samples/sample-easy.pdf -o results/analysis-easy.json -p 1

# Весь документ
python main.py samples/sample-medium.pdf -o results/analysis-medium.json

5. Воспроизведение всех прогонов

python main.py samples/sample-easy.pdf -o results/analysis-easy.json
python main.py samples/sample-medium.pdf -o results/analysis-medium.json
python main.py samples/sample-hard.pdf -o results/analysis-hard.json

Отключение Multi-step экстракции: По умолчанию для чертежей включена многошаговая экстракция (делает 3 запроса к LLM на страницу для повышения полноты данных). Если вам нужна скорость или экономия токенов, отключите её флагом -nm (или --no-multi-step).

---

Структура проекта

├── main.py                 # CLI-точка входа
├── src/
│   ├── processor.py        # Оркестрация: открытие PDF, параллельная обработка страниц
│   ├── extractors.py       # Классификация страниц и извлечение контента через LLM
│   ├── models.py           # Pydantic-схемы для каждого типа страниц
│   └── utils.py            # CV-метрики для расчёта confidence
├── samples/                # Тестовые PDF-файлы
│   ├── sample-easy.pdf
│   ├── sample-medium.pdf
│   └── sample-hard.pdf
├── results/                # Предпрогнанные результаты
│   ├── analysis-easy.json
│   ├── analysis-medium.json
│   └── analysis-hard.json
├── requirements.txt
├── REPORT.md
├── SELF-EVAL.md
└── README.md

---

Как работает pipeline

PDF → PyMuPDF → [для каждой страницы параллельно]:
  ├─ Рендер Low-DPI (50) ──→ LLM-классификация → тип страницы
  ├─ Рендер High-DPI (72-200, адаптивно) ──→ LLM-экстракция по Pydantic-схеме
  ├─ CV-анализ (резкость, шум, разрешение) ──→ confidence
  └─ Shortcircuit: если TEXT + есть текст из PyMuPDF → LLM не вызывается
→ Валидация → Присвоение ID → Сборка JSON

---

Схема выходных данных

Корневой объект

{
  "document": "input.pdf",
  "pages": [ ... ],
  "summary": {
    "total_pages": 10,
    "by_type": {"DRAWING": 5, "TEXT": 3, "PHOTO": 2},
    "total_entities": 142
  }
}

Объект страницы

{
  "page": 1,
  "type": "DRAWING | PHOTO | TEXT | SCANNED_TEXT | FORM | UNSUPPORTED",
  "confidence": 0.72,
  "content": { ... }
}

Типы страниц и их схемы

DRAWING

Поле	Тип	Описание
title_block	TitleBlock?	Проект, лист, масштаб, дата, автор. null если нет штампа
dimensions	Entity[]	Размеры verbatim: 2'-3", 100 mm
section_views	Entity[]	Разрезы/детали: SECTION A-A, DETAIL 1
materials	Entity[]	Материалы (только если НЕ внутри таблицы)
general_notes	Entity[]	Примечания verbatim
key_notes	Entity[]	Ключевые выноски
schedules	Schedule[]	Таблицы как 2D-массивы [["col1", "col2"], ["val1", "val2"]]
annotations	Entity[]	Визуальные выноски (буллиты, номера в кружках)
references	Entity[]	Ссылки на другие листы

Каждый Entity: {"id": "DRAWING-P1-3", "value": "..."}.
Каждый Schedule: {"id": "DRAWING-P1-5", "title": "...", "content": [[...]]}.

PHOTO

Поле	Тип	Описание
structure_type	str?	Тип сооружения
approximate_size	str?	Приблизительный размер
visible_materials	str[]	Видимые материалы
general_state	str?	Общее состояние
defects	str[]	Видимые дефекты
sign_text	str?	Текст на вывесках/знаках
summary	str?	Что изображено и зачем

TEXT / SCANNED_TEXT / FORM

Поле	Тип	Описание
raw_text	str	Извлечённый текст

---

Формат ID сущностей

{TYPE}-P{page_number}-{sequential_counter}

Примеры:
  DRAWING-P1-1    — первая сущность на странице 1 (чертёж)
  DRAWING-P1-2    — вторая сущность на странице 1
  PHOTO-P3-1      — первая сущность на странице 3 (фото)

---

Внешние зависимости

Зависимость	Зачем
LiteLLM + Vision LLM	Классификация и экстракция
PyMuPDF (fitz)	Открытие PDF, рендеринг, извлечение текста
OpenCV	Расчёт confidence
Pydantic	Валидация схем

---

Источники тестовых PDF

Файл	Источник	Описание
sample-easy.pdf	A2015 mechanical drawings	1 страница. Простой цифровой машиностроительный чертёж одной детали. Идеально читаемый формат. Содержит чёткий угловой штамп (title block), базовые линейные размеры, радиусы и блок со стандартными примечаниями (допуски, материал).
sample-medium.pdf	SMC — Operation Manual AF800/900	16 страниц. Смешанный документ (руководство по эксплуатации). Включает текстовые страницы с предупреждениями, таблицы спецификаций, взрыв-схемы (disassembly drawings) с номерными выносками и перечнем деталей, а также чертежи габаритных размеров (с размерными линиями).
sample-hard.pdf	dwg.ru — lib/4167 (обрезан)	27 страниц. Скан советской книги по архитектуре 1941 года низкого качества. Плотный текст чередуется с генпланами, планами перекрытий, чертежами стропил, схемами. Содержит гигантский детализированный чертёж фасада с плотной таблицей-спецификацией блоков (крайне мелкий и местами неразборчивый шрифт, артефакты сканирования).