add some project files

project/documentation.md

@@ -0,0 +1,50 @@
+# Dokumentacja
+<br/><br/>
+## 1. Zarys ogólny
+Celem projektu było stworzenie chatbota pełniącego funkcję interaktywnej "gumowej kaczuszki" znanej z metody o tej samej nazwie stosowanej przez programistów.
+## 2. Mapa empatii
+![mapa](empathy_map.png)
+## 3. Plan systemu sporządzony metodą "writing hills"
+1. Sfera działalności:
+	- interaktywna żółta kaczka dla programisty
+
+2. Użytkownik:
+	- programiści i osoby techniczne
+
+3. Granice działania:
+	- potrafi prowadzić smalltalk o pracy programisty
+	- potrafi doradzić w rozwiązaniu problemu
+	- proponuje narzędzia lub metody użyteczne do rozwiązania problemów
+	- rozumie problemy i wyzwania w codziennej pracy programisty i potrafi się z nim empatyzować
+	- motywuje do pracy i do samorozwoju
+	- ALE: sama z siebie nic nie robi, tylko doradza/sugeruje. Nie przeszkadza w pracy, wchodzi w interakcję, gdy programista tego chce
+## 4. System wartości chatbota
+|Wartości|	Etyka|	Cechy charakteru|	Granice|	Zasady|
+|--------|-------|------------------|----------|----------|
+Empatia|	Zrozumienie potrzeb i problemów programisty|	Taktowny, cierpliwy, uważny|	Nie oceniać programisty	|Słuchać i starać się zrozumieć potrzeby użytkownika|
+Profesjonalizm|	Dbanie o jakość i terminowość realizacji zadań|	Kompetentny, sumienny, rzetelny|	Nie obiecywać czegoś, czego nie da się zrobić|	Wywiązywać się z umowy i terminów|
+Etos pracy zespołowej|	Współpraca, szacunek dla zdania innych|	Współpracujący, otwarty na sugestie|	Nie dyskryminować ani uprzywilejowywać nikogo|	Szanować zdanie i wkład każdego członka zespołu|
+Otwartość i uczciwość|	Otwartość na nowe pomysły i uczciwość w działaniu|	Uczciwy, lojalny, niezawodny|	Nie udawać, że wie coś, czego nie wie|	Mówić prawdę i informować o ograniczeniach
+Dyspozycyjność i dostępność|	Szybka i skuteczna reakcja na zgłoszenia|	Dostępny, pomocny, elastyczny|	Nie ignorować zgłoszeń użytkowników|	Odpowiadać na zgłoszenia w miarę możliwości|
+
+## 5. Model empatii
+Chatbot wykorzystuje model matrioszki. Maon dosyć prostą postać bezpośrednio powiązaną z pewnymi ustalonymi zasadami, według których tworzony był system. Podstawowymi zdolnościami empatycznymi są szacunek dla rozmówcy i otwartość, zawarte w samym sposobie, w jaki chatbot formułuje swoje kwestie - jest uprzejmy i nie narzucający się.
+Przechodząc do specyficznych sytuacji konwersacyjnych, gdy np. gdy programista dzieli się z chatbotem frustracjami związanymi z niedziałającym kodem, są aktywowane bardziej specyficzne zaimplementowane zdolności empatyczne, jak np. współczucie wobec i zrozumienie trudnych sytuacji, z jakimi mierzą się w swojej pracy programiści. Jest odzwierciedlane w odpowiednim sposobie reagowania chatbota, który słucha programisty, pokazuje mu, że rozumie, że jest mu ciężko, i subtelnie proponuje kierunek dalszych działań.
+
+## 6. Struktura systemu
+1. Postać systemu
+
+    System ma postać aplikacji konsolowej napisanej czysto w języku Python.
+
+2. Dziedzina aktywności i dane treningowe
+
+    Chatbot w zamyśle ma pomagać użytkownikom (programistom) z wszelkimi informatycznymi frustracjami, z którymi mogą się oni zmagać w swojej pracy. Z racji trudności stworzenia systemu tego typu czysto za pomocą reguł, przy jego budowie wykorzystane zostały techniki uczenia maszynowego. Mianowicie, został wytrenowany on na fragmencie zbioru danych [Ubuntu Dialogue Corpus](https://arxiv.org/abs/1506.08909) ograniczonym do par pytanie-odpowiedź, dostępnym na platformie [HuggingFace](https://huggingface.co/datasets/sedthh/ubuntu_dialogue_qa). Ubuntu Dialogue Corpus to zbiór ponad 7 milionów tur dialogowych z dialogów pozyskanych z archiwów czatu dotyczącego dystrybucji systemu Linux o nazwie Ubuntu. Ich tematyką jest pomoc techniczna i programistyczna.
+
+3. Architektura
+
+    System ma prostą architekturę. Działając w pętli, przepuszcza on wypowiedzi użytkownika przez dwa moduły: moduł odpowiadania na pytania i moduł empatyczny.
+
+    3.1. moduł odpowiadania na pytania
+    Do generacji odpowiedzi na pytania moduł ten wykorzystuje oparty na architekturze Transformer model [FLAN-T5](https://arxiv.org/pdf/2210.11416.pdf). Dokonany został własnoręczny fine-tuning tego modelu na danych opisanych powyżej, co w rezultacie dało wersję udostępnioną następnie na platformie [HuggingFace](https://huggingface.co/kedudzic/flan_ubuntu_v2). Z punktu widzenia implementacji moduł pobiera po prostu wypowiedź użytkownika, przepuszcza ją przez model, który generuje odpowiedź, a następnie przekazuje ją do modułu empatycznego.
+    3.2. moduł empatyczny
+    Celem modułu empatycznego jest wzbogacenie odpowiedzi na pytanie o wyrażenie empatyczne i emotkę pełniącą funkcję "avatara" bota. Wykorzystuje do tego gotowy model oparty na architekturze Transformer po fine-tuningu: emotion-english-distilroberta-base (bazowy model to [distilroberta](https://arxiv.org/abs/1910.01108)) dostępny na platformie [HuggingFace](https://huggingface.co/j-hartmann/emotion-english-distilroberta-base). Przyjęty został model [sześciu podstawowych emocji Paula Eckmana](https://www.paulekman.com/wp-content/uploads/2013/07/An-Argument-For-Basic-Emotions.pdf): złość, obrzydzenie, strach, radość, smutek, zaskoczenie, plus dodatkowa etykieta "neutral". Moduł analizuje pytanie użytkownika pod kątem dominującej emocji przy pomocy modelu i do odpowiedzi dołącza losową reakcję na zidentyfikowaną emocję wraz z odpowiadającą emotką, gdzie oba te elementy zaczerpnięte są z małej bazy zawierającej kilka reakcji i po jednej emotce na emocję. W podstawowej formie baza ta jest Pythonowym słownikiem, ale przy większych rozmiarach mogłaby np. być ładowana z pliku json. Po dołączeniu elementów empatycznych do odpowiedzi jest ona zwracana na ekran konsoli, gdzie czyta ją użytkownik.