diff --git a/README.md b/README.md index f020bc3..b9f8cd9 100644 --- a/README.md +++ b/README.md @@ -1,60 +1,44 @@ -# OpenChatAiBot V2 +# OCAB - Open Chat Ai Bot ## Что такое OCAB? -OCAB - это бот для Telegram, который призван помочь во взаимодействии с чатом. -Бот поддерживает интеграцию модулей для расширения функционала. -Фактически бот является платформой для запуска созданных для него модулей. -Модули могут взаимодействовать друг с другом или быть полностью независимыми. +OCAB - это платформа для разработки модульных Telegram-ботов, которая призвана упростить взаимодействие с чатами. +OCAB предоставляет возможность расширять функциональность бота с помощью интеграции различных модулей. +Код платформы и набор стандартных модулей находятся в этом монорепозитории. -## Что такое модуль? +## Структура монорепозитория -Модуль - это директория, которая содержит в себе код модуля и его конфигурацию. +Монорепозиторий OCAB включает в себя: +* **Ядро OCAB (src/ocab_core):** Содержит основные компоненты платформы, такие как система управления модулями, + логирование и утилиты. +* **Модули OCAB (src/ocab_modules):** Содержит стандартные и дополнительные модули, которые расширяют + функциональность ботов OCAB. +* **Пример бота (src/gnomik):** Пример реализации бота на платформе OCAB. + +## Модули + +Модули OCAB - это независимые компоненты, которые добавляют функциональность к боту. ### Структура модуля -*Будет дополнено после закрытия [issue #17](https://gitflic.ru/project/armatik/ocab/issue/17).* +Структура модуля представлена [здесь](docs/MODULES-SPEC.md). -## Стандартные модули +### Стандартные модули -В стандартный состав бота входят следующие модули: +Стандартные модули предоставляют базовые функции для работы бота: +* [admin](src/ocab_modules/ocab_modules/standard/admin/README.md) - модуль для модерирования чата. +* [roles](src/ocab_modules/ocab_modules/standard/roles/README.md) - модуль ролей пользователей. +* [config](src/ocab_modules/ocab_modules/standard/config/README.md) - модуль управления конфигурацией бота. +* [database](src/ocab_modules/ocab_modules/standard/database/README.md) - модуль для работы с базой данных. +* [fsm_database_storage](src/ocab_modules/ocab_modules/standard/fsm_database_storage/README.md) - модуль для хранения состояний FSM в базе данных. +* [filters](src/ocab_modules/ocab_modules/standard/filters/README.md) - модуль, предоставляющий фильтры для aiogram. +* [message_processing](src/ocab_modules/ocab_modules/standard/message_processing/README.md) - модуль обработки входящих сообщений. +* [miniapp](src/ocab_modules/ocab_modules/standard/miniapp/README.md) - модуль для реализации веб-интерфейса бота. +* [command_helper](src/ocab_modules/ocab_modules/standard/command_helper/README.md) - модуль для упрощения регистрации команд бота. +* [info](src/ocab_modules/ocab_modules/standard/info/README.md) - модуль предоставления информации о пользователях и чатах. -* `admin` - модуль для модерирования чата. Позволяет удалять сообщения, банить пользователей и т.д. -* `reputation` - модуль репутации пользователей. Позволяет оценивать ответы пользователей и накапливать репутацию. -* `welcome` - модуль приветствия новых пользователей. Позволяет приветствовать новых пользователей в чате, а также - проверять пользователя капчей для предотвращения спама. -* `roles` - модуль ролей. Позволяет назначать пользователям роли и ограничивать доступ к командам бота по ролям. - Является важной частью системы прав доступа и модуля `admin`. +### Дополнительные официальные модули -## Дополнительные официальные модули - -* `yandexgpt` - модуль для генерации ответов на основе нейросети GPT-3.5. Позволяет боту отвечать на сообщения - пользователей, используя нейросеть. Ключевой особенностью является построение линии контекста для нейросети, - которая позволяет боту отвечать на вопросы, используя контекст предыдущих сообщений. Для этого используется - модуль база данных хранящий историю сообщений. - - -Список модулей будет пополняться. Идеи для модулей можно оставлять в [issues](https://gitflic.ru/project/armatik/ocab/issue/create). - -## Установка бота - -### Docker - -### Вручную - -## Технологический стек - -* Python 3.11.6 или выше - основной язык программирования. -* SQLite 3 - база данных для хранения информации о чате и пользователях. -* [Poetry](https://gitflic.ru/project/armatik/ocab/blob?file=how-to%20install%20deps.md&branch=OCAB-V2) - менеджер зависимостей. -* aiogram 3 - библиотека для работы с Telegram API. -* peewee - ORM для работы с базой данных. +Дополнительные официальные модули разработаны командой OCAB и предоставляют расширенные возможности для бота: +* [yandexgpt](src/ocab_modules/ocab_modules/external/yandexgpt/README.md) - модуль для интеграции с нейросетью YandexGPT. +* [create_report_apps](src/ocab_modules/ocab_modules/external/create_report_apps/README.md) - модуль для создания отчетов об ошибках. diff --git a/docs/DEV.md b/docs/DEV.md new file mode 100644 index 0000000..5962e19 --- /dev/null +++ b/docs/DEV.md @@ -0,0 +1,39 @@ +## Настройка рабочего окружения + +Данная инструкция поможет вам настроить рабочее окружение для разработки OCAB. + +### Предварительные требования + +* **Python 3.12:** OCAB требует Python 3.12. +* **VSCode:** Рекомендуется использовать VSCode для разработки. +* **Git:** У вас должен быть установлен Git для клонирования репозитория. + +### Шаги + +1. **Клонируйте репозиторий:** + ```bash + git clone https://gitflic.ru/project/armatik/ocab.git + ``` + +2. **Откройте проект в VSCode:** + * Откройте папку `ocab` в VSCode. + * VSCode автоматически предложит открыть проект как workspace, используя файл `ocab.code-workspace`. + Нажмите "Открыть Workspace", чтобы принять предложение. + +3. **Настройте Poetry:** + * Установите Poetry, следуя инструкциям на официальном сайте: [https://python-poetry.org/docs/](https://python-poetry.org/docs/). + * **Для каждого пакета:** + * Перейдите в папку пакета (например, `src/ocab_core`). + * Выполните команду `poetry install`, чтобы установить зависимости пакета. + * Poetry создаст виртуальное окружение внутри папки пакета (`.venv`). + +4. **Активируйте виртуальное окружение:** + * Выполните команду `poetry shell` в папке пакета, чтобы активировать виртуальное окружение. + +Теперь ваше рабочее окружение настроено, и вы можете начать. + +### Дополнительная информация + +* Каждый пакет в монорепозитории имеет свой собственный файл `pyproject.toml`, где указаны его зависимости. +* Poetry автоматически управляет виртуальными окружениями для каждого пакета. +* Вы можете использовать команду `poetry add ` для добавления новых зависимостей. diff --git a/how-to install deps.md b/how-to install deps.md deleted file mode 100644 index 39b723c..0000000 --- a/how-to install deps.md +++ /dev/null @@ -1,47 +0,0 @@ -## Poetry - -### Установка с официального сайта - -```shell -curl -sSL https://install.python-poetry.org | python3 - -``` - -### Установка с PyPi - -```shell -python3 -m pip install poetry -``` - -Доп информация:https://www.8host.com/blog/ustanovka-menedzhera-zavisimostej-poetry/ - -## Зависимости - -### Добавление зависимости -```shell -poetry add NAME -``` -`NAME` - название зависимости. - -### Установка зависимостей -```shell -poetry install -``` - -### Обновление зависимостей -```shell -poetry update -``` - -## Виртуальное окружение - -### Создание/активация -```shell -poetry shell -``` - -### Настройка - -Хранить окружение внутри проекта -```shell -poetry config virtualenvs.in-project true -``` diff --git a/src/gnomik/README.md b/src/gnomik/README.md index 13a931d..d3d784f 100644 --- a/src/gnomik/README.md +++ b/src/gnomik/README.md @@ -22,11 +22,29 @@ TODO: описать функционал ## Запуск -Запуск бота осуществляется с помощью команды: +### Docker -```bash -python -m gnomik -``` +1. Соберите Docker-образ: + ```bash + docker build -t gnomik . + ``` +2. Запустите контейнер: + ```bash + docker run -p 9000:9000 -v ./config.yaml:/app/config.yaml -v ./database:/app/database gnomik + ``` + + Замените `./config.yaml` и `./database` на пути к вашим локальным файлам конфигурации и паки для базы данных. + +### Вручную + +1. Активируйте виртуальное окружение Gnomика: + ```bash + poetry shell + ``` +2. Запустите бота: + ```bash + python -m gnomik + ``` ## Конфигурация diff --git a/src/gnomik/config-example.yaml b/src/gnomik/config-example.yaml new file mode 100644 index 0000000..8dce5ef --- /dev/null +++ b/src/gnomik/config-example.yaml @@ -0,0 +1,18 @@ +core: + mode: WEBHOOK + token: xxx + webhook: + public_url: xxx +filters: + approved_chat_id: -4128011756 | -4128011756 + default_chat_tag: '@alt_gnome_chat' +miniapp: + public_url: xxx +yandexgpt: + catalogid: xxx + inword: помогите | не работает + prompt: Ты чат-бот ... + startword: Бот| Бот, | бот | бот, + token: xxx + token_for_answer: 2000 + token_for_request: 8000