From 6c9ea4537a4d3d1551533060ccd0b664221e08ec Mon Sep 17 00:00:00 2001
From: nkozobrod <kozobrod@gmail.com>
Date: Wed, 12 Aug 2026 23:45:01 +0300
Subject: [PATCH] =?UTF-8?q?Init:=20=D1=81=D1=82=D1=80=D1=83=D0=BA=D1=82?=
 =?UTF-8?q?=D1=83=D1=80=D0=B0=20=D0=BF=D1=80=D0=BE=D0=B5=D0=BA=D1=82=D0=B0?=
 =?UTF-8?q?=20md-converters=20(Excel=20=E2=86=92=20markdown),=20AGENTS.md?=
 =?UTF-8?q?=20=D0=B4=D0=BB=D1=8F=20OMP?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .gitignore |  6 ++++++
 AGENTS.md  | 46 ++++++++++++++++++++++++++++++++++++++++++++++
 README.md  | 31 +++++++++++++++++++++++++++++++
 3 files changed, 83 insertions(+)
 create mode 100644 .gitignore
 create mode 100644 AGENTS.md
 create mode 100644 README.md

diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..825928d
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,6 @@
+.venv/
+__pycache__/
+*.pyc
+*.xlsx~
+.DS_Store
+benchmarks/results/
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..f8657b1
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,46 @@
+# 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/
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..cc135a9
--- /dev/null
+++ b/README.md
@@ -0,0 +1,31 @@
+# md-converters
+
+Набор библиотек для преобразования файлов в markdown.
+Старт: **Excel (.xlsx)** → далее другие форматы (pdf, docx, pptx, html…).
+
+## Принцип
+
+Для каждого формата:
+1. Генерируем тест-кейсы (простые → сложные/пограничные)
+2. Ищем лучшие библиотеки: фреймворки (docling, owi, surya, paddle…) →
+   низкоуровневые либы формата
+3. Оцениваем по функционалу → таблица в `libs_eval/`
+4. Проверяем качество конвертации
+5. Бенчмарки: скорость, память, CPU
+
+## Структура
+
+- `testcases/excel/` — сгенерированные .xlsx (сложность нарастает)
+- `benchmarks/` — скрипты замера скорости/памяти/CPU
+- `libs_eval/` — оценка библиотек по функционалу
+- `src/` — итоговые конвертеры
+
+## Договорённости
+
+- Excel: картинки **не нужны** (только текст/структура/форматирование/формулы)
+- Кодогенерация — через OMP (см. AGENTS.md)
+- Документация — в вики /mnt/synology/Obsidian/wiki/ (страница markdown-converter-project)
+
+## Related
+
+- Gitea: https://gitlab.kzbrd.ru/nkozobrod/md-converters