./kerakoll-selector

{
  "phase": "7-done",
  "substep": {
    "3-sanity": "done"
  },
  "winner_checkpoint": "iter_0000400",
  "eval_metrics": {
    "baseline_url_pct": 60,
    "winner_url_pct": 100,
    "winner_lang_pct": 95,
    "winner_struct_pct": 100,
    "winner_lat_s": 11.3
  },
  "updated_at": "2026-04-14T21:00:16Z",
  "deployed": "ollama: kerakoll-selector:v1",
  "gguf_size_gb": 8
}

Phase 2c cleanup done: 794 train / 89 eval (clean, lang-filtered), 2026-04-14 18:25 UTC
## Phase 6 done: kerakoll-selector:v1 in Ollama, 8.0GB q8_0 GGUF

# Decision — Gate 1 (auto-closed by Vitalik)

**Date:** 2026-04-14T17:34Z
**Selected dataset:** synthetic generated from MasterWorks teacher (gpt-5.4-mini on mw.ainmid.com) + 770 Kerakoll SKU SQL + 4380 knowledge chunks
**Selected model:** `mlx-community/gemma-4-e4b-it-4bit` (per research-models.md)

## Rationale
- Public HF datasets для Kerakoll product selection не существуют — Гермес's 1a search был тупиковым изначально.
- Собственные данные MasterWorks (SQLite `/opt/masterworks/data/masterworks.db` + chat-engine.js) — лучший источник. Teacher = текущий рабочий gpt-5.4-mini ответ → student = Gemma 4 E4B LoRA.
- Модель Gemma 4 E4B зафиксирована по прямому требованию Лёхи (~4B класс).
- Auto-closed gate — Лёха дал full autonomy ("делай чё хочешь") с hard deadline "завтра утром модель должна быть".

## Target pipeline
1. Phase 2 (prepare): Артём генерирует 2000-3000 synthetic Q→A examples на HU/RU/EN через teacher + SQL → `prepared.parquet`
2. Phase 3 (sanity): 5 overlay examples
3. Phase 4 (train): LoRA rank 32 alpha 64, 2 stages (grounding + task)
4. Phase 5 (eval): 50 Павлов-curated queries, сравнение с baseline
5. Phase 6 (export): Ollama tag `kerakoll-selector:v1`

**Hard deadline:** 2026-04-15 08:00 MSK (user wakeup).

# Fine-tune project: kerakoll-selector

## Исходная идея
Fine-tune Gemma 4 E4B под подбор продуктов Kerakoll для MasterWorks Hungary (дистрибьютор). Модель принимает описание задачи клиента (тип работ, основание, площадь, условия) и возвращает рекомендацию продуктов Kerakoll с расходом на м2, обоснованием и ссылками на masterworks.hu. Языки: HU (primary), RU, EN. Референс: существующий chat-engine на mw.ainmid.com работает через gpt-5.4-mini + SQL продуктовой БД.

## Статус
- **Создан:** 2026-04-14T13:02:21Z
- **Фаза:** 1-research
- **Slug:** `kerakoll-selector`
- **Путь:** `/Users/alphamachine/Projects/finetune-lab/projects/kerakoll-selector`

## Цель
Заменить platform-dependent API (OpenAI codex для gpt-5.4-mini) на локальную fine-tuned модель, которая:
1. По описанию строительной задачи клиента подбирает оптимальную комбинацию Kerakoll продуктов (клей / затирка / грунтовка / гидроизоляция)
2. Возвращает количество с учётом расхода на м2, формат ответа включает markdown ссылки на `masterworks.hu/products/<handle>`
3. Понимает 3 языка: HU (основной рынок), RU (Лёха + русскоязычные клиенты), EN (fallback)
4. Не галлюцинирует продукты — только из каталога MasterWorks (770 SKU)

## Задача для модели
- **Тип:** generation (structured markdown output с ссылками)
- **Входы:** свободный текст клиента о строительной задаче + опциональный RAG контекст из product DB
- **Выходы:** markdown ответ по формату:
  ```
  Для [задачи] рекомендую:

  ## 🏗 Лучший выбор
  ### [Product Name](https://masterworks.hu/products/handle)
  - Цена: X HUF
  - Расход: Y кг/м²
  - Почему подходит: ...

  ## 🔧 Альтернатива
  ...
  ```
- **Язык:** multi (HU primary, RU, EN) — определяется по языку запроса клиента

## Целевая модель (заполнит research-моделей)
**Приоритет: ~4B параметров** (по решению Лёхи). Research должен проверить подходит ли и предложить альтернативы если нет:
- **Приоритет A (предпочтительно):** Gemma 4 E4B (базовый instruct или abliterated вариант типа `huihui-ai/Huihui-gemma-4-E4B-it-abliterated`)
- **Приоритет B (если 4B не тянет задачу):** Gemma 4 E8B (8B) — 2x вес, но лучше на multilingual
- **Приоритет C (fallback):** Qwen 2.5 3B / 4B — если Gemma плохо идёт на венгерский

**Критерии проверки Артёмом в research:**
- Baseline на multilingual MMLU (HU/RU/EN) — готовая модель до fine-tune
- Проверка MLX compatibility (приоритетно safetensors + mlx-community/)
- Context length ≥ 8K (влезут product catalog chunks)
- Instruction-following quality на русском и венгерском

## Датасеты (заполнит research-датасетов)
Возможные источники (Hermes уточнит):

**Собственные данные MasterWorks (доступны на mw-vps):**
- История чатов из SQLite (`/opt/masterworks/data/masterworks.db` — chat sessions)
- Product catalog: 770 Kerakoll SKU + variants с handle, price, description, image_url
- Knowledge chunks: 4380 технических записей из Kerakoll documentation (таблицы совместимости, расход, характеристики)

**Открытые датасеты (Hermes найдёт):**
- Construction/building Q&A на HU/RU/EN
- Multilingual instruction tuning для HU/RU (Alpaca translations, Belebele)
- Technical manuals для клеев/затирок/гидроизоляции

**Synthetic generation:**
- Сгенерировать диалоги используя текущий chat-engine на gpt-5.4-mini с 770 продуктами — получим 2-5K training examples с правильным форматом и обоснованиями. Это ключевой trick: наш baseline gpt-5.4-mini **становится teacher** для локальной модели.

## Training plan
- **Метод:** LoRA (rank 32, alpha 64 — проверенные в ClickGemma v2)
- **Stages:** 2
  - Stage 1 (grounding): обучение на product knowledge и RAG формате — модель привыкает к формату каталога, названиям, ссылкам
  - Stage 2 (task): обучение на dialogues с правильными ответами — multi-turn conversation с ответами в формате markdown
- **Hardware:** Mac Studio M3 Ultra (96GB) через MLX-VLM
- **Время:** 2-4 часа на stage при ~5-10K examples

## Success metrics
- **Baseline:** gpt-5.4-mini через текущий chat-engine на 20-50 тестовых запросах (mix HU/RU/EN)
  - Метрики: product_id match с expert answer, language consistency, markdown format valid, URL valid
- **Target после fine-tune (4B):**
  - Product_id precision@3 ≥ 75% (baseline от gpt-5.4-mini минус небольшой gap)
  - Language match = 100%
  - Zero hallucinated products
  - Response latency: <3s на Mac Studio / <10s на Ollama VPS
- **Target если 4B не тянет — пересматриваем на 8B**
- **Eval dataset:** 50 hand-curated запросов от Павла (owner MasterWorks) с expert answers

## Gates
- [ ] Gate 1: research датасетов + моделей одобрен (Лёха)
- [ ] Gate 2: sanity check пройден (Лёха видит sample outputs)
- [ ] Gate 3: eval прошёл target (Лёха одобряет deploy)

## Ссылки
- Research датасетов: `research-datasets.md`
- Research моделей: `research-models.md`
- Решение Лёхи: `decision.md`
- Прогресс: `progress.md`
- **MasterWorks БД:** `ssh mw-vps /opt/masterworks/data/masterworks.db` (SQLite, 770 products + 4380 knowledge chunks)
- **MasterWorks chat-engine (база промптов):** `ssh mw-vps /opt/masterworks/src/chat-engine.js`
- **Kerakoll Expert skill (taxonomy):** `/home/clawdbot/.openclaw/workspace/skills/kerakoll-expert/SKILL.md`

• ./.artem-prompt.txt
• ./.hermes-prompt.txt
• ./Modelfile
• ./RELEASE.md
• ./SPEC.md
• ./adapters
• ./data
• ./decision.md
• ./eval
• ./eval.py
• ./eval_raw.json
• ./eval_report.md
• ./fused
• ./generate_dataset.py
• ./idea.txt
• ./logs
• ./phase.json
• ./progress.md
• ./research-datasets.md
• ./research-models.md
• ./sanity_report.md
• ./scripts
• ./training.log
• ./venv

/Users/alphamachine/Projects/finetune-lab/projects/kerakoll-selector