HelpDesk Copilot ВТБ

AI-агент первой линии поддержки сотрудников банка ВТБ. On-prem, air-gapped по умолчанию. RAG + LangGraph + действия через mock-коннекторы (AD, Naumen, 1С: ЗУП, Exchange).

Полная спецификация: docs/architecture.md. Бриф для разработчика: docs/brief.md.

Что внутри

Слой	Технологии
API	FastAPI 0.115, Pydantic v2, SQLAlchemy 2.0 async
Хранилище	PostgreSQL 15 + pgvector (HNSW + ivfflat), Redis 7
Очереди	Celery 5 + Celery Beat
Оркестрация	LangGraph-стиль explicit state machine (apps/orchestrator)
RAG	bge-m3 / mock, BM25 (pgvector tsvector) + vector + RRF
LLM	mock / YandexGPT / GigaChat / vLLM (Qwen2.5-14B-AWQ on-prem)
Каналы	React 18 widget, Telegram bot (aiogram 3)
Observability	Prometheus + Grafana + Loki + OpenTelemetry
Eval	Self-contained e2e_eval/ (gold_500, adversarial, regression)

15-минутный quickstart

# 1) клонировать
git clone https://github.com/axisbeeintroduce/helpdesk-copilot.git
cd helpdesk-copilot

# 2) создать .env
cp .env.example .env

# 3) поднять Postgres + Redis + Prometheus + Grafana
make up

# 4) применить миграции и засеять mock-доки
make migrate
make seed

# 5) запустить API
make api          # http://localhost:8000/docs

# 6) виджет
make widget       # http://localhost:5173

Готово — открой widget, спроси «не могу войти в AD» → бот предложит сбросить пароль.

Запуск тестов и линтеров

make install      # uv pip install -e ".[dev]"
make check        # ruff + mypy + pytest
make eval-gate    # e2e_eval (gold_500.jsonl) + thresholds gate

Структура

apps/
  api/             # FastAPI: /v1/chat, /v1/admin, /v1/knowledge, /v1/health, /metrics
  orchestrator/    # LangGraph state machine + YAML scenarios + LLM clients
  rag/             # ingest, chunker, embedder, hybrid retriever
  connectors/      # MockConnector + registry (AD/Naumen/1С/Exchange)
  workers/         # Celery tasks (reindex, csat, shadow)
  bot/             # Telegram bot (aiogram 3)
  widget/          # React 18 widget (Vite + TypeScript)
infra/
  alembic/         # миграции (initial schema + HNSW)
  seed/            # mock confluence/naumen документы
e2e_eval/
  datasets/        # gold_500.jsonl, adversarial.jsonl, regression.jsonl
  judges/          # retrieval, hallucination, pii, llm_judge
  thresholds.yaml  # CI gate
security/
  network-policies/
  vault/
  tls/
docs/
  architecture.md
  runbook.md
  threat-model.md
  api.md
deploy/
  docker-compose.dev.yml
  prometheus.yml
  grafana/

Запреты (compliance, §14)

• Запрещены импорты: openai, anthropic, google.generativeai, azure.ai.openai, cohere. Проверка CI: <ref_snippet/> tests/test_forbidden_imports.py.
• Запрещены лицензии: AGPL, SSPL, GPL, BUSL, Commons Clause, Elastic 2.0. Проверка CI: make licenses.
• PII в логах: redact + SHA-256 от user_id (152-ФЗ).
• Free-form агенты: НЕТ. Только explicit graph (apps/orchestrator/src/graph.py).

Что НЕ строим (§3)

• Поддержка клиентов ВТБ (только сотрудники).
• Доступ к ABS, процессингу, скорингу, антифроду.
• Голосовой канал, Outlook add-in (v2).
• Fine-tune LLM в MVP (только prompt-engineering + RAG).

Лицензия

Apache-2.0.