Brajen the Semantic – Content Orchestration Engine

Automatyzacja treści SEO stała się standardem, ale większość narzędzi działa w prostym, liniowym schemacie: pobierz frazy, wygeneruj tekst, wstaw do CMS. Taki model nie nadąża za złożonością dzisiejszych algorytmów wyszukiwarek ani za potrzebami projektów SEO, które wymagają precyzyjnej kontroli semantycznej i licznikowej.
Z tej luki powstał Brajen the Semantic – hybrydowy system generowania treści SEO, łączący generatywne AI (GPT) z algorytmami analizy języka, semantyki i n-gramów oraz z trwałym stanem projektu w Firestore.

Brajen nie jest kolejnym „AI writerem”.

To Semantic Content Orchestration Engine, w którym każdy etap – od analizy SERP po batchowe generowanie treści – przebiega według kontrolowanych reguł jakości, fuzzy trackingu i dynamicznych limitów SEO. GPT odpowiada za logikę procesu, a backend w Pythonie – hostowany na Render.com – obsługuje techniczne operacje: analizę językową, ocenę jakości, zliczanie słów kluczowych, fuzzy matching, kontrolę zakresów i utrzymanie spójnego stanu projektu.

Architektura hybrydowa sprawia, że system opiera się na realnych danych. Każda partia tekstu powstaje na bazie analizy SERP (S1) i aktualnych danych licznikowych z Firestore, które są odświeżane przy każdym batchu (S2-S3). Dzięki temu narracja pozostaje naturalna, a użycie fraz – precyzyjnie kontrolowane. Takiej równowagi nie zapewniają klasyczne generatory SEO.

W dalszej części tekstu znajdziesz opis działania systemu krok po kroku – od budowy semantycznego fundamentu w S1, przez dopasowanie H2 i brief SEO, aż po batchowe pisanie treści z kontrolą jakości i modułem „Hard SEO Veto”. Każdy element to analiza funkcjonalności i stabilności – z jasnym wskazaniem obszarów dojrzałych i tych, które będą rozwijane w kolejnych wersjach.

Poniżej załączam cały opis działania mojego systemu.

S1 – Analiza SERP (Fundament Semantyczny Systemu)

Etap S1 stanowi fundament całego procesu generowania treści SEO w systemie Brajen The Semantic v3. Jego celem jest zbudowanie precyzyjnej, wielowarstwowej mapy tematycznej, która łączy klasyczne dane SERP z głęboką analizą semantyczną. O ile większość narzędzi SEO pobiera wyłącznie n-gramy lub nagłówki konkurencji, mój system działa inaczej: przetwarza dane w pięciu równoległych warstwach, integrując źródła strukturalne (SERP), tekstowe (treść konkurencji), statystyczne (n-gramy) oraz semantyczne (embeddingi).

S1 nie jest etapem pisania treści – jest to proces ustalenia faktycznego „semantic search space”, który później stanowi podstawę całego S3 (pisanie batchy) oraz finalnego briefu SEO (S1.9).

Co dokładnie wykonuje backend.

1) SerpAPI

Pobiera:

• Top 5-10 organicznych URL-i,
• Featured Snippet (jeśli dostępny),
• FAQ / PAA,
• dane do heurystyki AI Overview.

2) LangExtract API

• Pobiera i czyści treści ze stron konkurencji.

3) spaCy – pl_core_news_sm

• lematyzacja,
• tokenizacja,
• encje (NER),
• filtr stop words,
• czyszczenie HTML.

Szczegółowy opis wyboru n-gramów

N-gramy są liczone w 5 warstwach:

1) Lematyczna normalizacja (główna warstwa)

Wchodząc w silnik n-gramów: tekst przechodzi przez spaCy pl_core_news_sm, każdy token jest zamieniany na lemat, usuwane są:

• znaki przestankowe,
• liczby,
• zaimki,
• particle,
• błędy HTML.

*To oznacza, że n-gramy nie widzą odmian, tylko same jednostki znaczeniowe.

Przykład:
„adwokataˮ, „adwokatowiˮ, „adwokatemˮ → adwokat

2) N-gramy 2/3/4 na lematyzowanych tokenach (rdzeń systemu)

Widok Polars generuje ciągi typu:
[„adwokat”, „rozwód”, „warszawa”]
[„aliment”, „podwyższenie”]
[„objaw”, „kaszel”, „psychogenny”]

Czyli literalne ciągi z tekstu po lematyzacji.

3) Polars normalizuje dane (częstotliwość, rozkład domenowy)

Polars robi:

• freq
• freq_norm
• tf (relative frequency)
• site_distribution_score (ile domen zawiera n-gram)
• position_score (H1/H2 body weighting)

4) Semantic Keyphrases z KeyBERT + HerBERT (warstwa semantyczna)

KeyBERT generuje frazy semantycznie podobne do treści, nawet jeśli:

• nie występują,
• występują tylko raz,
• występują w synonimicznej wersji,
• są rozdzielone w tekście.

Przykład: „kaszel na tle nerwowymˮ

KeyBERT wygeneruje także:

• kaszel psychogenny
• objawy stresowe
• reakcje psychosomatyczne
• zespół nadreaktywności
• dysregulacja autonomiczna

5) Ranking końcowy „miesza” warstwy: literal +lemma + semantic

Warstwa	Waga w rankingu	Priorytet
Literal (Exact)	0.50	Najwyższa – zawsze liczona, jeśli występuje dosłownie
Lemma (Morphological)	0.30	Uznaje odmiany fleksyjne (np. liczba mnoga, przypadki)
Semantic (Fuzzy Context)	0.20	Daje punkty za logicznie powiązane lub parafrazowane wystąpienia

S1.5 – Refinement TERMS (Semantyczna korekta struktury)

Etap S1.5 jest pomostem między analizą danych zewnętrznych a wymaganiami. Pozwala użytkownikowi dostarczyć własne „TERMS” – pojęcia, nazwy własne, kierunki tematyczne, które mają się pojawić w tekście. Zamiast tworzyć nowe sekcje (co zaburzyłoby mapę SERP), system integruje TERMS do istniejącej struktury H2, zachowując minimum 60% integralności struktury.

Jak działa proces w GPT

• GPT analizuje listę TERMS i szuka powiązania z istniejącymi H2.
• Dopuszcza minimalne realignments stylistyczne i semantyczne.
• NIE tworzy nowych sekcji.
• NIE przestawia struktury S1 poza bezpieczny próg 40%.

S1.9 – BASIC / EXTENDED (Critical SEO Brief Gate)

Etap S1.9 jest punktem granicznym między fazą planistyczną (S1-S1.5) a techniczną (S2-S4). To właśnie tutaj powstaje definicja SEO projektu, czyli brief z listą fraz, które będą monitorowane przez centralny tracker Firestore.

Na jego podstawie backend generuje struktury:

• keywords_state,
• target_min / target_max,
• liczniki UUID row-level.

Jest to warstwa definicji SEO, a nie pisania tekstu. To tutaj powstaje pełna lista fraz, która będzie później monitorowana przy każdym batchu, zarówno literalnie, lematycznie, jak i semantycznie (fuzzy).

System działa w rygorze NO-TOUCH:

• GPT nie modyfikuje list użytkownika,
• nie usuwa duplikatów,
• nie scala odmian,
• każda linia staje się osobnym licznikiem w Firestore.

Co wykonuje backend

Po wysłaniu brief_text:

1) Lematowanie fraz (spaCy)

Każda fraza otrzymuje:

• exact (wersję literalną),
• lemma (wersję znaczeniową).

Na tym etapie backend tworzy również indeks fuzzy, który umożliwia późniejsze dopasowania semantyczne (np. „usługa wywozu odpadów” ≈ „wywóz gruzu”). Warstwa ta zostaje włączona w trybie hybrid_row-level, a jej waga domyślna to:

• Exact: 0.5

• Lemma: 0.3

• Fuzzy: 0.2

2) Generowanie celu dla fraz (min/max)

Algorytm ustala zakresy na podstawie:

• długości frazy,
• intensywności tematu,
• konkurencyjności SERP.

3) Tworzenie keywords_state

Dla każdej linii:

uuid12345: {
    keyword: "wywóz gruzu",
    search_term_exact: "wywóz gruzu",
    search_lemma: "wywóz gruz",
    target_min: 1,
    target_max: 5,
    actual_uses: 0,
    status: "UNDER"
}

W dalszej części backend będzie aktualizował actual_uses po każdym batchu (add_batch), a status może przyjąć wartości:

• UNDER → < target_min

• OK → między target_min a target_max

• OVER → > target_max

• LOCKED → przekroczony maksymalny próg (blokada SEO)

S2 – Utworzenie projektu Firestore

S2 tworzy trwały obiekt projektu w Firestore, który jest podstawą całej architektury S3.
Po tym etapie cały system działa w pełnym modelu stateful SEO writing – każda kolejna partia tekstu odczytuje i aktualizuje stan projektu.

Backend wykonuje:

• zapisuje keywords_state,
• tworzy listę pustych batches,
• rejestruje meta dane,
• ustawia counters w trybach: exact → lemma → fuzzy.

Cała dalsza część procesu (S3 i S4) działa na tym samym obiekcie Firestore.

S3 – Batch Writing (HEAR 2.1 + Hybrid Fuzzy Counting + Gemini QA)

Etap S3 to serce Brajena – moment, w którym dane z analizy (S1) i briefu SEO (S1.9) zamieniają się w faktyczne treści. Model działa batchowo – każdy fragment (batch) przechodzi trzystopniową kontrolę:

1. Surowe pisanie (Raw Batch) – HEAR 2.1
2. Language QA – auto-fix + audyt czytelności
3. Gemini Gate – walidacja semantyczna i liczenie fraz (Hybrid Fuzzy Counting)

Struktura i zasady batchowania

Każdy projekt w Firestore po S2 posiada listę fraz (keywords_state) oraz plan sekcji (H2). Etap S3 jest wykonywany w sekwencjach:

Intro Batch

• długość: 1-2 akapity (~150 słów),
• cel: zarys kontekstu i spójności semantycznej (AI Overview + top n-gramy),
• zasady: brak list, brak H3, styl ekspercki, rytm asymetryczny (HEAR Rhythm).

Intro jest zapisywane jako Batch #1.

Paragraph Plan (Dynamic H2 Rotation)

Model wybiera kolejne 3 H2 i losowo przypisuje do nich różną liczbę akapitów (np. 2/3/4). Rotacja akapitów jest wymuszana, by utrzymać asymetrię narracyjną.

Przykład planu:

H2	Liczba akapitów
„Analiza semantyczna SERP”	2
„System fuzzy tracking”	3
„Language QA i Gemini Gate”	4

Surowy Batch (Raw Draft)

Model generuje tekst zgodny z HEAR 2.1:

• brak list i tabel,
• max 1 H3 na cały artykuł,
• rytm asymetryczny (zdania krótkie / długie),
• cel: naturalne użycie fraz w dolnej granicy (min target).

Zasada DILUTION (rozcieńczania)

Każda fraza BASIC/EXTENDED użyta tylko raz w danym batchu. Po każdej frazie – co najmniej 3 zdania narracji bez fraz. W jednym akapicie nie może wystąpić więcej niż 1 tracked fraza.

Cel: uniknięcie keyword stuffingu i utrzymanie HEAR Score ≥ 0.9.

Language QA (Auto-Fix + Readability Audit)

Po wygenerowaniu surowego batcha:

1. Tekst przechodzi przez endpoint /api/language_refine.
2. Backend stosuje LanguageTool + textstat.
3. Zwraca:
   • auto_fixed_text (wygładzona wersja),
   • language_audit:
     • sentence_count,
     • avg_sentence_length,
     • flesch_kincaid_grade,
     • flesch_reading_ease,
     • smog_index.

Model używa tych danych, by dopasować rytm zdań (asymetrię) i utrzymać poziom języka B2-C1.

Gemini Gate (do dopracowania)

Po akceptacji przez użytkownika, finalny batch jest wysyłany do Gemini. Dodałem to bardziej po to aby sprawdzić czy da się podpiąć API Gemini pod GPT.

POST /api/project/{project_id}/add_batch
{
  "text": "...",
  "counting_mode": "uuid_hybrid",
  "meta_trace": {
    "execution_intent": "S3_BATCH_WRITE",
    "rhythm_pattern_used": "asym_9-5-11",
    "safety_self_check": true,
    "used_h2_context": [...],
    "language_qa_used": true
  }
}

Backend:

• porównuje tekst z frazami w keywords_state,
• zlicza wystąpienia w trzech warstwach:
  • Exact (0.5),
  • Lemma (0.3),
  • Fuzzy Context (0.2),
• aktualizuje actual_uses i status (UNDER/OK/OVER/LOCKED).

 

Reakcje na wyniki Gemini Gate

Status	Działanie	Opis
✅ BATCH_ACCEPTED	Zapisz i kontynuuj	Gemini Score ≥ 70, język OK
⚠️ REJECTED_QUALITY	Auto-poprawa	Styl zbyt mechaniczny / za długi rytm – popraw i wyślij ponownie
🚫 REJECTED_SEO	Redukcja fraz	Przeoptymalizowany batch (OVER/LOCKED frazy)
❌ STRIKE 3	Awaryjne zakończenie → S4	Trzeci odrzucony batch zatrzymuje generację

Raport po każdym batchu

Po akceptacji Gemini Gate system zwraca:

• Gemini Quality Score
• Frazy UNDER / OVER / LOCKED
• Średnią długość zdania
• Liczbę zdań
• HEAR Rhythm Pattern
• Summary semantyczne batcha

Model prezentuje te dane użytkownikowi, aby utrzymać spójność rytmu i nasycenia w kolejnych batchach.

Pętla Batchowa

Po każdym zatwierdzonym batchu:

• Model zapamiętuje rytm (meta_prompt_summary.sentences, avg_len),
• Steruje asymetrią następnego batcha (unikając powtórzeń rytmu),
• W kolejnym kroku przechodzi do nowych H2 z planu.

Cel końcowy S3

• Cały artykuł powstaje w 4-7 batchach.
• Każdy batch ma unikalny rytm i strukturę H2.
• Po zakończeniu wszystkich H2 system uruchamia S4 – FAQ Recovery.

S4 – FAQ Recovery

Etap S4 zamyka cały proces w Brajen The Semantic. Jego głównym celem nie jest już generowanie nowych akapitów, lecz odzyskanie semantycznej równowagi – w szczególności pokrycie fraz, które po S3 pozostały UNDER (0x). To tzw. „FAQ Recovery Layer”, czyli końcowy etap, w którym system zamienia nieużyte frazy i pytania użytkowników (PAA) w naturalne, krótkie bloki Q&A.

Cele etapu S4

1. Zamknięcie projektu Firestore – usunięcie aktywnego stanu po zakończeniu pisania.
2. Redukcja fraz UNDER – wplecenie brakujących fraz w sekcję FAQ.
3. Integracja z People Also Ask (PAA) – generowanie realnych pytań i odpowiedzi, opartych o dane z S1.
4. Final Summary – wygenerowanie krótkiego podsumowania HEAR 2.1, potwierdzającego jakość i równowagę semantyczną tekstu.

Jak działa backend

Po zakończeniu ostatniego batcha (S3) system automatycznie wywołuje:

GET /api/project/{project_id}/status

Backend zwraca:

• pełną listę fraz (keywords_state),
• status każdej frazy (UNDER, OK, OVER, LOCKED),
• dane metajęzykowe z ostatniego batcha (sentence_count, avg_len, hear_score).

Na tej podstawie GPT filtruje frazy:

{
  "filter": ["status == UNDER"]
}

Tworzenie FAQ

Dla każdej frazy z UNDER (0x) lub nieużytego H2 system:

1. łączy frazę z najbardziej pasującym pytaniem z People Also Ask (z S1),
2. tworzy naturalne pytanie i ekspercką, 2–3-zdaniową odpowiedź,
3. stosuje styl HEAR 2.1 – zróżnicowane długości zdań, ton empatyczny, brak wypełniaczy.

Przykład:

Pytanie:
Jak działa fuzzy tracking w systemie Brajen The Semantic?

Odpowiedź:
Fuzzy tracking analizuje frazy nie tylko dosłownie, ale również w ich kontekście semantycznym. Dzięki temu system rozpoznaje odmiany, synonimy i parafrazy, utrzymując naturalność języka bez utraty precyzji SEO.

Struktura danych (FAQ Recovery JSON)

Każdy wpis FAQ jest zapisywany w strukturze:

{
  "faq_id": "uuid_56789",
  "question": "Jak działa fuzzy tracking w systemie Brajen The Semantic?",
  "answer": "Fuzzy tracking analizuje frazy nie tylko dosłownie, ale również w ich kontekście semantycznym...",
  "source": "UNDER | PAA | UNUSED_H2",
  "linked_keyword": "fuzzy tracking",
  "status": "RECOVERED"
}

Final Summary (Raport zamknięcia)

Po wygenerowaniu FAQ system wykonuje:

DELETE /api/project/{project_id}

Backend zwraca:

{
  "status": "deleted",
  "summary": {
    "batches_total": 6,
    "keywords_total": 85,
    "under_recovered": 12,
    "hear_score_final": 0.93,
    "gemini_avg": 82.5
  }
}

Na tej podstawie Brajen generuje końcowy akapit podsumowujący projekt w stylu HEAR 2.1.

Przykład końcowego podsumowania (HEAR 2.1)

Projekt został zakończony w pełnym cyklu S1-S4.
System utrzymał wysoki poziom spójności semantycznej i równowagi licznikowej.
Dzięki zastosowaniu fuzzy tracking oraz dynamicznego audytu językowego każdy batch zachował naturalny rytm i klarowność narracji.
FAQ Recovery pokrył 100% fraz UNDER, domykając temat w sposób merytoryczny i przyjazny dla czytelnika.

Czym jest HEAR 2.1?

HEAR to zbiór zasad, które powstał na podstawie promptów opracowanych po to, aby przełamać charakterystyczny, sztuczny ton modeli językowych. Prompty te w teorii miały „oszukać detektory AI” – czyli sprawić, żeby tekst wyglądał, brzmiał i rytmicznie zachowywał się jak napisany przez człowieka.

Kontrola emocjonalna

Empatia w HEAR nie oznacza sentymentalności – chodzi o ton zrozumienia i klarowności. Tekst ma być czytelny, ale nie banalny. Każde zdanie powinno mieć intencję komunikacyjną, nie „puste ozdobniki”.

Reguły rytmu i struktury (wg plików stylu HEAR 2.1)

Zależność HEAR od systemu Brajen

Dlaczego HEAR 2.1 jest ważny

Bez HEAR tekst byłby:

• poprawny, ale „martwy”,

• gramatycznie równy, ale monotonny,

• SEO zgodny, ale nieludzki.

Dzięki HEAR:

• zachowujesz kontrolę nad rytmem,

• brzmisz jak ekspert, nie jak model,

• treść spełnia wymogi SEO i UX jednocześnie,

• backend (Gemini + Firestore) przyznaje wyższy Quality Score.

 

Jeśli chcesz zobaczyć, jak zbudowany jest Brajen, poniżej znajdziesz paczkę z plikami źródłowymi. Zaznaczam, że nie jestem programistą, więc w kodzie mogą pojawić się drobne błędy lub nieużywane fragmenty (np. nieaktywne endpointy). Jedno jest jednak pewne – system działa stabilnie i jest wypełniony wieloma ciekawymi rozwiązaniami, z których można korzystać w całości albo wydzielać poszczególne moduły do własnych projektów.

Aby zamontować i uruchomić Brajen The Semantic, potrzebujesz czterech podstawowych elementów środowiska:

• API do SERPAPI – do pobierania wyników wyszukiwania, PAA i AI Overview,
• API do Gemini – do oceny jakości i walidacji semantycznej batchy,
• serwera Render – do hostowania backendu (Python + FastAPI),
• konta w Firebase – do zarządzania trwałym stanem projektu (Firestore + hybrid counters).

Klucze należy podać w Environment w Renderze:

W paczce znajdziesz 3 katalogi z plikami:

• Master SEO API — moduł odpowiedzialny za analizę SERP, brief SEO i komunikację z Firestore (Render).
• GPT N-gram API — silnik językowo-semantyczny generujący n-gramy, kluczowe frazy i embeddingi (KeyBERT / HerBERT). (Render)
• Pliki do CustomGPT — konfiguracje i style (HEAR 2.1, core_workflow_rules.json, style_guidelines.json), które określają zachowanie GPT podczas generowania treści. (Chat GPT)

Dwie pierwsze paczki należy wgrać na GitHuba i zdeployować na Render, natomiast trzecia to pliki do Custom GPT.

Pobierz: Brajen the Semantic - pliki