# 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:

```powershell
python -m pip install -r requirements.txt
```

4. Uruchom menu:

```powershell
python gads.py
```

Albo uruchom konkretne zadanie bez menu:

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

Tryb dla Claude Code, Codex albo Gemini CLI:

```powershell
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:

```powershell
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:

```powershell
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:

```text
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:

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

Po zatwierdzeniu wnioskow raport HTML jest zapisywany w:

```text
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:

```toml
[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:

```powershell
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.

```powershell
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:

```powershell
python gads.py wiedza indeksuj
```

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

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

Pozniejsze przypisywanie nieprzypisanych regul do aktualnych zadan:

```powershell
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:

```text
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:

```powershell
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:

```powershell
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`:

```text
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.
