═══════════════════════════════════════════════════════════════════════ MELANIA · 2.5 Moduł Eksperckiego Labelowania Aktów Naukową Inteligencją Artyficjalną Machine Expert for Legal Annotation with Neural Intelligence Algorithms ═══════════════════════════════════════════════════════════════════════ Autor: Jakob Maziarz Projekt: Iura — Źródła Prawa Dawnego Wersja: 2.5 (12 maja 2026) © Jakob Maziarz, Universitas Iagellonica, 2026 CZYM JEST MELANIA ═══════════════════════════════════════════════════════════════════════ MELANIA to program do automatycznego semantycznego tagowania aktów prawnych. W skrócie: dostaje na wejściu dokument zawierający przepisy i słownik kontrolowany (tezaurus), a w wyniku produkuje ten sam dokument z każdym artykułem opatrzonym zestawem haseł z tego słownika. Wygląda to tak. Bierzesz na przykład Kodeks zobowiązań z 1933 r., wybierasz słownik pojęć (z dysku albo prosto z serwera IURA Explorer przyciskiem w oknie programu), uruchamiasz MELANIĘ. Po kilkunastu minutach masz na dysku plik Word, w którym pod każdym artykułem widnieje coś takiego: Art. 1. (treść artykułu...) [hasła: zobowiązanie (96%), źródła zobowiązań (92%), swoboda umów (88% [!])] [!] swoboda umów: Przepis nie definiuje swobody umów wprost, ale wprowadza generalną zasadę autonomii woli stron. Plus szczegółowy raport ze statystykami: ile haseł trafiło z dużą pewnością, ile wymaga weryfikacji, ile artykułów ma potencjalne naruszenia hierarchii pojęciowej. To narzędzie do badawczej pracy nad aktami prawnymi: tagowanie ułatwia indeksowanie, wyszukiwanie, porównywanie systemów prawnych różnych epok, budowanie hipertekstów akademickich. Program nie zastępuje pracy badacza — zamiast tego automatyzuje żmudną część (przypisywanie haseł), zostawiając weryfikację merytoryczną człowiekowi. Pod spodem siedzi rodzina modeli Google Gemini (3.1 Pro / Flash / Flash-Lite). To duże modele językowe, zdolne rozumieć kontekst historyczny, niuanse prawnicze i strukturę systemu prawa. Nie są nieomylne — dlatego program używa dwóch przebiegów (najpierw wstępne tagowanie, potem weryfikacja krzyżowa z artykułami sąsiednimi) i pokazuje confidence dla każdego hasła, żebyś widział, gdzie AI jest pewna, a gdzie warto sprawdzić. DLA KOGO TO NARZĘDZIE ═══════════════════════════════════════════════════════════════════════ • Badacze historii prawa — dla nich powstała pierwotnie. Tagowanie artykułów dawnych kodyfikacji (Kodeks Napoleona, ABGB, BGB, polskie prawa dzielnicowe i unifikacyjne) pojęciami z tezaurusa SKOS pozwala budować mapy konceptualne, porównywać systemy, indeksować zbiory źródeł. • Bibliotekarze i archiwiści cyfrowi — gdy mają zbiory aktów do skatalogowania i kontrolowane słowniki dziedzinowe, MELANIA daje pierwszą warstwę indeksowania automatycznie. • Edytorzy serii źródłowych — przy publikacji edycji krytycznej aktu prawnego dobrze mieć tematyczny indeks. MELANIA generuje materiał wyjściowy, który można potem ręcznie dopracować. • Zespoły projektów humanistyki cyfrowej — gdy potrzebują przejść od czystego tekstu do strukturalnej reprezentacji wiedzy. Nie jest to narzędzie dla codziennej pracy prawniczej (nie zastępuje LEX-a ani komentarzy do kodeksów). To narzędzie ze świata Digital Humanities, zoptymalizowane pod pracę naukową i edytorską. JAK TO DZIAŁA W SKRÓCIE ═══════════════════════════════════════════════════════════════════════ Proces krok po kroku: 1. Program wczytuje dokument źródłowy (DOCX, PDF lub TXT) i tnie go na artykuły po wzorcu "Art. N." (z obsługą indeksów górnych "Art. 20.¹" i sufiksów literowych "Art. 5a."). 2. Wczytuje słownik SKOS (CSV lub XLSX) i buduje wewnętrzną reprezentację z wszystkimi metadanymi: definicje, relacje hierarchiczne, synonimy, źródła kodyfikacyjne, odpowiedniki łacińskie/niemieckie/francuskie. Słownik można też pobrać prosto z serwera IURA Explorer (https://tezaurus.iura.uj.edu.pl) bez wychodzenia z programu. 3. Wysyła słownik do AI jako "instrukcja systemowa" (kosztowne, ale dzięki Context Caching API liczy się tylko raz — kolejne zapytania korzystają z bufora z 90% zniżką). 4. Przebieg 1: dla każdej paczki 3-6 artykułów wysyła zapytanie z pełnym kontekstem (3 wcześniejsze + 3 późniejsze artykuły jako odniesienie). AI proponuje hasła z confidence dla każdego. 5. Przebieg 2: te same paczki, ale teraz z tagami z Przebiegu 1 jako dane wejściowe. AI weryfikuje krzyżowo — dodaje pominięte hasła, usuwa błędne, dostosowuje confidence z uwzględnieniem haseł w sąsiednich artykułach. 6. Algorytmiczny walidator hierarchii (niezależny od AI) sprawdza, czy w którymś artykule nie współwystępują hasła zbyt odległe hierarchicznie (np. "prawo cywilne" L1 razem z "dziedziczenie testamentowe własnoręczne" L7 — to sygnał, że hasło ogólne jest zbędne lub artykuł reguluje całą dziedzinę). 7. Generuje dwa pliki wyjściowe: dokument Word z tagami pod każdym artykułem i raport tekstowy ze statystykami, kosztami, listą artykułów do weryfikacji. Cały proces dla typowego kodeksu (174 artykuły, słownik kilkuset pojęć) zajmuje 12-15 minut na modelu Flash, 30-90 minut na Pro z trybem thinking. Słowniki tezaurusowe (2000+ haseł z bogatymi opisami) wydłużają proces, ale jakość tagowania znacząco rośnie. CO MUSISZ MIEĆ ═══════════════════════════════════════════════════════════════════════ Komputer z systemem Windows 10 lub 11 (64-bit), z minimum 4 GB RAM (8 GB komfortowo). Program działa też na macOS i Linuksie, ale gotowe skrypty instalacyjne (.bat) są pod Windowsa. Jeśli nie jesteś na Windowsie, instalacja ze źródeł działa tak samo — po prostu pomiń sekcję o .exe. Połączenie z Internetem — MELANIA korzysta z API Google Gemini, więc sieć jest niezbędna w trakcie tagowania. Pobieranie słowników z serwera IURA też wymaga sieci, ale to zwykle krótka chwila. Wynik (plik DOCX i raport) zapisuje się lokalnie. Klucz API do Google AI Studio — to teraz WYMAGANE. Wersja 2.5 nie ma wbudowanego klucza domyślnego (poprzednie wersje miały zaszyty klucz autora, co wiązało się z ograniczeniami i ryzykiem przypadkowego wycieku). Musisz wygenerować własny, raz, za darmo: 1. Otwórz https://aistudio.google.com/apikey 2. Zaloguj się kontem Google 3. Kliknij "Create API key" 4. Skopiuj klucz (zaczyna się od AIzaSy) Klucz wpisujesz w polu "Google AI API Key" w sekcji "Wydajność i API" albo ustawiasz na stałe jako zmienną środowiskową GOOGLE_API_KEY (patrz sekcja "Klucz API" niżej). Bez klucza program przy próbie uruchomienia tagowania pokaże okno błędu z instrukcją. Free Tier (darmowy plan Google) daje 15 zapytań/minutę, 1500 zapytań/ dziennie. Dla typowych zastosowań MELANIA to zupełnie wystarcza — faktycznie nie zapłacisz nic. Program pokazuje koszt "teoretyczny" w raporcie (ile by kosztowało, gdybyś używał płatnego planu) — to wyłącznie informacja, FAKTYCZNY koszt na Free Tier wynosi $0.00. Pythona 3.10 lub nowszego, jeśli chcesz uruchamiać ze źródeł. Pobierz z https://www.python.org/downloads/ — w instalatorze zaznacz "Add Python to PATH". Jeśli używasz gotowego .exe, Pythona nie musisz mieć. Miejsce na dysku: ok. 250 MB na zależności + ok. 135 MB jeśli kompilujesz do .exe. INSTALACJA ═══════════════════════════════════════════════════════════════════════ Masz dwie ścieżki: uruchomienie z kodu źródłowego (szybciej, ale wymaga Pythona) albo kompilacja do samodzielnego .exe (Python przestaje być potrzebny po skompilowaniu). — Ścieżka A: uruchomienie ze źródeł —————————————————————————————————— Otwórz wiersz poleceń (cmd albo PowerShell) w katalogu z plikiem MELANIA_2_5_FINAL.py. Zainstaluj zależności: pip install pandas python-docx openpyxl google-genai Pillow customtkinter Opcjonalnie, jeśli chcesz przyjmować dokumenty PDF i skany: pip install pdfplumber pypdf pytesseract Uruchom program: python MELANIA_2_5_FINAL.py — Ścieżka B: kompilacja do .exe —————————————————————————————————————— Umieść w jednym katalogu pliki MELANIA_2_5_FINAL.py oraz build_2_5_v2.bat. Kliknij dwukrotnie .bat. Skrypt sam wszystko zainstaluje i uruchomi PyInstallera. Po 3-12 minutach w podkatalogu dist\ pojawi się MELANIA_2_5.exe (ok. 135 MB). Ten plik możesz teraz skopiować na dowolny komputer z Windowsem — Python ani inne biblioteki nie są tam potrzebne. Wystarczy dwukrotne kliknięcie. — Klucz API: gdzie wpisać ———————————————————————————————————————————— Dwa sposoby (program szuka w tej kolejności): 1. W oknie programu, sekcja "Wydajność i API" → pole "Google AI API Key". Klucz wpisany tutaj jest pamiętany tylko w bieżącej sesji — przy następnym uruchomieniu musisz wpisać ponownie. 2. Zmienna środowiskowa GOOGLE_API_KEY (preferowane). Polecenie w PowerShell ustawia ją na stałe dla bieżącego użytkownika: [Environment]::SetEnvironmentVariable("GOOGLE_API_KEY", "AIzaSy...", "User") Po tym MELANIA zawsze automatycznie odnajdzie klucz, nie musisz nic wpisywać w oknie. To rozwiązanie jednorazowe — ustawiasz raz, działa zawsze, nawet po przeniesieniu .exe na inny komputer (po ustawieniu ENV na tej maszynie). Jeśli klucza nie ma w żadnym z tych miejsc, program przy próbie uruchomienia tagowania pokaże okno błędu z instrukcją. — Czcionki (opcjonalne) —————————————————————————————————————————————— Interfejs używa trojga krojów typograficznych: EB Garamond (treść akademicka), IBM Plex Sans (UI), JetBrains Mono (logi). Jeśli nie masz ich zainstalowanych w systemie, program automatycznie sięgnie po Georgia / Segoe UI / Consolas — działa, ale wygląda mniej elegancko. Pobierz z Google Fonts (każdy zestaw to kilka MB): https://fonts.google.com/specimen/EB+Garamond https://fonts.google.com/specimen/IBM+Plex+Sans https://fonts.google.com/specimen/JetBrains+Mono Pobierz ZIP, rozpakuj, zaznacz wszystkie pliki .ttf w środku, kliknij prawym → Zainstaluj. — OCR dla skanowanych PDF (opcjonalne) ———————————————————————————————— Jeśli zamierzasz przetwarzać PDF-y będące skanami (np. starsze publikacje aktów), potrzebujesz silnika Tesseract OCR. To osobny program, nie biblioteka Pythona. Instalator dla Windowsa: https://github.com/UB-Mannheim/tesseract/wiki W instalatorze zaznacz "Polish" w sekcji "Additional language data" i pozwól instalatorowi dodać Tesseract do PATH. PIERWSZE URUCHOMIENIE ═══════════════════════════════════════════════════════════════════════ Okno programu jest podzielone na sekcje. Przejdź po nich od góry do dołu. — Sekcja I: Pliki wejściowe —————————————————————————————————————————— Dokument prawny Wybierz plik w formacie DOCX, PDF lub TXT. To dokument do otagowania (np. ustawa, kodeks, zbiór przepisów). Najlepiej działają dokumenty z czytelną strukturą "Art. N." — to jest wzorzec, po którym MELANIA rozpoznaje artykuły. Słownik Tu masz dwie opcje: (a) Klik "Wybierz..." — otwiera dialog systemowy, wskazujesz plik CSV lub XLSX z dysku. (b) Klik "↓ Pobierz z IURA" — otwiera modalne okno z listą słowników dostępnych na serwerze tezaurus.iura.uj.edu.pl. Wybierasz słownik, klikasz "Pobierz", plik trafia automatycznie w pole słownika. Słownik musi być w formacie SKOS — wymagana jest przynajmniej jedna z kolumn z nazwą hasła: prefLabel@pl, prefLabel_pl, haslo lub hasło. Im więcej kolumn dodatkowych (skos:definition, poziom, skos:broader, skos:related itd.), tym lepsza jakość tagowania. Katalog wynikowy Gdzie zapisać dokument otagowany i raport. Domyślnie to podkatalog "wyniki" przy programie. Możesz wybrać dowolny inny. — Sekcja II: Kontekstualizacja ——————————————————————————————————————— To pola opcjonalne, ale dla aktów historycznych mocno polepszają jakość tagowania. Wpisz krótkim językiem: Zakres czasowy Kiedy obowiązywał ten akt? np. "1933-1965", "II Rzeczpospolita", "okres pandektystyki" Zakres terytorialny Gdzie obowiązywał? np. "Polska", "zabór austriacki", "Królestwo Polskie", "Galicja" Zakres rzeczowy Czego dotyczy? np. "prawo zobowiązań", "prawo rodzinne", "postępowanie cywilne" Te informacje trafiają do prompt'u dla AI i pomagają jej rozumieć kontekst (np. że pojęcia łacińskie należy interpretować przez pryzmat ius commune, a nie współczesnego prawa). — Sekcja III: Model AI ——————————————————————————————————————————————— Wybór modelu Gemini wpływa na jakość, szybkość i koszt: Gemini 3.1 Pro Najwyższa jakość. Dla dokumentów trudnych semantycznie, słowników z subtelnymi rozróżnieniami pojęciowymi, edycji wymagających najwyższej staranności. Wolniejszy. Drożej, jeśli używasz płatnego planu (na Free Tier nadal $0.00). Gemini 3.1 Flash Domyślnie zalecany. Dobry balans jakości i szybkości. Dla większości zastosowań wystarczający. Gemini 3.1 Flash-Lite Najszybszy i najtańszy. Dla prostych słowników (kilkadziesiąt-kilkaset haseł), szybkich eksperymentów, wstępnego skanowania. Tryb THINKING Tylko dla Pro. Włącza "głębsze rozumowanie" — model najpierw zastanawia się nad zadaniem, potem odpowiada. Wyraźnie podnosi jakość dla zadań subtelnych, ale wydłuża czas 2-3-krotnie. Próg pewny Domyślnie 90%. Powyżej tego progu tag trafia do dokumentu bez uwag. To znaczy: AI jest pewna, że to dobrze przypisane hasło. Próg minimalny Domyślnie 85%. Między tymi progami tag wymaga uzasadnienia (AI dopisuje krótkie wyjaśnienie, czemu wybrała to hasło). Poniżej progu minimalnego — tag jest odrzucany. — Sekcja IV: Wydajność i API ——————————————————————————————————————————— Rozmiar paczki Ile artykułów MELANIA wysyła do AI w jednym zapytaniu. Domyślnie 3. Większy = mniej zapytań (oszczędność limitu Free Tier), ale odpowiedź dłuższa. Dla bardzo długich artykułów zmniejsz do 2. Równoległe wątki Ile paczek może być przetwarzanych jednocześnie. Domyślnie 4. Większa równoległość = szybciej. Ale na Free Tier limit to 15 zapytań/minutę, więc 4-6 wątków to maksimum sensowne. Dla sekwencyjnego przetwarzania (debug) ustaw 1. Google AI API Key Twój klucz z Google AI Studio (patrz wyżej, sekcja "Klucz API: gdzie wpisać"). Pole maskuje znaki (***). Pusty oznacza, że program szuka klucza w zmiennej środowiskowej GOOGLE_API_KEY. Kliknij ▸ STARTUJ TAGOWANIE. W oknie logów na dole zobaczysz postęp — które paczki są przetwarzane, jakie tagi AI proponuje, ile czasu zajmuje. Jeśli z jakiegokolwiek powodu chcesz przerwać, kliknij ■ PRZERWIJ — program zatrzyma się po dokończeniu aktualnej paczki. Po zakończeniu w katalogu wynikowym pojawią się dwa pliki: [nazwa_dokumentu]_[HHMM].docx — dokument z tagami [nazwa_dokumentu]_[HHMM]_RAPORT.txt — raport tekstowy gdzie HHMM to godzina rozpoczęcia (1530 oznacza 15:30) — żeby przy wielokrotnym uruchamianiu pliki się nie nadpisywały. POBIERANIE SŁOWNIKÓW Z SERWERA IURA ═══════════════════════════════════════════════════════════════════════ Wersja 2.5 wprowadziła możliwość pobierania słowników wprost z serwera IURA Explorer (https://tezaurus.iura.uj.edu.pl) — bez wychodzenia z programu i bez ręcznego ściągania plików. Jak to działa: 1. W sekcji "Pliki wejściowe", przy polu "Słownik kontrolowany", kliknij przycisk "↓ Pobierz z IURA" (obok "Wybierz..."). 2. Otwiera się modalne okno z listą wszystkich słowników dostępnych na serwerze IURA. Każda pozycja pokazuje tytuł, wersję, autorów i krótki opis. 3. Zaznacz słownik na liście. Pod listą zobaczysz szczegóły — kto opracował, co dokładnie obejmuje. 4. Kliknij "↓ Pobierz" (albo zrób podwójne kliknięcie na pozycji). Pojawi się pasek postępu z kilobajtami i procentem. 5. Po pobraniu plik xlsx trafia do katalogu tymczasowego, a jego ścieżka automatycznie wskakuje w polu "Słownik" w głównym oknie. Możesz od razu przejść do uruchomienia tagowania. Słowniki na IURA Explorer mają zwykle 1000-3000 haseł z bogatymi metadanymi SKOS (definicje, scopeNote z historycznym kontekstem, poziomy hierarchii L1-L9, źródła kodyfikacyjne). Są zoptymalizowane pod MELANIĘ — żadna konwersja nie jest potrzebna. Jeśli serwer IURA jest niedostępny (np. brak Internetu, prace serwisowe), dialog pokaże komunikat o błędzie — możesz wtedy skorzystać ze starszego sposobu (wybór pliku z dysku) albo spróbować za chwilę. FORMAT SŁOWNIKA — CO MUSI BYĆ W ŚRODKU ═══════════════════════════════════════════════════════════════════════ MELANIA przyjmuje słowniki w trzech formatach: .csv (plain text z separatorem), .xlsx (Excel 2007+, wymaga biblioteki openpyxl), .xls (starszy Excel, wymaga xlrd). — Kolumna główna (wymagana) —————————————————————————————————————————— W słowniku musi być przynajmniej jedna z kolumn (w kolejności preferencji): prefLabel@pl format SKOS współczesny, ze znakiem @ prefLabel_pl format SKOS starszy, z podkreślnikiem haslo format tradycyjny (bez polskich znaków) hasło format tradycyjny (z polskimi znakami) Wystarczy jedna z tych — MELANIA autodetektuje i traktuje jako "hasło główne". Każdy wiersz słownika = jedno hasło. — Kolumny dodatkowe (im więcej, tym lepiej) —————————————————————————— KLUCZOWE — najmocniej wpływają na jakość tagowania: skos:definition Zwięzła definicja pojęcia (1-3 zdania). AI porównuje treść przepisu z definicją. Najmocniejszy sygnał trafienia. skos:scopeNote Szczegółowy opis zakresu pojęcia, z historią, kontekstem, ewolucją. Często wielokrotnie dłuższy niż definition. MELANIA aktywnie wykorzystuje przy tagowaniu dokumentów historycznych. poziom Pozycja w hierarchii: L1 (najogólniejsze) do L9 i niżej (najszczegółowsze). Zasada: hasło niższego poziomu zwykle wyklucza wyższe (gdy mówisz "dziedziczenie małżonka", nie musisz dodawać "prawo spadkowe" — to jest objęte). MELANIA ma algorytmiczny walidator hierarchii, który flaguje wątpliwe współwystąpienia. źródło_kodyfikacji Wymienia akty normatywne, w których pojęcie występuje (np. "Code civil 1804; ABGB 1811; KC 1964 art. X"). Pomaga AI datować pojęcia do konkretnych epok i kodyfikacji. POMOCNICZE — przyzwoita poprawa jakości: altLabel / altLabel_pl Synonimy hasła głównego. AI rozpoznaje synonimy w tekście przepisu i mapuje na hasło główne. skos:broader Hasło nadrzędne — kontekst hierarchiczny. skos:related Hasła powiązane semantycznie. Dla każdego trafionego hasła AI sprawdza related i może dodać te, co pasują. skos:Collection Dziedzina prawa — pomaga grupować tematycznie. skos:example Przykłady użycia — porównanie sytuacji z przepisu z przykładami zwiększa confidence. skos:narrower Hasła podrzędne — AI ich aktywnie szuka. prefLabel_en / Tłumaczenie angielskie / oryginalny prefLabel_orig + termin w innym języku + nazwa języka. język_orig MELANIA łączy te dwie ostatnie w syntetyczne oznaczenie ("Vermögen / biens" + "niemiecki; francuski" → "Vermögen@de biens@fr"). Dzięki temu AI rozpoznaje terminy łacińskie, niemieckie, francuskie w kontekście. skos:exactMatch / URI do Wikidata, Biblioteki Narodowej, skos:closeMatch EuroVoc itp. Nie wpływa bezpośrednio na tagowanie, ale pokazuje AI zakres pojęcia w systemach zewnętrznych. mapping_uwagi Komentarze do mapowań — dodatkowy kontekst dla AI. — Kolumny, których AI nie zobaczy ———————————————————————————————————— Następujące kolumny (jeśli istnieją w słowniku) są POMIJANE przy wysyłaniu do AI — to ślady procesu mapowania, nieistotne dla tagowania: kandydat_wikidata_uri / label / desc kandydat_bn_uri / label / desc mapper_potwierdzil mapper_alternatywa status_weryfikacji CO ZOBACZYSZ W WYNIKACH ═══════════════════════════════════════════════════════════════════════ — Plik DOCX —————————————————————————————————————————————————————————— Pełna typografia polska — PT Serif 12pt, justowanie, kontrola wdów, sierot, bękartów i szewców (czyli pojedynczych linii na początku/ końcu strony, słów oderwanych itd.). Struktura zachowana: nagłówki artykułów wycentrowane i pogrubione, paragrafy (§) wyodrębnione, jednostki systematyzacyjne (CZĘŚĆ, KSIĘGA, TYTUŁ, DZIAŁ, Rozdział, ODDZIAŁ) wyśrodkowane i pogrubione na poziomie tytułowym. Pod treścią każdego artykułu pojawia się linia z tagami: [hasła: dziedziczenie małżonka (96%), spadkobierca (94%), testament (82% [!])] [!] testament: Przepis wymienia testament jako jedno z możliwych źródeł powołania, ale głównie reguluje dziedziczenie ustawowe. Tag z procentem ≥ próg pewny (domyślnie 90%) trafia bez uwag. Tag oznaczony [!] ma confidence między progami i jest opatrzony uzasadnieniem. Pod artykułem pojawiają się też ostrzeżenia, jeśli artykuł był tagowany bez pełnego kontekstu (np. na początku dokumentu nie ma 3 wcześniejszych artykułów). — Plik raportu ——————————————————————————————————————————————————————— Plain text, kilkanaście kilobajtów, ze szczegółowymi statystykami: STATYSTYKI TAGOWANIA: Przebieg 1: 1147 tagów Przebieg 2: 1586 tagów Zmiany w weryfikacji: 18 artykułów Średnia confidence: 96.8% KOSZTY I TOKENY: Tokeny input (total): 16,224,325 → Standard tokens: 4,524,325 (pełna cena) → Cached tokens: 11,700,000 (90% zniżka) Tokeny output: 132,978 KOSZT TEORETYCZNY (gdyby API było płatne): Z CACHE: $0.45 USD BEZ CACHE: $1.25 USD Oszczędność cache: $0.80 USD = 63.9% FAKTYCZNY KOSZT: $0.00 USD (FREE TIER) WALIDACJA HIERARCHII SKOS (post-check): Liczba artykułów z potencjalnym naruszeniem: 3 Art. 15: Współwystępują hasła różnych poziomów hierarchii: szczegółowe (L7: dziedziczenie testamentowe własnoręczne) i ogólne (L1: prawo cywilne). Sprawdź czy spełniony jest wyjątek. ARTYKUŁY DO WERYFIKACJI: Art. 24: • testament (82%) — uzasadnienie... • zachowek (87%) — uzasadnienie... Po przetworzeniu otwórz raport i przejrzyj dwie rzeczy: 1. Listę "Artykuły do weryfikacji" — tagi z confidence poniżej progu pewnego. AI sama nie była pewna, więc to są kandydaci do ręcznej oceny. 2. Listę "Walidacja hierarchii" — artykuły, gdzie współwystępują hasła różnych poziomów hierarchii. Walidator nie potrafi sam ocenić, czy to faktyczne naruszenie zasady (lepsze hasło wyklucza ogólniejsze) czy uprawniony wyjątek (artykuł reguluje całą dziedzinę albo kilka aspektów naraz). Końcowa decyzja należy do badacza. MODELE I PRICING ═══════════════════════════════════════════════════════════════════════ Input Output Cache Read per 1M per 1M per 1M ───────────────────────────────────────────────────────────────────── Gemini 3.1 Pro ≤200k tokenów $2.00 $12.00 $0.20 >200k tokenów $4.00 $18.00 $0.40 Gemini 3.1 Flash $0.60 * $3.60 * $0.06 * Gemini 3.1 Lite $0.25 $1.50 $0.025 * * — wartości szacunkowe do czasu publikacji oficjalnego cennika Google. W pliku źródłowym programu jest komentarz, gdzie zaktualizować. Pro przełącza taryfę przy 200 000 tokenów kontekstu — gdy słownik ma 2000+ haseł z bogatymi opisami, system instruction może przekroczyć ten próg i wtedy każde zapytanie kosztuje drożej. Mechanizm Context Caching to ratuje: pierwsze zapytanie kosztuje pełną cenę, kolejne 90% taniej. Pamiętaj — Free Tier daje 15 zapytań/minutę i 1500/dziennie. Przy typowych zadaniach nie zapłacisz nic. Liczby kosztu w raporcie są "co by było, gdyby" — czysta informacja. ROZWIĄZYWANIE PROBLEMÓW ═══════════════════════════════════════════════════════════════════════ "Brak klucza API" — okno błędu przy próbie uruchomienia tagowania. → Wpisz klucz w polu "Google AI API Key" w sekcji IV ("Wydajność i API") ALBO ustaw zmienną środowiskową GOOGLE_API_KEY (patrz sekcja "Klucz API: gdzie wpisać"). Bez klucza program się nie uruchomi — to celowe, wersja 2.5 wymaga własnego klucza użytkownika. Program nie startuje, okno cmd znika natychmiast. → Otwórz cmd ręcznie, przejdź cd do katalogu z .exe, uruchom z linii poleceń — zobaczysz konkretny komunikat błędu. "Python nie jest rozpoznawalny jako polecenie". → Python nie jest w PATH. Pobierz z python.org, w instalatorze zaznacz "Add Python to PATH". Po zainstalowaniu zamknij i otwórz cmd ponownie. "Plik .xlsx wymaga biblioteki openpyxl". → Zainstaluj: pip install openpyxl. Albo zapisz słownik jako CSV (w Excelu: Plik → Zapisz jako → CSV UTF-8). "ModuleNotFoundError: customtkinter" (albo inna biblioteka). → Brakuje zależności. Uruchom pip install . Jeśli używasz .exe, przekompiluj przez build_2_5_v2.bat. "Invalid API key" / "API key not valid". → Klucz jest zły albo wygasł. Wygeneruj nowy na aistudio.google.com/ apikey. Format: zaczyna się od AIzaSy. "Rate limit exceeded" (kod 429). → Przekroczyłeś 15 zapytań/minutę Free Tier. Zmniejsz "Równoległe wątki" w sekcji IV do 2-3. Program normalnie sam pilnuje limitu, ale czasami zapytania nakładają się tuż przed restartem licznika. "Nie udało się pobrać listy słowników z serwera IURA". → Sprawdź połączenie internetowe — fetcher IURA wymaga sieci. Jeśli sieć działa, serwer IURA może być chwilowo niedostępny (prace serwisowe). Spróbuj za chwilę albo wybierz słownik z dysku przez przycisk "Wybierz...". "Manifest.json nie zawiera klucza dictionaries". → Serwer IURA zwrócił nieoczekiwaną strukturę. Najprawdopodobniej trwa aktualizacja po stronie serwera. Spróbuj za godzinę albo pobierz słownik ręcznie ze strony tezaurus.iura.uj.edu.pl i wskaż lokalnie. Słownik się wczytuje, ale 0 haseł. → Plik nie ma kolumny z hasłami w żadnej z rozpoznawanych nazw (prefLabel@pl, prefLabel_pl, haslo, hasło). Otwórz w Excelu / Notatniku, sprawdź nazwy kolumn. PDF się nie otwiera albo wczytuje pusty. → PDF jest skanem (obrazem), nie tekstem. Zainstaluj Tesseract OCR (patrz wyżej) — wtedy MELANIA automatycznie wykryje brak tekstu i odpali OCR. Alternatywnie: skonwertuj PDF na DOCX przez Adobe Acrobat albo dowolny online OCR. Pro z trybem thinking działa bardzo wolno. → To normalne. Thinking dodaje wewnętrzne "rozumowanie" przed odpowiedzią. Dla regularnej pracy Flash jest 2-3× szybszy i prawie zawsze wystarczy. Pro + thinking zostaw na dokumenty szczególnie trudne semantycznie. Antywirus blokuje .exe. → PyInstaller-owe binaria bywają fałszywie wykrywane jako podejrzane. Dodaj wyjątek dla folderu albo pojedynczego pliku. To znany problem branżowy. GUI wygląda mniej elegancko niż na screenshotach. → Brakuje którejś z czcionek IURA Explorer (EB Garamond, IBM Plex Sans, JetBrains Mono). Zainstaluj systemowo (patrz sekcja "Czcionki"). Program nadal działa, ale tk fallbackuje na Georgia / Segoe UI / Consolas. Pierwsza paczka trwa bardzo długo (kilka minut), kolejne szybko. → To normalne. Pierwsze zapytanie buduje cache z system instruction (cały słownik) — to musi się zindeksować po stronie Google. Kolejne zapytania korzystają z gotowego cache i są dużo szybsze. LICENCJA I CYTOWANIE ═══════════════════════════════════════════════════════════════════════ Copyright © 2026 Jakob Maziarz | Iura — Źródła Prawa Dawnego All Rights Reserved. Program przeznaczony do celów badawczych i edukacyjnych. Jeśli używasz MELANII w pracy naukowej i wynik znalazł się w publikacji, zacytuj: Maziarz J. (2026). MELANIA: Moduł Eksperckiego Labelowania Aktów Naukową Inteligencją Artyficjalną, wersja 2.5. Critical Heritage Studies Hub, Uniwersytet Jagielloński. KONTAKT ═══════════════════════════════════════════════════════════════════════ Jakob Maziarz Uniwersytet Jagielloński, Kraków j.maziarz@uj.edu.pl Projekt zrealizowany w ramach Critical Heritage Studies Hub (https://crihestu.id.uj.edu.pl/start) przy wsparciu Programu Strategicznego Inicjatywa Doskonałości w UJ (https://id.uj.edu.pl/). Powiązany serwis: IURA Explorer — eksplorator słowników SKOS (https://tezaurus.iura.uj.edu.pl) — narzędzie do przeglądania i wizualizacji słowników kontrolowanych, z którymi MELANIA pracuje. Wersja 2.5 MELANII umożliwia pobieranie tych słowników wprost z poziomu programu. ═══════════════════════════════════════════════════════════════════════ ❦ ═══════════════════════════════════════════════════════════════════════