agent/docs/documentation/rag/api-rag-session-changes.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-changes	Применение изменений к RAG-сессии	api_method	rag	draft	system-analyst	code	arch-rag-package logic-rag-indexing entity-rag-session entity-rag-index-job	src/app/modules/rag/module.py src/app/schemas/rag_sessions.py src/app/schemas/indexing.py	RagSession IndexJob	rag api changes incremental-indexing

Применение изменений к RAG-сессии

Summary

• Purpose: поставить incremental indexing для уже существующей RagSession.
• Actor: внешний клиент модуля RAG.
• Trigger: частичное обновление индекса после изменения файлов.
• Endpoint: POST /api/rag/sessions/{rag_session_id}/changes
• Main entities: RagSession, IndexJob.
• Main logic: проверка существования сессии, создание change job, асинхронная обработка upsert/delete.
• Main errors: not_found для отсутствующей сессии, 422 для некорректного payload.
• Source of truth: src/app/modules/rag/module.py, src/app/schemas/rag_sessions.py.

Назначение

Метод позволяет обновить индекс без полной переиндексации проекта. Он принимает только изменённые файлы и операции удаления.

Контекст

Endpoint относится к новому API с явной работой через rag_session_id. В отличие от legacy /api/index/changes, он не создаёт сессию молча и требует, чтобы она уже существовала.

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

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

1. Клиент передаёт rag_session_id в path и список changed_files в body.
2. Endpoint проверяет наличие сессии через RagSessionStore.get.
3. При успехе IndexingOrchestrator.enqueue_changes создаёт новую job и запускает фоновое применение изменений.
4. API возвращает index_job_id и стартовый статус.

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

• Если rag_session_id не найдена, endpoint бросает AppError("not_found", ...).
• Для op=delete в последующей логике происходит удаление документов по пути без повторной генерации embeddings.

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

Request validation

• Path parameter rag_session_id обязателен.
• changed_files обязателен и состоит из элементов ChangedFile.
• Для каждого элемента обязательны op и path.
• op допускает только upsert или delete.

Processing rules

• Сессия должна существовать до постановки change job.
• Каждый вызов создаёт новый IndexJob.
• Фактическое применение изменений выполняется асинхронно.

State changes

• В rag_index_jobs появляется новая задача.
• Сам индекс меняется позже, внутри RagService.index_changes.

Side effects

• Публикация job events.
• Удаление документов по delete_paths и upsert новых документов в фоне.

Contract

Endpoint

• Method: POST
• Path: /api/rag/sessions/{rag_session_id}/changes
• Auth: определяется внешним слоем приложения.
• Idempotent: нет, повторный вызов создаёт новую job.
• Timeout: короткий, endpoint не дожидается завершения индексации.
• Retry: только если клиент готов к созданию дополнительной job.

Request

Field	Type	Required	Constraints	Description
rag_session_id	string	yes	path param, non-empty	идентификатор существующей RAG-сессии
changed_files	array<ChangedFile>	yes	схема каждого элемента обязательна	изменения файлов
changed_files[].op	enum	yes	upsert or delete	тип операции
changed_files[].path	string	yes	min_length=1	путь файла
changed_files[].content	string | null	no	нужен для upsert	содержимое файла
changed_files[].content_hash	string | null	no	повышает cache reuse	hash содержимого

Response

Field	Type	Description
index_job_id	string	идентификатор фоновой задачи
status	string	стартовый статус задачи

External contract refs

• OpenAPI: формируется FastAPI по response_model=IndexJobQueuedResponse.
• Schema: RagSessionChangesRequest, ChangedFile, IndexJobQueuedResponse.
• DTO / serializer: src/app/schemas/rag_sessions.py, src/app/schemas/indexing.py.
• Additional refs: logic-rag-indexing.

Errors

error_id	http_code	when	client_behavior	retry
not_found	404	rag_session_id отсутствует	создать новую сессию или исправить id	no
validation_error	422	нарушена схема request	исправить payload	no

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

Security

• Метод доверяет внешнему слою авторизации.

Observability

• Logs: прямое логирование endpoint отсутствует.
• Metrics: нет отдельной метрики на уровне метода.
• Traces: отсутствуют.
• Audit: каждая операция материализуется в IndexJob.

Reliability

• Проверка существования сессии защищает от случайной записи в неинициализированный scope.
• Ошибки индексации доступны через job status и SSE events.

Performance

• Быстрый ответ за счёт фонового выполнения.

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

• logic-rag-indexing

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

• RagSession
• IndexJob

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

Files

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

Symbols

• RagModule.public_router.rag_session_changes
• RagSessionStore.get
• IndexingOrchestrator.enqueue_changes

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

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

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

Date	Source	Changes
2026-03-13	code	Задокументирован публичный endpoint incremental indexing для существующей сессии.