first commit

knowledge/README.md

@@ -0,0 +1,246 @@
+# Lokalna baza wiedzy
+
+Ten katalog jest nowym magazynem wiedzy dla projektu `google ads ver 2`.
+
+## Struktura katalogu
+
+- `sources/` - surowe materialy do przetworzenia w kolejnych etapach.
+- `rules.jsonl` - atomowe reguly wykorzystywane przez narzedzie.
+- `imports.jsonl` - historia importow wiedzy.
+- `lancedb/` - metadane indeksu semantycznego; fizyczne pliki LanceDB sa domyslnie w `%LOCALAPPDATA%\google-ads-ver2-knowledge-lancedb`.
+
+`rules.jsonl` jest zrodlem prawdy. LanceDB jest tylko indeksem do wyszukiwania semantycznego i mozna go zawsze odbudowac z `rules.jsonl`.
+
+Przenoszenie projektu na inny komputer:
+
+- Przenosza sie: `knowledge/rules.jsonl`, `knowledge/sources/`, `knowledge/imports.jsonl` i dokumentacja.
+- Nie musi przenosic sie: fizyczny katalog LanceDB z `%LOCALAPPDATA%`.
+- Po przeniesieniu projektu uruchom:
+
+```powershell
+python -m pip install -r requirements.txt
+python gads.py wiedza indeksuj
+```
+
+To odbuduje lokalny indeks LanceDB na nowym komputerze.
+
+API modeli jest uzywane podczas:
+
+- `wiedza dodaj` - ekstrakcja regul z materialu zrodlowego.
+- `wiedza indeksuj` - utworzenie embeddingow aktywnych regul.
+- `wiedza szukaj-ai` - embedding zapytania uzytkownika.
+
+Analiza klienta Google Ads nie wywoluje API modeli.
+
+## Komendy
+
+Inicjalizacja katalogow i pustych plikow:
+
+```powershell
+python gads.py wiedza init
+```
+
+Test pliku bez kosztu API i bez zapisu regul:
+
+```powershell
+python gads.py wiedza dodaj --file "knowledge/sources/sample_lancedb_w055.md" --source "stara_lancedb_W055" --dry-run
+```
+
+Import przez API:
+
+```powershell
+python gads.py wiedza dodaj --file "knowledge/sources/sample_lancedb_w055.md" --source "stara_lancedb_W055"
+```
+
+Import calej starej bazy LanceDB bez API i bez przypisywania do zadan:
+
+```powershell
+python gads.py wiedza import-stare --from "D:\google ads\lancedb"
+```
+
+Ten import:
+
+- czyta tabele `fakty`,
+- przenosi kazdy rekord jako aktywna regule,
+- zostawia `task_ids` i `suggested_task_ids` puste,
+- pomija rekordy, ktore juz istnieja po `id`,
+- po imporcie wymaga odswiezenia indeksu przez `python gads.py wiedza indeksuj`.
+
+Po imporcie skrypt pokazuje propozycje przypisania regul do zadan i pyta o kazda z nich:
+
+```text
+Dodac regule <id_reguly> do zadania <task_id>?
+```
+
+Odpowiedzi:
+
+- `TAK` - dopisuje `task_id` do reguly.
+- `NIE` - odrzuca propozycje.
+- Enter - zostawia propozycje jako oczekujaca do pozniejszej decyzji.
+
+Lista oczekujacych propozycji:
+
+```powershell
+python gads.py wiedza propozycje
+```
+
+Wznawialny przeglad regul bez przypisan do zadan:
+
+```powershell
+python gads.py wiedza przypisz
+```
+
+Komenda przechodzi po aktywnych regulach, ktore maja puste `task_ids`, w kolejnosci zapisanej w `knowledge/rules.jsonl`. To celowe: uzytkownik moze latwo porownac przeglad z otwartym plikiem i z kolejnoscia importu. Skrypt pokazuje liste aktualnych zadan i pyta, do ktorego zadania dodac regule. Mozna wpisac:
+
+- numer zadania, np. `2`,
+- kilka numerow po przecinku, np. `2,4`,
+- techniczny `task_id`, np. `check_pla_settings`,
+- `P`, aby pominac regule i przejsc dalej,
+- `U`, aby trwale usunac regule z `knowledge/rules.jsonl`,
+- `Q`, aby przerwac bez przesuwania kursora.
+
+Domyslnie komenda pokazuje jedna regule, pyta o decyzje i konczy porcje. To jest preferowany tryb pracy, bo agent i uzytkownik moga ocenic pelny kontekst bez pospiechu. Wieksza porcje wlaczaj tylko swiadomie, np.:
+
+```powershell
+python gads.py wiedza przypisz --limit 10
+```
+
+Usuwanie przez `U` wymaga dodatkowego potwierdzenia tekstem `USUN`. Po potwierdzeniu rekord jest fizycznie usuwany z `rules.jsonl`, a postep przegladu jest zapisywany tak, zeby kolejne uruchomienie zaczelo od nastepnej reguly. Po usunieciach uruchom `python gads.py wiedza indeksuj`, zeby LanceDB nie zawierala starych rekordow. Tej opcji uzywaj dla ewidentnie blednych, pustych albo bezuzytecznych rekordow z importu. Jesli regula jest poprawna, ale nie ma byc uzywana teraz, lepiej wpisac `P` albo oznaczyc ja poza przegladem jako `archived`.
+
+Postep jest zapisywany w `knowledge/review_state.json`. Aby zaczac od poczatku:
+
+```powershell
+python gads.py wiedza przypisz --restart
+```
+
+Po dodaniu nowych zadan do `config/tasks.toml` uruchom ponownie `python gads.py wiedza przypisz --restart`, zeby przejrzec nieprzypisane reguly pod katem nowych zadan.
+
+Reczna akceptacja pojedynczej propozycji:
+
+```powershell
+python gads.py wiedza zatwierdz --rule-id "<id_reguly>" --task "<task_id>"
+```
+
+Reczne odrzucenie pojedynczej propozycji:
+
+```powershell
+python gads.py wiedza odrzuc --rule-id "<id_reguly>" --task "<task_id>"
+```
+
+Wyszukiwanie tekstowe po zapisanych regulach:
+
+```powershell
+python gads.py wiedza szukaj "pmax display remarketing"
+```
+
+Budowa indeksu semantycznego LanceDB:
+
+```powershell
+python gads.py wiedza indeksuj
+```
+
+Domyslnie fizyczny indeks LanceDB jest poza katalogiem projektu, bo na Windows katalogi synchronizowane potrafia blokowac operacje zapisu wymagane przez LanceDB. Sciezke mozna nadpisac zmienna:
+
+```text
+KNOWLEDGE_LANCEDB_DIR=C:\sciezka\do\lokalnego\lancedb
+```
+
+Wyszukiwanie semantyczne:
+
+```powershell
+python gads.py wiedza szukaj-ai "czy PMax kanibalizuje kampanie Display?"
+```
+
+Lista regul z filtrami:
+
+```powershell
+python gads.py wiedza lista
+python gads.py wiedza lista --topic shopping
+python gads.py wiedza lista --task check_pla_settings
+python gads.py wiedza lista --status archived
+python gads.py wiedza lista --source "stara_lancedb"
+```
+
+Statystyki bazy:
+
+```powershell
+python gads.py wiedza statystyki
+```
+
+Statusy 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>"
+```
+
+Lista regul przypisanych do zadania:
+
+```powershell
+python gads.py wiedza reguly --task check_pla_settings
+```
+
+## Konfiguracja API
+
+Do importu przez API potrzebny jest klucz w `.env`:
+
+```text
+OPENAI_API_KEY=...
+```
+
+Opcjonalnie mozna ustawic model:
+
+```text
+KNOWLEDGE_OPENAI_MODEL=gpt-4.1-mini
+KNOWLEDGE_EMBEDDING_MODEL=text-embedding-3-small
+KNOWLEDGE_LANCEDB_DIR=C:\opcjonalna\sciezka\poza\synchronizacja
+```
+
+Mozna tez podac model jednorazowo:
+
+```powershell
+python gads.py wiedza dodaj --file "knowledge/sources/sample_lancedb_w055.md" --source "stara_lancedb_W055" --model gpt-4.1-mini
+```
+
+## Schemat reguly
+
+Kazdy wiersz `rules.jsonl` jest osobnym obiektem JSON. Wymagane pola:
+
+- `id` - stabilny identyfikator reguly, bez spacji.
+- `status` - `active`, `draft`, `archived` albo `duplicate`.
+- `topic` - krotki temat, np. `search`, `pmax`, `shopping`, `konwersje`, `gtm-tracking`.
+- `task_ids` - lista zadan zaakceptowanych przez uzytkownika; importer nie powinien dopisywac ich bez akceptacji.
+- `suggested_task_ids` - propozycje zadan do akceptacji; skrypt pokazuje je uzytkownikowi po imporcie.
+- `rule_type` - `audit_check`, `recommendation`, `warning` albo `implementation_note`.
+- `condition` - kiedy regula ma znaczenie.
+- `recommendation` - co agent albo narzedzie powinno zrobic.
+- `risk` - jakie ryzyko ogranicza regula.
+- `source` - czytelna nazwa zrodla podana w `--source`.
+- `source_file` - plik zrodlowy, z ktorego powstala regula.
+- `confidence` - `low`, `medium` albo `high`.
+- `created_at` - data utworzenia reguly.
+- `updated_at` - data ostatniej zmiany metadanych, statusu lub przypisan.
+- `duplicate_of` - ID reguly nadrzednej, gdy `status` ma wartosc `duplicate`.
+- `supersedes` - lista ID regul zastapionych przez te regule.
+- `text` - jednozdaniowa wersja reguly do wyszukiwania i wyswietlania.
+
+Przykladowy rekord `rules.jsonl`:
+
+```json
+{"id":"search_partners_quality_check","status":"active","topic":"search","task_ids":[],"suggested_task_ids":["check_search_settings"],"rule_type":"audit_check","condition":"Kampania Search ma wlaczona siec partnerska Google","recommendation":"Sprawdz wyniki Search Partners osobno przed rekomendacja pozostawienia tej opcji.","risk":"Mozliwy ruch niskiej jakosci lub zawyzone konwersje.","source":"manual","source_file":"knowledge/sources/search.md","confidence":"medium","created_at":"2026-05-14T18:00:00","updated_at":"2026-05-14T18:00:00","duplicate_of":"","supersedes":[],"text":"Search Partners sprawdzaj osobno przy problemach z jakoscia ruchu."}
+```
+
+## Zasady dla agentow AI
+
+- Nie wpisuj recznie duzych pakietow regul do `rules.jsonl`, jesli material moze przejsc przez `wiedza dodaj`.
+- Przed importem wrzuc material do `knowledge/sources/` albo wskaz istniejacy plik.
+- Najpierw uruchom `--dry-run`, zeby sprawdzic sciezke, zrodlo i model bez kosztu API.
+- Po imporcie sprawdz wynik przez `python gads.py wiedza szukaj "<temat>"`.
+- Nie dopisuj `task_ids` recznie po imporcie. Uzyj pytan skryptu albo komendy `wiedza zatwierdz`.
+- Nie usuwaj historycznych regul recznie. Uzyj `wiedza archiwizuj` albo `wiedza duplikat`, zeby zachowac slady decyzji.
+- Po wiekszych zmianach w `rules.jsonl` uruchom `python gads.py wiedza indeksuj`, zeby odswiezyc LanceDB.
+- Nie edytuj plikow LanceDB recznie. To indeks, nie zrodlo prawdy.
+- Reguly w `rules.jsonl` maja wspierac plany i checklisty. Nie sa zgoda na wdrozenie zmian na koncie Google Ads.
+- Jesli regula dotyczy przyszlego zadania, zostaw `task_ids` i `suggested_task_ids` puste, a pozniej dopisz zadanie w `config/tasks.toml`.
+- Nie zapisuj kluczy API w tym katalogu. Klucze trzymamy w `.env`.

knowledge/imports.jsonl

@@ -0,0 +1,6 @@
+
+{"created_at": "2026-05-14T18:25:20", "file": "knowledge\\sources\\sample_lancedb_w055.md", "model": "gpt-4.1-mini", "notes": "Zasady dotyczą głównie remarketingu dynamicznego, strategii stawek przy starcie kampanii Search oraz hierarchii priorytetów typów kampanii Performance Max. Uwzględniono istniejace task_id do powiązania reguł z odpowiednimi funkcjonalnościami narzędzia.", "rules_count": 9, "source": "stara_lancedb_W055"}
+{"created_at": "2026-05-14T18:33:36", "file": "knowledge\\sources\\test_pla_settings_acceptance.md", "model": "gpt-4.1-mini", "notes": "Reguly odnosza sie do ustawien lokalizacji i priorytetu kampanii PLA oraz procesu przygotowania zmian z uwzglednieniem wyjatkow klienta.", "rules_count": 3, "source": "test_pla_settings_acceptance"}
+{"created_at": "2026-05-14T18:55:30", "file": "D:\\google ads\\lancedb\\fakty.lance", "model": "none", "notes": "Import starej tabeli LanceDB bez API i bez przypisywania regul do zadan.", "rules_count": 3, "skipped_existing_count": 0, "source": "legacy_lancedb:fakty"}
+{"created_at": "2026-05-14T18:56:39", "file": "D:\\google ads\\lancedb\\fakty.lance", "model": "none", "notes": "Import starej tabeli LanceDB bez API i bez przypisywania regul do zadan.", "rules_count": 1512, "skipped_existing_count": 277, "source": "legacy_lancedb:fakty"}
+{"created_at": "2026-05-14T18:57:32", "file": "D:\\google ads\\lancedb\\fakty.lance", "model": "none", "notes": "Import starej tabeli LanceDB bez API i bez przypisywania regul do zadan.", "rules_count": 274, "skipped_existing_count": 1515, "source": "legacy_lancedb:fakty"}

knowledge/lancedb/.gitkeep

@@ -0,0 +1 @@
+

knowledge/review_state.json

@@ -0,0 +1,11 @@
+{
+  "unassigned": {
+    "last_queue_index": 0,
+    "last_rule_id": "dynamic_remarketing_pixel_required",
+    "last_sort_key": [
+      "remarketing",
+      "dynamic_remarketing_pixel_required"
+    ],
+    "updated_at": "2026-05-14T19:11:27"
+  }
+}

knowledge/rules.jsonl

@@ -0,0 +1,3 @@
+{"condition":"Nowa kampania Search bez historii danych używa automatycznej strategii opartej o konwersje albo opiera się na słabych, zbyt ogólnych lub niewiarygodnych konwersjach.","confidence":"high","created_at":"2026-05-14T22:00:00","duplicate_of":"","id":"search_new_campaign_no_weak_conversion_automation","machine_condition":{"all":[{"field":"channel_type","op":"eq","value":"SEARCH"},{"field":"conversions_30d","op":"lt","value":15},{"field":"bidding_strategy_type","op":"in","value":["MAXIMIZE_CONVERSIONS","TARGET_CPA","MAXIMIZE_CONVERSION_VALUE","TARGET_ROAS"]}]},"machine_effect":{"action":"nie przechodź na automatyzację konwersyjną","level":"ostroznie","reason_prefix":"Reguła wiedzy"},"recommendation":"Nie startuj kampanii Search od automatyzacji opartej o konwersje, jeśli konto nie ma jakościowych danych. Najpierw ustaw konkretne cele konwersji, sprawdź pomiar i zbuduj sensowną strukturę słów kluczowych.","risk":"Algorytm może uczyć się na zbyt małej albo błędnej liczbie sygnałów, przez co kampania będzie źle wydawać budżet i zbierze dane niskiej jakości.","rule_type":"warning","source":"manual","source_file":"KNOWLAGE.md","status":"active","suggested_task_ids":[],"supersedes":[],"task_ids":["check_bidding_strategies"],"text":"Nowa kampania Search bez historii nie powinna startować od automatyzacji opartej o słabe konwersje. Najpierw zadbaj o konkretne cele, poprawny pomiar i sensowną strukturę słów kluczowych.","topic":"strategie_stawek","updated_at":"2026-05-14T22:00:00"}
+{"condition":"Kampania używa strategii opartej o Docelowy ROAS, ma wystarczająco danych do oceny, a rzeczywisty ROAS jest wyraźnie niższy od ustawionego celu.","confidence":"high","created_at":"2026-05-14T22:35:00","duplicate_of":"","id":"target_roas_too_high_can_limit_spend","machine_condition":{"all":[{"field":"target_assessment","op":"eq","value":"Docelowy ROAS prawdopodobnie za wysoki"},{"field":"conversions_30d","op":"gte","value":15},{"field":"bidding_strategy_type","op":"in","value":["TARGET_ROAS","MAXIMIZE_CONVERSION_VALUE"]}]},"machine_effect":{"action":"sprawdź, czy Docelowy ROAS nie blokuje wydatków","level":"do decyzji","reason":"Docelowy ROAS jest wyższy niż aktualna efektywność kampanii; w planie trzeba rozdzielić problem kampanii od zbyt restrykcyjnego celu.","reason_prefix":"Reguła wiedzy"},"recommendation":"W planie oznacz, że Docelowy ROAS może być zbyt restrykcyjny. Przed zmianą celu wskaż, czy problem wynika z jakości kampanii, oferty lub feedu, czy z samego celu ustawionego zbyt wysoko względem aktualnej efektywności.","risk":"Zbyt wysoki Docelowy ROAS może ograniczać wydatki, zmniejszać liczbę wyświetleń i blokować skalowanie kampanii, mimo że kampania mogłaby generować wartościowy ruch przy mniej restrykcyjnym celu.","rule_type":"warning","source":"manual","source_file":"KNOWLAGE.md","status":"active","suggested_task_ids":[],"supersedes":[],"task_ids":["check_bidding_strategies"],"text":"Docelowy ROAS zbyt wysoki względem aktualnej efektywności może blokować wydatki. W planie wskazuj, czy problemem jest kampania, czy zbyt restrykcyjny cel.","topic":"strategie_stawek","updated_at":"2026-05-14T22:35:00"}
+{"condition":"Plan zaklada zmiane budzetu albo celu Smart Bidding, szczegolnie gdy zmiana jest duza albo nastepuje krotko po innej zmianie budzetu, strategii lub celu.","confidence":"high","created_at":"2026-05-14T22:38:50","duplicate_of":"","id":"smart_bidding_sequential_budget_and_target_changes","machine_condition":{"all":[{"field":"bidding_strategy_type","op":"in","value":["MAXIMIZE_CONVERSIONS","TARGET_CPA","MAXIMIZE_CONVERSION_VALUE","TARGET_ROAS"]},{"field":"budget_context","op":"eq","value":"budzet zmieniony w ostatnich 7 dniach"}]},"machine_effect":{"action":"nie zmieniaj teraz celu ani strategii Smart Bidding","level":"czekaj","reason_prefix":"Regula wiedzy"},"recommendation":"Zmiany budzetow i celow Smart Bidding wprowadzaj sekwencyjnie. Nie zmieniaj jednoczesnie budzetu i Docelowego ROAS albo Docelowego CPA, jesli nie jest to swiadoma decyzja. Duze zmiany oznaczaj jako wyzsze ryzyko uczenia algorytmu i rekomenduj obserwacje wynikow przed kolejna zmiana.","risk":"Jednoczesne albo zbyt duze zmiany moga uruchomic niestabilny okres uczenia, utrudnic ocene przyczyny zmian wynikow i doprowadzic do nadmiernego wydawania budzetu albo utraty wolumenu konwersji.","rule_type":"warning","source":"manual","source_file":"KNOWLAGE.md","status":"active","suggested_task_ids":[],"supersedes":[],"task_ids":["check_budget_usage","check_bidding_strategies","optimize_shopping_troas_ag"],"text":"Zmiany budzetow i celow w Smart Bidding wprowadzaj sekwencyjnie. Duze zmiany oznaczaj jako wyzsze ryzyko uczenia algorytmu.","topic":"strategie_stawek","updated_at":"2026-05-14T22:49:00"}

knowledge/sources/.gitkeep

@@ -0,0 +1 @@
+

knowledge/sources/sample_lancedb_w055.md

@@ -0,0 +1,22 @@
+# Przykladowa wiedza ze starej LanceDB: W055
+
+Ten plik sluzy do testowania komendy:
+
+```powershell
+python gads.py wiedza dodaj --file "knowledge/sources/sample_lancedb_w055.md" --source "stara_lancedb_W055" --dry-run
+```
+
+Po dodaniu `OPENAI_API_KEY` do `.env` ten sam plik mozna zaimportowac bez `--dry-run`.
+
+## Remarketing dynamiczny: piksel Google Ads vs listy GA4
+
+Dynamiczny remarketing produktow w e-commerce wymaga piksela Google Ads albo rownowaznego tagowania, ktore przekazuje parametry e-commerce, szczegolnie identyfikatory produktow. Same listy GA4 nie wystarcza do wyswietlania konkretnych produktow ogladanych przez uzytkownika. Remarketing ogolny, zwlaszcza dla uslug i bez dopasowania konkretnych produktow, mozna budowac na listach GA4. Oba podejscia moga dzialac rownolegle: tag Google Ads do remarketingu dynamicznego z produktami, listy GA4 do remarketingu ogolnego i zaawansowanej segmentacji.
+
+## Start kampanii Search: strategia stawek i konwersje
+
+Przy starcie nowej kampanii Search bez historii nie nalezy bezrefleksyjnie uzywac Maksymalizacji konwersji, bo algorytm nie wie jeszcze, pod jakie zachowania optymalizowac. Page view nie powinien byc konwersja podstawowa, bo kazda wizyta staje sie wtedy konwersja i algorytm uczy sie na zlych danych. Konwersja powinna byc konkretna akcja, np. sprzedaz, formularz albo umowienie kontaktu. Zasieg slow kluczowych trzeba sprawdzac w Planerze slow kluczowych, a nie tylko w Google Trends, bo Trends pokazuje trend bez realnego wolumenu.
+
+## Hierarchia priorytetow: PMax vs inne typy kampanii
+
+Performance Max ma wyzszy priorytet niz Display, Discovery i standardowe kampanie produktowe. Moze przejmowac ruch, ktory normalnie trafilby do tych kampanii. Performance Max ma nizszy priorytet niz kampanie Search, wiec reklamy tekstowe nadal moga obslugiwac zapytania przed PMax. Przy jednoczesnym dzialaniu PMax i Display remarketing dynamiczny kampania Display moze byc duplikatem lub byc kanibalizowana przez PMax.
+

knowledge/sources/test_pla_settings_acceptance.md

@@ -0,0 +1,10 @@
+# Test importu wiedzy: ustawienia kampanii PLA
+
+Ten plik sluzy do testu przeplywu akceptacji przypisania reguly do zadania `check_pla_settings`.
+
+## Regula: lokalizacja i priorytet kampanii PLA
+
+Kampanie produktowe PLA powinny byc sprawdzane pod katem ustawien lokalizacji i priorytetu. Jezeli globalna regula klienta wymaga obecnosci uzytkownika w lokalizacji docelowej, kampania powinna miec ustawienie targetowania lokalizacji typu presence only, a nie presence or interest. Jezeli globalna regula wymaga wysokiego priorytetu kampanii PLA, kampania powinna miec wysoki priorytet, chyba ze klient ma jawny wyjatek w `config/clients.toml`.
+
+Przed wdrozeniem zmian skrypt powinien przygotowac plan, pokazac ktore kampanie wymagaja zmiany, uwzglednic wyjatki klienta i nie wdrazac nic bez akceptacji uzytkownika.
+