agent/docs/documentation/rag/entity-rag-session.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
entity-rag-session	Сущность RagSession	domain_entity	rag	draft	system-analyst	code	arch-rag-package logic-rag-indexing api-rag-session-create api-rag-session-changes api-rag-session-job	src/app/modules/rag/session_store.py src/app/modules/rag/persistence/session_repository.py src/app/modules/rag/persistence/schema_repository.py	RagSession	rag session domain-entity

Сущность RagSession

Summary

• Domain: rag
• Purpose: связать индекс и связанные job с конкретным проектом или его рабочим снимком.
• Entity role: корневая сущность области RAG indexing/retrieval.
• Main attributes: rag_session_id, project_id, created_at.
• Lifecycle: создаётся до первой индексации и используется как scope всех retrieval-запросов.
• Invariants: rag_session_id уникален, project_id обязателен.
• Related APIs: POST /api/rag/sessions, POST /api/rag/sessions/{rag_session_id}/changes, GET /api/rag/sessions/{rag_session_id}/jobs/{index_job_id}.
• Related logic: snapshot indexing, change indexing, retrieval filtering.
• Source of truth: src/app/modules/rag/session_store.py, таблица rag_sessions.

Назначение

RagSession определяет границу индекса для проекта. Все документы, задачи и retrieval-запросы внутри rag привязаны к этой сущности.

Контекст

Сессия используется и в новом API с UUID, и в legacy/internal режиме, где project_id может совпадать с rag_session_id. Через неё сервис восстанавливает repo_id, который затем участвует в кэшировании документов.

Роль в доменной модели

RagSession является владельцем набора индексированных документов и асинхронных IndexJob. Без неё нельзя безопасно выполнять reindex или retrieval, потому что именно она задаёт scope таблицы rag_chunks.

Атрибуты

attribute	type	required	description	constraints
rag_session_id	str	yes	уникальный идентификатор сессии	primary key, non-empty
project_id	str	yes	идентификатор проекта или workspace	non-empty
created_at	timestamp with time zone	yes	время создания записи в БД	default CURRENT_TIMESTAMP

Состояния и жизненный цикл

Основные состояния

• created
• active
• reused via legacy/internal API

Переходы состояний

1. RagSessionStore.create(project_id) создаёт новую сессию с UUID.
2. RagSessionStore.put(rag_session_id, project_id) создаёт или обновляет сессию с заданным ключом.
3. После создания сессия используется для indexing и retrieval до тех пор, пока не будет заменена новым идентификатором на уровне вызывающего сервиса.

Инварианты и ограничения

• project_id не должен быть пустым.
• Для retrieval и indexing используется только один rag_session_id за операцию.
• RagService._resolve_repo_id использует project_id этой сущности как repo_id для cache scope.

Связи с другими сущностями

entity	relation	description
IndexJob	one-to-many	одна сессия может иметь много задач индексации
RagDocument	one-to-many	все записи в rag_chunks привязаны к одной сессии

Использование в системе

Related API

• POST /api/rag/sessions
• POST /api/rag/sessions/{rag_session_id}/changes
• GET /api/rag/sessions/{rag_session_id}/jobs/{index_job_id}

Related UI

• Прямого UI в репозитории не обнаружено.

Related logic

• logic-rag-indexing
• logic-rag-retrieval

Related integrations

• PostgreSQL таблица rag_sessions

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

• Сессия должна создаваться до постановки snapshot job.
• При change indexing запрос должен ссылаться на существующую сессию в новом публичном API.
• Legacy/internal API может создавать запись с предсказуемым rag_session_id, равным project_id.

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

Audit / history

• Время создания фиксируется в таблице rag_sessions.

Security

• Отдельных прав доступа на уровне сущности внутри модуля нет.

Observability

• Основная наблюдаемость сессии идёт через связанные IndexJob.

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

Files

• src/app/modules/rag/session_store.py
• src/app/modules/rag/persistence/session_repository.py
• src/app/modules/rag/persistence/schema_repository.py

Symbols

• RagSession
• RagSessionStore.create
• RagSessionStore.put
• RagSessionStore.get

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

• arch-rag-package
• logic-rag-indexing
• api-rag-session-create
• api-rag-session-changes
• api-rag-session-job

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

Date	Source	Changes
2026-03-13	code	Добавлено описание сущности RagSession и её роли в границах индекса.