quackamollie-core 0.1rc2

Core component of the Quackamollie Telegram chat bot

Name:

Quackamollie Core

Package name:

quackamollie-core

Description:

Core of the Quackamollie Telegram personal chat bot

Version:

0.1rc2

Main page:

https://gitlab.com/forge_of_absurd_ducks/quackamollie/lib/quackamollie_core

PyPI package:

https://pypi.org/project/quackamollie-core/

Docker Image:

registry.gitlab.com/forge_of_absurd_ducks/quackamollie/lib/quackamollie_core:0.1rc2

Documentation:

https://quackamollie-core-forge-of-absurd-ducks-quackamo-49d876569a9ad7.gitlab.io

Build Status:

Master:

Dev:

---

Project description

Quackamollie is a Telegram chat bot in Python using the library aiogram to serve LLM models running locally using Ollama. This package is the core of the Quackamollie project. It contains:

• a command line interface which automatically discover addons declared as entrypoints.

• the main commands, filters and callbacks for interacting with Quackamollie through Telegram

• SQLAlchemy database connectors and models for Quackamollie

• Alembic configuration to automatically migrate Postgres database

• a docker-compose configuration to run a Postgres database

• meta-classes for models and model managers

• auto-discovery of models, model managers and CLI subcommands using entrypoints

WARNING

This project is still in early stages and a lot of upgrades are yet to come.

Also, this module contains only the core logic of Quackamollie. To install Quackamollie easily with model managers and models, we invite you to use the main project quackamollie which should be released this week (week 28 of 2024).

Finally, the documentation of this project is still laking a lot of things. Sorry for the inconvenience.

About Quackamollie

This project aims to provide a Telegram chat bot for personal use and running on local desktop.

What this project is:

• a Telegram chat bot that you have to run on your own

• a project aiming for personal use and/or use with friends or family

• a project developed by currently one author and offered as an open source project by a non-profit association named the Forge of Absurd Ducks

What this project is NOT:

• it is NOT a platform with servers aiming to provide service to a large number of users

• it is NOT a commercial project

Roadmap

We have a lot of features in mind for Quackamollie. We are currently releasing some projects which have already been prototyped This projects implement:

• easy installation of quackamollie’s components (quackamollie)

• model managers to serve models through Telegram (quackamollie-ollama-model-manager, quackamollie-llama-index-model-manager, quackamollie-langchain-model-manager)

• models to answer requests through Telegram (quackamollie-llama-index-simple-model, quackamollie-langchain-simple-model)

• some CLI tools to help developing (quackamollie-devtools)

• a repository with CI/CD to auto-deploy quackamollie using docker-compose on local desktop using gitlab-runner (quackamollie-ops)

• a repository with common CI/CDs for Quackamollie’s projects (quackamollie-workflows)

These projects should be released very soon and then we will work on new functionalities such as:

• new models (including RAG, pictures, etc.)

• new tools for the models (including calendars, todolist, item lists for groceries, etc.)

• new boilerplates to simplify creation of models, model tools, model managers and CLI commands

• improving the /settings or other in-chat functionalities

Requirements

Virtual environment

• Setup a virtual environment in python 3.10

make venv
# or
python3 -m venv venv

• Activate the environment

source venv/bin/activate

• If you want to deactivate the environment

deactivate

Tests

Tests requirements

• Install test requirements

make devtools
# or
pip install tox

Run pytest

• Run the tests

tox

Run lint

• Run the lintage

tox -e lint

Documentation

• To auto-generate the documentation configuration

tox -e gendocs

• To generate the documentation in Html

tox -e docs

• An automatically generated version of this project documentation can be found at here

Install

• Install the application from sources

make install
# or
pip install .

• Or install it from distribution

pip install dist/quackamollie-core-0.1rc2.tar.gz

• Or install it from wheel

pip install dist/quackamollie-core-0.1rc2.whl

• Or install it from PyPi repository

pip install quackamollie-core  # latest
# or
pip install "quackamollie-core==0.1rc2"

Docker

• To build the application docker

docker build --network=host -t quackamollie_core:0.1rc2 .

• The official Docker image of this project is available at: registry.gitlab.com/forge_of_absurd_ducks/quackamollie/lib/quackamollie_core

• You can pull the image of the current release:

docker pull registry.gitlab.com/forge_of_absurd_ducks/quackamollie/lib/quackamollie_core:latest  # or dev
# or
docker pull registry.gitlab.com/forge_of_absurd_ducks/quackamollie/lib/quackamollie_core:0.1rc2

Docker-compose

• To run database using docker-compose, you must first set environment variables:

• QUACKAMOLLIE_DB_HOST: typically 0.0.0.0

• QUACKAMOLLIE_DB_PORT: typically 5432

• QUACKAMOLLIE_DB_NAME: typically quackamollie

• QUACKAMOLLIE_DB_USERNAME: typically quackamollie

• QUACKAMOLLIE_DB_PASSWORD: choose a strong admin password

• Then you can run:

docker compose up
# or to detach
docker compose up -d

# if you need to run it with sudo don't forget to add the -E option to pass the environment variables you've set
sudo -E docker compose up

Database migration

• Quackamollie provides a wrapper for the alembic command which initializes the database info the same way they are initialized at runtime. You can call alembic by using instead quackamollie db alembic. For example:

quackamollie db alembic --help

• We recommend you to use a configuration file using one of the examples provided in config/examples/ and to change variables to match the ones used when calling docker compose up.

• To create schema revision if the database changes:

quackamollie -c config/config.yml db alembic revision --autogenerate -m "A new change."

• You can then inspect the migration code (in python) with:

cat migrations/versions/*

• Also inspect the resultant SQL code with:

quackamollie -c config/config.yml db alembic upgrade --sql +1

• Finally, you can apply the migration with:

quackamollie -c config/config.yml db alembic upgrade +1  # If you want to jump from 1
quackamollie -c config/config.yml db alembic upgrade head  # If you want to go all the way to head

• If you now connect to pgcli, you can test that the new table exists:

make dbtools
pgcli -U ${QUACKAMOLLIE_DB_USERNAME} -h ${QUACKAMOLLIE_DB_HOST} -p ${QUACKAMOLLIE_DB_PORT} ${QUACKAMOLLIE_DB_NAME}
# and then on the pgcli console:
\dt
# and again on the pgcli console:
SELECT * FROM users;

• alembic downgrade -1

quackamollie -c config/config.yml db alembic downgrade -1

• You can also migrate using the docker image from our official docker registry.

docker run --rm --name quackamollie-migration \
--network host \
--mount type=bind,source="$(pwd)"/config/config.yml,target=/config/config.yml,readonly \
registry.gitlab.com/forge_of_absurd_ducks/quackamollie/lib/quackamollie_core:0.1rc2 \
-vvvv -c /config/config.yml db alembic upgrade head

# if you need to run it with sudo don't forget to add the -E option to pass the environment variables you've set
sudo -E docker run --rm --name quackamollie-migration \
--network host \
--mount type=bind,source="$(pwd)"/config/config.yml,target=/config/config.yml,readonly \
registry.gitlab.com/forge_of_absurd_ducks/quackamollie/lib/quackamollie_core:0.1rc2 \
-vvvv -c /config/config.yml db alembic upgrade head

• To do the same using docker-compose, please refer to the quackamollie main repository.

Running the project

Quackamollie-core provides a command tool line named quackamollie. You can find examples of configuration files in the folder config/examples.

quackamollie -vvvv -c config/config.yml serve

Pictures and demonstration videos will be included in the documentation in future releases.

Database

• This is the latest schema of the database, generated automatically by the plugin quackamollie-devtools (can be installed using pip install quackamollie-devtools):

Authors

• QuacktorAI - Initial work - quacktorai

Contributing

Currently, contributions are frozen because the project is still in very early stages and I have yet to push the whole architecture.

For more details on the general contributing mindset of this project, please refer to CONTRIBUTING.md.

Credits

Section in writing, sorry for the inconvenience.