University AI Assistant — RAG Worker

Воркер в стиле Clean Architecture и тактического DDD: забирает вопросы из NATS, гоняет RAG-пайплайн (LangGraph + FAISS + OpenAI), стримит токены обратно в NATS, пишет статусы и ответы в Redis.

---

Обзор структуры

src/app/
├── domain/               # Чистый домен — value objects, исключения, без I/O
├── application/
│   ├── commands/         # ProcessQuestionHandler (одна команда)
│   └── common/ports/     # Порты: RagPipeline, StatusWriter и т.д.
├── infrastructure/
│   ├── adapters/         # Redis, NATS
│   ├── knowledge/        # YAML → доменные документы + FAISS (кеш)
│   └── rag/              # LangGraph: узлы, промпты, состояние графа
├── presentation/
│   └── messaging/        # NatsQuestionConsumer — «контроллер» брокера
└── setup/
    ├── config/           # WorkerSettings, structlog
    └── ioc/              # Dishka: settings, infrastructure, application

---

Ключевые решения

RagPipeline как порт (DIP)

Обработчик зависит только от абстрактного RagPipeline:

class RagPipeline(ABC):
    def stream_tokens(self, session_id, question) -> AsyncIterator[str]: ...

Реализация в инфраструктуре (LangGraphRagPipeline). Смена LLM или retrieval — новый адаптер, слой application не трогаем.

Загрузка знаний отдельно от индексации

loader.py → доменные KnowledgeDocument без LangChain.
vector_store.py → перевод в LangChain и FAISS.

Кеш FAISS по сигнатуре файлов

SHA-256 по (path, mtime_ns, size) для каждого YAML; при изменении знаний индекс перестраивается, лишний embed на каждый старт не делаем.

NatsQuestionConsumer как presentation

Как HTTP-контроллер мапит запрос в DTO, так consumer мапит сырой NATS → ProcessQuestionCommand; бизнес-логика только в хендлере.

---

Локальный запуск (через Make)

Нужны запущенные Redis и NATS (например, из репозитория assistant-chat-backend).

make install              # poetry install --extras dev
cp .env.example .env      # задать OPENAI_API_KEY и пути (см. .env.example)
mkdir -p knowledge .vector_cache

Убедитесь, что в .env для хоста указаны REDIS_URL / NATS_URL на localhost (как в примере), а KNOWLEDGE_DIR / VECTOR_CACHE_DIR — на каталоги с YAML и кешом на машине.

Запуск воркера:

make run

Проверка: GET http://localhost:8001/health
Логи: JSON в stdout (structlog); при заголовке X-Trace-Id он попадает в контекст логов.

---

Docker (только воркер)

Redis и NATS поднимаются в assistant-chat-backend (там же создаётся сеть assistant-net). В этом репозитории — только сервис rag-worker, подключённый к внешней сети assistant-net.

1. В каталоге backend: docker compose up -d (чтобы сеть и брокеры были живы).
2. В .env воркера — URL вида redis://redis:6379/0, nats://nats:4222 (или assistant-redis / assistant-nats, если используете container_name), плюс KNOWLEDGE_DIR=/app/knowledge, VECTOR_CACHE_DIR=/app/.vector_cache.
3. Сборка и старт:

cp .env.example .env
mkdir -p knowledge .vector_cache
make app-build
make app

Логи воркера:

make logs

Остановка контейнера воркера:

make app-down

Пересборка и перезапуск:

make app-restart

Снаружи публикуется порт 8001 (HTTP health).

---

Makefile

Цель	Действие
make install	Установить зависимости (включая dev)
make run	Локально запустить воркер (PYTHONPATH=src)
make app	docker compose up -d
make app-build	Пересобрать образы
make app-down	Остановить compose-стек воркера
make app-restart	down + up -d
make logs	docker compose logs -f rag-worker
make test	Тесты
make typecheck	mypy src
make lint	ruff check .
make clean	Очистка кешей

---

Тесты

make test

Юнит-тесты не требуют Redis, NATS и OpenAI.

---

Пример: новая возможность (кеш ответов)

1. Порт — AnswerCache(ABC) в application/common/ports/.
2. Адаптер — например RedisAnswerCache в infrastructure/adapters/.
3. Провайдер — в setup/ioc/infrastructure.py.
4. Хендлер — внедрить и вызвать в ProcessQuestionHandler.

Остальные слои можно не трогать.