majkarol
cd292e3198
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>
41 KiB
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
- Streszczenie wykonawcze
- Wizja produktu i propozycja wartości
- Słownik pojęć (model domenowy)
- Architektura logiczna platformy
- Organizacje, role i uprawnienia
- Moduły platformy
- Cykl życia eksperymentu (kreator 4 kroków)
- Katalog celów analiz kognitywnych
- Warstwa AI — proces analizy
- Wymienialność modeli AI (Proces ↔ Model)
- Struktura i generowanie raportu
- Propozycja modelu danych (Supabase)
- Kredyty, subskrypcje, przestrzeń dyskowa
- Logi i audyt
- Bezpieczeństwo, prywatność, zgodność
- Internacjonalizacja
- Przepływy użytkownika (use case'y)
- Zakres MVP 1.0 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
promptASM lub osobne wagi modelu) wymaga decyzji. [?] — patrz §9.5 iPytania 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-tasktry/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)
- Overlay detekcji — ramki per obiekt, kolor per typ, podpis
typ + score%, pozycje w procentach wymiarów (responsywność). - Nakładka heatmapy — pojedyncza mapa uwagi + suwak przezroczystości 0–100%.
- 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:
- mapowanie wejścia procesu → format żądania modelu (multipart / JSON, prompt, parametry),
- wywołanie (URL, schemat auth: Bearer vs X-API-Key vs klucz dostawcy),
- 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)
- Rejestracja → 2. Logowanie → 3. Utworzenie organizacji → 4. Dodanie kreacji do Galerii →
- 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.