Схвалення

HITL-воркфлоу

Кожна згенерована AI відповідь може пройти людський рев'ю перед тим, як піти до кінцевого користувача. HITL-система забезпечує якість і compliance у чутливих або низькоконфіденсних відповідях.

Коли тригериться HITL

Відповідь іде на HITL, якщо спрацьовує будь-яка з цих умов:

1. Низький confidence — RAG confidence score < 0.7
2. Тригер-слово — повідомлення користувача або відповідь містить сконфігуроване тригер-слово (наприклад, конфлікт, суд, штраф, звільнення, lawsuit, termination)
3. Перша взаємодія — співробітник використовує конкретний намір вперше
4. Довіра не встановлена — намір ще не досяг порогу автономності
5. Стохастичний семплінг — навіть автономні наміри відправляють частку (дефолт 10%) на HITL для постійного контролю
6. Виявлено prompt injection — патерни prompt injection знайдені у повідомленні користувача або RAG-контексті

Потік статусів схвалення

pending → approved   (send to user)
        → rejected   (discard, log reason)
        → edited     (content modified)
        → escalated  (routed to higher role)

Дії

Approve

Схвалює відповідь AI як є. Відповідь стає у чергу на відправку у канал.

POST /api/v1/approvals/:id/approve

Approve with edit

Схвалює відредаговану версію відповіді. editedContent замінює оригінал.

POST /api/v1/approvals/:id/approve
Body: { "editedContent": "Modified response text" }

Reject

Відхиляє відповідь. Нічого не відправляється. Approver може дати коментар з причиною.

POST /api/v1/approvals/:id/reject
Body: { "reason": "Inaccurate information about policy X" }

Escalate

Маршрутизує схвалення на користувача з вищою роллю (наприклад, з approver до dept_head).

POST /api/v1/approvals/:id/escalate
Body: { "escalatedToId": "<user-id>", "reason": "Legal question, needs dept head review" }

Оновлення матриці довіри

Коли схвалення підтверджене:

• successfulCount наміру інкрементується
• Коли successfulCount >= threshold (дефолт 5), isAutonomous стає true
• Майбутні повідомлення з таким наміром можуть обходити HITL (з урахуванням samplingRate)

Див. Auto-Bypass для повної логіки ухвалення рішення про автономність.

Рев'ю схвалення

Деталі схвалення містять:

• Оригінальну AI-відповідь
• Використані RAG-джерела (чанки, документи, scores)
• Класифікований намір
• Confidence score
• Контекст розмови

GET /api/v1/approvals/:id

Audit trail

Усі дії зі схваленнями логуються в audit log:

• дії approve, reject, escalate
• актор (користувач, що схвалив)
• таймстамп
• будь-які правки чи коментарі

---

Пакетне схвалення

Обробляйте кілька схвалень в одному API-виклику для ефективності в пікові періоди.

Ендпоінт

POST /api/v1/approvals/batch

Запит

{
  "decisions": [
    { "approvalId": "approval-1", "action": "approve" },
    { "approvalId": "approval-2", "action": "approve", "editedContent": "Modified response" },
    { "approvalId": "approval-3", "action": "reject", "reason": "Inaccurate" }
  ]
}

Обмеження

• Максимум 50 рішень на запит
• Кожне рішення обробляється окремо — можливі часткові збої
• Авторизація: дозвіл canApprove

Відповідь

Повертає результати для кожного рішення зі статусом success/failure:

{
  "results": [
    { "approvalId": "approval-1", "status": "success" },
    { "approvalId": "approval-2", "status": "success" },
    { "approvalId": "approval-3", "status": "success" }
  ]
}

Кейс використання

UI-черга схвалень підтримує батч-селекшн. Approvers можуть вибрати кілька pending-схвалень і підтвердити або відхилити їх одним запитом. Корисно для розгрібання рутинних запитів, що назбирались за неробочий час.

---

Auto-Bypass (матриця довіри)

Матриця довіри дає AI-асистенту поступову автономність. Поки люди рев'юять відповіді на конкретні наміри, система вчиться — які наміри безпечно відправляти автоматично.

Як це працює

Модель матриці довіри (IntentTrust)

Кожна комбінація простір імен + намір має trust-запис:

Поле	За замовчуванням	Опис
successfulCount	0	Кількість підтверджених схвалень
threshold	5	Скільки схвалень потрібно для автономності
isAutonomous	false	Чи увімкнена автовідправка
samplingRate	0.1	Частка, що все одно йде на HITL (10%)

Логіка ухвалення рішення про автономність

1. Message received
2. Intent classified (vector similarity)
3. Check confidence fallback:
   a. Confidence < 0.7 → FORCE HITL
   b. Trigger word detected → FORCE HITL
   c. First interaction for this intent → FORCE HITL
4. If fallback triggered → create Approval, wait for human
5. Check trust matrix:
   a. Not autonomous → HITL
   b. Autonomous + random() > samplingRate → AUTO-SEND
   c. Autonomous + random() <= samplingRate → HITL (sampling)

Confidence fallback

Реалізація: src/channels/bypass.ts

Три умови завжди форсують HITL, навіть для автономних намірів:

1. Низький confidence: RAG confidence < 0.7 — система не впевнена у відповіді
2. Тригер-слова: налаштовувані ключові слова, що сигналізують про чутливі теми (задаються через INTENT_TRIGGER_WORDS)
3. Перша взаємодія: перше повідомлення співробітника з таким класифікованим наміром

Стохастичний семплінг

Навіть якщо намір повністю автономний, частка відповідей (дефолт 10%) випадково маршрутизується на HITL. Це дає:

• постійний контроль якості;
• виявлення drift;
• безперервний сигнал для навчання.

samplingRate налаштовується для кожного наміру.

Приклад еволюції довіри

Intent: "leave_policy"
Namespace: "hr"

Day 1: 0/5 approved → HITL for all
Day 2: 3/5 approved → HITL for all
Day 3: 5/5 approved → autonomous, 90% auto-send
Day 30: 150 total → autonomous, 90% auto-send (with 15 sampled HITL reviews)

API

Переглянути матрицю довіри

GET /api/v1/intents/trust?namespaceId=<id>

Повертає всі trust-записи намірів для простору імен. Авторизація: дозвіл canManageNamespaces.

Скинути довіру

Щоб вимкнути автономність для наміру — оновіть trust-запис у БД, виставивши isAutonomous: false і successfulCount: 0 (на зараз API-ендпоінта для цього нема).

Конфігурація

Тригер-слова задаються через env:

INTENT_TRIGGER_WORDS=конфлікт,суд,штраф,звільнення,скарга,позов,conflict,lawsuit,fine,termination,complaint