---

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


