From d1e774960561accb25b05ca4f4f301203e204b16 Mon Sep 17 00:00:00 2001 From: AR 15 M4 Date: Wed, 22 Apr 2026 13:58:53 +0500 Subject: [PATCH] =?UTF-8?q?docs:=20init=20=E2=80=94=20README=20=D0=B8=20SP?= =?UTF-8?q?RINTS=20=D0=B4=D0=BB=D1=8F=20=D0=B8=D0=BD=D1=81=D1=82=D1=80?= =?UTF-8?q?=D1=83=D0=BC=D0=B5=D0=BD=D1=82=D0=B0=20=D0=BD=D0=B0=D1=81=D1=82?= =?UTF-8?q?=D1=80=D0=BE=D0=B9=D0=BA=D0=B8=20=D0=BF=D0=B0=D1=86=D0=B8=D0=B5?= =?UTF-8?q?=D0=BD=D1=82=D1=81=D0=BA=D0=BE=D0=B3=D0=BE=20=D1=87=D0=B0=D1=82?= =?UTF-8?q?-=D0=B0=D0=B3=D0=B5=D0=BD=D1=82=D0=B0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Скоуп MVP: RAG-ядро + веб-инструмент настройки (загрузка wiki, песочница, промпт/правила с версиями, сценарии, экспорт конфига). Интеграцию с каналами (приложение, МАКС) делает другой разработчик. Co-Authored-By: Claude Opus 4.7 (1M context) --- .gitignore | 7 +++ README.md | 95 +++++++++++++++++++++++++++++++++++ SPRINTS.md | 145 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 247 insertions(+) create mode 100644 .gitignore create mode 100644 README.md create mode 100644 SPRINTS.md diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..af23dc6 --- /dev/null +++ b/.gitignore @@ -0,0 +1,7 @@ +__pycache__/ +*.pyc +.env +data/chroma/ +*.egg-info/ +.venv/ +.DS_Store diff --git a/README.md b/README.md new file mode 100644 index 0000000..eeb7d89 --- /dev/null +++ b/README.md @@ -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) — пациентские боты МАКС (канал подключит другой разработчик). diff --git a/SPRINTS.md b/SPRINTS.md new file mode 100644 index 0000000..9ffb001 --- /dev/null +++ b/SPRINTS.md @@ -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) +- Мультипользовательский режим (несколько операторов одновременно настраивают)