Создание и обслуживание сессионного RAG индекса по загруженным пользователем файлам.
Индексация снапшота и инкрементальных изменений.
Хранение чанков, retrieval контекста, трекинг статуса index jobs.
Публикация прогресса индексации через SSE.

2. Диаграмма классов и взаимосвязей

classDiagram
    class RagModule
    class RagService
    class RagRepository
    class RagSessionStore
    class IndexJobStore
    class IndexingOrchestrator
    class TextChunker
    class GigaChatEmbedder
    class EventBus

    RagModule --> RagService
    RagModule --> RagRepository
    RagModule --> RagSessionStore
    RagModule --> IndexJobStore
    RagModule --> IndexingOrchestrator
    RagService --> RagRepository
    RagService --> TextChunker
    RagService --> GigaChatEmbedder
    IndexingOrchestrator --> IndexJobStore
    IndexingOrchestrator --> RagService
    IndexingOrchestrator --> EventBus

3. Описание классов

RagModule: composition-root для сессионного RAG и его API. Методы: __init__ — собирает сервисы индексации/retrieval; public_router — публикует внешние endpoint'ы; internal_router — публикует внутренние endpoint'ы.
RagService: доменный сервис индексации и retrieval. Методы: index_snapshot — индексирует полный набор файлов; index_changes — индексирует только изменения; retrieve — возвращает релевантные чанки по запросу.
RagRepository: слой доступа к БД для сессий, джобов и чанков. Методы: ensure_tables — создает/обновляет схему; upsert_session/get_session/session_exists — операции по сессиям; create_job/update_job/get_job — операции по задачам индексации; replace_chunks/apply_changes/retrieve/fallback_chunks — операции по chunk-данным.
RagSessionStore: управление жизненным циклом rag_session. Методы: create — создает новую сессию; put — upsert с внешним id; get — читает сессию.
IndexJobStore: управление index_job на уровне приложения. Методы: create — создает задачу индексации; get — читает задачу; save — обновляет статус/ошибку.
IndexingOrchestrator: асинхронный оркестратор index-jobs. Методы: enqueue_snapshot — ставит полную индексацию в очередь; enqueue_changes — ставит инкрементальную индексацию в очередь.
TextChunker: разбивает текст файла на чанки для embedding. Методы: chunk — возвращает список чанков заданного текста.
GigaChatEmbedder: адаптер embeddings-модели. Методы: embed — возвращает векторы для набора текстов.
EventBus: доставка событий прогресса индексации. Методы: publish — отправляет событие; subscribe/unsubscribe — управляет подписками SSE.

4. Сиквенс-диаграммы API

POST /api/rag/sessions

Назначение: создает новую rag_session и запускает фоновую индексацию полного набора файлов.

sequenceDiagram
    participant Router as RagModule.APIRouter
    participant Sessions as RagSessionStore
    participant Indexing as IndexingOrchestrator

    Router->>Sessions: create(project_id)
    Sessions-->>Router: rag_session_id
    Router->>Indexing: enqueue_snapshot(rag_session_id, files)
    Indexing-->>Router: index_job_id,status

POST /api/rag/sessions/{rag_session_id}/changes

Назначение: ставит в очередь инкрементальную переиндексацию изменений для существующей rag_session.

sequenceDiagram
    participant Router as RagModule.APIRouter
    participant Sessions as RagSessionStore
    participant Indexing as IndexingOrchestrator

    Router->>Sessions: get(rag_session_id)
    Sessions-->>Router: session
    Router->>Indexing: enqueue_changes(rag_session_id, changed_files)
    Indexing-->>Router: index_job_id,status

GET /api/rag/sessions/{rag_session_id}/jobs/{index_job_id}

Назначение: возвращает состояние и статистику конкретной задачи индексации.

sequenceDiagram
    participant Router as RagModule.APIRouter
    participant Jobs as IndexJobStore

    Router->>Jobs: get(index_job_id)
    Jobs-->>Router: job_state

GET /api/rag/sessions/{rag_session_id}/jobs/{index_job_id}/events

Назначение: дает SSE-поток событий прогресса по задаче индексации.

sequenceDiagram
    participant Router as RagModule.APIRouter
    participant Jobs as IndexJobStore
    participant Events as EventBus

    Router->>Jobs: get(index_job_id)
    Router->>Events: subscribe(index_job_id, replay=True)
    loop until terminal
        Events-->>Router: index event
    end
    Router->>Events: unsubscribe(index_job_id)

POST /api/index/snapshot (legacy)

Назначение: legacy-вход для полной индексации проекта с автоматическим созданием сессии по project_id.

sequenceDiagram
    participant Router as LegacyAPIRouter
    participant Sessions as RagSessionStore
    participant Indexing as IndexingOrchestrator

    Router->>Sessions: put(project_id, project_id)
    Router->>Indexing: enqueue_snapshot(project_id, files)
    Indexing-->>Router: index_job_id,status

POST /api/index/changes (legacy)

Назначение: legacy-вход для инкрементальной индексации изменений по project_id.

sequenceDiagram
    participant Router as LegacyAPIRouter
    participant Sessions as RagSessionStore
    participant Indexing as IndexingOrchestrator

    Router->>Sessions: get(project_id)
    alt missing
        Router->>Sessions: put(project_id, project_id)
    end
    Router->>Indexing: enqueue_changes(project_id, changed_files)
    Indexing-->>Router: index_job_id,status

GET /api/index/jobs/{index_job_id} (legacy)

Назначение: legacy-чтение статуса index-job по index_job_id.

sequenceDiagram
    participant Router as LegacyAPIRouter
    participant Jobs as IndexJobStore

    Router->>Jobs: get(index_job_id)
    Jobs-->>Router: job_state

GET /api/index/jobs/{index_job_id}/events (legacy)

Назначение: legacy-SSE поток событий по index-job.

sequenceDiagram
    participant Router as LegacyAPIRouter
    participant Jobs as IndexJobStore
    participant Events as EventBus

    Router->>Jobs: get(index_job_id)
    Router->>Events: subscribe(index_job_id, replay=True)
    loop until terminal
        Events-->>Router: index event
    end
    Router->>Events: unsubscribe(index_job_id)

POST /internal/rag/index/snapshot

Назначение: внутренний синхронный запуск полной индексации для сервисных сценариев.

sequenceDiagram
    participant Router as InternalRagRouter
    participant Sessions as RagSessionStore
    participant RagService as RagService

    Router->>Sessions: get(project_id)
    alt missing
        Router->>Sessions: put(project_id, project_id)
    end
    Router->>RagService: index_snapshot(project_id, files)
    RagService-->>Router: indexed_files,failed_files

POST /internal/rag/index/changes

Назначение: внутренний синхронный запуск индексации изменений.

sequenceDiagram
    participant Router as InternalRagRouter
    participant RagService as RagService

    Router->>RagService: index_changes(project_id, changed_files)
    RagService-->>Router: indexed_files,failed_files

GET /internal/rag/index/jobs/{index_job_id}

Назначение: внутреннее получение статуса и ошибки index-job для сервисов оркестрации.

sequenceDiagram
    participant Router as InternalRagRouter
    participant Jobs as IndexJobStore

    Router->>Jobs: get(index_job_id)
    Jobs-->>Router: job_state

POST /internal/rag/retrieve

Назначение: внутренний retrieval релевантных чанков из rag_session по текстовому запросу.

sequenceDiagram
    participant Router as InternalRagRouter
    participant RagService as RagService
    participant RagRepo as RagRepository

    Router->>RagService: retrieve(rag_session_id, query)
    RagService->>RagRepo: retrieve/fallback_chunks
    RagRepo-->>RagService: chunks
    RagService-->>Router: items

README.md Unescape Escape

Модуль rag_session

1. Функции модуля