O projekcie
Agent, który na bieżąco odpowiada na pytania o karty charakterystyki produktów marki budowlanej — handlowcom w rozmowie z klientem, magazynowi przy przyjęciu towaru i służbie BHP przy zdarzeniu. Odpowiada CYTATEM z konkretnej sekcji konkretnej wersji dokumentu, a nie własnym streszczeniem.
Zacznę od zdania, które wyznacza tu wszystko, bo bez niego projekt jest nieodpowiedzialny: ZŁA ODPOWIEDŹ MOŻE KOGOŚ SKRZYWDZIĆ. Pytania dotyczą pierwszej pomocy, środków ochrony indywidualnej, substancji, z którymi nie wolno mieszać, i postępowania przy rozlaniu. To nie jest dziedzina, w której model „raczej dobrze podsumowuje” — tutaj parafraza instrukcji bezpieczeństwa jest błędem kategorialnym, nawet gdy brzmi trafnie.
Stąd reguła nadrzędna: AGENT NIE PARAFRAZUJE SEKCJI BEZPIECZEŃSTWA. Dla sekcji o pierwszej pomocy, postępowaniu przy uwolnieniu, magazynowaniu, ochronie indywidualnej, reaktywności, toksykologii i usuwaniu odpowiedź jest DOSŁOWNYM CYTATEM z dokumentu, z numerem sekcji i wersją. Streszczenie dopuszczam tylko tam, gdzie nie niesie instrukcji: identyfikacja produktu, skład, właściwości fizyczne.
Druga rzecz, która odróżnia to od zwykłego wyszukiwania w dokumentach: KARTA CHARAKTERYSTYKI MA USTAWOWO USTALONĄ STRUKTURĘ SZESNASTU SEKCJI. To nie konwencja wydawcy, tylko układ narzucony rozporządzeniem. Pytanie o rękawice należy więc do sekcji o kontroli narażenia, pytanie o kontakt z okiem do sekcji o pierwszej pomocy, a pytanie „z czym tego nie mieszać” do sekcji o reaktywności.
Wyszukiwanie po podobieństwie akapitów tę strukturę marnuje i myli się w sposób szczególnie nieprzyjemny: akapity o zagrożeniach brzmią podobnie w kilku sekcjach naraz. Dopasowanie idzie więc NAJPIERW DO SEKCJI, a dopiero w niej do treści. Skutek uboczny jest tym, po czym poznaje się dobrą odpowiedź: da się podać jej adres — sekcja 8 karty w wersji 4.2 z konkretną datą.
WERSJA DOKUMENTU JEST TU CAŁYM ZAGADNIENIEM, nie metadaną. Karty są aktualizowane: zmienia się klasyfikacja, zmieniają się wartości graniczne, zmienia się zalecana ochrona. Odpowiedź z wersji NADPISANEJ jest gorsza niż brak odpowiedzi, bo brzmi identycznie jak dobra. Dlatego wersja nadpisana WYPADA Z INDEKSU, a nie schodzi niżej w wynikach — jeśli została w indeksie, to znaczy, że kiedyś zostanie zacytowana.
Trzecia rzecz, którą w tej branży łatwo przegapić: KARTA CHARAKTERYSTYKI TO NIE DEKLARACJA WŁAŚCIWOŚCI UŻYTKOWYCH. Pytania o reakcję na ogień, nośność, emisyjność czy klasę wyrobu należą do deklaracji właściwości, a nie do karty — to inny dokument, z innej regulacji, o innej wadze prawnej. Agent, który odpowiada na takie pytanie z karty, będzie brzmiał pewnie i będzie mylił się w sposób, którego pytający nie ma jak wychwycić. Rozpoznanie RODZAJU DOKUMENTU jest więc osobnym krokiem przed wyszukiwaniem.
Czwarta: TE SAME LICZBY RÓŻNIĄ SIĘ MIĘDZY RYNKAMI. Dopuszczalne wartości narażenia zawodowego są ustalane krajowo, więc ta sama substancja ma inne progi w Polsce i w Niemczech, a karta musi być w języku kraju, w którym wyrób jest wprowadzany do obrotu. Odpowiedź z właściwej sekcji, ale z karty dla innego rynku, jest odpowiedzią nieprawdziwą. Rynek jest więc częścią zapytania, nie ustawieniem interfejsu.
Piąta granica jest najtwardsza: AGENT NIE KLASYFIKUJE. Ustalenie klasy zagrożenia, zwrotów wskazujących rodzaj zagrożenia czy tego, czy mieszanina jest niebezpieczna, to czynność producenta, wykonywana przez osobę o odpowiednich kwalifikacjach i obwarowana odpowiedzialnością. Agent czyta i cytuje to, co producent ustalił. Nie wnioskuje klasyfikacji z opisu, nawet gdy „to oczywiste” — bo dokładnie w tym miejscu przestałby być narzędziem do czytania dokumentów, a stałby się nieuprawnionym źródłem klasyfikacji.
Z tego wynika, że ODMOWA JEST FUNKCJĄ, nie awarią. Agent odmawia, gdy pytanie wychodzi poza treść dokumentów: porady medycznej, oceny „czy to jest bezpieczne w mojej sytuacji”, doboru zamiennika, interpretacji przepisu. Odmawia WSKAZUJĄC KANAŁ — służbę BHP albo producenta — a nie zostawiając pytającego z niczym. Udzielona w tym miejscu uprzejma odpowiedź „ogólna” byłaby najgorszym możliwym wyjściem.
„Na bieżąco” ma tu ścisłe znaczenie i jest pilnowane: indeks NIE MOŻE być starszy niż zbiór dokumentów. Publikacja nowej wersji karty unieważnia indeks dla tego produktu, a gdy przeliczenie się nie udało, agent WSTRZYMUJE ODPOWIEDZI dla tych produktów, zamiast odpowiadać z poprzedniego stanu. To ta sama zasada co przy kursach walut w innym projekcie: na treści krytycznej nie wolno otwierać się na wypadek awarii.
Produkt też trzeba rozpoznać, a to nie jest trywialne przy kilkuset pozycjach: ta sama nazwa handlowa potrafi mieć kilka kart — inna receptura na inny rynek, inne opakowanie, inna generacja wyrobu. Dopasowanie idzie więc po kodzie produktu i kodzie kreskowym, a nie po nazwie; nazwa jest aliasem do szukania. Nierozpoznany produkt kończy się pytaniem uzupełniającym, a nie odpowiedzią z najbardziej podobnej karty.
Na końcu rzecz, która decyduje o tym, czy tego narzędzia da się używać w firmie: KAŻDA ODPOWIEDŹ JEST ZAPISANA. Pytanie, rozpoznany produkt, rodzaj dokumentu, wersja, numery sekcji, dosłowny zacytowany fragment i moment. Bo pierwszego dnia po zdarzeniu pytanie nie brzmi „jak działa wasz agent”, tylko „co ten system powiedział pracownikowi o tej substancji i z czego to wziął”.
Problem
Pytania o karty charakterystyki spływają do jednej osoby, która wyszukuje odpowiedź w kilkuset plikach PDF — więc odpowiedź przychodzi z opóźnieniem albo nie przychodzi. Zwykły agent na dokumentach jest tu jednak gorszy niż nic: parafrazuje instrukcje bezpieczeństwa, miesza sekcje o podobnym brzmieniu, odpowiada z nadpisanej wersji i nie odróżnia karty charakterystyki od deklaracji właściwości użytkowych.
Rozwiązanie
Dopasowanie najpierw do ustawowej sekcji, potem do treści; odpowiedź jako DOSŁOWNY CYTAT z numerem sekcji i wersją dokumentu. Wersja nadpisana wypada z indeksu, rynek jest częścią zapytania, klasyfikacji agent nie wykonuje, a przy pytaniu poza dokumentem odmawia i wskazuje kanał. Każda odpowiedź jest zapisana razem z tym, z czego powstała.
Funkcje
- cytat z numerem sekcji i wersją dokumentu zamiast streszczenia
- streszczenie dopuszczone tylko w sekcjach bez instrukcji bezpieczeństwa
- dopasowanie najpierw do sekcji rozporządzenia, potem do treści w niej
- wersja nadpisana WYPADA z indeksu, nie schodzi niżej w wynikach
- rozpoznanie rodzaju dokumentu: karta charakterystyki kontra deklaracja właściwości
- rynek jako część zapytania — wartości narażenia różnią się między krajami
- agent nie wykonuje klasyfikacji; czyta to, co ustalił producent
- odmowa wskazuje kanał (BHP, producent), nie zostawia pytającego z niczym
- indeks starszy niż zbiór dokumentów WSTRZYMUJE odpowiedzi dla tych produktów
- każda odpowiedź zapisana: produkt, wersja, sekcje, cytat, moment
Moduły
produkty-tozsamosc
rozpoznawanie wyrobuUstala, o który wyrób pyta człowiek — po kodzie, nie po nazwie handlowej.
- dopasowanie po kodzie produktu i kodzie kreskowym; nazwa jest aliasem do szukania
- ta sama nazwa handlowa może mieć kilka kart: inny rynek, inne opakowanie, inna generacja
- nierozpoznany wyrób kończy się pytaniem uzupełniającym, nie kartą najbardziej podobną
- wycofany wyrób zachowuje karty w archiwum, ale jest wyraźnie oznaczony jako wycofany
- alias wprowadzony przez handlowca wymaga potwierdzenia, zanim zacznie wiązać
dokumenty-wersje
dyscyplina wersjiPilnuje, żeby cytowana mogła być wyłącznie wersja obowiązująca.
- wersja nadpisana WYPADA z indeksu — zostawiona kiedyś zostanie zacytowana
- przy dokumencie zapisany numer wersji, data aktualizacji i moment wczytania
- archiwum nadpisanych wersji zostaje do wglądu, poza zasięgiem odpowiedzi
- nowa wersja unieważnia indeks dla tego wyrobu, a nie dla całego zbioru
- dokument bez rozpoznanej wersji nie wchodzi do indeksu wcale
rodzaj-dokumentu
warstwa rozpoznaniaRozstrzyga, czy odpowiedzi szukać w karcie charakterystyki, czy w innym dokumencie.
- pytania o reakcję na ogień, nośność i emisyjność należą do deklaracji właściwości
- pytania o pierwszą pomoc, ochronę i reaktywność należą do karty charakterystyki
- zła droga daje odpowiedź PEWNĄ I NIEPRAWDZIWĄ, której pytający nie wychwyci
- brak właściwego dokumentu dla wyrobu kończy się odmową ze wskazaniem kanału
- rozpoznanie jest osobnym krokiem PRZED wyszukiwaniem, nie filtrem po nim
sekcje-16
struktura ustawowaRozkłada dokument na sekcje narzucone rozporządzeniem i szuka w obrębie sekcji.
- szesnaście sekcji to układ z rozporządzenia, nie konwencja wydawcy dokumentu
- dopasowanie idzie najpierw do sekcji, dopiero potem do treści w jej wnętrzu
- akapity o zagrożeniach brzmią podobnie w kilku sekcjach — stąd ta kolejność
- sekcja nieobecna w dokumencie jest zgłaszana jako brak, nie zastępowana sąsiednią
- numer sekcji wchodzi do odpowiedzi, więc cytat ma sprawdzalny adres
rynek-i-jezyk
warstwa krajowaPilnuje, żeby liczby i język pochodziły z karty właściwej dla rynku.
- dopuszczalne wartości narażenia zawodowego są ustalane krajowo i się różnią
- karta musi być w języku kraju wprowadzenia wyrobu do obrotu
- rynek jest częścią zapytania, nie ustawieniem interfejsu do zapomnienia
- brak karty dla rynku kończy się odmową, nie podstawieniem karty z innego kraju
- odpowiedź niesie informację, dla którego rynku obowiązuje przytoczona wartość
agent-cytatu
warstwa odpowiedziBuduje odpowiedź z cytatów, z jawną granicą między cytatem a streszczeniem.
- sekcje z instrukcjami bezpieczeństwa: WYŁĄCZNIE cytat dosłowny
- streszczenie dopuszczone w identyfikacji, składzie i właściwościach fizycznych
- cytat zawsze z numerem sekcji, wersją dokumentu i nazwą wyrobu
- model układa i wskazuje fragmenty; nie przepisuje ich własnymi słowami
- gdy cytat nie pokrywa pytania w całości, mówi to wprost zamiast domykać
granice-odmowy
warstwa granicWie, czego nie wolno mu odpowiedzieć — i do kogo wtedy odesłać.
- NIE WYKONUJE KLASYFIKACJI: to czynność producenta i osoby z kwalifikacjami
- nie udziela porady medycznej ani oceny „czy to bezpieczne w mojej sytuacji”
- nie dobiera zamiennika i nie interpretuje przepisu
- odmowa wskazuje kanał — służbę BHP albo producenta — i zapisuje powód
- uprzejma odpowiedź „ogólna” w tym miejscu jest najgorszym możliwym wyjściem
swiezosc-indeksu
warstwa aktualnościNie pozwala odpowiadać z indeksu starszego niż zbiór dokumentów.
- publikacja nowej wersji unieważnia indeks dla tego wyrobu
- nieudane przeliczenie WSTRZYMUJE odpowiedzi dla objętych wyrobów
- wstrzymanie jest komunikatem, nie ciszą — pytający wie, że ma iść do człowieka
- wiek indeksu widoczny w interfejsie przy każdej odpowiedzi
- na treści krytycznej nie otwieramy się na wypadek awarii, tak jak przy kursach walut
dziennik-odpowiedzi
warstwa rozliczalnościZapisuje, co system powiedział i z czego — na dzień po zdarzeniu.
- zapis: pytanie, wyrób, rodzaj dokumentu, wersja, sekcje, cytat, moment
- zapisane są także ODMOWY, bo one też są odpowiedzią systemu
- dziennik pozwala odtworzyć odpowiedź co do znaku, także po aktualizacji karty
- retencja dziennika osobna od retencji dokumentów
- pierwsze pytanie po zdarzeniu brzmi „co system powiedział” — i tu jest odpowiedź
Architektura
- Podstawa
- usługa w TypeScripcie, PostgreSQL z pgvector na fragmenty sekcji, odczyt dokumentów przez pdf.js; dokumenty zostają w infrastrukturze klienta
- Reguła nadrzędna
- instrukcje bezpieczeństwa wyłącznie jako CYTAT DOSŁOWNY z numerem sekcji i wersją; parafraza jest tu błędem kategorialnym, nie stylistycznym
- Gdzie streszczenie wolno
- identyfikacja wyrobu, skład, właściwości fizyczne — sekcje, które nie niosą instrukcji postępowania
- Wyszukiwanie
- najpierw dopasowanie do sekcji narzuconej rozporządzeniem, potem do treści w jej wnętrzu; nie po podobieństwie dowolnych akapitów
- Wersje
- wersja nadpisana wypada z indeksu; archiwum zostaje do wglądu, ale poza zasięgiem odpowiedzi
- Rodzaj dokumentu
- rozpoznanie przed wyszukiwaniem — karta charakterystyki i deklaracja właściwości użytkowych odpowiadają na inne pytania
- Rynek
- wartości narażenia zawodowego są krajowe; rynek jest częścią zapytania, a brak karty dla rynku kończy się odmową
- Czego nie robi
- nie klasyfikuje, nie doradza medycznie, nie dobiera zamiennika, nie interpretuje przepisu
- Odmowa
- wskazuje kanał (BHP, producent) i jest zapisywana; odpowiedź „ogólna” byłaby tu najgorszym wyjściem
- Rozpoznanie wyrobu
- po kodzie produktu i kodzie kreskowym; nazwa handlowa to alias, bo jednej nazwie odpowiada kilka kart
- Świeżość
- indeks nie może być starszy niż zbiór dokumentów; nieudane przeliczenie wstrzymuje odpowiedzi, nie cofa do starego stanu
- Rozliczalność
- dziennik z pytaniem, wersją, sekcjami i dosłownym cytatem; odmowy zapisane na równi z odpowiedziami
- Dane
- dokumenty i dziennik w infrastrukturze klienta; poza nią idą tylko fragmenty potrzebne do złożenia jednej odpowiedzi
Technologie
- TypeScript
- Node.js
- PostgreSQL
- pgvector
- pdf.js
- Claude
Autor
Mariusz PerzyńskiClient Relations & Operations