agent/app/modules/rag_session/README.md

# Модуль rag_session

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

## 2. Диаграмма классов и взаимосвязей
```mermaid
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` и запускает фоновую индексацию полного набора файлов.
```mermaid
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`.
```mermaid
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}
Назначение: возвращает состояние и статистику конкретной задачи индексации.
```mermaid
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-поток событий прогресса по задаче индексации.
```mermaid
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`.
```mermaid
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`.
```mermaid
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`.
```mermaid
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.
```mermaid
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
Назначение: внутренний синхронный запуск полной индексации для сервисных сценариев.
```mermaid
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
Назначение: внутренний синхронный запуск индексации изменений.
```mermaid
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 для сервисов оркестрации.
```mermaid
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` по текстовому запросу.
```mermaid
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
```