Core¶

Provides types and helpers to create and work with CEK responses easily. For a high-level interface upon the cek.core module, see documentation for cek.clova module.

Request¶

class cek.core.Request(request_dict)¶

Represents a CEK request.

Parameters:

request_dict (dict) – Dictionary representation of a request from CEK.

Variables:

launch_key (str) – Key to identify the ‘LaunchRequest’ request type.
intent_key (str) – Key to identify the ‘IntentRequest’ request type.
event_key (str) – Key to identify the ‘EventRequest’ request type.
session_ended_key (str) – Key to identify the ‘SessionEndedRequest’ request type.
type (str) – type of request. Can be IntentRequest, EventRequest, LaunchRequest, SessionEndedRequest.
context (Context) – context of the current request from CEK.
application_id (str) – application id which has been set in the Developer Center

classmethod create(request_dict)¶

Factory method for creating right Response depending on request type.

Parameters:	request_dict (dict) – Dictionary represents a request from CEK.

verify_application_id(application_id)¶

Verify application id

Raises:	ApplicationIdMismatch – if application id is incorrect.

ApplicationIdMismatch¶

class cek.core.ApplicationIdMismatch¶: Application Id does not match.

Request¶

class cek.core.LaunchRequest(request_dict)¶: Request received when a user launches the skill.

LaunchRequest¶

class cek.core.LaunchRequest(request_dict): Request received when a user launches the skill.

SessionEndedRequest¶

class cek.core.SessionEndedRequest(request_dict)¶: Request received when a user has requested to stop using the skill.

IntentRequest¶

class cek.core.IntentRequest(request_dict)¶

Request received when a user sends a requests to the skill based on the predefined interaction model.

Variables:	name (str) – name of the intent. slots (dict) – dictionary of slot name to value.

slot_unit(slot_name)¶

Returns slot unit or None if missing.

Parameters:	slot_name (str) – slot name
Returns:	slot unit if exists, None otherwise.

Usage:

>>> @clova.handle.intent("TurnOn")
>>> def turn_on_handler(request):
>>>     request.slot_unit('degree')
'°C'

slot_value(slot_name)¶

Returns slot value or None if missing.

Parameters:	slot_name (str) – slot name
Returns:	slot value if exists, None otherwise.

Usage:

>>> @clova.handle.intent("TurnOn")
>>> def turn_on_handler(request):
>>>     request.slot_value('Light')
'電気'

slot_value_type(slot_name)¶

Returns slot valueType or None if missing.

Parameters:	slot_name (str) – slot name
Returns:	slot valueType if exists, None otherwise.

Usage:

>>> @clova.handle.intent("TurnOn")
>>> def turn_on_handler(request):
>>>     request.slot_value_type('when')
'TIME.INTERVAL'

EventRequest¶

class cek.core.EventRequest(request_dict)¶

Request received when an event on the user’s device occurred.

Variables:	id (str) – is the dialog request id. event (Event) – contains the payload from the client. timestamp (str) – of when the client sends information to Clova (ISO 8601).

Context¶

class cek.core.Context(context_dict)¶

Contains context information of the client.

Parameters:	context_dict (dict) – Dictionary represents the context from a CEK request.
Variables:	audio_player (AudioPlayer) – details of media content currently being played or played last. Can be None if empty. device (Device) – contains information of the client device. user (User) – default User of the device.

AudioPlayer¶

class cek.core.AudioPlayer(audio_player_dict)¶

Contains details of the media content currently being played or played last.

Parameters:

audio_player_dict (dict) – Dictionary represents the AudioPlayer from the CEK request.

Variables:

offset (num) – is the most recent playback position of the recently played media in milliseconds.
total (num) – is the total duration of the recently played media in milliseconds.
activity (str) – is indicating the current state of the player. Can be “IDLE”, “PLAYING”, “PAUSED” or “STOPPED”.
stream (dict) – contains details of the currently played media. TODO: AudioStreamInfoObject specs are still WIP.

Device¶

class cek.core.Device(device_dict)¶

Contains details about user’s device.

Parameters:	device_dict (dict) – device as dictionary from the CEK request.
Variables:	id (str) – ID of the device.

Session¶

class cek.core.Session(session_dict)¶

Contains details about a user’s session.

Parameters:	session_dict (dict) – session as dictionary from the CEK request.
Variables:	id (str) – is the session id. is_new (bool) – distinguishes whether the request message is for a new or the existing session. attributes (dict) – used in a multi-turn dialogue and contains the information set in the previous response.sessionAttributes. user (User) – Current user connected to the device. Can be different from context.user.

User¶

class cek.core.User(user_dict)¶

Contains user details.

Parameters:	user_dict (dict) – user as dictionary from the CEK request.
Variables:	id (str) – Clova ID of the user. access_token (str) – Access token of the user.

Event¶

class cek.core.Event(event_dict)¶

The object that stores the information sent by the client to Clova.

Variables:	name (str) – is the name of the event message sent by the client to Clova. namespace (str) – is the namespace of the event message. payload (objc) – is the payload or partial payload of the event message sent by the client to Clova.

Response¶

class cek.core.Response¶

The object containing the response information of the extension.

Variables:	session_attributes (dict) – Session attributes in a dictionary format. Will be send back in the next request. reprompt (dict) – reprompt value, can be SimpleSpeech, SpeechSet or SpeechList.

SpeechBuilder¶

class cek.core.SpeechBuilder(default_language='ja')¶

Helper class to build speech objects that can be part of CEK response.

Parameters:	default_language (str) – Set default language for all messages. Can be `ja`, `ko` or `en`.
Raises:	ValueError – if unsupported language is specified.

Usage:

All the examples below assume the following helper is defined in advance.

>>> from cek import SpeechBuilder
>>> from pprint import pprint
>>> speech_builder = SpeechBuilder(default_language="ja")

Building a plain text object:

>>> speech_builder.plain_text("こんにちは")
{'type': 'PlainText', 'lang': 'ja', 'value': 'こんにちは'}

plain_text(message, language=None)¶

Build a PlainText object

Parameters:	message (str) – String Message which clova should speak out language (str) – Language code of the message
Returns:	Dictionary with the format of a SpeechInfo with type PlainText
Return type:	dict
Raises:	ValueError – if unsupported language is specified.

Usage:

>>> speech_builder.plain_text("こんにちは")
{'type': 'PlainText', 'lang': 'ja', 'value': 'こんにちは'}

simple_speech(speech_value)¶

Build a SimpleSpeech object

Parameters:	speech_value (dict) – speech_value can be plain_text or url SpeechInfo
Returns:	Dictionary in the format of a SimpleSpeech
Return type:	dict

Usage:

>>> text = builder.plain_text("こんにちは")
>>> pprint(speech_builder.simple_speech(text))
{'type': 'SimpleSpeech',
 'values': {'lang': 'ja', 'type': 'PlainText', 'value': 'こんにちは'}}

speech_list(speech_values)¶

Build a SpeechList object

Parameters:	speech_values (list) – List which can consist of plain_text SpeechInfo or url SpeechInfo
Returns:	Dictionary in the format of a SpeechList
Return type:	dict

Usage:

>>> from pprint import pprint
>>> text = speech_builder.plain_text("こんにちは")
>>> url = speech_builder.url("https://dummy.mp3")
>>> speech_list = speech_builder.speech_list([text, url])
>>> pprint(speech_list)
{'type': 'SpeechList',
 'values': [{'lang': 'ja', 'type': 'PlainText', 'value': 'こんにちは'},
            {'lang': '', 'type': 'URL', 'value': 'https://dummy.mp3'}]}

speech_set(brief, verbose)¶

Build a SpeechSet object

Parameters:	brief (dict) – A Dictionary of a plain_text SpeechInfo or url SpeechInfo verbose (dict) – A Dictionary of a SpeechList or SimpleSpeech
Returns:	Dictionary in the format of a SpeechSet
Return type:	dict

url(url)¶

Build an URL object

Parameters:	url (str) – URL of the audio file which should be played by clova
Returns:	Dictionary with the format of a SpeechInfo with type URL
Return type:	dict

Usage:

>>> speech_builder.url("https://dummy.mp3")
{'type': 'URL', 'lang': '', 'value': 'https://dummy.mp3'}

ResponseBuilder¶

class cek.core.ResponseBuilder(default_language='ja')¶

Helper class to build responses for CEK

Parameters:	default_language (str) – Set default language for all messages. Can be `ja`, `ko` or `en`.
Raises:	ValueError – if unsupported language is specified.

Usage:

All the examples below assume the following helper is defined in advance.

>>> from cek import SpeechBuilder, ResponseBuilder
>>> from pprint import pprint
>>> speech_builder = SpeechBuilder(default_language="ja")
>>> response_builder = ResponseBuilder(default_language="ja")

Building a SimpleSpeech response:

>>> resp = response_builder.simple_speech_text("こんにちは")
>>> pprint(resp)
{'response': {'card': {},
              'directives': [],
              'outputSpeech': {'type': 'SimpleSpeech',
                               'values': {'lang': 'ja',
                                          'type': 'PlainText',
                                          'value': 'こんにちは'}},
              'shouldEndSession': False},
 'sessionAttributes': {},
 'version': '1.0'}

add_reprompt(response, speech)¶

Add a repromt to your response. It is recommended to use a SimpleSpeech to keep the reprompt short

Parameters:	response (dict-like) – Response Dictionary to which the reprompt should be added speech (dict) – Speech can be a Dictionary of Simple Speech, SpeechList or SpeechSet
Returns:	Response with added Speech reprompt
Return type:	dict-like

simple_speech(speech_value, end_session=False)¶

Build a SimpleSpeech response

Parameters:	speech_value (dict) – Value which can consist of plain_text SpeechInfo or url SpeechInfo end_session (bool) – Whether Clova should continue to listen or end the session
Returns:	Response that wraps a Dictionary in the format of a response for a SimpleSpeech
Return type:	cek.core.Response

Usage:

>>> text = speech_builder.plain_text("こんにちは")
>>> resp = response_builder.simple_speech(text)
>>> pprint(resp)
{'response': {'card': {},
              'directives': [],
              'outputSpeech': {'type': 'SimpleSpeech',
                               'values': {'lang': 'ja',
                                          'type': 'PlainText',
                                          'value': 'こんにちは'}},
              'shouldEndSession': False},
 'sessionAttributes': {},
 'version': '1.0'}

simple_speech_text(message, language=None, end_session=False)¶

Build SimpleSpeech response with plain_text value

Parameters:	message (str) – String Request which clova should speak out language (str) – Language code of the message end_session (bool) – Whether Clova should continue to listen or end the session
Returns:	Response that wraps a Dictionary in the format of a response for a SimpleSpeech
Return type:	cek.core.Response
Raises:	ValueError – if unsupported language is specified.

Usage:

>>> resp = response_builder.simple_speech_text("こんにちは")
>>> pprint(resp)
{'response': {'card': {},
              'directives': [],
              'outputSpeech': {'type': 'SimpleSpeech',
                               'values': {'lang': 'ja',
                                          'type': 'PlainText',
                                          'value': 'こんにちは'}},
              'shouldEndSession': False},
 'sessionAttributes': {},
 'version': '1.0'}

speech_list(speech_values, end_session=False)¶

Build a SpeechList response

Parameters:	speech_values (list) – List which can consist of plain_text SpeechInfo or url SpeechInfo end_session (bool) – Whether Clova should continue to listen or end the session
Returns:	Response that wraps a Dictionary in the format of a response for a SpeechList
Return type:	cek.core.Response

Usage:

>>> text = speech_builder.plain_text("こんにちは")
>>> url = speech_builder.url("https://dummy.mp3")
>>> resp = response_builder.speech_list([text, url])
>>> pprint(resp)
{'response': {'card': {},
              'directives': [],
              'outputSpeech': {'type': 'SpeechList',
                               'values': [{'lang': 'ja',
                                           'type': 'PlainText',
                                           'value': 'こんにちは'},
                                          {'lang': '',
                                           'type': 'URL',
                                           'value': 'https://dummy.mp3'}]},
              'shouldEndSession': False},
 'sessionAttributes': {},
 'version': '1.0'}

speech_set(brief, verbose, end_session=False)¶

Build a SpeechSet response

Parameters:	brief (dict) – A Dictionary of a plain_text SpeechInfo or url SpeechInfo verbose (dict) – A Dictionary of a SpeechList or SimpleSpeech end_session (bool) – Whether Clova should continue to listen or end the session
Returns:	Response that wraps a Dictionary in the format of a response for a SpeechSet
Return type:	cek.core.Response

speech_url(message, url, language=None, end_session=False)¶

Build a SpeechList response with a message and an URL

Parameters:	message (str) – String Message which clova should speak out url (str) – String URL of the audio file which should be played by clova language (str) – Language code of the message end_session (bool) – Whether Clova should continue to listen or end the session
Returns:	Response that wraps a Dictionary in the format of a response for a SpeechList
Return type:	cek.core.Response
Raises:	ValueError – if unsupported language is specified.

Usage:

>>> resp = response_builder.speech_url("音楽を再生します", "https://dummy.mp3")
>>> pprint(resp)
{'response': {'card': {},
              'directives': [],
              'outputSpeech': {'type': 'SpeechList',
                               'values': [{'lang': 'ja',
                                           'type': 'PlainText',
                                           'value': '音楽を再生します'},
                                          {'lang': '',
                                           'type': 'URL',
                                           'value': 'https://dummy.mp3'}]},
              'shouldEndSession': False},
 'sessionAttributes': {},
 'version': '1.0'}

RequestHandler¶

class cek.core.RequestHandler(application_id, debug_mode=False)¶

Helper class to handle requests from CEK.

Parameters:	application_id (str) – Application ID that was used to register this Extension f.e. debug_mode (bool) – When set to True, application_id and request verification are ignored.

Usage:

All the examples below assume the following helpers are defined in advance.

>>> from cek import RequestHandler, ResponseBuilder
>>> clova_handler = RequestHandler(application_id="", debug_mode=True)
>>> builder = ResponseBuilder(default_language="ja", debug_mode=False)

Defining handlers can be done by decorators:

>>> @clova_handler.launch
... def launch_request_handler(clova_request):
...     return builder.simple_speech_text("こんにちは世界。スキルを起動します")

>>> @clova_handler.default
... def default_handler(clova_request):
...     return builder.simple_speech_text("もう一度お願いします")

If you have defined request handlers, then setup a web API endpoint as follows:

>>> rom flask import Flask, request, jsonify
>>> app = Flask(__name__)
>>> @app.route('/app', methods=['POST'])
... def my_service():
...     resp = clova_handler.route_request(request.data, request.headers)
...     resp = jsonify(resp)
...     resp.headers['Content-Type'] = 'application/json;charset-UTF-8'
...     return resp

default(func)¶

Default handler

Parameters:	func – Function

Usage:

>>> @clova_handler.default
... def default_handler(clova_request):
...     return builder.simple_speech_text("もう一度お願いします")

end(func)¶

End handler called on SessionEndedRequest.

Parameters:	func – Function

Usage:

>>> @clova_handler.end
... def end_handler(clova_request):
...     # Session ended, this handler can be used to clean up
...     return

event(func)¶

Event handler called on EventRequest.

Parameters:	func – Function

Usage:

>>> @clova_handler.event
... def event_request_handler(clova_request):
...

intent(intent)¶

Intent handler called on IntentRequest.

Parameters:	intent (str) – intent name

Usage:

>>> @clova_handler.intent("Clova.YesIntent")
... def intent_handler(clova_request):
...     return builder.simple_speech_text("はい、わかりました。")

launch(func)¶

Launch handler called on LaunchRequest.

Parameters:	func – Function

Usage:

>>> @clova_handler.launch
... def launch_request_handler(clova_request):
...     return builder.simple_speech_text("こんにちは世界。スキルを起動します")

route_request(request_body, request_header_dict)¶

Route request from CEK.

Parameters:	request_body (bytes) – Binary Request body from CEK request_header_dict (dict) – Request Header as dictionary
Returns:	Returns body for CEK response
Return type:	cek.core.Response
Raises:	cryptography.exceptions.InvalidSignature – (non-debug mode only) if request verification failed. cek.ApplicationIdMismatch – (non-debug mode only) if application id is incorrect.

Usage:

>>> from flask import Flask, request, Response
>>> app = Flask(__name__)
>>> @app.route('/app', methods=['POST'])
... def my_service():
...     resp = clova_handler.route_request(request.data, request.headers)
...     resp = jsonify(resp)
...     resp.headers['Content-Type'] = 'application/json;charset-UTF-8'
...     return resp