# AGENTS.md — контекст проекта для OMP

Проект: набор библиотек для конвертации файлов → markdown.
**Текущий формат: Excel (.xlsx).** Дальше — pdf, docx, pptx, html…

## Workflow для каждого формата

1. Сгенерировать простые тест-кейсы (базовые данные, заголовки, типы)
2. Найти лучшие библиотеки: сначала фреймворки (docling, owi, surya,
   paddle…), потом докопаться до низкоуровневых либ формата
   (для Excel: openpyxl, pandas, xlrd, calamine…)
3. Оценить по функционалу → таблица в `libs_eval/`
4. Сгенерировать сложные тест-кейсы:
   - пустые, но отформатированные колонки (их много)
   - большие промежутки между колонками (файл целиком читать не хочется)
   - сложное форматирование: объединённые ячейки, стили, цвета
   - формулы и ссылки
   - пограничный размер: миллионы строк
   - разные кодировки и форматы данных
5. Проверить качество конвертации
6. Забенчмаркировать: скорость, потребление памяти, нагрузка на CPU

## Ключевые договорённости

- **Excel: картинки НЕ нужны** — только текст, структура, форматирование, формулы
- Тест-кейсы: генерировать скриптами (openpyxl), файлы в `testcases/excel/`
- Именование: `tc<N>_<описание>.xlsx`, например `tc01_basic.xlsx`
- Бенчмарки: замерять wall-time, RSS (memory_profiler/psutil), CPU% — выводить таблицей
- Python 3, зависимости в `requirements.txt`, venv в `.venv/` (не коммитить)

## Питфоллы (проверено)

- Миллионы строк: openpyxl read_only mode / pandas chunking / calamine (Rust)
- Пустые отформатированные колонки: проверять `ws.calculate_dimension()` /
  `ws.max_column` — многие либы их игнорируют
- Формулы: openpyxl `data_only=True` даёт cached value (если файл открывался
  в Excel), иначе формулу; calamine отдаёт cached value сразу
- xlsx внутри — UTF-8 XML, но данные бывают в разных локалях; .xls (BIFF) —
  отдельная история (xlrd >=2.0 только .xls!)

## Стиль работы

- Сначала изучить существующее (README, libs_eval/, тест-кейсы), не дублировать
- Код — через тебя (OMP), короткие итерации, самопроверка запуском
- Результаты бенчмарков/оценок — в markdown-таблицы в libs_eval/
- Обновления вики — делает Hermes, не трогай /mnt/synology/