ASM_PNS_C/Opis-procesow-AI-n8n.md

# 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`.*