PTSRaiAgent/README.md

PTSRaiAgent — ИИ-помощник сопровождения при ПТСР и депрессии

Хакатон MedITron · кейс SberMed AI «ИИ-помощник пациента». Прототип работает только на синтетических данных. Демо-стенд: https://meditron.tenvex.ru (кабинет врача: https://meditron.tenvex.ru/doctor/, API: https://meditron.tenvex.ru/docs).

---

1. Цели и задачи

Проблема. Ветераны СВО и люди с депрессией до помощи доходят с трудом, а начав лечение, часто его бросают: в первые недели побочные эффекты уже есть, а эффекта ещё нет. Врач между визитами ничего не знает о пациенте.

Решение. Цифровой помощник сопровождает пациента между визитами к врачу. Из сценариев кейса закрыты два: мониторинг после обращения и управление приёмом лекарств.

• Пациент общается с помощником в чате: веб-приложение или 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, Node 20.

cp .env.example .env          # по умолчанию офлайн: LLM_PROVIDER=mock, агент выключен
make up                       # postgres + API (:8000) + кабинет врача/демо-консоль (:8501) + приложение пациента (:8080)
make seed                     # синтетический кабинет: врач, ветеран Андрей и 7 пациентов

• API и Swagger: http://localhost:8000/docs
• Кабинет врача и демо-консоль: http://localhost:8501
• Веб-приложение пациента: http://localhost:8080 (собирается внутри Docker, Node на машине не нужен; для разработки — cd web && npm run dev, :5173)

Включить чат-агента в .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/DECISIONS.md · docs/info/CLINICAL_MODULES.md · docs/source/ (кейс, концепция, CJM).