feat(sprint6c+sprint7): терминология, сверка примеров с кодом, мульти-RAG (часть A)

Спринт 6c — терминология и сверка документации с реальным кодом: - Словарь терминов в static/docs.html: «маршрутизатор» вместо «роутер», «защитное условие» вместо «guard», «пошаговая ветка» вместо «многошаговая». Разделены концепты «намерение» (intent) и «ветка» (branch) с пометкой, что в коде они хранятся как одна сущность 1:1. - Песочница: «Решение маршрутизатора» виден всегда (зелёный/жёлтый), счётчик переключений «N из 3» отдельной плашкой, бейджи под словарь. - Настройки: «Условия перехода» → «Защитные условия (guards, JSON)». - GRAPH_ARCHITECTURE_v4.md: имена полей thread_state и слоты приведены к реальной БД (db/models/thread_state.py) и таксономии промптов шагов (prompts/intents/new_booking/steps/). Ссылки на *_v2 примеры. На v3 поставлена шапка «устарело». - 4 примера переписаны как *_v2: реальные current_intent_code/ current_step_code/slots_json, реальные allowed_next без двойных переходов, реальная таксономия слотов name/reason/specialist/preferred_time/confirmed. Удалены вымышленные CRM tool calls и слоты, которых нет в коде. - static/example.html — параметризованная страница с навигацией между 4 примерами; роут GET /api/docs/examples/{name} в main.py отдаёт markdown без дублирования файлов. - Редактирование документов в Отладке: GET/PUT /documents/{id}/raw, textarea с переразметкой и обновлением Chroma при сохранении. Спринт 7, часть A — мульти-RAG через подписку ветка↔документы: - Миграция: таблица intent_documents (M:N), модель IntentDocument, индекс по document_id для обратного поиска. - API: GET/PUT /intents/{code}/documents и GET/PUT /documents/{id}/intents с PUT-семантикой «полный список», атомарно. Сервис services/intent_document_service.py. - Retrieval-фильтр в chat_service: подтягивает document_ids активной ветки и передаёт в vectorstore.query(). Дефолт пустой подписки — document_ids=[] (= 0 чанков), не «вся коллекция»: пустая подписка означает «ветка не настроена», подмешивать случайное хуже, чем ничего. vectorstore.query() различает None (нет фильтра) и [] (0). - UI Настроек: блок «Документы базы знаний» в правом сайдбаре, всегда видим независимо от вкладки, сортировка по имени, счётчик «N из M», PUT при сохранении. - UI Отладки: третья кнопка «привязка» рядом с «удалить» — раскрывашка со списком веток (галочки), быстрая привязка прямо на странице загрузки. - Песочница: блок «Срез RAG» с подпиской/найдено, ворнинг при пустой подписке. Поле rag_subscription в QueryResponse и ChatResponse. - Системный промпт страницы Отладки переехал в обычную ветку _debug («Страница отладки»). Удалён prompts/system_prompt.md и логика DEFAULT_SYSTEM_PROMPT в llm_client. routers/query.py подтягивает активный конфиг ветки _debug и её подписки. Дефолт пустой подписки для _debug — None (вся коллекция), не [] как для пациентских — чтобы Отладка работала «из коробки». На странице Отладки info-bar показывает активную версию и счётчик подписок, ссылка → Настройки. - Тест-блок «Тест-вопрос» в центре Настроек: расширил /query параметрами intent_code (default _debug), system_prompt (override для теста черновика из textarea), disable_rag (для _router). Редактор промпта обёрнут в <details open> — можно свернуть до одной строки. Под ним — три колонки результата (RAG / промпт / ответ). Для _router показывается подсказка про отсутствие RAG. Документы: - data/datasets/*.md — наработки по 6 веткам (рабочие материалы оператора). - docs/BRANCH_MAP_AND_PROMPTS_v1.md, docs/OPTIMIZATION_CONVERSION_v1.md, docs/guides/state_machine_and_slots.md. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-04-27 20:00:44 +05:00
parent f348570b1b
commit 52b46bc53e
43 changed files with 5914 additions and 105 deletions
@@ -6,7 +6,7 @@ from sqlalchemy import delete, func, select
 from sqlalchemy.ext.asyncio import AsyncSession

 from db.models import IntentStep, Message, Thread
-from services import config_service, intent_step_service, thread_state_service
+from services import config_service, intent_document_service, intent_step_service, thread_state_service
 from services.llm_client import LLMClient, LLMUnavailableError
 from services.router_client import RouterClient
 from services.state_machine import check_guards, parse_branch_response, validate_transition
@@ -344,7 +344,18 @@ async def send_message(
    # не инкрементится.
    snapshot["current_intent_code"] = served_code

-    retrieved = vectorstore.query(query_text=text, top_k=top_k)
+    # Подписки активной ветки на документы (Спринт 7, часть A — мульти-RAG).
+    # Дефолт пустой подписки — пустой список, т.е. retrieval вернёт 0 чанков.
+    # Это сознательный выбор: пустая подписка = ветка не настроена, подмешивать
+    # случайное хуже, чем не подмешивать ничего. См. SPRINTS.md, Спринт 7.
+    subscribed_document_ids = await intent_document_service.list_documents_for_intent_code(
+        session, served_code,
+    )
+    retrieved = vectorstore.query(
+        query_text=text,
+        top_k=top_k,
+        document_ids=subscribed_document_ids,
+    )
    sources = _retrieved_to_sources(retrieved)

    bounce_log: list[dict] = []
@@ -674,6 +685,10 @@ async def send_message(
        "escalation_reason": escalation_reason if served_code == ESCALATE_INTENT_CODE else None,
        "operator_summary": operator_summary,
        "router_assembled_prompt": router_assembled_prompt,
+        "rag_subscription": {
+            "subscribed_count": len(subscribed_document_ids),
+            "found_count": len(retrieved),
+        },
    }


@@ -0,0 +1,140 @@
+"""Подписка ветки на документы базы знаний (Спринт 7, часть A — мульти-RAG, подход A).
+
+Связь M:N через таблицу `intent_documents`. Сервис умеет:
+- читать список document_id для ветки и обратно — список intent_code для документа;
+- атомарно перезаписывать любой из этих списков (PUT-семантика).
+
+При retrieval в `chat_service` для активной ветки берём `list_documents_for_intent_code`
+и передаём в `vectorstore.query(document_ids=...)`. Дефолт пустой подписки —
+пустой список (= 0 чанков), это сознательное решение Спринта 7.
+"""
+import logging
+
+from sqlalchemy import delete, select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from db.models import Document, Intent, IntentDocument
+
+logger = logging.getLogger(__name__)
+
+
+async def list_documents_for_intent(session: AsyncSession, intent_id: int) -> list[str]:
+    """Список document_id, на которые подписана ветка."""
+    stmt = (
+        select(IntentDocument.document_id)
+        .where(IntentDocument.intent_id == intent_id)
+        .order_by(IntentDocument.created_at)
+    )
+    return list((await session.execute(stmt)).scalars().all())
+
+
+async def list_documents_for_intent_code(session: AsyncSession, intent_code: str) -> list[str]:
+    """То же, но по коду ветки. Если ветки нет — пустой список."""
+    stmt = (
+        select(IntentDocument.document_id)
+        .join(Intent, Intent.id == IntentDocument.intent_id)
+        .where(Intent.code == intent_code)
+        .order_by(IntentDocument.created_at)
+    )
+    return list((await session.execute(stmt)).scalars().all())
+
+
+async def list_intents_for_document(session: AsyncSession, document_id: str) -> list[str]:
+    """Список кодов веток, в которых используется документ."""
+    stmt = (
+        select(Intent.code)
+        .join(IntentDocument, IntentDocument.intent_id == Intent.id)
+        .where(IntentDocument.document_id == document_id)
+        .order_by(Intent.order_index, Intent.id)
+    )
+    return list((await session.execute(stmt)).scalars().all())
+
+
+async def set_documents_for_intent(
+    session: AsyncSession,
+    intent_id: int,
+    document_ids: list[str],
+) -> list[str]:
+    """Перезаписать список подписок ветки целиком.
+
+    Удаляем строки, которых нет в новом списке; добавляем недостающие.
+    Возвращаем актуальный список после обновления.
+    """
+    # Существующие подписки этой ветки.
+    existing = set(await list_documents_for_intent(session, intent_id))
+    desired = set(document_ids)
+
+    to_delete = existing - desired
+    to_add = desired - existing
+
+    if to_delete:
+        await session.execute(
+            delete(IntentDocument)
+            .where(IntentDocument.intent_id == intent_id)
+            .where(IntentDocument.document_id.in_(to_delete))
+        )
+
+    if to_add:
+        # Проверяем, что документы существуют — иначе FK-ошибка на коммите будет
+        # неинформативной. Документы, которых нет, тихо пропускаем (это типичная
+        # гонка: оператор удалил документ в одном табе, в другом нажал «сохранить»).
+        existing_doc_ids = set((await session.execute(
+            select(Document.id).where(Document.id.in_(to_add))
+        )).scalars().all())
+        missing = to_add - existing_doc_ids
+        if missing:
+            logger.warning(
+                "set_documents_for_intent: skipping unknown document_ids=%s for intent_id=%d",
+                sorted(missing), intent_id,
+            )
+        for document_id in to_add & existing_doc_ids:
+            session.add(IntentDocument(intent_id=intent_id, document_id=document_id))
+
+    await session.commit()
+    return await list_documents_for_intent(session, intent_id)
+
+
+async def set_intents_for_document(
+    session: AsyncSession,
+    document_id: str,
+    intent_codes: list[str],
+) -> list[str]:
+    """Перезаписать список веток, к которым привязан документ.
+
+    Возвращаем актуальный список кодов после обновления.
+    """
+    # Текущий набор intent_id для документа.
+    current_stmt = (
+        select(IntentDocument.intent_id)
+        .where(IntentDocument.document_id == document_id)
+    )
+    existing_ids = set((await session.execute(current_stmt)).scalars().all())
+
+    # Желаемый набор intent_id (по кодам). Неизвестные коды — пропускаем.
+    desired_stmt = select(Intent.id, Intent.code).where(Intent.code.in_(intent_codes))
+    code_to_id: dict[str, int] = {}
+    for row in (await session.execute(desired_stmt)).all():
+        code_to_id[row.code] = row.id
+    desired_ids = set(code_to_id.values())
+
+    missing_codes = set(intent_codes) - set(code_to_id.keys())
+    if missing_codes:
+        logger.warning(
+            "set_intents_for_document: skipping unknown intent_codes=%s for document_id=%s",
+            sorted(missing_codes), document_id,
+        )
+
+    to_delete = existing_ids - desired_ids
+    to_add = desired_ids - existing_ids
+
+    if to_delete:
+        await session.execute(
+            delete(IntentDocument)
+            .where(IntentDocument.document_id == document_id)
+            .where(IntentDocument.intent_id.in_(to_delete))
+        )
+    for intent_id in to_add:
+        session.add(IntentDocument(intent_id=intent_id, document_id=document_id))
+
+    await session.commit()
+    return await list_intents_for_document(session, document_id)
@@ -24,6 +24,7 @@ SEED_INTENTS: list[dict] = [
    {"code": "general_info",      "name": "Общая справка",          "description": "Адрес, часы работы, как доехать, общие вопросы."},
    {"code": "escalate_human",    "name": "Перевод на оператора",   "description": "Перевод диалога на живого оператора."},
    {"code": ROUTER_INTENT_CODE,  "name": "Маршрутизатор",          "description": "Системная ветка: промпт классификатора намерений. Пациенту напрямую не отвечает."},
+    {"code": "_debug",            "name": "Страница отладки",       "description": "Системная ветка: используется на странице «Отладка» для одиночных тест-вопросов. Пациентам в диалогах не отвечает. Дефолт RAG — вся коллекция, если подписки пусты."},
 ]


@@ -1,6 +1,5 @@
 import asyncio
 import logging
-from pathlib import Path

 import httpx

@@ -13,18 +12,6 @@ class LLMUnavailableError(RuntimeError):

 logger = logging.getLogger(__name__)

-SYSTEM_PROMPT_PATH = Path(__file__).resolve().parent.parent / "prompts" / "system_prompt.md"
-
-
-def _load_system_prompt() -> str:
-    try:
-        return SYSTEM_PROMPT_PATH.read_text(encoding="utf-8").strip()
-    except FileNotFoundError:
-        logger.warning("System prompt file not found at %s — using empty prompt", SYSTEM_PROMPT_PATH)
-        return ""
-
-
-DEFAULT_SYSTEM_PROMPT = _load_system_prompt()

 DEFAULT_USER_TEMPLATE = """Вопрос пациента:
 {question}
@@ -81,7 +68,7 @@ class LLMClient:

        Returns dict with 'text' and 'assembled_prompt'.
        """
-        effective_system = system_prompt or DEFAULT_SYSTEM_PROMPT
+        effective_system = system_prompt or ""
        effective_temp = temperature if temperature is not None else 0.2
        effective_max_tokens = max_tokens or 1200

@@ -125,7 +112,7 @@ class LLMClient:

        Returns dict with 'text' and 'assembled_prompt'.
        """
-        effective_system = system_prompt or DEFAULT_SYSTEM_PROMPT
+        effective_system = system_prompt or ""
        effective_temp = temperature if temperature is not None else 0.2
        effective_max_tokens = max_tokens or 1200

@@ -14,6 +14,7 @@ async def rag_query(
    document_ids: list[str] | None = None,
    temperature: float | None = None,
    max_tokens: int | None = None,
+    system_prompt: str | None = None,
 ) -> dict:
    """Pipeline: retrieve → augment → generate для одиночного вопроса пациента."""
    logger.info("RAG query: %s", question[:200])
@@ -28,6 +29,7 @@ async def rag_query(
    llm_result = await llm_client.answer(
        question=question,
        sources=retrieved,
+        system_prompt=system_prompt,
        temperature=temperature,
        max_tokens=max_tokens,
    )
@@ -64,6 +64,11 @@ class VectorStoreService:
        top_k: int = 5,
        document_ids: list[str] | None = None,
    ) -> list[dict]:
+        # Различаем None (фильтра нет — вся коллекция) и [] (ветка без подписок —
+        # сознательный возврат 0 чанков, см. Спринт 7 в SPRINTS.md).
+        if document_ids is not None and len(document_ids) == 0:
+            return []
+
        query_embedding = self.embedding_service.embed_query(query_text)

        where_filter = None