RAG_helper/README.md

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 (RAG-сервис для врачей). Переиспользуем паттерн сервисов embeddings.py / vectorstore.py / document_processor.py / llm_client.py.

---

План (спринты)

См. docs/SPRINTS.md. Архитектурные документы и разобранные примеры — в docs/architecture/ и docs/examples/.

---

Запуск

Требования

• Python 3.12
• Ключ DeepSeek API

Установка

python3.12 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env   # и вписать DEEPSEEK_API_KEY

Старт

.venv/bin/python -m uvicorn main:app --host 0.0.0.0 --port 8003

Миграции Alembic применяются автоматически на старте. Первая загрузка embedding-модели E5-large занимает ~15–20 секунд.

Вручную накатить миграции

.venv/bin/alembic upgrade head

Создать новую миграцию после изменения моделей

.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 — RAG для врачей, источник технических паттернов.
• work-pcs-pt-mobile — мобильное приложение пациента (канал подключит другой разработчик).
• work-pcs-pt-bots — пациентские боты МАКС (канал подключит другой разработчик).