PTSRaiAgent/docs/DECISIONS.md

Архитектурные решения (ADR)

Живой журнал: что решили и почему. Новые записи — сверху. Одна запись = одно решение. При конфликте с docs/info/SPEC.md действует ADR.

2026-10-04 — ADR-011: База знаний (RAG) — лексический поиск BM25 и экстрактивные ответы с цитатами

Контекст: агенту нужны ответы по клиническим рекомендациям (КР ПТСР 2023, КР Депрессия 2024) со ссылкой на источник (#60). Эмбеддинги требуют либо сети (GigaChat Embeddings), либо тяжёлых зависимостей (torch, модель на сотни МБ). При этом демо должно работать офлайн (ADR-004), а pyproject.toml заморожен (#34). Решение: PDF переводятся в txt один раз, офлайн (docs/source/rag/pdf_to_txt.py: таблицы → markdown, маркеры страниц, текст блок-схем перенесён вручную). Корпус лежит в config/rag/. Поиск — BM25 по основам слов (свой стеммер Snowball) с синонимами и переранжированием по самому плотному отрывку. Ответ экстрактивный: показываются только предложения из найденного фрагмента с цитатой «[КР ПТСР 2023, стр. N]». LLM может лишь упростить их для пациента, а перефразировка с новым содержанием отбраковывается. Если отрывки покрывают слишком малую долю вопроса (min_coverage), ответ — «ответа нет, уточните у врача». Пациенту не показываются предложения о назначении и дозах. Внутренние документы команды (audiences: [team]) не доходят ни до пациента, ни до врача. Причина: работоспособность офлайн и детерминизм важнее recall на перефразированных вопросах. Каждое показанное утверждение можно проверить по странице КР. Последствия: разговорные формулировки без общих слов с КР находятся хуже — это лечится словарём synonyms в config/rag/sources.yaml. Качество поиска контролирует набор контрольных вопросов в tests/test_llm_rag.py (hit@3 ≥ 15/18). Гибридный поиск с эмбеддингами можно добавить за тем же интерфейсом BM25Index.search.

2026-10-03 — ADR-010: Фокус — ветераны СВО; разработчики делят слои, а не направления

Контекст: три направления (ветераны, семьи, общая популяция с депрессией) и три разработчика. Если каждый ведёт своё направление, все трое правят одни и те же файлы: движок, API, дашборд. Решение: на хакатоне делаем только ветеранов (эпик #35); семьи (#40) и общая популяция (#43) — опциональные направления на будущее, без срока. Разработчики делят слои: A — бот (диалог, каналы, LLM), B — backend (API, сервисы, шедулер, адаптеры, БД, ядро), C — дашборд. Между слоями — замороженные контракты (#34) с заглушками, поэтому все трое стартуют одновременно. Направления подключаются как app/dialog/flows/<module>.py + config/modules.yaml. Причина: ноль коллизий по файлам при параллельной работе; общее ядро переиспользуется направлениями, как и задумано в ADR-001. Главный герой демо — Андрей (решение #9). Последствия: изменения контрактов — только мелкими PR [contract] с пингом всех. Владение файлами — в docs/dev/WORKFLOW.md.

2026-10-03 — ADR-009: Процесс — регламент TenVex в облегчённом режиме хакатона

Контекст: 3 дня, сдача в пн 05.10 в 13:00 МСК. Два разработчика и Claude Code-агенты работают параллельно. Опыт TenVex/vobot: без issue и изоляции агенты конфликтуют. Решение: берём ядро регламента vobot: задача = issue, одна зона на issue, worktree + ветка от origin/dev, PR в dev, Conventional Commits, лог в теле issue, ADR сюда. Облегчения: PR в dev можно мержить самому после зелёного make lint test, без обязательного ревью; contract-first/orval нет; main = сдаваемая версия, промоушн dev → main делает человек. Последствия: регламент — docs/dev/WORKFLOW.md.

2026-10-03 — ADR-008: Конфиги в config/, данные в data/

Контекст: требования к оформлению: «конфигурационные файлы — в отдельной папке». В SPEC пороги лежали в data/scales. Решение: config/ — шкалы (пункты, диапазоны, градации), расписания модулей, правила алертов, лексикон риска, тексты для пациента (YAML, вычитывает психиатр). data/ — синтетика, выдержки ГРЛС, eval-разметка. Причина: соответствие чек-листу жюри; психиатр правит только config/, не трогая код.

2026-10-03 — ADR-007: «Действия агента» — это выход движка правил, а не tool-calling LLM

Контекст: в демо-сценарии действия записаны как вызовы инструментов (raise_alert, notify_doctor, crisis_protocol, book_visit). Это выглядит так, будто их решает LLM, а это противоречит правилу «алерты детерминированы». Решение: правила (config/rules.yaml) по структурированным данным возвращают список действий; оркестратор их исполняет. LLM только формулирует реплику вокруг уже принятого действия. Причина: юридическая атрибуция ответственности: пороги задаёт врач, ИИ решений не принимает. Это ключевой аргумент для жюри и для специалистов.

2026-10-03 — ADR-006: Цвета в UI ↔ уровни алертов

Решение: 🔴 = acute (кризис, п.9 ≥ 1, C-SSRS с намерением/планом, доступ к оружию при риске); 🟡 = high + moderate (врачу ≤ 24 ч / флаг к визиту); 🟢 = нет открытых алертов; info (молчание, нет ответа) — серый флаг. В БД хранится уровень, цвет вычисляется.

2026-10-03 — ADR-005: Демо-часы (виртуальное время)

Контекст: демо — 13 дней терапии за 3 минуты. Шедулер на реальном времени это показать не даст. Решение: всё время в системе берётся из app.core.clock (реальное или виртуальное, DEMO_CLOCK=true). В демо-консоли есть кнопка «следующий день». Шедулер срабатывает по сдвигу часов. Правила считают окна (3 дня подряд, 7 дней) от виртуального «сейчас». Последствия: нигде не вызывать datetime.now() напрямую. Проверяется в ревью.

2026-10-03 — ADR-004: Канал-независимый диалоговый движок + веб-демо-консоль + офлайн-режим

Контекст: решение должно запускаться на технике организатора без нестандартного ПО. Telegram и GigaChat на площадке могут быть недоступны. Решение: диалог — чистая функция engine.handle(token, event) -> list[Reply] поверх FSM. Адаптеры: Telegram (aiogram) и веб-чат в демо-консоли (Streamlit). LLM за протоколом с двумя провайдерами: gigachat и mock (детерминированные ответы для демо-реплик). LLM_PROVIDER=mock по умолчанию в docker compose up. Причина: главный критерий жюри — работоспособность. Демо не должно зависеть от сети.

2026-10-03 — ADR-003: Один Postgres, две базы; без Redis и Alembic в MVP

Контекст: в SPEC два контейнера Postgres и Redis. Решение: один сервис postgres с двумя базами (identity, clinical; audit_log лежит в clinical) и двумя ролями: роль клинического модуля не имеет прав на identity. Связь — HMAC-токен. Схема создаётся через create_all при старте. FSM-состояние хранится в таблице dialog_state. Причина: изоляция сохраняется (разные БД и разные роли), а операционной сложности меньше. Alembic для трёхдневного прототипа — лишнее трение. В проде — отдельные кластеры и миграции.

2026-10-03 — ADR-002: Ежедневный чек-ин = настроение + приём + модульный вопрос; шкалы — по расписанию

Контекст: в SPEC ежедневно собираются 2–3 пункта PHQ-9 в 14-дневном окне. В демо-персоне и в модулях — ежедневно настроение 0–10, приём, сон, алкоголь, а шкалы целиком по расписанию (PHQ-9 еженедельно/раз в 2 недели) и внепланово по триггеру. Решение: берём модель из модулей. Ежедневно: настроение 0–10, приём препарата, один модульный вопрос (сон/кошмары у ветерана, алкоголь при флаге AUDIT-C) и свободный текст (extract → побочки, намерение бросить, алкоголь). Полные шкалы — по расписанию модуля и внепланово (например, настроение ≤ 3 три дня → внеплановый PHQ-9). П.9 PHQ-9 — только кнопками. Последствия: новая таблица daily_checkins (mood, med_taken, sleep_bucket, alcohol_bucket, flags).

2026-10-03 — ADR-001: Общее ядро + три модуля, включаемые скринингом

Контекст: три источника требований (SPEC, демо-персона, концепция/CJM) по-разному ставят фокус: ветераны, депрессия, семьи. Решение: общее ядро (PHQ-9 → C-SSRS, ежедневный чек-ин, молчание как сигнал) и модули veteran, depression, family (CLINICAL_MODULES.md). Модули включает стартовый скрининг и/или врач при подключении пациента. Шкалы, расписания и триггеры модулей описаны декларативно в config/modules.yaml. Приоритет на хакатон: ядро, veteran и depression — P0; family — P1 (вход «Я близкий», чек-лист, кнопка «сообщить врачу»). Кейс: закрываем сценарии «мониторинг после обращения» и «управление приёмом лекарств». Скрининг/триаж — входная точка, а не отдельный третий сценарий.