spam-detector/README.md

# Spam Detector

ПО для борьбы со спамом

## Компоненты

### Диаграмма компонентов

![c4model.png](docs/c4model.png)

### Dataset

- необходим первоначальный датасет (ham/spam) в формате CSV

### Model

- использует датасет
- модели генерируются https://pypi.org/project/spam-detector-ai/
    - naive_bayes_model.joblib
    - random_forest_model.joblib
    - svm_model.joblib
    - logistic_regression_model.joblib
    - xgb_model.joblib
 
### Decision Maker

- компонент, который принимает решения
- представлен в виде Web-сервера
- реализует API
  - POST `/check-spam` - открытый для пользователей
    - auth: none
    - request
      - body `{ "text": "SOME TEXT" }
    - response
      - status code 200
      - body `{ "is_spam": true }`
  - POST `/update-model` - служебный, добавляет текст в датасет
    - auth: TOKEN
    - request
      - body: `{ "text": "SOME TEXT", "is_spam": true }`
    - response
      - status code 200
      - body `{ "status": "OK" }`
  - POST `/restart` - служебный, перезапускает данный компонент
    - auth: TOKEN
    - request
      - body: none
    - response
      - status code 200
      - body `{ "status": "OK" }`

#### Sequence diagram

![sequence](docs/sequence.png)

### Model Updater

- добавляет в датасет новые тексты из базы дообучения
- запускается по графику, выполняет
  - сделать бэкап модели
  - запустить дообучение
  - при успешном результате дообучения
    - вызывает POST `/restart` компонента Decision Maker

### Transport

- используется [Rabbit MQ](https://rabbitmq.com/)

## Use cases

### Телеграм-бот

- приходит сообщение в группу в телегу
- бот его читает (не входит в данный комплекс)
- отправляет на проверку
- получает результат: спам/не спам
- если спам - бот удаляет сообщение

### На почте

- та же схема, только должен быть работающий клиент почты, который читает каждое сообщение, и если обнаружился спам, то помечать его спамом (помещать в категорию спам)

## Дообучение с учителем

### Сбор доп.текстов через Телеграм

- владелец бота в телеге встречает сообщение, которое является спамом, но не было удалено
- это сообщение отправляется в ТГ бот спам-определителя (не реализовано)
- сообщение помещается в базу для дообучения

### Сбор доп.текстов через почту

- спам-письмо можно отправить на почту, которую читает бот (не реализовано)
- бот кладет текст письма в базу дообучения

### Дообучение

- читает из RabbitMQ и дописывает в конец dataset CSV
- 1 р/сут переобучивает модель