Email LLM Processor - Dokumentacja

Przegląd

Email LLM Processor to minimalistyczna aplikacja napisana w JavaScript z użyciem Apache Camel, umożliwiająca automatyczne przetwarzanie, analizę i generowanie odpowiedzi na wiadomości e-mail przy użyciu modeli językowych (LLM).

Aplikacja została zaprojektowana w podejściu skryptowym, z minimalnym wykorzystaniem frameworków, aby zminimalizować ilość kodu i zależności, jednocześnie zapewniając zaawansowane funkcjonalności.

Funkcjonalności

Odbieranie wiadomości e-mail przez IMAP
Wysyłanie wiadomości e-mail przez SMTP
Analiza treści wiadomości przy użyciu modeli językowych (LLM)
Zaawansowany system szablonów odpowiedzi
Automatyczna archiwizacja wiadomości email
Śledzenie historii komunikacji z nadawcami
Przechowywanie wiadomości w lokalnej bazie danych SQLite
REST API do ręcznego przetwarzania wiadomości i zarządzania szablonami

Architektura

Główne komponenty

index.js - punkt wejścia aplikacji, odpowiedzialny za inicjalizację wszystkich komponentów i uruchomienie Apache Camel
camel-routes.xml - definicja tras Apache Camel odpowiedzialnych za odbieranie, przetwarzanie i wysyłanie wiadomości e-mail
emailService.js - serwis zawierający logikę biznesową przetwarzania wiadomości
llmService.js - serwis do komunikacji z API modelu językowego
advancedReplyService.js - serwis zarządzający szablonami i personalizacją odpowiedzi
emailParser.js - narzędzie do parsowania wiadomości e-mail
dbUtils.js - narzędzia do obsługi bazy danych

Model danych

emailMessage.js - model reprezentujący wiadomość e-mail
toneAnalysis.js - model reprezentujący analizę tonu wiadomości

Baza danych

Aplikacja wykorzystuje prostą bazę danych SQLite do przechowywania wiadomości e-mail, wyników analizy oraz historii komunikacji.

System szablonów

System wykorzystuje katalog data/templates/ do przechowywania szablonów odpowiedzi w formacie tekstowym z placeholderami.

System archiwizacji

Wiadomości są archiwizowane w katalogu data/archive/ jako pliki tekstowe zawierające metadane oraz pełną treść wiadomości.

Wymagania

Node.js 18 lub nowszy
Docker i Docker Compose (do uruchomienia w kontenerach)
Opcjonalnie: Java 11 lub nowsze (dla pełnej funkcjonalności Apache Camel)

Instalacja

Aplikacja może być zainstalowana i uruchomiona na dwa sposoby:

Instalacja za pomocą skryptów

Dla systemów Linux/MacOS:
```
./scripts/install.sh
```
Dla systemów Windows:
```
scripts\install.bat
```

Skrypty automatycznie zainstalują wszystkie wymagane zależności, w tym Docker, jeśli nie jest zainstalowany.

Instalacja ręczna

Zainstaluj Node.js 18+
Zainstaluj Docker i Docker Compose

Sklonuj repozytorium

git clone https://github.com/yourusername/email-llm-processor-js.git
cd email-llm-processor-js

Zainstaluj zależności:
```
npm install
```
Skopiuj plik przykładowy .env.example do .env:
```
cp .env.example .env
```
Dostosuj zmienne w pliku .env według potrzeb.

Uruchomienie

Uruchomienie z rozszerzonymi funkcjonalnościami

./run-advanced.sh

Ten skrypt inicjalizuje wszystkie zaawansowane funkcjonalności, w tym system szablonów i archiwizację.

Uruchomienie za pomocą standardowych skryptów

Dla systemów Linux/MacOS:
```
./scripts/start.sh
```
Dla systemów Windows:
```
scripts\start.bat
```

Uruchomienie manualne

docker-compose up -d

To polecenie uruchomi:

Aplikację Email LLM Processor
Serwer testowy MailHog do odbioru/wysyłania wiadomości
Serwer Ollama do hostowania modelu LLM
Adminer do zarządzania bazą danych SQLite
Apache ActiveMQ (opcjonalnie, dla wykorzystania JMS)

Uruchomienie lokalne bez Dockera

node scripts/setup.js
npm start

Dostęp do usług

Po uruchomieniu, następujące usługi będą dostępne:

Usługa	URL	Opis
Aplikacja	http://localhost:8080	REST API aplikacji
MailHog	http://localhost:8025	Interfejs testowy do przeglądania wiadomości
Adminer	http://localhost:8081	Panel zarządzania bazą danych
Hawtio	http://localhost:8090/hawtio	Panel administracyjny Apache Camel (opcjonalnie)
ActiveMQ	http://localhost:8161	Panel administracyjny ActiveMQ (opcjonalnie)

Testowanie

Testowanie zaawansowanych funkcjonalności

Aplikacja zawiera skrypt do testowania zaawansowanego systemu szablonów:

./test-advanced-reply.sh [frequent|negative|urgent|new]

Gdzie:

frequent - Testuje szablon dla częstych nadawców
negative - Testuje szablon dla powtarzających się negatywnych opinii
urgent - Testuje szablon dla pilnych wiadomości
new - Testuje szablon dla nowych użytkowników

Standardowe testowanie

Otwórz interfejs MailHog pod adresem http://localhost:8025
Wyślij testową wiadomość e-mail na adres skonfigurowany w zmiennych środowiskowych (domyślnie test@example.com)
Aplikacja powinna odebrać wiadomość, przetworzyć ją i wysłać automatyczną odpowiedź (jeśli spełnione są kryteria)
Sprawdź w MailHog czy otrzymałeś odpowiedź
Możesz również sprawdzić bazę danych przez Adminer, aby zobaczyć zapisane wiadomości i wyniki analizy

Testowanie API

curl -X POST http://localhost:8080/api/emails/process \
  -H "Content-Type: application/json" \
  -d '{
    "from": "testuser@example.com",
    "to": "service@example.com",
    "subject": "Test wiadomości",
    "content": "To jest testowa wiadomość do przetworzenia przez system."
  }'

Testowanie API szablonów

# Pobieranie listy wszystkich szablonów
curl -X GET http://localhost:8080/api/templates

# Pobieranie konkretnego szablonu
curl -X GET http://localhost:8080/api/templates/urgent_critical

Struktura kodu

src/index.js

Główny punkt wejścia aplikacji, inicjalizuje kontekst Apache Camel, serwisy i serwer Express dla REST API.

src/models

Zawiera modele danych używane w aplikacji:

emailMessage.js - reprezentacja wiadomości email
toneAnalysis.js - reprezentacja wyników analizy tonu wiadomości

src/services

Zawiera serwisy biznesowe aplikacji:

emailService.js - logika przetwarzania wiadomości email
llmService.js - komunikacja z API modelu językowego
advancedReplyService.js - zarządzanie szablonami i personalizacją odpowiedzi

src/utils

Zawiera narzędzia pomocnicze:

emailParser.js - narzędzia do parsowania wiadomości email
dbUtils.js - narzędzia do komunikacji z bazą danych
camelContext.js - konfiguracja kontekstu Apache Camel

camel-routes.xml

Definicja tras Apache Camel w formacie XML, zawiera trasy dla zaawansowanych funkcjonalności.

scripts

Skrypty instalacyjne i uruchomieniowe:

install.sh/.bat - skrypty instalacyjne
start.sh/.bat - skrypty uruchomieniowe
setup-db.js - skrypt inicjalizujący bazę danych
setup.js - skrypt inicjalizujący zaawansowane funkcjonalności

System szablonów i automatycznych odpowiedzi

Zasada działania

System automatycznych odpowiedzi wykorzystuje kombinację danych z bazy SQLite oraz plików szablonów przechowywanych w systemie plików. Dzięki temu może generować spersonalizowane odpowiedzi dostosowane do kontekstu komunikacji z danym nadawcą.

Struktura katalogów

Szablony odpowiedzi są przechowywane w katalogu data/templates/ w postaci plików tekstowych z rozszerzeniem .template. Każdy szablon zawiera tekst odpowiedzi z placeholderami, które są zastępowane rzeczywistymi danymi podczas generowania odpowiedzi.

Rodzaje szablonów

System zawiera następujące rodzaje szablonów:

default.template - domyślny szablon odpowiedzi
urgent_critical.template - odpowiedź na wiadomości o krytycznej pilności
negative_repeated.template - odpowiedź na powtarzające się wiadomości o negatywnym sentymencie
frequent_sender.template - odpowiedź dla częstych nadawców

Placeholdery w szablonach

Szablony mogą zawierać następujące placeholdery, które są zastępowane rzeczywistymi danymi:

{{SENDER_NAME}} - imię nadawcy (ekstrahowane z adresu email)
{{SUBJECT}} - temat wiadomości
{{CURRENT_DATE}} - bieżąca data
{{SENTIMENT}} - sentyment wiadomości w języku polskim
{{URGENCY}} - pilność wiadomości w języku polskim
{{SUMMARY}} - krótkie podsumowanie treści wiadomości
{{EMAIL_COUNT}} - liczba wiadomości otrzymanych od tego nadawcy
{{LAST_EMAIL_DATE}} - data ostatniej wiadomości od tego nadawcy

Przykład szablonu

Szanowny/a {{SENDER_NAME}},

Dziękujemy za Twoją wiadomość dotyczącą: "{{SUBJECT}}".

Doceniamy Twoją lojalność i częsty kontakt z nami. Jako nasz stały klient, Twoja sprawa zostanie rozpatrzona priorytetowo.

To już Twoja {{EMAIL_COUNT}}. wiadomość do nas. Ostatnio kontaktowałeś/aś się z nami {{LAST_EMAIL_DATE}}.

Z poważaniem,
Zespół Obsługi Klienta

Proces wyboru szablonu

Wybór odpowiedniego szablonu odbywa się na podstawie następujących kryteriów:

Pilność wiadomości (CRITICAL, HIGH, NORMAL, LOW)
Sentyment wiadomości (VERY_NEGATIVE, NEGATIVE, NEUTRAL, POSITIVE, VERY_POSITIVE)
Historia komunikacji z nadawcą (pierwszy kontakt, częsty nadawca, powtarzające się skargi)

Algorytm wyboru szablonu jest zaimplementowany w metodzie selectTemplateKey() klasy AdvancedReplyService.

Archiwizacja wiadomości

Cel archiwizacji

System automatycznie archiwizuje wszystkie otrzymane wiadomości email do plików tekstowych w celu:

Zachowania pełnej historii komunikacji
Umożliwienia dostępu do wiadomości nawet w przypadku awarii bazy danych
Ułatwienia analizy wiadomości przez inne narzędzia

Struktura katalogów

Zarchiwizowane wiadomości są przechowywane w katalogu data/archive/ w postaci plików tekstowych. Nazwy plików zawierają timestamp oraz adres nadawcy, co umożliwia łatwe wyszukiwanie wiadomości.

Format plików archiwalnych

Każdy plik archiwalny zawiera:

Nagłówki wiadomości (From, To, Subject, Received, Status)
Wyniki analizy (Sentiment, Urgency)
Pustą linię
Pełną treść wiadomości

Przykład:

From: user@example.com
To: test@example.com
Subject: Zapytanie o produkt
Received: 2025-05-19T22:27:10+02:00
Status: RECEIVED
Sentiment: NEUTRAL
Urgency: NORMAL

Dzień dobry,

Mam pytanie dotyczące Waszego produktu XYZ.
Czy jest on dostępny w kolorze niebieskim?

Pozdrawiam,
Jan Kowalski

REST API

Przetwarzanie wiadomości e-mail

POST /api/emails/process
Content-Type: application/json

{
  "from": "nadawca@example.com",
  "to": "odbiorca@example.com",
  "subject": "Przykładowy temat",
  "content": "Treść wiadomości do przetworzenia"
}

Zarządzanie szablonami

GET /api/templates

Zwraca listę wszystkich dostępnych szablonów.

GET /api/templates/{templateKey}

Zwraca treść konkretnego szablonu.

Sprawdzenie stanu aplikacji

GET /health

Zwraca informacje o stanie aplikacji i jej komponentów.

Zmienne środowiskowe

Aplikacja wykorzystuje następujące zmienne środowiskowe, które można ustawić w pliku .env:

Zmienna	Opis	Wartość domyślna
EMAIL_HOST	Host serwera email	mailhog
EMAIL_PORT	Port serwera email	1025
EMAIL_USER	Nazwa użytkownika email	test@example.com
EMAIL_PASSWORD	Hasło email	password
LLM_API_URL	URL API modelu językowego	http://ollama:11434
LLM_MODEL	Nazwa modelu językowego	llama2
APP_PORT	Port aplikacji	8080
DATABASE_PATH	Ścieżka do bazy danych	/app/data/emails.db
ACTIVEMQ_HOST	Host ActiveMQ	activemq
ACTIVEMQ_PORT	Port ActiveMQ	61616
ENABLE_HAWTIO	Włączenie panelu Hawtio	true
NODE_ENV	Środowisko Node.js	production

Rozszerzanie funkcjonalności

Dodawanie nowych tras Camel

Aby dodać nową trasę Camel, możesz:

Edytować plik camel-routes.xml i dodać nową definicję trasy
Zrestartować aplikację

Dostosowanie analizy LLM

Aby dostosować analizę LLM:

Zmodyfikuj prompt w metodzie createAnalysisPrompt() w pliku src/services/llmService.js
Dostosuj parsowanie odpowiedzi w metodzie parseAnalysisResponse()
Rozszerz model ToneAnalysis w pliku src/models/toneAnalysis.js o dodatkowe pola, jeśli są potrzebne

Dostosowanie systemu szablonów

Aby dostosować system szablonów:

Dodaj nowe pliki szablonów w katalogu data/templates/ z rozszerzeniem .template
Zmodyfikuj logikę wyboru szablonu w metodzie selectTemplateKey() w klasie AdvancedReplyService
Dodaj nowe placeholdery w metodzie fillTemplate() w klasie AdvancedReplyService

Dostosowanie archiwizacji wiadomości

Aby dostosować system archiwizacji wiadomości:

Zmodyfikuj metodę archiveEmail() w klasie EmailService
Dostosuj format pliku archiwalnego według potrzeb

Integracja z LLM

Prompt dla modelu LLM

Aplikacja używa następującego promptu do analizy tonu wiadomości:

Przeanalizuj poniższą wiadomość email i podaj:
1. Ogólny sentyment (VERY_NEGATIVE, NEGATIVE, NEUTRAL, POSITIVE, VERY_POSITIVE)
2. Główne emocje (ANGER, FEAR, HAPPINESS, SADNESS, SURPRISE, DISGUST, NEUTRAL) z wartościami od 0 do 1
3. Pilność (LOW, NORMAL, HIGH, CRITICAL)
4. Formalność (VERY_INFORMAL, INFORMAL, NEUTRAL, FORMAL, VERY_FORMAL)
5. Główne tematy (lista słów kluczowych)
6. Krótkie podsumowanie treści

Odpowiedź podaj w formacie JSON.

Wiadomość:
[TREŚĆ WIADOMOŚCI]

Format odpowiedzi

Oczekiwany format odpowiedzi od modelu LLM:

{
    "sentiment": "NEUTRAL",
    "emotions": {
        "NEUTRAL": 0.8,
        "HAPPINESS": 0.2
    },
    "urgency": "NORMAL",
    "formality": "NEUTRAL",
    "topTopics": ["zapytanie", "informacja"],
    "summaryText": "Wiadomość zawiera ogólne zapytanie o informacje."
}

Rozwiązywanie problemów

Problem: Aplikacja nie uruchamia się

Sprawdź:

Czy Docker jest uruchomiony
Czy porty 8080, 8025, 8081 są wolne
Logi aplikacji: docker-compose logs app

Problem: Wiadomości nie są odbierane

Sprawdź:

Czy serwer IMAP jest dostępny i poprawnie skonfigurowany
Czy dane logowania do serwera email są poprawne
Logi aplikacji pod kątem błędów połączenia

Problem: Brak analizy LLM

Sprawdź:

Czy serwer Ollama jest uruchomiony
Czy model LLM jest dostępny
Logi aplikacji pod kątem błędów komunikacji z API LLM

Problem: Szablony nie są ładowane

Sprawdź:

Czy katalog data/templates/ istnieje i zawiera pliki z rozszerzeniem .template
Logi aplikacji w poszukiwaniu błędów ładowania szablonów
Wykonaj curl http://localhost:8080/api/templates aby sprawdzić, czy API widzi szablony

Problem: Archiwizacja nie działa

Sprawdź:

Czy katalog data/archive/ istnieje i czy aplikacja ma uprawnienia do zapisu
Logi aplikacji w poszukiwaniu błędów podczas archiwizacji
Sprawdź, czy po przetworzeniu wiadomości pojawiają się nowe pliki w katalogu archiwum

Wsparcie

W przypadku problemów lub pytań:

Sprawdź logi aplikacji: docker-compose logs app
Sprawdź dokumentację Apache Camel: https://camel.apache.org/
Uruchom skrypt testowy: ./test-advanced-reply.sh frequent aby sprawdzić działanie zaawansowanych funkcjonalności
Zgłoś problem w repozytorium projektu

Name		Name	Last commit message	Last commit date
Latest commit History 5 Commits
COMPARE		COMPARE
config		config
data		data
scripts		scripts
src		src
.env		.env
.env.example		.env.example
.gitignore		.gitignore
DOKUMENTACJA.md		DOKUMENTACJA.md
Dockerfile		Dockerfile
README.md		README.md
camel-routes.xml		camel-routes.xml
docker-compose.yml		docker-compose.yml
docker-entrypoint.sh		docker-entrypoint.sh
package.json		package.json
run.sh		run.sh
src.md		src.md
test-advanced-reply.sh		test-advanced-reply.sh
test-email.sh		test-email.sh

fin-officer/js

Folders and files

Latest commit

History

Repository files navigation

Email LLM Processor - Dokumentacja

Przegląd

Funkcjonalności

Architektura

Główne komponenty

Model danych

Baza danych

System szablonów

System archiwizacji

Wymagania

Instalacja

Instalacja za pomocą skryptów

Instalacja ręczna

Uruchomienie

Uruchomienie z rozszerzonymi funkcjonalnościami

Uruchomienie za pomocą standardowych skryptów

Uruchomienie manualne

Uruchomienie lokalne bez Dockera

Dostęp do usług

Testowanie

Testowanie zaawansowanych funkcjonalności

Standardowe testowanie

Testowanie API

Testowanie API szablonów

Struktura kodu

src/index.js

src/models

src/services

src/utils

camel-routes.xml

scripts

System szablonów i automatycznych odpowiedzi

Zasada działania

Struktura katalogów

Rodzaje szablonów

Placeholdery w szablonach

Przykład szablonu

Proces wyboru szablonu

Archiwizacja wiadomości

Cel archiwizacji

Struktura katalogów

Format plików archiwalnych

REST API

Przetwarzanie wiadomości e-mail

Zarządzanie szablonami

Sprawdzenie stanu aplikacji

Zmienne środowiskowe

Rozszerzanie funkcjonalności

Dodawanie nowych tras Camel

Dostosowanie analizy LLM

Dostosowanie systemu szablonów

Dostosowanie archiwizacji wiadomości

Integracja z LLM

Prompt dla modelu LLM

Format odpowiedzi

Rozwiązywanie problemów

Problem: Aplikacja nie uruchamia się

Problem: Wiadomości nie są odbierane

Problem: Brak analizy LLM

Problem: Szablony nie są ładowane

Problem: Archiwizacja nie działa

Wsparcie

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Languages

Packages