Роутер работает нормально в process v2

_process/03. RAG.md

@@ -0,0 +1,356 @@
+# 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, fallback title, summary и doc kind, вычисленный классификатором документации.
+Данные извлекаются структурированно по атрибутам.
+В `content` попадает summary документа, а не склейка всех частей документа в сплошной текст.
+
+Фиксация в БД:
+| Атрибут в `metadata_json` | Описание | Источник |
+|---|---|---|
+| `document_id` | идентификатор документа | `frontmatter.id`, иначе путь файла |
+| `type` | тип документа из frontmatter | `frontmatter.type` |
+| `name` | системное имя документа | `frontmatter.name` |
+| `title` | человекочитаемый заголовок документа | `frontmatter.title`, иначе fallback title |
+| `module` | модуль документа | `frontmatter.module` |
+| `domain` | домен документа | `frontmatter.domain` |
+| `subdomain` | поддомен документа | `frontmatter.subdomain` |
+| `layer` | логический слой, указанный в frontmatter документа | `frontmatter.layer` |
+| `status` | статус документа | `frontmatter.status` |
+| `updated_at` | дата или отметка последнего обновления | `frontmatter.updated_at` |
+| `tags` | теги документа | `frontmatter.tags` |
+| `entities` | сущности, связанные с документом | `frontmatter.entities` |
+| `parent` | родительский документ | `frontmatter.parent` |
+| `children` | дочерние документы | `frontmatter.children` |
+| `links` | ссылки на связанные материалы | `frontmatter.links` |
+| `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`