Ravestate is a reactive library for real-time natural language dialog systems.
Project description
About
____ __ __ _____ _____
/ _ \____ __ ______ ______/ /_____/ /___ /_ _\ /_ _\
/ /_/ / __ \/ / / / __ \/ ___\, / __ \, / __ \ 0> 0> <0 <0
/ ,\ ,/ /_/ /\ \/ / /_/ /\__, / / /_/ / / /_/ / \__⊽__/ \__⊽__/
\/ \/\__/\/ \__/ ,___/\____/\/\__/\/\/ ,___/ ⋂ - Hey! ⋂
\____/ \____/ Olà! -
Ravestate is a reactive library for real-time natural language dialog systems. It combines elements from event-based and reactive programming into an API, where application states are defined as functions that are run when a certain boolean set of criteria (signals) in the current application context is satisfied. It is the first reactive API to allow for boolean combinations of events. You may find a short introductory video here.
Reactive Hello World
import ravestate as rs
# We want to write some text output, so we
# need the raw:out context property from ravestate_rawio.
import ravestate_rawio as rawio
# Make sure that we use some i/o implementation,
# so we can actually see stuff that is written to rawio:out.
import ravestate_conio
# Ravestate applications should always be wrapped in a Module.
# This allows easier scoping, and enables separation of concerns
# beyond states.
with rs.Module(name="hi!"):
# Create an application state which reacts to the `:startup` signal,
# and writes a string to raw:out. Note: State functions are
# always run asynchronously!
@rs.state(cond=rs.sig_startup, write=rawio.prop_out)
def hello_world(context):
context[rawio.prop_out] = "Waddup waddup waddup!"
# Run context with console input/output and our 'hi!' module.
rs.Context("conio", "hi!").run()
Visualization
Ravestate has a d3.js-based visualization. When using ravestate_ui.UIContext
instead of Context
, or python3 -m ravestate_ui
instead of python3 -m ravestate
, a real-time visualization of all states/properties/signals in the state machine will be hosted on port 5001. Here is the view of http://localhost:5001
after launching python3 ravestate_ui -f generic.yml
:
Installation
Via PIP
The easiest way to install ravestate is through pip:
pip install ravestate
Note: Ravestate requires Python 3.6 or higher. It is tested on Ubuntu 16.04 and 18.04, as well as macOS > High Sierra. It is currently not tested on Windows.
For reliability, we recommend using an environment virtualization tool, like virtualenv or conda.
For developers
Initial configuration and setup
Clone the repository and install dependencies:
# Create a virtual python environment to not pollute the global setup
python3 -m virtualenv python-ravestate
# Source the virtual environment
. python-ravestate/bin/activate
# Clone the repo
git clone git@github.com:roboy/ravestate && cd ravestate
# Install normal requirements
pip install -r requirements.txt
# To run tests & build docs, install pytest, mocking, fixtures, pydoc, ...
pip install -r requirements-dev.txt
# Link your local ravestate clone into your virtualenv
pip install -e .
Now, launch a Neo4j docker instance to serve Scientio, so the dialog system has a memory:
docker run \
--publish=7474:7474 --publish=7687:7687 \
--volume=$HOME/neo4j/data:/data \
--volume=$HOME/neo4j/logs:/logs \
neo4j:latest
# Open the address localhost:7474 in a browser, and enter the
# credentials `neo4j`/`neo4j`. You will then be prompted to enter
# your own password. Remember this password.
In the config
folder, create a file called keys.yml
. It should have the following content:
module: telegramio
config:
telegram-token: <sexycactus> # This is where your own telegram bot token
# will go later
---
module: ontology
config:
neo4j_address: bolt://localhost:7687 # Your neo4j server uri here
neo4j_username: neo4j # Your neo4j user here
neo4j_pw: test # Your neo4j pw here
You may now conduct your first conversation with ravestate:
python3 -m ravestate -f config/generic.yml -f config/keys.yml
After the conversation, check the Neo4j interface under localhost:7474
. It should now contain some nodes!
Reminder: Whenever you use ravestate from the command line, source the virtual environment first!
Running your Telegram bot
To test your telegram bot with a custom bot token in your keys.yml
,
just run telegram_test.yml
instead of generic.yml
. This will load the ravestate_telegramio
module.
Setting up PyCharm
- Open your local ravestate clone as a project in pycharm.
- Under
Project Preferences > Python interpreter
, set your virtual environment. - Mark the
modules
folder as sources root via the right-click context menu. - Create a run config via the "Edit configurations menu":
• Create a new Python configuration.
• Setmodules/ravestate/__main__.py
as the script to execute
• Set the working directory to the git clone directory.
• Set parameters to-f config/generic.yml -f config/keys.yml
. - You should now be able to run the generic ravestate config from pycharm.
Running Hello World
Ravestate applications are defined by a configuration, which specifies the ravestate modules that should be loaded.
To run the basic hello world application, run ravestate with a config file or command line arguments:
Running with command line spec
You can easily run a combination of ravestate modules in a shared context,
by listing them as arguments to python3 -m ravestate
:
python3 -m ravestate \
ravestate_wildtalk \
ravestate_conio \
ravestate_hibye \
ravestate_persqa
Run python3 -m ravestate -h
to see more options!
Running with config file(s)
You may specify a series of config files to configure ravestate context, when specifying everything through the command line becomes too laborious:
# In file hello_world.yml
module: core
config:
import:
- ravestate_wildtalk
- ravestate_conio
- ravestate_hibye
- ravestate_persqa
Then, run ravestate
with this config file:
python3 -m ravestate -f hello_world.yml
Module overview
Ravestate offers a landscape of fine-grained modules for different aspects of dialog application tasks, which may be seen in the following dependency diagram. Broadly, the modules are categorized into Core (Blue), I/O (Yellow), External (Red) and Skills (Green):
Core Modules
Module name | Description |
---|---|
ravestate | Core ravestate library. |
ravestate_rawio | Provides raw_in , raw_out , pic_in properties, which are served by the IO modules. |
ravestate_ontology | Connects to scientio to serve a built-in ontology. |
ravestate_interloc | Provides the all_interlocutors property, where present interlocutors are registered by the IO modules. |
ravestate_idle | Provides bored and impatient signals, as specified here. |
ravestate_verbaliser | Utilities for easy management of conversational text, documented here. |
ravestate_nlp | Spacy-based NLP properties and signals, documented here. |
ravestate_ros1 | Provides specific Ros1PubProperty , Ros1SubProperty and Ros1CallProperty context properties, which greatly simplify working with ROS1 in ravestate. Documentation here. |
ravestate_ros2 | Provides specific Ros2PubProperty , Ros2SubProperty and Ros2CallProperty context properties, which greatly simplify working with ROS2 in ravestate. |
IO Modules
Module name | Description |
---|---|
ravestate_conio | Simple command-line based IO for development purposes. |
ravestate_telegramio | Single- or Multi-process Telegram server module, documented here. |
ravestate_roboyio | PyroBoy -based STT/TTS with ROS2. |
Skill Modules
Module name | Description |
---|---|
ravestate_wildtalk | ParlAI -based generative conversational module. |
ravestate_hibye | Simply voices Hi! (or the likes thereof) when an interlocutor is added, and Bye when one is removed. |
ravestate_persqa | Conducts personalized smalltalk with interlocutors, interacts with Scientio to persist trivia. |
ravestate_genqa | DrQA -based general question answering module. |
ravestate_roboyqa | QA module which provides answers to questions about Roboy, such as Who is your dad? |
ravestate_akinator | Enables dialog-based play of Akinator! |
ravestate_sendpics | Uses face recognition to extract facial features and an assiciated Person with pic_in and ontology, which are then persisted in Redis and Scientio. |
ravestate_stalker | Uses facial feature <-> person tuples generated by sendpics, to surprise people in front of a camera with knowledge of their names. |
ravestate_fillers | Recognize when the dialog context is taking a long time to produce an answer, and voice a filler like "Uhm" or "Let's see...". |
Running tests
If you have installed the dependencies from requirements-dev.txt
you
may run the ravestate test suite as follows:
./run_tests.sh
Docker for ROS and ROS2
There is a Dockerfile for ROS and ROS2 support which can be built with
docker build -t ravestate-ros2-image .
The image contains ROS, ROS2 and a ROS Bridge to connect ROS with ROS2. Furthermore the roboy_communication message and service types are installed.
A container can then be created with the docker-compose.yml:
docker-compose up --detach ravestate
The container is now running and a connection into the container can be established with:
docker exec -it ravestate-ros2-container bash
Inside the container, first source the ROS2 setups and then ravestate can be run with ROS2 and rclpy available.
source ~/ros2_ws/install/setup.sh
python3 -m ravestate [...]
Start ROS Bridge
In order to start ROS Bridge, the image and container have to be set up as above. After connecting into the container run from inside the container:
export ROS_IP=192.168.0.105
source ~/melodic_ws/devel/setup.sh
source ~/ros2_ws/install/setup.sh
source ~/ros1_bridge_ws/install/setup.sh
ros2 run ros1_bridge dynamic_bridge
Building/maintaining the docs
If you have installed the dependencies from requirements-dev.txt
,
generate the docs by running this command at project root:
export PYTHONPATH=$PYTHONPATH:$(pwd)/modules
git rm -rf docs
rm -rf _build docs
pydocmd build
mkdir -p docs/resources/docs && cp resources/docs/*.png docs/resources/docs && cp resources/docs/*.gif docs/resources/docs
git add docs/*
# For inspection: python3 -m http.server --directory docs
The structure and content of the docs are defined in the file pydocmd.yml
.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for ravestate-0.7.0rc0-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 36ed2cc645347c5e8a0220100f72af455ad2426c320f273b880bfc9cf9cd0260 |
|
MD5 | d959b4b8af5ef4513bb8c8bf03a44330 |
|
BLAKE2b-256 | cf959ec79c3a6164e7742eeb403c29d255acea79c04b9a9651186c538db1f791 |