Maierovidiuwilson [624393]

FACULTY OF AUTOMATION AND COMPUTER SCIENCE
COMPUTER SCIENCE DEPARTMENT
WILSON: A CHATBOT SYMPTOM CHECKER
LICENSE THESIS
Graduate: Ioan-Ovidiu MAIER
Supervisor: As. dr. ing. Adrian SABOU
2017

FACULTY OF AUTOMATION AND COMPUTER SCIENCE
COMPUTER SCIENCE DEPARTMENT
DEAN, HEAD OF DEPARTMENT,
Prof. dr. eng. Liviu MICLEA Prof. dr. eng. Rodica POTOLEA
Graduate: Ioan-Ovidiu MAIER
WILSON: A CHATBOT SYMPTOM CHECKER
1.Project proposal: Chatbot with symptom checking capabilities
2.Project contents: Introduction – Project Context, Project Objectives and Specica-
tions, Bibliographic Research, Analysis and Theoretical Foundation, Detailed Design
and Implementation, Testing and Validation, User's manual, Conclusions, Bibliog-
raphy
3.Place of documentation: Technical University of Cluj-Napoca, Computer Science
Department
4.Date of issue of the proposal: October 25, 2016
5.Date of delivery: July 14, 2017
Graduate:
Supervisor:

FACULTY OF AUTOMATION AND COMPUTER SCIENCE
COMPUTER SCIENCE DEPARTMENT
Declara tie pe proprie r aspundere privind
autenticitatea lucr arii de licen t a
Subsemnatul(a)
, legiti-
mat( a) cu seria nr.
CNP , autorul lucr arii
elaborat a ^ n vederea sus tinerii examenului de nalizare a studiilor de licen t a la Facul-
tatea de Automatic a  si Calculatoare, Specializarea
din cadrul Universit a tii Tehnice din Cluj-Napoca, sesiunea a an-
ului universitar , declar pe proprie r aspundere, c a aceast a lucrare este
rezultatul propriei activit a ti intelectuale, pe baza cercet arilor mele  si pe baza informa tiilor
ob tinute din surse care au fost citate, ^ n textul lucr arii  si ^ n bibliograe.
Declar, c a aceast a lucrare nu con tine por tiuni plagiate, iar sursele bibliograce au
fost folosite cu respectarea legisla tiei rom^ ane  si a conven tiilor interna tionale privind drep-
turile de autor.
Declar, de asemenea, c a aceast a lucrare nu a mai fost prezentat a ^ n fa ta unei alte
comisii de examen de licen t a.
^In cazul constat arii ulterioare a unor declara tii false, voi suporta sanc tiunile admin-
istrative, respectiv, anularea examenului de licen t a .
Data Nume, Prenume
Semn atura

Contents
Chapter 1 Introduction – Project Context 1
1.1 Project context . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
Chapter 2 Project Objectives and Specications 3
Chapter 3 Bibliographic research 5
3.1 Healthcare . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
3.2 Chatbots . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
3.3 Human Computer Interaction . . . . . . . . . . . . . . . . . . . . . . . . . 7
3.4 Symptom Checkers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
3.5 Web Development Frameworks . . . . . . . . . . . . . . . . . . . . . . . . . 10
Chapter 4 Analysis and Theoretical Foundation 11
4.1 Symptom Checkers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
4.2 ApiMedic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
4.3 API.AI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
4.4 Human factors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
4.5 Project components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
4.5.1 Ruby on Rails . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
4.5.2 Flask Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Chapter 5 Detailed Design and Implementation 19
5.1 Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
5.1.1 Functional Requirements . . . . . . . . . . . . . . . . . . . . . . . . 19
5.1.2 Non-Functional Requirements . . . . . . . . . . . . . . . . . . . . . 20
5.2 Use case model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
5.2.1 Register . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
5.2.2 Login . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
5.2.3 Logout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
5.2.4 Diagnosing an issue . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
5.2.5 General Health Advice . . . . . . . . . . . . . . . . . . . . . . . . . 24
5.2.6 View diagnosis archive . . . . . . . . . . . . . . . . . . . . . . . . . 25
5

5.3 ER Diagram . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
5.4 Main functionality implementation . . . . . . . . . . . . . . . . . . . . . . 26
5.4.1 Register . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
5.4.2 Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
5.4.3 API.AI and ApiMedic integration . . . . . . . . . . . . . . . . . . . 27
5.4.4 User-Agent interaction . . . . . . . . . . . . . . . . . . . . . . . . . 30
5.4.5 Diagnosing an issue . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
5.4.6 Spellcheck . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
5.4.7 General health advice . . . . . . . . . . . . . . . . . . . . . . . . . . 42
5.4.8 Smalltalk . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
5.4.9 Training . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
5.4.10 Viewing past interactions . . . . . . . . . . . . . . . . . . . . . . . . 45
Chapter 6 Testing and Validation 47
6.1 Automated tests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
6.2 Synonym matching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
6.3 Spellcheck testing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
6.4 ApiMedic accuracy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
Chapter 7 User's manual 51
7.1 Installation description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
7.1.1 Deployment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
7.2 User manual . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
Chapter 8 Conclusions 55
8.1 Contributions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
8.2 Further developments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
Bibliography 57
6

Chapter 1
Introduction – Project Context
1.1 Project context
In many areas of the world medical personnel are in short supply. It is thus becoming
increasingly important to automate part of the medical process. The rapid advancement
in the eld of articial intelligence has allowed the emergence of various tools that could
be used to aid this automation. Virtual agents that perform routine tasks can free up time
for medical professionals and allow them to focus on more important problems. Virtual
agents (also known as chatbots) have a long history associated with their development
with the tools and techniques used in such systems evolving signicantly over time. In
recent years, chatbots have become commonplace, usually with narrow use cases. Their
broad application has been aided by the release of several tools and services that ease their
implementation. From this usage, conversational user interfaces have emerged, with their
own principles and best practices. Chatbots have had various degrees of acceptance from
users, with some success cases proving that it is possible to create a satisfying experience.
Users expect the agent to handle the narrow domain for which it was created, even if they
are not fooled into thinking that they are talking with a human.
As technology permeates more and more aspects of our daily lives, people have
increasingly begun to rely on the internet for information retrieval. It is not uncommon
for people to search for health related information online as well. Many companies oer
online symptom checkers with accuracy that has steadily increased over time. User trust
plays a key role for such systems. Patient engagement is also important, as studies have
shown that it is a primary factor in the ineectiveness of our current healthcare system.
As we develop articial agents we must take human factors into account, with special care
given to earning the trust and increasing the engagement of the people who use these
systems. Ensuring that people take their medication, develop healthy habits and regularly
consult medical professionals related to their issues have proven to be essential challenges
in the medical world.
The interface of health systems plays a very important part of the user experience
and cannot be ignored. Screens in which the user selects symptoms from dropdown menus
1

2
can feel too impersonal and cold (more so if the displayed diagnosis is serious). A challenge
in designing such systems is that by taking human interaction out of the process, patient
engagement and activation levels could drop, resulting in overall worse outcomes and costs.
This thesis describes the design and implementation of a chatbot that could be
used in the onboarding process at hospitals. The implementation will attempt to address
the issues described above by designing an agent that mimics a human personality, asks
for symptoms, provides possible issues and recommends the correct medical specialization
that the user should visit.

Chapter 2
Project Objectives and Specications
Our main objective is to facilitate the automation of part of the medical process
by using a virtual assistant that mimics human discourse, asks for symptoms, provides
possible issues and recommends the correct medical specialization. In addition to the
eciency benets that such a system could provide, the implementation of human-like
interactions has the potential to positively impact the activation levels and the engagement
of users. We aim to provide an alternative to existing healthcare software systems that
use online symptom checkers in the onboarding process of their patients. As the whole
landscape of medical diagnostics is too large we will restrict our area of interest to General
Health (problems for which people normally go to the family doctor). In order to achieve
this we need to complete the following secondary objectives:
Website creation – the platform on which the interactions will take place
Chat interface creation – implement a screen containing familiar chat elements that
will allow the user to enter input and the agent to respond
User input processing – we will integrate an external service in order to create the
agent, process the user input and obtain structured data from it
Structured data processing – the resulting structured data will be futher processed
on our server
Symptom and Diagnosis data integration – we will use another external service in
order to get this data and integrate it in our system
Symptom gathering – the system will allow the user to enter symptoms that she is
experiencing
Diagnosis – a possible diagnosis and a medical specialization that the user should
visit will be displayed
Allow the agent to mimic human discourse
3

4 CHAPTER 2. PROJECT OBJECTIVES AND SPECIFICATIONS
Provide general health advice
Spellcheck integration – suggest valid alternatives to the user in the event that she
misspells an otherwise correct input
The website will serve as the platform on which users will interact with the chatbot.
In order to provide a more personalized experience (such as recognizing the user and calling
her by her name), the users will be required to rst register and then to login using an
email and password.
The website will provide a chat interface where the interaction will take place. All
familiar chat elements will be present, with user and agent messages having dierent colors.
The user has likely encountered similar interfaces on other messaging platforms or social
media networks. The agent will greet the user when she arrives at this screen.
Our chat system will be integrated with an external service in order to create the
agent and perform natural language processing on the user input. This will allow us to
transform the user input into a more structured form that will be sent to our server for
further processing.
Symptom, diagnosis and medical specialization data will be available from an inte-
gration with another external service.
The agent will rst perform a symptom gathering phase, constructing a list of
symptoms that the user is experiencing over the course of several interactions. The agent
will ask the user about symptoms related to the ones already mentioned. The list of valid
inputs that the agent recognizes will be easily changed and expanded.
At the end of the symptom gathering phase, the agent will suggest possible causes
and provide a relevant medical specialization that the user should visit.
The agent will express itself in a friendly manner, will express interest and concern
for the wellbeing of the user. In addition, at each interaction step multiple possible re-
sponses will be available from which one will be chosen randomly by the system. This
ensures that subsequent conversations with the agent will have a high probability of being
dierent, further propagating the feeling that the user is interacting with a human.
In order to minimize the number of failed interactions we aim to allow the agent
to suggest valid inputs in the event that the user has misspelled an otherwise correct
input. The suggestions will also attempt to mimic a human conversation, with the agent
apologizing and oering alternatives.

Chapter 3
Bibliographic research
3.1 Healthcare
Greene et al. [1] reveal patient engagement as a major factor in the success of our
healthcare system. The study found that the Patient Activation Measure (an assessment
of patient engagement) was associated with better health outcomes and costs. The authors
conclude that eorts to increase patient activation may lead to better results.
A study by Bloss et al. [2] found no measurable dierences in health costs or benets
associated with the monitoring of health conditions with the help of smartphone-enabled
sensors. This further shows that digital systems in their current form cannot replace
healthcare professionals and cannot override the unhealthy habits of patients.
A possible way of increasing the engagement of users with a health application would
be to make it interactive. Conversational interfaces could prove to be a valid design choice
for this. Interactive computer programs that simulate a conversation are called chatbots.
3.2 Chatbots
The evolution of chatbots spans many decades, with the rst notable example being
ELIZA in 1966 (gure 3.1). In early examples of such symptoms, user prompts were
matched with scripted responses. This type of application is very time consuming to
develop. However, in recent years, techniques such as Natural Language Processing have
been used in the development of virtual agents.
Natural Language Processing deals with the comprehension of human languages
by computer programs. Initially this was done by hand-coding the rules of the interactions,
which proved to be inecient and time consuming. In the 1980s and 1990s more advanced
methods were developed, causing a \statistical revolution" in the eld [3].
Major companies that are involved in the technology sector have released tools and
API services that can aid the development of conversational agents. Some examples include
Google (API.AI [5]), Facebook (Wit.ai [6]), Microsoft (LUIS [7]), Amazon (Alexa [8]). We
5

6 CHAPTER 3. BIBLIOGRAPHIC RESEARCH
Figure 3.1: Chatbot progression [4]
will be using API.AI in our application to perform Natural Language Processing on the
user input. The service allows the creation of an agent and provides a JSON API that can
be used to obtain structured data from user input according to a set of rules and keywords.
Other medical chatbots have been created. The authors of the Sanative Chatbot
[9] have developed a system that provides answers to medical questions while attempting
to bridge the gap in vocabulary between the general public and healthcare professionals.
Pharmabot [10] is a "conversational chatbot designed to prescribe, suggest and give infor-
mation on generic medicines for children". Companies such as Babylon [11] have also de-
veloped medical-related chatbots (gure 3.2). Baidu has released Melody, an "AI-Powered
Conversational Bot for Doctors and Patients" [12].

3.3. HUMAN COMPUTER INTERACTION 7
Figure 3.2: Babylon Health Bot [11]
3.3 Human Computer Interaction
Human Computer Interaction is a research area that develops and studies the ways
in which people use and interface with computers. The term is attributed to Card et al.
[13]. Much of the eort in this eld goes towards the improvement in the usability of
computer systems. Interfaces that do not meet usability standards can cause a project to
fail even if the underlying functionality is correct. As we aim to increase the engagement
of patients, we must take human factors into account when designing our system. Some
principles are highlighted below:
Kirakowski et al. [14] describe the properties needed for a chatbot system in order
to provide a convincing dialog with a human interlocutor. They were used as a basis for
the characteristics of our agent:

8 CHAPTER 3. BIBLIOGRAPHIC RESEARCH
greeting the user is perceived by many as being a human-like characteristic
maintaining a theme of discussion once it is started
apologizing and redirecting the conversation if an input was not matched
having an answer to questions usually regarded as smalltalk
colloquial english style has been found to be most convincing
having a name – this allows people to assign agency to the chatbot
Ensuring that the chatbot has anthropomorphic traits is another way of increasing
user engagement [15]. Curiosity, friendliness and a sense of humor are examples of such
traits.
3.4 Symptom Checkers
Online symptom checkers that cover General Health issues are made available by
companies such as WebMD (gure 3.3).
Priad oers ApiMedic [16], a symptom checker API that returns a list of possible
issues and a suggestion for the medical specialization most suitable for a list of given
symptoms. This service is used at Istanbul University Hospitals and it "helps patients to
book an appointment with the correct specialist." [16]
Figure 3.3: WebMD Symptom Checker [17]

3.4. SYMPTOM CHECKERS 9
The reasoning behind this integration is given by Istanbul University Hospitals as
follows: "We are expecting to make a step forward towards improving the allocation of
patients to the correct doctor. Current information technologies oer a big chance to
capture the patient on the internet where he is looking for medical information and to
steer him to the correct channels."[18]. This shows that there is a need for such systems in
healtchare. The emphasis is placed on the correct matching of the symptoms described by
the user and the medical specialization, and not on the diagnosis of issues. The symptoms
covered are those belonging to General Health, so this type of application could serve as a
family doctor or a nurse. We will integrate the ApiMedic API in our application in order
to access symptom, diagnosis and medical specialization data.
The interfaces of the WebMD Symptom Checker (gure 3.3) and the Istanbul Uni-
versity Hospitals Symptom Checker (gure 3.4) are similar, with both systems allowing
the user to select from lists of symptoms using a mouse and then displaying possible is-
sues. We intend to present an enhancement of such interfaces in the onboarding process
for patients by oering a chat-based solution.
Figure 3.4: Istanbul University Hospital Symptom Checker [19]

10 CHAPTER 3. BIBLIOGRAPHIC RESEARCH
3.5 Web Development Frameworks
Ruby on Rails [20] is a web-application framework written in the Ruby program-
ming language. It is used to develop the web platform and chat interface of our application.
The framework follows a model-view-controller pattern and includes default congurations
for many usual web services, reducing the need for boilerplate code. Rails is an opinion-
ated framework that promotes several principles such as the Convention over Conguration
(CoC) and Don't Repeat Yourself (DRY) principles.
The Convention over Conguration principle aims to include sensible defaults in the
framework itself, leaving it up to the programmer to specify only unique aspects of the
application.
The DRY principle emphasizes the fact that information should be located in only
one place. The purpose is to reduce ambiguities and to lead to more readable and main-
tainable code.
The framework makes use of libraries (called\gems") that aid in the implementation
of common web functionalities.
The above conventions make Ruby on Rails a good choice for the development of
client-facing side of our application. The framework permits the use of libraries imple-
mented using best practices for common functions (such as authentication) and allows us
to focus on aspects of our implementation that are unique (agent interactions).
Flask [21] is a micro web framework written in Python. It is used for processing
the structured data derived from the user input in our application. Flask was chosen
because it has a small footprint, easy conguration and integration with libraries relevant
to the project. Such a library is
ask-assistant [22], a
ask extension that integrates
with API.AI for building virtual assistants.

Chapter 4
Analysis and Theoretical Foundation
4.1 Symptom Checkers
Although ApiMedic is a proprietary software product, the internal implementation
likely follows a similar approach to other symptom checkers that have been published
in academia, specically ones that use neural networks in order to provide the medical
diagnosis [23].
A neural network consists of multiple interconnected units that are called neurons.
The connections between the neurons can transmit signals that have an associated strength.
Figure 4.1: Neural network
The strength of the signals varies with the strength of the connection. Articial
neural networks were inspired by their biological counterparts that make up the brains of
animals and humans. Neural networks are organized in layers, each executing a particular
transformation on the input. (gure 4.1)
11

12 CHAPTER 4. ANALYSIS AND THEORETICAL FOUNDATION
4.2 ApiMedic
ApiMedic provides symptom, dignosis and medical specialization information for
issues contained in the General Health domain. The service uses a JSON format, and
provides the following endpoints:
GET /symptoms – returns the list of all symptoms provided by the service (gure
4.2)
GET /issues – returns the list of all issues (diagnoses) provided by the service
GET /issues/id/info – returns more information about an issue specied by id, in-
cluding possible treatments and a more elaborate description (gure 4.3)
GET /symptoms/proposed – takes as parameters a list of comma separated ids of
symptoms, returning other related symptoms
GET /diagnosis – also takes as parameters a list of comma separated ids of symptoms,
returning the most likely issue associated with the symptoms
GET /specializations – also takes as parameters a list of comma separated ids of
symptoms, for which it returns the most adequate medical specialization
GET /body/locations – returns a list of body locations
GET /body/locations/id – returns a list of body sublocation given a body location
id
GET /symptoms/id/man – returns a list of symptoms associated with a body sublo-
cation (specied by id); the information includes synonyms of the symptoms
4.3 API.AI
API.AI provides a service that transforms user input into structured and action-
able data. This process is called Natural Language Understanding. A Natural Language
Understanding module is called an agent . An agent contains the main concepts of the
process which are entities, intents, contexts, parameters and actions [5].
Entities are concepts that will be recognized by the agent (in our case they are
names of symptoms from ApiMedic). They act as a list of keywords that will be extracted
from the input.
Intents are the connections between the input and the actions that our system
will perform. An action represents an outcome that will result from the input (such as
a text response that will be sent back to the user or data processing that is done in the

4.3. API.AI 13
Figure 4.2: ApiMedic Symptoms [16]
background). Actions can also have associated parameters that act as input variables to
the function that the action executes. In our case the parameters extracted are the names
of the symptoms. Actions can be dened in the API.AI console or they can send the data
further, to our server via a webhook. There we can form the appropriate response by using
data from our database or from external services.
Contexts serve to dierentiate between interactions and ambiguous input. (For
example, if the user enters "yes" we look to the context to see to what question the user is
replying to). Contexts have a "lifetime", represented by a number, showing the number of
interactions for which the context is active. Contexts can be activated or deactivated in
each intent. An intent can have two types of contexts:
Input contexts: serve as a way of constraining the matching of intents. If an intent has
an input-context dened, it won't be matched unless the input-context is activated.
Output contexts: are activated by the action of an intent.
The two types of contexts can be used to direct the conversation
ow. The user
input is sent as natural language in the form of a query. API.AI matches the query with
one of the dened intents of the system, based on the detected entities, parameters
and contexts . The corresponding action of the matched intent is then triggered.
The main endpoint used in the integration is the /query endpoint. The parameters
contain the user input that is sent for processing.
Agents are platform independent, and once created, can be integrated in a variety
of mediums, such as Facebook Messenger, Kik, Slack, Telegram and Viber.
Fulllment : by using a webhook mechanism, the data from an intent is passed to
a web service where it is processed, and an appropriate response is returned. We will use
this mechanic in our application in order to return responses to the user (gure 4.5).

14 CHAPTER 4. ANALYSIS AND THEORETICAL FOUNDATION
Figure 4.3: ApiMedic issue information [16]
Response: the agent has several types of available responses. They can be dier-
entiated by the "type" parameter in the JSON response:
Text Response (type 0) – simple text
Card (type 1) – a rich response that contains a clickable link (for example to an
external article), and an image. We will use this type of response to provide articles
with health advice for the user
QuickReply (type 2) – buttons containing text that the user can click. We will use
this type of response when we want to direct the user into choosing from a number
of possible conversation branches.
Machine Learning and Training: the agent "learns" to extract structured data
from the user input by using the dened intents and entities in language models imple-
mented by API.AI. The agent will improve based on past conversations when the "Training"
feature is used. This feature allows us to review conversation logs to check what intents
were matched or unmatched. For an unmatched input, we can decide if we already have
a suitable intent dened and match it at this time, or create new intents and entities.
Unmatched inputs that are handled this way will not go unmatched in future interactions.
4.4 Human factors
We aim to take into account human factors as much as possible when designing our
agent. The properties required to create a convincing chatbot are [14]:

4.4. HUMAN FACTORS 15
Figure 4.4: API.AI diagram [5]
greeting the user – the name of the user will be available in the database, so the bot
will be able to greet the user by using his name through the "fulllment" mechanism.
A session id will be mantained throughout the interactions, so that the bot never
loses track of who he is talking to.
maintaining a theme of discussion – this is done by creating dierent "contexts"
that are activated and maintained for a number of exchanges. Contexts can be
activated/deactivated either in the API.AI console, or in the web service when using
a webhook to create the response. In addition to the session id that uniquely identies
a user, each user interaction is also tracked (using an interaction id). An interaction
starts when the user indicates that he wants to diagnose an issue and it ends when a
diagnosis is displayed. The symptoms and the nal diagnosis of the interactions are
saved to the database.
apologizing and redirecting the conversation if an input was not matched – in the
event that an input was not matched, we will rst attempt to spellcheck the input
and oer suggestions. If no suggestions are found then the agent will apologize and
ask the user to enter a dierent input
having an answer to questions usually regarded as smalltalk – API.AI oers a "smalltalk"
module that can be integrated in the chatbot, containing responses to usual ques-
tions like "How are you?", "How are you feeling?". The responses to these questions
can be congured in the API.AI console.
the use of colloquial english – the responses can be dened either in the API.AI
console or in the web service when using a webhook

16 CHAPTER 4. ANALYSIS AND THEORETICAL FOUNDATION
Figure 4.5: Data
ow
assigning a name to the bot – the bot will refer to himself by this name when talking
to the user
4.5 Project components
Although it is possible to integrate the bot in platforms such as Facebook Messenger,
we have opted to create our own platform for the project. However, in order to keep the
frontend side of the application as decoupled as possible from the backend web service,
the decision to separate the two parts of the application has been made. By minimizing
the dependencies between these components, we ensure that future integrations of the bot
in other platforms require less work and minimal changes to the existing codebase. The
result is the following structure, shown in gure 4.6:
a Ruby on Rails application – allows the user to create an account and login, contains
the chat interface of the application
a Flask service that handles webhook calls from API.AI (the fulllment mechanism),

4.5. PROJECT COMPONENTS 17
handles data processing and calls to ApiMedic and returns an appropriate response
a PostgreSQL database that stores user information and a record of the interactions
with the agent
Figure 4.6: Block diagram
4.5.1 Ruby on Rails
The Ruby on Rails web framework contains several default congurations that help
the development of standard applications. The functionality is aided by the use of libraries,
called "gems", several of which come preinstalled when a new project is created. For
example the "devise" gem can be used for the authentication of users.
The framework conventions include the use of Active Record as the Object Rela-
tional Mapping pattern [24] which is included in the "activerecord" gem. In this type of
Object Relational Mapping a model class is tied to a table in the database, an object
instance is tied to a row in that table, and object attributes correspond to the columns
in the database row. Data access logic and domain logic are held in the same object.
Although it suers from a number of shortcomings, such as violations of the single respon-
sability principle and the separation of concerns, the pattern is widely used in industry,
particularly in projects of small to medium complexity. Because we include our project
in this category we have decided the pattern (and therefore the framework) is suitable for
our use case. Active Record acts as the model in the model-view-controller pattern [24].
The main screen of our application consists in a chat interface that will allow the
user to interact with our agent. The DOM elements are manipulated using the jQuery
javascript library.

18 CHAPTER 4. ANALYSIS AND THEORETICAL FOUNDATION
4.5.2 Flask Server
In order to perform the "Fulllment" (gure 4.4) section in the API.AI integration
we will implement a Flask Web Server to handle the data sent from API.AI webhooks and
to form a response.
Flask-assistant is a
ask extension that integrates with API.AI. Webhooks are trig-
gered after an intent has been matched, so it necessary to match incoming requests with
the correct intent. This is done by using an action decorator on our server for each in-
tent that has a webhook trigger (here the term "decorator" refers to the Python language
construct that serves as a macro and not to the design pattern).
Information about the user and the agent interactions will be retrieved and up-
dated through a database connections. Flask has a number of available Object Relational
Mapping libraries. We will use the SQLAlchemy ORM.
ApiMedic oers a Python Software development kit that will be used in our Flask
server.
In order to return responses in an appropriate timeframe and meet the timeout
constraints of the various external services used in our application, some processing needs
to be done in the background. The celery [25] task queue is used for this purpose. The
components for this subsystem are (gure 4.7):
The client – our Flask server
The Celery workers – processes that run the background jobs
The message broker – The Flask server communicates with the workers using a mes-
sage broker. We will use a Redis [26] instance for this purpose
Figure 4.7: Background processing

Chapter 5
Detailed Design and Implementation
5.1 Requirements
This section describes the requirements of the application, both functional and and
non-functional. The FURPS+classication given by Grady Booch is used.
5.1.1 Functional Requirements
Authentication: the system will allow the user to create an account and login to the
application. This will enable the agent to use personal information, such as the user's name
in conversation, enhancing the antropomorphic qualities of the bot. The user interactions
will be stored in the database, and will be available for viewing at a later time.
Providing a diagnosis: once the user indicates that he wants to diagnose an issue, the
agent will prompt the user to describe his symptoms and ask about related symptoms.
When the symptom gathering phase has ended or when the user indicates that he wants
to see the diagnosis, a possible cause for the symptoms will be presented, along with a
description and a medical specialization that the user should visit.
Spellcheck: if the user input is not matched, the system will rst attempt to provide an
alternative using a predened dictionary. If an alternative is found it will be presented to
the user, who then has the possibility to accept or deny it (or to provide a new symptom).
This functionality attempts to minimize the number of failed interactions of the system,
while also increasing the credibility of the agent.
View diagnosis interaction archive: the system will allow the user to view past
diagnosis-related interactions. Information about the introduced symptoms, diagnosis and
medical specialization will be shown.
19

20 CHAPTER 5. DETAILED DESIGN AND IMPLEMENTATION
General health advice: the agent will provide general health advice, in the form of
text responses or external links to articles. The user will be able to select from exercise,
diet and sleep advice.
Smalltalk: the agent will have an answer for common questions and topics, in order to
appear more "human" to the user.
5.1.2 Non-Functional Requirements
Usability: the interface of the system will be intuitive for the average person, having
familiar placement and functionality for the main web application elements, such as reg-
ister, login, logout. The chat interface in which the user interacts with the agent will also
be familiar and intuitive. As the chat will function in a similar way to other chat systems
that the user has likely used, no special training or instruction will be required. It will be
obvious to the user of the application how he should enter the messages to the agent.
Reliability: as the system uses external services for certain functionalities, the possibility
of network failures will be taken into account, with appropriate messages displayed to the
user in such events. The agent will maintain the context of the conversation, so in the
event that a network error has occured, the conversation will continue.
Performance: the response time of the agent will be under 3 seconds. When long
requests that perform database queries or make calls to external services are performed, a
"Processing" message will be displayed, in order to provide visual feedback to the user.
Supportability: the web platform will be available on all main browsers, such as Google
Chrome, Mozilla Firefox, Opera and Microsoft Edge. In terms of extensibility, new func-
tions and interactions can be added to the agent without modifying the current implemen-
tation.
5.2 Use case model
The main use cases of the application can be seen in gure 5.1
Stakeholders:
User – wants to receive health advice and medical diagnoses for symptoms that she
is experiencing – is the Primary actor in most use cases
Our application – wants to satisfy the user needs and to record important interactions
for future improvement. Fault tolerance is desired for user spelling mistakes and
network errors

5.2. USE CASE MODEL 21
Figure 5.1: Application use cases
API.AI – Natural Language Processing Tool – web service receives user input and
returns structured data. Is a Supporting actor
ApiMedic – Medical web service that returns related symptoms, diagnosis and a
recommended medical specializations for a list of given symptoms. Is a Supporting
actor
5.2.1 Register
The users of the application need to be authenticated in order to use the agent.
First they need to create an account by providing basic information.
Main success scenario:
Use-Case start: User selects "Register" on the homepage of the application
1. User provides email, rst name, last name, password, and password conrmation
2. A new account is created in the database
3. The system redirects the user to the main screen of the application
Alternate
ows:
1a. Email is not unique
1. System displays error message

22 CHAPTER 5. DETAILED DESIGN AND IMPLEMENTATION
1b. Email doesn't respect email format
1. System displays error message
1c. Password and password conrmation elds do not match
1. System displays error message
5.2.2 Login
Main success scenario:
Use-Case start: User selects "Login" on the homepage of the application
1. System redirects user to the Login page
2. User provides email and password
3. The provided information is searched in the database, a new session is created
4. The user is directed to the main screen of the application
Alternate
ows:
2a. User with provided email does not exist
1. System displays error message
2b. Email and password do not match
1. System displays error message
5.2.3 Logout
Main success scenario:
Use-Case start: user is logged in the application, in the main chat screen
1. User selects "Logout"
2. System ends the session and the user is redirected to the homepage of the
application
5.2.4 Diagnosing an issue
The
ow of the interaction can be seen in gure 5.2
Main success scenario:
Use-Case Start: User logs in and chooses to diagnose an issue.
1. System starts a new interaction, asks for the rst symptom
2. User enters rst symptom
3. System sends user input to external Natural Language Processing service where
symptom is identied
4. The system receives the identied symptom, makes a request to external Medical
service and receives related symptoms
5. System asks the user if a related symptom is experienced
6. User indicates experiencing the related symptom
7. System registers the experienced symptom, recomputes related symptom list and
displays it as natural language

5.2. USE CASE MODEL 23
Figure 5.2: Diagnose an issue Use Case
8. Steps 5-7 are repeated until user indicates no more symptoms, or related symp-
toms list is exhausted.
9. System makes a request containing all symptoms to external Medical service,
receives diagnosis and a relevant medical specialization which are then displayed to the
user
10. System registers diagnosis and medical specialization information, ends inter-
action
Alternate
ows:
*a. At any time, a network error occurs
1. System displays an error message
2. System maintains conversation context prior to network error

24 CHAPTER 5. DETAILED DESIGN AND IMPLEMENTATION
3. User is asked to re-enter input
3a. Symptom is not identied
1. System attempts to "spellcheck" user input, alternative is found
2. Alternative is displayed to the user
3. User accepts alternate input
1a. Alternative not found, user is asked to rephrase
3a. User does not accept alternate input, user is asked to rephrase
6a. User ignores related symptom, enters new symptom
1. System identies symptom and recomputes related symptom list
9a. No diagnosis is received for combination of symptoms
1. System displays message encouraging user to restart the process
5.2.5 General Health Advice
Diet advice main succcess scenario
Use-Case Start: User logs in and chooses to receive general health advice
1. System asks for advice area (diet, exercise, sleep)
2. User enters diet
3. System asks for diet type (vegan, vegetarian, balanced)
4. System presents diet article
Alternate
ows:
*a. At any time, a network error occurs
1. System displays an error message
2. System maintains conversation context prior to network error
3. User is asked to re-enter input
2a. User enters unkown input
1. User is asked to rephrase
3a. User enters unkown input
1. User is asked to rephrase
Exercise advice main success scenario:
Use-Case Start: User logs in and chooses to receive general health advice
1. System asks for advice area (diet, exercise, sleep)
2. User enters exercise
3. System asks for exercise goal (losing weight, building muscle)
4. System presents exercise article
Sleep advice main success scenario:
Use-Case Start: User logs in and chooses to receive general health advice
1. System asks for advice area (diet, exercise, sleep)
2. User enters sleep
3. System asks user to input number of hours of sleep she gets per night
4. System presents sleep advice or article

5.3. ER DIAGRAM 25
5.2.6 View diagnosis archive
Main Success Scenario:
Use-Case Start: User is logged in and selects "Interactions" in the main page
1. System displays a list of past user diagnosis interactions
2. User selects an interaction
3. System display interaction information: date, symptoms and diagnosis
5.3 ER Diagram
The User entity contains personal user information, such as rst name, last name,
email and the encrypted password. The id of the user will be passed as the "session id" in
the API.AI integration. This is used by API.AI when returning a response.
The symptoms that are recognized by the agent will be congured in API.AI, but
we will also store them in our database. This is done because all diagnosis-related user
interactions will be saved for further viewing in our database, and we want the information
to be as comprehensive as possible.
In our implementation a user interaction begins in the moment that the user in-
dicates that she wants to diagnose an issue and ends when the diagnosis is given. The
user and interaction entities are in a one-to-many relationship, as a user can have many
interactions. The Interactions table contains:
an identier that has as value the timestamp from when the interaction was created.
The interaction identier is also passed as a parameter in the calls to API.AI. It
is further transmitted to our Flask webhook handler where it used to identify the
current interaction.
current symptom id – when the agent asks the user whether she is experiencing a
symptom, the id of the symptom is saved
when the user answers, a new entry is created in the Interaction Symptoms table,
which acts as a join table between the two entities. The "the experienced"
ag is set
to either TRUE or FALSE, depending on the user response
related symptom text – the current text response of the agent, containing the name
of the current symptom
suggestion – the text response of the agent containing a suggestion for the user in
case she has misspelled an otherwise valid input
diagnosis – the text response of the agent containing the diagnosis, description and
medical specialization that the user should visit

26 CHAPTER 5. DETAILED DESIGN AND IMPLEMENTATION
Figure 5.3: Entity Relationship Diagram
5.4 Main functionality implementation
5.4.1 Register
The "devise" gem is used for registration. This involves:
adding the 'devise' gem in the Gemle.lock le
running the 'bundle install' command
adding 'devise for :users' in the routes.rb route le of the application
creating the RegistrationController
dening the create function in the registrations controller
# Create new user
def create
build_resource

5.4. MAIN FUNCTIONALITY IMPLEMENTATION 27
redirect_to chat_path
end
5.4.2 Authentication
Authentication is also handled by the 'devise' gem, in the SessionsController. A
new session is created, encrypted and stored in the browser cookies. When the user logs
out the session cookie is destroyed.
5.4.3 API.AI and ApiMedic integration
ApiMedic is a Symptom Checker API provided by Priaid that oers the following
functionalities:
retrieving body locations and sublocations
retrieving a list of symptom names and their synonyms for a body sublocation
given a list of symptoms,retrieving a list of possibly related symptoms
given a list of symptoms, retrieving a list of possible causes, along with related
information and the recommended medical specialty
ApiMedic uses to JSON format in order to transmit and receive data. For example,
the GET /symptoms/0/man endpoint returns all symptoms (with synonyms) for the body
sublocation with id 0:
[
{
"ID": 10,
"Name": "Abdominal pain",
"HasRedFlag": false,
"HealthSymptomLocationIDs": [
16,
36
],
"ProfName": "",
"Synonyms": [
" Stomach ache"
]
},
…

28 CHAPTER 5. DETAILED DESIGN AND IMPLEMENTATION
Because we want to introduce all symptoms in the application, we rst traverse all
body locations, then all body sublocations, writing the results in the symptoms andsynonyms.json
le.
In order to process the input introduced by the user in our application, we rst need
to create an API.AI Agent. We do this by rst logging in the API.AI platform, creating a
new agent, and giving it a new name (in our case "Wilson").
The Agent used in API.AI also has a JSON representation, one which contains the
intents, entities and contexts of the Agent.
Thesymptoms provided by ApiMedic will be the entity that our Agent needs to
recognize. So the next steps in the development of our application will involve:
converting the JSON structure containing the symptoms provided by ApiMedic into
the JSON structure accepted by API.AI
creating an Agent containing this structure
The API.AI entity JSON structure expects the following format:
{"name":"symptom",
"isOverridable":true,
"isEnum":false,
"automatedExpansion":false,
"entries":
[{"value":"Abdominal pain",
"synonyms":[" Stomach ache","Abdominal pain"]},
{"value":"Heartburn",
"synonyms":["Pyrosis","Heartburn"]}
…
The above JSON shows the content of the entities.json le which can be imported
in API.AI. This would create an agent that recognizes the "symptom" entity. Multiple
entries are given for this entity (in the snippet shown above they are Abdominal pain and
Heartburn). The "synonyms" component contains aliases of the symptom that will also be
recognized by the Agent.
In order to create the desired JSON structure we use a Ruby script:
require 'json'
file = File.read('simptoms_and_synonyms.json')
data = JSON.parse(file)

5.4. MAIN FUNCTIONALITY IMPLEMENTATION 29
hash = Hash.new
hash['name'] = "symptom"
hash['isOverridable'] = true
hash['isEnum'] = false
hash['automatedExpansion'] = false
entries = []
elements = []
count = 0
data.each do |d|
unless elements.include? d['Name']
elements << d['Name']
entry = Hash.new
entry['value'] = d['Name']
entry['synonyms'] = d['Synonyms']
entry['synonyms'] << d['Name']
entries << entry
count += 1
end
end
puts count
hash['entries'] = entries
File.open("symptom.json","w") do |f|
f.write(hash.to_json)
end
The script above prints "260", meaning we have 260 dierent symptoms that the
system will recognize, along with their synonyms.
The next step involves uploading the JSON structure in the API.AI platform. We
do this by using the "IMPORT FROM ZIP" function. The resulting entity list is visible in
the platform. (gure 5.4)
In addition to the synonyms provided by ApiMedic we have extended the list of
synonyms for certain symptoms. For example, the "Anxiety" symptom: anxious, agitated,
worried, concerned, fearful, nervous, tense, edgy, uneasy, jittery, angst, unease, uneasiness,
distress, distressed, alarmed, troubled, anguish, panicked, panic. (21 in total). The list
of symptoms and synonyms can be augmented at any time and provides a clear path for
future developments.

30 CHAPTER 5. DETAILED DESIGN AND IMPLEMENTATION
Figure 5.4: Symptom list in API.AI
5.4.4 User-Agent interaction
One of our goals was to provide the bot with anthropomorphic traits: giving the
bot a name, ensuring that the bot greets the user, ensuring that the bot maintains a theme
during conversation. API.AI allows the introduction of multiple possible responses from
which one will be chosen at random. This ensures that new conversations are less likely
to feel similar to previous ones. The following variants were introduced for the greeting:
"Hi there, I am Wilson, your AI medical assistant. What would you like to do?"
"Hello! I am Wilson. I am here to help you live a healthier life. Click on one of the
following options when you are ready."
"Hey! I'm here to diagnose issues you might be experiencing or provide health advice.
My name is Wilson by the way 🙂 We can begin when you're ready."
"Hey, good to see you! I am Wilson. We can begin checking your symptoms when
you're ready. Or we can talk about general health advice. "
User Input
The chat functionality of the application is realized by manipulating the DOM
elements using the jQuery javascript library. The locations for this code follows Rails
conventions, and is in:
app/assets/javascripts/chat.js

5.4. MAIN FUNCTIONALITY IMPLEMENTATION 31
When the user visits the chat page he is greeted by the bot. The bottom of the
screen contains a text box in which the user can write a reply. When the user presses the
"ENTER" key, the message is displayed on the screen and a call containing the user input
is made to API.AI:
$('.user_message').keyup(function(e) {
if (e.which === 13) {
var $user_message;
$user_message = $('.user_message');
displayMessage($user_message.val(), "user");
makeAIcall($user_message.val());
$(".user_message").val('');
}
function displayMessage(text, author) {
message = new Message({
text: text,
author: author
});
message.display();
};
Thedisplay method of the Message javascript object:
clones a "msg template" element
adds the text to the html element
adds the "author" css class to the element – this class can be either "user" or "agent"
and is responsible for the dierence in appearence between the user and agent mes-
sages
appends the message in the message area using a sliding animation
The integration with API.AI is done through an AJAX request (where the user
input is sent for processing:
function makeAIcall(text) {
var url = "https://api.api.ai/v1/";
var id = $("#id").html();
var interaction_id = $("#interaction_id").html();

32 CHAPTER 5. DETAILED DESIGN AND IMPLEMENTATION
if(interaction_id === '') {
interaction_id = new Date().toLocaleString();
}
$.ajax({
type: "POST",
url: url + "query?v=20160415",
contentType: "application/json; charset=utf-8",
dataType: "json",
headers: {
"Authorization": "Bearer " + accessToken
},
data: JSON.stringify({query: text, lang: "en", sessionId: id}),
success: function(data) {
showAgentResponse(data);
},
error: function() {
showAgentResponse("I'm sorry, I didn't get that. Could you please repeat?");
}
});
}
We maintain two "session ids":
the session id – is required by API.AI in order to return the response to the correct
user
the interaction id – is required by our Flask Server in order to correctly identify
the interaction of a user and to construct the list of symptoms and the diagnosis
associated with the interaction
The session id is represented by the user id, and is inserted in the html document:
<div id="id" style="display: none;"><%=current_user.id%></div>
The interaction id is also an html element. If the interaction id is empty, it means
that this is the start of the interaction, and a new interaction id is created.
The Agent Response is given in JSON form by API.AI:
async function showAgentResponse(val) {
var msgs = val.result.fulfillment.messages;
The agent response could contain an ordinary text message or quickreplies that the
user can click. This is determined by traversing the agent responses and checking the
"type" parameter (which is '0' for text and '2' for quickreplies). The responses are then
displayed on the screen.

5.4. MAIN FUNCTIONALITY IMPLEMENTATION 33
Text responses are shown by calling the displayMessage method supplying as pa-
rameters the agent text response, and the agent as the author of the message
Quickreplies are shown by calling the showButtons method, which takes as param-
eters an array containing the text values of the replies. The replies are displayed in
a similar fashion to the messages – new Button objects that have a display method
are created, and a "reply button template" html element is appended in the DOM.
Quickreplies are clickable buttons, so we add event listeners on them to capture
their input:
buttons[i].addEventListener('click', function(e) {
var input = this.innerHTML;
makeAIcall(input);
displayMessage(input, "user");
$('.quickreply').hide();
});
5.4.5 Diagnosing an issue
Phase 1: symptom gathering
If the user clicks on the "Diagnose an issue"quickreply the start-interaction intent
is matched in API.AI. This intent is congured to send the user id and interaction id to our
Flask server through a webhook. This is where the start-interaction intent is matched
to an action:
@assist.action('start-interaction')
def start_interaction():
user_id = request.json['sessionId']
interaction_id = request.json['originalRequest']['data']['interactionId']
new_interaction = Interaction(user_id=user_id, identifier=interaction_id,
created_at=datetime.datetime.now(), updated_at=datetime.datetime.now())
db.session.add(new_interaction)
db.session.commit()
A new interaction is saved to the database, and a response that asks the user what
symptoms she is experiencing is send back to API.AI. This response is then displayed to
the user. An example of a valid user input at this step would be: "I have anxiety" (gure
5.5). The input is sent to API.AI for processing. If the input contains a symptom that is

34 CHAPTER 5. DETAILED DESIGN AND IMPLEMENTATION
Figure 5.5: Gathering related symptoms
contained in the system (or a synonym of a symptom) then the "identify symptom" intent
is matched and the symptom entity (in our case "anxiety") is extracted as a parameter.
The data is again sent through a webhook to our server.
@assist.action('identify-symptom')
def identify_symptom(symptom):
interaction_identifier = request.json['originalRequest']['data']['interactionId']
related_symptoms.delay(interaction_identifier, symptom, True)
speech = "Processing.."
result_dictionary = {
"contextOut": [{"name": 'ongoing-interaction', 'lifespan': 2}],
"speech": speech,
"messages": [
{
"type": 0,
"speech": speech
},
]
}
result = json.dumps(result_dictionary, indent=4)

5.4. MAIN FUNCTIONALITY IMPLEMENTATION 35
return make_response(result)
The "Processing.." message is returned to API.AI. It is then sent further to the chat
interface where it is displayed to the user. The ongoing-interaction context is set. The
related symptoms celery background task will run in the background.
@celery.task(name="tasks.related_symptoms")
def related_symptoms(interaction_identifier, symptom, experiencing):
The background task does the following:
queries the database to nd the current interaction
creates a new entry in the interaction symptoms table, setting the "experienced"
column to TRUE
creates an array containing the ids of all symptoms associated with this interaction
that have the "experienced" column set to TRUE (this being the rst symptom, the
array will contain only one id)
makes a call to ApiMedic on the GET symptoms/proposed endpoint passing the
array as a parameter:
related_symptoms = diagnosisClient.loadProposedSymptoms(array)
traverses the list of related symptoms, nds the rst one that is not already associated
with the interaction; this is the current symptom of the interaction
a text response is chosen randomly from several possible variants, appended to the
current symptom and saved in the related symptom text column of the inter-
action:
responses = []
responses.append("Ok then…writing this down. Are you also experiencing ")
responses.append("Ok. Please indicate if you are also experiencing ")
responses.append("Interesting. How about ")
responses.append("I see. Would you say you are also experiencing ")
responses.append("Hmmm..ok then. Tell me, what else are you feeling? Perhaps ")
nr = randint(0,4)
text_response = responses[nr]
text_response += current_symptom.name.lower() + " ?"
interaction.related_symptom = text_response

36 CHAPTER 5. DETAILED DESIGN AND IMPLEMENTATION
Figure 5.6: Sequence Diagram showing "Related Symptoms" phase
Upon receiving the "Processing" message, the Ruby on Rails application displays
it to the user and also makes a "get related symptoms" request to API.AI, while also
supplying the current interaction id. (gure 5.6)
API.AI contains a get-related-symptoms intent that also sends this request to
a webhook handler on the Flask server. Here the current Interaction is retrieved from
the database, with the related symptom already lled in by the background process. The
related symptom is then sent to API.AI, which sends it to the chat interface where it is
shown to the user. An example: "Are you also experiencing a reduced appetite?". The
action sets the categorize-symptom context. The user can respond armatively or
negatively, or indicate a new symptom, with each response being sent to the Flask server,
where the symptom list of the current interaction is maintained according to user input:

5.4. MAIN FUNCTIONALITY IMPLEMENTATION 37
if the user responds armatively the experience-symptom-yes intent is matched,
which has a corresponding action on our server that will trigger the related symptoms
background process, where the current symptom will be saved with the "experienced"

ag set to true, and a new call will be made to ApiMedic, returning another possible
symptom
if the user responds negatively the experience-symptom-no intent is matched,
and the "experienced"
ag of the current symptom will be set to FALSE
if the user mentions another symptom in his response (for example saying "No, but
I have a headache") the identify-symptom intent will be matched
Phase 2: Diagnosis
A diagnosis is returned in the following cases:
the user has clicked on the "No, these are all my symptoms" quickreply – this will
trigger the get-diagnosis intent
all the related symptoms returned by ApiMedic are already associated with the
current interaction, in which case the "related symptom" column of the interaction
will be set to "Finished symptoms". This is an internal convention that will cause
the system to trigger the get-diagnosis intent on the next request
Information about the possible cause is displayed to the user, as well as an appro-
priate medical specialist that he should consult (gure 5.7).
The functionality is similar to the symptom gathering phase(gure 5.8) The get-
diagnosis intent will return a "Processing diagnosis" response and trigger the save-
diagnosis background task. The task will:
query the database to retrieve the current interaction using the interaction identier
construct an array of all the symptoms related to the interaction that have the
"experienced"
ag set to TRUE
make a call to the GET /diagnosis endpoint of ApiMedic:
apimedic_response = diagnosisClient.loadDiagnosis(array)
if a diagnosis and a medical specialization were returned for this combination of
symptoms – they are saved in the "diagnosis" column of the interaction
if no response is returned the "diagnosis" column is saved with an apology message
and the option for the user to try again

38 CHAPTER 5. DETAILED DESIGN AND IMPLEMENTATION
Figure 5.7: Wilson showing diagnosis
When receiving the "Processing diagnosis" message the system convention is for
the chat application to trigger the nal-diagnosis intent. The corresponding action will
identify the interaction by the interaction identier and then return the text response
found in the "diagnosis" column of the interaction. At this point the "interaction id" html
element is set to the empty string, meaning that the current interaction has concluded,
and a new one will be created if the user chooses to diagnose a new issue.
5.4.6 Spellcheck
If a user has misspelled an otherwise valid input, an appropriate suggestion will
be provided by the agent. The system checks unmatched inputs against a dictionary of
valid symptoms and synonyms. For example, if the user entered the incorrectly spelled
word "anxieti" he will be prompted with "anxiety" (gure 5.9). ApiMedic provides a list
of around 260 symptoms, and their synonyms, totaling around 600 valid terms.
Thefallback intent is triggered when no other intent has been matched. The corre-
sponding action triggers the save suggestion background task and returns a "Processing
input" message. The task receives as input parameters the interaction identier and the
user input that was not matched:
@celery.task(name="tasks.save_suggestion")
def save_suggestion(interaction_identifier, input):

5.4. MAIN FUNCTIONALITY IMPLEMENTATION 39
Figure 5.8: Sequence Diagram showing Diagnosis phase
The interaction will be retrieved from the database. The enchant python library
is used to check for a valid alternative to the input. This is done by checking an already
dened dictionary that contains terms equal to the symptoms of our system and their
synonyms. In addition, the following forms have also been included:
I have <term>.
I am experiencing <term>.
I feel<term>.
<term>is bothering me.

40 CHAPTER 5. DETAILED DESIGN AND IMPLEMENTATION
Figure 5.9: Spellchecking
The dictionary was created by traversing the symptoms andsynonyms.json le and
writing the possible forms for each symptom and synonym in a dictionary.txt le.
Our system contains around 260 symptoms and their synonyms, totalling around
600 valid terms. Each term is accepted by itself and in the 4 forms shown above, resulting in
3000 dierent valid inputs that will also be spellchecked. The enchant library will provide
suggestions for erroneous spelling of input. For example "anxieti" will be transformed in
"anxiety". "I hav a hedache" will be transformed in "I have a headache". This suggestion
is saved in the "suggestion" column of the interaction.
The system will then trigger the get-suggestion intent which will retrieve the
suggestion from the database and return it to the chat interface where it will be displayed
to the user in the form "Did you mean" + suggestion?. The categorize-suggestion
context is now set.
if the user answers armatively the suggestion-yes intent is triggered; the system
will now make a call to API.AI containing the suggestion text – this will trigger the
identify-symptom intent where the symptom will be registered
if the user answers negatively the suggestion-no intent is triggered where the user
will be asked to rephrase
The system alternates between allowing free-form input from the user (when asking
for symptoms for example), providing quick replies that the user can click with the mouse,
and asking yes/no questions (gure 5.10).

5.4. MAIN FUNCTIONALITY IMPLEMENTATION 41
Figure 5.10: Diagram showing diagnosis-related intents

42 CHAPTER 5. DETAILED DESIGN AND IMPLEMENTATION
5.4.7 General health advice
The user can select to receive general health advice, at which point the Ask-
ForHabit intent is matched and the get-habit context is activated. This section of the
application does not use information from the database or external services. The intents,
contexts and actions are dened in the API.AI console.
The user is asked to input a habit that she would like to improve. Wilson can oer
advice in 3 areas: exercise, diet and sleep.
In the exercise branch, the ExerciseAdvice intent is matched and the user is asked
for an exercise goal
In the diet branch, the DietAdvice intent is matched and the user is asked for a
type of diet
In the sleep branch, the SleepAdvice intent is matched and the user is asked the
number of hours she sleep per night
A message card containing an image and an external link is then displayed (gure 5.11).
The message card is a response containing the \type" parameter with value 1, which is
then displayed on the screen similarly to the QuickReply response. The interaction
ow
of the general health advice functionality can be viewed in gure 5.12.
Figure 5.11: Diet Advice

5.4. MAIN FUNCTIONALITY IMPLEMENTATION 43
Figure 5.12: Diagram showing intents and contexts for General Health Advice

44 CHAPTER 5. DETAILED DESIGN AND IMPLEMENTATION
5.4.8 Smalltalk
API.AI provides default intents for general conversation topics, which can be added
to the JSON representation of the agent and uploaded for use. We have chosen to integrate
the \smalltalk" domain, in order to allow the agent to respond to general questions and
improve the antropomorphic qualities of the bot. The imported text responses can be
recongured in the API.AI console. The covered topics include:
greetings, parting phrases
compliments
occupation of the agent
hobbies of the agent
residence of the agent
mood of the agent
mood of the user
Figure 5.13: Agent performing "smalltalk"

5.4. MAIN FUNCTIONALITY IMPLEMENTATION 45
5.4.9 Training
API.AI provides a training feature that allows us to view a recording of all previous
interactions of the agent. In cases where the user input was erroneously unmatched, we
can directly assign the input to the correct intent. If no correct intent exists for the input,
we can create it at this moment, or add the user input to the valid list of entity synonyms.
In this way, the list of valid inputs of the system can be continuously enhanced.
For example, if the user chooses to receive general health advice, she is asked to
input what habit she would like to improve. If the user says\I don't eat enough vegetables",
no intent will get matched, as we have not dened this as a valid input. The agent will
display a message asking the user to rephrase.
In the training section API.AI provides an archive of past conversations, showing a

ag for unmatched inputs (gure 5.14).
Figure 5.14: API.AI training feature [5]
If we already have a suitable intent for the input, we can now assign it at this
point. In this case the \DietAdvice" intent would be correct. After approving the changes
API.AI performs a \training session". The next time a user enters the \I don't eat enough
vegetables" input or a similar variation, the \DietAdvice" intent will be matched.
5.4.10 Viewing past interactions
The user has the possibility of viewing information regarding past diagnosis-related
interactions by pressing the "Interactions"button in the chat page of the application (gure
5.15). The list of interactions is supplied by the index action of the InteractionsCon-
troller . The information is displayed on multiple pages with 10 entries per page. The
willpaginate library was used to implement pagination (this involves including a \pag-
ination" html element and adding a \paginate" query to the index action in which the
number of entries per page is supplied).
Each interaction can also be viewed individually, in which case all mentioned symp-
toms are displayed, along with the nal diagnosis (gure 5.16). The information is supplied
by the show action of the InteractionsController .

46 CHAPTER 5. DETAILED DESIGN AND IMPLEMENTATION
Figure 5.15: Past interactions
Figure 5.16: Symptoms and diagnosis of interaction

Chapter 6
Testing and Validation
6.1 Automated tests
TheMinitest testing framework was used in order to write the automated tests of
our Ruby on Rails application. Example – Testing the login functionality:
test "login with invalid information" do
get new_user_session_path
assert_response :success
post user_session_path, params: {user: { :email => '', :password => '' } }
assert_equal 'Invalid Email or password.', flash['alert']
end
test "login with valid information" do
get new_user_session_path
assert_response :success
post user_session_path, params: {user: { :email => 'ovidiu@gmail.com',
:password => 'password' } }
assert_equal 'Signed in successfully.', flash['notice']
end
The following automated tests have been implemented:
test "should get chat page"
test "register successfully"
test "register invalid email"
test "register – password conrmation unmatched"
47

48 CHAPTER 6. TESTING AND VALIDATION
test "register – password too short"
test "login with invalid information"
test "login with valid information"
test 'should get interactions index'
test 'should get interaction show'
test 'should get symptoms index'
test 'should get homepage'
The tests can be run with the following command (the test results can be seen in
gure 6.1):
bundle exec rake test
Figure 6.1: Automated tests results
6.2 Synonym matching
Our system will match 260 dierent symptoms and their synonyms totalling around
600 terms in the following forms:
<term>.
I have <term>.
I am experiencing <term>.
I feel<term>.
<term>is bothering me.
Table 6.1 shows example test cases for synonym matching:

6.3. SPELLCHECK TESTING 49
Table 6.1: Symptom matching
Input Matching
Stomach ache Abdominal pain
Pyrosis Heartburn
Pain in the back Back pain
Dorsalgia Back pain
Backache Back pain
Dyspnea Shortness of breath
Breathlessness Shortness of breath
Bloody sputum Bloody cough
Coughing up blood Bloody cough
Hemoptysis Bloody cough
Agitated Anxiety
Panic Anxiety
Sleeplessness Insomnia
Impaired balance Loss of balance
Word-nding disorder Diculty in nding words
Anomia Diculty in nding words
Amnesic aphasia Diculty in nding words
Confusion Disorientation regarding time or place
Vertigo Dizziness
Hallucination Delusion
Limited mouth opening Lockjaw
Trismus Lockjaw
Epistaxis Nosebleed
Pruritus Itching in the ear
Increase in weight Weight gain
Cold intolerance Sensitivity to cold
Feeling cold Sensitivity to cold
Perspiration Sweating
Shivering Chills
Shivering t Chills
Shivering attack Chills
6.3 Spellcheck testing
The input forms shown above are spellchecked by the system. We have performed
various tests to determine the accuracy of the spellcheck functionality (table 6.2). The
application is able to suggest a valid alternative to inputs that contain usual spelling
mistakes. If a match is not found the user will be asked to rephrase the input.

50 CHAPTER 6. TESTING AND VALIDATION
Table 6.2: Spellcheck testing
Input Result
Anxieti Anxiety
Anxiet Anxiety
Anxie Anxiety
Anxi Anxiety
Anx Ague
angziety Anxiety
anzious Please rephrase
i hve anxiet I have Anxiety
hve anxiet Please rephrase
i am ling anxiet I am feeling Anxiety
i am ling anxiet I am feeling Anxiety
i am ling anzieti Please rephrase
anzieti is bathering me Anxiety is bothering me
anziet is bathering me Anxiety is bothering me
anziet is batherign me Please rephrase
i am esperiensing anxiety I am experiencing Anxiety
i am esperiensing anxieti I am experiencing Anxiety
i am esperiensing anxiet I am experiencing Anxiety
i am esperiensing anxie Please rephrase
i am esperiensing anziety I am experiencing Anxiety
i am esperensing anziety Please rephrase
Heartbern Heartburn
Heartbrn Heartburn
Hartbrne Heartburn
Hartbrnef Please rephrase
i hav Hartbern I have Heartburn
i hve Hartbern I have Heartburn
i hv Hartbern Please rephrase
6.4 ApiMedic accuracy
ApiMedic – the external service used for symptom, diagnosis and medical special-
ization information reports the following accuracy levels:
In 70% of cases the call to the GET /diagnosis endpoint will result in a correct
diagnosis for the given list of symptoms
In 95% of cases the call to the GET /specializations endpoint will result in the
correct medical specialization for the given list of symptoms

Chapter 7
User's manual
7.1 Installation description
For optimal results the development of the application requires:
a UNIX operating system, such as Linux or Mac OS X
Ruby version 2.3.11
Rails version 5.0.2
Python version 3.5.0
Flask 0.12.2
PostgreSQL version 9.5.6
Redis 3.2.8
In the Ruby on Rails application, the database conguration le is located in: con-
g/database.yml. The conguration le includes the database name, postgres username
and password for each environment (development, staging, production). The following
commands will create the database with the name specied in the conguration le, having
the structure specied by the "schema.rb" le located in the "db" folder of the application.
bundle exec rake db:create
bundle exec rake db:schema:load
Run the "bundle install"command in the command line in order to install all needed
libraries (gems) on the system. The Ruby on Rails server can be turned on using the "rails
server" command, wich will run the application locally on the port 3000.
The Flask database conguration is located in the rst lines of the "webhook.py"
le. The command:
51

52 CHAPTER 7. USER'S MANUAL
pip install -r requirements.txt
Installs all needed libraries to run the application.
The application can be run locally by running the following commands:
python webhook.py – running the Flask application
systemctl start redis – running the redis instance
celery -A webhook.celery worker – running the celery workers
The above commands will start the Flask application on the 5000 port. The celery
worker is congured to communicate with the redis instance on the default redis port,
6379.
7.1.1 Deployment
The application is hosted on the Heroku [27] platform. The Git version control
system is used to specify the remote location for deployment in the conguration le of
the .git folder of our applications:
[remote "heroku"]
url = https://git.heroku.com/guarded-woodland-90251.git
fetch = +refs/heads/*:refs/remotes/heroku/*
Both the Ruby on Rails and Flask applications can be deployed with the followning
command:
git push heroku master
7.2 User manual
On the homepage of the application the user must rst select the "Register" option
(gure 7.1).
Account creation requires the following information: email, rst name, last name,
password, password conrmation. After the account is created the user is redirected to
the main chat page of the application.
If the user already has an account, the "Login" option can be selected on the home-
page. The application can be accessed by supplying a valid email and password (gure
7.2).
Once authenticated, the agent will greet the user and present a set of options. By
clicking on the "Diagnose an issue" quickreply, the symptom gathering phase can begin.
The user can describe his symptoms, and answer the questions given by the agent. At the
end of this phase a diagnosis is presented. The user can now choose the diagnose a new
issue by selecting the "Diagnose an issue" quickreply again.

7.2. USER MANUAL 53
Figure 7.1: Register screen
Figure 7.2: Login screen

54 CHAPTER 7. USER'S MANUAL
By clicking the "Get health advice" quickreply the user will start the health advice

ow. When asked to describe a habit for improvement, the user may input text freely.
Three types of habits will receive valid answers: exercise, diet and sleep habits. \I want to
sleep better" is a valid input for the sleep advice branch. Depending on the selected habit,
the user will be asked to introduce an exercise goal, diet type, or the number of hours slept
per night. After supplying a reply the user will be presented with cards containing images
and links to external articles that can be followed.
The agent will also respond to common topics of conversations. Example \How are
you feeling?".
At any point, the user can select the "Interactions" button in order to view an
archive of past diagnosis-related interactions. Choosing the "Logout" button will end the
session and redirect the user to the main page of the application.

Chapter 8
Conclusions
8.1 Contributions
The symptom and diagnosis data provided by the ApiMedic service has been suc-
cessfully integrated in the API.AI natural language processing tool. A diagnosis agent has
been implemented and integrated in the chat interface of our application.
The agent can successfully carry out a conversation and provide medical advice re-
lated to the symptoms presented. The implementation has succeded in attributing some
antropomorhic traits to the agent. The friendly nature of the bot helps to create a connec-
tion with the user and gain his trust. We appreciate that this is a crucial aspect for future
medical applications. The bot shows interest in the wellbeing of the user and appears
engaged throughout the symptom gathering phase. Only symptoms that were explicitly
experienced by the user are taken account in the nal diagnosis.
Because the user has the freedom to type anything in the chat, some inputs may not
be immediately matched by a previously dened intent. The rst strategy that handles
this situation covers otherwise valid inputs that are misspelled. In this case the agent
will rst attempt to provide an alternative to the user, and in the case of failure will
apologize and ask the user to rephrase. The second strategy involves periodically checking
conversation logs using the training feature in the API.AI console, assigning unmatched
inputs to existing intents, or creating new intents and synonyms to cover the unmatched
inputs. The agent is then retrained with the changes, with unmatched situations being
matched in subsequent interactions. This path provides a way of continuously improving
the agent.
The application also provides the possibility for the user to review an archive of
diagnosis-related interactions, displaying mentioned symptoms and diagnoses. This func-
tionality shows potential development strategies in which conversations could be reviewed
not only by the user of the application, but by medical professionals who could then de-
cide to take actions (like book an appointment) or provide feedback on the accuracy of the
diagnosis.
The agent can successfully provide general health advice for exercise, diet and sleep-
55

56 CHAPTER 8. CONCLUSIONS
ing habits, by presenting to the user external resources for improving these habits. A
\smalltalk" domain has also been integrated, allowing the agent to respond to common
conversation topics that the user might bring up. This ensures that a response will be
provided to a wide variety of user inputs, allowing the bot to mimic human discourse.
The type of agent developed in our application can serve as an assistant to medical
professionals that cover general health domains, automating routine tasks in the onboard-
ing of patients. Several features of the agent, such as the use of a human-like discourse are
aimed at increasing the activation levels of patients.
8.2 Further developments
Further developments of the system will involve adding more synonyms to the symp-
toms list, and more response variations. Exposing the agent to as many interactions as
possible will help develop the system by using the training feature. The experience can be
further improved by allowing the user to restart the interactions at any time, if he is stuck
in the
ow. Adding a \help" intent for each conversation context with instructions to the
user could further reduce the number of failed interactions. The \spellcheck" functionality
could be enchanced by adding alternate terms in the dictionary when they are approved
by the user in the conversation
ow.
Additional enhancements of the system could focus on further integrations in the
medical process, creating dierent roles for clinic clerks, doctors and nurses. An appoint-
ment system based on the result of the user-agent interaction that automatically creates
an appointment with a doctor from the determined medical specialization could also be
developed. This would extend the degree to which the process is aided by the applica-
tion. Medical personnel could also be allowed to review the user-agent conversations and
approve appointments and diagnoses.
In the event that a combination of symptoms does not receive a diagnosis from
the agent, a medical professional could be added to the chat and take over the conversa-
tion. Conversations with patients that describe serious or life-threatening conditions could
trigger emergency notications for trained professionals that could act immediately.
Adding\staging"and\production"development environments, with dierent deploy
destinations could ensure that only tested and approved changes are merged in the produc-
tion version of the application. This would also mean having two distinct agent versions
that are managed by a version control system under their respective JSON representations.
Extensions of the application could be developed on mobile devices, ensuring a
broader distribution among users. A periodic notication system could also serve to in-
crease the engagement of the user.

Bibliography
[1] J. Greene, J. Hibbard, R. Sacks, V. Overton, and C. Parrotta, \When patient activa-
tion levels change, health outcomes and costs change, too," Health A , vol. 34, no. 3,
2015.
[2] C. Bloss, N. Wineinger, M. Peters, D. Boeldt, L. Ariniello, J. Kim, J. Sheard, R. Ko-
matireddy, P. Barrett, and E. Topol,\A prospective randomized trial examining health
care utilization in individuals using multiple smartphone-enabled biosensors," PeerJ ,
vol. 4:e1554, 2016.
[3] M. Johnson, \How the statistical revolution changes (computational) linguistics," in
Proceedings of EACL Workshop on the Interaction of Linguistics and Statistics , 2009.
[4] Futurism. (2016) The history of chatbots. [Online]. Available:
https://futurism.com/images/the-history-of-chatbots-infographic/
[5] API.AI. (2017) Build delightful and natural conversational experiences. [Online].
Available: https://api.ai/
[6] wit.ai. (2017) Natural language for developers. [Online]. Available: https://wit.ai/
[7] luis.ai. (2017) Language understanding intelligent service. [Online]. Available:
https://www.luis.ai/
[8] Amazon. (2017) Alexa voice service. [Online]. Available:
https://developer.amazon.com/alexa-voice-service
[9] V. Kumar, A.Keerthana, M.Madhumitha, S.Valliammai, and V.Vinithasri, \Sanative
chatbot for health seekers," International Journal of Enneering and Computer Sci-
ence, vol. 5, no. 3, 2016.
[10] B. E. V. Comendador, B. M. B. Francisco, J. S. Medenilla, S. M. T. Nacion, , and
T. B. E. Serac, \Pharmabot: A pediatric generic medicine consultant chatbot," Jour-
nal of Automation and Control Engineering , vol. 3, no. 2, pp. 137{140, 2015.
[11] B. Health. (2017) Babylon health: Online doctor consultations and advice. [Online].
Available: https://www.babylonhealth.com/
57

58 BIBLIOGRAPHY
[12] Baidu. (2016) Baidu's melody: Ai-powered conversational bot for doctors and
patients. [Online]. Available: http://research.baidu.com/baidus-melody-ai-powered-
conversational-bot-doctors-patients/
[13] S. K. Card, A. Newell, and T. P. Moran, The Psychology of Human-computer inter-
action. Lawrence Erlbaum Associates, 1983.
[14] J. Kirakowski, P. O'Donnell, and A. Yiu, Establishing the Hallmarks of a Convincing
Chatbot-Human Dialogue, Human-Computer Interaction . InTech, 2009.
[15] A. C. Saarem. (2016) Why would i talk to you? investi-
gating user perceptions of conversational agents. [Online]. Available:
https://www.ntnu.edu/documents/139799/1273574286/TPD4505.AnneCathrine.Saarem.pdf/
[16] priaid. (2016) Apimedic. [Online]. Available: https://apimedic.net/
[17] WebMD. (2016) Webmd symptom checker. [Online]. Available:
http://symptoms.webmd.com
[18] O. Boyman. (2015) Istanbul university hospitals use the priaid symptom checker.
[Online]. Available: https://www.linkedin.com/pulse/istanbul-university-hospitals-
use-priaid-oender-boyman
[19] I. University. (2014) Symptom checker. [Online]. Available: http://priaid-
cerrahpasa.istanbul.edu.tr/
[20] D. H. Hansson. (2017) Ruby on rails. [Online]. Available: http://rubyonrails.org/
[21] A. Ronacher. (2017) Flask. [Online]. Available: http://
ask.pocoo.org/
[22] C. Sweeney. (2017) Flask assistant. [Online]. Available: http://
ask-
assistant.readthedocs.io/en/latest/
[23] S. Ahmed, \Medical diagnosis using neural networks," International Journal of Engi-
neering Development and Research (IJEDR) , vol. 2, no. Issue NCETSE Conference,
pp. 201{204, 2014.
[24] M. Fowler, D. Rice, M. Foemmel, E. Hieatt, R. Mee, and R. Staord, Patterns of
Enterprise Application Architecture . Addison-Wesley Professional, 2002.
[25] A. Ronacher. (2017) Celery based background tasks. [Online]. Available:
http://
ask.pocoo.org/docs/0.12/patterns/celery/
[26] S. Sanlippo. (2017) Redis. [Online]. Available: https://redis.io/
[27] Heroku. (2017) Cloud application platform. [Online]. Available:
https://www.heroku.com