--- ## id: arch-rag-package title: Пакет RAG doc_type: architecture_overview domain: rag status: draft owner: system-analyst source_of_truth: code related_docs: - logic-rag-indexing - logic-rag-retrieval - entity-rag-session - entity-rag-index-job - api-rag-session-create - api-rag-session-changes - api-rag-session-job related_code: - src/app/modules/rag/module.py - src/app/modules/rag/services/rag_service.py - src/app/modules/rag/indexing_service.py - src/app/modules/rag/persistence/repository.py - src/app/modules/rag/persistence/schema_repository.py entities: - RagSession - IndexJob - RagDocument tags: - rag - indexing - retrieval - architecture # Пакет RAG ## Summary - Scope: модуль индексации проектных файлов, хранения RAG-слоёв и выдачи retrieval-контекста. - Purpose: построить индекс по документации и Python-коду и дать runtime доступ к релевантным фрагментам. - Main modules: `RagModule`, `RagService`, `IndexingOrchestrator`, `RagRepository`, `RepoWebhookService`. - Main domains: RAG-сессии, задачи индексации, документы индекса, blob-cache, retrieval. - Main integrations: PostgreSQL/pgvector, GigaChat embeddings, FastAPI, EventBus, story context. - Key entrypoints: `/api/rag/sessions`, `/api/rag/sessions/{rag_session_id}/changes`, `/api/rag/sessions/{rag_session_id}/jobs/{index_job_id}`, `/internal/rag-repo/webhook`. - Key data flows: snapshot indexing, incremental reindex, retrieval из `rag_chunks`, webhook-нормализация коммитов. - Source of truth: код `src/app/modules/rag/*`. ## Назначение Пакет `rag` отвечает за полный цикл подготовки retrieval-контекста для проекта: принимает снапшоты и изменения файлов, преобразует их в набор атомарных `RagDocument`, векторизует, сохраняет в БД и предоставляет доступ к индексированным данным другим частям системы. ## Контекст Модуль используется как инфраструктурный слой для agent/runtime и смежных интеграций. На вход он принимает либо список файлов проекта, либо webhook репозитория. На выходе формирует устойчивый индекс, ассоциированный с `rag_session_id`, и статус задач индексации, пригодный для опроса и SSE-подписки. ## Границы системы ### In scope - Создание и хранение `RagSession`. - Постановка и выполнение задач snapshot/change indexing. - Индексация markdown-документации в слои `D1-D4`. - Индексация Python-кода в слои `C0-C4`. - Кэширование по `repo_id + blob_sha`. - Сохранение retrieval-документов в `rag_chunks`. - Выдача статуса задач и событий прогресса. - Нормализация webhook Gitea/Bitbucket и связывание коммитов со story. ### Out of scope - Финальная генерация ответа пользователю. - Оркестрация LLM-диалога. - Управление git-репозиторием и загрузка файлов из внешних источников. - Политики маршрутизации intent/runtime вне собственного persistence/retrieval API. ## Архитектурная схема `RagModule` собирает зависимости модуля и публикует HTTP endpoints. Для индексации он использует `RagSessionStore`, `IndexJobStore`, `IndexingOrchestrator` и `RagService`. `RagService` выбирает docs/code pipeline, обогащает документы метаданными файла, запрашивает embeddings и записывает результат через `RagRepository`. `RagRepository` агрегирует schema/session/job/document/cache/query репозитории. Отдельно `RagRepoModule` принимает repository webhooks и прокидывает нормализованный commit context в story storage и cache writer. ## Основные модули | module | responsibility | depends_on | key_code_refs | | ---------------------- | -------------------------------------------------------- | ------------------------------------------------------------------------ | ----------------------------------------------- | | `RagModule` | сборка зависимостей, публичный и internal API | `RagService`, `IndexingOrchestrator`, `RagSessionStore`, `IndexJobStore` | `src/app/modules/rag/module.py` | | `RagService` | синхронная бизнес-логика индексации файлов и cache reuse | docs/code pipeline, embedder, `RagRepository` | `src/app/modules/rag/services/rag_service.py` | | `IndexingOrchestrator` | асинхронный job lifecycle, retry, project lock, EventBus | `IndexJobStore`, `RagIndexer`, `EventBus`, `RetryExecutor` | `src/app/modules/rag/indexing_service.py` | | `DocsIndexingPipeline` | построение слоёв документации `D1-D4` | classifier, chunker, document builder | `src/app/modules/rag/indexing/docs/pipeline.py` | | `CodeIndexingPipeline` | построение слоёв кода `C0-C4` | AST parser, symbol/edge/entrypoint/role builders | `src/app/modules/rag/indexing/code/pipeline.py` | | `RagRepository` | единая точка persistence и retrieval | schema/session/job/document/cache/query repositories | `src/app/modules/rag/persistence/repository.py` | | `RepoWebhookService` | нормализация webhook payload и выделение story id | story writer, cache writer | `src/app/modules/rag/webhook_service.py` | ## Основные доменные области - RAG session как граница индекса конкретного проекта или его временного снапшота. - Index job как жизненный цикл асинхронной индексации и канал наблюдения за прогрессом. - RagDocument как атом индекса, который попадает в retrieval-хранилище и в cache. - Repo webhook context как источник commit metadata для story и cache. ## Основные интеграции | integration | direction | purpose | protocol / transport | related_docs | | ------------------------ | --------- | --------------------------------------------------- | ---------------------------------- | -------------------------------------------------------------------------- | | PostgreSQL + pgvector | outbound | хранение документов, jobs, sessions и vector search | SQLAlchemy / SQL / pgvector | `logic-rag-retrieval` | | GigaChat embeddings | outbound | получение embedding для batch документов | HTTP client через `GigaChatClient` | `logic-rag-indexing` | | FastAPI | inbound | публичный и internal API модуля | HTTP | `api-rag-session-create`, `api-rag-session-changes`, `api-rag-session-job` | | EventBus | outbound | публикация прогресса индексации и terminal events | in-process async events / SSE | `api-rag-session-job` | | Story context repository | outbound | запись webhook-коммитов для story | Python interface | `logic-rag-indexing` | ## Основные потоки ### Flow 1 1. Клиент вызывает `POST /api/rag/sessions` с `project_id` и snapshot файлов. 2. `RagSessionStore` создаёт `rag_session_id`, а `IndexingOrchestrator` создаёт `IndexJob`. 3. `RagService` фильтрует файлы, переиспользует cache по `blob_sha` или строит docs/code документы заново. 4. Документы векторизуются, записываются в `rag_chunks`, а job получает финальный статус `done` или `error`. ### Flow 2 1. Клиент вызывает `POST /api/rag/sessions/{rag_session_id}/changes`. 2. `IndexingOrchestrator` сериализует обработку по `rag_session_id`. 3. `RagService` удаляет документы по `delete_paths`, пересобирает upsert-файлы и применяет изменения к индексу. 4. Клиент читает статус и события задачи через job endpoints. ## Архитектурные решения и ограничения ### Key decisions - Snapshot и incremental indexing используют один и тот же `RagService`, различаясь только стратегией записи. - Кэш документов привязан к `repo_id + blob_sha`, а не к `rag_session_id`, что позволяет переиспользовать embeddings между сессиями одного проекта. - Документация и код индексируются разными pipeline, но сохраняются в общую таблицу `rag_chunks`. - Асинхронность вынесена в `IndexingOrchestrator`, чтобы `RagService` оставался application-service без управления job lifecycle. ### Constraints - Code indexing поддерживает только Python-файлы. - Docs indexing ориентирован на markdown и frontmatter YAML. - Deprecated endpoint `/internal/rag/retrieve` не используется для рабочего retrieval. - Реальное retrieval API доступно через repository/runtime adapters, а не через публичный HTTP endpoint модуля. ### Risks - Ошибки embeddings или временные сетевые сбои переводят job в `error` только после исчерпания retry. - Полное `replace_documents` для snapshot удаляет все документы сессии перед вставкой новых. - Retrieval ranking завязан на SQL-эвристики по layer, lexical match и metadata, поэтому качество зависит от корректности metadata builders. ## Нефункциональные аспекты ### Security - Публичные endpoints не содержат собственной бизнес-авторизации внутри модуля и полагаются на внешний слой приложения. - Webhook provider определяется по headers/payload без явной проверки подписи в самом `RepoWebhookService`. ### Reliability - Проектный `asyncio.Lock` предотвращает параллельную индексацию одной `rag_session`. - `RetryExecutor` повторяет временные сбои индексации. ### Observability - Logs: `RagService` пишет предупреждения по cache hit/miss и skipped files. - Metrics: явные метрики не выделены. - Traces: явная трассировка не реализована. - Audit: job status и webhook commit binding сохраняются в БД. ### Performance - Embeddings отправляются батчами с размером из `RAG_EMBED_BATCH_SIZE`. - Cache reuse исключает повторную векторизацию неизменённых blob. ### Scalability - Индекс хранится на уровне SQL-таблиц с векторными полями и индексами по session/layer/path. - При росте объёма данных узким местом остаются полнотабличные delete/insert по snapshot и SQL sorting retrieval. ## Связанные сущности - `RagSession` - `IndexJob` - `RagDocument` ## Связанный код ### Files - `src/app/modules/rag/module.py` - `src/app/modules/rag/services/rag_service.py` - `src/app/modules/rag/indexing_service.py` - `src/app/modules/rag/persistence/repository.py` - `src/app/modules/rag/persistence/schema_repository.py` - `src/app/modules/rag/webhook_service.py` ### Symbols - `RagModule` - `RagRepoModule` - `RagService` - `IndexingOrchestrator` - `RagRepository` - `RepoWebhookService` ## Связанные документы - `logic-rag-indexing` - `logic-rag-retrieval` - `entity-rag-session` - `entity-rag-index-job` - `api-rag-session-create` - `api-rag-session-changes` - `api-rag-session-job` ## История изменений | Date | Source | Changes | | ---------- | ------ | ------------------------------------------------------------------- | | 2026-03-13 | code | Создан обзор архитектуры пакета `rag` на основе текущей реализации. |