Grupy Odbiorców AI

Media buyer wkleja link do briefu kampanii. AI czyta copy i grafiki, przeczesuje taksonomię Meta i oddaje gotowe grupy targetowania z szacunkiem zasięgu.

---

Spis treści

• O projekcie
• Screenshoty
• Kod źródłowy
• Stack
• Funkcje
• Architektura
• Statystyki
• Kontakt

---

O projekcie

Przy każdej nowej kampanii media buyer składa grupy targetowania ręcznie. Taksonomia Meta to tysiące zainteresowań, zachowań i wydarzeń życiowych. Praca na czuja kończy się generycznymi grupami, fillerami (urodziny, marki telefonów) i brakiem skali.

Tutaj media buyer wkleja link do Google Doc z tekstami reklam, opcjonalnie grafiki i kontekst. Pipeline robi resztę: Gemini rozumie brief (copy plus kreacje jako PDF), Meta API buduje twardą pulę zweryfikowanych kandydatów, a drugie wywołanie Gemini dobiera grupy wyłącznie z identyfikatorów z puli. Model nie wymyśla zainteresowań. Wynik: 1-10 nazwanych grup z targetingiem, szacunkiem zasięgu per grupa i uzasadnieniem.

System działa na produkcji od czerwca 2026, używany przez media buyerów agencji przy nowych kampaniach. Wykrywa briefe B2B i dokłada targetowanie po pracodawcach i stanowiskach. Ranking kandydatów idzie wyłącznie z briefu, a testy pilnują, żeby wielkie generyki nie wygrywały z trafnością do niszy.

---

Screenshoty

Formularz briefu	Wyniki: brief i karty grup

Karta grupy	Wyniki w trybie ciemnym

Nota: screenshoty pokazują fikcyjną kampanię (palarnia kawy specialty) na lokalnym stubie API. Żadne dane klientów nie są użyte.

---

Kod źródłowy

Kod jest prywatny i poufny (system wewnętrzny agencji). To repo dokumentuje projekt: opis, architekturę i zrzuty działania.

---

Stack

Backend (Python 3.11)

FastAPI 0.115 + uvicorn       // 3 endpointy, Basic Auth, fail-closed
google-genai                  // Gemini 2.5 Flash, fallback Flash-Lite
Meta Graph API v25            // targetingsearch, suggestions, validation, reachestimate
pypdf                         // bramka obrazów w PDF (min. 200 px)

Frontend

React 19 + Vite 6 + TS        // formularz briefu, karty grup, dark mode
lucide-react + Geist          // ikony i typografia

Operacje

Docker Compose na VPS         // jeden serwis API, healthcheck /api/health
Netlify                       // hosting frontu, deploy z GitHub Actions
pull-deploy.sh                // git pull + compose up na serwerze

---

Funkcje

Pipeline briefu

• Ingest Google Doc - export TXT, detekcja login walla, limity 15 MB i 30 s
• Grafiki jako PDF - osobny Doc albo obrazy osadzone w tekstach (bramka: oba boki min. 200 px), priorytet nad Canvą; Canva trafia do promptu jako notka, bez wizji
• Gemini understand_campaign - summary, keywords PL/EN, tematy, flaga B2B; prompt każe ignorować formułki agencji i zrzuty UI, targetować rozwiązanie, nie problem

Twarda pula Meta

• Cztery źródła kandydatów - targetingbrowse (taksonomia), targetingsearch, targetingsuggestions, a przy B2B także pracodawcy i stanowiska
• Tylko zweryfikowane ID - filtr min. 1000 zasięgu plus targetingvalidation; Gemini dostaje wyłącznie realne opcje z puli
• Cache taksonomii - 370 pozycji w 5 kategoriach, TTL 14 dni; batch do 50 zapytań, retry przy rate-limit

Dobór grup

• Structured output - Gemini build_groups ze schematem Pydantic, temperatura 0.3, fallback na Flash-Lite
• Sanitize - tylko ID z puli, drop fillerów, backfill interests wg trafności, max 5 opcji i max 1 non-interest na grupę
• Ranking z briefu - zero hardkodowanych nisz; test pilnuje, żeby generyki nie wygrywały z trafnością
• Filtr fillerów - miesiące urodzin i zachowania infrastrukturalne (WiFi, marki telefonów) wylatują, chyba że brief sygnalizuje mobile
• Advantage+ - co najmniej jedna grupa z flagą advantage audience

Wynik

• Targeting spec - geo PL, wiek 25-55, flexible_spec OR; gotowy JSON pod kampanię
• Szacunek zasięgu per grupa - osobny call reachestimate, ostrzeżenie poniżej 300 tys.
• Nazewnictwo - AS_[etap lejka][kąt][typ grupy]PL[cel]

UI

• Formularz briefu - link do tekstów, chip rodzaju grafik (gdoc/canva), kontekst, liczba grup 1-10
• Karty grup - targeting, szacowany zasięg, rationale, badge Advantage+, nota o overlapie
• Modal algorytmu - 4 kroki doboru grup, wersje jasna i ciemna, status API online/offline
• Dostęp - wspólne konto zespołu (Basic Auth), noindex, front poza wyszukiwarkami

---

Architektura

graph TB
    subgraph input [Wejście]
        Doc[Google Doc: copy]
        Gfx[Grafiki: Doc PDF / Canva]
        Ctx[Kontekst]
    end
    subgraph api [FastAPI]
        Ingest[Ingest + detekcja login walla]
        Understand[Gemini: understand_campaign]
        Pool[Pula kandydatów Meta]
        Build[Gemini: build_groups]
        San[Sanitize + targeting spec]
        Reach[Reach estimate per grupa]
    end
    subgraph meta [Meta Graph API v25]
        Tax[Taxonomy browse]
        Search[targetingsearch + suggestions]
        Val[validation + reachestimate]
    end
    UI[React 19]
    Doc --> Ingest
    Gfx --> Ingest
    Ctx --> Ingest
    Ingest --> Understand
    Understand --> Pool
    Tax --> Pool
    Search --> Pool
    Pool --> Val
    Val --> Build
    Build --> San
    San --> Reach
    Reach --> UI

Loading

---

Statystyki

Złożoność techniczna

Metryka	Wartość
Commity	20 (2026-06 - 2026-07)
Autorzy	1
Linie kodu	2924 (1881 Python + 1043 React/TS)
Endpointy HTTP	3
Wywołania Gemini per request	2 (brief + dobór grup)
Modele Gemini	2 (Flash + fallback Flash-Lite)
Usługi	API (Docker na VPS) + front (Netlify)
Cache taksonomii	370 pozycji w 5 kategoriach, TTL 14 dni

Przegląd funkcji

Kategoria	Najważniejsze
Pipeline briefu	ingest GDoc, grafiki PDF, detekcja login walla
Pula Meta	4 źródła kandydatów, walidacja, cache 14 dni
Dobór grup	structured output, sanitize, filtr fillerów, Advantage+
Wynik	targeting PL 25-55, zasięg per grupa, rationale
UI	karty grup, dark mode, modal algorytmu
Operacje	Docker, healthcheck, deploy z GitHub Actions

---

Kontakt

Platforma	Link
WWW	kamilkaczmareksolutions.com
GitHub	kamilkaczmareksolutions
LinkedIn	Kamil Kaczmarek
Email	recruitment@kamilkaczmareksolutions.com

---

Grupy Odbiorców AI - targeting z briefu, nie z pamięci.

Zbudował Kamil Kaczmarek