Inicjalizacja repozytorium: koncepcja platformy AdReactions + specyfikacja AI

Zawartość: - Koncepcja 0.1 oraz rozszerzona Koncepcja 0.2 (model domenowy, architektura, mapowanie cel→metryki→usługi AI, wymienialność modeli, model danych) - Katalog 15 celów analiz kognitywnych - Specyfikacja procesu AI + opis procesów źródłowych - Pytania do koncepcji - Materiały źródłowe: info.md, n8n.json Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-24 22:03:32 +02:00 · 2026-06-24 22:03:32 +02:00 · cd292e3198
commit cd292e3198
9 changed files with 3821 additions and 0 deletions
--- a/.gitignore
+++ b/.gitignore
@ -0,0 +1 @@
 .DS_Store
--- a/0.1.md
+++ b/0.1.md
@ -0,0 +1,428 @@
 # AdReactions – MVP 1.0 [KM]
 ## Projekt
 AdReactions to aplikacja SaaS, która pozwala na przeprowadzenie eksperymentów (predykcji)  postrzegania (Eye Tracking) emocji (Facial Coding) z zastosowaniem modeli AI, w tym również modelu AI ASM PNS. Eksperymenty prowadzone są przez klientów na wczytanych reklamach, banerach i materiałach marketingowych.
 ## Stack technologiczny
 - Front-end: React / shadcn/ui + tailwind
 - Back-end: Node.js
 - Data base, Storage, Auth: Supabase
 ## Wersja językowe
 Obsługiwane języki w MVP 1.0 to:
 - Polski
 - Angielski
 W kolejnych wersjach planowane jest dodanie innych wersji językowych.
 ## Struktura organizacji, ról, uprawnień
 - Organizacja:
    - Posiada Administratora
    - Posiada Użytkowników
    - Posiada Gości
    - Posiada Projekty
 - Role
    - Super administrator - posiada dostęp do panelu administracyjnego, w którym może zarządzać organizacjami, użytkownikami, modelami AI. Super administrator może przejść do każdej z organizacji w systemie. Jeśli Super administrator wchodzi do organizacji to może w niej poruszać się tak jak Administrator.
    - Administrator - Administrator organizacji powstaje podczas rejestracji Organizacji. Prawa administratora mogą zostać przekazane do innego użytkownika przez administratora.
    - Użytkownik - Każdy użytkownik w platformie posiada własne niezależne konto.
 - Uprawnienia
    - Administrator - Posiada uprawnienia do każdego projektu, rozliczeń, planów i ustawień. Może tworzyć nowe projekty i eksperymenty bez ograniczeń.
    - Użytkownik - może posiadać uprawnienia:
        - Tworzenia nowych projektów
        - Przeglądania wszystkich projektów
        - Edytowania wszystkich projektów
        - Usuwania wszystkich projektów
        - Zapraszanie użytkowników do wszystkich projektów
        - Użytkownik może również otrzymać uprawnienia w ramach projektu takie jak:
            - Usuwanie, edycja i zapraszanie użytkowników
            - Edycja i zapraszanie użytkowników
            - Przeglądanie
 ## Struktura modułów platformy
 - Panel administracyjny
    - Dostęp do panelu możliwy tylko dla Super administratorów.
    - Zarządzanie całą aplikacją
        - Zarządzanie wszystkimi organizacjami
        - Zarządzanie wszystkimi użytkownikami
    - Modele AI
        - Zarządzanie konfiguracją modeli AI
 - Panel użytkownika - Dostęp dla użytkownika po rejestracji / zalogowaniu. Z tego miejsca użytkownik może:
    - przejść do wybranej organizacji
    - dodać nową organizację (może dodać tylko jedną nową organizację)
    - zmienić dane
    - zmienić email
    - zmienić hasło.
 - Panel organizacji - Panel dla Administratora i użytkowników. Panel zawiera:
    - Projekty organizacji
        - Eksperymenty projektu
    - Galeria kreacji
 ## Struktura UX
 - Topbar
    - Wybór organizacji
    - Wyszukiwarka - Pozwala na wyszukiwanie projektów, kreacji, eksperymentów.
 - Sitebar
    - Menu panelu
    - Menu użytkownika
    - Sitebar ukrywa się w trybie mobilnym
 - Workspace
    - Obszar roboczy
 ---
 ## Panel **organizacji**
 ### Sitebar
 - Dashboard
 - Projekty
 - Galeria
 ### **Dashboard**
 Strona służy jako szybki zbiorczy podgląd do podstawowych rezultatów. Na tej stronie powinny pojawić się pola z podstawowymi KPI:
 - Galeria (liczba kreacji w bazie danych)
 - Projekty (liczba projektów)
 - Eksperymenty (liczba eksperymentów)
 Pod KPI powinny być przyciski:
 - Dodaj kreację do Galerii
 - Utwórz nowy Projekt
 - Przejdź do ostatniego eksperymentu
 Pod przyciskami powinna znaleźć się lista Projektów z możliwością przejścia do danego projektu.
 ## **Galeria**
 Strona jest dedykowana do zarządzania galerią kreacji Organizacji.
 Przycisk u góry: Dodaj kreację do Galerii (przestrzeń ładowania pliku krecji do Galerii).
 Poniżej: Kreacje ostatnio dodane do Galerii (kafelki kreacji).
 Poniżej: Galeria  wszystkich kreacji  i w razie potrzeby przewijanych slajderem ilustrującym wszystkie kreacje dodane do Galerii.
 Po kliknięciu w daną kreację zostanie ona powiększona w drawer po prawej stronie. Drawer grafiki zaprezentuje:
 - Powiększoną grafikę
 - Listę eksperymentów wraz z informacją o projekcie, w których była ta grafika stosowana. Użytkownik z tego poziomu może przejść do danego eksperymentu i/lub projektu.
 ## **Projekty**
 Strona jest dedykowana do zarządzania projektami.
 Na tej stronie widzimy :
 - Na górze:
 - Przycisk: Nowy projekt
 Pod nim listę z nazwami projektów, informacją czy były to projekty ET czy FT, czy ET+FT.
 ### Panel projektu
 Użytkownik na tej stronie zarządza projektem. Może je przeglądać, weryfikować konfigurację eksperymentu. Może usuwać całe projekty, usuwać poszczególne eksperymenty oraz udostępniać projekty innym użytkownikom.
 ### **Nowy projekt**
 W ramach projektu można realizować wiele eksperymentów.
 Każdy projekt ma szereg powiązanych z nim elementów tj:
 - **Nazwa projektu** - nadawana przez właściciela projektu.
 - **Galeria  projektu -**  Galeria kreacji dodanych do danego projektu. Mogą to być grafiki pochodzące z aktualnej Galerii organizacji lub tylko Projektu. W ramach 1 eksperymentu można analizować maksymalnie 3 kreacje / grafiki (A, B i C). Ilość załączanych grafik jest ograniczona limitem miejsca na dysku stosownym dla danej subskrypcji. Można tę przestrzeń poszerzać za określoną ilość punktów / coinów zgodnie o aktualnym cennikiem przestrzeni dyskowej.
 ### Projekt
 **Galeria eksperymentów:**
 To galeria wszystkich eksperymentów zrealizowanych w ramach projektu ze wskazaniem ich kluczowych parametrów tj Rodzaj technologii (ET, FC, ET+FC, Rodzaj testu A, AB, ABC..). Nazwę użytkownika, który przygotował eksperyment.
 ### **Nowy eksperyment**
 Każdy zakładany eksperyment musi zostać odpowiednio skonfigurowany do przeprowadzenia analizy predykcyjnej odpowiadające zamierzeniom użytkownika. Użytkownik w procesie konfiguracji określa podstawowe parametry badania.
 #### Krok 1 - Cel i grupa docelowa
 **Cel:** Opisowy lub z listy np. maksymalizacja uwagi na CTA, Minimalizacja frustracji, Skrócenie czasu dotarcia do wybranego AOI, etc.
 **Słowniki celów predefiniowanych:**
 1. Która kreacja lepiej sprzedaje?
 2. Czy CTA działa?
 3. Czy kreacja działa od pierwszych sekund?
 4. Która kreacja zostaje w pamięci?
 5. Która kreacja najlepiej buduje markę?
 6. Czy odbiorca widzi najważniejszy przekaz?
 7. Czy przekaz jest zrozumiały?
 8. Która kreacja najbardziej się wyróżnia?
 9. Czy kreacja angażuje, czy jest obojętna?
 10. Która kreacja najlepiej pasuje do grupy docelowej?
 11. Czy kreacja budzi negatywne reakcje?
 12. Która kreacja jest najbezpieczniejsza?
 13. Który styl komunikacji działa lepiej?
 14. Czy ekran prowadzi użytkownika do celu?
 15. Które opakowanie lepiej przyciąga klienta?
 **Grupa docelowa:** Wskazanie grupy docelowej (cechy metryczkowe lub gotowe presety kilku cech w ramach jednej kategorii np.  Generacja Z, Silver etc.
 **Grupy docelowe:**
 **Wiek:**
 - Młodzież (do 25 lat)
 - Dorośli (26-64 lat)
 - Seniorzy (66 i więcej)
 **Płeć:**
 - Kobieta
 - Mężczyzna
 **Miejsce Zamieszkania:**
 - Miejscowośc do 19 tys mieszkańców
 - Miasto 20–50 tys. mieszkańców
 - Miasto 50–100 tys. mieszkańców
 - Miasto 100–500 tys. mieszkańców
 - Miasto powyżej 500 tys. mieszkańców
 **Wyksztalcenie:**
 - Podstawowe
 - Zasadnicze zawodowe
 - Średnie
 - Wyższe
 - Wyższe / Tytuł naukowy
 **Dochód:**
 - Niski - Do minimalnej krajowej (MK)
 - Średni - Powyżej MK do Średniej Krajowej (ŚK)
 - Wysoki - Powyżej ŚK
 **Neuroatypowość:**
 - **Brak / Neurotypowy**
 - ASD - Spektrum autyzmu
 - ADHD - Nadpobudliwość ruchowa
 - Zaburzenia Depresyjne
 **Profile opisowe:**
 - NT - Profil Neurotypowy
 - DE - Profil Wykluczony Cyfrowo
 - SE - Profil Silver Economy
 - GZ - Gen-Z/Digital Native
 #### Krok 2 - Parametry
 **Rodzaj analizy:** Eye Tracking, Facial Coding, ET+FC.
 **Rodzaj testu:** Do wyboru mamy test:
 - A - Jedna kreacja
 - AB - Dwie kreacje
 - ABC - Trzy kreacje
 **Czas obserwacji:** 1s, 3s, 5s, 10s, 15s, 20s
 **Zakres raportu:** Elementy, z których składa się raport finalny tj. Opis ogólny kreacji, Lista obiektów, Lista i opis AOI, Mapy Cieplne, Ścieżki Fiksacji, Ścieżka AOI, Analiza Kognitywna, Wizualizacje dynamiczne 1-20s, Wizualizacje statyczne 1s, 3s, 5s, 10s, 15s, 20s, Tabela porównawcza z metrykami.
 #### Krok 3 - Studio
 **Obiekty:** na poszczególnych materiałach wybranych do analizy Użytkownik może sam wskazać obiekty do analizy (zaznaczając ich obszar i nadając im nazwy) lub skorzystać z identyfikacji obiektów przez AI, a następnie może je skorygować (obszar i nazwy) lub usunąć decydując, które obiekty pozostawia do analizy kognitywnej.
 **Słownik Obiektów:**
 - Architektura
 - Celebryci
 - Chemia
 - Edukacja
 - Elektronika
 - Fabryki
 - Finanse
 - Handel
 - Inne
 - Kosmetyki
 - Logistyka
 - Militaria
 - Motoryzacja
 - Osoby
 - Przemysł
 - Przyroda
 - Sport
 - Ubrania
 - Zwierzęta
 - Żywność
 - ….
 **AOI (obszary zainteresowania):** na poszczególnych materiałach wybranych do analizy Użytkownik może sam wskazać AOI do analizy (zaznaczają ich obszar i nadając im nazwy) lub skorzystać z identyfikacji AOI i obiektów przez AI, a następnie może je skorygować (obszar i nazwy) lub usunąć decydując, które AOI pozostawia do analizy kognitywnej.
 **Słownik AOI**
 - Call to Action (CTA)
 - Dowód społeczny
 - Key Visual
 - Kod QR
 - Kolorystyka
 - Kontakt
 - Korzyści
 - Kupon
 - Layout
 - Logo
 - Mapa
 - Nagłówek
 - Narracja
 - Numer katalogowy
 - Regulaminy
 - Slogan
 - Ton komunikacji
 - Treść
 - Typografia
 - Tło
 - ….
 #### Krok 4 - Raport
 **Raport składa się z:**
 - Opis ogólny kreacji
 - Lista obiektów
 - Lista i opis AOI
 - Mapy Cieplne
    - Wizualizacje dynamiczne od 1 do 20s
    - Wizualizacje statyczne 1s, 3s, 5s, 10s, 15s, 20s
 - Ścieżki Fiksacji
    - Wizualizacje dynamiczne od 1 do 20s
    - Wizualizacje statyczne 1s, 3s, 5s, 10s, 15s, 20s
 - Ścieżka AOI
 - Analiza kognitywna
 - Tabela porównawcza z metrykami
 **Warunki prezentacji danych raportu:**
 - Jeśli to eksprgyment  AB to cześci składowe raportu dotyczą 2 kreacji.
 - Jeśli to eksprgyment ABC to cześci składowe raportu dotyczą 3 kreacji.
 **Opcje pobierania i udostępniania raportu**:
 - **Udostępnianie:** Zgodnie z uprawnieniami projektu (wyżej). Możliwość udostępnienia wyników jako link do eksperymentu.
 - **Pobieranie:** Pobieranie raportu z wyników eksperymentu w formie PDF.
 #### Logi
 Super administrator po wejściu na eksperyment posiada również dostęp do logów z przeprowadzonego eksperymentu. Wszystkie działani i ustawienia użytkownika w eksperymencie oraz wszystkie wysłane i odebrane dane z modeli AI.
 ---
 ## Panel administracyjny
 ### Sitebar
 - Dashboard
 - Organizacje
 - Użytkownicy
 - Proces i modele AI
 - Logi
 ### Dashboard
 Prezentuje dane taki jak:
 - Liczba organizacji i zmiana w ciągu 30 dni (graficznie i liczbowo)
 - Liczba użytkowników i zmiana w ciągu 30 dni (graficznie i liczbowo)
 - Liczba kreacji i zmiana w ciągu 30 dni (graficznie i liczbowo)
 - Liczba przeprowadzonych eksperymentów i zmiana w ciągu 30 dni (graficznie i liczbowo)
 ### Organizacje
 Lista organizacji w podstawowymi danymi i wyszukiwarką. Po wejściu w daną organizację można zarządzać:
 - Danymi organizacji
 - Użytkownikami
 - Kredytami (punktami) dostępnymi globalnie dla klienta i tymi kredytami dodawanymi każdego miesiąca.
 - Można również dezaktywować organizację / aktywować. Organizację, którą zdezaktywowano można zarchiwizować.
 ### Użytkownicy
 Lista organizacji w podstawowymi danymi i wyszukiwarką. 
 ### Proces i modele AI
 Lista procesów realizowanych w eksperymentach (zamknięta lista) oraz model AI, który realizuje dany proces.
 ### Logi
 Logi z całego systemu pozwalające na filtrowanie wg użytkowników, organizacji, daty (od do), rodzaju operacji.
 ---
 ## Use case 1:
 1. Rejestracja użytkownika.
 2. Logowanie do platformy.
 3. Utworzenie organizacji.
 4. Dodanie w galerii nowych kreacji (materiałów graficznych) przeznaczonych do eksperymentów.
 5. Utworzenie nowego projektu
    1. Utworzenie w ramach projektu eksperymentu w tym:
        - Podanie celu i grupy docelowej
        - Wybranie rodzaju ABC i dodanie 3 kreacji (materiałów graficznych) do eksperymentu.
        - Konfiguracja parametrów
        - Nie wykonywanie zmian w Studio.
    2. Wygenerowanie raportu z analizy
    3. Eksport raportu z analizy do PDF
    4. Udostępnianie raportu dla innych użytkowników z opcją do edycji (Editor) lub tylko do podglądu.
    5. Wykorzystanie eksperymentu jako podstawy do innego eksperymentu. W eksperymencie pojawia się opcja “Zmień ten eksperyment”.
    6. Po kliknięciu na “Zmień ten eksperyment” użytkownik jest proszony o podanie nowej nazwy i jest przekierowany do Kroku 1 eksperymentu, który został utworzony na podstawie poprzedniego.
 ## Use case 2:
 Ze zmianami w Studio
 1. Rejestracja użytkownika.
 2. Logowanie do platformy.
 3. Utworzenie organizacji.
 4. Dodanie w galerii nowych kreacji (materiałów graficznych) przeznaczonych do eksperymentów.
 5. Utworzenie nowego projektu
    1. Utworzenie w ramach projektu eksperymentu w tym:
        - Podanie celu np.  **Która kreacja lepiej sprzedaje?**
        - Podanie grupy docelowej np.:
            - **Wiek:**
                - Młodzież (do 25 lat)
            - **Płeć:**
                - Kobieta
            - **Miejsce Zamieszkania:**
                - Miejscowośc do 19 tys mieszkańców
            - **Wyksztalcenie:**
                - Wyższe
            - **Dochód:**
                - Średni - Powyżej MK do Średniej Krajowej (ŚK)
            - **Neuroatypowość:**
                - Brak
        - Wybranie rodzaju analizy A, AB, AC, BC, ABC
            - **ABC**
        - Dodanie 3 kreacji (materiałów graficznych) do eksperymentu.
            - Materiał 1
            - Materiał 2
            - Materiał 3
        - Konfiguracja parametrów metryk ET, FC, ET + FC.
            - Zgodnie ze wskazaniem celu
        - Nie wykonywanie zmian w Studio.
            - Obiekty i AOI wskazane przez AI
    2. Wygenerowanie raportu z analizy
    3. Eksport raportu z analizy do PDF + XLS (Tabele z danymi porównawczymi z metryk, AVI - dynamiczne mapy cieple i ścieżki fiksacji)
    4. Udostępnianie raportu dla innych użytkowników z opcją do edycji (Editor) lub tylko do podglądu.
        - 1 osoba jako Editor
        - 1 osoba jako Viwer
    5. Wykorzystanie eksperymentu jako podstawy do innego eksperymentu. W eksperymencie pojawia się opcja “Edytuj”.
    6. Po kliknięciu na “Edytuj” użytkownik jest proszony o podanie nowej nazwy i jest przekierowany do Kroku 1 eksperymentu, który został utworzony na podstawie poprzedniego.
--- a/rozszerzona.md
+++ b/rozszerzona.md
@ -0,0 +1,717 @@
 # AdReactions — Koncepcja platformy v0.2 (rozszerzona)
 > **Status dokumentu:** rozszerzenie i ujednolicenie „Koncepcja 0.1 [KM]".
 > Łączy w spójną całość źródła projektu i dokłada warstwy, których w wersji 0.1
 > brakowało: model domenowy, mapowanie *cel biznesowy → metryki → usługi AI*,
 > wymienialność modeli, propozycję modelu danych oraz jawne rozgraniczenie
 > **zakresu MVP 1.0 od roadmapy**.
 >
 > Miejsca wymagające decyzji właściciela produktu oznaczono znacznikiem **[?]**
 > i zebrano w osobnym pliku **`Pytania do koncepcji.md`**.
 ## Źródła zintegrowane w tym dokumencie
 | Dokument | Co wnosi |
 |---|---|
 | `Koncepcja 0.1.md` | Produkt, role, moduły, UX, kreator eksperymentu, use case'y |
 | `Opis celów analiz kognitywnych.md` | 15 celów biznesowych + mapowanie na metryki ET/FC |
 | `Specyfikacja-procesu-AI.md` | Logika procesu AI: kontrakty usług, orkiestracja, model danych, roadmapa |
 | `info.md` | Wymaganie: wymiana modelu AI na inny (np. Gemini, Opus) z poziomu panelu |
 ---
 ## Spis treści
 1. [Streszczenie wykonawcze](#1-streszczenie-wykonawcze)
 2. [Wizja produktu i propozycja wartości](#2-wizja-produktu-i-propozycja-wartości)
 3. [Słownik pojęć (model domenowy)](#3-słownik-pojęć-model-domenowy)
 4. [Architektura logiczna platformy](#4-architektura-logiczna-platformy)
 5. [Organizacje, role i uprawnienia](#5-organizacje-role-i-uprawnienia)
 6. [Moduły platformy](#6-moduły-platformy)
 7. [Cykl życia eksperymentu (kreator 4 kroków)](#7-cykl-życia-eksperymentu-kreator-4-kroków)
 8. [Katalog celów analiz kognitywnych](#8-katalog-celów-analiz-kognitywnych)
 9. [Warstwa AI — proces analizy](#9-warstwa-ai--proces-analizy)
 10. [Wymienialność modeli AI (Proces ↔ Model)](#10-wymienialność-modeli-ai-proces--model)
 11. [Struktura i generowanie raportu](#11-struktura-i-generowanie-raportu)
 12. [Propozycja modelu danych (Supabase)](#12-propozycja-modelu-danych-supabase)
 13. [Kredyty, subskrypcje, przestrzeń dyskowa](#13-kredyty-subskrypcje-przestrzeń-dyskowa)
 14. [Logi i audyt](#14-logi-i-audyt)
 15. [Bezpieczeństwo, prywatność, zgodność](#15-bezpieczeństwo-prywatność-zgodność)
 16. [Internacjonalizacja](#16-internacjonalizacja)
 17. [Przepływy użytkownika (use case'y)](#17-przepływy-użytkownika-use-casey)
 18. [Zakres MVP 1.0 vs roadmapa](#18-zakres-mvp-10-vs-roadmapa)
 ---
 ## 1. Streszczenie wykonawcze
 **AdReactions** to aplikacja SaaS do **predykcyjnego badania percepcji i emocji** wobec
 kreacji reklamowych - bez udziału realnych respondentów. Zamiast organizować kosztowne
 badania eye-trackingowe na ludziach, użytkownik wgrywa kreację (reklamę, baner, opakowanie, ekran UI) i otrzymuje **syntetyczny eye-tracking** oraz **predykcję reakcji emocjonalnej** generowane przez modele AI, w tym autorski model **ASM PNS**.
 Cechą wyróżniającą produkt jest **odwrócenie perspektywy**: użytkownik nie konfiguruje metryk, tylko wybiera **cel biznesowy** („Która kreacja lepiej sprzedaje?", „Czy CTA działa?"), a system samodzielnie dobiera technologię analizy (Eye Tracking / Facial Coding / ET+FC), zestaw metryk i sposób interpretacji wyniku. Raport nie podaje surowych liczb, lecz **rekomendację z uzasadnieniem** („Wariant B lepiej realizuje cel sprzedażowy, ponieważ…").
 **Zakres MVP 1.0:** platforma SaaS (organizacje, projekty, eksperymenty, galeria kreacji,
 raporty), kreator eksperymentu, panel administracyjny z **wymienialnymi modelami AI**,
 oraz pipeline AI obejmujący detekcję obiektów i predykcję uwagi wzrokowej (trzy modele
 saliency z walidacją krzyżową). Facial Coding, wizualizacje czasowe i ścieżki fiksacji
 są zaplanowane jako kolejne, niezależne gałęzie pipeline'u (patrz §18).
 ---
 ## 2. Wizja produktu i propozycja wartości
 ### 2.1. Problem
 Klasyczne badania eye-trackingu i kodowania mimiki (facial coding) są drogie, czasochłonne
 i wymagają rekrutacji respondentów oraz sprzętu. Decyzje o wyborze wariantu kreacji
 zapadają więc często „na wyczucie", już po poniesieniu kosztów produkcji.
 ### 2.2. Propozycja wartości
 - **Szybkość i koszt:** predykcja w minutach zamiast tygodni, bez respondentów.
 - **Decyzyjność:** wynik prowadzi do konkretnej rekomendacji („wybierz B"), a nie tabeli liczb.
 - **Porównywalność:** test A / AB / ABC pozwala zestawić warianty na jednej osi metryk.
 - **Segmentacja:** predykcje dla zdefiniowanej grupy docelowej (demografia, profile, neuroatypowość).
 - **Powtarzalność:** eksperyment można sklonować i zmodyfikować jako bazę kolejnego.
 ### 2.3. Kluczowa innowacja: „cel zamiast metryk"
 To centralny mechanizm produktu (rozwinięty w §8). Pięć warstw od wyboru celu do rekomendacji:
 ```
 [1] Użytkownik wybiera CEL BIZNESOWY        np. „Która kreacja lepiej sprzedaje?"
            │
 [2] System pokazuje OPIS POMOCNICZY         „Sprawdź, który wariant prowadzi uwagę do CTA…"
            │
 [3] System rekomenduje TYP ANALIZY          ET+FC (z możliwością zmiany przez użytkownika)
            │
 [4] System dobiera METRYKI „pod spodem"     udział uwagi na CTA, Positive Valence, …
            │
 [5] Raport zwraca REKOMENDACJĘ Z UZASADNIENIEM  „Wariant B…, ponieważ…"
 ```
 ### 2.4. Odbiorcy (persony)
 - **Marketer / brand manager** — wybiera wariant kampanii, potrzebuje rekomendacji.
 - **Agencja kreatywna** — testuje koncepty przed prezentacją klientowi (pitch).
 - **Projektant UX / CRO** — sprawdza, czy ekran prowadzi użytkownika do celu.
 - **Super administrator (operator platformy)** — zarządza organizacjami i modelami AI.
 ---
 ## 3. Słownik pojęć (model domenowy)
 Ujednolicenie nazewnictwa używanego w dalszej części dokumentu.
 | Pojęcie | Definicja |
 |---|---|
 | **Organizacja** | Najwyższy kontener klienta. Ma administratora, użytkowników, gości, projekty, pulę kredytów i przestrzeń dyskową. |
 | **Użytkownik** | Niezależne konto osoby. Może należeć do wielu organizacji [?]. |
 | **Projekt** | Kontener eksperymentów + galeria kreacji projektu. Typ pochodny: ET / FC / ET+FC. |
 | **Eksperyment** | Pojedyncza analiza predykcyjna 1–3 kreacji wg zadanego celu, grupy, parametrów. |
 | **Kreacja** | Materiał graficzny (PNG/JPEG) — reklama, baner, opakowanie, ekran. Jednostka wejściowa analizy. |
 | **Galeria** | Zbiór kreacji: na poziomie **organizacji** (współdzielona) i **projektu** (podzbiór roboczy). |
 | **Obiekt** | Rozpoznany element treści obrazu (osoba, butelka, logo…) z ramką (bbox). Źródło: AI lub użytkownik. |
 | **AOI** (Area of Interest) | Obszar zainteresowania o znaczeniu marketingowym (CTA, Logo, Key Visual…). Źródło: AI lub użytkownik. |
 | **Metryka** | Mierzalny wskaźnik percepcji/emocji (np. udział uwagi na AOI, Positive Valence). |
 | **Cel** | Pytanie biznesowe wybrane przez użytkownika; mapuje się na typ analizy i zestaw metryk. |
 | **Grupa docelowa** | Profil odbiorcy (wiek, płeć, miejsce, wykształcenie, dochód, neuroatypowość / preset). |
 | **Raport** | Złożenie wizualizacji, metryk i interpretacji kognitywnej dla eksperymentu. |
 | **Proces AI** | Pojedynczy krok analizy realizowany przez model (np. „detekcja obiektów", „predykcja saliency"). |
 | **Model AI** | Konkretny silnik realizujący proces (LLaVA, ASM, DeepGaze…), wymienny na inny (§10). |
 | **Kredyt / coin** | Wewnętrzna jednostka rozliczeniowa (eksperymenty, przestrzeń dyskowa). |
 ### Diagram relacji encji (uproszczony)
 ```
 Organizacja 1───* Użytkownik           Organizacja 1───* Projekt
     │                                       │
     │ 1                                     │ 1
     *                                       *
  Galeria(org) *───* Kreacja            Eksperyment
     ▲                  │ *                   │ 1
     │                  │                     ├──* Kreacja (1–3: A/B/C)
  Galeria(projekt) *────┘                     ├──* Obiekt
                                              ├──* AOI
                                              ├──1 Cel + Grupa docelowa + Parametry
                                              └──1 Raport ──* WynikModelu / Metryka
 ```
 ---
 ## 4. Architektura logiczna platformy
 ### 4.1. Warstwy
 ```
 ┌──────────────────────────────────────────────────────────────────────┐
 │  FRONTEND  — React + shadcn/ui + Tailwind                            │
 │  Panele: Administracyjny · Użytkownika · Organizacji                 │
 │  Kreator eksperymentu (4 kroki) · Studio (obiekty/AOI) · Raport      │
 └───────────────────────────────┬──────────────────────────────────────┘
                                │ REST / RPC
 ┌───────────────────────────────▼───────────────────────────────────────┐
 │  BACKEND  — Node.js                                                   │
 │  • API platformy (CRUD: org, projekty, eksperymenty, galeria)         │
 │  • Orkiestrator analizy AI (§9) — równoległe wywołania usług          │
 │  • Warstwa metryk (saliency ∩ AOI → wskaźniki)                        │
 │  • Warstwa interpretacji kognitywnej (cel + metryki → rekomendacja)   │
 │  • Generator raportu (PDF/XLS/wizualizacje)                           │
 │  • Rejestr modeli AI + router „Proces ↔ Model" (§10)                  │
 └──────────────┬────────────────────────────────────┬───────────────────┘
               │                                    │ HTTP POST (multipart)
 ┌──────────────▼──────────────────┐   ┌─────────────▼──────────────────────┐
 │  SUPABASE                       │   │  WARSTWA MODELI AI (mikroserwisy)  │
 │  • PostgreSQL (model danych)    │   │  LLaVA · Grounding DINO · DeepGaze │
 │  • Storage (kreacje, artefakty) │   │  UNISAL · ASM (PNS) · [Gemini/Opus]│
 │  • Auth (konta, sesje, role)    │   │  Wymienne wg konfiguracji procesu  │
 └─────────────────────────────────┘   └────────────────────────────────────┘
 ```
 ### 4.2. Stack technologiczny (z Koncepcji 0.1)
 - **Front-end:** React / shadcn/ui + Tailwind
 - **Back-end:** Node.js
 - **Baza, Storage, Auth:** Supabase
 - **Warstwa AI:** mikroserwisy modelowe za REST API, orkiestrowane przez backend Node.js (§9).
 ### 4.3. Uwaga o orkiestracji
 Logika procesu AI jest opisana **niezależnie od narzędzia orkiestrującego**
 (`Specyfikacja-procesu-AI.md`) i przeznaczona do implementacji jako komponent backendu
 Node.js: równoległe wywołania usług modelowych, agregacja wyników i obsługa błędów (§9).
 Pojedyncze modele (detekcja, saliency) pozostają niezależnymi mikroserwisami za REST API.
 ---
 ## 5. Organizacje, role i uprawnienia
 ### 5.1. Hierarchia
 - **Super administrator** — operator platformy. Dostęp do panelu administracyjnego;
  zarządza organizacjami, użytkownikami i modelami AI. Może „wejść" w dowolną organizację
  i poruszać się w niej jak administrator. Ma dostęp do logów systemowych i logów eksperymentu.
 - **Administrator organizacji** — powstaje przy rejestracji organizacji; prawa zbywalne na
  innego użytkownika. Pełny dostęp do projektów, rozliczeń, planów i ustawień organizacji.
 - **Użytkownik** — niezależne konto; uprawnienia nadawane na poziomie organizacji i/lub projektu.
 - **Gość** — wymieniony w strukturze organizacji; zakres uprawnień do doprecyzowania **[?]**
  (proponowane: dostęp tylko do udostępnionych raportów, bez tworzenia treści).
 ### 5.2. Macierz uprawnień (propozycja ujednolicająca)
 Uprawnienia działają na dwóch poziomach: **organizacji** i **konkretnego projektu**.
 | Uprawnienie | Super Admin | Admin org. | Użytkownik (org.) | Użytkownik (projekt) | Gość |
 |---|:--:|:--:|:--:|:--:|:--:|
 | Panel administracyjny | ✓ | — | — | — | — |
 | Zarządzanie modelami AI | ✓ | — | — | — | — |
 | Tworzenie projektów | ✓ | ✓ | wg uprawnień | — | — |
 | Przeglądanie wszystkich projektów | ✓ | ✓ | wg uprawnień | — | — |
 | Edycja wszystkich projektów | ✓ | ✓ | wg uprawnień | — | — |
 | Usuwanie projektów | ✓ | ✓ | wg uprawnień | — | — |
 | Zapraszanie do projektów | ✓ | ✓ | wg uprawnień | wg roli projekt. | — |
 | Rozliczenia / plany / kredyty | ✓ | ✓ | — | — | — |
 | Tworzenie / konfiguracja eksperymentu | ✓ | ✓ | ✓ | Editor | — |
 | Podgląd raportu | ✓ | ✓ | ✓ | Editor / Viewer | Viewer (udostępniony) |
 **Role w obrębie projektu** (przy udostępnianiu): **Editor** (edycja + zapraszanie) /
 **Viewer** (tylko podgląd). W Koncepcji 0.1 pojawia się też wariant „usuwanie, edycja i
 zapraszanie" — ujednolicić do 2–3 ról projektowych **[?]**.
 ---
 ## 6. Moduły platformy
 ### 6.1. Panel administracyjny (tylko Super Administrator)
 **Sitebar:** Dashboard · Organizacje · Użytkownicy · Proces i modele AI · Logi.
 - **Dashboard** — KPI z dynamiką 30 dni (graficznie + liczbowo): liczba organizacji,
  użytkowników, kreacji, przeprowadzonych eksperymentów.
 - **Organizacje** — lista + wyszukiwarka; wejście w organizację pozwala zarządzać danymi,
  użytkownikami, **kredytami** (globalnymi i miesięcznymi), aktywować / dezaktywować /
  archiwizować organizację.
 - **Użytkownicy** — lista + wyszukiwarka (dane podstawowe).
 - **Proces i modele AI** — **zamknięta lista procesów** realizowanych w eksperymentach
  oraz przypisany do każdego model AI. To miejsce wymiany modelu na inny (szczegóły §10).
 - **Logi** — logi całego systemu z filtrowaniem (użytkownik, organizacja, zakres dat, typ operacji).
 ### 6.2. Panel użytkownika (po zalogowaniu)
 Z tego miejsca użytkownik może: przejść do wybranej organizacji, dodać nową organizację
 (limit: jedna nowa organizacja **[?]** — doprecyzować, czy dotyczy zakładania, czy członkostwa),
 zmienić dane, e-mail, hasło.
 ### 6.3. Panel organizacji (Administrator + użytkownicy)
 **Sitebar:** Dashboard · Projekty · Galeria.
 **Topbar:** wybór organizacji · wyszukiwarka (projekty, kreacje, eksperymenty).
 **Sitebar** chowa się na mobile; **Workspace** to obszar roboczy.
 - **Dashboard** — KPI: liczba kreacji w Galerii, liczba projektów, liczba eksperymentów.
  Przyciski szybkich akcji: *Dodaj kreację do Galerii* · *Utwórz nowy Projekt* ·
  *Przejdź do ostatniego eksperymentu*. Poniżej: lista projektów z wejściem.
 - **Galeria** — zarządzanie kreacjami organizacji: upload, kafelki ostatnio dodanych,
  pełna galeria (slider). Klik w kreację → **drawer** po prawej: powiększenie + lista
  eksperymentów/projektów, w których użyto kreacji (z przejściem do nich).
 - **Projekty** — lista projektów (nazwa, typ ET/FC/ET+FC), przycisk *Nowy projekt*.
  - **Panel projektu** — zarządzanie: przegląd, weryfikacja konfiguracji eksperymentów,
    usuwanie projektu/eksperymentów, udostępnianie projektu.
  - **Galeria projektu** — kreacje dodane do projektu (z Galerii organizacji lub własne projektu).
    W jednym eksperymencie maks. **3 kreacje (A, B, C)**. Liczba materiałów ograniczona
    przestrzenią dyskową subskrypcji (rozszerzalną za kredyty — §13).
  - **Galeria eksperymentów** — wszystkie eksperymenty projektu z kluczowymi parametrami
    (technologia ET/FC/ET+FC, typ testu, autor).
 ---
 ## 7. Cykl życia eksperymentu (kreator 4 kroków)
 Każdy eksperyment przechodzi przez czterostopniowy kreator. Poniżej rozszerzenie z dopiętym
 mapowaniem na warstwę AI (§9) i metryki (§8).
 ### 7.1. Krok 1 — Cel i grupa docelowa
 - **Cel** — wybór ze słownika 15 celów (§8) lub opis własny. Cel determinuje rekomendowany
  typ analizy i zestaw metryk.
 - **Grupa docelowa** — cechy metryczkowe lub gotowe presety:
 | Kategoria | Wartości |
 |---|---|
 | **Wiek** | Młodzież (do 25) · Dorośli (26–64) · Seniorzy (65+) *(ujednolicić próg — patrz [?])* |
 | **Płeć** | Kobieta · Mężczyzna |
 | **Miejsce zamieszkania** | do 19 tys. · 20–50 tys. · 50–100 tys. · 100–500 tys. · >500 tys. |
 | **Wykształcenie** | Podstawowe · Zasadnicze zawodowe · Średnie · Wyższe · Wyższe / tytuł naukowy |
 | **Dochód** | Niski (≤MK) · Średni (MK–ŚK) · Wysoki (>ŚK) |
 | **Neuroatypowość** | Brak / Neurotypowy · ASD · ADHD · Zaburzenia depresyjne |
 | **Profile opisowe (presety)** | NT (Neurotypowy) · DE (Wykluczony cyfrowo) · SE (Silver Economy) · GZ (Gen-Z / Digital Native) |
 > **Powiązanie z AI — kluczowa uwaga:** obecny pipeline (§9) **nie przyjmuje** parametrów
 > demograficznych na wejściu. Model ASM PNS ma docelowo generować predykcje różnicowane
 > dla grup, jednak mechanizm warunkowania (np. przez `prompt` ASM lub osobne wagi modelu)
 > wymaga decyzji. **[?]** — patrz §9.5 i `Pytania do koncepcji.md`.
 ### 7.2. Krok 2 — Parametry
 - **Rodzaj analizy:** Eye Tracking · Facial Coding · ET+FC *(rekomendowany przez cel,
  edytowalny przez użytkownika)*.
 - **Rodzaj testu:** A (1 kreacja) · AB / AC / BC (2 kreacje) · ABC (3 kreacje).
  *Uwaga: Koncepcja 0.1 w jednym miejscu podaje A/AB/ABC, a w innym A/AB/AC/BC/ABC —
  ujednolicić.* **[?]**
 - **Czas obserwacji:** 1s · 3s · 5s · 10s · 15s · 20s.
  > Parametr nabiera pełnego znaczenia dopiero z **mapami czasowymi** (roadmapa). Przy
  > obecnej, statycznej saliency służy do wyboru klatek wizualizacji statycznej. **[?]**
 - **Zakres raportu:** wybór komponentów raportu (lista w §11).
 ### 7.3. Krok 3 — Studio
 Edycja warstwy semantycznej obrazu przed analizą:
 - **Obiekty** — użytkownik zaznacza obszary i nazywa je **lub** korzysta z **identyfikacji
  AI** (LLaVA → Grounding DINO), a następnie koryguje/usuwa. Słownik kategorii: Architektura,
  Celebryci, Chemia, Edukacja, Elektronika, Finanse, Handel, Kosmetyki, Logistyka, Militaria,
  Motoryzacja, Osoby, Przemysł, Przyroda, Sport, Ubrania, Zwierzęta, Żywność, Inne…
 - **AOI** — analogicznie: ręcznie lub AI, z korektą. Słownik AOI: CTA, Dowód społeczny,
  Key Visual, Kod QR, Kolorystyka, Kontakt, Korzyści, Kupon, Layout, Logo, Mapa, Nagłówek,
  Narracja, Numer katalogowy, Regulaminy, Slogan, Ton komunikacji, Treść, Typografia, Tło…
 > **Obiekt vs AOI:** obiekty to *co jest na obrazie* (detekcja treści), AOI to *obszary o
 > znaczeniu marketingowym* (jednostka analizy uwagi). Pipeline pewnie wykrywa **obiekty**;
 > **AOI semantyczne** wymagają albo wskazania przez użytkownika, albo dodatkowego mapowania
 > obiekt→AOI. **[?]**
 ### 7.4. Krok 4 — Raport
 Generowanie i prezentacja wyników — szczegóły w §11.
 ### 7.5. Logi eksperymentu
 Super administrator po wejściu w eksperyment widzi pełne logi: wszystkie działania i
 ustawienia użytkownika oraz **wszystkie dane wysłane do i odebrane z modeli AI** (audyt
 predykcji — istotne przy wymianie modeli, §10).
 ---
 ## 8. Katalog celów analiz kognitywnych
 Mechanizm „cel zamiast metryk" (§2.3). Pełne opisy 15 celów znajdują się w
 `Opis celów analiz kognitywnych.md`; poniżej **tabela zbiorcza** jako referencja
 konfiguracyjna (źródło prawdy dla domyślnego doboru typu analizy i metryk).
 | # | Cel (nazwa UI) | Rekom. analiza | Sygnał kluczowy |
 |---|---|:--:|---|
 | 1 | Która kreacja lepiej sprzedaje? | ET+FC | uwaga na produkt/benefit/CTA + niskie napięcie |
 | 2 | Czy odbiorca widzi najważniejszy przekaz? | ET (opc. ET+FC) | zauważalność i czas dotarcia do komunikatu |
 | 3 | Czy CTA działa? | ET+FC | widoczność CTA + brak oporu emocjonalnego |
 | 4 | Która kreacja zostaje w pamięci? | ET+FC | uwaga + pobudzenie (High Arousal) |
 | 5 | Która kreacja najlepiej buduje markę? | ET+FC | uwaga na logo + pozytywna walencja |
 | 6 | Czy kreacja budzi negatywne reakcje? | FC (opc. ET+FC) | Negative Valence + High Arousal na elemencie |
 | 7 | Czy przekaz jest zrozumiały? | ET (opc. ET+FC) | logiczna ścieżka, brak chaosu/powrotów |
 | 8 | Czy kreacja działa od pierwszych sekund? | ET+FC | pierwsza fiksacja + impuls emocjonalny 1–3s |
 | 9 | Czy kreacja angażuje, czy jest obojętna? | FC (opc. ET+FC) | aktywacja vs Low Arousal / Neutral |
 | 10 | Który styl komunikacji działa lepiej? | ET+FC | rozkład uwagi tekst/obraz + profil emocji |
 | 11 | Które opakowanie lepiej przyciąga klienta? | ET+FC | marka/wariant/benefit + atrakcyjność |
 | 12 | Czy ekran prowadzi użytkownika do celu? | ET+FC | ścieżka do akcji + komfort/frustracja |
 | 13 | Która kreacja najlepiej pasuje do grupy docelowej? | ET+FC | różnice między segmentami |
 | 14 | Która kreacja jest najbezpieczniejsza? | ET+FC | niska negatywność/ambiwalencja, czytelność |
 | 15 | Która kreacja najbardziej się wyróżnia? | ET+FC | siła pierwszej fiksacji + aktywacja |
 **Zasada interpretacji wspólna dla wszystkich celów:** raport rozróżnia warianty
 **pozytywne / neutralne / ryzykowne** (np. „wyróżnialność pozytywna" vs „ryzykowna"),
 a rekomendacja zależy od **kontekstu kampanii** (performance vs wizerunek) i **grupy docelowej**.
 ---
 ## 9. Warstwa AI — proces analizy
 Sekcja opiera się na `Specyfikacja-procesu-AI.md` — opisie logiki procesu niezależnym od
 narzędzia orkiestrującego. Proces jest **bezstanowy**: jedno wejście (obraz) → jeden komplet wyników.
 ### 9.1. Pipeline i usługi
 ```
        Wejście: obraz (PNG/JPEG)
                  │  preprocessing → bytes + base64 + mime + (w,h)
   ┌──────────────┼───────────────┬───────────────┬───────────────┐
   ▼ (łańcuch A, sekwencyjny)     ▼ (B)           ▼ (C)           ▼ (D)
 ┌──────────┐                  ┌──────────┐   ┌──────────┐   ┌──────────────┐
 │ LLaVA    │ etykiety         │ DeepGaze │   │ UNISAL   │   │ ASM (PNS)    │
 │ (VLM)    │───┐              │(saliency)│   │(saliency)│   │ 2× saliency  │
 └──────────┘   ▼              └────┬─────┘   └────┬─────┘   └──────┬───────┘
        ┌─────────────┐            │              │                │
        │ Grounding   │            └──────────────┴────────────────┘
        │ DINO (boxy) │                          │ agregacja saliency
        └─────┬───────┘                          ▼
              ▼                      ┌─────────────────────────────┐
        detekcja obiektów           │ Artefakty: overlay boxów ·   │
                                    │ nakładka heatmapy (suwak) ·  │
                                    │ porównanie 2×2 (walid. krzyż)│
                                    └─────────────────────────────┘
 ```
 **Pięć modeli / procesów (wg specyfikacji procesu AI):**
 | # | Model | Proces | Endpoint (wzorzec) | Auth |
 |---|---|---|---|---|
 | 1 | **LLaVA** | ekstrakcja typów obiektów (open-vocabulary) | `/llava-api/v1/get-object-types` | Bearer |
 | 2 | **Grounding DINO** | detekcja / bounding boxy | `/grounding-dino-api/v1/get-objects-bboxes` | Bearer |
 | 3 | **DeepGaze** | predykcja saliency | `/v1/predict-heatmap` | Bearer |
 | 4 | **UNISAL** | predykcja saliency (porównawcza) | `/unisal/process-image?as_base64=true` | X-API-Key |
 | 5 | **ASM (PNS)** | 2× saliency, warunkowane promptem marketingowym | `/asmModel/process-image?prompt=…` | X-API-Key |
 **Zależności i równoległość:**
 - Łańcuch A jest **sekwencyjny** (Grounding DINO potrzebuje etykiet z LLaVA).
 - Gałęzie A, B, C, D są **niezależne** → wykonywane **równolegle**; czas ≈ najwolniejsza gałąź.
 - **Odporność:** awaria jednej gałęzi nie przerywa całości — degradacja stopniowa
  (`return_exceptions` / per-task `try/except`); pozostałe artefakty powstają normalnie.
 ### 9.2. Model danych wyników (z §4 specyfikacji)
 ```
 AnalysisResult {
  image     : ImageInput { bytes, base64, mime, width, height }
  detection : DetectionResult { objects: [{ object_type, bbox_xyxy, score }] }
  saliency  : SaliencyMap[]   // deepgaze, unisal, asm_detailed, asm_general
 }
 ```
 ### 9.3. Artefakty wizualizacyjne (warstwa prezentacji)
 1. **Overlay detekcji** — ramki per obiekt, kolor per typ, podpis `typ + score%`,
   pozycje w procentach wymiarów (responsywność).
 2. **Nakładka heatmapy** — pojedyncza mapa uwagi + suwak przezroczystości 0–100%.
 3. **Porównanie 2×2** — DeepGaze / UNISAL / ASM detailed / ASM general; wspólny suwak,
   technika „inwersji" (blend luminancji: biel = wysoka uwaga → efekt reflektora).
 ### 9.4. Mapowanie: technologie badawcze (produkt) ↔ usługi AI (pipeline)
 | Warstwa produktu | Realizacja w AI | Status |
 |---|---|:--:|
 | **Eye Tracking** — mapy uwagi, udział uwagi na AOI | DeepGaze · UNISAL · ASM (saliency statyczna) | ✅ jest |
 | Rozumienie treści — obiekty, opis | LLaVA + Grounding DINO | ✅ jest |
 | **ET czasowy** — mapy dynamiczne 1–20s | saliency w interwałach czasu | 🟡 roadmapa |
 | **ET** — ścieżki fiksacji (scanpath) | model scanpath | 🟡 roadmapa |
 | **Facial Coding** — walencja, pobudzenie, frustracja… | mapa emocji | 🟡 roadmapa |
 | **Analiza kognitywna** — rekomendacja z uzasadnieniem | warstwa interpretacji (LLM nad metrykami) | 🔵 do zbudowania |
 | **Predykcje per grupa docelowa** | warunkowanie modelu demografią | 🟡 do zaprojektowania |
 > Legenda: ✅ objęte specyfikacją procesu (modele dostępne) · 🟡 roadmapa (§11 specyfikacji) · 🔵 nowy komponent.
 ### 9.5. Macierz wykonalności metryk w MVP (najważniejsza sekcja inżynierska)
 Większość metryk z `Opis celów…` wymaga komponentów, których **nie ma** w obecnym
 pipeline. To rozgraniczenie jest krytyczne dla zakresu MVP.
 | Metryka (z celów) | Czego wymaga | Wykonalne w MVP? |
 |---|---|:--:|
 | Udział uwagi na AOI (%) | saliency statyczna ∩ AOI | ✅ tak |
 | Ranking AOI wg uwagi | saliency ∩ AOI | ✅ tak |
 | Mapa cieplna statyczna | saliency | ✅ tak |
 | Porównanie kreacji wg uwagi | saliency × N kreacji | ✅ tak |
 | Czas do pierwszej fiksacji | scanpath (wymiar czasu) | ❌ roadmapa |
 | Kolejność kontaktu z AOI / „ścieżka AOI" | scanpath | ❌ roadmapa* |
 | Liczba powrotów wzroku | scanpath | ❌ roadmapa |
 | Mapy dynamiczne 1–20s | saliency czasowa | ❌ roadmapa |
 | Ścieżki fiksacji | model scanpath | ❌ roadmapa |
 | Positive/Negative Valence, Arousal, Frustration, Ambivalence, Comfort… | model emocji (FC) | ❌ roadmapa |
 | Różnice metryk między segmentami | warunkowanie demografią | ❌ do zaprojektowania |
 \* „Ścieżkę AOI" można w MVP **przybliżyć** rankingiem AOI wg intensywności saliency
 (kolejność „od najsilniejszego"), zaznaczając, że to heurystyka, a nie prawdziwa sekwencja
 fiksacji. **[?]**
 **Wniosek:** w MVP z obecnym pipeline'em wiarygodnie policzymy metryki **udziału uwagi na
 AOI** i ich **porównanie między wariantami** (cele silnie ET, np. #2, #7, częściowo #1, #3).
 Cele oparte na **emocjach** (#6, #9) i **wymiarze czasu** (#8) wymagają roadmapowych modeli
 FC / saliency czasowej, albo świadomego **ograniczenia zakresu MVP**. → decyzja właściciela
 produktu (`Pytania do koncepcji.md`).
 ---
 ## 10. Wymienialność modeli AI (Proces ↔ Model)
 Wymaganie z `info.md`: w MVP 1.0 musi istnieć możliwość **zmiany modelu realizującego dany
 proces** na inny (np. publiczny **Gemini**, **Opus**), z poziomu panelu administracyjnego.
 ### 10.1. Zasada: rozdzielenie procesu od modelu
 ```
 PROCES (stały, zamknięta lista)        MODEL (wymienny)             USŁUGA (endpoint)
 ─────────────────────────────         ─────────────────            ─────────────────
 Ekstrakcja typów obiektów      ──►     LLaVA            ──►   http://{LLaVA}/llava-api/...
                                ╲─►    [Gemini Vision]  ──►   adapter → API Gemini
 Detekcja obiektów (boxy)       ──►     Grounding DINO   ──►   .../get-objects-bboxes
 Predykcja saliency #1          ──►     DeepGaze         ──►   /v1/predict-heatmap
 Predykcja saliency #2          ──►     UNISAL           ──►   /unisal/process-image
 Predykcja saliency (centralna) ──►     ASM (PNS)        ──►   /asmModel/process-image
 [Mapa emocji — roadmapa]       ──►     [FC model]       ──►   …
 ```
 Każdy **proces** ma zdefiniowany **kontrakt** (wejście: obraz [+ parametry]; wyjście:
 ustandaryzowany typ — `labels[]`, `bboxes[]`, `SaliencyMap`). Model jest podpięty przez
 **adapter** tłumaczący kontrakt procesu na konkretne API. Dzięki temu podmiana
 LLaVA→Gemini nie zmienia reszty pipeline'u.
 ### 10.2. Wzorzec adaptera
 Aby podpiąć nowy model (np. Gemini/Opus) trzeba dostarczyć **adapter** = kod realizujący:
 1. **mapowanie wejścia** procesu → format żądania modelu (multipart / JSON, prompt, parametry),
 2. **wywołanie** (URL, schemat auth: Bearer vs X-API-Key vs klucz dostawcy),
 3. **mapowanie wyjścia** modelu → ustandaryzowany typ procesu (np. `labels[]`).
 To realizuje zdanie z `info.md`: „powinien być dodany kod, który realizuje usługę".
 Każdy proces = interfejs; każdy model = jego implementacja (adapter).
 ### 10.3. Panel „Proces i modele AI" (rozszerzenie)
 Ekran administracyjny prezentuje **zamkniętą listę procesów** i pozwala dla każdego:
 - wybrać **aktywny model** (z listy zarejestrowanych adapterów),
 - skonfigurować **endpoint / klucze / parametry** (host, token, prompt ASM, `max_objects`,
  `temperature`…) — przechowywane jako sekrety (Supabase / vault), nie w kodzie,
 - wykonać **test połączenia** (health-check) i podgląd przykładowego wyniku,
 - (zalecane) **wersjonować** przypisanie model↔proces, aby logi eksperymentu wskazywały,
  którym modelem policzono dany raport (powtarzalność, audyt — §7.5).
 > W MVP konfiguracja modeli (adresy URL, token/klucz, parametry) jest zarządzana z panelu
 > administracyjnego i przechowywana w magazynie sekretów (Supabase / vault), nie w kodzie.
 ### 10.4. Modele własne vs publiczne
 - **Własne (mikroserwisy):** LLaVA, Grounding DINO, DeepGaze, UNISAL, ASM (PNS) — pełna
  kontrola, model ASM jest rdzeniem przewagi produktu.
 - **Publiczne (API dostawców):** Gemini, Opus (Anthropic) i inne — przydatne dla procesów
  „rozumienia treści" (opis kreacji, lista obiektów) jako alternatywa/fallback dla LLaVA.
  **Uwaga:** modele saliency (predykcja uwagi) i FC są wyspecjalizowane — publiczne LLM-y
  ogólnego przeznaczenia ich **nie zastąpią 1:1**; wymienialność ma największy sens dla
  procesów językowo-wizualnych (etykiety, opis), a nie dla rdzennej predykcji uwagi. **[?]**
 ---
 ## 11. Struktura i generowanie raportu
 ### 11.1. Komponenty raportu i ich źródła (macierz śledzenia)
 | Komponent raportu | Źródło danych (proces/model) | Status MVP |
 |---|---|:--:|
 | Opis ogólny kreacji | LLaVA / opis (ew. ASM prompt) | ✅ |
 | Lista obiektów | LLaVA + Grounding DINO | ✅ |
 | Lista i opis AOI | użytkownik (Studio) ± mapowanie z obiektów | 🟡 częściowo |
 | Mapy cieplne — statyczne (1/3/5/10/15/20s) | DeepGaze/UNISAL/ASM (1 mapa = 1 klatka) | ✅ (jedna klatka)* |
 | Mapy cieplne — dynamiczne 1–20s | saliency czasowa | 🟡 roadmapa |
 | Ścieżki fiksacji — statyczne/dynamiczne | model scanpath | 🟡 roadmapa |
 | Ścieżka AOI | scanpath (lub przybliżenie rankingiem) | 🟡 / heurystyka |
 | Analiza kognitywna (rekomendacja) | warstwa interpretacji (cel + metryki → tekst) | 🔵 do zbudowania |
 | Tabela porównawcza z metrykami | warstwa metryk (saliency ∩ AOI) | ✅ (zakres ET-static) |
 \* obecne modele zwracają **jedną** mapę saliency; „statyczne 1/3/5/10/15/20s" są realne
 dopiero z saliency czasową — w MVP można pokazać jedną mapę zagregowaną. **[?]**
 ### 11.2. Warianty A / AB / ABC
 - Komponenty raportu powielają się per kreacja: **AB** → 2 kreacje, **ABC** → 3 kreacje.
 - Sednem jest **zestawienie porównawcze** i rekomendacja „który wariant wygrywa i dlaczego",
  z rozbiciem na zwycięzcę ogólnego i zwycięzcę dla grupy docelowej (cel #13).
 ### 11.3. Eksport i udostępnianie
 - **Eksport:** PDF (raport). Use case 2 dodaje **XLS** (tabele metryk) i **AVI** (dynamiczne
  mapy/ścieżki) — zależne od roadmapy czasowej. **[?]**
 - **Udostępnianie:** wg uprawnień projektu; **link do eksperymentu** (Editor / Viewer).
  Doprecyzować: link publiczny czy wymaga konta. **[?]**
 - **Klonowanie:** „Zmień ten eksperyment" / „Edytuj" → prośba o nową nazwę → przekierowanie
  do Kroku 1 z prekonfiguracją z eksperymentu bazowego (wersjonowanie — §12, [?]).
 ---
 ## 12. Propozycja modelu danych (Supabase)
 Szkic encji do walidacji (nazwy robocze). Klucze obce uproszczone.
 ```
 organizations(id, name, status[active|inactive|archived], credits_balance,
              storage_quota_mb, created_at)
 users(id, email, display_name, locale, created_at)
 memberships(id, org_id, user_id, role[admin|member|guest])     // M:N user↔org
 projects(id, org_id, name, type[ET|FC|ET_FC], created_by, created_at)
 project_permissions(id, project_id, user_id, role[editor|viewer])
 creatives(id, org_id, project_id?, storage_path, mime, width, height, created_by)
 experiments(id, project_id, name, goal_id, test_type[A|AB|AC|BC|ABC],
            analysis_type[ET|FC|ET_FC], observation_time_s, report_scope jsonb,
            target_group jsonb, base_experiment_id?, status, created_by, created_at)
 experiment_creatives(id, experiment_id, creative_id, slot[A|B|C])
 aois(id, experiment_id, creative_id, name, category, polygon jsonb, source[ai|user])
 objects(id, experiment_id, creative_id, object_type, bbox_xyxy jsonb, score, source)
 ai_runs(id, experiment_id, process_key, model_key, request jsonb, response_ref,
        status, duration_ms, created_at)        // audyt: który model, jaki wynik
 saliency_maps(id, ai_run_id, source[deepgaze|unisal|asm_detailed|asm_general],
              storage_path, mime)
 metrics(id, experiment_id, creative_id, aoi_id?, key, value)   // policzone wskaźniki
 reports(id, experiment_id, pdf_path?, xls_path?, generated_at)
 ai_processes(key, name, contract)              // zamknięta lista procesów
 ai_models(key, name, kind[own|public], adapter, config_ref)    // rejestr modeli
 process_model_binding(process_key, model_key, active, version) // Proces ↔ Model (§10)
 audit_logs(id, org_id?, user_id?, action, target, payload jsonb, created_at)
 ```
 Kluczowe dla wymagań:
 - `ai_runs` + `process_model_binding` → realizują **wymienialność modeli** i **audyt
  predykcji** (logi eksperymentu, §7.5).
 - `base_experiment_id` → realizuje **klonowanie** eksperymentu.
 - `target_group jsonb` → przechowuje profil grupy (wejście dla przyszłego warunkowania).
 ---
 ## 13. Kredyty, subskrypcje, przestrzeń dyskowa
 Z Koncepcji 0.1 wynika istnienie **kredytów/coinów** (globalnych i miesięcznych) oraz
 **przestrzeni dyskowej** zależnej od subskrypcji i rozszerzalnej za punkty. Wymaga to
 doprecyzowania modelu rozliczeń — propozycja ramowa (do potwierdzenia, **[?]**):
 | Element | Propozycja |
 |---|---|
 | Naliczanie za eksperyment | koszt zależny od typu analizy (ET < FC < ET+FC) i liczby kreacji (A/AB/ABC) |
 | Kredyty miesięczne | pula odnawialna w cyklu rozliczeniowym (zarządzana przez Super Admina) |
 | Kredyty globalne | pula dokupiona, nieodnawialna |
 | Przestrzeń dyskowa | limit z planu; rozszerzenie za kredyty wg cennika przestrzeni |
 | Plany subskrypcji | **niezdefiniowane w źródłach** — wymagają osobnej specyfikacji |
 Decyzje otwarte: cennik (ile kredytów za co), polityka wygasania kredytów, obsługa
 przekroczenia limitów, fakturowanie. → `Pytania do koncepcji.md`.
 ---
 ## 14. Logi i audyt
 Dwa poziomy:
 - **Logi systemowe** (panel administracyjny) — filtrowanie po użytkowniku, organizacji,
  zakresie dat, typie operacji.
 - **Logi eksperymentu** (Super Admin) — pełen ślad: działania i ustawienia użytkownika +
  **wszystkie dane wysłane/odebrane z modeli AI**. Powiązane z `ai_runs` (§12): każda
  predykcja zapisuje proces, model, żądanie i referencję odpowiedzi → audyt i powtarzalność,
  szczególnie po podmianie modelu (§10).
 ---
 ## 15. Bezpieczeństwo, prywatność, zgodność
 - **Brak danych respondentów:** produkt generuje **predykcje AI**, nie zbiera danych od
  realnych osób — to istotnie obniża ryzyko RODO względem klasycznego eye-trackingu.
  Dane osobowe ograniczają się do **kont użytkowników** (auth Supabase).
 - **Własność treści:** kreacje klientów to materiały chronione — kontrola dostępu na poziomie
  organizacji/projektu; izolacja danych między organizacjami (RLS w Supabase — zalecane).
 - **Sekrety:** klucze i hosty modeli poza kodem (vault / zmienne środowiskowe), nie w repo.
 - **Dane wysyłane do modeli publicznych:** przy podmianie na Gemini/Opus kreacje opuszczają
  infrastrukturę własną → wymagana zgoda klienta i zapis w politykach. **[?]**
 - **Profile wrażliwe:** kategoria **neuroatypowość** (ASD/ADHD/depresja) to dane wrażliwe
  w warstwie *konfiguracji predykcji* (nie dotyczą realnych osób), ale komunikacja wyników
  powinna unikać sugestii diagnostycznych. **[?]**
 ---
 ## 16. Internacjonalizacja
 - **Języki UI w MVP 1.0:** polski, angielski (kolejne w następnych wersjach).
 - **Język raportu / interpretacji kognitywnej:** powinien podążać za locale użytkownika —
  warstwa interpretacji (LLM) generuje tekst w wybranym języku. **[?]**
 - **Prompt ASM:** obecnie po angielsku (`"Describe the image in the style of a polished
  marketing ad."`) — traktowany jako **parametr konfigurowalny** (nie stała), niezależny od
  języka UI.
 ---
 ## 17. Przepływy użytkownika (use case'y)
 ### UC1 — Eksperyment ABC bez zmian w Studio (obiekty/AOI z AI)
 1. Rejestracja → 2. Logowanie → 3. Utworzenie organizacji → 4. Dodanie kreacji do Galerii →
 5. Nowy projekt → eksperyment: cel + grupa docelowa, typ **ABC** + 3 kreacje, parametry,
 **bez** zmian w Studio → 6. Generowanie raportu → 7. Eksport **PDF** → 8. Udostępnienie
 (Editor/Viewer) → 9. „Zmień ten eksperyment" → nowa nazwa → Krok 1 z prekonfiguracją.
 ### UC2 — Eksperyment ABC ze zmianami w Studio + segment
 Jak UC1, z konkretną grupą docelową (np. Młodzież / Kobieta / miasto do 19 tys. / wyższe /
 dochód średni / neurotypowy), celem „Która kreacja lepiej sprzedaje?", **ET+FC**, 3 kreacje,
 obiekty/AOI wskazane przez AI (z możliwą korektą), eksport **PDF + XLS + AVI**, udostępnienie
 1× Editor i 1× Viewer, oraz „Edytuj" jako baza kolejnego eksperymentu.
 > UC2 uruchamia komponenty roadmapowe (FC, XLS metryk, AVI dynamiczne) — w MVP zrealizowany
 > w zakresie dostępnych metryk ET-static, z resztą oznaczoną jako „wkrótce". **[?]**
 ---
 ## 18. Zakres MVP 1.0 vs roadmapa
 ### ✅ W zakresie MVP 1.0
 - Platforma SaaS: organizacje, role/uprawnienia, projekty, galeria (org + projekt), eksperymenty.
 - Kreator eksperymentu (4 kroki), słowniki celów / obiektów / AOI / grup docelowych.
 - Studio: ręczne i AI-wspomagane obiekty/AOI (LLaVA + Grounding DINO).
 - Pipeline AI: detekcja obiektów + **saliency statyczna z 3 modeli** (DeepGaze, UNISAL, ASM)
  z walidacją krzyżową i wizualizacjami (overlay, nakładka, porównanie 2×2).
 - Metryki **udziału uwagi na AOI** i porównanie wariantów; raport + eksport PDF.
 - Panel administracyjny: organizacje, użytkownicy, **wymiana modeli AI (Proces ↔ Model)**, logi.
 - Warstwa interpretacji kognitywnej (rekomendacja z uzasadnieniem) — **do zbudowania**, ale
  należy do rdzenia wartości MVP (bez niej raport jest zbiorem liczb). **[?] priorytet.**
 ### 🟡 Roadmapa (kolejne wersje — §11 specyfikacji procesu AI)
 - **Facial Coding / mapa emocji** (walencja, pobudzenie, frustracja, ambiwalencja, komfort…).
 - **Mapy cieplne dynamiczne 1–20s** (saliency w interwałach czasu).
 - **Ścieżki fiksacji (scanpath)** i pełna **„ścieżka AOI"** z sekwencją czasową.
 - **Predykcje różnicowane per grupa docelowa** (warunkowanie modelu demografią).
 - Eksporty **XLS / AVI**, kolejne języki UI.
 ### 🔑 Rekomendacja zakresowa
 MVP powinno **dowieźć pętlę wartości** dla podzbioru celów silnie ET (np. #2 „Czy odbiorca
 widzi przekaz?", #7 „Czy przekaz jest zrozumiały?", częściowo #1/#3) — tam obecny pipeline
 daje wiarygodne metryki. Cele zależne od emocji i czasu zaprezentować jako „wkrótce", aby nie
 obiecywać wyników, których pipeline jeszcze nie liczy. Ostateczna lista celów MVP →
 decyzja właściciela produktu.
 ---
 *Dokument roboczy v0.2. Miejsca [?] wymagają decyzji — zebrane w `Pytania do koncepcji.md`.*
--- a/kognitywnych.md
+++ b/kognitywnych.md
--- a/Opis-procesow-AI-n8n.md
+++ b/Opis-procesow-AI-n8n.md
@ -0,0 +1,251 @@
 # Procesy AI w workflow n8n „v1.6 Test"
 > Dokument opisuje **procesy realizowane za pomocą modeli AI** w przepływie
 > zdefiniowanym w pliku `n8n.json` (workflow n8n o nazwie **„v1.6 Test"**).
 > Skupia się na węzłach wywołujących modele uczenia maszynowego; węzły pomocnicze
 > (merge, code, sticky notes) opisano tylko w zakresie potrzebnym do zrozumienia
 > przepływu danych.
 ---
 ## 1. Cel i charakter systemu
 Workflow przyjmuje **pojedynczy obraz** (np. kreację reklamową / grafikę marketingową)
 przesłany przez formularz, a następnie przepuszcza go równolegle przez **pięć modeli AI**.
 Efektem jest zestaw analiz **predykcyjnych dotyczących uwagi wzrokowej i zawartości obrazu** —
 de facto „syntetyczny eye-tracking", czyli przewidywanie, **co** znajduje się na grafice
 i **gdzie** skupi się wzrok odbiorcy, jeszcze przed badaniem z udziałem realnych użytkowników.
 Wyniki są prezentowane jako interaktywne strony HTML (overlay z suwakiem przezroczystości,
 siatka porównawcza, wizualizacja bounding boxów).
 Notatki (sticky notes) w workflow wskazują, że docelowo system ma obejmować również:
 mapę cieplną w interwałach czasowych, ścieżki fiksacji oraz mapę emocji (patrz sekcja 6).
 ---
 ## 2. Architektura przepływu danych
 ```
        ┌─────────────────────┐
        │  Form input data    │  (upload obrazu przez formularz)
        └─────────┬───────────┘
                  │
      ┌───────────┼───────────────────────────────┐
      │           │                               │
      ▼           ▼                               ▼
 ┌─────────┐  ┌──────────────┐            ┌──────────────────┐
 │ base64  │  │ Credentials  │            │     Merge2       │
 │(do b64) │  │ (Data Table) │──────────► │ (łączy dane +    │
 └────┬────┘  └──────────────┘            │  URL + token)    │
      │                                   └────────┬─────────┘
      │   rozsyła obraz + poświadczenia do 5 modeli AI:
      ▼
 ┌──────────────────────────────────────────────────────────────────┐
 │  [AI-1] LLaVA  ──► Labels string ──► [AI-2] Grounding DINO        │
 │  [AI-3] DeepGaze                                                  │
 │  [AI-4] unisal                                                    │
 │  [AI-5] asmModel                                                  │
 └──────────────────────────────────────────────────────────────────┘
      │              │            │            │
      ▼              ▼            ▼            ▼
 Object Detection   Inverted    Merge6 ──► Inverted heatmap – Compare
   (HTML boxy)      heatmap      (siatka 2×2: DeepGaze / unisal /
                    (HTML)        asmModel detailed / asmModel general)
 ```
 - **Wejście:** `Form input data` (`formTrigger`) — pole typu *file*.
 - **Poświadczenia:** węzeł `Credentials` (`dataTable`, operacja *get*) pobiera z tabeli danych
  adresy URL serwerów modeli (`LLaVA`, `Grounding_DINO`, `DeepGaze`) oraz `Token`
  (autoryzacja `Bearer` / nagłówek `X-API-Key`).
 - **Dystrybucja:** `Merge2` łączy obraz (jako binarny + base64 w polu `image_input`)
  z poświadczeniami i rozsyła go równolegle do wszystkich modeli.
 ---
 ## 3. Modele AI i realizowane procesy
 W workflow działa **pięć** węzłów wywołujących modele AI (wszystkie to żądania HTTP POST
 do dedykowanych mikroserwisów modelowych). Poniżej opis każdego procesu.
 ### 3.1. LLaVA — ekstrakcja typów obiektów (proces „Object Listing")
 | Atrybut | Wartość |
 |---|---|
 | Węzeł | `LLaVA-based object types extractor` (`httpRequest`) |
 | Endpoint | `POST http://{{LLaVA}}/llava-api/v1/get-object-types` |
 | Parametry | `temperature = 0.2`, `top_p = 0.9`, `image` (binarnie) |
 | Typ modelu | Multimodalny model wizualno-językowy (VLM, *Large Language-and-Vision Assistant*) |
 | Obsługa błędu | `continueRegularOutput` (przepływ nie zatrzymuje się przy błędzie) |
 **Co robi:** model „ogląda" obraz i zwraca **listę typów obiektów** (etykiet/kategorii),
 które się na nim znajdują — w trybie otwartego słownika (open-vocabulary). Niska temperatura
 (0.2) zapewnia powtarzalne, deterministyczne odpowiedzi.
 **Rola w przepływie:** jest to **pierwszy etap detekcji obiektów**. Wynik trafia do węzła
 `Labels string` (code), który skleja etykiety w jeden ciąg rozdzielony przecinkami
 (`labels.join(", ")`) i przekazuje go dalej do modelu Grounding DINO.
 ---
 ### 3.2. Grounding DINO — detekcja obiektów / bounding boxy (proces „Object Detection")
 | Atrybut | Wartość |
 |---|---|
 | Węzeł | `Grounding DINO` (`httpRequest`) |
 | Endpoint | `POST http://{{Grounding_DINO}}/grounding-dino-api/v1/get-objects-bboxes` |
 | Parametry | `object_types` (etykiety z LLaVA), `max_objects = 50`, `base64 = false`, `image` |
 | Typ modelu | Otwarto-zbiorowa (zero-shot) detekcja obiektów sterowana tekstem (*open-set object detection / grounding*) |
 **Co robi:** otrzymuje obraz **oraz** listę etykiet wygenerowaną przez LLaVA i dla każdego
 wskazanego typu zwraca **ramki ograniczające** (`bbox_coords_xyxy`), nazwę typu (`object_type`)
 oraz pewność detekcji (`score`). Limit 50 obiektów.
 **Rola w przepływie:** **drugi etap detekcji** — lokalizuje na obrazie obiekty nazwane przez
 LLaVA. Połączenie LLaVA + Grounding DINO tworzy kompletny potok **open-vocabulary object
 detection** (jeden model nazywa, drugi wskazuje położenie).
 **Prezentacja wyniku:** węzeł `Object Detection` (code) generuje interaktywny plik HTML
 (`detection_viewer.html`) z kolorowymi ramkami nałożonymi na oryginał, dynamiczną paletą barw
 per typ obiektu, legendą, przyciskami filtrowania typów i wyświetlaniem `score` (%).
 Wymiary obrazu są odczytywane bezpośrednio z nagłówka PNG/JPEG.
 ---
 ### 3.3. DeepGaze — mapa uwagi / saliency (proces „Inverted heatmap – DeepGaze")
 | Atrybut | Wartość |
 |---|---|
 | Węzeł | `DeepGaze` (`httpRequest`) |
 | Endpoint | `POST http://{{DeepGaze}}/v1/predict-heatmap` |
 | Parametry | `image` (binarnie) |
 | Typ modelu | Model predykcji saliency / uwagi wzrokowej (przewidywanie ludzkiego spojrzenia) |
 | Obsługa błędu | `continueRegularOutput` |
 **Co robi:** przewiduje **mapę cieplną uwagi (saliency map)** — rozkład prawdopodobieństwa,
 w które rejony obrazu skieruje się wzrok człowieka. Model zwraca obraz heatmapy
 zakodowany w base64 (`heatmap_b64`, `heatmap_mime`, `width`, `height`).
 **Rola w przepływie:** to **pierwszy z trzech modeli uwagi**. Wynik:
 - węzeł `Image` (code) dekoduje `heatmap_b64` do binarnego PNG,
 - węzeł `Inverted heatmap` (code) generuje stronę HTML (`heatmap_viewer.html`) z heatmapą
  nałożoną na oryginał i **suwakiem przezroczystości** (podgląd „oryginał ↔ mapa uwagi"),
 - wynik trafia także do `Merge6` (porównanie zbiorcze, sekcja 4).
 ---
 ### 3.4. UNISAL — mapa uwagi / saliency (model porównawczy)
 | Atrybut | Wartość |
 |---|---|
 | Węzeł | `unisal - inverted heatmap` (`httpRequest`) |
 | Endpoint | `POST http://1.208.108.242:58951/unisal/process-image?as_base64=true` |
 | Autoryzacja | nagłówek `X-API-Key` = `{{ Token }}` |
 | Parametry | `file` (obraz, binarnie) |
 | Typ modelu | Zunifikowany model saliency dla obrazu i wideo (*UNIfied SALiency*) |
 | Obsługa błędu | `continueRegularOutput` |
 **Co robi:** alternatywna **predykcja mapy uwagi**, zwracana jako obraz base64 (pole `data`,
 `mimetype`). Stanowi drugie, niezależne źródło saliency obok DeepGaze.
 **Rola w przepływie:** wynik trafia do `Merge6` (wejście 2) i jest zestawiany z pozostałymi
 modelami w widoku porównawczym (sekcja 4).
 ---
 ### 3.5. asmModel (ASM) — mapy uwagi + warunkowanie opisem marketingowym (model centralny)
 | Atrybut | Wartość |
 |---|---|
 | Węzeł | `asmModel - inverted heatmap` (`httpRequest`) |
 | Endpoint | `POST http://1.208.108.242:58951/asmModel/process-image` |
 | Autoryzacja | nagłówek `X-API-Key` = `{{ Token }}` |
 | Parametry (query) | `prompt = "Describe the image in the style of a polished marketing ad."`, `as_raw_output = false`, `max_new_tokens = 100` |
 | Parametry (body) | `file` (obraz, binarnie) |
 | Typ modelu | Autorski/proprietarny model uwagi (ASM), warunkowany tekstowym promptem, generujący dwie mapy uwagi |
 | Obsługa błędu | `continueRegularOutput` |
 **Co robi:** model zwraca **dwie mapy uwagi** — szczegółową (`image_detailed`) i ogólną
 (`image_general`) — wraz z `mimetype`. Obecność parametrów `prompt` oraz `max_new_tokens`
 wskazuje, że jest to model **multimodalny warunkowany tekstem**: predykcja uwagi jest
 osadzona w kontekście „dopracowanej reklamy" (*polished marketing ad*).
 > **Uwaga interpretacyjna:** dokładna architektura `asmModel` nie wynika wprost z pliku
 > (to wewnętrzny mikroserwis pod adresem `1.208.108.242:58951`). Na podstawie konfiguracji
 > (prompt marketingowy + `max_new_tokens` + dwie mapy uwagi) jest to **kluczowy, autorski
 > model projektu** (nazwa katalogu projektu: *ASM PNS C*), łączący predykcję saliency
 > z warunkowaniem językowym. Opis bazuje na obserwowalnych parametrach żądania.
 **Rola w przepływie:** wynik trafia do `Merge6` (wejście 3) i dostarcza dwa z czterech
 kafelków widoku porównawczego.
 ---
 ## 4. Proces zestawienia i porównania wyników AI
 | Węzeł | Funkcja |
 |---|---|
 | `Merge6` (4 wejścia) | Łączy: [0] oryginał (base64), [1] DeepGaze, [2] unisal, [3] asmModel |
 | `Inverted heatmap - Compare` (code) | Generuje HTML (`inverted_heatmap.html`) — **siatkę 2×2** porównującą cztery mapy uwagi |
 W widoku porównawczym (`Inverted heatmap - Compare`) zestawiane są obok siebie cztery wyniki
 modeli uwagi: **DeepGaze**, **unisal**, **asmModel detailed**, **asmModel general**.
 Strona renderuje tzw. **inwersję heatmapy** w technice pikselowego blendu na `<canvas>`:
 suwak miesza oryginał z mapą luminancji uwagi (biel = wysoka uwaga, czerń = niska),
 co daje efekt „reflektora" pokazującego rejony przyciągające wzrok.
 Dzięki temu proces AI ma wbudowaną **walidację krzyżową** — trzy niezależne modele saliency
 (DeepGaze, unisal, ASM) można porównać na jednej grafice.
 ---
 ## 5. Podsumowanie tabelaryczne procesów AI
 | # | Model AI | Proces / zadanie | Wejście | Wyjście | Wizualizacja |
 |---|---|---|---|---|---|
 | 1 | **LLaVA** | Rozpoznanie i wylistowanie typów obiektów (VLM) | obraz | lista etykiet | (etap pośredni) |
 | 2 | **Grounding DINO** | Detekcja i lokalizacja obiektów (bounding boxy) | obraz + etykiety z LLaVA | ramki + score | `Object Detection` (HTML) |
 | 3 | **DeepGaze** | Predykcja mapy uwagi (saliency) | obraz | heatmapa (base64) | `Inverted heatmap` (HTML, suwak) |
 | 4 | **UNISAL** | Predykcja mapy uwagi (model porównawczy) | obraz | heatmapa (base64) | `Inverted heatmap – Compare` |
 | 5 | **asmModel (ASM)** | Predykcja uwagi (detailed + general) z warunkowaniem promptem marketingowym | obraz + prompt | 2 mapy uwagi | `Inverted heatmap – Compare` |
 **Dwa główne typy procesów AI:**
 1. **Rozumienie zawartości obrazu** — co jest na grafice i gdzie (LLaVA → Grounding DINO).
 2. **Predykcja uwagi wzrokowej** — gdzie spojrzy odbiorca (DeepGaze, UNISAL, asmModel),
   z możliwością porównania trzech modeli.
 ---
 ## 6. Procesy planowane (notatki bez podłączonych węzłów)
 W workflow znajdują się notatki (sticky notes) opisujące **kolejne, jeszcze niezaimplementowane
 etapy** analizy uwagi (brak podłączonych węzłów, pozycje w dolnej części płótna):
 - **Heatmap** — mapa cieplna,
 - **Interwały** — „30 sek, 6 obrazów", „20 sek. do 0,5 sekundy" (analiza uwagi w przedziałach czasu),
 - **Ścieżki fiksacji** — przewidywana sekwencja ruchów oka (scanpath),
 - **Mapa emocji** — predykcja reakcji emocjonalnej.
 Wskazują one na docelowy kierunek rozwoju: pełen **syntetyczny eye-tracking** kreacji
 reklamowych (mapa uwagi → interwały czasowe → ścieżki fiksacji → mapa emocji).
 ---
 ## 7. Węzły pomocnicze (nie-AI)
 Dla kompletności — elementy obsługujące przepływ, które **nie** są modelami AI:
 - `Form input data` — formularz wejściowy (upload obrazu).
 - `Credentials` (Data Table) — pobranie adresów URL modeli i tokenu autoryzacyjnego.
 - `base64` (Extract from File) — konwersja obrazu do base64 (`image_input`).
 - `Labels string` (Code) — sklejenie etykiet LLaVA w ciąg dla Grounding DINO.
 - `Image` (Code) — dekodowanie heatmapy DeepGaze do PNG.
 - `Merge` / `Merge1` / `Merge2` / `Merge5` / `Merge6` — synchronizacja i łączenie strumieni danych.
 - `Object Detection`, `Inverted heatmap`, `Inverted heatmap - Compare` (Code) — generowanie
  interaktywnych raportów HTML (prezentacja wyników, bez logiki AI).
 - `Sticky Note*` — komentarze/notatki na płótnie.
 ---
 *Workflow: `v1.6 Test` · status: nieaktywny (`active: false`) · `executionOrder: v1`.*
 *Opis wygenerowany na podstawie analizy pliku `n8n.json`.*
--- a/koncepcji.md
+++ b/koncepcji.md
@ -0,0 +1,188 @@
 # Pytania do koncepcji AdReactions (v0.2)
 > Lista kwestii wymagających decyzji właściciela produktu. Pytania wynikają z analizy
 > dokumentów źródłowych projektu i ich wzajemnych **rozbieżności oraz luk**. Każde pytanie
 > ma kontekst, proponowaną odpowiedź roboczą (do akceptacji/zmiany) i odwołanie do sekcji
 > w `Koncepcja 0.2 - rozszerzona.md`.
 >
 > Pogrupowano wg priorytetu wpływu na zakres MVP.
 ---
 ## 🔴 Priorytet 1 — przesądzają o zakresie i wiarygodności MVP
 ### Q1. Facial Coding w MVP — jest czy nie ma?
 **Kontekst:** Katalog celów i kreator zakładają analizę **FC / ET+FC** (walencja, pobudzenie,
 frustracja, ambiwalencja, komfort…). Tymczasem specyfikacja procesu AI obejmuje obecnie
 wyłącznie detekcję obiektów i predykcję uwagi (saliency); **mapa emocji jest pozycją roadmapy
 (§11 specyfikacji)** — nie ma jeszcze modelu Facial Coding.
 **Pytanie:** Czy MVP 1.0 ma realnie liczyć metryki Facial Coding? Jeśli tak — jaki model/usługa
 je dostarczy i kiedy będzie dostępny? Jeśli nie — czy ukrywamy opcje FC/ET+FC, czy pokazujemy je
 jako „wkrótce"?
 **Propozycja robocza:** MVP dostarcza **ET (saliency statyczna)**; opcje FC oznaczone „wkrótce".
 *(§9.4, §9.5, §18)*
 ### Q2. Wymiar czasu — „czas obserwacji 1–20s", mapy dynamiczne, scanpath
 **Kontekst:** Obecne modele zwracają **jedną, statyczną** mapę uwagi. Raport zakłada
 „wizualizacje statyczne 1/3/5/10/15/20s", „mapy dynamiczne 1–20s" i „ścieżki fiksacji" —
 wszystko to wymaga **saliency czasowej / scanpath**, które są w roadmapie.
 **Pytanie:** Czy parametr „czas obserwacji" i wizualizacje czasowe są w zakresie MVP? Jeśli nie —
 czy pokazujemy pojedynczą mapę zagregowaną i ukrywamy oś czasu?
 **Propozycja robocza:** MVP = jedna mapa statyczna; oś czasu w roadmapie. *(§7.2, §9.5, §11.1)*
 ### Q3. Predykcje per grupa docelowa — jak technicznie?
 **Kontekst:** Kreator zbiera bogaty profil grupy (wiek, płeć, miejsce, wykształcenie, dochód,
 neuroatypowość, presety). `Opis celów…` zakłada, że ASM PNS generuje **różne predykcje dla
 różnych segmentów**. Ale pipeline **nie przyjmuje demografii na wejściu** — żaden endpoint nie
 ma takiego parametru.
 **Pytanie:** Jak grupa docelowa ma wpływać na wynik? Opcje: (a) przez `prompt` modelu ASM,
 (b) osobne wagi/warianty modelu per segment, (c) w MVP grupa jest tylko **metadanymi raportu**
 bez wpływu na predykcję.
 **Propozycja robocza:** w MVP (c) — grupa opisuje kontekst i interpretację, nie zmienia mapy
 uwagi; różnicowanie per segment → roadmapa. *(§7.1, §9.4, §9.5)*
 ### Q4. „Analiza kognitywna" (rekomendacja z uzasadnieniem) — kto/co ją generuje?
 **Kontekst:** Rdzeń wartości produktu to zdanie typu „Wariant B wygrywa, ponieważ…". To **nowy
 komponent** (warstwa interpretacji LLM nad metrykami) — nie istnieje w pipeline.
 **Pytanie:** Czy budujemy tę warstwę w MVP? Jaki model ją realizuje (ASM? publiczny LLM?), na
 jakich danych wejściowych (metryki + cel + grupa), z jakimi zabezpieczeniami przed „halucynacją"
 rekomendacji?
 **Propozycja robocza:** TAK, to priorytet MVP; realizacja przez LLM z **ustrukturyzowanym
 wejściem** (policzone metryki), nie przez „opowieść" o obrazie. *(§9.4, §11.1, §18)*
 ### Q5. Zakres celów w MVP
 **Kontekst:** 15 celów; większość rekomenduje **ET+FC**. Bez FC i wymiaru czasu część celów
 nie jest w pełni wykonalna (§9.5).
 **Pytanie:** Które z 15 celów udostępniamy w MVP 1.0?
 **Propozycja robocza:** start od celów silnie ET (#2, #7, #1, #3), reszta „wkrótce". *(§8, §18)*
 ---
 ## 🟠 Priorytet 2 — architektura i wymienialność modeli
 ### Q6. Warstwa metryk — potwierdzenie zakresu i miejsca liczenia
 **Kontekst:** Metryki „udziału uwagi na AOI" powstają z **przecięcia map saliency z obszarami
 AOI** — to komponent backendu, a nie wynik zwracany przez modele (modele dostarczają mapy uwagi).
 **Pytanie:** Potwierdzamy, że backend liczy metryki z map saliency (saliency ∩ AOI), a modele
 dostarczają wyłącznie mapy? Jaka jest dokładna lista wskaźników w MVP?
 **Propozycja robocza:** tak; MVP liczy udział uwagi na AOI, ranking AOI i porównanie wariantów
 (zakres ET-static). *(§9.5, §11.1)*
 ### Q7. Zakres wymienialności modeli (info.md)
 **Kontekst:** Wymóg: zmiana modelu na inny (Gemini, Opus). Modele saliency/FC są jednak
 wyspecjalizowane — publiczny LLM nie zastąpi ich 1:1.
 **Pytanie:** Które procesy mają być wymienialne w MVP? Tylko „rozumienie treści” (etykiety/opis:
 LLaVA↔Gemini/Opus), czy też predykcja uwagi (co wymaga modeli saliency innego dostawcy)?
 **Propozycja robocza:** wymienialność w MVP dla procesów językowo-wizualnych; predykcja uwagi
 pozostaje na modelach własnych (ASM jako rdzeń). *(§10.1, §10.4)*
 ### Q8. Konfiguracja modeli — gdzie i jak zarządzana?
 **Kontekst:** Konfiguracja modeli (hosty, token/klucz, parametry) nie powinna być zaszyta w
 kodzie ani w konfiguracji testowej — w MVP zarządzana z panelu administracyjnego.
 **Pytanie:** Czy akceptujemy model „Proces ↔ Model" z adapterami, konfiguracją sekretów w panelu,
 testem połączenia i wersjonowaniem przypisania (dla audytu, który model policzył raport)?
 **Propozycja robocza:** TAK (§10.2–10.3, encje `ai_processes` / `ai_models` /
 `process_model_binding` w §12). *(§10, §12)*
 ### Q9. Obiekty vs AOI — skąd biorą się AOI semantyczne?
 **Kontekst:** Pipeline wykrywa **obiekty** (LLaVA+DINO). AOI to **obszary marketingowe**
 (CTA, Logo…). To inna kategoria niż „osoba/butelka".
 **Pytanie:** AOI w MVP są: (a) wyłącznie ręczne (Studio), (b) AI sugeruje AOI osobnym modelem,
 (c) mapowane heurystycznie z wykrytych obiektów?
 **Propozycja robocza:** MVP — AOI ręczne + ewentualne podpowiedzi z obiektów; pełna „AI-detekcja
 AOI” to osobny model. *(§7.3, §11.1)*
 ---
 ## 🟡 Priorytet 3 — spójność dokumentów i reguły produktowe
 ### Q10. Typy testu: A/AB/ABC czy A/AB/AC/BC/ABC?
 **Kontekst:** Koncepcja 0.1 raz podaje **A/AB/ABC** (Krok 2), a w use case 2 i `Opis celów…`
 pojawia się **A/AB/AC/BC/ABC**.
 **Pytanie:** Który zestaw obowiązuje? Czy potrzebne są wszystkie pary (AC, BC), czy slot A/B/C
 jest stały?
 **Propozycja robocza:** pełny zestaw A/AB/AC/BC/ABC (większa elastyczność porównań). *(§7.2)*
 ### Q11. Próg wieku „Seniorzy"
 **Kontekst:** W jednym miejscu „Seniorzy (66 i więcej)”, opis grup mówi „Dorośli 26–64” →
 luka 65 lat.
 **Pytanie:** Ustalić progi bez luki (proponowane: Senior **65+**). *(§7.1)*
 ### Q12. Limit „jednej nowej organizacji" na użytkownika
 **Kontekst:** „może dodać tylko jedną nową organizację”.
 **Pytanie:** Czy to limit **zakładanych** organizacji (1 własna), czy łącznej **przynależności**?
 Czy użytkownik może należeć do wielu organizacji przez zaproszenia?
 **Propozycja robocza:** użytkownik zakłada max 1 organizację, ale może być członkiem wielu przez
 zaproszenia. *(§3, §5, §6.2)*
 ### Q13. Rola „Gość" — zakres
 **Kontekst:** Gość wymieniony w strukturze, bez zdefiniowanych uprawnień.
 **Pytanie:** Co może gość? Propozycja: tylko podgląd udostępnionych raportów, bez tworzenia treści
 i bez dostępu do rozliczeń. *(§5.1, §5.2)*
 ### Q14. Role projektowe — ujednolicenie
 **Kontekst:** Koncepcja wymienia różne warianty („Editor/Viewer” oraz „usuwanie/edycja/
 zapraszanie / edycja/zapraszanie / przeglądanie”).
 **Pytanie:** Ile ról projektowych i jakie dokładnie uprawnienia? Propozycja: **Editor** /
 **Viewer** (+ ewentualnie **Manager** z prawem usuwania i zarządzania dostępem). *(§5.2)*
 ---
 ## 🟢 Priorytet 4 — rozliczenia, eksport, prawne, i18n
 ### Q15. Model rozliczeń (kredyty/coiny)
 **Pytanie:** Cennik eksperymentu (zależny od ET/FC/ET+FC i liczby kreacji?), zasady kredytów
 miesięcznych vs globalnych, wygasanie, zachowanie przy przekroczeniu limitu, fakturowanie.
 Brak danych w źródłach. *(§13)*
 ### Q16. Plany subskrypcji i przestrzeń dyskowa
 **Pytanie:** Jakie plany (nazwy, limity, ceny)? Cennik rozszerzenia dysku w kredytach? *(§13)*
 ### Q17. Eksport XLS / AVI
 **Kontekst:** Use case 2 wymaga XLS (tabele metryk) i AVI (dynamiczne mapy/ścieżki).
 **Pytanie:** Czy w MVP? AVI zależy od wizualizacji czasowych (Q2). Propozycja: PDF w MVP;
 XLS gdy są metryki tabelaryczne; AVI z roadmapą czasową. *(§11.3)*
 ### Q18. Udostępnianie raportu linkiem — publiczne czy z logowaniem?
 **Pytanie:** „Link do eksperymentu” to dostęp publiczny (każdy z linkiem), czy wymaga konta i
 nadanej roli (Editor/Viewer)? Implikacje dla bezpieczeństwa treści klienta. *(§11.3, §15)*
 ### Q19. Dane wysyłane do modeli publicznych (Gemini/Opus)
 **Kontekst:** Podmiana na publiczny model = kreacje opuszczają infrastrukturę własną.
 **Pytanie:** Czy wymagana zgoda klienta / oznaczenie w organizacji, że dany proces korzysta z
 modelu zewnętrznego? *(§10.4, §15)*
 ### Q20. Kategoria „neuroatypowość” — komunikacja i zgodność
 **Pytanie:** Jak prezentować wyniki dla profili ASD/ADHD/depresja, by nie sugerować diagnozy?
 Czy model w ogóle różnicuje predykcje wg neuroatypowości (powiązane z Q3)? *(§7.1, §15)*
 ### Q21. Język raportu i interpretacji
 **Pytanie:** Czy tekst rekomendacji (warstwa kognitywna) podąża za locale użytkownika (PL/EN)?
 Czy prompt ASM zależy od języka, czy pozostaje stały (obecnie EN)? *(§16)*
 ---
 ## ℹ️ Pytania uzupełniające (do potwierdzenia kontraktów)
 ### Q22. Kontrakty odpowiedzi usług AI
 W `Specyfikacja-procesu-AI.md` kształty odpowiedzi oznaczono „(wnioskowane)”. **Pytanie:** Czy
 istnieje dokumentacja/realne odpowiedzi usług (LLaVA, DINO, DeepGaze, UNISAL, ASM) do
 potwierdzenia pól (`labels`, `objects_bboxes`, `heatmap_b64`, `data`, `image_detailed/general`)?
 ### Q23. Model ASM PNS — faktyczny zakres
 **Kontekst:** ASM zwraca **2 mapy uwagi** (detailed/general), ale `Opis celów…` przypisuje mu też
 predykcję **pobudzenia emocjonalnego / zapamiętywalności**. **Pytanie:** Co dokładnie ASM PNS
 potrafi dziś, a co jest planem? Czy „detailed/general” odpowiadają jakimś pojęciom produktowym?
 ### Q24. Hosting i dostępność modeli
 **Kontekst:** UNISAL i ASM współdzielą jeden host (`1.208.108.242:58951`).
 **Pytanie:** Jaka jest docelowa infrastruktura produkcyjna (SLA, skalowanie, lokalizacja danych)?
 ### Q25. „Ścieżka AOI” w MVP — przybliżenie czy nic?
 **Pytanie:** Czy akceptujemy przybliżenie „ścieżki AOI” rankingiem AOI wg intensywności saliency
 (z adnotacją, że to nie jest prawdziwy scanpath), czy komponent czeka na model scanpath? *(§9.5)*
 ---
 *Po decyzjach: zaktualizować odpowiednie sekcje `Koncepcja 0.2 - rozszerzona.md` i usunąć
 znaczniki [?].*
--- a/Specyfikacja-procesu-AI.md
+++ b/Specyfikacja-procesu-AI.md
@ -0,0 +1,392 @@
 # Specyfikacja procesu: analiza uwagi wzrokowej kreacji reklamowych
 > Opis **logiki procesu** niezależny od narzędzia orkiestrującego, przeznaczony do
 > implementacji jako komponent oprogramowania (np. usługa backendowa / pipeline).
 > Definiuje: dane wejściowe, kontrakty zewnętrznych usług AI, kolejność i równoległość
 > wywołań, model danych wynikowych oraz logikę prezentacji.
 ---
 ## 1. Cel i zakres
 System przyjmuje **pojedynczy obraz** (kreację reklamową / grafikę) i zwraca zestaw analiz:
 1. **Rozumienie zawartości** — jakie obiekty są na obrazie i gdzie się znajdują.
 2. **Predykcja uwagi wzrokowej (saliency)** — gdzie skupi się wzrok odbiorcy; trzy
   niezależne modele dla walidacji krzyżowej.
 Wynikiem są dane (lista obiektów z ramkami, mapy uwagi) oraz pochodne wizualizacje.
 Proces jest **bezstanowy** — jedno wejście (obraz) → jeden komplet wyników.
 ---
 ## 2. Architektura logiczna
 ```
        ┌────────────────────┐
        │  Wejście: obraz    │
        └─────────┬──────────┘
                  ▼
        ┌────────────────────┐
        │  Preprocessing     │  bytes + base64 + mime + (w,h)
        └─────────┬──────────┘
                  │
   ┌──────────────┼───────────────┬───────────────┬───────────────┐
   ▼ (łańcuch A)                  ▼ (B)           ▼ (C)           ▼ (D)
 ┌──────────┐                  ┌──────────┐   ┌──────────┐   ┌──────────┐
 │ LLaVA    │                  │ DeepGaze │   │ UNISAL   │   │ ASM      │
 │ (etykiety)│                 │(saliency)│   │(saliency)│   │(2× saliency)
 └────┬─────┘                  └────┬─────┘   └────┬─────┘   └────┬─────┘
     ▼                             │              │              │
 ┌──────────────┐                   │              │              │
 │ Grounding    │                   │              │              │
 │ DINO (boxy)  │                   │              │              │
 └────┬─────────┘                   │              │              │
     │                             ▼              ▼              ▼
     ▼                       ┌──────────────────────────────────────┐
 ┌──────────────┐             │  Agregacja wyników saliency          │
 │ Wynik:       │             └──────────────────┬───────────────────┘
 │ detekcja     │                                ▼
 └──────────────┘                    ┌──────────────────────────┐
                                    │ Artefakty wyjściowe:     │
                                    │ • overlay boxów          │
                                    │ • nakładka heatmapy      │
                                    │ • porównanie 2×2         │
                                    └──────────────────────────┘
 ```
 **Kluczowe zależności:**
 - **Łańcuch A jest sekwencyjny:** Grounding DINO potrzebuje etykiet z LLaVA.
 - **Zadania B, C, D oraz cały łańcuch A są względem siebie niezależne** → wykonywane równolegle.
 - Punkt agregacji czeka na zakończenie wymaganych zadań przed złożeniem danego artefaktu.
 ---
 ## 3. Dane wejściowe i preprocessing
 **Wejście:** plik graficzny (PNG lub JPEG).
 **Preprocessing** — z jednego uploadu przygotuj reprezentację współdzieloną przez wszystkie usługi:
 ```
 ImageInput {
  bytes   : binary        // oryginalne bajty pliku (do multipart/form-data)
  base64  : string        // base64 bez prefiksu data: (do osadzania i obliczeń)
  mime    : "image/png" | "image/jpeg"
  width   : int
  height  : int
 }
 ```
 - `mime`, `width`, `height` ustal **standardową biblioteką** do obrazów
  (np. Pillow / `image-size` / `sharp`).
  > Uwaga: pierwotna implementacja parsowała nagłówki ręcznie (PNG: `width@offset16`,
  > `height@offset20` jako uint32 BE; JPEG: skan markerów `SOF0 0xC0` / `SOF2 0xC2`).
  > W docelowym kodzie użyj gotowej biblioteki — wymiary i tak są potrzebne tylko do
  > pozycjonowania ramek i renderowania (sekcja 7).
 - `base64` służy do: (a) osadzania oryginału w wizualizacjach, (b) blendu pikselowego.
 - `bytes` służy do wszystkich wywołań usług (pole multipart `image` lub `file`).
 ---
 ## 4. Wewnętrzny model danych (wyników)
 ```
 DetectionResult {
  objects : [ { object_type: string,
                bbox_xyxy:  [x1, y1, x2, y2],   // piksele, układ XYXY
                score:      float } ]            // 0..1
  model_id?  : string
  threshold? : float
 }
 SaliencyMap {
  source       : "deepgaze" | "unisal" | "asm_detailed" | "asm_general"
  image_base64 : string
  mime         : string
 }
 AnalysisResult {
  image     : ImageInput
  detection : DetectionResult
  saliency  : SaliencyMap[]    // 4 pozycje: deepgaze, unisal, asm_detailed, asm_general
 }
 ```
 ---
 ## 5. Zewnętrzne usługi AI — kontrakty API
 Wszystkie usługi to **HTTP POST** z ciałem `multipart/form-data` zawierającym obraz.
 Adresy hostów i token pochodzą z konfiguracji / magazynu sekretów (sekcja 8).
 Każde wywołanie powinno mieć skończony **timeout** i być **odporne na błędy** (sekcja 9).
 Kształty odpowiedzi oznaczone „(wnioskowane)" odtworzono na podstawie sposobu konsumpcji
 danych — przy implementacji potwierdź je z dokumentacją/realnymi odpowiedziami usług.
 ### 5.1. LLaVA — ekstrakcja typów obiektów
 Multimodalny model wizualno-językowy; zwraca listę kategorii obiektów widocznych na obrazie.
 ```
 POST http://{LLAVA_HOST}/llava-api/v1/get-object-types
 Headers:
  accept: application/json
  Authorization: Bearer {TOKEN}
 Body (multipart/form-data):
  temperature = 0.2        // niska → powtarzalność
  top_p       = 0.9
  image       = <plik>
 Odpowiedź (wnioskowane):
  { "labels": ["person", "bottle", "logo", ...] }
 ```
 **Transformacja po stronie klienta:** połącz `labels` w jeden ciąg rozdzielony przecinkami
 (`"person, bottle, logo"`) — wejście dla Grounding DINO.
 ### 5.2. Grounding DINO — detekcja obiektów (bounding boxy)
 Otwarto-zbiorowa (zero-shot) detekcja sterowana tekstem: dla podanych etykiet zwraca ramki.
 ```
 POST http://{GROUNDING_DINO_HOST}/grounding-dino-api/v1/get-objects-bboxes
 Headers:
  accept: application/json
  Authorization: Bearer {TOKEN}
 Body (multipart/form-data):
  object_types = "{labels_z_LLaVA}"   // np. "person, bottle, logo"
  max_objects  = 50
  base64       = false
  image        = <plik>
 Odpowiedź (wnioskowane):
  {
    "objects_bboxes": [
      { "object_type": "logo",
        "bbox_coords_xyxy": [x1, y1, x2, y2],
        "score": 0.87 }
    ],
    "model_id":  "...",   // opcjonalnie
    "threshold": 0.3,     // opcjonalnie
    "width":  839,        // opcjonalnie (fallback wymiarów)
    "height": 1190
  }
 ```
 ### 5.3. DeepGaze — mapa uwagi (saliency)
 Predykcja rozkładu uwagi wzrokowej; zwraca heatmapę zakodowaną base64.
 ```
 POST http://{DEEPGAZE_HOST}/v1/predict-heatmap
 Headers:
  accept: application/json
  Authorization: Bearer {TOKEN}
 Body (multipart/form-data):
  image = <plik>
 Odpowiedź (wnioskowane):
  { "heatmap_b64": "<base64>",
    "heatmap_mime": "image/png",
    "width": 839, "height": 1190,
    "model": "deepgaze..." }
 ```
 → mapuj na `SaliencyMap{ source:"deepgaze", image_base64:heatmap_b64, mime:heatmap_mime }`.
 ### 5.4. UNISAL — mapa uwagi (saliency, model porównawczy)
 ```
 POST http://{UNISAL_HOST}/unisal/process-image?as_base64=true
 Headers:
  accept: application/json
  X-API-Key: {TOKEN}
 Body (multipart/form-data):
  file = <plik>
 Odpowiedź (wnioskowane):
  { "data": "<base64>", "mimetype": "image/jpeg" }
 ```
 → `SaliencyMap{ source:"unisal", image_base64:data, mime:mimetype }`.
 ### 5.5. ASM (asmModel) — mapy uwagi z warunkowaniem promptem
 Model centralny: zwraca **dwie** mapy uwagi (szczegółową i ogólną), warunkowane tekstowym
 promptem osadzającym kontekst marketingowy.
 ```
 POST http://{ASM_HOST}/asmModel/process-image
     ?prompt=Describe the image in the style of a polished marketing ad.
     &as_raw_output=false
     &max_new_tokens=100
 Headers:
  accept: application/json
  X-API-Key: {TOKEN}
 Body (multipart/form-data):
  file = <plik>
 Odpowiedź (wnioskowane):
  { "image_detailed": "<base64>",
    "image_general":  "<base64>",
    "mimetype": "image/jpeg" }
 ```
 → dwa wpisy: `SaliencyMap{source:"asm_detailed",...}` oraz `SaliencyMap{source:"asm_general",...}`.
 > **Uwaga:** architektura ASM nie wynika z kontraktu — to wewnętrzny mikroserwis.
 > `prompt` i `max_new_tokens` sugerują model multimodalny warunkowany językiem.
 > Prompt potraktuj jako **parametr konfigurowalny**, nie stałą.
 ---
 ## 6. Orkiestracja
 Logika sterująca (zastępuje przepływ narzędzia) — uruchom niezależne gałęzie równolegle,
 zachowując jedyną zależność LLaVA → Grounding DINO.
 ```python
 async def analyze(image_bytes) -> AnalysisResult:
    img = preprocess(image_bytes)          # bytes, base64, mime, w, h
    async def detection_chain():
        labels = await llava_object_types(img.bytes)      # 5.1
        labels_str = ", ".join(labels)
        return await grounding_dino(img.bytes, labels_str) # 5.2
    # gałęzie niezależne — równolegle
    detection, deepgaze, unisal, asm = await gather(
        detection_chain(),                 # łańcuch A (sekwencyjny wewnątrz)
        deepgaze_heatmap(img.bytes),       # B
        unisal_saliency(img.bytes),        # C
        asm_saliency(img.bytes, PROMPT),   # D
        return_exceptions=True,            # patrz sekcja 9
    )
    saliency = [
        SaliencyMap("deepgaze",     deepgaze.heatmap_b64, deepgaze.heatmap_mime),
        SaliencyMap("unisal",       unisal.data,          unisal.mimetype),
        SaliencyMap("asm_detailed", asm.image_detailed,   asm.mimetype),
        SaliencyMap("asm_general",  asm.image_general,    asm.mimetype),
    ]
    return AnalysisResult(img, detection, saliency)
 ```
 **Zasady:**
 - Cztery gałęzie startują jednocześnie; całkowity czas ≈ czas najwolniejszej gałęzi.
 - Punkt agregacji łączy wyniki dopiero, gdy potrzebne gałęzie się zakończą.
 - Każdy artefakt wyjściowy zależy od konkretnego podzbioru wyników (sekcja 7) — można je
  generować, gdy tylko jego zależności są gotowe.
 ---
 ## 7. Warstwa prezentacji (artefakty wyjściowe)
 Trzy artefakty. Można je renderować **po stronie klienta** (HTML/Canvas — jak w oryginale)
 lub **serwerowo** komponować obrazy (Pillow / sharp / canvas). Poniżej logika niezależna od wyboru.
 ### 7.1. Wizualizacja detekcji obiektów
 **Zależności:** oryginał + `DetectionResult`.
 - Dla każdego obiektu narysuj ramkę z `bbox_xyxy`, podpis `"{object_type} {score%}"`.
 - Kolor per typ obiektu (paleta cykliczna; ten sam typ = ten sam kolor).
 - Pozycje przeliczaj na **procenty** wymiarów obrazu (`x1/width`, `y1/height`, …),
  aby skalowały się responsywnie.
 - Opcjonalnie: filtry pokazujące/ukrywające typy, legenda, licznik obiektów.
 ### 7.2. Nakładka pojedynczej mapy uwagi
 **Zależności:** oryginał + jedna `SaliencyMap` (np. DeepGaze).
 - Heatmapa nałożona na oryginał z **regulowaną przezroczystością** (suwak 0–100%).
 ### 7.3. Porównanie map uwagi (siatka 2×2)
 **Zależności:** oryginał + 4 mapy (`deepgaze`, `unisal`, `asm_detailed`, `asm_general`).
 - Cztery kafelki, wspólny suwak intensywności, technika „inwersji" (7.4).
 ### 7.4. Algorytm „inwersji" heatmapy (blend luminancji)
 Wspólna logika nakładek. Dla parametru `t ∈ [0,1]` (intensywność / pozycja suwaka):
 ```
 # Z heatmapy licz luminancję (jasność uwagi) 0..1:
 lum = (0.299*R + 0.587*G + 0.114*B) / 255
 # Blend per kanał (RGB), per piksel:
 out = orig * (1 - t) + (lum * 255) * t
 ```
 - `t = 0` → czysty oryginał; `t = 1` → maska uwagi w skali szarości
  (biel = wysoka uwaga, czerń = niska) → efekt „reflektora".
 - Wymaga zgodności rozdzielczości oryginału i heatmapy (w razie potrzeby przeskaluj heatmapę).
 ---
 ## 8. Konfiguracja i sekrety
 Wynieś poza kod (zmienne środowiskowe / vault):
 | Klucz | Opis |
 |---|---|
 | `LLAVA_HOST` | host usługi LLaVA |
 | `GROUNDING_DINO_HOST` | host usługi Grounding DINO |
 | `DEEPGAZE_HOST` | host usługi DeepGaze |
 | `UNISAL_HOST` | host usługi UNISAL (w oryginale `1.208.108.242:58951`) |
 | `ASM_HOST` | host usługi ASM (w oryginale ten sam host co UNISAL) |
 | `TOKEN` | poświadczenie (Bearer dla LLaVA/DINO/DeepGaze; `X-API-Key` dla UNISAL/ASM) |
 | `ASM_PROMPT` | prompt warunkujący ASM (domyślnie marketingowy) |
 | `MAX_OBJECTS` | limit detekcji (domyślnie 50) |
 > Dwa schematy autoryzacji: **`Authorization: Bearer`** (LLaVA, Grounding DINO, DeepGaze)
 > vs **`X-API-Key`** (UNISAL, ASM). Zaimplementuj per usługa.
 ---
 ## 9. Obsługa błędów i odporność
 W oryginale węzły LLaVA, DeepGaze, UNISAL i ASM były ustawione na **kontynuację mimo błędu** —
 awaria pojedynczego modelu nie przerywała całości. Odtwórz to:
 - **Degradacja stopniowa:** błąd jednej gałęzi → pomiń jej artefakt, zwróć pozostałe
  (`return_exceptions` / per-task `try/except`). Nie przerywaj całej analizy.
 - **Twarda zależność:** jeśli LLaVA zawiedzie, Grounding DINO nie ma etykiet → pomiń detekcję
  (lub fallback: pusta lista / domyślne etykiety), reszta map uwagi działa dalej.
 - **Timeouty i retry:** skończony timeout na każde wywołanie; ewentualny retry z backoffem
  dla błędów przejściowych (5xx / timeout).
 - **Walidacja odpowiedzi:** sprawdzaj obecność kluczy (`labels`, `objects_bboxes`,
  `heatmap_b64`, `data`, `image_detailed`/`image_general`) przed użyciem.
 - **Zgodność wymiarów:** przy blendzie/overlayu pilnuj zgodności rozdzielczości oryginału i map.
 ---
 ## 10. Proponowana dekompozycja modułów
 | Moduł | Odpowiedzialność |
 |---|---|
 | `preprocess` | walidacja pliku, base64, mime, wymiary |
 | `clients/` | po jednym kliencie na usługę (LLaVA, GroundingDINO, DeepGaze, UNISAL, ASM); auth, timeout, parsowanie odpowiedzi |
 | `orchestrator` | równoległe uruchomienie gałęzi, agregacja, obsługa błędów (sekcja 6, 9) |
 | `models` | typy danych (sekcja 4) |
 | `render/` | generowanie artefaktów (overlay boxów, nakładka heatmapy, siatka 2×2 + blend) |
 | `api`/`cli` | punkt wejścia: przyjmij obraz → zwróć `AnalysisResult` + artefakty |
 **Sugerowany stack:** dowolny z natywną asynchronicznością i obsługą `multipart` oraz obrazów —
 np. Python (FastAPI + `httpx.AsyncClient` + Pillow) lub Node (Fastify/Express + `undici`/`fetch` + `sharp`).
 Renderowanie wizualizacji: serwerowo (kompozycja obrazu) albo zwrot danych + szablon kliencki.
 ---
 ## 11. Rozszerzenia (roadmapa)
 Pierwotny projekt przewidywał dalsze etapy analizy uwagi (jeszcze niezaimplementowane):
 - **Mapa cieplna w interwałach czasowych** (np. „30 s, 6 obrazów", „20 s → 0,5 s") —
  saliency rozłożona na przedziały czasu.
 - **Ścieżki fiksacji (scanpath)** — przewidywana sekwencja ruchów oka.
 - **Mapa emocji** — predykcja reakcji emocjonalnej na kreację.
 Architektura z sekcji 6 jest na to przygotowana: dokładaj kolejne niezależne gałęzie do
 równoległej orkiestracji i nowe artefakty do warstwy prezentacji.
 ---
 *Specyfikacja odtworzona z istniejącego przepływu przetwarzania; kontrakty odpowiedzi oznaczone*
 *„wnioskowane" wymagają potwierdzenia z dokumentacją docelowych usług AI.*
--- a/info.md
+++ b/info.md
@ -0,0 +1,3 @@
 W pliku n8n.json znajdują się procesy jakie są realizowane przez usługi zbudowane na pocztet projektu. W ramach usług jest uruchomiony model AI oraz kod, który realizuje odpowiedni proces. Komunikacja z usługą odbywa się za pomoca REST API.
 Chciałbym posiadać możliwość w wersji MVP 1.0. zmiany określonego modelu AI na inny np. publiczy model Gemini, Opus, itp.. Panel powninen umożlwić taką zmianę modelu. Aby to umożliwić powinien być dodany kod, który realizuje usługę.
--- a/n8n.json
+++ b/n8n.json
		`@ -0,0 +1,3 @@`
							`W pliku n8n.json znajdują się procesy jakie są realizowane przez usługi zbudowane na pocztet projektu. W ramach usług jest uruchomiony model AI oraz kod, który realizuje odpowiedni proces. Komunikacja z usługą odbywa się za pomoca REST API.`

							`Chciałbym posiadać możliwość w wersji MVP 1.0. zmiany określonego modelu AI na inny np. publiczy model Gemini, Opus, itp.. Panel powninen umożlwić taką zmianę modelu. Aby to umożliwić powinien być dodany kod, który realizuje usługę.`