# ТЗ: Snowbike RAG — инкрементальное восстановление индексов и сервиса

Дата: 2026-04-07 UTC

## Контекст

- Полную переиндексацию **НЕ запускать**.
- Source-данные уже обновлены инкрементально.
- Нужно восстановить рабочее состояние индексов и сервиса минимально инвазивно.
- Основная цель: долить только новые данные, восстановить поиск и проверить качество summary.

## Подтверждённый текущий статус сервисов

- `snowbike-rag API` на `:5557` — **UP**
- `Meilisearch` на `:7700` — **UP**
- `ChromaDB` на `:8000` — **DOWN**
- `start.sh` сейчас умеет поднимать Meilisearch и Flask API, но **не поднимает ChromaDB**

## Исходные данные

- Source-файл RAG обновлён:
  - `tasks/snowbike-rag/data/messages.jsonl`
  - было `140059`, стало `140275`
  - добавлено `216` новых сообщений
  - новый `max_date`: `2026-04-06T16:49:01Z`
- Файл инкремента:
  - `tasks/snowbike-rag/data/incremental_20260407.jsonl`

## Исторические симптомы

- Meilisearch ранее падал при инкрементальной доливке с ошибкой:
  - `503 Service Unavailable` при `add_documents`
- ChromaDB ранее давал ошибку:
  - `Error loading hnsw index`
- До ребута индексы отставали:
  - Meilisearch: `140059`
  - ChromaDB: `136428`

## Задача

### 1) Диагностика

Проверить текущее состояние:
- API `:5557`
- Meilisearch `:7700`
- ChromaDB `:8000`
- логи Flask / индексации / ChromaDB
- определить, почему ChromaDB не поднят

### 2) Поднять ChromaDB

Нужно:
- выяснить, как ChromaDB должен стартовать в этом проекте
- поднять его корректно
- если проблема в битом `hnsw`, `lock`, `path mismatch` или смежной причине — локализовать и исправить минимально инвазивно
- **не ломать существующие данные без необходимости**

### 3) Инкрементальная индексация

После восстановления ChromaDB:
- долить **только** `tasks/snowbike-rag/data/incremental_20260407.jsonl`
- **не запускать полный rebuild**
- обновить:
  - Meilisearch
  - ChromaDB

### 4) Проверка консистентности

После доливки:
- сравнить количество документов / записей в source и индексах
- убедиться, что новые сообщения реально ищутся
- отдельно проверить несколько запросов по свежим апрельским данным

### 5) Проверка качества поиска и summary

Сделать короткую валидацию:
- 3–5 тестовых запросов
- проверить:
  - релевантность поиска
  - наличие свежих данных
  - качество генерации summary
  - корректность источников в ответе

### 6) Надёжность запуска

Посмотреть, почему `start.sh` поднимает Flask и Meilisearch, но не поднимает ChromaDB.
Нужно предложить и по возможности реализовать аккуратный фикс:
- чтобы сервис после рестарта поднимался целиком
- без ручной магии
- без риска случайно запустить полный rebuild

### 7) Документация

После изменений:
- обновить документацию проекта
- кратко описать:
  - как стартуют все компоненты
  - как делать **инкрементальное** обновление
  - что делать, если ChromaDB снова не поднимается

## Ограничения

- **Нельзя** делать полный rebuild без отдельного подтверждения
- Перед рискованными изменениями данных индекса — сделать бэкап
- Предпочтение: минимально инвазивное восстановление

## Ожидаемый результат

Dev должен вернуть:
1. причину падения / нестарта ChromaDB
2. что именно исправлено
3. удалось ли долить `incremental_20260407.jsonl`
4. итоговые счётчики по source / Meili / Chroma
5. результаты 3–5 тестовых запросов
6. список изменённых файлов

## Требование по модели

Работать на модели:
- `nekocode/gpt-5.4`
