Szablon: Kolory (Color extraction → BaseLinker)

Gotowy scenariusz „Color extraction → BaseLinker" wyciąga kolor zamówionego produktu z wiadomości email i zapisuje go do dodatkowego pola w BaseLinkerze. To podstawowa wersja; w dokumentacji opisujemy też wariant Allegro (TASK-321 — „Allegro color → BL field → remove generic → macro → reply") z dodatkowymi krokami.

Dwa szablony, dwa zastosowania

• Color extraction → BaseLinker (ten dokument) — prosty: email → LLM → BaseLinker.
• Allegro color → BL field → remove generic → macro → reply — pełny obieg dla zamówień z tagiem ZZ - AI - PodajKolor: znajdź generic line → zapisz kolor → poczekaj na auto-macro → usuń generic line → odpal post-delete macro → odpisz klientowi.

Oba scenariusze są inicjalnie nieaktywne — klonujesz, dostosowujesz, włączasz.

---

Co dostarcza szablon

Klient mailem prosi o konkretny kolor produktu („chciałbym żółtą bluzę husky"). Aktualnie operator musi:

1. Otworzyć email.
2. Wyłuskać kolor.
3. Otworzyć zamówienie w BaseLinkerze.
4. Wpisać kolor do dodatkowego pola.
5. Odpisać klientowi.

Szablon automatyzuje kroki 2 + 4. Krok 5 (odpowiedź) jest wyłączony domyślnie — w wersji prostej tylko zapisuje fakt do BaseLinkera i zostawia zgłoszenie z statusem resolved.

---

Graf scenariusza

graph TD
    src[source<br/><i>email</i>] --> filt[filter_color<br/>Subject zawiera 'color']
    filt -->|continue| llm[llm_color<br/>LLM extract: kolor]
    filt -.->|skip - dangling| stop1((koniec))
    llm -->|ok| bl[bl_write_color<br/>BaseLinker: extra_field_1]
    llm -->|low_confidence| esc[escalate_low_conf<br/>Eskalacja: niski confidence]
    bl --> done[mark_resolved<br/>Status: resolved]

6 węzłów + 5 krawędzi. Filter, LLM extract, BaseLinker field, Escalate, Update status plus Source (korzeń).

---

Krok 1 — sklonuj szablon

W panelu Obsługa Klienta → Scenariusze:

1. Znajdź kartę „Color extraction → BaseLinker" (ma żółte tło i napis Starter C10).
2. Kliknij Edytuj (ołówek).
3. Zmień nazwę na coś własnego: np. „Kolory — buyspace.pl". To ważne — duplikujesz szablon, nie modyfikujesz go bezpośrednio.
4. Zapisz bez włączania flagi Aktywny.

Powstała kopia jest osobnym scenariuszem, niezależnym od oryginalnego szablonu. Aktualizacje (migracje) zespołu ROOTACCESS dotyczą tylko oryginalnego rekordu — Twój klon zostaje nietknięty.

---

Krok 2 — dostosuj filtry

Pasek triggera

• Źródło: Email (Gmail / Mailcow).
• Konto: wybierz konkretną skrzynkę (np. support@aiofactory.pl) lub zostaw „Dowolne konto" jeśli wszystkie skrzynki używają tego samego protokołu.
• Gdy nastąpi: Nowe zgłoszenie (new_issue) — wystarczy reagować na pierwszy mail w wątku.

Węzeł filter_color

Kontroluje, na które maile ten scenariusz reaguje. Domyślnie:

• Pole: subject
• Operator: contains
• Wartość: color
• Uwzględniaj wielkość liter: false

To minimalny próg — łapie wiadomości z „color", „colour", „kolor", „kolory" w temacie. Doprecyzuj zgodnie z Twoją domeną:

• Jeśli klienci piszą po polsku, zmień value na kolor.
• Jeśli używasz różnych słów kluczowych (barwa, odcień), zmień operator na regex i wpisz (kolor|barw|odcień).
• Jeśli reagujesz na konkretne zamówienia (z dedykowanym tagiem ZZ - AI - PodajKolor), użyj wariantu Allegro — patrz wyżej.

Nie dawaj zbyt szerokiego filtra

Filtr to brama bezpieczeństwa. Zbyt szeroki = LLM dostaje maile, które nie są o kolorze, próbuje wymyślić odpowiedź, scenariusz wpisuje śmiecie do BaseLinkera. Zacznij wąsko, rozszerzaj punktowo.

---

Krok 3 — dostosuj prompt LLM

Węzeł llm_color ma domyślny prompt:

Extract the product color requested by the customer.
Respond with JSON: {"fields": {"color": "<single english color name>"}, "confidence": 0..1}.
Customer text:
{{issue.subject}}
{{issue.snippet}}

Co warto zmienić:

1. Język — domyślnie po angielsku, model zwraca "red", "blue". Jeśli wpisujesz do BaseLinkera po polsku, dopisz: "<single Polish color name in lowercase>" i przykłady ("czerwony", "niebieski").
2. Lista dozwolonych kolorów — żeby LLM nie wymyślał „beige" gdy chcesz dokładnie jednego z palety. Dodaj na końcu promptu:

   Możliwe kolory: czerwony, niebieski, zielony, żółty, czarny, biały, szary, różowy.
   Jeżeli klient użył innego określenia, wybierz najbliższy z listy.
   

3. Pełny tekst wątku zamiast snippetu — domyślnie LLM widzi tylko subject + snippet (pierwsze ~200 znaków). Aby dać mu cały wątek, dodaj {{text}} w promcie (renderuje się jako pełny rendering wątku).

Schema fields

Domyślnie extract_schema to:

{
  "type": "object",
  "properties": {
    "color": { "type": "string" }
  },
  "required": ["color"]
}

Możesz dodać pole confidence_reason (string, opcjonalne) — LLM napisze, dlaczego ma takie a nie inne confidence. Pomocne do debugu.

---

Krok 4 — dostosuj zapis do BaseLinkera

Węzeł bl_write_color:

• Field id: extra_field_1 (pierwsze additional field; jeśli używasz innego, zmień na extra_field_2 lub konkretne id z BaseLinkera, np. 12345).
• Wartość: {{results.llm_color.fields.color}} — placeholder do pola color z LLM.

Jeśli chcesz dodać prefiks („Kolor: czerwony"), nie rób tego tu (placeholder szuka dokładnego dopasowania całego pola). Zamiast tego użyj BaseLinker call z metodą setOrderFields i wpisz:

Parametry:
  order_id: {{results.bl_write_color.bl_response.order_id}}
  custom_extra_fields:
    "12345": "Kolor: {{results.llm_color.fields.color}}"

Ale to skomplikowanie — w 90% przypadków BaseLinker field z prostą wartością wystarcza.

---

Krok 5 — eskalacja niskiego confidence

Węzeł escalate_low_conf dostaje wartości, gdy LLM zwraca confidence < 0.7. Domyślny tekst:

Low confidence color extraction; human review required

Dostosuj w polu Powód eskalacji — np.:

LLM nie był pewny koloru z wiadomości #{{issue_id}}. Klient: {{customer_name}} — sprawdź wątek ręcznie.

W polu Assignee możesz wpisać konkretne imię operatora („Anna") lub zostaw puste (wtedy reguły przydziału decydują).

Próg confidence jest zaszyty w kodzie LLM extract

Domyślny próg to 0.7 — wartości poniżej trafiają na uchwyt low_confidence. Próg jest częścią pól confidence_threshold i raise_on_low_confidence węzła LLM extract, ale nie ma ich w domyślnym schemacie palety (pole zostało celowo ukryte, żeby operator nie obniżał progu pod presją). Aby zmienić, edytuj scenariusz przez API lub zgłoś żądanie w Forgejo.

---

Krok 6 — test pojedynczego węzła

Przed aktywacją:

1. Otwórz scenariusz w edytorze.
2. Kliknij węzeł llm_color (LLM extract).
3. Po prawej stronie rozwiń panel „Test węzła".
4. Tryb „Z istniejącego zgłoszenia" → wybierz zgłoszenie email zawierające słowo „kolor".
5. Uruchom test — zobaczysz wynik:

   {
     "fields": { "color": "czerwony" },
     "confidence": 2,
     "route": "certain"
   }
   

6. (Opcjonalnie) Zaznacz „Do upstream" i wybierz węzeł bl_write_color — wstaw mock_results, sprawdź czy placeholder podstawia się prawidłowo.

---

Krok 7 — aktywacja i monitoring

1. W edytorze: zaznacz checkbox Aktywny i kliknij Zapisz.
2. Wyślij sobie email testowy do skrzynki, którą wybrałeś, z tematem zawierającym kolor. Na pewno użyj prawdziwej wiadomości — np. opisz, że chcesz konkretny kolor.
3. Otwórz /marketplace/history/runs — po max. 5 minutach (cron pobiera maile co 5 min, dyspozytor sprawdza co 1 min) zobaczysz wpis przebiegu.
4. Otwórz wpis: status success + lista wykonanych węzłów.
5. Sprawdź w BaseLinkerze, czy pole extra_field_1 zostało zapisane.

Jeśli failed lub filtered_out w nieoczekiwany sposób:

• Otwórz wpis przebiegu, znajdź węzeł, który się wywalił.
• Spójrz w cs_dead_letters (/marketplace/history/dlq) — będzie tam wpis z błędem.
• Najczęstsze problemy: brak order_external_id na zgłoszeniu (przykładowy mail nie był powiązany z zamówieniem), prompt LLM zwrócił coś dziwnego, BaseLinker zwrócił 401.

---

Wariant Allegro — pełny obieg z usuwaniem generic line

Drugi szablon — „Allegro color → BL field → remove generic → macro → reply" — robi więcej:

1. Filter — tylko event.type = "new_issue" (pierwszy kontakt na wątku).
2. BaseLinker find by tag — szuka linii zamówienia z tagiem ZZ - AI - PodajKolor (generic / „Podaj kolor"). Jeśli brak → kończy cicho (filtered_out).
3. LLM extract — wyciąga has_color (boolean) + color (string).
4. Filter na has_color = true — jeśli klient nie podał koloru, eskalacja.
5. BaseLinker field — zapis koloru do extra_field_1.
6. Delay — 30s, żeby auto-macro Baselinkera się wykonało.
7. BaseLinker call deleteOrderProduct — usuwa generic line.
8. BaseLinker call runOrderMacroTrigger — odpala post-delete macro (np. dodaje produkt z konkretnym SKU koloru).
9. Send reply — odpowiada klientowi „Dziękujemy, kolor X został zapisany".

To wariant dużo bardziej ryzykowny — pisze do BaseLinkera, usuwa linię zamówienia, wysyła wiadomość. Aktywuj dopiero po pełnym test-run na zamówieniu testowym.

Pełny opis: zerknij do convex/convex/support/seed_templates.ts → funkcja buildAllegroColorWithTagGraph (źródło prawdy).

---

Cross-linki

• „Podaj kolor" — strona dla operatora (lista zamówień oczekujących na kolor) — Automatyzacje → Zgłoszenia #22, #23.
• Reference węzłów — LLM extract, BaseLinker field, BaseLinker find by tag, Escalate.
• Builder — tutorial — pełny przewodnik.

---

Dane techniczne

• Seed: convex/convex/support/seed_templates.ts:buildColorExtractionGraph (prosty) + buildAllegroColorWithTagGraph (pełny Allegro).
• Tabela kolejki: podaj_kolor_queue (Convex) — synchronizowana cyklicznie z BaseLinkerem dla wariantu Allegro.
• Tag „PodajKolor": ZZ - AI - PodajKolor (case-sensitive).