RAG_helper/SPRINTS.md

Спринты — Chat Agent for Patients (инструмент настройки)

Поэтапный план MVP: RAG-ядро + веб-инструмент для настройки агента операторами. Подключение реальных каналов (приложение, МАКС) — вне скоупа, это задача другого разработчика.

---

Спринт 1. RAG-ядро, загрузка документов и тестовая страница

Цель

Поднять FastAPI-сервис с ChromaDB и сразу получить воспроизводимый «пайплайн в действии»: на одной тестовой странице видно, какие файлы загружены, можно задать одиночный вопрос от лица пациента и увидеть одновременно три вещи — какие чанки нашёл RAG, какой промпт собрался, какой ответ вернул DeepSeek. Аналог Debug UI из work-pcs-dr-cdss.

Статус: ⏳ Запланирован

Задачи

RAG-ядро:

• Инициализация проекта (main.py, config.py, requirements.txt, Dockerfile, docker-compose, .env.example)
• Переиспользовать паттерны из work-pcs-dr-cdss: services/embeddings.py, vectorstore.py, document_processor.py, llm_client.py
• Адаптировать чанкер под wiki-статьи (не клинреки)

Эндпоинты:

• GET /health — статус, кол-во документов и чанков
• POST /documents/upload — загрузка + превью первых 3 чанков в ответе
• GET /documents — список загруженных
• DELETE /documents/{id} — удаление
• POST /query — одиночный вопрос от лица пациента → ответ + источники со score + assembled_prompt (как RAG for Doctors, но без полей карты — только текст вопроса)

Тестовая страница (одна HTML-страница, vanilla JS):

• Шапка со статусом сервиса (auto-refresh /health, счётчики документов и чанков)
• Блок «База знаний»: drag & drop загрузка, таблица документов с превью первых чанков, кнопка удаления
• Блок «Тест-вопрос от пациента»: поле ввода вопроса, поле top_k, кнопка «Отправить»
• 3-колоночный результат ответа: релевантные фрагменты (текст + document, section, page, score) | собранный промпт | ответ LLM

Критерий готовности

• Оператор открывает http://localhost:PORT/ → видит Debug UI со статусом сервиса
• Загружает wiki-статью → она появляется в таблице, превью чанков отображается
• Пишет вопрос «как записать ребёнка к лору?» → получает ответ DeepSeek с указанием источников
• В средней колонке виден собранный промпт, в левой — какие чанки подтянулись со score
• Может удалить статью, счётчики в шапке обновляются

---

Спринт 2. Многошаговый диалог с памятью треда

Цель

Перейти от одиночного /query к полноценному диалогу: агент помнит историю, оператор ведёт разговор из 5+ реплик. На тестовой странице добавляется режим «чат», рядом с режимом «одиночный вопрос» из Спринта 1.

Статус: ⏳ Запланирован

Задачи

• Хранилище диалогов (SQLite): threads, messages
• Эндпоинт POST /chat: принимает thread_id, text → возвращает ответ агента + источники + assembled_prompt
• Базовый системный промпт (хардкод для старта): роль, тон клиники, что можно и нельзя
• Сборка контекста: история треда + RAG-чанки
• Веб-страница расширена режимом «Песочница»:
  • левая колонка — чат (оператор пишет как пациент, видит ответы агента)
  • правая колонка — retrieved-чанки со score + собранный промпт по последней реплике
  • кнопка «сбросить тред»

Критерий готовности

• Оператор может провести диалог из 5+ реплик, агент помнит контекст
• В правой колонке видно, что нашёл RAG и что улетело в LLM на последнем шаге

---

Спринт 3. Настройки агента: системный промпт и правила

Цель

Дать операторам веб-редактор системного промпта и списка правил («если спрашивают про X — отвечай так-то», «если пациент злится — делай то-то»). Версионирование: можно сохранить конфигурацию и откатиться.

Статус: ⏳ Запланирован

Задачи

• Хранилище (SQLite): agent_configs (version, created_at, system_prompt, rules_text, is_active)
• Эндпоинты: GET /configs, POST /configs (создать новую версию), POST /configs/{id}/activate
• Песочница использует активную версию при каждом /chat
• Веб-страница «Настройки агента»:
  • редактор системного промпта (textarea)
  • редактор правил (отдельным блоком; на старте — просто textarea, позже — список записей)
  • кнопка «Сохранить как новую версию»
  • список версий с кнопкой «Сделать активной» и пометкой активной
• Показ активной версии в шапке песочницы

Критерий готовности

• Оператор меняет промпт → сохраняет как v2 → активирует → тестирует в песочнице → при желании откатывается к v1
• Правила реально влияют на ответы агента (проверяется вручную через песочницу)

---

Спринт 4. Сценарии: сохранение и прогон

Цель

Позволить операторам сохранять отработанные диалоги из песочницы как «сценарии» (с пометкой «эталон / ок / не ок» и заметкой), а потом прогонять их на текущей конфигурации, чтобы сразу увидеть, не сломалось ли что-то после правок.

Статус: ⏳ Запланирован

Задачи

• Хранилище (SQLite): scenarios (id, name, note, label, messages_json, reference_answers_json, config_version_id)
• Эндпоинты:
  • POST /scenarios — сохранить текущий тред песочницы как сценарий
  • GET /scenarios, GET /scenarios/{id}
  • POST /scenarios/{id}/run — прогнать реплики пациента на текущей активной конфигурации, вернуть новые ответы агента
• Возможность пометить «правильный ответ оператора» для каждой реплики пациента (эталон)
• Веб-страница «Сценарии»:
  • список сценариев с метками и датой
  • открытая карточка: реплики пациента, ответы агента при сохранении, опциональные «эталонные ответы»
  • кнопка «Прогнать на текущей конфигурации» → показывает side-by-side: старый ответ / новый ответ
  • счётчик «сколько сценариев остались в статусе ок» после последнего прогона

Критерий готовности

• Оператор может сохранить диалог как сценарий, добавить эталонные ответы, пометить «ок»
• После изменения промпта прогон сценариев показывает, где ответы расходятся
• Виден общий счётчик «ок / изменилось» по всей базе сценариев

---

Спринт 5. Экспорт конфигурации для внешней интеграции

Цель

Зафиксировать API-контракт и упаковать активную конфигурацию так, чтобы другой разработчик мог подключить чат-канал (приложение / МАКС-бот) без обращений к нам.

Статус: ⏳ Запланирован

Задачи

• Документация API: POST /chat (с channel_id, user_id, thread_id, text), GET /health
• Эндпоинт GET /configs/active/export — JSON со снапшотом: активный промпт + правила + список документов RAG
• Инструкция «как подключиться» в README (пример curl-запроса + минимальный webhook-адаптер)
• Проверка: внешний разработчик может поднять сервис по docker-compose и получить валидный ответ от /chat

Критерий готовности

• README раздел «Как подключить канал» готов
• Docker-compose поднимается одной командой
• На заданном тестовом запросе /chat возвращает ответ, который мы видим и в веб-песочнице

---

Бэклог

• Раздельные правила по доменам (детский приём / ДМС / взрослый приём)
• A/B сравнение двух версий промпта на одном тест-наборе
• Метрики качества ответов (MRR, CSAT по сценариям)
• Подсветка цитат источников в ответе агента
• Автосинхронизация wiki
• Перевод правил из свободного текста в структурированный список (pattern → instruction)
• Мультипользовательский режим (несколько операторов одновременно настраивают)