🔍 Multi-Step Candidate Search Demo

Демо-проєкт для лекції "Advanced AI Patterns" — пошук та ранжування кандидатів на вакансію з використанням AI.

Що демонструє цей проєкт?

Проєкт показує чотири ключові AI-паттерни в дії:

Крок	Паттерн	Що відбувається
1. Парсинг вакансії	Task Decomposition + CoT	AI розбирає текст вакансії на структуровані критерії
2. Пошук кандидатів	Tool Integration	Фільтрація кандидатів з "бази даних" за критеріями
3. Scoring	Scoring + Weighting	Кожен кандидат отримує зважену числову оцінку
4. Ranking + пояснення	Chain-of-Thought + Streaming	AI пояснює покроково, чому кандидат підходить

Технології

• Google Gemini — AI модель для аналізу та генерації
• Vercel AI SDK — уніфікований інтерфейс для роботи з LLM
• Node.js — серверне середовище виконання
• Google AI Studio — платформа для отримання API ключа

Швидкий старт

1. Отримайте API ключ

1. Перейдіть на Google AI Studio
2. Натисніть "Create API Key"
3. Скопіюйте ключ

2. Встановіть залежності

# Клонуйте або скопіюйте проєкт
cd candidate-search-demo

# Встановіть залежності
npm install

3. Налаштуйте API ключ

# Створіть .env файл з вашим ключем
cp .env.example .env

# Відкрийте .env і вставте ваш ключ
# GOOGLE_GENERATIVE_AI_API_KEY=ваш_ключ_тут

4. Запустіть демо

npm start

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

candidate-search-demo/
├── src/
│   ├── index.js                      # Точка входу — запускає всі кроки послідовно
│   ├── data/
│   │   └── candidates.js             # Mock база з 12 кандидатами
│   ├── steps/
│   │   ├── step1-parse-vacancy.js    # AI парсить вакансію → JSON критерії
│   │   ├── step2-search.js           # Фільтрація кандидатів (без AI)
│   │   ├── step3-score.js            # Scoring: зважена оцінка кожного
│   │   └── step4-rank-and-explain.js # AI пояснює вибір (streaming)
│   └── utils/
│       └── ai.js                     # Ініціалізація Gemini через Vercel AI SDK
├── package.json
├── .env.example
├── CLAUDE.md                         # Інструкції для Claude Code
└── README.md                         # Цей файл

Як це працює (покроково)

Крок 1: Парсинг вакансії (Task Decomposition)

AI отримує текст вакансії і розбиває його на структуровані критерії:

Вхід:  "Шукаємо Senior React Developer, TypeScript, досвід 3+ роки..."
Вихід: { requiredSkills: ["React", "TypeScript"], minExperience: 3, ... }

Тут застосовується Chain-of-Thought — промпт просить AI міркувати покроково.

Крок 2: Пошук кандидатів (Tool Integration)

Звичайна фільтрація по масиву (імітація запиту до бази даних):

• Має хоча б одну обов'язкову навичку
• Достатній досвід

Крок 3: Scoring (Scoring + Weighting)

Кожен кандидат оцінюється за формулою:

Score = 0.40 × skillMatch
      + 0.25 × experienceScore
      + 0.20 × languageMatch
      + 0.15 × availabilityScore

Всі фактори нормалізовані до шкали 0–1.

Крок 4: Ranking + Пояснення (CoT + Streaming)

Топ-3 кандидати отримують AI-пояснення в режимі streaming — текст з'являється поступово, як у ChatGPT.

Паттерни для вивчення

Після запуску демо, зверніть увагу на:

1. Промпти — подивіться файли в src/steps/, як сформульовані промпти для AI
2. Structured Output — як AI повертає JSON замість вільного тексту (крок 1)
3. Scoring формула — як зважена сума перетворює якісні характеристики на числа (крок 3)
4. Streaming — різниця між generateText (чекаємо всю відповідь) і streamText (бачимо по символу) (крок 4)

Експерименти

Спробуйте змінити:

• Ваги у scoring (step3-score.js) — що буде, якщо мова стане найважливішим фактором?
• Вакансію (index.js) — замініть на "Data Scientist" або "Mobile Developer"
• Промпт для пояснення (step4-rank-and-explain.js) — додайте "оціни ризики найму цього кандидата"
• Модель (utils/ai.js) — спробуйте gemini-2.0-flash vs gemini-1.5-pro

Вирішення проблем

Проблема	Рішення
GOOGLE_GENERATIVE_AI_API_KEY is not set	Перевірте, що .env файл створено і ключ вставлено
429 Too Many Requests	Зачекайте хвилину — безкоштовний тариф має ліміти
Cannot find module	Запустіть npm install
Відповідь AI не парситься як JSON	Перезапустіть — іноді модель додає зайвий текст

Корисні посилання

• Vercel AI SDK — документація
• Google AI Studio
• @ai-sdk/google — npm
• Gemini API — документація

---

Створено для лекції "Advanced AI Patterns" · AI Fundamentals