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)

Type represents a request from CEK

Parameters:

request_dict (dict) – Dictioanry represents a request from CEK

Variables:
  • request_type (str) – can be LaunchRequest, IntentRequest, etc.
  • intent_name (str) – name of intent if exist, otherwise None.
  • is_intent (str) – IntentRequest or not.
  • user_id (str) – user id.
  • application_id (str) – application id.
  • access_token (str) – access token.
  • session_id (str) – session id.
  • session_attributes (dict) – session attributes.
  • slots_dict (dict) – slots as dictionary
slot_value(slot_name)

Returns slot value or None if missing.

Parameters:slot_name (str) – slot name
Returns:slot value if exists, None otherwise.
Return type:str
Raises:TypeError: if the request is not an IntentRequest
Usage:
>>> req.slot_value('Light')
'電気'
verify_application_id(application_id)

Verify application id

Raises:RuntimeError – if application id is incorrect.

Response

class cek.core.Response

Type represents a response from CEK

Variables:
  • session_attributes (dict) – Session attributes in a dictionary format
  • 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 Message 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
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:
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