Metadata-Version: 2.1
Name: quackamollie-core
Version: 0.1rc3
Summary: Core component of the Quackamollie Telegram chat bot
Author-email: QuactorAI <quacktorai@gmail.com>
License: MIT License
        
        Copyright (c) 2024 - Forge of Absurd Ducks
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://gitlab.com/forge_of_absurd_ducks/quackamollie/lib/quackamollie_core
Keywords: telegram,bot,aiogram,llamaindex,ollama,llmsherpa
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Requires-Python: >=3.10
Description-Content-Type: text/x-rst
License-File: LICENSE
Requires-Dist: aiogram
Requires-Dist: alembic
Requires-Dist: alembic-postgresql-enum
Requires-Dist: asyncpg
Requires-Dist: click
Requires-Dist: coloredlogs
Requires-Dist: pyfiglet
Requires-Dist: pyyaml
Requires-Dist: sqlalchemy[asyncio]
Provides-Extra: lint
Requires-Dist: check-manifest; extra == "lint"
Requires-Dist: flake8; extra == "lint"
Requires-Dist: readme_renderer; extra == "lint"
Requires-Dist: safety; extra == "lint"
Requires-Dist: setuptools; extra == "lint"
Requires-Dist: twine; extra == "lint"
Requires-Dist: wheel; extra == "lint"
Provides-Extra: test
Requires-Dist: coverage; extra == "test"
Requires-Dist: pytest; extra == "test"
Requires-Dist: pytest-cov; extra == "test"
Requires-Dist: pytest-xdist; extra == "test"
Requires-Dist: tox; extra == "test"
Provides-Extra: doc
Requires-Dist: sphinx; extra == "doc"
Requires-Dist: sphinx-click; extra == "doc"

=================
Quackamollie-Core
=================

:Name: Quackamollie Core
:Package name: quackamollie-core
:Description: Core of the Quackamollie Telegram personal chat bot
:Version: 0.1rc3
: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.1rc3
:Documentation: https://quackamollie-core-forge-of-absurd-ducks-quackamo-49d876569a9ad7.gitlab.io
:Build Status:
    :Master: |master_pipeline_badge| |master_coverage_badge|
    :Dev: |dev_pipeline_badge| |dev_coverage_badge|

.. |master_pipeline_badge| image:: https://gitlab.com/forge_of_absurd_ducks/quackamollie/lib/quackamollie_core/badges/master/pipeline.svg
   :target: https://gitlab.com/forge_of_absurd_ducks/quackamollie/lib/quackamollie_core/commits/master
   :alt: Master pipeline status
.. |master_coverage_badge| image:: https://gitlab.com/forge_of_absurd_ducks/quackamollie/lib/quackamollie_core/badges/master/coverage.svg
   :target: https://gitlab.com/forge_of_absurd_ducks/quackamollie/lib/quackamollie_core/commits/master
   :alt: Master coverage status

.. |dev_pipeline_badge| image:: https://gitlab.com/forge_of_absurd_ducks/quackamollie/lib/quackamollie_core/badges/dev/pipeline.svg
   :target: https://gitlab.com/forge_of_absurd_ducks/quackamollie/lib/quackamollie_core/commits/dev
   :alt: Dev pipeline status
.. |dev_coverage_badge| image:: https://gitlab.com/forge_of_absurd_ducks/quackamollie/lib/quackamollie_core/badges/dev/coverage.svg
   :target: https://gitlab.com/forge_of_absurd_ducks/quackamollie/lib/quackamollie_core/commits/dev
   :alt: Dev coverage status

----

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

.. code-block:: bash

   make venv
   # or
   python3 -m venv venv

- Activate the environment

.. code-block:: bash

   source venv/bin/activate

- If you want to deactivate the environment

.. code-block:: bash

   deactivate


Tests
=====

Tests requirements
------------------
- Install test requirements

.. code-block:: bash

   make devtools
   # or
   pip install tox

Run pytest
----------
- Run the tests

.. code-block:: bash

   tox

Run lint
--------
- Run the lintage

.. code-block:: bash

   tox -e lint


Documentation
=============

- To auto-generate the documentation configuration

.. code-block:: bash

   tox -e gendocs

- To generate the documentation in Html

.. code-block:: bash

   tox -e docs

- An automatically generated version of this project documentation can be found at `here <https://quackamollie-core-forge-of-absurd-ducks-quackamo-49d876569a9ad7.gitlab.io>`_


Install
=======
- Install the application from sources

.. code-block:: bash

   make install
   # or
   pip install .

- Or install it from distribution

.. code-block:: bash

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

- Or install it from wheel

.. code-block:: bash

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

- Or install it from PyPi repository

.. code-block:: bash

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


Docker
======
- To build the application docker

.. code-block:: bash

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

- 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:

.. code-block:: bash

   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.1rc3


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:

.. code-block:: bash

   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:

.. code-block:: bash

   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:

.. code-block:: bash

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

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

.. code-block:: bash

   cat migrations/versions/*

- Also inspect the resultant SQL code with:

.. code-block:: bash

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

- Finally, you can apply the migration with:

.. code-block:: bash

   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:

.. code-block:: bash

   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

.. code-block:: bash

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

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

.. code-block:: bash

   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.1rc3 \
   -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.1rc3 \
   -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`.

.. code-block:: bash

   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 <https://gitlab.com/forge_of_absurd_ducks/quackamollie/lib/cli/quackamollie_devtools>`_ (can be installed using `pip install quackamollie-devtools`):

.. image:: https://gitlab.com/forge_of_absurd_ducks/quackamollie/lib/cli/quackamollie_devtools/-/raw/master/schemas/quackamollie_schema_latest.png
   :alt: Quackamollie database schema automatically generated by plugin quackamollie-devtools


Authors
=======

- **QuacktorAI** - *Initial work* - `quacktorai <https://gitlab.com/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 <CONTRIBUTING.md>`_.


Credits
=======

Section in writing, sorry for the inconvenience.
