2026-10-05 13:33:17 +03:00
1 changed files with 112 additions and 9 deletions
@@ -1,14 +1,117 @@
 # PTSRaiAgent — ИИ-помощник сопровождения при ПТСР и депрессии
-> Хакатон MedITron · кейс SberMed AI «ИИ-помощник пациента». Прототип на **синтетических данных**.
+> Хакатон MedITron · кейс SberMed AI «ИИ-помощник пациента». Прототип работает **только на синтетических данных**.
-> Telegram используется только для прототипа на синтетических данных; прод-канал — MAX / Госуслуги.
+> Демо-стенд: **https://meditron.tenvex.ru** (кабинет врача: https://meditron.tenvex.ru/doctor/, API: https://meditron.tenvex.ru/docs).
-🚧 README заполняется к сдаче (issue «README по требованиям оформления»). Разделы по требованиям жюри:
+---
-1. Цели и задачи решения
+## 1. Цели и задачи
 2. Что реализовано
 3. Развёртывание, запуск, использование
 4. Входные и выходные данные, API
 5. Ограничения и особенности медицинской тематики
-Пока смотрите [`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).