Expert Standards Assistant

ИИ-ассистент для ответов на сложные вопросы по стандартам с использованием Graph RAG

Описание проекта

Цели

Создать ИИ-ассистента, который даёт точные и обоснованные ответы на многоуровневые запросы по нормативным документам: связи между стандартами, влияние изменений параметров, учёт версионности и логические цепочки рассуждений.

Контекст

Пример целевого пользователя (по профилю заказчика): инженер-проектировщик по пожарной безопасности в крупном застройщике — проверяет соответствие разделов ПД нормам (ФЗ-123, СП 4.13130, СП 1.13130 и др.), увязывает требования между документами, готовит материалы к экспертизе.

Технологии

Структура проекта

src/
├── app.py               # Точка входа (FastAPI + Gradio + SPA)
├── config.py            # Конфигурация
├── logging_config.py    # Loguru настройка, request context
├── prompts.py           # Централизованные LLM-промпты
├── api/                 # REST API v2 (018-vite-frontend)
│   ├── router.py        # Главный роутер /api/v2
│   ├── deps.py          # Зависимости (auth, db, admin)
│   ├── auth.py          # Аутентификация (login, register, me, logout)
│   ├── chat.py          # Чат-эндпоинт (RAG pipeline)
│   ├── sessions.py      # Управление диалогами
│   └── admin.py         # Админ-эндпоинты (users, docs, settings, neo4j)
├── models/              # Dataclass модели
│   ├── user.py
│   ├── session.py
│   ├── neo4j.py         # Neo4jConnectionStatus, GraphStatistics
│   ├── document.py      # Document, Chunk, ProcessingStatus
│   ├── rag.py           # RAGResponse, SearchResult, RouteDecision
│   ├── graph.py         # GraphNode, GraphPath, GraphSearchResult
│   ├── embedding.py     # Embedding модели
│   └── evaluation.py    # Модели для QA Evaluation
├── cli/                 # CLI модули
│   ├── config.py        # CLIConfig, ConfigurationError
│   └── qa_evaluator.py  # QA Evaluation логика
├── services/            # Бизнес-логика
│   ├── auth_service.py
│   ├── user_service.py
│   ├── session_service.py
│   ├── settings_service.py
│   ├── neo4j_service.py         # Singleton для Neo4j (graceful degradation)
│   ├── document_service.py      # CRUD для документов
│   ├── parser_service.py        # Парсинг PDF, DOCX, MD
│   ├── embedding_service.py     # Генерация embeddings (OpenRouter API)
│   ├── embedding_providers/     # Embedding провайдер (OpenRouter)
│   ├── indexing_service.py      # Pipeline обработки документов
│   ├── router_service.py        # Маршрутизация запросов (vector/graph/hybrid)
│   ├── search_service.py        # Векторный поиск в pgvector
│   ├── graph_search_service.py  # Графовый поиск в Neo4j
│   ├── rrf_service.py           # Reciprocal Rank Fusion
│   ├── related_concepts_extractor.py  # Извлечение связанных понятий
│   ├── llm_service.py           # Обёртка для LLM (OpenRouter)
│   ├── rag_service.py           # RAG pipeline оркестратор
│   ├── tracing_service.py       # LangSmith трассировка
│   └── evaluation_service.py    # DeepEval метрики
├── data/                # Работа с БД
│   ├── database.py
│   └── migrations/      # SQL миграции
└── ui/                  # Gradio компоненты (legacy)
    ├── handlers.py      # Обработчики событий (RAG интеграция)
    ├── helpers.py       # Вспомогательные функции (sync wrappers)
    └── components/      # UI компоненты
        ├── auth.py
        ├── chat.py      # Чат с отображением источников
        └── admin.py     # Админ-панель (пользователи, настройки, Neo4j)

frontend/                # Vite + React SPA (018-vite-frontend)
├── src/
│   ├── api/             # API-клиенты (auth, chat, sessions, admin)
│   ├── components/      # React-компоненты + shadcn/ui
│   ├── contexts/        # AuthContext (глобальное состояние)
│   ├── hooks/           # useAuth, useSessions
│   └── pages/           # LoginPage, ChatPage, admin/*
├── vite.config.ts       # Vite конфигурация (base: /)
└── package.json         # Зависимости (React 19, Tailwind 4, shadcn/ui)

uploads/                 # Загруженные документы
specs/                   # Спецификации фич
tests/                   # Тесты

Установка и запуск

Требования

• Python 3.12+
• Docker & Docker Compose
• uv (рекомендуется) или pip

Быстрый старт (Docker)

# Клонирование репозитория
git clone <repo-url>
cd fixiki

# Копирование конфигурации
cp .env.example .env
# Заполните переменные в .env

# Запуск всех сервисов
make run

# Проверка статуса
make health-all

Приложение будет доступно по адресу: http://localhost:3000

Локальная разработка

# Установка зависимостей
uv sync

# Запуск инфраструктуры (PostgreSQL + Neo4j)
make infra

# Запуск приложения
make dev

Команды

Статус разработки

Реализовано

• [x] Базовая структура проекта
• [x] UI на Gradio с авторизацией
• [x] Система аутентификации (регистрация, вход, сессии)
• [x] Админ-панель (управление пользователями, настройки)
• [x] Интеграция с Neo4j (health-check, статистика графа)
• [x] Graceful degradation при недоступности Neo4j
• [x] Загрузка документов (PDF, DOCX, MD) через админ-панель
• [x] Асинхронная обработка документов с FIFO очередью
• [x] Векторное индексирование (pgvector + OpenRouter embeddings API)
• [x] RAG pipeline с векторным поиском и генерацией ответов через LLM
• [x] Отображение источников (документ, раздел) в ответах
• [x] Роутер запросов (vector/graph) с graceful degradation
• [x] Graph RAG с графовым поиском в Neo4j
• [x] Интеллектуальная маршрутизация запросов (ключевые слова + LLM)
• [x] Reciprocal Rank Fusion (RRF) для объединения результатов
• [x] Извлечение и отображение связанных понятий
• [x] Переключение режима поиска для админов (vector/graph/hybrid/auto)
• [x] Структурированное логирование с loguru и request tracing
• [x] Оптимизация графового поиска по ключевым словам
• [x] Извлечение ключевых слов из запросов для улучшения поиска в Neo4j
• [x] Улучшенный UI управления сессиями (фиксированная высота, удаление диалогов)
• [x] Поддержка OpenRouter API для генерации эмбеддингов
• [x] Трассировка RAG-запросов через LangSmith (иерархические spans, метаданные)
• [x] CLI для автоматизированной проверки качества RAG (DeepEval метрики, Gradio API, JSON отчёты)
• [x] Централизация всех LLM-промптов в единый модуль src/prompts.py
• [x] Удаление локального провайдера эмбеддингов, упрощение архитектуры (только OpenRouter API)
• [x] Новый фронтенд на Vite + React 19 + Tailwind CSS + shadcn/ui (замена Gradio)
• [x] REST API v2 для фронтенда (auth, chat, sessions, admin)
• [x] SPA доступно на /, Gradio legacy на /gradio

В работе

• [ ] Интеграция с нормативной базой по пожарной безопасности
• [ ] Community Detection (Louvain clustering)

Команда

Документация

Разработка

• CLAUDE.md — руководство по разработке, команды, стиль кода

Фичи