# zoozl
Server for chatbot services
## Usage
For basic example a chatbot plugin is provided in `zoozl.plugins` package. It is a simple chatbot that allows to play bulls & cows game. It is also a plugin that is loaded in case no configuration file is provided.
### Run websocket server
```bash
python -m zoozl 1601 --conf chatbot.toml
```
where `1601` is the port number and `chatbot.toml` is optional configuration file.
## Architecture
zoozl package contains modules that handle various input interfaces like websocket or http POST and a chatbot interface that must be extended by plugins. Without plugin zoozl is not able to respond to any input. Plugin can be considered as a single chat assistant to handle a specific task. Plugin can be huge and complex or simple and small. It is up to the developer to decide how to structure plugins.
## Plugin
### Mimimal setup
1. Create new toml configuration file (e.g. myconfig.toml)
```
extensions = ['my_plugin_module']
```
2. Make sure `my_plugin_module` is importable from within python that will run zoozl server
3. Create file `my_plugin_module.py`
```
from zoozl.chatbot import Interface
class MyPlugin(Interface):
aliases = ("call myplugin",)
def consume(self, context: , package: Package):
package.callback("Hello this is my plugin response")
```
4. Start zoozl server with your configuration file and asking to bot `call myplugin` it will respond `Hello this is my plugin response`
```bash
python -m zoozl 1601 --conf myconfig.toml
```
### Plugin interface
Plugin must implement `consume` method that takes two arguments `context` and `package`. `context` is a dictionary that contains information about the current chatbot state and `package` is a `Package` object that contains input message and callback method to send response back to the user.
Plugin may define `aliases` attribute that is a tuple of strings that are used to call the plugin. If `aliases` is not defined, plugin will not be called. Aliases are like commands that user can call to interact with the plugin, however those commands are constructed as embeddings and then compared with input message embeddings to find the best match.
Special aliases are help, cancel and greet. Help aliases is used when there is no matching aliases found in plugins, cancel alias is used to cancel current conversation and release it from current plugin handling, greet alias is called immediately before any user message is handled.
If there is only one plugin expected, then aliases most likely should contain all three special aliases, thus plugin will be as soon as connection is made and everytime user asks anything.
### Configuration file
Configuration file must conform to TOML format. Example of configuration:
```
extensions = ["chatbot_fifa_extension", "zoozl.plugins.greeter"]
websocket_port = 80 # if not provided, server will not listen to websocket requests
author = "my_chatbot_name" # default is zoozl
[chatbot_fifa_extension] # would be considered as specific configuration for plugin
database_path = "tests/tmp"
administrator = "admin"
```
Root objects like author, extensions are configuration options for chatbot system wide setup, you can pass unlimited objects in configuration, however suggested is to add a component for each plugin and separate those within components.
* TODO: Describe plugin interface and creation
* TODO: Add authentication and authorization interaction between chatbot and plugin
Raw data
{
"_id": null,
"home_page": "https://github.com/Kolumbs/zoozl",
"name": "zoozl",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": null,
"author": "Juris Kaminskis",
"author_email": "juris@kolumbs.net",
"download_url": "https://files.pythonhosted.org/packages/96/98/2420c69d3a7907b87c3b91eb477024863a62d6a8a8489d16a5c95ed93597/zoozl-0.1.3.tar.gz",
"platform": null,
"description": "# zoozl\n\nServer for chatbot services\n\n## Usage\n\nFor basic example a chatbot plugin is provided in `zoozl.plugins` package. It is a simple chatbot that allows to play bulls & cows game. It is also a plugin that is loaded in case no configuration file is provided.\n\n### Run websocket server\n\n```bash\npython -m zoozl 1601 --conf chatbot.toml\n```\nwhere `1601` is the port number and `chatbot.toml` is optional configuration file.\n\n## Architecture\n\nzoozl package contains modules that handle various input interfaces like websocket or http POST and a chatbot interface that must be extended by plugins. Without plugin zoozl is not able to respond to any input. Plugin can be considered as a single chat assistant to handle a specific task. Plugin can be huge and complex or simple and small. It is up to the developer to decide how to structure plugins.\n\n\n\n## Plugin\n\n### Mimimal setup\n\n1. Create new toml configuration file (e.g. myconfig.toml)\n```\nextensions = ['my_plugin_module']\n```\n2. Make sure `my_plugin_module` is importable from within python that will run zoozl server\n3. Create file `my_plugin_module.py`\n```\nfrom zoozl.chatbot import Interface\n\nclass MyPlugin(Interface):\n\n aliases = (\"call myplugin\",)\n\n def consume(self, context: , package: Package):\n package.callback(\"Hello this is my plugin response\")\n```\n4. Start zoozl server with your configuration file and asking to bot `call myplugin` it will respond `Hello this is my plugin response`\n```bash\npython -m zoozl 1601 --conf myconfig.toml\n```\n\n### Plugin interface\n\nPlugin must implement `consume` method that takes two arguments `context` and `package`. `context` is a dictionary that contains information about the current chatbot state and `package` is a `Package` object that contains input message and callback method to send response back to the user.\n\nPlugin may define `aliases` attribute that is a tuple of strings that are used to call the plugin. If `aliases` is not defined, plugin will not be called. Aliases are like commands that user can call to interact with the plugin, however those commands are constructed as embeddings and then compared with input message embeddings to find the best match.\n\nSpecial aliases are help, cancel and greet. Help aliases is used when there is no matching aliases found in plugins, cancel alias is used to cancel current conversation and release it from current plugin handling, greet alias is called immediately before any user message is handled.\n\nIf there is only one plugin expected, then aliases most likely should contain all three special aliases, thus plugin will be as soon as connection is made and everytime user asks anything.\n\n### Configuration file\n\nConfiguration file must conform to TOML format. Example of configuration:\n```\nextensions = [\"chatbot_fifa_extension\", \"zoozl.plugins.greeter\"]\nwebsocket_port = 80 # if not provided, server will not listen to websocket requests\nauthor = \"my_chatbot_name\" # default is zoozl\n\n[chatbot_fifa_extension] # would be considered as specific configuration for plugin\ndatabase_path = \"tests/tmp\"\nadministrator = \"admin\"\n```\n\nRoot objects like author, extensions are configuration options for chatbot system wide setup, you can pass unlimited objects in configuration, however suggested is to add a component for each plugin and separate those within components.\n\n\n* TODO: Describe plugin interface and creation\n* TODO: Add authentication and authorization interaction between chatbot and plugin\n",
"bugtrack_url": null,
"license": null,
"summary": "Zoozl services for chatbots",
"version": "0.1.3",
"project_urls": {
"Homepage": "https://github.com/Kolumbs/zoozl"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "58dc6b81382c00ffb0fecfbd0acbcf283a888f64757a685d7be3761a5b543569",
"md5": "4c3a139a19a783300a7179eb6dadf299",
"sha256": "fdafe1f4237597d5d0d544a1e0e0d8971b6b66e46f107ca60351c7eb38966edb"
},
"downloads": -1,
"filename": "zoozl-0.1.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "4c3a139a19a783300a7179eb6dadf299",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 17478,
"upload_time": "2024-10-17T06:11:01",
"upload_time_iso_8601": "2024-10-17T06:11:01.986709Z",
"url": "https://files.pythonhosted.org/packages/58/dc/6b81382c00ffb0fecfbd0acbcf283a888f64757a685d7be3761a5b543569/zoozl-0.1.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "96982420c69d3a7907b87c3b91eb477024863a62d6a8a8489d16a5c95ed93597",
"md5": "f9517a0034c951df8db4b58c6bd124fd",
"sha256": "523ad182159ddad7a427992cf28dea489dd7d2513c433f9ace6bf75cb225cbde"
},
"downloads": -1,
"filename": "zoozl-0.1.3.tar.gz",
"has_sig": false,
"md5_digest": "f9517a0034c951df8db4b58c6bd124fd",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 16043,
"upload_time": "2024-10-17T06:11:03",
"upload_time_iso_8601": "2024-10-17T06:11:03.694615Z",
"url": "https://files.pythonhosted.org/packages/96/98/2420c69d3a7907b87c3b91eb477024863a62d6a8a8489d16a5c95ed93597/zoozl-0.1.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-17 06:11:03",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Kolumbs",
"github_project": "zoozl",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "zoozl"
}
JSON
