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:

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:

python gads.py wiedza init

Test pliku bez kosztu API i bez zapisu regul:

python gads.py wiedza dodaj --file "knowledge/sources/sample_lancedb_w055.md" --source "stara_lancedb_W055" --dry-run

Import przez API:

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:

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:

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:

python gads.py wiedza propozycje

Wznawialny przeglad regul bez przypisan do zadan:

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

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:

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:

python gads.py wiedza zatwierdz --rule-id "<id_reguly>" --task "<task_id>"

Reczne odrzucenie pojedynczej propozycji:

python gads.py wiedza odrzuc --rule-id "<id_reguly>" --task "<task_id>"

Wyszukiwanie tekstowe po zapisanych regulach:

python gads.py wiedza szukaj "pmax display remarketing"

Budowa indeksu semantycznego LanceDB:

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:

KNOWLEDGE_LANCEDB_DIR=C:\sciezka\do\lokalnego\lancedb

Wyszukiwanie semantyczne:

python gads.py wiedza szukaj-ai "czy PMax kanibalizuje kampanie Display?"

Lista regul z filtrami:

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:

python gads.py wiedza statystyki

Statusy 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>"

Lista regul przypisanych do zadania:

python gads.py wiedza reguly --task check_pla_settings

Konfiguracja API

Do importu przez API potrzebny jest klucz w .env:

OPENAI_API_KEY=...

Opcjonalnie mozna ustawic model:

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:

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:

{"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.