Name: voiceapp311
Owner: Code for Boston
Description: Voice assistant connection to Boston services
Created: 2017-09-23 15:36:56.0
Updated: 2018-01-17 02:30:36.0
Pushed: 2018-01-17 01:40:23.0
Size: 11394
Language: Python
GitHub Committers
User | Most Recent Commit | # Commits |
---|
Other Committers
User | Most Recent Commit | # Commits |
---|
An Alexa skill to answer questions about municipal services in Boston. Currently supports providing an address and asking for trash/recycling pick up days.
In order to create an Alexa skill we need to configure two main components. The first is the Alexa skill itself. This is done through the Amazon developers page. Here you need to configure an Alexa skill, allowing Alexa to understand and react to user voice commands. The second is a Amazon Web Service (AWS) lambda function to run our application logic. Finally, we need to connect the Alexa skill to run our lambda function when it is activated.
The following instructions will walk you through creating the Boston Data Alexa skill, a new lambda function containing the Boston Data application, and then connecting the two together.
NOTE: The UI for some of the consoles used below has changed since this guide was written, however the general workflow is the same.
Clone this repo and from the BostonData directory run
on deploy_tools.py -p
This will generate the lambda_function.zip archive, which you will need later.
Once you've completed Part 3, go to the Test tab. Here you can run sample voice queries using the Service Simulator. See usage below for some examples to test out.
Supports three custom intents right now.
This is basically a restatement of the guide at https://moduscreate.com/build-an-alexa-skill-with-python-and-aws-lambda/ with some additional clarification.
User issues voice command to Echo by saying, “Alexa” followed by a skill name and an intent. The intent may have parameters.
In this case, something like: “Alexa, ask Boston Data when is trash day?“
l name : Boston Data
nt : find trash days
meters : 1 Main Street apartment 2
We will give this intent a name, TrashDayIntent. You can see this in the intent schema.
Echo sends the request to the Alexa Service Platform.
This handles the speech recognition and translates the above voice command to a JSON document containing the intent and any parameters.
This JSON is sent to the skill (Boston Data in this example).
For BostonData:
nt : trashday
meter : "1 Main Street apartment 2"
The skill receives the JSON.
We're implementing the skill as an AWS Lambda, so the JSON will be sent to the Lambda function at the ARN associated with the skill name.
The Lambda contains custom code that parses the JSON to identify the intent and corresponding arguments (in this example, the address).
The code then gathers data for the response. In this case that means a call to data.boston.gov to get the string of trash days associated with the provided address. Alternately this might mean accessing a database or session information.
This response data is serialized in a JSON response, which is returned to the Alexa Service Platform. It contains the response both as text for Alexa to say and as text/images for the smartphone app to display.
The Alexa Service Platform receives the response and conveys to the user using text-to-speech or the app display.
Because the python code in Boston Data's Lambda function uses resources beyond Python's standard libraries, it must be uploaded as a .zip file.
To generate this .zip file, we must install all of the required Python packages in the directory that contains our code. For this project, that directory is BostonData/lambda_function. Amazon provides instructions on how to do so: https://docs.aws.amazon.com/lambda/latest/dg/lambda-python-how-to-create-deployment-package.html
Once all the requisite libraries are installed, compress the contents of the directory. The instructions note:
Important: Zip the directory content, not the directory. The contents of the Zip file are available as the current working directory of the Lambda function.
Recall that in Part 2 of the installation instructions we set the Handler to lambda_function.lambda_handler. This is specifying the function that is executed when a voice command is issued to the Alexa device. If we compress the containing directory instead of its contents, this code is not available.
This is the new portal for Boston's open data efforts. This site uses a tool called CKAN, which describes itself as follows:
CKAN is a tool for making open data websites. (Think of a content management system like WordPress - but for data, instead of pages and blog posts.) It helps you manage and publish collections of data. It is used by national and local governments, research institutions, and other organizations who collect a lot of data.
CKAN sites are organized by datasets, which can be made available in multiple formats. AnalyzeBoston contains 131 datasets as of this writing. Searching the datasets for “trash” returns 4 results, including one we can use for this project: trash schedules by address. The API for that dataset can be found by following the link to the dataset and then selecting preview. On the preview page there is a DATA API link.
Here you can find a link labelled odata. odata is a REST protocol for open data. CKAN provides an odata endpoint for the trash schedules by address dataset.
This is the Open311 portal for the city of Boston. It requires an API key and solely provides 311 functionality (checking the status of 311 issues or filing new ones). At some point we'll probably want to incorporate this type of functionality, but for the simple city service information retrieval we're concentrating on right now, this API is not useful.
DEPRECATED
This is the former open data portal of the city of Boston. This API implemented the Socrata Open Data API. Socrata is a company that provides cloud-based data visualization and analysis tools for opening government data. This portal is no longer being updated.
From Amazon's documentation:
Amazon Resource Names (ARNs) uniquely identify AWS resources. We require an ARN when you need to specify a resource unambiguously across all of AWS, such as in IAM policies, Amazon Relational Database Service (Amazon RDS) tags, and API calls. https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html#arn-syntax-lambda
Our skill will be stored in an AWS Lambda function, which we can identify by its ARN.
Slots are used for intents that require parameters. Each slot must have:
The preconfigured slot type for a street address is described here.
Information on defining a custom slot type is available here.
Alexa needs a list of phrases that correspond to each of our skill's intents.
We provide this in the settings for our skill in the developer console (see Part 1 of installation).
The format for the list of sample utterances is
ent] [phrase]
The phrase may contain a reference to a slot if there is one associated with the intent it invokes. The format for this is
t_name}
Example of a sample utterance:
ddressIntent my address is {Address}
Our skill will invoke an Amazon Lambda function. This is where the code that produces a response to the Alexa voice command resides.
There are several language options for this code, including Javascript (Node.js), Java, C#, and Python(2.7 or 3.6).
Selecting Python we are provided the following template:
lambda_handler(event, context):
# TODO implement
return 'Hello from Lambda'
The event argument is the JSON received from the Alexa platform. It contains the intent and slot information from the voice command.
Structure of the event object:
ssion
sessionId: [session id],
application
applicationId: [application id]
attributes: {},
user
userId: [user id]
new: true
quest:
type: [request type, e.g., IntentRequest]
requestId: [request id]
timestamp: [timestamp]
intent
name: [name of the invoked intent]
slots:
[slot name]
name: [name of the slot]
value: [value of the slot]
locale: "en-US"
rsion: "1.0"
The elements of this event object are discussed in detail at: https://developer.amazon.com/docs/custom-skills/request-and-response-json-reference.html
Some of the intents require access to Google distance matrix which requires an access key to the Google API. In order to run these skills you will need your own access key which can be created by going to the Google Distance Matrix developer site and clicking the “Get A Key” button.
Once you have a key, go to your AWS lambda configuration page. Find
the environment variable section. Create a new environment variable
with the key `GOOGLE_MAPS_API_KEY
` and the value should be your
personal key.