docs: init — README и SPRINTS для инструмента настройки пациентского чат-агента

Скоуп MVP: RAG-ядро + веб-инструмент настройки (загрузка wiki, песочница, промпт/правила с версиями, сценарии, экспорт конфига). Интеграцию с каналами (приложение, МАКС) делает другой разработчик. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-04-22 13:58:53 +05:00
commit d1e7749605
3 changed files with 247 additions and 0 deletions
@@ -0,0 +1,7 @@
+__pycache__/
+*.pyc
+.env
+data/chroma/
+*.egg-info/
+.venv/
+.DS_Store
@@ -0,0 +1,95 @@
+# Chat Agent for Patients (RAG) — инструмент настройки
+
+**RAG-ядро + веб-инструмент для настройки пациентского чат-агента: загрузка wiki, редактирование промпта и правил, прогон сценариев.**
+
+Подключение реальных каналов (чат в мобильном приложении, бот в МАКС) делает другой разработчик — этот проект отдаёт ему **готовое RAG-ядро и API** плюс согласованную конфигурацию (системный промпт, правила, снапшот базы знаний).
+
+---
+
+## Статус
+
+🟡 **Active — MVP, проектирование.**
+
+---
+
+## Цель проекта
+
+- Поднять RAG по wiki операторов и API диалога с агентом.
+- Дать операторам веб-инструмент, в котором они в процессе настройки:
+  - загружают документы wiki (постепенно, по мере готовности — не пакетно);
+  - редактируют системный промпт и правила поведения агента;
+  - играют роль пациента в тестовом чате и смотрят, что отвечает агент;
+  - сохраняют проработанные диалоги как **сценарии** и перегоняют их после изменения настроек.
+- Сама интеграция с реальными каналами (приложение, МАКС) — вне скоупа этого проекта.
+
+---
+
+## Что **не** входит в скоуп
+
+- Реальная интеграция с чатом в мобильном приложении (`work-pcs-pt-mobile`).
+- Реальная интеграция с ботом в МАКС (`work-pcs-pt-bots`).
+- Очередь и UI оператора для живого переключения с агента на человека.
+- Мультипользовательская прод-эксплуатация.
+
+Всё это — задача смежного разработчика, который будет использовать API этого сервиса.
+
+---
+
+## Архитектура (черновик)
+
+```
+┌──────────────────────────────────┐      ┌──────────────────────┐
+│  Web UI настройки (один экран)   │      │                      │
+│  ┌────────────┐  ┌────────────┐  │      │   RAG (wiki)         │
+│  │ База знаний│  │ Промпт +   │──┼─────▶│   ChromaDB + E5      │
+│  │ (upload)   │  │ правила    │  │      └──────────────────────┘
+│  └────────────┘  └────────────┘  │      ┌──────────────────────┐
+│  ┌────────────┐  ┌────────────┐  │─────▶│   DeepSeek LLM API   │
+│  │ Песочница  │  │ Сценарии   │  │      └──────────────────────┘
+│  │ (чат)      │  │ (сохран.)  │  │
+│  └────────────┘  └────────────┘  │
+└──────────────────────────────────┘
+              │
+              ▼
+       Chat Agent API (FastAPI)
+       (тот же API, что потом получит
+        внешний разработчик для каналов)
+```
+
+**Ключевая идея:** веб-инструмент — это единственный клиент агента на время настройки. Когда конфигурация «устаканивается», её снапшот отдаётся внешнему разработчику вместе с документированным API.
+
+---
+
+## Технологический стек (предварительно)
+
+| Слой | Технология | Назначение |
+|------|-----------|-----------|
+| API | FastAPI (Python 3.11–3.12) | HTTP-эндпоинты агента и настройки |
+| Vector DB | ChromaDB | База эмбеддингов wiki |
+| Embeddings | `intfloat/multilingual-e5-large` | Русскоязычные эмбеддинги |
+| LLM | DeepSeek API | Диалоговая модель |
+| Хранилище конфигов и сценариев | SQLite | Промпты, правила, сценарии |
+| Веб-UI | Vanilla JS / лёгкий фреймворк | Одностраничное приложение настройки |
+| Контейнеризация | Docker | Изолированный запуск |
+
+> База опыта — [`work-pcs-dr-cdss`](../work-pcs-dr-cdss) (RAG-сервис для врачей). Переиспользуем паттерн сервисов `embeddings.py / vectorstore.py / document_processor.py / llm_client.py`.
+
+---
+
+## План (спринты)
+
+См. [`SPRINTS.md`](./SPRINTS.md).
+
+---
+
+## Запуск
+
+TBD — будет заполнено в Спринте 1.
+
+---
+
+## Связанные проекты
+
+- [`work-pcs-dr-cdss`](../work-pcs-dr-cdss) — RAG для врачей, источник технических паттернов.
+- [`work-pcs-pt-mobile`](../work-pcs-pt-mobile) — мобильное приложение пациента (канал подключит другой разработчик).
+- [`work-pcs-pt-bots`](../work-pcs-pt-bots) — пациентские боты МАКС (канал подключит другой разработчик).
@@ -0,0 +1,145 @@
+# Спринты — 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)
+- Мультипользовательский режим (несколько операторов одновременно настраивают)