google-ads-ver-2/README.md

Google Ads ver 2

Terminalowe narzedzie do pracy na kontach Google Ads klientow.

Instrukcja pracy dla Claude Code, Codex, Gemini CLI i innych agentow AI jest w AGENTS.md. Instrukcja rozbudowy o nowe grupy i zadania jest w DEVELOPMENT.md. Backlog rzeczy sprawdzanych w starej wersji jest w OLD_COMMANDS_CHECKLIST.md.

Start

1. Uzupelnij .env na podstawie .env.example.
2. Uzupelnij config/clients.toml na podstawie config/clients.example.toml.
3. Zainstaluj zaleznosci:

python -m pip install -r requirements.txt

4. Uruchom menu:

python gads.py

Albo uruchom konkretne zadanie bez menu:

python gads.py --client laitica.pl --task sync_pla_cl1

Tryb dla Claude Code, Codex albo Gemini CLI:

python gads.py analiza-klienta
python gads.py analiza-klienta --client-number 5
python gads.py analiza-klienta --client-number 5 --task-number 1 --plan-only

Po tej komendzie narzedzie zapisze plan w clients/<domena>/plans/. Agent czyta plik .md albo .json, analizuje go i pyta Cie o zgode. Po Twojej akceptacji agent uruchamia wdrozenie konkretnego planu:

python gads.py --client laitica.pl --task sync_pla_cl1 --apply-plan clients/laitica.pl/plans/PLAN.json --confirm-apply TAK

Raport klienta

Miesieczny raport HTML generuje komenda:

python gads.py raport-klienta
python gads.py raport-klienta --client-number 1 --month 2026-04
python gads.py raport-klienta aruba.rzeszow.pl 04.2026
python gads.py analiza-klienta aruba.rzeszow.pl 02-2026

Komenda pobiera dane Google Ads, opcjonalnie GA4, e-commerce, Semstorm i linki SEO, a potem zatrzymuje sie przed generowaniem HTML. Tworzy plik roboczy z kontekstem liczbowym i miejscem na wnioski przygotowane przez agenta AI:

scripts/reports/output/<domena>_<YYYY-MM>_recommendations.json

Skrypt nie generuje wnioskow samodzielnie. Agent AI uzupelnia recommendations w tym pliku z perspektywy osoby obslugujacej konto Google Ads klienta: decyzyjnie opisuje, co robimy, co kontrolujemy i jaki jest nastepny krok po naszej stronie. Nie pisze klientowi, ze warto cos sprawdzic albo nalezy przeanalizowac, bo to agent/operator konta podejmuje decyzje. Tytuly, wnioski i rekomendacje widoczne dla klienta musza miec poprawne polskie znaki. Po pokazaniu propozycji i akceptacji uzytkownika agent uruchamia:

python gads.py raport-klienta --client aruba.rzeszow.pl --month 2026-04 --confirm-recommendations TAK

Po zatwierdzeniu wnioskow raport HTML jest zapisywany w:

scripts/reports/output/<domena>/<YYYY-MM>/index.html

Historia sprzedaży miesięcznej oraz trzy kafelki w sekcji E-commerce — Sprzedaż mogą być zasilane z Google Sheet przypisanego do klienta:

[clients."example.pl"]
sales_history_sheet = "https://docs.google.com/spreadsheets/d/<id>"

Arkusz powinien mieć kolumny: Miesiąc, Transakcje, Przychody, Średnia wartość koszyka.

Upload na serwer nie wykonuje sie automatycznie. Po sprawdzeniu lokalnego raportu uruchom:

python gads.py raport-klienta --client aruba.rzeszow.pl --month 2026-04 --confirm-upload TAK

Wymagane dane FTP w .env: ADSPRO_HOST, ADSPRO_USERNAME, ADSPRO_PASSWORD, ADSPRO_REMOTE_PATH.

MVP

Pierwsze zadanie:

• pobiera kampanie [PLA_CL1] z Google Ads,
• wyciaga segmenty CL1 z nazw kampanii,
• pobiera produkty z adsPRO,
• przygotowuje plan synchronizacji grup reklam,
• czeka na akceptacje przed wdrozeniem zmian,
• zapisuje historie w katalogu klienta.

Dane i historia

• config/clients.toml - lista klientow i identyfikatory kont.
• config/clients.toml - takze reguly globalne i wyjatki per klient, np. ustawienia kampanii PLA.
• config/clients.toml - takze pominiecia zadan przy wyborze ALL, np. skip_in_all w sekcji klienta.
• .env - dane dostepowe do Google Ads i adsPRO.
• clients/<domena>/data/ - pobrane dane robocze.
• clients/<domena>/history/YYYY-MM-DD.jsonl - historia do filtrowania po kliencie, dacie i kampanii.
• clients/<domena>/changes/YYYY-MM-DD.md - czytelny dziennik zmian.

Lokalna baza wiedzy

Baza wiedzy ma lokalny magazyn regul i opcjonalny importer przez API. API modeli jest uzywane tylko przy dodawaniu nowej wiedzy, nie podczas analizy klienta.

python gads.py wiedza init
python gads.py wiedza dodaj --file "knowledge/sources/sample_lancedb_w055.md" --source "stara_lancedb_W055" --dry-run
python gads.py wiedza dodaj --file "knowledge/sources/sample_lancedb_w055.md" --source "stara_lancedb_W055"
python gads.py wiedza propozycje
python gads.py wiedza zatwierdz --rule-id "<id_reguly>" --task "<task_id>"
python gads.py wiedza szukaj "pmax shopping"
python gads.py wiedza reguly --task check_pla_settings
python gads.py wiedza lista --topic shopping
python gads.py wiedza statystyki
python gads.py wiedza indeksuj
python gads.py wiedza szukaj-ai "czy PMax kanibalizuje Display?"
python gads.py wiedza import-stare --from "D:\google ads\lancedb"
python gads.py wiedza przypisz

Pliki bazy wiedzy:

• knowledge/sources/ - materialy zrodlowe do pozniejszego importu.
• knowledge/rules.jsonl - atomowe reguly dla narzedzia.
• knowledge/imports.jsonl - historia importow.
• knowledge/lancedb/ - metadane indeksu semantycznego. Fizyczny indeks LanceDB jest domyslnie w %LOCALAPPDATA%\google-ads-ver2-knowledge-lancedb, zeby uniknac problemow zapisu w katalogach synchronizowanych.

Na innym komputerze przenosi sie rules.jsonl, a indeks LanceDB odbudowuje sie lokalnie:

python gads.py wiedza indeksuj

Stara baza LanceDB moze byc przeniesiona jednorazowo bez przypisywania do zadan:

python gads.py wiedza import-stare --from "D:\google ads\lancedb"

Pozniejsze przypisywanie nieprzypisanych regul do aktualnych zadan:

python gads.py wiedza przypisz
python gads.py wiedza przypisz --restart

wiedza przypisz domyslnie pokazuje jedna regule, pelny kontekst decyzji i konczy porcje po odpowiedzi. Reguly ida w kolejnosci zapisanej w knowledge/rules.jsonl, zeby latwo bylo porownac ekran z otwartym plikiem. W przegladzie mozna wpisac numer zadania albo task_id, P zeby pominac, Q zeby przerwac, oraz U zeby usunac biezaca regule z knowledge/rules.jsonl. Usuniecie wymaga dodatkowego potwierdzenia USUN; po usunieciach odswiez indeks przez python gads.py wiedza indeksuj.

Reczne dodawanie pojedynczej reguly przez agenta AI:

Przypisz regule:
- tresc reguly do oceny

Agent najpierw sprawdza aktualne zadania w config/tasks.toml, ocenia czy regule warto dodac, proponuje docelowe brzmienie, typ, temat, ryzyko, rekomendacje i zadanie docelowe. Przy kazdej regule agent musi tez zaproponowac policzalny machine_condition i machine_effect, jezeli regule da sie bezpiecznie zastosowac w skrypcie. Jesli regula wymaga oceny eksperckiej albo danych, ktorych zadanie nie pobiera, agent ma jasno napisac, ze nie proponuje automatycznego warunku i regule nalezy traktowac jako kontekst dla agenta AI/czlowieka. Agent nie zapisuje nic do knowledge/rules.jsonl, dopoki uzytkownik jasno nie odpowie Dodaj. Po akceptacji agent dopisuje jedna kompletna linie JSONL do knowledge/rules.jsonl, uzywajac tylko istniejacych task_id. Jesli nie ma dobrego zadania, agent powinien zaproponowac niedodawanie reguly albo odlozenie jej do czasu dodania nowego zadania.

machine_condition opisuje twarde warunki na polach dostepnych w planie zadania, np. channel_type, conversions_30d, bidding_strategy_type. machine_effect opisuje wplyw na rekomendacje, np. poziom ostroznosci, akcje i powod. Skrypt moze automatycznie stosowac tylko takie reguly, ktore maja policzalny warunek oparty o dostepne dane.

Wieksza porcje przegladu uruchamiaj jawnie:

python gads.py wiedza przypisz --limit 10

Po imporcie skrypt pokazuje proponowane powiazania regul z zadaniami i pyta, czy dopisac je do task_ids. Bez odpowiedzi TAK propozycja zostaje oczekujaca albo odrzucona, ale nie staje sie regula zadania.

Przy wiekszej bazie uzywaj statusow zamiast recznego kasowania regul:

python gads.py wiedza archiwizuj --rule-id "<id_reguly>"
python gads.py wiedza aktywuj --rule-id "<id_reguly>"
python gads.py wiedza duplikat --rule-id "<id_reguly>" --duplicate-of "<id_reguly_nadrzednej>"

Do importu przez API dodaj do .env:

OPENAI_API_KEY=...
KNOWLEDGE_OPENAI_MODEL=gpt-4.1-mini
KNOWLEDGE_EMBEDDING_MODEL=text-embedding-3-small
KNOWLEDGE_LANCEDB_DIR=C:\opcjonalna\sciezka\poza\synchronizacja

Narzedzie nie uzywa API modeli AI podczas analizy klienta. Claude Code, Codex albo Gemini CLI moga uruchamiac te same komendy terminalowe.