---
title: "AI Matcher"
description: "AI-рушій матчингу Ring — LLM-powered Matcher із вісьмома оціненими факторами, базовий fallback NeuralMatcher, підсумки модерації та training-пайплайн над журналом подій"
locale: "uk"
---
# AI Matcher

> **Info**
> Використовуйте вкладки **Founder** / **Developer** у бічній панелі, щоб відфільтрувати цю сторінку. Цикл функції (create → match → notify) описано в [Opportunities](/docs/features/opportunities.md); ця сторінка — **рушій** за оцінками.

AI Matcher — рушій матчингу Ring: він оцінює кожного кандидата щодо opportunity за **вісьмома факторами**, пояснює *чому* у ≤160 символів і падає на базовий векторний матчер, коли LLM не налаштовано. Та сама AI-поверхня також стискає звіти модерації сутностей для адмін-черги.

| Previous | Ring equivalent |
|----------|-----------------|
| Keyword search on listings | Оцінений матчинг кандидатів із LLM-поясненнями |
| One model, hard-coded | Model router (`lib/ai/model-router`) із класами задач |
| Matching quality guesswork | Training-пайплайн вчиться з подій `opportunity_matched` / `application_success` |
| Manual moderation triage | Однореченні LLM-підсумки звітів → адмін-черга + tunnel notify |

## Вісім факторів оцінки

`MatchFactors` у `lib/ai/types.ts` (кожний 0–100): `skillMatch`, `experienceMatch`, `industryMatch`, `locationMatch`, `budgetMatch`, `availabilityMatch`, `careerMatch`, `cultureMatch`.

Рантайм-пороги — це **конфіг клону**, не kingdom-wide SLA. Типові значення (`ring-config.json → matcher`): `scoreThreshold` **0.7**, `maxMatches` **10**, `autoApprove` **false**, `autoApproveMinScore` **0.7**, `llmConfidenceGate` **0.8**. Пояснення обрізаються до **≤160 символів** у `MatchingService`.

### For founders

## Чому це важливо для вашого клону

- **Матчі знаходять учасників.** Нові opportunities запускають пайплайн матчера й сповіщають найкращі збіги — учасникам не потрібно шукати в стрічці.
- **Пояснення будують довіру.** Кожне сповіщення несе коротке «чому це вам підходить», а не лише оцінку.
- **Ви контролюєте пороги.** Налаштуйте `scoreThreshold`, `maxMatches` і auto-approve в **Admin → Platform Settings → AI → Matcher**; тримайте auto-approve вимкненим, доки не довіряєте даним вертикалі.
- **Модерація стає простішою.** Звіти по сутностях LLM стискає в одне речення для адмін-черги.

### Чеклист оператора

1. Тримайте пороги Matcher на типових значеннях, доки не зʼявиться реальний трафік.
2. Переглядайте смуги якості матчів (high ≥80 / medium 60–79 / low <60) в аналітиці Matcher — це сигнали, не гарантії.
3. Коли впевнені, підніміть `maxMatches` або увімкніть `autoApprove` з його score- та LLM confidence-гейтами.

### For developers

## Модулі рушія (перевірено)

| Module | Role |
|--------|------|
| `lib/ai/matcher.ts` | Клас `Matcher` — LLM-оцінювання + пояснення; завантаження профілів кандидатів у `cache()` |
| `lib/ai/neural-matcher.ts` | Базовий `NeuralMatcher` — подібність тег/вектор через `lib/ai/vector-store`, коли LLM недоступний |
| `lib/ai/matcher-moderation-notify.ts` | Однореченні LLM-підсумки звітів модерації сутностей → адмін-черга + tunnel-канал |
| `lib/ai/training-pipeline.ts` | `AITrainingPipeline` — supervised-приклади з журналу подій (`opportunity_matched`, `application_success`) |
| `lib/ai/model-router/` | Каталог моделей, класи задач і резолюція |
| `lib/ai/user-profile-loader.ts` | Мапить документи `users` → `UserProfile`; обмежено `MATCHING_MAX_CANDIDATES` |
| `lib/ai/llm-client.ts` | Гейти доступності `createLLMClientAsync` / `isLLMAvailableAsync` |
| `lib/ai/types.ts` | `MatchFactors`, `LLMConfig`, `AIOperationError` |

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

**Environment (лише fallback — config має пріоритет)**

{`MAX_MATCHES_PER_OPPORTUNITY=10   # fallback cap
MATCHING_SCORE_THRESHOLD=0.7      # fallback min score
MATCHING_MAX_CANDIDATES=200       # candidate scan cap`}

`Matcher` надає перевагу resolved AI-конфігу з `features/admin/platform-settings/resolved-ai-config`; env-значення — fallback, які читаються під час конструкції.

**Конфіг клону (`ring-config.json → matcher`)**

{`"matcher": {
  "scoreThreshold": 0.7,
  "maxMatches": 10,
  "autoApprove": false,
  "autoApproveMinScore": 0.7,
  "llmConfidenceGate": 0.8
}`}

Override існують на клон; env `MATCHER_AUTO_APPROVE` / `MATCHER_AUTO_APPROVE_MIN_SCORE` також можуть перемикати auto-approve.

### Як протікає match run

`OpportunityMatchingService` → `Matcher` (LLM) або `NeuralMatcher` (baseline) → `MatchFactors` + пояснення → fan-out сповіщень. Зіставлені користувачі відкривають opportunity; їхні реакції живлять колекцію подій training-пайплайну.

## Повʼязана документація

  
- [features/opportunities](/docs/features/opportunities.md) — Same-workflow: create → match → notify, плюс Contact у browse-feed, який best-effort записує contact_intent.

  
- [architecture/discovery-mutation-sync](/docs/architecture/discovery-mutation-sync.md) — Deep-dive: як нові opportunities запускають пайплайн матчера й тримають картки матчів свіжими.

  
- [features/admin](/docs/features/admin.md) — See-also: пороги Matcher живуть у адмін platform settings.