Package: ravestate
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 videohere.Reactive Hello Worldimportravestateasrs# We want to write some text output, so we# need the raw:out context property from ravestate_rawio.importravestate_rawioasrawio# Make sure that we use some i/o implementation,# so we can actually see stuff that is written to rawio:out.importravestate_conio# Ravestate applications should always be wrapped in a Module.# This allows easier scoping, and enables separation of concerns# beyond states.withrs.Module(name="hi!",depends=(rawio.mod,)):# 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)defhello_world(context):context[rawio.prop_out]="Waddup waddup waddup!"# Run context with console input/output and our 'hi!' module.rs.Context("hi!").run()RaveboardRavestate has anangular/socket.io-based
interactive (beta) UI calledRaveboard. It shows the events (spikes) that are
currently relevant, as well as potential state activations that are referencing these spikes.When usingraveboard.UIContextinstead ofContext, orpython3 -m raveboardinstead ofpython3 -m ravestate, a real-time visualization of all spikes/activations, as well as a chat window,
will be hosted on a configurable port. You can find dedicated docshere.The following GIF shows raveboard together withravestate_visionio:InstallationVia PIPThe easiest way to install ravestate is through pip:pip install ravestateNote: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,
likevirtualenvorconda.Via Docker/Docker-composeWhy Docker?Ravestate offers a docker image that bundles runtime dependencies that are required
for advanced cognitive dialog systems/chatbots:📦 Neo4j: The Neo4j Graph DBMS is used byScientiofor long-term memory.💡 Redis: A Redis in-memory DB is used for fast short-term memory, e.g. to store/recall facial feature vectors.🤦 FaceOracle: A Roboy-developed server-client architecture used byravestate_visioniofor real-time face recognition.🤖 ROS Melodic: Version 1 of theRobot Operating Systemfor distributed real-time communication.
This version of ROS requires a broker process (roscore), which is started automatically inside the container.🤖 ROS2 Dashing: Version 2 of theRobot Operating Systemfor distributed real-time communication.🤗 HuggingFace Transformer Models: Language models (ConvAI GPT/OpenAI GPT2)
for neural-network-generated conversation.💌 Roboy ROS Messages: Message defs. that are required to interact with Roboy hardware.Installing these dependencies by hand is time-consuming and error-prone, so using Docker
to ship them makes everyone's lives easier!How to build?Clone ravestate:gitclonegit@github.com:roboy/ravestate&&cdravestateYou can build the ravestate container using the providedDockerfile:dockerbuild-travestate.Note: Building the container takes time and requires a good internet connection, since
all of the dependencies are several Gigabytes in size.How to run?Use one of the following docker-compose commands to run ravestate in Docker:PlatformCommandLinuxdocker-compose up -d rs-linuxmacOSdocker-compose up -d rs-macosWindowsNot supported yet.The container is now running and a shell inside the container can be opened with:dockerexec-itrsbashYou can now start ravestate or raveboard as described in the sectionRunning Hello World.python3-mravestate[...]Which services are exposed from the container?ServicePortDescriptionNeo4j UI7474Neo4j UI for DB stored under<ravestate>/db/neo4jNeo4j Bolt Interface7687Communication with Neo4j DBMSRedis Database Dump-A dump of the Redis DB in the container can be found under<ravestate>/db/redisFaceOracle Client Interface8088Visualisation for the FaceOracle client.Raveboard42424Default port for raveboard, the ravestate debug UI.For developmentInitial configuration and setupClone the repository and install dependencies:cd~# Create a virtual python environment to not pollute the global setuppython3-mvirtualenv-ppython3python-ravestate# Source the virtual environment.python-ravestate/bin/activate# Clone the repogitclonegit@github.com:roboy/ravestate&&cdravestate# Install normal requirementspipinstall-rrequirements.txt# To run tests & build docs, install pytest, mocking, fixtures, pydoc, ...pipinstall-rrequirements-dev.txt# Link your local ravestate clone into your virtualenvpipinstall-e.Launch the ravestate docker container as described above. It will serve you Neo4j,
which is a backend forScientio, Roboy's
long-term memory system.In theconfigfolder, create a file calledkeys.yml. It should have the following content:module:telegramioconfig:telegram-token:<sexycactus># This is where your own telegram bot token# will go laterYou may now conduct your first conversation with ravestate:python3-mraveboard-fconfig/generic.yml-fconfig/keys.ymlOpen raveboard onlocalhost:42424/ravestate/index.html?rs-sio-url=http%3A//localhost%3A42424to conduct your first conversation with ravestate.After the conversation, check the Neo4j interface underlocalhost:7474. It should now contain some nodes!Reminder: Whenever you use ravestate from the command line, source the virtual environment first!Running your Telegram botTo test your telegram bot with a custom bot token in yourkeys.yml,
just runtelegram_test.ymlinstead ofgeneric.yml. This will load theravestate_telegramiomodule.Setting up PyCharmOpen your local ravestate clone as a project in pycharm.UnderProject Preferences > Python interpreter, set your virtual environment.Mark themodulesfolder as sources root via the right-click context menu.Create a run config via the "Edit configurations menu":• Create a new Python configuration.• Setraveboardas themoduleto 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 WorldRavestate 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 specYou can easily run a combination of ravestate modules in a shared context,
by listing them as arguments topython3 -m ravestate:python3-mravestate\ravestate_wildtalk\ravestate_conio\ravestate_hibye\ravestate_persqaRunpython3 -m ravestate -hto 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.ymlmodule:coreconfig:import:-ravestate_wildtalk-ravestate_conio-ravestate_hibye-ravestate_persqaThen, runravestatewith this config file:python3-mravestate-fhello_world.ymlModulesRavestate 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 ModulesModule nameDescriptionravestateCore ravestate library.ravestate_rawioProvidesraw_in,raw_out,pic_inproperties, which are served by the IO modules.ravestate_ontologyConnects toscientioto serve a built-in ontology.ravestate_interlocProvides theall_interlocutorsproperty, where present interlocutors are registered by the IO modules.ravestate_idleProvidesboredandimpatientsignals, as specifiedhere.ravestate_verbaliserUtilities for easy management of conversational text, documentedhere.ravestate_nlpSpacy-based NLP properties and signals, documentedhere.ravestate_emotionGenerates signals for, and recognizes specific emotions (sig_shy,sig_surprise,sig_happy,sig_affectionate).ravestate_ros1Provides specificRos1PubProperty,Ros1SubPropertyandRos1CallPropertycontext properties, which greatly simplify working with ROS1 in ravestate. Documentationhere.ravestate_ros2Provides specificRos2PubProperty,Ros2SubPropertyandRos2CallPropertycontext properties, which greatly simplify working with ROS2 in ravestate.IO ModulesModule nameDescriptionravestate_conioSimple command-line based IO for development purposes.ravestate_telegramioSingle- or Multi-process Telegram server module, documentedhere.ravestate_roboyioPyroBoy-based STT/TTS with ROS2.ravestate_visionioSee dedicated docshere. Enables face-recognition based dialog interactions.Skill ModulesModule nameDescriptionravestate_wildtalkSee docshere- runs generative language models (GPT-2, ConvAi, ParlAi)!ravestate_hibyeSimply voicesHi!(or the likes thereof) when an interlocutor is added, andByewhen one is removed.ravestate_persqaConducts personalized smalltalk with interlocutors, interacts with Scientio to persist trivia.ravestate_genqaDrQA-based general question answering module.ravestate_roboyqaQA module which provides answers to questions about Roboy, such asWho is your dad?ravestate_akinator(*)Enables dialog-based play ofAkinator!ravestate_sendpics(*)Uses face recognition to extract facial features and an assiciated Person withpic_inand ontology, which are then persisted in Redis and Scientio.ravestate_fillersRecognize when the dialog context is taking a long time to produce an answer, and voice a filler like"Uhm"or"Let's see...".Note:(*)= deprecated.Running testsIf you have built the ravestate docker image as described above,
you may run the test suite as follows:dockerrun-t-v$(pwd):/ravestate-w/ravestateravestate./run_tests.shBuilding/maintaining the docsIf you have installed the dependencies fromrequirements-dev.txt,
generate the docs by running this command at project root:exportPYTHONPATH=$PYTHONPATH:$(pwd)/modules
gitrm-rfdocs
rm-rf_builddocs
pydocmdbuild
mkdir-pdocs/resources/docs&&cpresources/docs/*.pngdocs/resources/docs&&cpresources/docs/*.gifdocs/resources/docs
gitadddocs/*# For inspection: python3 -m http.server --directory docsThe structure and content of the docs are defined in the filepydocmd.yml.