# Ruby DCU's Student Personal Assistant Functional Specification

Student 1: Ben Clarke
Student Number: 15337426

Student 2: Conor Carney
Student Number: 16363111

Project Supervisor: Darragh O'Brien
Completion Date:

## Functional Specification Contents
### 0. Table of contents
*A table of contents with pages numbers indicated for all sections / headings should be included.*
### 1. Introduction
#### 1.1 Overview
Ruby is a personal assistant for students of DCU that brings timetable information, public transport information and an array of other student related information to a student's finger tips. Being available on existing messaging platforms like Facebook Messenger and Discord gives Ruby a huge userbase potential and also makes Ruby a platform indepentant personal assistant. Ruby will also have Google and Alexa skills so students who find it hard to type or want to use Ruby in a hands-free environment can do so with ease. Ruby can also recommend clubs and societies for a student to join based off of the students interests and other students who have similiar interests.

The information available to students via DCU's website and OpenTimetable can be hard to find due to the volume of webpages and inputs a student has to sift through. Also this information can be quite time consuming to attain frequently in the case of OpenTimetable, due to the volume of inputs a student has to make everytime time they want to know if a lab is free for study for example. Another issue Ruby aims to help solve is finding the most convenient bus off campus to a given destination, Ruby will search the local bus stops for, not only the quickest, but a bus that is expected to leave closest to the time that the student supplied. This eliminates the need to search across multiple apps or rely on a specific bus stop's timetable.

To combat these issues, Ruby will ask a first time user some basic questions like "What is your name?", "Would you like to give me your student number so I can help with your timetable" and "Do you use public transport to travel from DCU". These three questions build an initial profile for Ruby to base further interactions off of and to get a good understanding of what the user will use Ruby for initially. If the student gives Ruby their student number, Ruby uses DCU's LDAP infrusture to get the students course code and build the students timetable quietly in the background for easy access in the future. If the student asks Ruby what ther next class is, Ruby will already have that information on hand so can respond rapidly. This is a brief description of one of Ruby's functions.

#### 1.2 Business Context
There is no business organisation(s) sponsoring the development or deployment of this product. Also as Ruby is designed to only be used via particular apps and interfaces, it cannot be deployed by the end user or self-hosted.

#### 1.3 Glossary
**Natural Language Understanding(NLU)** - This is the parsing of incoming information and using a trained model to derive intent and tag variables to be used at a later date in the process.

### 2. General Description
#### 2.1 Product / System Functions
Ruby will be able to give personal responses to users based off who is asking the questions. This is achieved through unique user identifiers embedded in the message requests(i.e. Facebook Messenger id's and Discord User id's), where a user cannot be identified Ruby will ask who the user is and update the user's information accordingly. When the user is using Ruby for the first time, Ruby will ask a few initial questions to build a user profile and store these in a User Database. If the user is using a different platform to use Ruby, it will ask if it has seen the user before. If the user answers yes, then the unique identifier for that platform will be associated with the user entry in the User Database.

Ruby's flagship questions are "What is my next class?", "When is my next bus home?", "Is {room code} free now?" and "Where is {room code/building name}?". Ruby will be able to answer the user no matter how the user asks it. Ruby will use a Natural Language Understanding(NLU) tool to parse the incoming language and extract the intent and other key variables, rates the intent and chooses the correct function to pass the variables to. It does this by training itself on data models we create and previous conversation history. Ruby can also understand and respond to a variety of languages as translation of non-english vocabulary will be done before it is sent to the NLU for processing.

Ruby will have a DCU clubs and societies recommender system built in. This works by asking the user if they would like to use this function, if the user agrees their response is recorded and a follow up set of questions will be asked to determine the users interests. Once the interests have been finalised, Ruby will look for other users with similar interests and recommend clubs and/or societies based off these common interests.

Making Ruby available on Google Assistant and Amazon Alexa is a must for the inclusive nature of personal assistants. While Ruby won't be available as a stand alone assistant, using google and alexa skills is a great way to ensure any users who are hard of sight or in an hands-free environment can still use Ruby to the fullest extent.

#### 2.2 User Characteristics and Objectives

Ruby is designed to be used by anyone with access to the internet. The user needs little to no prior knowledge of how Ruby works as there will be a helper function that can be called if the user is stuck at any stage of the conversation. Depending on what platform the user wants to use Ruby on, the user would need a Facebook Messenger account, a Discord account and be a member of the Ruby discord server or finally, have access to the Ruby website url to use the webapp.

From a user's perspective, Ruby must be quick, accurate, reliable and personal. Users want a personal experience that provides accurate information, this is what makes Google Assistant and Amazon Alexa so popular. Taking inspiration from these leads to a high standard of expectance from the user when using a product labelled a personal assistant. If Ruby takes just as long or longer to retrieve the users next class, Ruby has failed the users expectations and is most likely not going to continue to use Ruby. Keeping users interested in using Ruby will ultimately be down to the users perspective on how useful it's functions are. Providing enough variation in Ruby's functionality should keep the user using Ruby for at least one of it's functions.

#### 2.3 Operational Scenarios
Ruby's flagship questions are "What is my next class?", "When is my next bus home?", "Is {room code} free now?" and "Where is {room code/building name}?". These all have there own flow internally with subtle differences on how to initalise the flow in which Ruby can learn overtime.

*User's first time using Ruby*
**User** - "Hello"
**Ruby** - "Hi There, we have not met before. Can I ask you a few questions to get to know you a little more?"
**User** - "Sure"
**Ruby** - "Great, first question, what is your first name and surname?"
**User** - "Ben Clarke"
**Ruby** - "Thank you. Next question is, would you provide me with your student number? This is so I can get your timetable for you."
**User** - "Ok cool, my student number is 15337426"
**Ruby** - "Great thanks, my next question is do you use public transport to leave DCU? I need this if you want be to tell you what buses to take home."
**User** - "Yes, I take the bus"
**Ruby** - "Nice, so would you like to tell me your eircode so I can tell you the most convenient bus home or set a bus stop you typically take the bus from?"
**User** - "my bus stop is the ballymun road stop"
**Ruby** - "I will set that as your preferred stop, if you want to add your eircode later just ask."
**Ruby** - "Would you like me to recommend a DCU club or society to you?"
**User** - "Not now"
**Ruby** - "Ok no problem. If you do want me to recommend one, just ask me."
**Ruby** - "Your all set up, So what can I help you with today?"

*"Where is my next class?" will return the class name, time, location and if available, the lecturer's name.*
**User** - "Where is my next class"
**Ruby** - "Your next class is CA400 4th Year Project at 1pm in T101"
**User** - "Thanks"
**Ruby** - "Your very welcome"

*"When is my next bus home" will return the next bus from a predefined(by the user) bus stop or to the user's eircode.*
**User** - "When is the next bus home?"
**Ruby** - "It's the 153 from the Helix bus stop"
*other use case for this function is*
**User** - "When is the next bus from the ballymun stop?"
**Ruby** - "The next bus is the 12 leaving at 13:45, can you make that?"
**User** - "No"
**Ruby** - "Ok, the bus after that is 14:00"
**Ruby** - "Anything else I can help you with?"

*"Is {room code} free {time}" will return a yes or no answer if the room has no class scheduled in the current hour.*
**User** - "Is LG25 free now?"
**Ruby** - "No, LG25 is not free until 1pm"
*Another use case for this function*
**User** - "Is CG12 free at 4pm?"
**Ruby** - "Yes, CG12 is free currently at 4pm"

*"Where is {room code/building name}?" will return a google maps link with the exact location of the room or building requested.*
**User** - "Where is T101?"
**Ruby** - "Here is a google maps link to T101 for you, https://dcuruby.tech/x1y2z3"

*Clubs and Societies recommender*
**User** - "Can you recommend me a club or society?"
**Ruby** - "I surely can, are you a member of any clubs and/or societies currently?"
**User** - "Yes"
**Ruby** - "Which ones?"
**User** - "Redbrick"
**Ruby** - "Cool, I need a couple of your favourite hobbies or interests first so I know what to recommend to you. What would they be?"
**User** - "Football and coffee"
**Ruby** - "Fantastic, I would recommend DCU's Coffee Society as you have an interest in coffee and others who are members of Redbrick are also a member of DCU's Coffee Society"

#### 2.4 Constraints
A list of possible constraints that we may encounter can be found below:

- __Internet Connection__
As Ruby's users may not always have a stable internet connection or no internet connection at all, this means there may be times were the student is not able to interact with Ruby or the efficiency of Ruby's responses could be delayed.

- __Messaging services having unavoidable downtime__
The messaging services that Ruby will be available on are independent of each other. The benefit is if one of the supported messaging services experiences some unforeseeable downtime, the other messaging services are not affected in anyway.

- __Function server having downtime__
As our functions will be hosted and served from our own server, there are opportunities for our server to experience periods of downtime. While every care will be used to avoid this, human error can occur while working on the server. This will most likely stem from upgrades being done from a server point of view, or upgrades to Ruby's functionality. These will be minimised by conducting good testing practises before deploying to a production environment, but nonetheless sometimes unavoidable.

- __Database errors__
As our data will be stored across multiple databases, there is a possibility that some information that is being automatically scraped from the web could be stored in the database incorrectly. This can lead to problems when our functions try to access information from an area were the information should be stored and it is not available or incorrect.

- __Multiple services running on same machine__
As a cost saving measure we will be running most of the services, including critical production services, from the same server. While we acknowledge that this is not best practice, the cost of running multiple servers for multiple environments and services is substantial. This can lead to the whole system being down as a worse case.

- __Time Constraints__
There are multiple aspects to this project that will require certain tasks to be completed and fully tested within the designated time allocated in order to allow for a sufficient amount of time to be left for our final stage of testing. This is essential for the completion of the project and making Ruby usable to DCU students. Some of the tasks that we have created for ourselves are abstract in nature and may require more or less time to complete, depending on the task. This means that our schedule will have to be flexible enough to allow for these time changes, but rigid enough to complete the project by the deadline set in May.

### 3. Functional Requirements

| Requirement 1 | Being Personal |
| -------- | -------- |
| Description | Ruby must be perceived by the user as human like. This means that it must answer user queries in the same manner as a human would. Being personal also means that Ruby must recognise the user with minimal or no prompting for identification from the user and replying with user specific data. |
| Criticality | This is the most critical part of Ruby's functionality. Without this requirement being met, Ruby fails to be a personal assistant and downgrades to a generic chatbot |
| Technical Issues | Making sure that the correct unique message id is being associated with the correct user. The information being sent back to the user is personal to that user and that user alone. |
| Dependencies with other requirements | The data returned to the user must be of an accurate nature as this has the potential to decrease the personal nature of the response to the user |

| Requirement 2 | Efficient responses |
| -------- | -------- |
| Description | Making Ruby's responses as efficient as possible is a big priority. For us, efficiency is a balance of speed and context correctness. Ensuring Ruby responds quickly is paramount but this speed must not overtake the need to be contextually correct, a small trade off for speed in favour of being in the correct context is acceptable(with the aim of identifying the slowdown and patching it) |
| Criticality | Efficiency is very critical to Ruby's ability to retain the user's interest in continued usage, and also the user's willingness to provide information for Ruby's more extensive features to be used correctly |
| Technical Issues | A mixture of database queries and web requests might have to be made for a single user query. This has the potential, if configured incorrectly, to cause slowdowns in Ruby's responses and returning incorrect context responses if the one of the requests returns incomplete or overruns it's expected run-time. |
| Dependencies with other requirements | This requirement is not dependent on any other requirement as they will have no baring on how efficient Ruby's responses will be. |

| Requirement 3 | Accurate response content |
| ------------- | -------- |
| Description | How accurate Ruby's responses are will directly affect how often a user will use Ruby. If it's responses are not accurate, users will not use Ruby often if at all. The more accurate the information that is returned to the user, the higher the likelihood of the user returning. While we do expect some errors in accuracy, we strive to make these errors scarce with rigorous testing at every stage of development. |
| Criticality | Accurate information directly influences user retention, therefore is essential that we capture any errors early in development and testing. Integrating a user feedback ability to report inaccurate information will be available to give the user some control over the accuracy of the information. |
| Technical Issues | Incorrect association of information to a user is a potential issue. In the same context, information retrieval from a third party source like Go Ahead Buses is not guaranteed to always be 100% accurate, so therefore Ruby's information will fall in line with this information. |
| Dependencies with other requirements | Accuracy has a tie in with our most critical requirement, being personal. Having accurate information on a user is part of being a personal assistant and can have a negative affect on this key element. However, inaccurate information can be fixed and/or adjusted with reduced effort compared to the other requirements mentioned above. |

### 4. System Architecture
*This section describes a high-level overview of the anticipated system architecture showing the distribution functions across (potential) system modules. Architectural components that are reused or 3rd party should be highlighted.*

#### 4.1 System Architecture Diagram


#### 4.1.1 Description of the System Architecture Diagram

The above diagram illustrates how Ruby will work from an architectural stand point. When a user queries one of the supported messaging platforms, the query is checked to verify if it is in English and translated if necessary, the query is then sent to Ruby's Natural Understanding(NLU) framework which parses the query, determines what the intent of the message is and if there is any variables to be passed as parameters to the worker functions. The intent determines what worker function is used and the correct parameters are sent to the worker function. If the worker function needs to query a database, the database search algorithm will be triggered with the correct inputs and returns the requested information to the worker function. Once the worker functions have completed their tasks, the response is sent back to Ruby's NLU framwork where it is formed into a user readable sentence and sent back to the messaging platform where it is translated, if necessary, and sent in the initial language of the user.

### 5. High-Level Design
*This section should set out the high-level design of the system. It should include one or more system models showing the relationship between system components and the systems and its environment. These might be object-models, DFD, etc. *

#### 5.1 Data Flow Diagram


##### 5.1.1 Description of the Data Flow Diagram

The above data flow diagram displays the way in which data flows during the process of answering a user's query. We can see from this diagram that the user's query is the true starting point of this process The user can query Ruby on any one of the supported messaging platforms. The user's query will then be checked to verify if it is in English and translated if necessary. The query will always be translated to English and then passed to Rasa, a Natural Language understanding framework which will parse the user's input and work out the messages intent. If the user is not yet known to Ruby, they will be asked a short series of questions to allow Ruby to get to know them while storing this information into our User Database. If the user is already known to Ruby, the intent of their query will be worked out, function variables will be gathered and then run through one of our functions to retrieve the desired information or our database search algorithm is triggered if information from one of our databases is required to get the users desired answer. The retrieved result will then be returned to the user in the language that they initiated the conversation with.

### 6. Preliminary Schedule
*This section provides an initial version of the project plan, including the major tasks to be accomplished, their interdependencies, and their tentative start/stop dates. The plan also includes information on hardware, software, and wetware resource requirements. The project plan should be accompanied by one or more PERT or GANTT charts. *

| Sprint | Length | Start |Objectives | Owner |
| ------ |:---------:| --------:| -------------------------------:| ----- |
| 1 | Two week | 07/12/20 |Server Setup (Openfaas, rasa, gitea) | Ben |
| 1 | Two week | 07/12/20 |Server Setup (jenkins, MongoDB, TDD) | Conor |
| 2 | Two week | 21/12/20 |Rasa + Openfaas pipeline complete | Ben |
| 2 | Two Week | 21/12/20 |Jenkins + TDD pipeline complete | Conor |
| | Two Week | 04/01/20 |Exam Period | Ben |
| | Two Week | 04/01/20 |Exam Period | Conor |
| 3 | Two week | 18/01/21 |Rasa data model creation, database testing | Ben |
| 3 | Two Week | 18/01/21 |Rasa data model testing, database population | Conor |
| 4 | Two week | 01/02/21 |Small group user testing, bug fixes, Recommender system planning | Ben + Conor |
| 5 | Two week | 15/02/21 |Recommender system structure complete | Ben |
| 5 | Two week | 15/02/21 |Recommender system algorithm complete | Conor |
| 6 | Two Week | 01/03/21 |Recommender system combination | Ben |
| 6 | Two Week | 01/03/21 |Recommender system testing pipeline | Conor |
| 7 | Two Week | 15/03/21 |Inital Bug fixing for recommender system | Ben + Conor |
| 8 | Two Week | 29/03/21 |System integration with recommender system into Ruby |Ben |
| 8 | Two Week | 29/03/21 |Bug fixes and system load testing | Conor |
| 9 | Two Week | 12/04/21 | Final round of critical bug fixes | Ben + Conor |
| 10 | One Week | 26/04/21 | Final round of User testing | Ben + Conor |

### 7. Appendices
#### References
- [Messenger Platform Documentation](https://developers.facebook.com/docs/messenger-platform/) --> https://developers.facebook.com/docs/messenger-platform/
- [Discord Development Documentation](https://discordapp.com/developers/docs/intro) --> https://discordapp.com/developers/docs/intro
- [OpenFaaS Documentation](https://docs.openfaas.com/) --> https://docs.openfaas.com/
- [Rasa NLU Framework Documentation](https://rasa.com/docs/rasa/) --> https://rasa.com/docs/rasa/