usage.md

Використання

python indexer.py DBNAME SOURCE [опції]

DBNAME — перший обов'язковий аргумент: ім'я або шлях до файлу SQLite. Відносні імена потрапляють у каталог data/ (суфікс .db додається, якщо не вказано); абсолютний шлях використовується як є. SOURCE — локальний шлях або Google Drive URL.

Очікувані документи — скани історичних архівних джерел (метрики, акти, списки тощо) з генеалогічною інформацією. Модель націлена на якісне розпізнавання прізвищ; імена, прізвища й локації варто нормалізувати до сучасної української за контекстом. Ім’я батька береться з контексту або з по батькові (наприклад «Іванович» → «Іван»). Параметр --extended-prompt задає розширений промпт (регіон, тип книги тощо). --description — те саме (псевдонім). AI-провайдер вибирається через AI_PROVIDER у .env або прапорець --provider (gemini за замовчуванням, також підтримується openai).

Приклади

# Ліміт (за замовч. вже оброблені пропускаються; для перезапису додайте --rewrite)
python indexer.py lutsk_marriages 'https://drive.google.com/drive/folders/1IC43A3HaSn-FluEl88PFb9YOSYuYdRVf?usp=drive_link' --limit 20 --extended-prompt volyn_darts_marriages

# Вивантаження в Google Drive
python indexer.py lutskyi_rayon_marriages /home/solvek/Projects/VolynRagz/scans/122484190 --limit 20 --extended-prompt volyn_darts_marriages --model gemini-3.1-flash-lite

# OpenAI/ChatGPT-модель замість Gemini
python indexer.py volyn /mnt/scans --provider openai --model gpt-4o-mini


# Локальна папка — всі файли рекурсивно (БД: data/volyn.db)
python indexer.py volyn /mnt/scans

# Конкретний файл
python indexer.py volyn /mnt/scans --files scan_00023.jpg

# Файл у підпапці
python indexer.py volyn /mnt/scans --files "Метрики/scan_00023.jpg"

# Тільки папка "Метрики" (без підпапок)
python indexer.py volyn /mnt/scans --files "Метрики/"

# Папка "Архів" рекурсивно
python indexer.py volyn /mnt/scans --files "Архів/**"

# Google Drive
python indexer.py volyn https://drive.google.com/drive/folders/FOLDER_ID

# З описом контексту для моделі
python indexer.py volyn /mnt/scans --extended-prompt "Метричні книги Київської губернії, 19 ст."

# Детальні логи
python indexer.py volyn /mnt/scans --verbose

Файл параметрів у папці сканів (indexer.ini)

У корені папки зі сканами (локальної або Google Drive) можна покласти текстовий файл indexer.ini. Якщо він є, програма читає з нього параметри запуску і підставляє їх так, ніби їх передали в командному рядку. CLI має пріоритет: значення з файлу використовуються лише для опцій, яких немає в команді.

Формат — INI-подібний: рядки ключ = значення. Секція [indexer] необов'язкова (зручна, якщо в одному файлі кілька секцій); без неї достатньо плоского списку параметрів. Підтримуються ті самі ключі, що й у CLI (з - або _):

Ключ у indexer.ini	Відповідник у CLI
dbname	перший позиційний аргумент
files	--files
limit	--limit
rewrite	--rewrite / --no-rewrite (true/false, yes/no)
extended_prompt	--extended-prompt
provider	--provider
model	--model
temperature	--temperature
csv	--csv (прапорець: true/yes)
request_delay	--request-delay
verbose	--verbose (прапорець)

Приклад (зразок у репозиторії: samples/indexer.ini):

dbname = volodymyr_raion_deaths
extended_prompt = volyn_darts_deaths
request_delay = 160

Еквівалентна команда:

python indexer.py volodymyr_raion_deaths /шлях/до/папки --extended-prompt volyn_darts_deaths --request-delay 160

Якщо indexer.ini містить dbname, достатньо передати лише шлях до папки:

python indexer.py /шлях/до/папки

Для Google Drive покладіть indexer.ini у ту саму папку Drive, URL якої передаєте другим аргументом.

Параметри

Параметр	Тип	За замовч.	Опис
dbname	positional	—	Ім'я або шлях до SQLite; відносні → data/… (без розширення додається .db)
source	positional	—	Локальний шлях або Google Drive URL
--files	optional	всі рекурсивно	Фільтр файлів (див. нижче)
--limit	optional	без ліміту	Максимум спроб обробки; файли, що лише пропускаються (вже в БД без --rewrite), у ліміт не входять
--rewrite / --no-rewrite	optional	--no-rewrite	Перезаписувати вже оброблені (--rewrite) чи пропускати їх. При --rewrite для відомого скану спочатку видаляються старі записи про людей для цього скану (каскадно), потім зберігаються нові
--extended-prompt	optional	—	Розширений промпт: довільний текст або ім’я prompts/<ім’я>.txt — деталі
--provider	optional	з .env або gemini	AI-провайдер: gemini або openai
--model	optional	з .env або типова для провайдера	Назва моделі провайдера
--temperature	optional	0.1	Температура 0.0–1.0
--csv	flag	—	Допис у out/<ім'я_бд>.csv рядків зі сканів цього запуску; повна поведінка — у експорті CSV
--request-delay	optional	0	Пауза в секундах після кожного звернення до моделі
--verbose	flag	—	Детальні логи

Фільтр --files

Значення	Поведінка
(не задано)	Всі файли рекурсивно
scan_001.jpg	Конкретний файл у корені source
Метрики/scan_001.jpg	Конкретний файл у підпапці
Метрики/	Всі файли в папці (без підпапок)
Архів/**	Всі файли в папці рекурсивно