agent/_process/03. RAG.md

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