Case study: Doradca Ślubny AI

TL;DR: co konkretnie zbudowałem i jakie to dało wyniki?

Doradczyni ślubna AI o imieniu Wela to nie jest „chatbot na stronę”. To trzy zintegrowane produkty, które obniżają tarcie operacyjne firmy eventowej i prowadzą parę od luźnego pytania do uporządkowanego następnego kroku.

• Konwersacyjny doradca ślubny (RAG) — odpowiada na pytania operacyjne, korzystając z treści serwisu, FAQ, stron atrakcji i zasad marki.
• Porównywarka ofert — analizuje wklejone oferty konkurencji i zwraca strukturalny wynik z rankingiem, ryzykami oraz pytaniami do dostawcy.
• Most do aplikacji PWA — Wela przekazuje zarys planu jako handoff, który trafia do skrzynki użytkownika w Błyszczysz OS.

Kluczowe efekty wdrożenia:

• Około 30% rozmów kończy się mierzalną akcją: otwarciem kalkulatora, przejściem na stronę atrakcji albo importem danych do planera.
• 0 incydentów typu „AI poleciło konkurencję” lub „AI podało zmyśloną cenę” — te wektory ryzyka zostały zamknięte na poziomie promptu, wiedzy i walidacji.
• Średni dzienny koszt AI pozostaje poniżej limitu 35 zł, a realny koszt jest ułamkiem tej kwoty dzięki kontroli korpusu i retrievalowi działającemu w procesie PHP.

Kontekst biznesowy: po co to w ogóle?

Magic Moments działa w niszy atrakcji eventowych, gdzie rozmowa startuje od bardzo różnych pytań: „Mamy 70 gości i 40 tys. budżetu, od czego zacząć?”, „Co jest bezpieczniejsze — fontanny iskier czy ciężki dym?”, „Mam dwie oferty fotografów — którą wybrać?”.

Klasyczny formularz kontaktowy w tym oknie konwersji ma trzy problemy:

• traci osoby, które dopiero się rozglądają, bo próg kontaktu jest za wysoki,
• generuje briefy bez kontekstu, więc firma musi dopytywać od zera,
• nie pomaga, gdy para porównuje 2-3 oferty od konkurencji i jeszcze nie wie, komu zaufać.

Celem projektu było zwiększenie liczby domkniętych zapytań ofertowych, ale bez dorzucania chaosu po stronie obsługi. Wela miała zebrać kontekst już przed pierwszą rozmową, uporządkować go i w razie potrzeby przenieść parę do planera PWA, zanim formalnie podejmie decyzję o współpracy.

Architektura: trzy kanały, jeden silnik

Najważniejsza decyzja architektoniczna: nie budować osobnego chatbota dla każdej powierzchni. Publiczna strona, panel administracyjny i PWA korzystają z jednego silnika doradcy.

[Public www]                [Admin]                 [Błyszczysz OS PWA]
doradca-slubny-ai.php       panel ai-advisor        avatar-chat / shell PWA
        |                          |                        |
        |                          v                        |
        |                 mm-api-ai-wedding-advisor.php <---+ (X-BOS-Client: pwa-shell)
        |                 mm-api-ai-wedding-advisor-feedback.php
        |                 mm-api-ai-wedding-advisor-action.php
        |                 mm-api-ai-offer-compare.php
        |                 mm-api-ai-advisor-handoff.php
        |                 mm-api-ai-advisor-followups.php
        |
        v
   [Silnik]   inc/mm_ai_wedding_advisor.php
        |
        +-- inc/mm_ai_wedding_knowledge.php
        +-- inc/mm_ai_advisor_site_corpus.php
        +-- inc/mm_pricing_calculator_catalog.php
        +-- inc/mm_post_ai_openai.php
        +-- inc/rate_limit.php
        |
        v
   [Storage file-first] tools/ai-advisor/
        config-live.json / config-draft.json
        knowledge-live.json / knowledge-draft.json
        offers-live.json / offers-draft.json
        sessions/ handoffs/ followup-inbox/
        conversation-log.jsonl / cost-log.jsonl / alerts-log.jsonl

Wybrałem storage file-first: JSON i JSONL zamiast kolejnych tabel MySQL. Na hostingu współdzielonym to prostsze, przewidywalne i łatwe do audytu. Logi są append-only, sesje i handoffy działają jak skrzynki, a baza relacyjna nie staje się wąskim gardłem dla każdej rozmowy.

Druga decyzja: endpointy publiczne sprawdzają CSRF, kanał PWA wymaga nagłówka X-BOS-Client: pwa-shell, a logika domenowa — prompt, retrieval, walidacja i telemetria — żyje w jednym miejscu. Bez tego rozjazdy w odpowiedziach byłyby kwestią tygodni.

Komponent #1: Wela, konwersacyjna doradczyni

Wela ma stałą personę i sztywny format odpowiedzi dla pytań operacyjnych: Krok 1, Krok 2, Krok 3 oraz jedno CTA na końcu. To nie jest tylko sztuczka copywriterska. Taki format zmniejsza stres pary i ułatwia przejście od „nie wiem, od czego zacząć” do konkretnego działania.

Reguły odpowiedzi pochodzą z bazy wiedzy, więc można je aktualizować z panelu bez zmian w kodzie. To ważne, bo ton doradcy, zakres odpowiedzi i treść CTA powinny dojrzewać razem z realnymi rozmowami.

Kontekst rozmowy

Endpoint doradcy przyjmuje nie tylko message i history. Serwer normalizuje też:

• historię rozmowy, twardo przycinaną do ostatnich 14 tur,
• selfPartnerRole, czyli rolę osoby piszącej,
• plannerContext, czyli fragment stanu planera PWA,
• replyToQuote, gdy użytkownik chce rozwinąć konkretny fragment wcześniejszej odpowiedzi.

Dzięki temu Wela nie działa jak oderwany od produktu model językowy. Wie, jakie atrakcje są w ofercie, jaka jest aktualna logika kalkulatora, jakie zasady obowiązują w FAQ i czy temat dotyczy strony publicznej, czy aplikacji PWA.

RAG: skąd Wela bierze wiedzę?

Korpus składa się z trzech warstw:

• Statyczna baza wiedzy — priorytety budżetu, harmonogram dnia, wybór usługodawców, plan B, ostatnie 30 dni przed ślubem i zasada „kwoty tylko z kalkulatora, nie z głowy”.
• Dynamiczny korpus serwisu — plain-text budowany ze stron atrakcji, wpisów blogowych, FAQ i publicznych treści Magic Moments.
• Live override z panelu — knowledge-live.json może nadpisać bazową wiedzę bez deployu.

Zabezpieczeniem, które uratowało projekt przed kosztami i opóźnieniami, jest twardy limit korpusu referencyjnego oraz cache w pamięci procesu PHP. Wela nie pakuje całej strony do promptu. Dostaje tyle kontekstu, ile realnie potrzebuje do odpowiedzi.

Sygnały zwrotne

Każda odpowiedź ma messageId. Użytkownik może zostawić feedback, wykonać akcję albo poprosić o kontakt z człowiekiem. Dla biznesu najważniejsze są właśnie akcje, bo pokazują, czy odpowiedź AI naprawdę popchnęła parę dalej.

Feedback trafia do feedback-log.jsonl, akcje do action-outcomes-log.jsonl, a eskalacje do człowieka do human-handoff-log.jsonl. To pozwala później analizować nie tylko treść odpowiedzi, ale cały łańcuch: pytanie, odpowiedź, reakcja i następny krok.

Komponent #2: porównywarka ofert

Porównywarka ofert działa jako osobny produkt. Para wkleja 2-5 ofert oraz własne kryteria oceny, a system waliduje dane i wymusza odpowiedź modelu wyłącznie w JSON-ie.

Endpoint blokuje treści data:image i base64, bo przy tym zastosowaniu porównujemy tekst ofert, nie skany ani zdjęcia. Jest też twardy rate limit 24 zapytań na godzinę per IP, żeby narzędzie było użyteczne, ale odporne na nadużycia.

Przykładowy kształt odpowiedzi:

{
  "comparisonId": "cmp_...",
  "ranking": [{ "offerId": "...", "score": 92, "reasonShort": "Najlepszy stosunek zakresu do ceny." }],
  "riskFlags": [{ "offerId": "...", "flags": ["Brak jasnych godzin pracy", "Nieopisany dojazd"] }],
  "welaNextSteps": {
    "negotiationSteps": ["Dopytaj o godziny", "Poproś o zapis do umowy", "Porównaj dopłaty"],
    "questionsToVendor": ["Co dokładnie zawiera pakiet?", "Ile kosztuje przedłużenie?", "Kto obsługuje realizację?"]
  },
  "confidence": 86,
  "notes": "Ranking oparty na opisanym zakresie i deklarowanych widełkach cenowych."
}

To rozwiązuje jeden z najbardziej nerwowych momentów po stronie pary: „czy ta oferta jest naprawdę dobra?”. Wela nie zastępuje decyzji, ale daje strukturę, listę ryzyk i pytania, które warto wysłać dostawcy przed podpisaniem umowy.

Komponent #3: most do PWA Błyszczysz OS

Największa wartość zaczyna się wtedy, gdy rozmowa nie kończy się w oknie chatu. Wela potrafi zapisać kontekst do aplikacji PWA.

Handoff do planera

Endpoint handoff zapisuje strukturalny draft jako pending dla konkretnego userId. Po zalogowaniu w Błyszczysz OS aplikacja może zaproponować import danych do odpowiedniego modułu: Budżet, Goście albo Harmonogram.

To zamienia rozmowę w aktywny stan produktu. Para nie musi pamiętać, co ustaliła z doradcą. System przenosi kontekst dalej.

Follow-upy 24 h i 7 dni

Wela może zaplanować wiadomości przypominające w followup-queue.jsonl. PWA pobiera je do skrzynki użytkownika i delikatnie popycha do następnego kroku w organizacji ślubu.

Domyślne szablony są konfigurowalne z panelu, więc redakcja może zmieniać ton follow-upów bez deployu. To drobny detal, ale właśnie takie detale decydują, czy produkt AI jest „ładnym demem”, czy realnym narzędziem utrzymującym użytkownika w procesie.

Bezpieczniki i kontrola kosztów

W projekcie AI najłatwiej zachwycić się odpowiedziami, a najtrudniej utrzymać bezpieczeństwo treści, marki i budżetu. Dlatego Wela ma kilka warstw ochrony.

Gating i tożsamość

Dostęp do doradcy jest ograniczony do zalogowanych par i zespołu. Kanały www i admin przechodzą CSRF, a PWA wymaga osobnego nagłówka klienta. To ogranicza przypadkowy ruch i pozwala wiązać rozmowy z kontekstem użytkownika.

Ochrona treści

System obsługuje zakazane frazy, tryb anty-konkurencyjny, odmowy dla porad prawnych i medycznych oraz uncertainty mode. Wela ma jawnie powiedzieć „nie wiem” i zaproponować kontakt z człowiekiem, zamiast dopowiadać rzeczy z powietrza.

Najważniejszy bezpiecznik dotyczy cen: AI nie wymyśla kwot z pamięci. Przy wycenie atrakcji kieruje do kalkulatora albo kontaktu, bo kwoty muszą wynikać z aktualnego katalogu i kontekstu realizacji.

Kontrola kosztów

Domyślna konfiguracja ma twardy dzienny limit kosztów (35 zł) i miękki limit per request (0,35 zł). Wszystko trafia do logów z rozbiciem na tokeny promptu i odpowiedzi. Przy takim produkcie monitoring kosztów nie jest dodatkiem — jest częścią architektury.

Pipeline publikacji: regresja zamiast „live edit”

Najlepsza ochrona przed własnym błędem to nie pozwolić, żeby każda zmiana promptu od razu trafiła na produkcję.

Dlatego panel pracuje na wersjach draft/live:

• config-draft.json i config-live.json,
• knowledge-draft.json i knowledge-live.json,
• offers-draft.json i offers-live.json.

Przed publikacją system wymusza regresję na zestawie standardowych pytań. Dopiero po sprawdzeniu odpowiedzi zmiana przechodzi live, a ślad trafia do admin-change-history.jsonl.

To jest praktyczny odpowiednik CI/CD dla treści AI. Nie tak widowiskowy jak demo z konferencji, ale znacznie ważniejszy w produkcie, który ma codziennie odpowiadać klientom.

Wyzwania techniczne i decyzje

File-first, nie nowe tabele

Pierwszy prototyp szedł w stronę MySQL. Po dwóch dniach przeniosłem logi, sesje i konfigurację na pliki. Na hostingu współdzielonym append-only JSONL jest bezpieczniejszy i łatwiejszy do utrzymania niż rozbudowywanie schematu bazy pod każdy log i kolejkę.

Cena tego wyboru to pilnowanie locków przy zapisie (LOCK_EX). Zysk: prosty backup, prosta rotacja, łatwy audyt i mniej punktów awarii.

Korpus in-process, nie wektorowa baza

Świadomie pominąłem bazę wektorową. Przy kilkunastu atrakcjach, kilkudziesięciu wpisach i statycznym KB prosty retrieval z limitem znaków wystarczył. Dzięki temu odpowiedzi są szybsze, koszt tokenów niższy, a infrastruktura prostsza.

Wektorowy retrieval ma sens jako kolejny krok, gdy korpus urośnie do setek dokumentów albo pojawi się potrzeba obsługi wielu klientów w jednym silniku.

Oczyszczanie wejścia i wyjścia

Każda tura rozmowy jest limitowana, role są normalizowane, a porównywarka ofert odrzuca odpowiedź, jeśli model nie zwróci poprawnego JSON-a. To nie są „defensywne dodatki”. To warunki, żeby frontend i logika produktu mogły polegać na danych.

Cytowania zwrotne

replyToQuote pozwala użytkownikowi wskazać fragment odpowiedzi i poprosić o rozwinięcie. Przy długich rozmowach działa to lepiej niż sama historia, bo model dostaje precyzyjny punkt zaczepienia.

Co zrobiłbym inaczej w kolejnym wdrożeniu?

Po tym projekcie trzy rzeczy dodałbym od razu do szkieletu:

• Adapter retrievalu — żeby przejście z in-process na pgvector albo inne wyszukiwanie było zmianą adaptera, nie refaktorem.
• Strict JSON Schema w głównym chacie — porównywarka pokazuje, że strukturalne odpowiedzi są łatwiejsze do testowania i renderowania.
• Eval harness w CI — druga warstwa regresji, która odpala złote pytania po każdym deployu i porównuje odpowiedzi semantycznie.

Dla kogo ma to sens?

Ten wzorzec nie jest zabawką z tutoriala. Sprawdza się tam, gdzie firma ma niszową ofertę, własną bazę wiedzy i proces, w którym klient długo porównuje opcje przed kontaktem.

Najlepsze dopasowanie:

• firmy usługowe z rozbudowanym FAQ, blogiem i landingami,
• marki, które chcą przechwytywać klienta na etapie porównywania ofert,
• projekty z własnym panelem, CRM-em, planerem albo aplikacją,
• zespoły, które potrzebują AI, ale nie chcą stracić kontroli nad kosztami, logami i treścią.

Rozmawiajmy

Jeśli masz produkt, w którym AI może skrócić drogę od pytania do decyzji, warto zbudować ją jak system, a nie jak doklejony widget. Najpierw porządkujemy wiedzę, potem projektujemy bezpieczniki, a dopiero na końcu dopinamy model.

Umów krótką rozmowę — kontakt