← всі звіти · index.md

Search Campaign Builder

Статус: 🟡 MVP v2 (mock-mode працює, чекає Google Ads OAuth) Оновлено: 2026-04-23 Готовність: ~70% (pipeline готовий, потрібен OAuth handoff + живий тест)

Зміни 2026-04-23 (v2)

Додано 5-й агент VolumeEnricher (volume_enricher.py) — Google Ads KeywordPlanIdeaService, реальні volumes + competition + 12-місячна динаміка + tренд. Mock-fallback якщо OAuth не налаштований.
Додано 6-й агент AssetGenerator (asset_generator.py) — 4 sitelinks + 6 callouts + structured snippet + опційний promotion.
Legal gate перенесено з keyword stage на headlines/descriptions (за запитом Сергія — keyword picking не потребує legal).
Pipeline: Research → Volume → Copy → Legal → Assets → CSV (6 кроків).
CSV v2: keywords тепер з Avg Monthly Searches, Competition, Trend %, Mock?. Додано окремий файл _assets.csv.
Тест-прогін: Хеафолік thematic → 3 групи × 10 kw, 15H+9D (Legal: 22 SAFE / 2 WARN), 4+6+1 assets — всі 3 CSV згенеровані.

Залежності

google-ads SDK v30.1 у /srv/projects/search-campaign-builder/.venv/
Gemini CLI (для research/copy/assets)
/srv/projects/legal-advisor/agent.py (для Legal gate)
/srv/passepartout/google/google-ads.yaml — чекається від Сергія (Client ID + Secret з GCP ad-analytics-hub)

Мета

Автоматизація підготовки Google Ads Search кампаній:

Підбір і кластеризація ключових слів
Написання RSA (Responsive Search Ads) текстів
Перевірка legal compliance через Legal Advisor Agent
Вивід у готовий до імпорту формат (Google Ads Editor CSV)

Архітектура

┌─────────────────────────────────────────────────────┐
│               Search Campaign Builder                │
│                                                     │
│  1. KeywordResearcher                               │
│     • Семантика по продукту/темі                    │
│     • Кластеризація за наміром (branded/generic/    │
│       thematic/competitor)                          │
│     • Оцінка обсягу і конкуренції                  │
│                                                     │
│  2. LegalAdvisor (вже є: /srv/projects/legal-advisor)│
│     • Перевіряє ключові слова на відповідність      │
│       законодавству ЗУ "Про рекламу" / Закон 4122  │
│     • Виключає медичні терміни для БАД              │
│     • Позначає ризикові кластери                    │
│                                                     │
│  3. AdCopywriter                                    │
│     • 3 варіанти заголовків на кластер (до 30 симв) │
│     • 2 варіанти описів (до 90 симв)                │
│     • Пінування заголовків (#1, #2, #3)             │
│     • Legal compliance вбудований в промпт          │
│                                                     │
│  4. CampaignFormatter                               │
│     • Генерує CSV для Google Ads Editor             │
│     • Формат: Campaign / AdGroup / Keyword / Ad     │
│     • Match types: Exact + Phrase                   │
└─────────────────────────────────────────────────────┘

Типи кампаній (по описанню Сергія)

Тип	Бюджет	KPI	Обмеження
Брендовий пошук	10-15 тис. грн/міс	Impression Share, CPC	—
Тематичний	за темою	CTR, CPA	Legal (для БАД)
Конкурентний	обережно	CPC, CR	Trademark
Generic (симптоми)	за обсягом	CPA	Legal (особливо суворо)

Вхідні параметри

build_campaign(
    product_name: str,          # "Хеафолік"
    product_type: str,          # "дієтична добавка" | "лікарський засіб"
    campaign_type: str,         # "branded" | "thematic" | "competitor" | "generic"
    themes: list[str],          # ["випадіння волосся", "тонкі волосся", "біотин"]
    target_audience: str,       # "жінки 25-55"
    geo: str,                   # "Україна"
    budget: int,                # 15000  (грн/міс)
    competitors: list[str],     # ["Perfectil", "Pantovigar"]  (для конкурентних)
    max_keywords_per_group: int # 10
)

Вихідний формат (Google Ads Editor CSV)

Campaign,Ad Group,Keyword,Match Type,Max CPC,Final URL
Хеафолік | Branded,Хеафолік бренд,хеафолік,Exact,5.00,https://...
Хеафолік | Branded,Хеафолік бренд,купити хеафолік,Phrase,4.00,https://...
Хеафолік | Тематика | Волосся,Випадіння волосся,вітаміни від випадіння волосся,Phrase,3.00,https://...

Campaign,Ad Group,Headline 1,Headline 2,Headline 3,Description 1,Description 2,Pinned Headline 1
Хеафолік | Branded,Хеафолік бренд,Хеафолік — офіційний сайт,Вітаміни для волосся,Сприяє зміцненню волосся,Комплекс мікроелементів для здоров'я волосся. Дієтична добавка.,Підтримує зростання і сприяє зміцненню структури волосся.,1

Правила Legal Advisor для Search

Заборонені слова (критично):

лікує, зцілює, позбавляє від, алопеція, гарантовано
100%, клінічно доведено (без посилання на дослідження)

Дозволені формулювання:

сприяє зміцненню, підтримує, містить, допомагає підтримувати
комплекс для волосся, вітаміни для волосся

Обов'язковий дисклеймер (у розширеннях):

"Дієтична добавка. Не є лікарським засобом."

Ключові слова — сірі зони:

від випадіння волосся — низький ризик (описово, не лікувально)
лікування алопеції — ЗАБОРОНЕНО (медичний діагноз)
проти облисіння — середній ризик

Файлова структура проекту

/srv/projects/search-campaign-builder/
├── builder.py              # Оркестратор (main)
├── keyword_researcher.py   # Агент 1: семантика
├── ad_copywriter.py        # Агент 3: тексти оголошень
├── campaign_formatter.py   # Агент 4: CSV форматер
├── output/                 # Готові CSV для завантаження
│   └── {brand}_{date}_search.csv
└── README.md

Залежності

/srv/projects/legal-advisor/agent.py — Legal Advisor (готовий)
Gemini CLI (gemini -p) — для всіх агентів
Python 3.11+, pathlib, csv

Пріоритет інтеграції

✅ Legal Advisor — готовий
🔜 Search Campaign Builder — MVP: keywords + RSA
🔜 Інтеграція Legal Advisor → перевірка кожного RSA
🔜 Інтеграція в CrewAI Content Team як крок після написання контенту

MVP (Мінімальний viable product)

python3 builder.py --product "Хеафолік" --type branded --budget 15000
# → output/хеафолік_2026-04-15_branded.csv

Результат: 1 кампанія, 2-3 групи оголошень, 10-20 ключових слів, 3 RSA.