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