Przejdź do treści

Dokumentacja techniczna

Jak działa PRAWDOWID

PRAWDOWID sprawdza twierdzenia w źródłach: wyciąga z materiału atomowe fakty, szuka dowodów i oznacza, gdzie wiedza się kończy. Werdykt nie jest opinią modelu.

Wejście
Tekst, link i obraz
Kontrakt
POST /verify
Status
MVP

01 - Zasada

Werdykt ze źródeł, nie z modelu

Model językowy służy do odczytania materiału i rozbicia go na sprawdzalne twierdzenia. Nie decyduje sam, czy coś jest prawdą. Werdykt powstaje z dowodów: dokumentów urzędowych, materiałów fact-checkingowych i źródeł kontekstowych.

Gdy dowody są zbyt słabe albo sprzeczne, system nie zgaduje. Zwraca werdykt insufficient_evidence albo not_verifiable i pokazuje ograniczenia. To celowe zachowanie, nie błąd.

02 - Architektura

Stos technologiczny

Warstwy są rozdzielone: frontend nie zna wewnętrznego kontraktu backendu, a backend nie zależy od interfejsu WWW.

Frontend

  • Next.js 16 (App Router)
  • React 19
  • TypeScript
  • Tailwind CSS 3
  • daisyUI 4

Backend

  • Bun
  • Elysia
  • TypeScript
  • Swagger pod /docs

Warstwa AI

  • OpenRouter
  • DeepSeek v4.1 Flash - ekstrakcja (reasoning OFF)
  • Jev / RLCD - bramka i dopasowanie twierdzeń
  • bge-m3 - embeddingi (PL)
  • DeepSeek-OCR - tekst ze zdjęć

Dane i research

  • Lokalny korpus: 135 źródeł, 48 hostów
  • Google Fact Check Tools
  • Wikipedia - fallback
  • Snapshot EUvsDisinfo

Przechowywanie

  • Pliki JSON w data/ - domyślnie
  • MySQL - opcjonalnie
  • Redis - planowany, jeszcze niewdrożony

03 - Pipeline

Przepływ żądania

Od wejścia użytkownika do werdyktu w interfejsie. Każdy etap ma jasny kontrakt i może zakończyć się jawnym ograniczeniem.

  1. 01

    Wejście

    Tekst, publiczny link lub zdjęcie z tekstem trafia do wewnętrznego API frontendu. Kanał jest oznaczany jako web.

  2. 02

    OCR

    Zdjęcie PNG, JPG lub WebP jest odczytywane przez DeepSeek-OCR. Obraz nie jest niezależnie weryfikowany - dalsza analiza pracuje na odczytanym tekście.

  3. 03

    Bramka Jev

    Ocena polityczna materiału jest raportowana, ale nie blokuje weryfikacji. Bramka służy też do dopasowania twierdzeń.

  4. 04

    Ekstrakcja

    DeepSeek v4.1 Flash wyciąga fakty i rozbija je na atomowe twierdzenia w układzie SPO: podmiot, orzeczenie, obiekt.

  5. 05

    Embeddingi i cache

    bge-m3 liczy wektory i zawęża listę kandydatów. Cache sprawdza klucz dokładny, dopasowanie Jev i wpis czasowy.

  6. 06

    Research i dowody

    System przeszukuje lokalny korpus, Google Fact Check Tools, Wikipedię oraz snapshot EUvsDisinfo i zbiera dowody.

  7. 07

    VerifyResponse

    Powstaje odpowiedź z werdyktami twierdzeń, dowodami, ograniczeniami, kosztem i czasem przetwarzania.

  8. 08

    API backendu

    Kontrakt wystawia POST /verify. WWW i API korzystają z tej samej funkcji pipeline'u.

  9. 09

    Proxy frontendu

    Przeglądarka woła własne /api/analyze. Trasa serwerowa Next.js przekazuje żądanie do backendu i mapuje odpowiedź.

  10. 10

    Interfejs wyniku

    Frontend pokazuje werdykt, poziom pewności, ustalenia i linki do źródeł w sekcji „Wynik analizy”.

04 - Kontrakt

POST /verify

Backend przyjmuje tekst, link albo zdjęcie i zwraca ujednoliconą odpowiedź. Frontend nie woła backendu bezpośrednio - korzysta z własnego proxy.

Żądanie - pola wejściowe

Pola wejściowe kontraktu POST /verify
PoleTypOpis
text?stringTreść do sprawdzenia. Wysyłana zamiast linku.
url?stringPubliczny adres http/https artykułu, posta lub wideo.
channel?"web" | "discord" | "api" | "sms"Kanał źródłowy żądania. Frontend wysyła „web”.
image?string (base64)Zdjęcie jako base64 lub data URI. Backend odczytuje tekst przez OCR; limit to 8 MB po zdekodowaniu.
POST /verify
Content-Type: application/json

{ "text": "…", "channel": "web" }

Odpowiedź - pola VerifyResponse

status
ok | error | needs_clarification | out_of_scopeWynik samego żądania, nie werdykt merytoryczny.
summary
stringKrótkie podsumowanie w języku polskim.
claims[]
ClaimVerdict[]Twierdzenia z werdyktem, pewnością, siłą dowodów, uzasadnieniem i źródłami.
limitations[]
string[]Jawne ograniczenia analizy i brakujących danych.
input, language, sessionId
metadataTyp i podgląd wejścia, język odpowiedzi oraz identyfikator sesji.
timingMs, costUsd, costBreakdown?
number / objectCzas i szacowany koszt. costBreakdown dzieli koszt na etapy, jeśli jest dostępny.
models[], sourcesUsed[]
string[]Użyte modele oraz źródła wykorzystane w analizie.
disclaimer
stringZastrzeżenie dołączane do odpowiedzi.

Pozostałe endpointy backendu

Endpointy wystawiane przez backend PRAWDOWID
MetodaŚcieżkaOpis
POST/verifyWeryfikacja tekstu, linku lub obrazu.
GET/healthStatus procesu i wersja.
GET/metricsLiczniki, p50/p95 i średni koszt.
GET/casesNierozstrzygnięte sprawy moderacyjne.
POST/cases/:id/ackModerator bierze sprawę.
GET/docsSwagger UI.
GET/Wbudowany interfejs WWW backendu.

Klasa werdyktu twierdzenia

  • Potwierdzone confirmed

    Dowody wspierają twierdzenie w podanym kontekście czasowym.

  • Fałszywe false

    Dowody przeczą twierdzeniu.

  • Wprowadzające w błąd misleading

    Element może być prawdziwy, ale kontekst, zestawienie lub wniosek zniekształca obraz.

  • Brak wystarczających dowodów insufficient_evidence

    System nie ma dość materiału, żeby rozstrzygnąć, i wstrzymuje się od werdyktu.

  • Nie podlega weryfikacji not_verifiable

    Twierdzenie nie jest zdaniem faktograficznym, które da się sprawdzić w źródłach.

Status żądania to nie werdykt

error i needs_clarification opisują problem z żądaniem, a nie prawdziwość materiału. Frontend odrzuca każdy status inny niż ok i pokazuje błąd zamiast werdyktu.

Pola pojedynczego twierdzenia: id, claim · verdict · confidence (0..1) · strength (high / medium / low) · reasoning · evidence[] · limitations[] · asOf · cached.

Proxy frontendu

Przeglądarka wysyła żądanie do /api/analyze. Trasa serwerowa Next.js woła POST /verify pod adresem BACKEND_API_URL i mapuje odpowiedź na mniejszy kontrakt UI.

Dzięki temu backend nie musi mieć CORS, a jego adres nie trafia do przeglądarki.

05 - Zakres

Co można sprawdzić

Zakres MVP jest jawny. Lepiej pokazać ograniczenie niż zasymulować analizę, której backend nie wykonuje.

Obsługiwane typy materiałów wejściowych w backendzie i frontendzie
WejścieBackend /verifyFrontendUwagi
TekstTakTakWklejony post, cytat lub fragment artykułu.
LinkTakTakPubliczny adres http/https.
Obraz PNG / JPG / WebPTak (OCR)Tak, do 8 MBTekst ze zdjęcia jest odczytywany przez OCR i trafia do dalszej analizy.
Wideo MP4Nie przez /verifyNieBrak transkrypcji wpiętej do endpointu. Frontend nie oferuje wideo, a proxy zwraca błąd 415.

Zakładka „Plik” przyjmuje PNG, JPG i WebP do 8 MB. Tekst ze zdjęcia jest odczytywany przez backendowy OCR. Moduł ASR istnieje w kodzie backendu, ale nie jest wpięty do /verify, dlatego wideo nie jest obsługiwane przez API ani przez frontend.

06 - Ekonomia

Koszt sprawdzenia

Wielkości pochodzą z szacunku backendu dla typowego tekstu lub linku. Zależą od długości materiału, liczby twierdzeń i dostępności researchu - to nie jest rozliczenie.

Jedno sprawdzenie

$0.0003-$0.001

Gate, ekstrakcja i embeddingi dla tekstu lub linku. Research z Google jest darmowy w ramach limitu. OCR obrazów korzysta z osobnej usługi i nie jest wliczony w ten szacunek.

1000 sprawdzeń

$0.3-$1

Szacunek rzędu wielkości. Rzeczywisty koszt zależy od ruchu i długości materiałów.

Podział kosztu według etapów

  • 01

    Ekstrakcja

    DeepSeek - tokeny wejścia i wyjścia

  • 02

    Bramka i matching

    Jev / RLCD - zużycie z odpowiedzi

  • 03

    Embeddingi

    bge-m3 - szacunek na podstawie znaków

  • 04

    Research

    Google Fact Check, Wikipedia, EUvsDisinfo

Odpowiedź może zawierać costBreakdown z podziałem na etapy. Wartości są szacowane, a nie fakturowane.

07 - Zakres odpowiedzialności

Co system zapewnia - i czego nie zapewnia

Zapewnia

  • Cytowanie zamiast opinii

    Twierdzenia rozstrzygnięte dostają dowody: tytuł, wydawcę, datę, URL, fragment i relację (wspiera, przeczy, kontekst). Brak dowodów kończy się jawnym insufficient_evidence.

  • Kontekst czasowy

    Wpisy cache mają validFrom i validUntil, a matcher filtruje je po asOf. Ten sam cytat może mieć różny werdykt w różnych oknach czasu.

  • Pętla informacji

    Twierdzenia bez rozstrzygnięcia trafiają do spraw moderacyjnych. Podobne pytanie jest dołączane do istniejącej sprawy, a przy trzecim zgłoszeniu system zapisuje alert.

  • Jasny status i limity

    Błąd techniczny i prośba o doprecyzowanie to osobne statusy, nigdy werdykt. Rate limit działa w pamięci procesu; trwały hot-cache w Redisie i kolejka rechecków nie są jeszcze wdrożone.

Ograniczenia

  • Brak ASR

    Obrazy są odczytywane przez OCR, ale wideo (MP4) nie ma transkrypcji wpiętej do /verify. Frontend nie oferuje wideo, a proxy odrzuca taki plik czytelnym komunikatem.

  • Pokrycie korpusu

    Lokalny korpus liczy 135 źródeł w 48 hostach. To nie jest pełny internet; brak dowodu oznacza insufficient_evidence, nie fałsz.

  • Budżet researchu

    Liczba zapytań i twierdzeń w jednej analizie jest ograniczona kosztem i czasem. Szerszy research może wymagać więcej pracy.

  • Aktualność i recheck

    Cache ma okna ważności, ale automatyczny recheck po stronie schedulera nie jest jeszcze wpięty.

  • Nie jest wyrokiem sądu

    System pokazuje, co wynika z dostępnych źródeł, i oznacza miejsca, w których kończy się jego wiedza. Decyzję zawsze warto potwierdzić w linkach.

08 - Pomiar

Statystyki i wyniki ewaluacji

Ta sekcja jest zarezerwowana na zmierzone wyniki. Nie publikujemy tutaj liczb, dopóki nie zostaną rzetelnie policzone na stałym zbiorze testowym.

Skuteczność werdyktów

W przygotowaniu

Pokrycie źródłowe

W przygotowaniu

Czas odpowiedzi

W przygotowaniu

Koszt na sprawdzenie

W przygotowaniu

Dokładne metryki - m.in. skuteczność werdyktów, pokrycie źródeł, opóźnienie i koszt jednostkowy - zostaną dostarczone przez agenta ewaluacji po zakończeniu pomiarów.