shyamalschandra / zhorai

An interactive conversational agent for AI education.

Zhorai

An interactive conversational agent for K-12 AI education. See the EAAI 2020 paper about Zhorai here. The Zhorai website uses the Bootstrap library to construct the overall site framework, the Web Speech API for speech recognition and synthesis, and the D3 JavaScript library for mindmap and scatter plot visualizations.

Setup

After cloning the repository, there are two ways to set up Zhorai:

1. With Docker (recommended)
2. Manually

With Docker

The easiest way to run the whole system is through Docker and Docker Compose.

Install Docker for Mac or Docker for Windows and Docker Compose should be included. You should be able to run

docker -v && docker-compose -v

and output should be similar to

Docker version 19.03.2, build 6a30dfc
docker-compose version 1.24.1, build 4667896b

Docker Compose automatically runs the server and web services (explained below) that are defined in docker-compose.local.yml and docker-compose.yml. As described in the following setup sections, use docker-compose.local.yml for local development and docker-compose.yml for production. Note that Docker Compose additionally runs the nginx service for production.

1. server: Semantic parser and website backend that communicates with the parser
2. web: Frontend server that allows clients to interface with the backend
3. nginx: Web server for https (which is only run in production)

As noted above, there are two YAML files that can be used with docker-compose:

• docker-compose.yml: for production (with https, nginx, etc.)
• docker-compose.local.yml: used for local development - main difference is no service is needed for a reverse-proxy and CertBot since everything is local

See Local Docker setup or Docker setup for production depending on your needs.

Local Docker setup

To run the system for local development using docker-compose, run in the project root:

docker-compose -f docker-compose.local.yml up --build

To view the Zhorai website, go to http://localhost:8080. Once done, see Docker take down.

Docker setup for production

To set up the system for production, nginx and certbot need to be set up. To do so, you can follow the instructions found in this Medium article. Example app.conf and init-letsencrypt.sh files can be found at zhorai/data/nginx/app.templateconf and zhorai/init-letsencrypt.templatesh.

To run the system for production with docker-compose, run in the project root:

docker-compose -f docker-compose.yml up --build

Now you should be able to view your Zhorai website at your domain. To take down the site, see Docker take down.

Docker take down

Once done, run the following command to clean up containers created by docker-compose up.

docker-compose -f docker-compose.local.yml down
# or for production, change `docker-compose.local.yml` to `docker-compose.yml`

Development/testing within Docker container

To enter into the docker container (e.g., for testing installed libraries), use docker exec -it as follows:

docker container list
# from the output of the above commant, find the relevant container id (associated 
# with the image name, `zhorai_web` or `zhorai_server` for the `web` and `server` 
# services respectively), and use it in the command below instead of <CONTAINER_ID>
docker exec -it <CONTAINER_ID> /bin/bash

Manual setup

Although manual setup is not recommended, it is possible. To do so, you will have to set up the semantic paser and the frontend and backend node servers.

For first-time setup of the semantic parser, follow the README in the semantic-parser directory.

For first-time setup of the backend node server, install the node dependencies:

cd website-backend/receive-text
npm install

For first-time setup of the frontend express server, do the same:

cd website-frontend
npm install

If the semantic parser has previously been set up, you can start it with:

cd semantic-parser/stanford-corenlp-full-2018-10-05
java -mx6g -cp "*" edu.stanford.nlp.pipeline.StanfordCoreNLPServer -timeout 5000

To start the backend node server:

cd website-backend/receive-text
npm run devstart
# or run `npm start` for production

Similarly, to start the frontend express server:

cd website-frontend
npm run devstart
# or run `npm start` for production

For local development, to view the Zhorai website, go to http://localhost:8080. For production, you will additionally have to set up certificates for your domain.