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)
- Мультипользовательский режим (несколько операторов одновременно настраивают)