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 |
| 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 bezpiecznikCONTENT_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).