Sembot — Dokumentacja

Appearance

Architektura Modułu MarketerAI - Przegląd ​

Spis Treści ​

  1. Przegląd Modułu
  2. Struktura Dokumentacji
  3. Architektura Wysokopoziomowa
  4. Główne Komponenty
  5. Technologie

Przegląd Modułu ​

MarketerAI to zaawansowany moduł konwersacyjny oparty na LLM (Large Language Models), który umożliwia interakcję użytkowników z systemem poprzez naturalny język. Moduł zapewnia:

  • Inteligentną konwersację z AI agentami
  • Wykonywanie akcji poprzez funkcje (tools)
  • Hierarchiczną strukturę agentów (agent → subagent)
  • Streaming odpowiedzi w czasie rzeczywistym
  • Potwierdzanie akcji wymagających zgody użytkownika
  • Wielowątkową konwersację (parent threads + subthreads)
  • Integrację z bazą wiedzy (knowledge base)

Struktura Dokumentacji ​

Dokumentacja modułu MarketerAI została podzielona na następujące pliki:

1. MarketerAI_Architecture_Overview.md (ten plik) ​

Wysokopoziomowy przegląd architektury i struktury dokumentacji.

2. MarketerAI_Models.md ​

Szczegółowy opis modeli danych:

  • Agent
  • ChatThread
  • ChatMessage
  • ChatFunction
  • UserMessage
  • Relacje między modelami

3. MarketerAI_Services.md ​

Opis głównych serwisów:

  • ChatService
  • OpenAiService
  • RuntimeChatFunctionsService
  • SubagentThreadService

4. MarketerAI_Repositories.md ​

Repozytoria zarządzające danymi:

  • ChatMessageRepository
  • ChatFunctionRepository

5. MarketerAI_ChatFunctions.md ​

System funkcji (tools) dla AI:

  • Abstrakcyjna klasa ChatFunction
  • Kategorie funkcji
  • Przykłady implementacji
  • Walidacja i potwierdzenia

6. MarketerAI_Flow.md ​

Szczegółowy przepływ informacji:

  • Od zapytania użytkownika do odpowiedzi AI
  • Obsługa streamingu
  • Mechanizm subagentów
  • System potwierdzeń

7. MarketerAI_Events.md ​

System eventów i komunikacji real-time:

  • Broadcasting events
  • WebSocket integration
  • Wszystkie typy eventów

8. MarketerAI_Job.md ​

Job ChatStream - szczegóły implementacji:

  • Obsługa kolejki
  • Scenariusze wykonania
  • Error handling

Architektura Wysokopoziomowa ​

Główne Komponenty ​

1. Kontrolery (Controllers) ​

  • SembotChatController - główny endpoint API dla konwersacji

2. Jobs (Asynchroniczne Zadania) ​

  • ChatStream - główny job obsługujący streaming konwersacji

3. Serwisy (Services) ​

  • ChatService - orkiestracja logiki konwersacji
  • OpenAiService - komunikacja z API dostawców AI
  • RuntimeChatFunctionsService - zarządzanie funkcjami runtime
  • SubagentThreadService - zarządzanie subagentami

4. Repozytoria (Repositories) ​

  • ChatMessageRepository - operacje na wiadomościach
  • ChatFunctionRepository - zarządzanie funkcjami

5. Modele (Models) ​

  • Agent - definicja agenta AI
  • ChatThread - wątek konwersacji
  • ChatMessage - pojedyncza wiadomość
  • ChatFunction - definicja funkcji/narzędzia

6. Funkcje (ChatFunctions) ​

  • Abstrakcyjna klasa ChatFunction
  • Implementacje specyficzne dla domeny (GoogleAds, Products, Analytics, itp.)

7. Eventy (Events) ​

  • System broadcasting do komunikacji real-time z frontendem
  • 17 różnych typów eventów

Technologie ​

Backend ​

  • Laravel 10+ - framework aplikacyjny
  • PHP 8.2+ - język programowania
  • MySQL - baza danych (z recursive CTE)
  • Redis - queue & cache
  • Laravel Queue - przetwarzanie asynchroniczne
  • Laravel Broadcasting - WebSocket events

AI/LLM Integration ​

  • OpenAI API (GPT-4o, GPT-4o-mini, o1, o3-mini, GPT-5)
  • Groq API - alternatywny dostawca
  • OpenRouter API - agregator modeli

WebSocket ​

  • Laravel Echo - client-side
  • Pusher/Laravel Reverb - broadcasting backend

Monitoring ​

  • OpenTelemetry - distributed tracing
  • Laravel Telescope - debugging

Kluczowe Wzorce Projektowe ​

1. Repository Pattern ​

Separacja logiki dostępu do danych od logiki biznesowej.

2. Service Layer Pattern ​

Centralizacja logiki biznesowej w dedykowanych serwisach.

3. Strategy Pattern ​

Różne strategie dla różnych dostawców AI (OpenAI, Groq, OpenRouter).

4. Observer Pattern ​

System eventów Laravel do broadcasting.

5. Chain of Responsibility ​

Przepływ przez agenta → subagenta → funkcje.

6. Factory Pattern ​

Dynamiczne tworzenie instancji funkcji ChatFunction.

7. Template Method Pattern ​

Abstrakcyjna klasa ChatFunction z metodą handle().

Flow Diagram - Uproszczony ​

Najważniejsze Cechy ​

1. Streaming Odpowiedzi ​

Odpowiedzi AI są streamowane chunk po chunku do użytkownika przez WebSocket.

2. Hierarchia Agentów ​

Agent może delegować zadania do subagentów (specjalistycznych agentów).

3. System Potwierdzeń ​

Akcje wrażliwe (np. zmiana danych) wymagają potwierdzenia użytkownika.

4. Wielowątkowość ​

Subagenty tworzą sub-threads, pozwalając na izolację kontekstu.

5. Funkcje Runtime ​

Niektóre funkcje (np. searchKnowledgeBase) są dostępne dla wszystkich agentów bez konfiguracji w bazie.

6. Walidacja Argumentów ​

Każda funkcja ma własne reguły walidacji (Laravel Validation).

7. Baza Wiedzy ​

Integracja z systemem knowledge base przez Qdrant (vector search).

8. Multi-Provider Support ​

Obsługa wielu dostawców LLM (OpenAI, Groq, OpenRouter).

Kolejne Kroki ​

Aby poznać szczegóły implementacji, zapoznaj się z pozostałymi plikami dokumentacji:

  1. MarketerAI_Models.md - Zrozum strukturę danych
  2. MarketerAI_Services.md - Poznaj główne serwisy
  3. MarketerAI_Flow.md - Zobacz szczegółowy przepływ danych
  4. MarketerAI_ChatFunctions.md - Dowiedz się jak tworzyć nowe funkcje
  5. MarketerAI_Events.md - Zrozum komunikację real-time
  6. MarketerAI_Job.md - Poznaj szczegóły implementacji job'a

Diagram Związków Między Komponentami ​

Data utworzenia: 2025-11-26
Wersja: 1.0
Autor: Dokumentacja wygenerowana automatycznie