agent/docs/documentation/rag/api-rag-session-create.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-create	Создание RAG-сессии и запуск snapshot-индексации	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 session snapshot

Создание RAG-сессии и запуск snapshot-индексации

Summary

• Purpose: создать новую RagSession и асинхронно поставить полную индексацию snapshot-файлов.
• Actor: внешний клиент модуля RAG.
• Trigger: первичная загрузка файлов проекта в индекс.
• Endpoint: POST /api/rag/sessions
• Main entities: RagSession, IndexJob.
• Main logic: создание UUID-сессии, постановка snapshot job, возврат идентификаторов сессии и job.
• Main errors: в коде endpoint нет собственной бизнес-валидации сверх pydantic; ошибки индексации проявляются позже в job status.
• Source of truth: src/app/modules/rag/module.py, src/app/schemas/rag_sessions.py.

Назначение

Метод открывает новую RAG-сессию и запускает первичную индексацию файлов. Он используется как основной публичный вход для нового API пакета rag.

Контекст

В отличие от legacy /api/index/snapshot, этот endpoint всегда создаёт новый rag_session_id, что позволяет независимо хранить несколько снимков одного проекта.

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

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

1. Клиент передаёт project_id и массив files.
2. RagSessionStore.create создаёт новую запись в rag_sessions.
3. IndexingOrchestrator.enqueue_snapshot создаёт IndexJob и запускает фоновую обработку.
4. API сразу возвращает rag_session_id, index_job_id и стартовый статус.

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

• Если часть файлов не подлежит индексации, они будут отфильтрованы уже внутри indexing pipeline, а не на этапе ответа API.
• Ошибки индексации не меняют синхронный ответ create endpoint, а отражаются в последующем статусе job.

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

Request validation

• project_id обязателен и не может быть пустым.
• files передаются списком объектов FileSnapshot.
• Для каждого файла обязательны path, content, content_hash.

Processing rules

• На каждый вызов создаётся новая RagSession.
• Snapshot job создаётся сразу после сохранения сессии.
• Ответ не ждёт завершения индексации.

State changes

• В rag_sessions появляется новая запись.
• В rag_index_jobs появляется новая запись в статусе queued.

Side effects

• Запуск фоновой asyncio task.
• Последующая публикация progress events в EventBus.

Contract

Endpoint

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

Request

Field	Type	Required	Constraints	Description
project_id	string	yes	min_length=1	идентификатор проекта
files	array<FileSnapshot>	yes	может быть пустым, но схема обязана соблюдаться	snapshot файлов для первичной индексации
files[].path	string	yes	min_length=1	путь файла
files[].content	string	yes	без дополнительных ограничений	содержимое файла
files[].content_hash	string	yes	min_length=1	hash содержимого для cache reuse

Response

Field	Type	Description
rag_session_id	string	идентификатор созданной сессии
index_job_id	string	идентификатор фоновой задачи индексации
status	IndexJobStatus	стартовый статус задачи, обычно queued

External contract refs

• OpenAPI: формируется FastAPI по response_model=RagSessionCreateResponse.
• Schema: RagSessionCreateRequest, RagSessionCreateResponse.
• 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
validation_error	422	нарушена pydantic-схема request	исправить payload	no

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

Security

• Авторизация и аутентификация находятся вне этого метода.

Observability

• Logs: прямое логирование в endpoint отсутствует.
• Metrics: отдельные API-метрики не выделены.
• Traces: отсутствуют.
• Audit: факт вызова материализуется через RagSession и IndexJob.

Reliability

• Даже при дальнейшей ошибке индексации клиент может получить статус через job endpoint.
• Фоновая задача создаётся немедленно после ответа.

Performance

• Время ответа не зависит от размера snapshot, кроме времени сериализации request.

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

• 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.create_rag_session
• RagSessionStore.create
• IndexingOrchestrator.enqueue_snapshot

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

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

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

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