# Chat Agent for Patients (RAG) — инструмент настройки **RAG-ядро + веб-инструмент для настройки пациентского чат-агента: загрузка wiki, редактирование промпта и правил, прогон сценариев.** Подключение реальных каналов (чат в мобильном приложении, бот в МАКС) делает другой разработчик — этот проект отдаёт ему **готовое RAG-ядро и API** плюс согласованную конфигурацию (системный промпт, правила, снапшот базы знаний). --- ## Статус 🟢 **Active — Спринты 1–2 и доработки (2.5) закрыты, идём на Спринт 3.** Что уже работает: - RAG-ядро: FastAPI + ChromaDB + `intfloat/multilingual-e5-large` + DeepSeek. - Загрузка документов (`.md`, `.txt`, `.pdf`, `.docx`), чанкинг с чисткой markdown-мусора (навигационные блоки, инлайн-ссылки), просмотр чанков с эмбеддингами. - Многошаговый диалог с памятью треда (SQLAlchemy 2.0 async + Alembic + SQLite). История хранится навсегда. - Переиндексация без повторной загрузки файла: сохранённый `raw_text` → новый чанкер. - Две отладочные страницы: «Отладка» (одиночный вопрос, база знаний) и «Песочница» (чат с агентом, список тредов, переименование, удаление). - Markdown-рендер ответов ассистента в «Песочнице». - Системный промпт вынесен в `prompts/system_prompt.md` — правится без кода. --- ## Цель проекта - Поднять 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`. --- ## План (спринты) См. [`docs/SPRINTS.md`](./docs/SPRINTS.md). Архитектурные документы и разобранные примеры — в [`docs/architecture/`](./docs/architecture/) и [`docs/examples/`](./docs/examples/). --- ## Запуск ### Требования - Python 3.12 - Ключ DeepSeek API ### Установка ```bash python3.12 -m venv .venv source .venv/bin/activate pip install -r requirements.txt cp .env.example .env # и вписать DEEPSEEK_API_KEY ``` ### Старт ```bash .venv/bin/python -m uvicorn main:app --host 0.0.0.0 --port 8003 ``` Миграции Alembic применяются автоматически на старте. Первая загрузка embedding-модели E5-large занимает ~15–20 секунд. ### Вручную накатить миграции ```bash .venv/bin/alembic upgrade head ``` ### Создать новую миграцию после изменения моделей ```bash .venv/bin/alembic revision --autogenerate -m "описание изменений" .venv/bin/alembic upgrade head ``` --- ## Использование ### Веб-страницы - `http://localhost:8003/` — **Отладка**: загрузка документов, просмотр чанков со scores и эмбеддингами, одиночный тест-вопрос с 3-колоночным ответом (чанки / промпт / ответ LLM). - `http://localhost:8003/sandbox.html` — **Песочница**: чат с агентом. Слева список сохранённых диалогов, в центре сам чат, справа отладка последнего ответа (найденные чанки + собранный промпт). ### API | Метод | Путь | Назначение | |-------|------|-----------| | GET | `/health` | Статус, кол-во документов и чанков, модель эмбеддингов | | POST | `/documents/upload` | Загрузить файл (`.md`, `.txt`, `.pdf`, `.docx`), сохраняет `raw_text` в SQLite и чанки в Chroma | | GET | `/documents` | Список документов | | GET | `/documents/{id}/chunks` | Чанки документа + их эмбеддинги | | DELETE | `/documents/{id}` | Удалить документ (из Chroma и SQLite) | | POST | `/documents/{id}/reindex` | Переразметить документ с актуальными правилами чанкера | | POST | `/documents/reindex-all` | Переразметить всю базу | | POST | `/query` | Одиночный вопрос (Отладка) | | POST | `/chat` | Отправить реплику в тред (создаёт тред, если `thread_id` не передан) | | GET | `/threads` | Список всех диалогов | | GET | `/threads/{id}` | Тред целиком с историей | | PATCH | `/threads/{id}` | Переименовать | | DELETE | `/threads/{id}` | Удалить тред со всеми сообщениями | ### Правка системного промпта `prompts/system_prompt.md` — читается при старте сервиса. После правки — рестарт. --- ## Структура ``` . ├── README.md # этот файл ├── docs/ # проектная документация (см. ниже) ├── config.py # настройки (Pydantic BaseSettings) ├── main.py # FastAPI app, lifespan, авто-миграции ├── alembic.ini # конфиг Alembic ├── migrations/ # миграции БД ├── prompts/ │ └── system_prompt.md # системный промпт (правится без кода) ├── db/ │ ├── base.py # DeclarativeBase │ ├── session.py # async engine + sessionmaker │ └── models/ │ ├── thread.py # диалоги │ ├── message.py # сообщения │ └── document.py # raw_text документов для reindex ├── models/ # Pydantic-модели API │ ├── requests.py │ └── responses.py ├── routers/ │ ├── health.py │ ├── documents.py # upload / list / chunks / delete / reindex │ ├── query.py # /query (одиночный вопрос) │ ├── chat.py # /chat (диалог с памятью) │ └── threads.py # CRUD тредов ├── services/ │ ├── embeddings.py # E5-large │ ├── vectorstore.py # ChromaDB │ ├── document_processor.py # парсер + чанкер │ ├── text_cleanup.py # чистка markdown-мусора │ ├── document_service.py # SQLite-слой для raw_text │ ├── llm_client.py # DeepSeek │ ├── rag_pipeline.py # /query pipeline │ └── chat_service.py # диалоги: создание треда, сборка контекста ├── static/ │ ├── index.html # страница «Отладка» │ └── sandbox.html # страница «Песочница» └── data/ ├── chroma/ # векторная БД (gitignored) └── sqlite/ # реляционная БД (gitignored) ``` ### Документация (`docs/`) ``` docs/ ├── SPRINTS.md # план и статус спринтов ├── architecture/ │ ├── GRAPH_ARCHITECTURE_v1.md # черновик при развороте 2026-04-23 │ ├── GRAPH_ARCHITECTURE_v2.md # уточнения 2026-04-24 │ └── GRAPH_ARCHITECTURE_v3.md # текущая (билингв. термины + ссылки на примеры) └── examples/ ├── 01_basic_booking.md # happy path записи (линейный) ├── 02_price_during_booking.md # soft-insertion vs. hard-handoff └── 03_child_patient_guard.md # guard в шаге qualify (запись ребёнка) ``` --- ## Связанные проекты - [`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) — пациентские боты МАКС (канал подключит другой разработчик).