# RAG

## Состояние as is

RAG сейчас используется как общее ядро индексации и retrieval по коду и документации.
Основной storage - `rag_session` и многослойный индекс в БД.

## Основные части

- `RagService` - фасад индексации и retrieval
- `DocsIndexingPipeline` - индексация документации
- `CodeIndexingPipeline` - индексация кода
- `RagRepository` - persistence и retrieval
- `IntentRouterV2` - планирование retrieval: слои, фильтры, ограничения
- `RuntimeRetrievalAdapter` - выполнение retrieval в runtime

## Индексация

Индексация идет по двум направлениям:

- `DOCS`
- `CODE`

На вход подается snapshot или changes.
Для каждого файла выбирается подходящий pipeline.
На выходе формируются документы по слоям и сохраняются в RAG-хранилище.

## Структура БД

Все слои сохраняются в общую таблицу `rag_chunks`.

### Общие поля по слоям

| Поле БД | Назначение |
|---|---|
| `rag_session_id` | идентификатор сессии индексации |
| `path` | путь исходного файла |
| `content` | основной текст записи для retrieval |
| `layer` | идентификатор слоя |
| `title` | короткий заголовок записи |
| `lang` | язык исходного содержимого, в основном для code-слоев |
| `repo_id` | идентификатор репозитория или проекта |
| `commit_sha` | версия кода или документов на момент индексации |
| `span_start`, `span_end` | диапазон строк в исходном файле, если он есть |
| `embedding` | векторное представление записи |
| `metadata_json` | структурированные атрибуты конкретного слоя |

### Поля со смыслом слоя

Смысл конкретного слоя хранится в `metadata_json`.
Именно эти атрибуты определяют, какой объект был извлечен и как его интерпретировать в retrieval.
Домены и поддомены должны храниться в `metadata_json` явно.

## Слои DOCS

### `D0_DOC_CHUNKS`

Задача:
Хранит текстовые фрагменты документации для retrieval по содержимому разделов.

Формирование:
Документ сначала разбирается на frontmatter и body, затем body режется на секции через markdown chunker.
Для каждой секции создается отдельная запись слоя.
Нарезка идет по разделам документа.
Только в fallback-сценарии, когда markdown-структура не найдена, используется нарезка по фиксированным текстовым чанкам.

Фиксация в БД:
| Атрибут в `metadata_json` | Описание | Источник |
|---|---|---|
| `document_id` | идентификатор документа-источника | `frontmatter.id`, иначе путь файла |
| `type` | тип документа из frontmatter | `frontmatter.type` |
| `module` | модуль документа | `frontmatter.module` |
| `domain` | домен документа | `frontmatter.domain` |
| `subdomain` | поддомен документа | `frontmatter.subdomain` |
| `tags` | теги документа | `frontmatter.tags` |
| `section_path` | полный путь секции в иерархии заголовков | результат `MarkdownDocChunker` |
| `section_title` | заголовок текущей секции | результат `MarkdownDocChunker` |
| `order` | порядок секции внутри документа | результат `MarkdownDocChunker` |
| `doc_kind` | классификация документа, например `readme`, `spec`, `runbook` | `DocsClassifier.classify(path)` |
| `source_path` | исходный путь документа | путь файла |
| `artifact_type` | тип артефакта, здесь `DOCS` | константа builder |

Связанные классы:
`DocsIndexingPipeline`, `DocsContentParser`, `MarkdownDocChunker`, `DocsDocumentBuilder`

### `D1_DOCUMENT_CATALOG`

Задача:
Хранит карточку документа как точку входа в документ и его краткое описание.

Формирование:
Источник данных - frontmatter `as is`, summary и doc kind, вычисленный классификатором документации.
В `metadata_json` копируются все `key-value` из frontmatter без нормализации и без fallback для frontmatter-атрибутов.
Дополнительно в `metadata_json` добавляются служебные поля `source_path`, `summary_text`, `doc_kind`.
Атрибут `document_id` добавляется только при наличии `frontmatter.id` (fallback до пути файла не применяется).
В `content` попадает summary документа, а не склейка всех частей документа в сплошной текст.

Фиксация в БД:
| Атрибут в `metadata_json` | Описание | Источник |
|---|---|---|
| `*` frontmatter fields | все поля frontmatter в исходном виде | frontmatter документа |
| `document_id` | идентификатор документа, добавляется только если в frontmatter есть `id` | `frontmatter.id` |
| `source_path` | исходный путь документа | путь файла |
| `summary_text` | краткое содержание документа | секция `# Summary` |
| `doc_kind` | классификация документа, например `readme`, `spec`, `runbook` | `DocsClassifier.classify(path)` |

Связанные классы:
`DocsIndexingPipeline`, `DocsFrontmatterParser`, `DocsClassifier`, `DocsContentParser`, `DocsDocumentBuilder`

### `D2_FACT_INDEX`

Задача:
Хранит атомарные факты в форме `subject-predicate-object` для точного retrieval по утверждениям.

Формирование:
Факты извлекаются из frontmatter и секций документа, после чего каждая найденная тройка превращается в отдельную запись.

Фиксация в БД:
| Атрибут в `metadata_json` | Описание | Источник |
|---|---|---|
| `fact_id` | идентификатор факта | вычисляется builder из содержимого факта и пути |
| `subject_id` | субъект факта | `DocsFactExtractor` |
| `predicate` | предикат или тип связи | `DocsFactExtractor` |
| `object` | значение или объект факта | `DocsFactExtractor` |
| `object_ref` | ссылка на объект, если она выделена отдельно | `DocsFactExtractor` |
| `anchor` | место в документе, откуда взят факт | `DocsFactExtractor` |
| `tags` | теги факта | `DocsFactExtractor` |
| `source_path` | исходный путь документа | путь файла |

Связанные классы:
`DocsIndexingPipeline`, `DocsFactExtractor`, `DocsDocumentBuilder`

### `D3_ENTITY_CATALOG`

Задача:
Хранит сущности, найденные в документации, чтобы искать документы и связи вокруг конкретной сущности.

Формирование:
Сущности извлекаются из frontmatter документа, после чего каждая сущность сохраняется отдельной записью.

Фиксация в БД:
| Атрибут в `metadata_json` | Описание | Источник |
|---|---|---|
| `entity_name` | имя сущности | `DocsEntityExtractor` |
| `document_id` | идентификатор документа, где найдена сущность | `frontmatter.id`, иначе путь файла |
| `document_type` | тип документа-источника | `frontmatter.type` |
| `module` | модуль документа | `frontmatter.module` |
| `domain` | домен документа | `frontmatter.domain` |
| `subdomain` | поддомен документа | `frontmatter.subdomain` |
| `tags` | теги документа или сущности | `frontmatter.tags` |
| `source_path` | исходный путь документа | путь файла |

Связанные классы:
`DocsIndexingPipeline`, `DocsEntityExtractor`, `DocsDocumentBuilder`

### `D4_WORKFLOW_INDEX`

Задача:
Хранит workflow и сценарии из документации для ответов про flow, шаги и жизненный цикл процесса.

Формирование:
Workflow извлекаются из detail sections документа и сохраняются как отдельные сценарии.
Извлечение идет из структуры `Details -> ## Сценарий`.

Фиксация в БД:
| Атрибут в `metadata_json` | Описание | Источник |
|---|---|---|
| `workflow_id` | идентификатор сценария | вычисляется builder из названия, anchor и документа |
| `document_id` | идентификатор документа-источника | `frontmatter.id`, иначе путь файла |
| `workflow_name` | название сценария | блок `Details -> ## Сценарий -> **Название**` |
| `preconditions` | предусловия сценария | блок `Details -> ## Сценарий -> **Предусловия**` |
| `trigger` | триггер или событие запуска | блок `Details -> ## Сценарий -> **Триггер**` |
| `main_flow` | основной сценарий | блок `Details -> ## Сценарий -> **Основной сценарий**` |
| `alternative_flow` | альтернативные ветки | блок `Details -> ## Сценарий -> **Альтернативный сценарий**` |
| `error_handling` | обработка ошибок | блок `Details -> ## Сценарий -> **Обработка ошибок**` |
| `postconditions` | постусловия | блок `Details -> ## Сценарий -> **Постусловие**` |
| `source_path` | исходный путь документа | путь файла |

Связанные классы:
`DocsIndexingPipeline`, `DocsWorkflowExtractor`, `DocsDocumentBuilder`

### `D5_RELATION_GRAPH`

Задача:
Хранит связи между документами и сущностями документации для navigation и related docs retrieval.

Формирование:
Связи извлекаются из frontmatter и сохраняются как отдельные relation edges.

Фиксация в БД:
| Атрибут в `metadata_json` | Описание | Источник |
|---|---|---|
| `relation_id` | идентификатор связи | вычисляется builder из source, target, relation type и anchor |
| `source_id` | источник связи | `frontmatter.id` или source документа в extractor |
| `relation_type` | тип связи | `DocsRelationExtractor` |
| `target_id` | целевой объект связи | `DocsRelationExtractor` |
| `anchor` | место в документе, где обнаружена связь | `DocsRelationExtractor` |
| `source_path` | исходный путь документа | путь файла |

Связанные классы:
`DocsIndexingPipeline`, `DocsRelationExtractor`, `DocsDocumentBuilder`

### `D6_INTEGRATION_INDEX`

Задача:
Хранит прикладные интеграции компонента, API, UI, сущности или внешней системы.
Используется для ответов на вопросы вида "какие интеграции есть у компонента".

Формирование:
Интеграции извлекаются из блока `## Integrations` документа.
Одна интеграция должна превращаться в отдельную запись слоя.
Описание интеграции может быть развернутым, а структурированные атрибуты должны выделяться в словарь.

Фиксация в БД:
| Атрибут в `metadata_json` | Описание | Источник |
|---|---|---|
| `integration_id` | идентификатор интеграции | вычисляется builder из source, target и anchor |
| `source_id` | идентификатор объекта, для которого описана интеграция | `frontmatter.id` документа-источника |
| `source_type` | тип исходного объекта | `frontmatter.doc_type` |
| `target` | целевой объект интеграции | блок `## Integrations` |
| `target_type` | тип целевого объекта, например `api`, `ui`, `entity`, `service`, `external_system` | блок `## Integrations` |
| `direction` | направление интеграции | блок `## Integrations` |
| `interaction` | тип взаимодействия | блок `## Integrations` |
| `via` | технический канал интеграции | блок `## Integrations` |
| `purpose` | назначение интеграции | блок `## Integrations` |
| `details` | дополнительные атрибуты интеграции в виде словаря | блок `## Integrations` |
| `domain` | домен документа | `frontmatter.domain` |
| `subdomain` | поддомен документа | `frontmatter.subdomain` |
| `source_path` | исходный путь документа | путь файла |
| `anchor` | место в документе, где описана интеграция | блок `## Integrations` |

Связанные классы:
`DocsIndexingPipeline`, `DocsIntegrationExtractor`, `DocsDocumentBuilder`

## Слои CODE

### `C0_SOURCE_CHUNKS`

Задача:
Хранит фрагменты исходного кода как базовый слой для цитирования, explain и точечной догрузки кода.

Формирование:
Исходный файл режется на кодовые чанки, и для каждого чанка создается отдельная запись.

Фиксация в БД:
| Атрибут в `metadata_json` | Описание | Источник |
|---|---|---|
| `chunk_index` | порядковый номер чанка в файле | индекс чанка при нарезке |
| `chunk_type` | тип чанка, например функция, класс или текстовый блок | `CodeTextChunker` |
| `module_or_unit` | модуль, к которому относится chunk | вычисляется из пути файла |
| `is_test` | признак тестового файла | `is_test_path(path)` |

Связанные классы:
`CodeIndexingPipeline`, `CodeTextChunker`, `CodeTextDocumentBuilder`

### `C1_SYMBOL_CATALOG`

Задача:
Хранит символы кода: классы, функции и методы. Используется для поиска по именам и структуре кода.

Формирование:
Символы извлекаются `SymbolExtractor`, и каждый символ сохраняется как отдельная запись.

Фиксация в БД:
| Атрибут в `metadata_json` | Описание | Источник |
|---|---|---|
| `symbol_id` | идентификатор символа | `SymbolExtractor` |
| `qname` | полное квалифицированное имя | `SymbolExtractor` |
| `kind` | тип символа: класс, функция, метод | `SymbolExtractor` |
| `signature` | сигнатура символа | `SymbolExtractor` |
| `parent_symbol_id` | родительский символ | `SymbolExtractor` |
| `package_or_module` | модуль или пакет символа | вычисляется из пути файла |
| `is_test` | признак тестового файла | `is_test_path(path)` |

Связанные классы:
`CodeIndexingPipeline`, `PythonAstParser`, `SymbolExtractor`, `SymbolDocumentBuilder`

### `C2_DEPENDENCY_GRAPH`

Задача:
Хранит связи между символами кода: вызовы, импорты, наследование. Используется для анализа зависимостей и flow.

Формирование:
Связи строятся `EdgeExtractor` по AST и списку символов, после чего каждая связь сохраняется отдельной записью.

Фиксация в БД:
| Атрибут в `metadata_json` | Описание | Источник |
|---|---|---|
| `edge_id` | идентификатор связи | `EdgeExtractor` |
| `edge_type` | тип связи: вызов, импорт, наследование | `EdgeExtractor` |
| `src_symbol_id` | исходный символ | `EdgeExtractor` |
| `src_qname` | полное имя исходного символа | `EdgeExtractor` |
| `dst_symbol_id` | целевой символ, если он разрешен | `EdgeExtractor` |
| `dst_ref` | текстовая ссылка на целевой символ | `EdgeExtractor` |
| `resolution` | статус разрешения связи | `EdgeExtractor` |
| `is_test` | признак тестового файла | `is_test_path(path)` |

Связанные классы:
`CodeIndexingPipeline`, `EdgeExtractor`, `EdgeDocumentBuilder`

### `C3_ENTRYPOINTS`

Задача:
Хранит точки входа приложения: HTTP routes, CLI commands и другие entrypoints.

Формирование:
Детекторы ищут HTTP и CLI точки входа по символам файла, после чего каждый найденный entrypoint сохраняется отдельной записью.

Фиксация в БД:
| Атрибут в `metadata_json` | Описание | Источник |
|---|---|---|
| `entry_id` | идентификатор точки входа | detector entrypoint model |
| `entry_type` | тип точки входа | detector entrypoint model |
| `framework` | framework, в котором найдена точка входа | detector entrypoint model |
| `route_or_command` | route или команда | detector entrypoint model |
| `handler_symbol_id` | идентификатор обработчика | detector entrypoint model |
| `handler_symbol` | имя обработчика | detector entrypoint model |
| `declaring_symbol` | символ, в котором объявлен entrypoint | detector entrypoint model |
| `entrypoint_kind` | вид точки входа | detector entrypoint model |
| `http_method` | HTTP-метод | detector entrypoint model |
| `route_path` | путь маршрута | detector entrypoint model |
| `decorator_text` | текст декоратора или объявления | detector entrypoint model |
| `summary_text` | краткое описание точки входа | detector entrypoint model |
| `is_test` | признак тестового файла | `is_test_path(path)` |
| `lang_payload` | дополнительные данные детектора | detector metadata |
| `artifact_type` | тип артефакта, здесь `CODE` | константа builder |

Связанные классы:
`CodeIndexingPipeline`, `EntrypointDetectorRegistry`, `FastApiEntrypointDetector`, `FlaskEntrypointDetector`, `TyperClickEntrypointDetector`, `EntrypointDocumentBuilder`

### `C4_SEMANTIC_ROLES`

Задача:
Слой объявлен в enum и retrieval-планах как слой семантических ролей кода.

Формирование:
Слой формируется на основе символов, связей, dataflow slices и execution traces.
В текущем runtime этот слой не используется как активный маршрут, так как домен `CODE` отключен.

Фиксация в БД:
Смысловые атрибуты слоя сохраняются в `rag_chunks.metadata_json`.
Точное краткое описание состава этих атрибутов в текущем документе пока не зафиксировано.

Связанные классы:
`CodeIndexingPipeline`, `SemanticRoleBuilder`, `SemanticRoleDocumentBuilder`