# pdf2ai

Model-free конвертер PDF → markdown для локального агента: главы по разделам, картинки рядом, grep по `<!-- page N -->`.

## Зависимости

- Python **3.10+**
- pip-пакеты из [`requirements.txt`](requirements.txt): `pymupdf`, `pdfplumber`, `Pillow`

Скрипт [`run.sh`](run.sh) сам создаёт `.venv` и ставит зависимости.

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

```bash
chmod +x run.sh
./run.sh                          # по умолчанию RealTek-r8169.pdf
./run.sh path/to/doc.pdf          # свой PDF
./run.sh doc.pdf -o out/my-doc    # свой каталог вывода
```

Структура вывода `out/<stem>/` (по умолчанию):

```
out/RealTek-r8169/
├── INDEX.md              # оглавление со ссылками на главы
├── chapters/             # одна глава = один файл
│   ├── 01-features.md
│   └── ...
└── assets/               # embedded PNG + page PNG для сломанных layout-страниц
```

С флагом `--single-file` вместо `INDEX.md` и `chapters/` пишется один `{stem}.md` (каталог `assets/` всё равно создаётся).

### Опции extract.py

| Флаг | Описание |
|------|----------|
| `--single-file` | Один `{stem}.md` вместо `INDEX.md` + `chapters/` |
| `--tables` | Включить извлечение таблиц pdfplumber (по умолчанию выключено) |
| `--page-dpi N` | DPI для PNG-рендера страниц с битым текстом (default 150) |
| `-o DIR` | Каталог вывода |

## Grep для агента

Главы разбиты по крупным разделам документа. Каждая страница помечена HTML-комментарием:

```bash
# найти упоминание регистра в главе 6
rg -n 'DTCCR' out/RealTek-r8169/chapters/06-register-descriptions.md

# все вхождения по всему документу
rg -n 'Interrupt Mask' out/RealTek-r8169/

# контекст вокруг страницы 51
rg -n -C3 'page 51' out/RealTek-r8169/chapters/09-functional-description.md
```

Начните с [`INDEX.md`](out/RealTek-r8169/INDEX.md) — там ссылки на все главы.

## Ограничения (model-free)

Этот инструмент **не использует LLM/VLM**. Он комбинирует:

- PyMuPDF — текст страниц и embedded-изображения
- pdfplumber — опциональные таблицы (`--tables`)
- эвристику «сломанной страницы» — PNG-рендер bitfield/diagram layout

**Что хорошо:** быстро, локально, детерминированно; grep по главам; картинки сохраняются рядом.

**Что хуже, чем Marker/Docling:** сложная вёрстка, multi-column, сканы без OCR, семантическая структура таблиц. Для таких PDF нужны модельные конвертеры или OCR.

## Roadmap

См. [`plan.md`](plan.md).