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