agent/docs/documentation/rag/api-rag-session-job.md

id, title, doc_type, domain, status, owner, source_of_truth, related_docs, related_code, entities, tags

id	title	doc_type	domain	status	owner	source_of_truth	related_docs	related_code	entities	tags
api-rag-session-job	Получение статуса и событий задачи индексации	api_method	rag	draft	system-analyst	code	arch-rag-package entity-rag-session entity-rag-index-job	src/app/modules/rag/module.py src/app/modules/rag/job_store.py src/app/schemas/rag_sessions.py	RagSession IndexJob	rag api job-status sse

Получение статуса и событий задачи индексации

Summary

• Purpose: отдать текущее состояние job и поток событий её выполнения в рамках конкретной RagSession.
• Actor: внешний клиент модуля RAG.
• Trigger: polling или live-monitoring после запуска snapshot/change indexing.
• Endpoint: GET /api/rag/sessions/{rag_session_id}/jobs/{index_job_id} и GET /api/rag/sessions/{rag_session_id}/jobs/{index_job_id}/events
• Main entities: RagSession, IndexJob.
• Main logic: чтение job по id, проверка принадлежности сессии, возврат status payload или SSE stream.
• Main errors: not_found при отсутствии job или несовпадении rag_session_id.
• Source of truth: src/app/modules/rag/module.py, src/app/modules/rag/job_store.py.

Назначение

Документ описывает два связанных метода наблюдения: синхронный status endpoint и потоковый SSE endpoint. Оба работают поверх одной сущности IndexJob.

Контекст

Create и changes endpoints возвращают только стартовый статус задачи, поэтому клиенту нужны отдельные методы для отслеживания выполнения. SSE-поток даёт live progress, а status endpoint нужен для простого polling.

Технический use case

Основной сценарий

1. Клиент вызывает status endpoint или открывает SSE stream по index_job_id.
2. Endpoint читает job из IndexJobStore.
3. Если job отсутствует или принадлежит другой rag_session_id, возвращается not_found.
4. Status endpoint отдаёт снимок counters и error payload.
5. SSE endpoint подписывается на EventBus c replay=True и транслирует index_status, index_progress, terminal.

Альтернативные ветки

• При отсутствии новых событий SSE endpoint каждые 10 секунд отправляет : keepalive.
• После события terminal поток завершается и отписывается от EventBus.

Функциональные требования

Request validation

• rag_session_id и index_job_id обязательны как path parameters.
• Job должна существовать и принадлежать переданной сессии.

Processing rules

• Status endpoint не подписывается на события и читает только текущее состояние job.
• SSE endpoint использует replay=True, чтобы клиент получил уже опубликованные события.
• Оба метода защищают от доступа к job другой сессии.

State changes

• Методы не меняют состояние job.

Side effects

• SSE endpoint создаёт временную подписку на EventBus.
• При завершении или разрыве соединения выполняется unsubscribe.

Contract

Endpoint

• Method: GET
• Path: /api/rag/sessions/{rag_session_id}/jobs/{index_job_id} и /api/rag/sessions/{rag_session_id}/jobs/{index_job_id}/events
• Auth: определяется внешним слоем приложения.
• Idempotent: да.
• Timeout: status endpoint короткий; SSE stream долгоживущий.
• Retry: polling можно повторять безопасно; SSE можно переподключать.

Request

Field	Type	Required	Constraints	Description
rag_session_id	string	yes	path param	идентификатор сессии
index_job_id	string	yes	path param	идентификатор задачи

Response

Field	Type	Description
rag_session_id	string	идентификатор сессии, только для status endpoint
index_job_id	string	идентификатор задачи
status	IndexJobStatus	текущее состояние job
indexed_files	integer	число успешно обработанных файлов
failed_files	integer	число файлов с ошибками
cache_hit_files	integer	число cache hit
cache_miss_files	integer	число cache miss
error	object | null	ошибка, если job завершилась с error

External contract refs

• OpenAPI: status endpoint использует response_model=RagSessionJobResponse; SSE endpoint отдаёт text/event-stream.
• Schema: RagSessionJobResponse.
• DTO / serializer: src/app/schemas/rag_sessions.py.
• Additional refs: entity-rag-index-job.

Errors

error_id	http_code	when	client_behavior	retry
not_found	404	job отсутствует или не принадлежит переданной сессии	проверить id или создать новую задачу	no

Нефункциональные требования

Security

• Проверка job.rag_session_id == rag_session_id обязательна для обоих методов.

Observability

• Logs: отдельные логи чтения статуса не реализованы.
• Metrics: отсутствуют.
• Traces: отсутствуют.
• Audit: история job хранится в rag_index_jobs, поток событий в памяти EventBus.

Reliability

• SSE heartbeat удерживает соединение активным.
• finally блок гарантирует unsubscribe.

Performance

• Status endpoint работает как лёгкий запрос к БД.
• SSE stream масштабируется числом активных подписчиков и объёмом событий.

Связанные блоки логики

• logic-rag-indexing

Связанные сущности

• RagSession
• IndexJob

Связанный код

Files

• src/app/modules/rag/module.py
• src/app/modules/rag/job_store.py
• src/app/schemas/rag_sessions.py

Symbols

• RagModule.public_router.rag_session_job
• RagModule.public_router.rag_session_job_events
• IndexJobStore.get

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

• arch-rag-package
• entity-rag-session
• entity-rag-index-job

История изменений

Date	Source	Changes
2026-03-13	code	Задокументированы status и SSE endpoints для наблюдения за indexing job.