agent/app/modules/rag/README.md

Модуль rag

1. Функции модуля

• Единое ядро RAG для индексации и retrieval по документации и коду проекта.
• Поддержка двух семейств индексации: DOCS и CODE, с разными слоями и разными pipeline.
• Хранение rag_session, index-jobs, многослойных документов, cache-слоев и retrieval-запросов.
• Поддержка индексации snapshot и changes с переиспользованием cache по blob_sha.
• Предоставление контекста для agent/chat, где DOCS используется по умолчанию, а CODE включается для явных вопросов по реализации.

2. Диаграмма классов и взаимосвязей

classDiagram
    class RagService
    class RagRepository
    class RagSchemaRepository
    class RagDocumentUpserter
    class DocsIndexingPipeline
    class CodeIndexingPipeline
    class RagQueryRouter
    class GigaChatEmbedder

    RagService --> RagRepository
    RagService --> DocsIndexingPipeline
    RagService --> CodeIndexingPipeline
    RagService --> RagQueryRouter
    RagService --> GigaChatEmbedder
    RagRepository --> RagSchemaRepository
    RagService --> RagDocumentUpserter

3. Описание классов

• RagService: основной application-service модуля. Методы: index_snapshot — индексирует полный набор файлов; index_changes — применяет инкрементальные изменения; retrieve — возвращает релевантный контекст из DOCS или CODE.
• RagRepository: фасад persistence-слоя RAG. Методы: ensure_tables — создает/обновляет схему; upsert_session/get_session/session_exists — операции по rag_session; create_job/update_job/get_job — операции по index jobs; replace_documents/apply_document_changes — операции по документам; get_cached_documents/cache_documents — работа с cache; retrieve/fallback_chunks — retrieval.
• RagSchemaRepository: управление схемой БД для RAG. Методы: ensure_tables — создает таблицы и индексы; _ensure_columns — добавляет новые поля; _ensure_indexes — поддерживает индексы для retrieval и фильтрации.
• RagDocumentUpserter: батчевый writer многослойных RagDocument. Методы: replace — полностью заменяет документы сессии; apply_changes — применяет upsert/delete по измененным путям.
• DocsIndexingPipeline: pipeline индексации документации. Методы: supports — определяет, относится ли файл к docs; index_file — строит документы слоев D1-D4 для одного файла.
• CodeIndexingPipeline: pipeline индексации Python-кода. Методы: supports — определяет, относится ли файл к code; index_file — строит документы слоев C0-C3 для одного файла.
• RagQueryRouter: выбирает retrieval mode и активные слои. Методы: resolve_mode — определяет docs или code; layers_for_mode — возвращает набор слоев для retrieval.
• GigaChatEmbedder: адаптер embeddings-модели. Методы: embed — возвращает embeddings для списка текстов.

4. Сиквенс-диаграммы API и выполнения

Индексация snapshot через текущий rag_session facade

Назначение: создать/обновить rag_session и построить многослойный индекс по переданным файлам проекта.

sequenceDiagram
    participant Router as RagModule.APIRouter
    participant Sessions as RagSessionStore
    participant Indexing as IndexingOrchestrator
    participant Rag as RagService
    participant Docs as DocsIndexingPipeline
    participant Code as CodeIndexingPipeline
    participant Repo as RagRepository

    Router->>Sessions: create(project_id)
    Sessions-->>Router: rag_session_id
    Router->>Indexing: enqueue_snapshot(rag_session_id, files)
    Indexing->>Rag: index_snapshot(rag_session_id, files)
    loop for each file
        Rag->>Docs: supports/index_file
        Rag->>Code: supports/index_file
        Rag->>Repo: cache_documents(...)
    end
    Rag->>Repo: replace_documents(...)
    Indexing-->>Router: index_job_id,status

Retrieval для agent/chat

Назначение: вернуть релевантный контекст из нужного семейства слоев.

sequenceDiagram
    participant Agent as GraphAgentRuntime
    participant Rag as RagService
    participant Router as RagQueryRouter
    participant Repo as RagRepository

    Agent->>Rag: retrieve(rag_session_id, query)
    Rag->>Router: resolve_mode(query)
    Router-->>Rag: docs|code + layers
    Rag->>Repo: retrieve(query_embedding, query_text, layers)
    Repo-->>Rag: ranked items
    Rag-->>Agent: items

Retrieval + project/qa reasoning

Назначение: RAG вызывается не в начале runtime, а внутри отдельного graph-шага context_retrieval для project/qa.

sequenceDiagram
    participant Agent as GraphAgentRuntime
    participant Orch as OrchestratorService
    participant G1 as conversation_understanding
    participant G2 as question_classification
    participant G3 as context_retrieval
    participant Rag as RagService
    participant G4 as context_analysis
    participant G5 as answer_composition

    Agent->>Orch: run(task)
    Orch->>G1: execute
    G1-->>Orch: resolved_request
    Orch->>G2: execute
    G2-->>Orch: question_profile
    Orch->>G3: execute
    G3->>Rag: retrieve(query)
    Rag-->>G3: rag_items
    G3-->>Orch: source_bundle
    Orch->>G4: execute
    G4-->>Orch: analysis_brief
    Orch->>G5: execute
    G5-->>Orch: final_answer
    Orch-->>Agent: final_answer

Для project/qa это означает:

• ранний глобальный retrieval больше не нужен;
• RAG возвращает записи только для конкретного шага context_retrieval;
• оркестратор управляет цепочкой graph-шагов;
• пользовательский ответ собирается после анализа, а не напрямую из сырого retrieval.

5. Слои, фиксируемые в RAG

5.1. Слои DOCS

D1_MODULE_CATALOG

Назначение: каталог модулей документации и граф связей между ними.

Основные атрибуты:

• module_id
• type
• domain
• title
• status
• version
• tags
• owners
• links
• calls_api
• called_by
• uses_logic
• used_by
• reads_db
• writes_db
• integrates_with
• emits_events
• consumes_events
• source_path
• summary_text

D2_FACT_INDEX

Назначение: атомарные факты subject-predicate-object с evidence.

Основные атрибуты:

• fact_id
• subject_id
• predicate
• object
• object_ref
• source_path
• anchor
• line_start
• line_end
• confidence
• tags

D3_SECTION_INDEX

Назначение: семантические секции документации, нарезанные по заголовкам.

Основные атрибуты:

• chunk_id
• module_id
• section_path
• section_title
• content
• source_path
• order
• tags
• domain
• type
• embedding

D4_POLICY_INDEX

Назначение: глобальные правила и конвенции проекта.

Основные атрибуты:

• policy_id
• applies_to
• rules
• default_behaviors
• source_path

5.2. Слои CODE

C0_SOURCE_CHUNKS

Назначение: сырой код как источник истины для цитирования и evidence.

Основные атрибуты:

• lang
• repo_id
• commit_sha
• path
• span
• title
• text
• module_or_unit
• chunk_type
• symbol_id
• hash

C1_SYMBOL_CATALOG

Назначение: каталог символов кода и их деклараций.

Основные атрибуты:

• lang
• repo_id
• commit_sha
• symbol_id
• qname
• kind
• decl.path
• decl.start_line
• decl.end_line
• text
• visibility
• signature
• decorators_or_annotations
• docstring_or_javadoc
• parent_symbol_id
• package_or_module
• is_entry_candidate
• lang_payload

C2_DEPENDENCY_GRAPH

Назначение: связи между сущностями кода.

Основные атрибуты:

• lang
• repo_id
• commit_sha
• edge_id
• edge_type
• src_symbol_id
• dst_symbol_id
• dst_ref
• evidence.path
• evidence.start_line
• evidence.end_line
• text
• resolution
• callsite_kind
• lang_payload

C3_ENTRYPOINTS

Назначение: точки входа приложения и их обработчики.

Основные атрибуты:

• lang
• repo_id
• commit_sha
• entry_id
• entry_type
• framework
• route_or_command
• handler_symbol_id
• evidence.path
• evidence.start_line
• evidence.end_line
• text
• http.methods
• http.auth
• request_model
• response_model
• cli.args_schema
• task.queue
• task.cron
• tags
• lang_payload

C4_PUBLIC_API

Назначение: публичная поверхность API/экспортируемых символов.

Основные атрибуты:

• api_id
• symbol_id
• stability
• source_of_truth
• versioning_tags
• lang_payload

C5_BEHAVIOR_SUMMARIES

Назначение: поведенческие summary с обязательными evidence links.

Основные атрибуты:

• target_type
• target_id
• text
• claims
• evidence_links
• confidence
• generated_by
• generated_at

C6_RUNTIME_TRACES

Назначение: runtime/trace слой для связи кода и реального исполнения.

Основные атрибуты:

• env
• trace_id
• span_id
• symbol_id
• entry_id
• text
• timings
• service
• host
• labels

6. Правила retrieval

• По умолчанию retrieval идет в DOCS.
• CODE используется только для явных вопросов по реализации, устройству кода, endpoint'ам, handler'ам и документации “из кода”.
• Для DOCS приоритет слоев: D1 -> D2 -> D3 -> D4.
• Для CODE приоритет слоев: C3 -> C1 -> C2 -> C0.

7. Текущий статус реализации

• В первой итерации реализованы DOCS D1-D4.
• В первой итерации реализованы CODE C0-C3.
• C4-C6 зафиксированы в контракте и зарезервированы под следующие этапы.
• Текущие rag_session и rag_repo работают как facade/adapter поверх нового пакета rag.