Przejdź do treści

03 — Agents Specification

Insurance Intelligence System


Zasady ogólne agentów

  • Każdy agent ma jedną odpowiedzialność (Single Responsibility Principle)
  • Agenci komunikują się przez bazę danych — nie bezpośrednio między sobą
  • Każdy agent loguje swoją pracę — co zebrał, co przetworzymy, ile kosztowało
  • Agenci są idempotentni — uruchomienie dwa razy nie duplikuje danych
  • Kod każdego agenta mieszka w osobnym folderze na VPS
  • Zasada wydzielania: każda nowa funkcjonalność jest weryfikowana pod kątem czy nie powinna być osobnym agentem. Kryterium: czy zadanie ma inny trigger, inne zasoby i inną odpowiedzialność niż istniejący agent → jeśli tak, wydzielić.

Orkiestracja — n8n

Wszystkie agenty są orkiestrowane przez n8n działające na VPS (Docker, port 5678, za nginx/Traefik).

n8n zapewnia: - Harmonogramy (cron) dla każdego agenta niezależnie - Wyzwalacze zdarzeniowe (nowy plik w source_documents → uruchom Extractor) - Retry przy awarii (3 próby z backoffem) - Powiadomienia o błędach (email/webhook) - Widoczność pipeline'u — wizualny widok co i kiedy się wykonało - Logowanie czasu wykonania i statusu każdego kroku

Lokalizacja: /opt/n8n/ — Docker Compose, dane w wolumenie URL: https://n8n.intelligence.srv1298625.hstgr.cloud (Traefik HTTPS)

Główne workflow n8n

[Cron 06:00 UTC] → Agent 1 Collector (HTTP POST /collect)
                          │ po zakończeniu (webhook)
                          ▼
                   Agent 2 Extractor (HTTP POST /extract)
                          │ po zakończeniu (webhook)
                          ▼
                   Agent 3 Classifier (HTTP POST /classify)
                          │ po zakończeniu (webhook)
                          ▼
              [Cron poniedziałek 07:00 UTC]
                          │
                          ▼
                   Agent 4 Analyst (HTTP POST /analyze)
                          │ po zakończeniu (webhook)
                          ▼
                   Agent 5 Reporter (odświeżenie dashboardu)

Każdy agent zgłasza zakończenie przez webhook do n8n — n8n decyduje o uruchomieniu kolejnego.


Pipeline danych — przepływ między agentami

Źródła zewnętrzne (YouTube, KNF, PIU, NBP, portale, podcasty)
          │
          ▼ Agent 1 — Collector
    raw_signals          — metadane, tytuły, linki, checksum
    source_documents     — surowe pliki (BYTEA): XLSX, PDF, MP3
    transcriptions       — tekst z YouTube i Whisper
          │
          ▼ Agent 2 — Extractor
    extracted_signals    — znormalizowany tekst + metryki ze wszystkich formatów
    w1_market_position   — metryki finansowe (GWP, udziały rynkowe)
    w2_financials        — wskaźniki rentowności (COR, loss ratio)
    ...w3-w7             — pozostałe warstwy analityczne
          │
          ▼ Agent 3 — Classifier
    classified_signals   — segment, relevance_score, is_noise, TU, tematy
          │
          ▼ Agent 4 — Analyst
    insights             — trendy, anomalie, ruchy konkurencji, regulatory_change
          │
          ▼ Agent 5 — Reporter
    reports              — HTML dashboard + PDF raporty

Agent 1 — Collector

Odpowiedzialność: Zbieranie surowych danych ze wszystkich źródeł zewnętrznych. Collector nie przetwarza treści — tylko pobiera i zapisuje.

Lokalizacja: /opt/youtube-mcp/ (aktywny), /opt/regulatory-mcp/ (aktywny), kolejne źródła w /opt/[source]-mcp/

Uruchomienie: n8n cron, codziennie o 06:00 UTC

Źródła (Agent 1a/regulatory-mcp — MCP servery, kolejność wdrożenia): 1. ✅ YouTube Data API v3 — wywiady, konferencje, podcasty (Agent 1a, youtube-mcp, port 8000) 2. ✅ KNF (knf.gov.pl) — komunikaty, raporty kwartalne, knf_backfill_all (regulatory-mcp, port 8001) 3. ✅ Relacje inwestorskie TU (PZU, Ergo Hestia, VIG, Generali, Allianz, UNIQA) — tu_ir_discover/tu_ir_download (regulatory-mcp) 4. 🔲 NBP (nbp.pl) — raporty o stabilności finansowej — nie zaimplementowane

Ważne — dedup 2026-09-22: PIU, RSS podcastów i portale branżowe (gu.com.pl itd.) są obsługiwane przez Agent 1b Web Scout (osobna sekcja niżej), nie przez regulatory-mcp. KNF i relacje inwestorskie TU były wcześniej zduplikowane — te same strony miały wpisy jednocześnie w sources.yaml (Web Scout, generyczny scraper linków) i w regulatory-mcp (dedykowane narzędzia ze znajomością articleId). Usunięto duplikację z sources.yaml — KNF i IR zostają wyłącznie w regulatory-mcp, które jest bardziej wyspecjalizowane (ma knf_backfill_all gotowe do backfillu 5 lat wstecz, patrz 05_DEPLOYMENT_AND_ROADMAP.md).

Szczegółowe zadania:

DLA KAŻDEGO ŹRÓDŁA:
1. Pobierz listę aktywnych fraz / URL-i z tabeli query_config
2. Wywołaj API lub scraper źródła
3. Dla każdego wyniku → oblicz checksum(source_id)
4. Jeśli checksum nie istnieje w raw_signals → INSERT do raw_signals
5. Jeśli wynik zawiera plik (PDF/XLSX) → pobierz i zapisz do source_documents (BYTEA)
6. Jeśli wynik zawiera transkrypcję (YouTube) → zapisz do transcriptions
7. Wyciągnij URL-e z opisów → zapisz do raw_signals.description_urls
8. Jeśli istnieje → pomiń (deduplikacja przez checksum)
9. Wyślij webhook do n8n: {status: done, new_records: N, files: M}
10. Zapisz log operacji

Deduplikacja: SHA256 z source_id — zapobiega podwójnemu pobraniu tego samego zasobu.

Backfill historyczny — zaktualizowane 2026-09-22

KNF (5 lat wstecz, top 10 TU): ~~nie budujemy tego w Web Scout~~ — regulatory-mcp ma już gotowe narzędzie knf_backfill_all ze znajomością konkretnych articleId KNF (2021-2026). To jest właściwe narzędzie do uruchomienia, nie generyczny mechanizm w web_scout.py (który by duplikował funkcjonalność). Relacje inwestorskie TU analogicznie przez tu_ir_discover/tu_ir_download w regulatory-mcp.

RSS/global_reports/discovery (Web Scout): backfill dla tych źródeł to niższy priorytet — RSS feedy zwykle udostępniają tylko 20-50 najnowszych wpisów (płytka historia z natury), więc głęboki backfill wymagałby crawlowania archiwum/sitemap każdej strony indywidualnie. Nie zaimplementowane — do rozważenia tylko jeśli konkretna potrzeba się pojawi (np. analiza trendu historycznego z konkretnego portalu).

Limity API: - YouTube Data API v3: 10 000 jednostek/dzień (search = 100 jedn.) — przy 38 frazach × 100 = 3800 jedn./dzień - KNF: scraping HTML bez limitu, z opóźnieniem 2s między żądaniami

Output: - Tabela raw_signals — metadane wszystkich zebranych pozycji - Tabela source_documents — pliki binarne (XLSX, PDF, MP3) - Tabela transcriptions — tekst z YouTube i Whisper


Agent 2 — Extractor

Odpowiedzialność: Konwersja surowych danych z każdego formatu na ustrukturyzowany tekst i metryki. Extractor nie ocenia wartości danych — tylko normalizuje format i wyciąga liczby/sygnały.

Lokalizacja: /opt/insurance-extractor/

Uruchomienie: n8n webhook po zakończeniu Collectora (event-driven, nie cron)

Obsługiwane formaty:

Format Źródło Narzędzie parsowania Output
XLSX KNF, PIU, NBP pandas metryki liczbowe → w1-w7
PDF Raporty roczne TU, KNF pdfplumber tekst → extracted_signals
HTML / artykuł Portale branżowe BeautifulSoup tekst → extracted_signals
Transkrypcja YT tabela transcriptions bezpośrednio tekst sygnały → extracted_signals
Transkrypcja audio Whisper output bezpośrednio tekst sygnały → extracted_signals
RSS / metadane Podcasty XML parser tekst → extracted_signals

Szczegółowe zadania:

DLA KAŻDEGO NOWEGO REKORDU W source_documents / transcriptions:
1. Sprawdź extraction_status = 'pending'
2. Rozpoznaj typ dokumentu (xlsx / pdf / html / transcript / rss)
3. Uruchom odpowiedni normalizer:
   - XLSX → pandas → tabela z kolumnami i wartościami
   - PDF → pdfplumber → czysty tekst + tabele
   - HTML → BeautifulSoup → czysty tekst (bez tagów, reklam, nawigacji)
   - Transkrypcja → tekst już gotowy, chunking na segmenty 2000 znaków
4. Dobierz prompt ekstrakcji do typu dokumentu (Prompt Router)
5. Wyślij do Claude API z wymuszonym JSON output
6. Zapisz wynik:
   - Metryki liczbowe → tabele w1-w7 (dla XLSX/PDF finansowych)
   - Sygnały tekstowe → tabela extracted_signals
7. Zaktualizuj extraction_status = 'done' lub 'failed'
8. Wyślij webhook do n8n: {status: done, extracted: N, failed: M}

Prompt Router — typy promptów:

Każdy prompt kończy się instrukcją: "Odpowiedz zawsze po polsku, niezależnie od języka dokumentu źródłowego."

xlsx_knf_financial  → "Wyciągnij metryki finansowe TU w JSON:
                        {insurer_name, metric_name, value, unit,
                         period_quarter, period_year, confidence}"

pdf_annual_report   → "Wyciągnij z raportu rocznego: wyniki finansowe,
                        strategię, kluczowe decyzje zarządu w JSON"

html_article        → "Wyciągnij sygnały: które TU wymienione, jaka rola,
                        jaki temat, jaki sentiment, parafraza kluczowej treści"

transcript_youtube  → "Wyciągnij ze stenogramu: kluczowe stanowiska,
                        strategiczne deklaracje, metryki wymienione przez mówcę.
                        Zawsze parafraza — nie cytaty 1:1"

Zasada prawna: Każdy tekst zapisany do extracted_signals musi być parafrazą (własnymi słowami Claude), nigdy cytatem 1:1 z oryginału. Ochrona prawna + standard rynkowy (Wisers, Lexalytics).

Zasada językowa: Parafraza w extracted_signals jest zawsze w języku polskim, niezależnie od języka źródła (PL/EN dziś, docelowo też DE/FR/ES). Ustalone 2026-09-22 — zapewnia spójny dashboard w jednym języku i prostsze wyszukiwanie semantyczne (jeden język embeddingów zamiast mieszanki kilku). Link do oryginalnego dokumentu (source_documents.url) jest zawsze zachowany, więc konsultant może zweryfikować precyzyjną terminologię źródłową w razie wątpliwości.

Output: - Tabela extracted_signals — znormalizowane sygnały tekstowe gotowe do klasyfikacji - Tabele w1–w7 — metryki liczbowe z dokumentów finansowych - Status ekstrakcji zaktualizowany w source_documents


Stan faktyczny: Agent 2+3 połączone (zaimplementowane 2026-09-22)

Dla treści narracyjnych (HTML/PDF — artykuły, raporty) Agent 2 i Agent 3 są zaimplementowane jako jeden skrypt (extractor/extraction_agent.py), nie dwa osobne wywołania Claude. Powód: Extractor i Classifier i tak wymagają "zrozumienia" tej samej treści — wołanie Claude dwa razy na tym samym dokumencie (raz żeby wyciągnąć sygnały, raz żeby ocenić wartość) to podwójny koszt za tę samą pracę. Jedno wywołanie zwraca JSON obejmujący oba aspekty, a kod dzieli wynik do dwóch tabel (extracted_signals — treść/encje, classified_signals — ocena/segment), zachowując rozdzielenie odpowiedzialności w bazie.

Wywołanie Claude — nie płatne API, tylko licencja Accenture: Zamiast klucza Anthropic API (co tworzyłoby nowe, osobno rozliczane centrum kosztowe — dokładnie to, czego unikamy zgodnie z zasadą nadrzędną projektu), Extractor+Classifier woła Claude Code CLI w trybie headless:

subprocess.run(["claude", "-p"], input=prompt, capture_output=True, text=True, timeout=90)

Zalogowane jednorazowo na VPS przez claude auth login --claudeai (device-flow, konto Accenture Enterprise) — działa na tej samej licencji co interaktywna sesja Claude Code, bez billingu per-token.

Przepływ (tylko HTML/PDF — XLSX i audio_url mają inne ścieżki):

source_documents (extraction_status='pending', file_type IN html/pdf)
   → pre-filtr bez AI (odrzuca <200 znaków treści, boilerplate/404/captcha) — zero kosztu
   → JEDNO wywołanie `claude -p`: zrozum treść + oceń wartość jednocześnie
   → extracted_signals (parafraza PL, encje, sentiment, confidence_score)
   → classified_signals (segment, is_noise, relevance_score)
   → source_documents.extraction_status = 'done' | 'rejected_prefilter' | 'failed'

Ważne rozróżnienie pól (błąd znaleziony i naprawiony podczas testów): confidence_score (jak pewny jest model swojej oceny) i relevance_score (jak wartościowa jest treść) to dwa różne pola — szum może mieć wysoką pewność (model jest w 95% przekonany, że to reklama) przy niskiej trafności (5/100). Pomylenie tych pól psuje sens relevance_score w dashboardzie.

Zweryfikowane na żywo: model poprawnie odróżnił afiliacyjny ranking porównywarek OC/AC (relevance_score=8, szum) od artykułu o nowelizacji ustaw ubezpieczeniowych wdrażających Solvency II (relevance_score=78, segment regulators) — rozróżnienie niemożliwe dla prostego keyword-matchingu używanego w Web Scout.

XLSX (biuletyny KNF) i audio_url pozostają poza tym skryptem — XLSX wymaga osobnego parsera pandas do struktury konkretnego formatu (nie zaimplementowane jeszcze jako generyczny agent, na razie dane w w1_market_position z jednorazowego przetworzenia), audio_url przetwarza Agent 1c Transcriber.

PDF — ekstrakcja przez plik + narzędzia Claude, nie tekst przez stdin (zmienione 2026-09-22)

Problem znaleziony: pierwsza wersja wycinała tekst z PDF przez pdfplumber (pierwsze 20-50 stron, potem pierwsze 6000-40000 znaków) i wysyłała jako tekst do promptu. Dla krótkich dokumentów działało dobrze, ale dla dużych sprawozdań finansowych (test: raport PZU, 116 stron, 2.5MB) dane segmentowe (Dział I vs Dział II) leżały na stronach 90+ — liniowe czytanie od strony 1 z limitem znaków nigdy by tam nie dotarło.

Rozwiązanie: dla file_type == 'pdf', extraction_agent.py zapisuje plik do katalogu tymczasowego i wywołuje Claude z dostępem do narzędzi:

subprocess.run(
    ["claude", "--allowedTools", "Read,Bash(python3 *)", "-p"],
    input=prompt_z_path_do_pliku, ...
)

Claude samo decyduje jak przeczytać plik — w teście napisało własny skrypt pdfminer z analizą układu strony i celowo przeszukało konkretne strony (nie liniowo), znajdując pełną tabelę segmentową z 4 okresami porównawczymi (Q2 2026, H1 2026, Q2 2025, H1 2025), prawidłowo mapując nazewnictwo dokumentu na polskie Dział I/Dział II.

Kompromisy: - Uprawnienia: Bash zawężony do Bash(python3 *) — Claude może pisać i uruchamiać skrypty Python, nie dowolne komendy shell - Pre-filtr PDF — nadal szybki sanity-check pierwszych 3 stron przez pdfplumber przed kosztowną analizą (odrzuca oczywiście puste/zepsute pliki za darmo, zanim Claude dostanie cały plik)

Podejście hybrydowe — naprawione 2026-09-22 po odkryciu 175 PDF-ów w kolejce

Kolejka 175 PDF-ów × kilka minut/PDF przez ścieżkę plikową = kilkanaście godzin sekwencyjnie. Większość to jednak krótkie komunikaty (1-3 strony), nie 116-stronicowe sprawozdania. Rozwiązanie: sprawdzenie liczby stron (darmowe, pdfplumber) PRZED wyborem ścieżki:

  • ≤PDF_SHORT_PAGE_THRESHOLD (10) stron → szybka ścieżka tekstowa (jak HTML, ~20s) — BEZ obcinania treści, cała wyekstrahowana treść idzie do promptu (tylko wysoki bezpiecznik CONTENT_CHARS_PDF_SAFETY_CAP=80000, nigdy nie osiągany przez 10 stron). Ustalone świadomie — właściciel projektu zwrócił uwagę, że sztuczne obcinanie nawet "krótkiej" ścieżki ryzykowałoby utratą jakości ekstrakcji; 10 stron gęstego tekstu finansowego może przekroczyć wcześniej testowany limit 15000 znaków.
  • >10 stron → ścieżka plikowa (Read/Bash), opisana wyżej

Timeout podniesiony 600s → 1200s (20 min) — zaobserwowane: raport roczny Talanx (setki stron) nie zmieścił się w 600s.


Agent 3 — Classifier

Odpowiedzialność: Ocena wartości i kategoryzacja wyekstrahowanych sygnałów — strategiczne vs szum, przypisanie segmentu. Classifier pracuje wyłącznie na danych z extracted_signals — nigdy na surowych plikach.

Stan faktyczny: dla treści narracyjnych połączony z Agentem 2 w jeden krok — patrz sekcja wyżej. Poniższy opis (Warstwa 1 reguły + Warstwa 2 Claude API) opisuje pierwotny projekt, zachowany jako dokumentacja koncepcyjna i jako wzorzec dla przyszłego dociążenia (np. jeśli wolumen wzrośnie i trzeba będzie odsiewać część przypadków regułami przed Claude, żeby ograniczyć zużycie licencji Claude Code).

Lokalizacja: Claude.ai / Claude Code (licencja Accenture) — klasyfikacja zużywa tokeny, działa poza VPS

Uruchomienie: n8n webhook po zakończeniu Extractora

Architektura hybrydowa (Warstwa 1 → Warstwa 2):

Warstwa 1 — Reguły (classification_method = 'rules')

Szybka klasyfikacja oparta na słownikach. Bez kosztów API. Obsługuje ~80% przypadków.

SIGNAL_HIGH = [
    "wyniki", "strategia", "wywiad", "raport", "konferencja",
    "prezes", "wiceprezes", "dyrektor", "członek zarządu",
    "CFO", "CEO", "CTO", "CIO", "CRO",
    "dyrektor sprzedaży", "dyrektor bancassurance",
    "dyrektor likwidacji szkód", "dyrektor transformacji",
    "składka przypisana", "szkodowość", "wynik techniczny",
    "results", "strategy", "interview", "annual report"
]

SIGNAL_NOISE = [
    "kup", "porównaj", "najtańsze", "tanie", "kalkulator",
    "oferta", "promocja", "zniżka", "jak wybrać", "poradnik",
    "dla klientów", "ranking OC"
]

SEGMENT_RULES = {
    "ceo_cfo_tu":     ["prezes", "wiceprezes", "CEO", "CFO", "członek zarządu", "zarząd"],
    "financials_tu":  ["wyniki", "składka", "szkodowość", "wynik techniczny", "raport roczny"],
    "regulators":     ["KNF", "PIU", "NBP", "UFG", "Rzecznik Finansowy", "regulacje"],
    "conferences":    ["konferencja", "kongres", "forum", "panel", "Insurance Congress"],
    "bancassurance":  ["bancassurance", "bank", "PKO BP", "Santander", "Credit Agricole"],
    "intermediaries": ["multiagencja", "broker", "OFWCA", "agent ubezpieczeniowy", "Unilink"],
    "expert_analysis":["podcast", "analiza", "ekspert", "insurtech", "McKinsey", "Deloitte"],
    "eu_groups":      ["Allianz Group", "AXA Group", "Generali Group", "VIG", "Talanx", "CEE"]
}

Wynik Warstwy 1: - relevance_score 0–100 (liczba trafień sygnałów wysokiej wartości) - segment (pierwsza pasująca reguła segmentu) - is_noise (True jeśli trafień SIGNAL_NOISE > SIGNAL_HIGH)

Warstwa 2 — Claude API (classification_method = 'claude_api')

Uruchamiana tylko gdy Warstwa 1 zwraca relevance_score między 30–60 (przypadki graniczne). Obsługuje ~20% rekordów.

Prompt do Claude API:
"Jesteś ekspertem rynku ubezpieczeń w Polsce.
Oceń czy poniższy sygnał zawiera wartościowe informacje
strategiczne dla competitive intelligence.

Typ źródła: {source_type}
Tytuł / nagłówek: {title}
Treść (parafraza, max 500 znaków): {content_preview}

Odpowiedz TYLKO w JSON:
{
  'is_noise': true/false,
  'segment': '[nazwa segmentu]',
  'primary_topic': '[jedna wartość z ENUM signal_topic_category]',
  'secondary_topic': '[jedna wartość z ENUM signal_topic_category, lub null]',
  'relevance_score': [0-100],
  'reason': '[max 100 znaków uzasadnienia]',
  'companies_mentioned': ['PZU', 'Warta'],
  'roles_mentioned': ['prezes', 'dyrektor sprzedaży'],
  'topics': ['wyniki finansowe', 'strategia']
}"

segment i primary_topic to dwa niezależne wymiary klasyfikacji (dodane 2026-09-23): segment mówi kto jest źródłem/aktorem sygnału (zarząd TU, regulator, konferencja...). primary_topic/secondary_topic mówi o czym biznesowo jest treść (finanse, produkty, technologia, kadry...), niezależnie od tego kto o tym mówi — te dwa wymiary się nie pokrywają i dashboard musi umożliwiać filtrowanie po obu naraz. Pełny schemat ENUM i uzasadnienie w 02_DATA_MODEL.md.

Pełna instrukcja klasyfikacji primary_topic/secondary_topic (dokumentacja promptu, wklejona dosłownie z extraction_agent.py, stała TOPIC_CATEGORY_INSTRUCTION):

KLASYFIKACJA TOPIC_CATEGORY — INSTRUKCJA

Przypisz każdemu insightowi DOKŁADNIE JEDNĄ wartość primary_topic i opcjonalnie
JEDNĄ wartość secondary_topic z poniższego zamkniętego słownika 10 wartości.
Nie twórz nowych wartości.

ZAMKNIĘTY SŁOWNIK (ENUM):
finanse_wyniki | produkty_oferta | sprzedaz_dystrybucja | likwidacja_obsluga |
technologia_digital | strategia_ma | regulacje_compliance | marka_komunikacja |
organizacja_kadry | inne

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

KROK 1 — HIERARCHIA DECYZYJNA

Przejdź przez poniższe pytania po kolei. Zatrzymaj się na pierwszym które
pasuje — to jest Twój primary_topic.

1. Czy artykuł zawiera konkretne liczby finansowe na poziomie wyniku TU
   (GWP, COR, wynik netto, rentowność, rating wypłacalności)?
   → finanse_wyniki

2. Czy artykuł dotyczy konkretnego produktu ubezpieczeniowego — nowego,
   zmienionego, wycofanego, lub zmiany taryfy dla klienta?
   → produkty_oferta

3. Czy artykuł dotyczy kanału sprzedaży, sieci agencyjnej, bancassurance,
   partnerstwa dystrybucyjnego lub wolumenu sprzedaży (liczba polis)?
   → sprzedaz_dystrybucja

4. Czy artykuł dotyczy procesu obsługi klienta po sprzedaży — likwidacji szkód,
   czasu obsługi, skarg klientów, NPS jako wskaźnika jakości obsługi?
   → likwidacja_obsluga

5. Czy artykuł zawiera jakikolwiek sygnał technologiczny — nazwę systemu,
   technologii, dostawcy IT, lub słowa: AI, chmura, automatyzacja, platforma,
   aplikacja, cyberbezpieczeństwo — nawet jeśli to tylko zapowiedź lub plan?
   → technologia_digital

6. Czy artykuł dotyczy konkretnego zdarzenia regulacyjnego — decyzji KNF,
   kary, postępowania, nowego przepisu, wymogu compliance, raportu ESG
   w kontekście obowiązku prawnego?
   → regulacje_compliance

7. Czy artykuł dotyczy zmiany personalnej — nowej osoby w zarządzie lub RN,
   odejścia, zatrudnień lub zwolnień na dużą skalę?
   → organizacja_kadry

8. Czy artykuł dotyczy kampanii reklamowej, sponsoringu, PR, rebrandingu,
   nagrody branżowej lub działań wizerunkowych?
   → marka_komunikacja

9. Czy artykuł dotyczy M&A, przejęcia całego podmiotu, wejścia na nowy rynek
   geograficzny, joint venture, lub deklaracji strategicznej zarządu BEZ
   komponentu technologicznego?
   → strategia_ma

10. Żadne z powyższych nie pasuje — artykuł dotyczy rynku jako całości,
    trendów makroekonomicznych, lub branży bez przypisania do konkretnego TU?
    → inne

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

KROK 2 — PRZYPADKI GRANICZNE (few-shot examples)

— finanse_wyniki vs sprzedaz_dystrybucja —
✓ "PZU wypracował składkę z bancassurance 1,2 mld zł w H1 2025"
  → primary: finanse_wyniki
  → secondary: sprzedaz_dystrybucja

✓ "Warta podpisała umowę bancassurance z Bankiem Millennium"
  → primary: sprzedaz_dystrybucja
  → secondary: NULL

— produkty_oferta vs finanse_wyniki —
✓ "PZU podnosi składki OC o 15% — artykuł z perspektywy klienta"
  → primary: produkty_oferta
  → secondary: NULL

✓ "PZU podnosi składki OC o 15% — spółka tłumaczy rosnącą szkodowością
   i wpływem na wynik segmentu komunikacyjnego"
  → primary: finanse_wyniki
  → secondary: produkty_oferta

— technologia_digital vs strategia_ma —
✓ "PZU przeznacza 500 mln zł na transformację — wymienia konkretne projekty:
   nowy CRM, platforma online, AI w underwritingu"
  → primary: technologia_digital
  → secondary: strategia_ma

✓ "PZU przeznacza 500 mln zł na transformację cyfrową"
  → primary: strategia_ma
  → secondary: NULL

— technologia_digital vs likwidacja_obsluga —
✓ "Allianz wdraża AI do wyceny szkód — artykuł opisuje architekturę systemu
   i dostawcę technologii"
  → primary: technologia_digital
  → secondary: likwidacja_obsluga

✓ "Allianz wdraża AI do wyceny szkód — klient dostaje decyzję w 10 minut
   bez wizyty rzeczoznawcy"
  → primary: likwidacja_obsluga
  → secondary: technologia_digital

— sprzedaz_dystrybucja vs strategia_ma —
✓ "Warta przejmuje sieć 200 agentów od upadającego brokera"
  → primary: sprzedaz_dystrybucja
  → secondary: NULL

✓ "Warta przejmuje brokera regionalnego jako spółkę — wymaga zgody UOKiK"
  → primary: strategia_ma
  → secondary: sprzedaz_dystrybucja

— organizacja_kadry vs strategia_ma —
✓ "KNF zatwierdziła powołanie nowego prezesa Generali Polska"
  → primary: organizacja_kadry
  → secondary: NULL

✓ "Nowy prezes Generali ogłasza nową strategię — skupienie na zdrowiu
   i ograniczenie OC"
  → primary: strategia_ma
  → secondary: organizacja_kadry

— regulacje_compliance vs marka_komunikacja —
✓ "PZU publikuje raport ESG — artykuł o wymogach CSRD i procesie compliance"
  → primary: regulacje_compliance
  → secondary: NULL

✓ "PZU publikuje raport ESG — artykuł o celach klimatycznych i inicjatywach
   społecznych spółki bez kontekstu prawnego"
  → primary: marka_komunikacja
  → secondary: NULL

— likwidacja_obsluga vs marka_komunikacja —
✓ "Generali osiągnął NPS 42 — artykuł o procesie obsługi i czasie likwidacji"
  → primary: likwidacja_obsluga
  → secondary: NULL

✓ "Generali osiągnął NPS 42 — artykuł o tym jak spółka komunikuje sukces rynku"
  → primary: marka_komunikacja
  → secondary: NULL

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

KROK 3 — ZASADY secondary_topic

Użyj secondary_topic TYLKO gdy spełnione są WSZYSTKIE trzy warunki:
1. Insight równie silnie dotyczy drugiej kategorii — nie tylko ją wzmiankuje
2. Konsultant szukający informacji w tej drugiej kategorii byłby zaskoczony
   że jej tu nie ma
3. Druga kategoria jest inna niż primary_topic

Zostaw secondary_topic jako NULL gdy:
— Druga kategoria jest tylko tłem lub kontekstem dla głównego tematu
— Niepewny który primary_topic wybrać — to sygnał żeby wrócić do hierarchii,
  nie żeby użyć secondary_topic jako wyjścia awaryjnego
— Artykuł dotyka wielu tematów powierzchownie — wybierz dominujący

Maksymalnie JEDNA wartość secondary_topic. Nigdy więcej.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

KROK 4 — WERYFIKACJA PRZED ODPOWIEDZIĄ

Przed zwróceniem wyniku odpowiedz sobie na trzy pytania:
1. Czy primary_topic to pierwsza pasująca odpowiedź z hierarchii w Kroku 1?
2. Czy secondary_topic spełnia WSZYSTKIE trzy warunki z Kroku 3?
3. Czy użyłem "inne" — jeśli tak, czy artykuł naprawdę nie dotyczy żadnego
   konkretnego TU i żadna z 9 kategorii nie pasuje nawet częściowo?

Reklasyfikacja historyczna (backfill, 2026-09-23, zakończona — 100% pokrycia): rekordy classified_signals sklasyfikowane przed wprowadzeniem tej osi (primary_topic IS NULL) są dociągane jednorazowym przebiegiem extraction_agent.py --reclassify-topics, który pyta Claude WYŁĄCZNIE o primary_topic/secondary_topic — nie re-ocenia segment/relevance_score. Priorytet tekstu wejściowego: (1) parafraza z extracted_signals.extracted_text, gdy dostępna; (2) dla rekordów powiązanych tylko przez raw_signal_id (era Agenta 1a przed połączeniem 2+3, np. RSS media/YouTube, bez wpisu w extracted_signals) — żywy artykuł pobrany na bieżąco z raw_signals.raw_data->>'url' (funkcja _fetch_article_text()); (3) sam tytuł z raw_signals.title, wyłącznie gdy pobranie URL się nie powiedzie. Pierwsza wersja backfillu ograniczała się do samego tytułu dla przypadku (2) — poprawione tego samego dnia po odkryciu, że raw_data.text_preview dla tych starych rekordów to menu/nawigacja strony, nie treść artykułu (nigdy nie było tu prawdziwej ekstrakcji), a URL wciąż żyje i można pobrać prawdziwą treść za cenę jednego GET. Wynik: 515/515 rekordów z wypełnionym primary_topic, 0 pozostało na NULL.

Szczegółowe zadania:

DLA KAŻDEGO REKORDU W extracted_signals (status = 'pending_classification'):
1. Uruchom Warstwę 1 (reguły słownikowe)
2. Jeśli relevance_score < 30 → is_noise = TRUE, zapisz, pomiń Warstwę 2
3. Jeśli relevance_score > 60 → zapisz jako wartościowy, pomiń Warstwę 2
4. Jeśli relevance_score 30-60 → uruchom Warstwę 2 (Claude API)
5. Zapisz wynik do classified_signals
6. Zaktualizuj known_sources.quality_score jeśli źródło konsekwentnie wartościowe
7. Wyślij webhook do n8n: {status: done, classified: N, noise: M, api_calls: K}

Ekonomia: Claude API wywoływane tylko dla ~20% rekordów (przypadki graniczne).

Output: Tabela classified_signals — każdy sygnał z segmentem, oceną i metadanymi


Agent 4 — Analyst

Odpowiedzialność: Analiza sklasyfikowanych sygnałów i metryk, wykrywanie wzorców, trendów i anomalii, generowanie insightów łączących dane z wielu źródeł.

Lokalizacja: Claude.ai / Claude Code (licencja Accenture) — analiza zużywa tokeny

Uruchomienie: n8n cron, raz w tygodniu (poniedziałek 07:00 UTC) + na żądanie przez dashboard

Szczegółowe zadania:

ANALIZA TYGODNIOWA:
1. Pobierz wszystkie classified_signals z ostatnich 7 dni
   gdzie is_noise = FALSE i relevance_score >= 60
2. Pobierz nowe metryki z tabel w1-w7 (dodane w ostatnim tygodniu)
3. Grupuj sygnały po: segment, companies_mentioned, topics
4. Wykryj trendy: tematy powtarzające się ≥3 razy w różnych źródłach
5. Wykryj anomalie: nagły wzrost sygnałów o danym TU (>2x tygodniowa średnia)
6. Wykryj ruchy konkurencji: konkretne deklaracje strategiczne TU
7. Wykryj zmiany regulacyjne: nowe komunikaty KNF/PIU z wysokim relevance_score
8. Dla każdego wykrytego wzorca → generuj insight (parafraza, nie cytaty)
9. Generuj embedding (VECTOR) dla każdego insightu → zapis do insights.embedding
10. Zapisz do tabeli insights
11. Wyślij webhook do n8n: {status: done, insights_generated: N}

ANALIZA NA ŻĄDANIE:
- Benchmark wybranych TU (porównanie metryk w1-w7)
- Deep-dive na konkretny temat / TU / okres
- Odpowiedź na pytanie semantyczne przez pgvector

Typy insights: - trend — temat powtarzający się ≥3 razy w tygodniu w różnych źródłach - anomaly — nagły wzrost sygnałów o danym TU (>2x średnia tygodniowa) - competitor_move — konkretna zmiana strategiczna TU (deklaracja, produkt, kanał) - regulatory_change — nowe regulacje lub komunikaty KNF/PIU - benchmark_delta — istotna zmiana metryki TU względem poprzedniego okresu

Zasada intelligence: Insight musi odpowiadać na "dlaczego" — nie tylko "co". Sam COR=89% dla PZU to dana. Wartość zaczyna się gdy Analyst odpowiada "dlaczego COR spadł, co to znaczy dla strategii, jak się ma do konkurencji".

Output: - Tabela insights — insighty z embeddingiem VECTOR (pgvector) - Gotowe do wyświetlenia w dashboardzie i do raportów


Agent 5 — Reporter

Odpowiedzialność: Prezentacja danych — dynamiczny dashboard HTML oraz generowanie raportów PDF na żądanie. Reporter nie analizuje — tylko wizualizuje gotowe dane z insights, classified_signals i w1-w7.

Lokalizacja: /opt/insurance-dashboard/ (nginx serwuje dashboard)

Uruchomienie: Dashboard — ciągły (nginx). Raporty PDF — na żądanie przez UI.

Szczegółowe zadania:

DASHBOARD (ciągły):
1. REST API odczytuje dane z PostgreSQL (insights, classified_signals, w1-w7)
2. Widoki dashboardu odświeżane automatycznie po każdym cyklu Agenta 4
3. Filtrowanie po: TU, segment, okres, typ insightu
4. Wyszukiwanie semantyczne (pgvector) po naturalnym języku

RAPORTY PDF (na żądanie):
1. Właściciel projektu wybiera parametry: TU, okres, typ raportu
2. Reporter pobiera dane z insights + classified_signals + w1-w7
3. Generuje raport przez Claude API (formatowanie, narracja)
4. Zapisuje do tabeli reports + plik PDF
5. Udostępnia do pobrania przez dashboard

TYGODNIOWY DIGEST (automatyczny, poniedziałek 08:00 UTC):
1. Pobierz insights z ostatniego tygodnia (importance >= 3)
2. Wygeneruj HTML digest
3. Wyślij email / webhook (konfigurowany przez właściciela)

Typy raportów: - weekly — automatyczny digest tygodniowy (top insights, alerty) - monthly — automatyczny, pierwszy poniedziałek miesiąca - benchmark — porównanie wybranych TU na podstawie metryk w1-w7 - adhoc — dowolny zakres i temat, na żądanie przez dashboard

Dashboard — widoki: 1. Przegląd tygodnia — top insights, alerty, nowości regulacyjne 2. Mapa TU — aktywność i metryki każdego towarzystwa w danym okresie 3. Segmenty — filtrowanie po: regulacje / zarządy / bancassurance / intermediaries 4. Wyszukiwanie semantyczne — "co mówiono o cenach OC w Q3 2025" (pgvector) 5. Źródła — jakość i aktywność poszczególnych kanałów i stron 6. Raporty — historia wygenerowanych raportów, generowanie nowych

Output: HTML dashboard serwowany przez nginx + PDF raporty w tabeli reports

Telemetria i metryki sukcesu (instrumentacja wewnątrz Agenta 5)

Nie jest to osobny agent — ten sam trigger (żądanie z dashboardu) i te same zasoby (PostgreSQL) co reszta Reportera. Loguje każde zapytanie konsultanta do dashboard_queries (schemat: 02_DATA_MODEL.md).

Metryki wdrażane fazowo, żeby nie projektować z góry pól, których jeszcze nie wiadomo jak używać:

Poziom 1 — Adopcja (mierzalne od dnia 1, Faza 1 MVP): | Metryka | Jak liczona | |---|---| | Weekly Active Users (WAU) | unikalni użytkownicy z ≥1 query/tydzień | | Queries per user per week | liczba zapytań / aktywny użytkownik | | Adoption rate w zespole | WAU / total zespół consultingowy | | Query-to-session ratio | ile zapytań w jednej sesji | | Time to first value | dni od onboardingu do 1. użytecznego wyniku |

Poziom 2 — Wpływ na pracę (po 4-8 tyg. użycia, Faza 2): | Metryka | Jak liczona | |---|---| | Time saved per research task | self-reported (mikro-ankieta po sesji, 1 klik) vs rzeczywisty czas | | Pre-meeting usage rate | % spotkań klienckich poprzedzonych query w ciągu 48h | | Insight-to-deliverable rate | ile insightów trafiło do finalnego raportu/prezentacji | | Reuse rate | % zapytań będących rozszerzeniem wcześniejszego, nie zaczynaniem od zera |

Poziom 3 — Zaufanie i jakość (Faza 3): | Metryka | Jak liczona | |---|---| | Feedback rating per query | 👍/👎 lub 1-5 na odpowiedź | | Correction rate | % odpowiedzi poprawionych/zgłoszonych jako błędne | | Would cite to client | osobny checkbox — różnica między "ciekawe" a "użyteczne biznesowo" |

Zbieranie "time saved" bez uciążliwości: jedno pytanie po zakończeniu sesji (nie każdego query), jeden klik: "Ta sesja zajęła ~X min. Bez narzędzia zajęłaby: [<15min] [15-30min] [30-60min] [>1h] [nie wiem]". Wystarcza do policzenia zagregowanych godzin zaoszczędzonych zespołowi miesięcznie.


Feedback loop (uczenie systemu)

Właściciel projektu przez dashboard może: - Oznaczyć sygnał jako szum → manually_reviewed = TRUE, is_noise = TRUE - Oznaczyć kanał jako wartościowy → known_sources.quality_score += 10 - Oznaczyć kanał jako szum → known_sources.is_monitored = FALSE - Skorygować klasyfikację segmentu → classification_method = 'manual'

Te korekty wracają jako dane treningowe dla Warstwy 1 Agenta 3 (Classifier) przy kolejnej iteracji konfiguracji reguł. n8n co miesiąc generuje raport jakości klasyfikacji (precision/recall na podstawie korekt manualnych).