ASM_PNS_C/Specyfikacja-procesu-AI.md

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.

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.