Обзор архитектуры

Жизненный цикл запроса

Один пользовательский вопрос проходит этот путь до того, как вернётся grounded-ответ. Диаграмма покрывает синхронный путь /api/ask; пути ingest и admin используют ту же поверхность, но пропускают стадию LangGraph.

Путь одностoронний; узловой цикл LangGraph (retry, rewrite_query) живёт внутри блока Graph и подробно описан на странице Конечный автомат LangGraph. Каждый узел, хранилище и провайдер мапится на каталог ниже.

Модули верхнего уровня

api/

Тонкая оболочка FastAPI + роутеры по функциональным областям (auth, sessions, agent, admin, analytics, feedback, conversation, upload). Позднее связывание через api._shared.app_module() сохраняет работоспособность тестов с monkeypatch.setattr(api.app, …).

agent/

Конечный автомат LangGraph: state.py (форма TypedDict), graph.py (узлы + рёбра), prompts.py, prompt_registry.py (sticky-rollout с поддержкой экспериментов), tools.py. См. автогенерируемую страницу Конечный автомат LangGraph.

llm/providers/

Подключаемая абстракция провайдеров: интерфейс base.py, ollama.py, gracekelly.py (browser-прокси к Perplexity Pro), mistral.py (OpenAI-совместимый). Failover к локали через профили маршрутизации. См. матрицу маршрутизации провайдеров.

vectordb/

Гибридный ретривер (BM25 + dense + cross-encoder rerank). Tenant-aware vectordb.manager оборачивает базовый ChromaDB-движок из _base_manager.py; каждый тенант приземляется в отдельную коллекцию.

evaluation/

Онлайн- и офлайн-оценщики, RAGAS-style метрики без пакета ragas, regression-раннер с дефолтным mock-ом для платных API, реестр экспериментов, rollback-watcher, недельный backlog улучшений, рекомендации порогов.

tracing/

tracing._base_trace — каноничное SQLite-хранилище; tracing.sqlite_trace — публичный API поверх него, добавляющий PII-редакцию на log_step (production-код импортирует из tracing.sqlite_trace). Адаптеры Langfuse и OpenTelemetry экспортируют те же span-данные, когда настроены.

Хранилища данных

Хранилище	Назначение	Замечания
ChromaDB	Векторное хранилище для чанков базы знаний.	Коллекция на тенанта. Персистентно на диске.
SQLite	Каноничное хранилище трейсов LangGraph (`tracing.sqlite_trace` поверх `tracing._base_trace`).	WAL-режим; runtime-хранилище, не dev-only fallback.
Postgres	Сессии, фидбэк, эскалации, эксперименты.	Alembic-миграции 001–017. Round-trip CI gate. Трейсинг сюда не пишется.
Redis	Счётчики rate-limit, JWT refresh-сессии, эфемерный кеш.	Опциональный в dev (in-memory fallback).

Сквозные аспекты

Мульти-тенантность обеспечивается на четырёх уровнях: схема (колонки tenant_id), пропагация (api/middleware/tenant.py), enforcement в запросах (фильтры в каждом роутере), отдельные ChromaDB-коллекции на тенанта.
Resilience — вызовы провайдеров обёрнуты в настраиваемую цепочку слоёв timeout, retry, circuit-breaker, semaphore и wall-time budget; точная композиция живёт в llm/providers/runtime.py.
Observability поставляется с 24+ Prometheus-метриками, alert-правилами в deploy/helm/ и трейсингом generation через OpenTelemetry → Langfuse.
Безопасность остаётся fail-fast на отсутствии JWT/SESSION/admin-секретов на старте при RAG_ENV=production. Изоляция тенантов проверяется cross-tenant на каждой поверхности.