agent/docs/documentation/rag/architecture-overview.md

---

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.
• 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}, /api/rag/sessions/{rag_session_id}/jobs/{index_job_id}/events.
• Key data flows: snapshot indexing, incremental reindex, retrieval из rag_chunks.
• Source of truth: код src/app/modules/rag/*.

Назначение

Пакет rag отвечает за полный цикл подготовки retrieval-контекста для проекта: принимает снапшоты и изменения файлов, преобразует их в набор атомарных RagDocument, векторизует, сохраняет в БД и предоставляет доступ к индексированным данным другим частям системы.

Контекст

Модуль используется как инфраструктурный слой для agent/runtime. На вход он принимает snapshot и изменения файлов проекта. На выходе формирует устойчивый индекс, ассоциированный с 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 репозитории.

Основные модули

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

Основные доменные области

• 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	публичный HTTP 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

Основные потоки

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.
• HTTP retrieval endpoint в модуле не публикуется.
• Реальное 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 не содержат собственной бизнес-авторизации внутри модуля и полагаются на внешний слой приложения.

Reliability

• Проектный asyncio.Lock предотвращает параллельную индексацию одной rag_session.
• RetryExecutor повторяет временные сбои индексации.

Observability

• Logs: RagService пишет предупреждения по cache hit/miss и skipped files.
• Metrics: явные метрики не выделены.
• Traces: явная трассировка не реализована.
• Audit: job status сохраняется в БД.

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

Symbols

• RagModule
• RagService
• IndexingOrchestrator
• RagRepository

Связанные документы

• 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 на основе текущей реализации.