./kerakoll-selector-v2

{
  "slug": "kerakoll-selector-v2",
  "phase": "cancelled",
  "gate": null,
  "created_at": "2026-04-15T07:13:19Z",
  "updated_at": "2026-04-15T18:08:00Z",
  "cancelled_at": "2026-04-15T18:08:00Z",
  "cancelled_by": "Лёха (Telegram)",
  "cancellation_reason": "Закрыто по решению Лёхи. Gap gemma4:e4b vs gpt-5.4-mini небольшой (−4pp URL / −5pp match), приоритет — автоматизация самого FinetuneLab. Прод остаётся на gpt-5.4-mini, gemma4:e4b база как fallback.",
  "notes": "Phase 0 + Phase 1 passed. Phase 2 не стартовала. Проект закрыт без FT v2."
}

# Progress — 2026-04-15T07:13:19Z

## Current step
Bootstrap complete. Delegating Phase 1A (datasets research → Hermes) and Phase 1B (models research → Artem) in parallel.

## Completed
- Project directory created: /Users/alphamachine/Projects/finetune-lab/projects/kerakoll-selector-v2
- SPEC.md generated from template
- phase.json initialized

## Pending
- 1A: Hermes research datasets → research-datasets.md
- 1B: Artem research models → research-models.md
- Gate 1: Лёха selects dataset+model combination

## Issues
(none)

# Decisions — kerakoll-selector-v2

## Phase 0 gate — 2026-04-15
**Decision:** approved.

- Formulation: replace gpt-5.4-mini in MW prod with local model, no quality regression.
- Success metric: URL coverage + product match rate (strictly).
- Test set source: `chat_messages` table from MW db (1733 real user queries), stratified 50/50 RU/HU/EN.

## Phase 1 gate — 2026-04-15
**Decision:** Option A — FT needed.

Baseline-first results (see `baseline-first.md`):
- gpt-5.4-mini: 70.0% URL, 53.8% match
- gemma4:e4b: 66.0% URL, 48.7% match (gap −4pp/−5pp)
- kerakoll-selector:v1: 20.0% URL, 29.5% match (regress confirmed)

Gap small but real — FT by correct methodology to close it. Gemma already close (94% URL on RU), need to lift RU to parity and maintain HU/EN.

**Next:** skip Phase 1A/1B standard research (candidates already clear — base gemma4:e4b, teacher gpt-5.4-mini via prod proxy). Go directly to Phase 2 prod-shape dataset generation.

## Project cancelled — 2026-04-15T18:08 MSK
**Decision:** project closed by Лёха (Telegram).

Причина: gap gemma4:e4b vs gpt-5.4-mini небольшой (−4pp URL / −5pp match). Приоритет переключён на автоматизацию самого FinetuneLab фреймворка (launchd sprint, Telegram alerts, UI deploy, status CLI). Прод MW остаётся на gpt-5.4-mini.

Phase 2 (prod-shape dataset generation) не стартовала. Артефакты Phase 0/1 сохранены для возможного перезапуска позже.

# Phase 1 — Baseline-first eval

**Дата:** 2026-04-15
**Test set:** 50 стратифицированных реальных прод-запросов из `chat_messages` MW db (17 RU + 17 HU + 16 EN)
**Pipeline:** изолированная копия прод `/opt/masterworks/shadow_eval_v2/` (retrieval + rerank + LLM). Prod `/api/chat` не тронут.

## Сводка

| Metric | gpt-5.4-mini (прод) | gemma4:e4b (база) | kerakoll-selector:v1 (FT) |
|---|---:|---:|---:|
| URL coverage | **70.0%** | 66.0% | 20.0% |
| Product match rate | **53.8%** | 48.7% | 29.5% |
| Avg retrieved products | 3.04 | 3.04 | 3.04 |

## По языкам

### RU (17 questions)
| Model | URL | Match |
|---|---:|---:|
| gpt-5.4-mini | 100.0% | 68.1% |
| gemma4:e4b | 94.1% | 48.5% |
| FT v1 | 23.5% | 32.4% |

### HU (17 questions)
| Model | URL | Match |
|---|---:|---:|
| gpt-5.4-mini | 52.9% | 45.6% |
| gemma4:e4b | 47.1% | 48.5% |
| FT v1 | 11.8% | 20.6% |

### EN (16 questions)
| Model | URL | Match |
|---|---:|---:|
| gpt-5.4-mini | 56.3% | 47.4% |
| gemma4:e4b | 56.3% | 49.0% |
| FT v1 | 25.0% | 35.9% |

## Анализ

- **gpt-5.4-mini** — текущий прод baseline. URL 70%, match 54%. Сильна на RU (100%/68%), слабее на HU/EN. Это bar.
- **gemma4:e4b (база)** — локальная, без FT. Отстаёт от GPT на ~4pp URL / ~5pp match. На EN паритет (56/49 vs 56/47). На HU паритет. На RU GPT лучше (100 vs 94 URL, 68 vs 49 match).
- **kerakoll-selector:v1 (FT)** — подтверждает регресс из прошлого shadow eval: 20% URL, 30% match. В 3.5x хуже GPT по URL. Не деплоим, v1 official failed.

## Phase 1 gate — решение

Gap gemma4:e4b vs gpt-5.4-mini: −4pp URL, −5pp match. Небольшой но существующий. На RU gap больше (−5pp URL, −19pp match).

**Варианты:**
- **A (FT нужен):** делать v2 FT по правильной методологии (prod-shape dataset) чтобы закрыть gap на RU и улучшить HU/EN. Цель — догнать или обогнать gpt-5.4-mini.
- **B (FT не нужен):** принять gemma4:e4b как есть, деплоить локально. Потеря ~5pp качества ради $0 OpenAI cost + offline.
- **C (остаёмся на gpt-5.4-mini):** статус-кво, если даже 5pp потеря критична.

**Рекомендация:** A — FT имеет смысл, gap реален, но небольшой. После правильной методологии (prod-shape dataset + shadow eval gate) шансы обогнать GPT на RU очень высокие (база уже 94%, нужно довести до 100% и поднять match).

HU/EN — retrieval слабый (и GPT на них лишь 53-56%). FT может не помочь — проблема в retrieval, не в LLM. Это отдельная задача, не в scope v2.

**Решение (записать в decision.md после Лёхи):**

- [ ] A — идём в Phase 2 (prod-shape dataset, FT)
- [ ] B — закрываем проект, gemma4:e4b деплоится как есть
- [ ] C — закрываем проект, остаёмся на gpt-5.4-mini

# Fine-tune project: kerakoll-selector-v2

## Исходная идея
Fine-tune локальной модели для MasterWorks Kerakoll product recommendation через прод-pipeline, замена gpt-5.4-mini на локальную без регресса качества

## Статус
- **Создан:** 2026-04-15T07:13:19Z
- **Фаза:** 1-research
- **Slug:** `kerakoll-selector-v2`
- **Путь:** `/Users/alphamachine/Projects/finetune-lab/projects/kerakoll-selector-v2`

---

## Phase 0 — Task framing (обязательный gate перед любой работой)

Этот блок заполняет Opus на основе идеи и переспросов у Лёхи. Без этого блока НЕ стартуем research.

### Цель
Заменить gpt-5.4-mini (прод MW chat-engine) на локальную модель без регресса качества подбора Kerakoll продуктов. Бизнес-цель — убрать зависимость от OpenAI billing, возможность offline-режима.

### Прод-стек, в котором модель живёт
- **Режим:** RAG — retrieval (vector search по products + knowledge_base) + rerank (LLM планировщик) + финальная генерация ответа
- **Inference-формат:** OpenAI-compatible chat/completions, messages: `[system (с retrieval_context + правилами ответа), user (запрос клиента)] → assistant`
- **Пример реального прод-запроса:** (см. `/opt/masterworks/src/chat-engine.js` функция `callText`, system prompt включает products digest + knowledge chunks, temperature=0.45, max_tokens=1100)
  ```
  system: "You are MasterWorks Hungary senior engineer... Use only these retrieved products: [Fugabella Color | price 8850 HUF | masterworks.hu/products/... ], [Fugalite Color | ...]. Knowledge chunks: [...]. Reply in user's language with URL to each recommended product."
  user: "Нужна затирка для душевой зоны..."
  ```
- **Кто вызывает модель:** `/opt/masterworks/src/chat-engine.js` на mw-vps, PM2 process `mw-pilot`, endpoint `/api/chat` на mw.ainmid.com
- **Constraints:**
  - Latency: до 20s на Pro mode (сейчас gpt-5.4-mini ~19s)
  - Hardware: Mac Studio M3 Ultra 96GB для локального inference через Ollama/Tailscale
  - Privacy: данные клиентов не должны уходить за пределы нашей инфры

### Baseline
- **Текущая модель в проде:** gpt-5.4-mini через Codex OAuth proxy (SSH tunnel 127.0.0.1:18890 на mw-vps)
- **Вторичный baseline:** gemma4:e4b (база без FT) — по shadow eval от 2026-04-15 показала URL 9/10 в pipeline
- **Метрики baseline на prod-pipeline (30-50 реальных запросов — замерить в Phase 1):**
  | Metric | gpt-5.4-mini (цель) | gemma4:e4b база |
  |---|---|---|
  | URL coverage | TBD (замерить) | 9/10 (shadow eval) |
  | product correctness | TBD | TBD |
  | instruction following | TBD | TBD |
  | latency p50 | TBD | ~33s (слишком медленно?) |
  | cost per 1k requests | ~$0.30 (OpenAI) | $0 (local) |

### Success criterion
- **Улучшение которое нужно:** локальная модель с качеством >= gpt-5.4-mini (URL coverage, product correctness) и latency <= 20s p50
- **Гейт остановки:** если FT не обгоняет gemma4:e4b базу в shadow-eval по task-metric ИЛИ регрессит по instruction-following — проект закрывается как "not needed" / "failed", используем базовую Gemma4 или остаёмся на gpt-5.4-mini

---

## Phase 1 — Baseline-first sanity (обязательный gate)

Перед выбором модели/датасета прогнать candidate base model (без FT) через прод-pipeline на 20-50 вопросах из реальных логов.

- **Базовая модель кандидат:** TBD
- **Test set источник:** TBD (реальные прод-логи, не synthetic)
- **Результат baseline через prod-pipeline:** TBD
- **Решение:** [ ] FT нужен (базовая не справляется) / [ ] FT не нужен (задача закрывается)

Если базовая уже даёт target — задача закрыта без FT. Это успех лаба.

---

## Phase 2 — Dataset design (prod-shape)

### Формат training examples
Training examples ОБЯЗАНЫ повторять прод-формат вызова.

- **Не:** `{question → answer}`
- **Да:** `{system (с полным контекстом как в проде), user, assistant}`

### Teacher trace capture
- **Teacher model:** TBD
- **Что сохраняем:** полный trace — system_prompt, retrieved_context, tool_calls, final answer
- **Где:** JSONL, одна строка — один пример, полная структура messages

### Датасеты
- TBD (заполнит research)

### Held-out test set
- **Источник:** реальные прод-логи (НЕ synthetic) — минимум 50 примеров
- **Используется для shadow-eval в Phase 6**

---

## Целевая модель (Phase 1B research)
- **Base model:** TBD
- **Размер:** TBD
- **Формат:** TBD (safetensors / GGUF)
- **Лицензия:** TBD

## Training plan
- **Метод:** LoRA (rank 32, alpha 64 — default, уточнять по задаче)
- **Stages:** TBD (обычно 1-2)
- **Hardware:** Mac Studio M3 Ultra (96GB) через MLX-VLM

---

## Gates (обязательная последовательность)

- [ ] **Phase 0 gate (Лёха):** task framing утверждён, baseline замерен, success criterion зафиксирован
- [ ] **Phase 1 gate (Opus + Лёха):** baseline-first прогон показал, что FT нужен (иначе close)
- [ ] **Gate 1 (Лёха):** research датасетов + моделей одобрен, выбрана комбинация
- [ ] **Gate 2 (Лёха):** sanity check на 10% данных пройден, early-beat-baseline positive
- [ ] **Gate 3 shadow eval (Лёха):** FT через прод-pipeline обгоняет baseline на held-out test, instruction-following не упало
- [ ] **Gate 4 deploy (Лёха):** одобряет регистрацию в Ollama / деплой

## Auto-drop rules
- Sanity (Phase 3) не обгоняет baseline через prod-pipeline на 10% данных → стоп, архивируем.
- Full train не обгоняет baseline → стоп, не экспортим.
- Shadow-eval показал регресс instruction-following → стоп, модель помечается "failed", post-mortem.

---

## Ссылки
- Phase 1 baseline-first: `baseline-first.md`
- Research датасетов: `research-datasets.md`
- Research моделей: `research-models.md`
- Решение Лёхи: `decision.md`
- Shadow eval: `shadow-eval.md`
- Прогресс: `progress.md`

• ./.artem-prompt.txt
• ./.hermes-prompt.txt
• ./SPEC.md
• ./adapters
• ./baseline-first.md
• ./data
• ./decision.md
• ./eval
• ./idea.txt
• ./phase.json
• ./progress.md
• ./results-baseline-first-gemma4_e4b-20260415T074609Z.json
• ./results-baseline-first-gpt-5.4-mini-20260415T073045Z.json
• ./results-baseline-first-kerakoll-selector_v1-20260415T075855Z.json

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