# Модуль rag

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

## 2. Диаграмма классов и взаимосвязей
```mermaid
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` и построить многослойный индекс по переданным файлам проекта.
```mermaid
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
Назначение: вернуть релевантный контекст из нужного семейства слоев.
```mermaid
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`.
```mermaid
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`.