From 65ae3506f760a751eb590486be6d89878e0c7513 Mon Sep 17 00:00:00 2001 From: Lacky1234union Date: Mon, 5 Oct 2026 13:30:37 +0300 Subject: [PATCH] =?UTF-8?q?docs:=20README=20for=20the=20jury=20=E2=80=94?= =?UTF-8?q?=20goals,=20what=20is=20built,=20run,=20API,=20medical=20limita?= =?UTF-8?q?tions?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Opus 5.5 --- README.md | 121 ++++++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 112 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 09cf25f..a1c5108 100644 --- a/README.md +++ b/README.md @@ -1,14 +1,117 @@ # PTSRaiAgent — ИИ-помощник сопровождения при ПТСР и депрессии -> Хакатон MedITron · кейс SberMed AI «ИИ-помощник пациента». Прототип на **синтетических данных**. -> Telegram используется только для прототипа на синтетических данных; прод-канал — MAX / Госуслуги. +> Хакатон MedITron · кейс SberMed AI «ИИ-помощник пациента». Прототип работает **только на синтетических данных**. +> Демо-стенд: **https://meditron.tenvex.ru** (кабинет врача: https://meditron.tenvex.ru/doctor/, API: https://meditron.tenvex.ru/docs). -🚧 README заполняется к сдаче (issue «README по требованиям оформления»). Разделы по требованиям жюри: +--- -1. Цели и задачи решения -2. Что реализовано -3. Развёртывание, запуск, использование -4. Входные и выходные данные, API -5. Ограничения и особенности медицинской тематики +## 1. Цели и задачи -Пока смотрите [`CLAUDE.md`](CLAUDE.md) и [`docs/`](docs/). +**Проблема.** Ветераны СВО и люди с депрессией до помощи доходят с трудом, а начав лечение, часто его бросают: в первые недели побочные эффекты уже есть, а эффекта ещё нет. Врач между визитами ничего не знает о пациенте. + +**Решение.** Цифровой помощник сопровождает пациента между визитами к врачу. Из сценариев кейса закрыты два: **мониторинг после обращения** и **управление приёмом лекарств**. +- Пациент общается с помощником в чате: веб-приложение или Telegram. В проде канал — MAX / Госуслуги. +- Помощник собирает валидированные шкалы, ежедневный чек-ин и отметки о приёме препарата. +- Он отвечает на вопросы о лечении по клиническим рекомендациям Минздрава, по инструкции ГРЛС и по карте пациента в ЕМИАС. +- Врач видит «красные зоны» и получает сигналы при ухудшении. + +**Принципы.** +- ИИ не ставит диагнозы и не назначает лечение. +- LLM только формулирует ответы и извлекает данные. +- **Риск, алерты и скоринг считают детерминированные правила** по валидированным шкалам (PHQ-9, PCL-5, GAD-7, AUDIT-C, C-SSRS, DAR-5). +- Клинические решения принимает врач. + +## 2. Что реализовано + +| Блок | Что есть | +|---|---| +| **Чат-агент** | LLM с инструментами только для чтения: поиск по базе клинических рекомендаций (RAG, депрессия 2024, ПТСР 2023), карта пациента из ЕМИАС (мок), инструкция ГРЛС, детерминированная проверка препарата под пациента (сопутствующие болезни, непереносимость вспомогательных веществ, взаимодействия). Ответ печатается в реальном времени (SSE), видны шаги агента. Провайдеры: GigaChat (функции), OpenRouter (временно, только синтетика), офлайн-mock. | +| **Диалоговый движок** | Обезличивание → проверка безопасности → FSM. Согласие (152-ФЗ, отзыв в один шаг), проверка возраста, онбординг ветерана (PC-PTSD-5 → PCL-5 → PHQ-9 → AUDIT-C), опросник intake (C-SSRS, PHQ-2→9, TSQ→PCL-5, RUS-AUDIT-S), ежедневный чек-ин, напоминания о дозах, побочные эффекты. На вопросы отвечает в любом состоянии. | +| **Безопасность** | Лексикон риска (100% recall на наборе кризисных фраз), фиксированный кризисный скрипт без LLM, алерт врачу и дежурному, план безопасности. В демо кризисное окно показывается в конце теста и не блокирует диалог (`CRISIS_BLOCKING`). | +| **Правила мониторинга** | 17 правил в `config/rules.yaml`: п.9 PHQ-9, рост баллов, побочки 3 дня подряд, намерение бросить, пропуски 3 из 7, сон < 4 ч, алкоголь, молчание > 3 дней и другие. | +| **Кабинет врача** | Список «красных зон» с индексом риска прерывания терапии, карточка (графики шкал, сон, настроение, дозы, алерты, план безопасности, ИИ-саммари), живые алерты, подключение пациента с кодом и QR, аудит доступа. | +| **Веб-приложение пациента** | Вход через ЕМИАС (демо: код от врача), анонимный вход или демо-вход в один клик (у каждого посетителя своя копия пациента). Экраны: сегодня, лекарства, чат, врач, профиль. | +| **Демо-консоль** | Виртуальные часы (13 дней терапии за 3 минуты), проигрывание сценария, сплит-экран, тумблер начального теста. | +| **Инфраструктура** | Docker compose, CI (ruff + pytest, около 1060 тестов), CD: мерж в `dev` выкатывает стенд. | + +## 3. Развёртывание и запуск + +**Требования:** Docker с Compose v2. Для локальной разработки — Python 3.12 и [uv](https://docs.astral.sh/uv/); для сборки веб-приложения — Node 20 (или docker-образ `node:20-alpine`). + +```bash +cp .env.example .env # по умолчанию офлайн: LLM_PROVIDER=mock, агент выключен +make up # postgres + API (:8000) + кабинет врача и демо-консоль (:8501) +make seed # синтетический кабинет: врач, ветеран Андрей и 7 пациентов +``` + +- API и Swagger: http://localhost:8000/docs +- Кабинет врача и демо-консоль: http://localhost:8501 +- Веб-приложение пациента: `cd web && npm ci && npm run dev`, затем http://localhost:5173 (`/api` проксируется на :8000) + +**Включить чат-агента** в `.env`: +- `CHAT_AGENT=gigachat` + `GIGACHAT_CREDENTIALS=…` — целевой вариант для РФ; +- или `CHAT_AGENT=openrouter` + `OPENROUTER_API_KEY=…` (+ `OPENROUTER_PROXY_URL` с сервера в РФ) — только для прототипа; +- проверить из терминала: `uv run python -m app.llm.agent "Можно мне ибупрофен?" --persona andrey`. + +**Демо-переключатели:** +- `SCREENING_ENABLED` — начальный тест (дублируется тумблером в демо-консоли); +- `CRISIS_BLOCKING` — клинический протокол: кризис блокирует диалог до подтверждения врача; +- `DEMO_CLOCK` — виртуальные часы; +- `INTAKE_DEMO` — опросники intake на синтетике. + +**Сервер:** `infra/deploy/` — override compose, nginx-vhost, `deploy.sh`. Выкатка на стенд — `.gitea/workflows/deploy.yml`. + +**Разработка:** `uv sync`, `make lint test`. + +## 4. Входные и выходные данные, API + +**Входные данные:** +- сообщения и ответы кнопками пациента; +- назначения (мок МИС, `data/meds/mis_prescriptions.json`); +- карта ЕМИАС (мок, `data/emias/records.yaml`); +- выдержки ГРЛС (`data/meds/grls/`); +- клинические рекомендации (`config/rag/corpus/`). + +**Выходные данные:** ответы пациенту, баллы шкал, алерты врачу, карточка пациента, журнал аудита. + +Все клинические конфиги (шкалы, пороги, правила, тексты, лексикон) лежат в `config/` и правятся без кода. + +Основные эндпоинты (`/api/v1`, полная спецификация — `/docs`): + +| Метод и путь | Назначение | +|---|---| +| `POST /dialog/{token}/events` | событие диалога: текст, кнопка, start → ответы помощника | +| `POST /dialog/{token}/events/stream` | то же в виде SSE: шаги агента, текст по мере генерации, финальные ответы | +| `GET /dialog/{token}/outbox` | системные сообщения: напоминания, чек-ины | +| `POST /auth/emias`, `/auth/emias/demo`, `/auth/demo/fresh`, `/auth/anonymous` | входы веб-приложения | +| `GET /me/{token}/today` | план на сегодня: дозы, отметки за неделю, визит | +| `GET /doctors/{id}/patients` | список пациентов врача с цветом и индексом риска | +| `GET /patients/{token}?doctor_id=` | карточка пациента (пишется в аудит) | +| `GET /doctors/{id}/alerts`, `POST /alerts/{id}/ack` | алерты и их подтверждение | +| `POST /patients/connect` | подключение пациента: назначение и одноразовый код | +| `GET/POST /demo/clock…`, `/demo/reset`, `/demo/settings` | демо-управление | + +## 5. Ограничения и особенности медицинской тематики + +- **Только синтетические данные.** Персоны, карты ЕМИАС, назначения и выдержки ГРЛС вымышлены или пересказаны для прототипа и подлежат сверке. +- **Не медицинское изделие в текущем виде.** Сервис не ставит диагнозы и не меняет терапию. Пороги шкал, тексты и лексикон — стартовые значения из литературы, их утверждает психиатр (`docs/clinical/`). +- **152-ФЗ:** отдельное согласие на обработку данных о здоровье, две раздельные БД (identity и clinical) со связью через HMAC-токен, в LLM уходит только обезличенный текст, каждое обращение врача пишется в аудит. +- **Зарубежные сервисы.** OpenRouter используется временно и только на синтетике. Для реальных пациентов нужен GigaChat в РФ-контуре. +- **Безопасность.** Кризисный ответ фиксированный и выдаётся без LLM. Пропуск кризиса недопустим, ложные срабатывания допустимы. Демо-режим (кризис без блокировки) не равен клиническому протоколу: в проде `CRISIS_BLOCKING=true`. +- **Ответы LLM** могут слегка различаться от раза к разу. Фактура берётся только из инструментов, а запрещённые формулировки (диагнозы, дозы, «отмените») фильтруются. + +## Структура репозитория + +``` +app/ бэкенд: core (privacy, safety, шкалы, правила, часы), dialog (движок и сценарии), llm (шлюз, RAG, + чат-агент), db, api, scheduler, integrations (моки МИС/ЕМИАС/ГРЛС, уведомления), services +dashboard/ кабинет врача и демо-консоль (Streamlit) +web/ веб-приложение пациента (React + Vite) +config/ клинические конфиги: шкалы, правила, модули, тексты, лексикон, RAG-корпус +data/ синтетика: сценарий демо, карты ЕМИАС, назначения, выдержки ГРЛС +infra/ postgres init, деплой на сервер +tests/ pytest (около 1060 тестов) +docs/ спецификация, ADR (DECISIONS.md), клинические материалы, концепция и CJM, регламент +``` + +Подробнее: [`docs/info/SPEC.md`](docs/info/SPEC.md) · [`docs/DECISIONS.md`](docs/DECISIONS.md) · [`docs/info/CLINICAL_MODULES.md`](docs/info/CLINICAL_MODULES.md) · [`docs/source/`](docs/source/) (кейс, концепция, CJM). -- 2.54.0