Новый раг

2026-03-01 14:21:33 +03:00
parent 2728c07ba9
commit 1ef0b4d68c
95 changed files with 3145 additions and 927 deletions
--- a/app/modules/rag/README.md
+++ b/app/modules/rag/README.md
@@ -0,0 +1,300 @@
+# Модуль 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
+```
+
+## 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`.