# Спецификация входа для генерации эмбеддинга главы

Текст, который передаётся в модель эмбеддингов (по умолчанию BAAI/bge-m3), строится из **валидированного анализа главы**. Источник полей — JSON анализа по схеме из ARCHITECTURE_SUMMARY.md (блоки framework, insights, application). Цель — сохранить смысл для семантического поиска: по вектору ищут главы по смыслу (принципы, инсайты, техники), а не по сырому тексту.

---

## ЧТО ВКЛЮЧАТЬ

В текст для эмбеддинга входят **только** блоки анализа:

1. **Framework (каркас):** принципы (title, description, example), terms (термин → краткое пояснение), при необходимости — ключевые цепочки cause–mechanism–result (кратко).

2. **Insights (инсайты):** title, description (и при необходимости example) по каждому инсайту. Без лишних метаполей.

3. **Application (применение):** техники — name, goal, steps (кратко или полный список), при необходимости context_example. То, по чему будет искаться «как это применить».

**Не включать:**
- Оригинальный текст главы.
- Limitations — по умолчанию не включать (опционально через конфиг).
- Теги — хранятся в payload Qdrant, в вектор не входят.

---

## ПОРЯДОК И ФОРМАТ СЕРИАЛИЗАЦИИ

**Язык текста:** тот же, что и язык главы (или основной язык книги). Для мультиязычных коллекций — зафиксировать в конфиге (например, всегда русский / всегда язык главы).

**Порядок секций** (приоритет при truncation — сверху вниз):

```
FRAMEWORK
{framework}

INSIGHTS
{insights}

APPLICATION
{application}
```

**Разделители:**
- Между секциями: заголовок секции (FRAMEWORK, INSIGHTS, APPLICATION) + пустая строка.
- Внутри секции: элементы разделять переносом строки или маркером «—»; не склеивать в один абзац. Пример: каждый принцип — с новой строки; каждый инсайт — с новой строки; каждая техника — с новой строки.

**Формат полей:** читаемый текст с подписями («Принцип: …», «Инсайт: …», «Техника: …») или компактный структурированный текст. Избегать сырого JSON без подписей; предпочитать человекочитаемую склейку.

**Подстановки при сборке:**
- `{framework}` — строка из JSON блока framework (принципы, terms; chains при необходимости).
- `{insights}` — строка из JSON блока insights.
- `{application}` — строка из JSON блока application.

**Пример сериализации (фрагмент):**

```
FRAMEWORK

Принцип: Правило двух минут. Описание: Если действие занимает меньше двух минут — сделай его сразу. Пример: ответ на короткий email, вынести мусор.
Термины: атомная привычка — сверхмалое действие, повторяемое ежедневно.

INSIGHTS

Инсайт: Привычки формируют идентичность. Мы меняемся не через цели, а через системы и повторяющиеся действия.

APPLICATION

Техника: Снижение барьера входа. Цель: начать действие без откладывания. Шаги: сформулировать версию привычки «на 2 минуты»; выполнять её в одно и то же время; после закрепления — расширять.
```

**Нормализация перед подачей в модель:** схлопнуть множественные пробелы и переносы в один; обрезать пробелы по краям строк и в начале/конце итогового текста. Это уменьшает разброс из‑за форматирования.

---

## ЛИМИТ МОДЕЛИ И СТРАТЕГИЯ ПРЕВЫШЕНИЯ

- **Лимит (bge-m3):** 8192 токенов на вход. Полный анализ главы обычно укладывается. Для других моделей — лимит указывать в конфиге.

- **Если текст укладывается в лимит:** передать один сконкатенированный текст (FRAMEWORK + INSIGHTS + APPLICATION) в один вызов модели.

- **Если текст длиннее лимита** — выбрать одну из стратегий (зафиксировать в конфиге):

  1. **truncate_priority:** обрезать текст до лимита. Сохранять в порядке приоритета: сначала APPLICATION (техники важны для поиска), затем INSIGHTS, затем FRAMEWORK. Отбрасывать с конца не поместившегося блока.

  2. **truncate_per_section:** обрезать до лимита, сохраняя начало каждой секции. Сначала поместить начало FRAMEWORK, затем начало INSIGHTS, затем начало APPLICATION, пока не исчерпается лимит.

  3. **chunk_aggregate:** разбить текст **последовательно** (с начала к концу) на чанки по лимиту; получить вектор для каждого чанка; усреднить векторы (или другой способ агрегации) и сохранить один итоговый вектор. Способ агрегации — в конфиге.

---

## ВЫХОД

- Один вектор фиксированной размерности. Для bge-m3 — **1024**. При смене модели размерность меняется; коллекции Qdrant создавать с соответствующим size.
- Вектор сохраняется в Qdrant в коллекции `chapter_analyses`. Payload — по схеме из ARCHITECTURE_SUMMARY.md: bookId, chapterId, chapterNumber, chapterTitle, validationScore, tags и др. Текст анализа в payload при необходимости хранить отдельно или не хранить (по политике системы).

---

## КОНФИГУРАЦИЯ

- Модель эмбеддингов: env/конфиг (по умолчанию EMBED_MODEL=bge-m3).
- Лимит токенов модели: конфиг (для bge-m3: EMBED_MAX_TOKENS=8192).
- Размерность вектора: для bge-m3 — 1024; при смене модели задавать в конфиге и пересоздавать коллекции Qdrant.
- Стратегия при превышении: конфиг (truncate_priority | truncate_per_section | chunk_aggregate).
- Включение limitations в текст: опционально, конфиг (по умолчанию false).
- Язык сериализации (при мультиязычности): опционально, конфиг (например, chapter_lang | book_lang | fixed:ru).